[ADD] unit tests and documentation for our logger

src/common/WLogEntry.cpp

@@ -23,24 +23,23 @@
 //---------------------------------------------------------------------------
 
 #include <string>
+
 #include <boost/algorithm/string.hpp>
 
 #include "WLogEntry.h"
 
-WLogEntry:: WLogEntry( std::string logTime, std::string message, LogLevel level, std::string source ) :
-    m_time( logTime ),
-    m_message( message ),
-    m_level( level ),
-    m_source( source )
+WLogEntry:: WLogEntry( std::string logTime, std::string message, LogLevel level, std::string source )
+    : m_time( logTime ),
+      m_message( message ),
+      m_level( level ),
+      m_source( source )
 {
 }
 
-
 WLogEntry::~WLogEntry()
 {
 }
 
-
 std::string WLogEntry::getLogString( std::string format )
 {
     std::string s = format;
@@ -69,11 +68,9 @@ std::string WLogEntry::getLogString( std::string format )
 
     boost::ireplace_first( s, "%s", m_source );
 
-
     return s;
 }
 
-
 LogLevel WLogEntry::getLogLevel()
 {
     return m_level;

src/common/WLogEntry.h

@@ -27,6 +27,9 @@
 
 #include <string>
 
+/**
+ * Various log levels, to distinguish output on its level.
+ */
 typedef enum
 {
     LL_DEBUG = 0,
@@ -37,56 +40,50 @@ typedef enum
 LogLevel;
 
 /**
- * TODO(schurade): Document this!
+ * Represents a simple log message with some attributes.
  */
 class WLogEntry
 {
 public:
     /**
-     *
+     * Construtcs a log message entry
      */
-    WLogEntry( std::string logTime, std::string message, LogLevel level, std::string source );
+    WLogEntry( std::string logTime, std::string message, LogLevel level, std::string source = "" );
 
     /**
-     *
+     * Destroys a log message entry.
      */
     virtual ~WLogEntry();
 
     /**
-     *
+     * \return String of this log entry.
      */
     std::string getLogString( std::string format = "[%t] *%l* %m \n" );
 
     /**
-     *
+     * \return log level of this entry.
      */
     LogLevel getLogLevel();
 
 protected:
-
 private:
     /**
-     * Private standard constructor to prevent empty log entries
-     */
-    WLogEntry();
-
-    /**
-     *
+     * The time the log message was received
      */
     std::string m_time;
 
     /**
-     *
+     * The actual message
      */
     std::string m_message;
 
     /**
-     *
+     * Log level
      */
     LogLevel m_level;
 
     /**
-     *
+     * Source (e.g. module name) where this log message comes from.
      */
     std::string m_source;
 };

src/common/WLogger.cpp

@@ -25,7 +25,7 @@
 #include <iostream>
 #include <string>
 
-#include "boost/date_time/posix_time/posix_time.hpp"
+#include <boost/date_time/posix_time/posix_time.hpp>
 #include <boost/filesystem/fstream.hpp>
 
 #include "WLogger.h"
@@ -62,40 +62,35 @@ WLogger* WLogger::getLogger()
     return logger;
 }
 
-
 void WLogger::setLogLevel( LogLevel level )
 {
     m_LogLevel = level;
 }
 
-
 void WLogger::setSTDOUTLevel( LogLevel level )
 {
     m_STDOUTLevel = level;
 }
 
-
 void WLogger::setSTDERRLevel( LogLevel level )
 {
     m_STDERRLevel = level;
 }
 
-
 void WLogger::setLogFileLevel( LogLevel level )
 {
     m_LogFileLevel = level;
 }
 
-
 void WLogger::setLogFileName( std::string fileName )
 {
-    /**
-     * TODO (schurade) check if it's a valid filename
-     */
+    boost::filesystem::path p( fileName );
+
+    // TODO(schurade): check if this is a _VALID_ path (existence is not needed)
+
     m_LogFileName = fileName;
 }
 
-
 void WLogger::addLogMessage( std::string message, std::string source, LogLevel level )
 {
     if ( m_LogLevel > level || m_FinishRequested )
@@ -111,7 +106,6 @@ void WLogger::addLogMessage( std::string message, std::string source, LogLevel l
     m_LogQueue.push( entry );
 }
 
-
 void WLogger::processQueue()
 {
     boost::mutex::scoped_lock l( m_QueueMutex );
@@ -135,6 +129,8 @@ void WLogger::processQueue()
 
         if ( entry.getLogLevel() >= m_LogFileLevel )
         {
+            // TODO(schurade): first open file, then write to file, then close the file
+            // for atomic file usage.
             boost::filesystem::path p( "walnut.log" );
             boost::filesystem::ofstream ofs( p, boost::filesystem::ofstream::app );
             ofs << entry.getLogString();
@@ -142,7 +138,6 @@ void WLogger::processQueue()
     }
 }
 
-
 void WLogger::threadMain()
 {
     // Since the modules run in a separate thread: such loops are possible

src/common/WLogger.h

@@ -38,7 +38,7 @@
 #include "WLogEntry.h"
 
 /**
- * TODO(schurade): Document this!
+ * Does actual logging of WLogEntries down to stdout or something similar.
  */
 class WLogger: public WThreadedRunner
 {
@@ -54,50 +54,50 @@ public:
     virtual ~WLogger();
 
     /**
-     * Returns pointer to the currently running logger.
+     * Returns pointer to the currently running logger instance.
      *
      * \return pointer to logger instance.
      */
     static WLogger* getLogger();
 
     /**
-     *
+     * Sets the global log level
      */
     void setLogLevel( LogLevel level );
 
     /**
-     *
+     * Sets the log level for stdout.
      */
     void setSTDOUTLevel( LogLevel level );
 
     /**
-     *
+     * Sets the log level for stderr.
      */
     void setSTDERRLevel( LogLevel level );
 
     /**
-     *
+     * Sets the log level for the given log file.
      */
     void setLogFileLevel( LogLevel level );
 
-
     /**
-     *
+     * Specifies the path for logging to this file and checks if the path
+     * exists by an assertion.
      */
     void setLogFileName( std::string fileName );
 
     /**
-     *
+     * Appends a log message to the logging queue.
      */
     void addLogMessage( std::string message, std::string source = "", LogLevel level = LL_DEBUG );
 
     /**
-     *
+     * Locks this logging instance for threadsafeness and prints the
+     * items of the queue.
      */
     void processQueue();
 
     /**
-     * \par Description
      * Entry point after loading the module. Runs in separate thread.
      */
     virtual void threadMain();
@@ -105,52 +105,49 @@ public:
 protected:
 
 private:
-
     /**
      * We do not want a copy constructor, so we define it private.
      */
-    WLogger( const WLogger& )
-    {
-    };
+    WLogger( const WLogger& );
 
     /**
-     *
+     * The actual level of logging so messages with a lower level will be
+     * discarded.
      */
     LogLevel m_LogLevel;
 
     /**
-     *
+     * LogLevel for stdout
      */
     LogLevel m_STDOUTLevel;
 
     /**
-     *
+     * LogLevel for stderr
      */
     LogLevel m_STDERRLevel;
 
     /**
-     *
+     * LogLevel for the given log file
      */
     LogLevel m_LogFileLevel;
 
-
     /**
-     *
+     * Filename of the log file
      */
     std::string m_LogFileName;
 
     /**
-     *
+     * Storage for all WLogEntries that were given to our logging instance
      */
     std::vector< WLogEntry > m_SessionLog;
 
     /**
-     *
+     * Queue for storing pending WLogEntries.
      */
     std::queue< WLogEntry > m_LogQueue;
 
     /**
-     *
+     * Mutex for doing locking due to thread-safety.
      */
     boost::mutex m_QueueMutex;
 };

src/common/test/WLogEntry_test.h

+//---------------------------------------------------------------------------
+//
+// Project: OpenWalnut ( http://www.openwalnut.org )
+//
+// Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
+// For more information see http://www.openwalnut.org/copying
+//
+// This file is part of OpenWalnut.
+//
+// OpenWalnut is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// OpenWalnut is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
+//
+//---------------------------------------------------------------------------
+
+#ifndef WLOGENTRY_TEST_H
+#define WLOGENTRY_TEST_H
+
+#include <cxxtest/TestSuite.h>
+
+#include "../WLogEntry.h"
+
+/**
+ * Unit tests our log messages.
+ */
+class WLogEntryTest : public CxxTest::TestSuite
+{
+public:
+    /**
+     * If given a format string of the form: "%t :: %l :: %m" then 
+     * the log message will replace %t with time of logging and
+     * %l with level of logging and %m with the message itself.
+     */
+    void testFormatStringReplacement( void )
+    {
+        std::string dummyTime = "2009-Oct-02 14:46:50";
+        WLogEntry entry( dummyTime, "Dummy message", LL_INFO, "WLogEntryTest" );
+        // build our customized format string
+        std::string format = "%m :: %t %t %l";
+        std::string expected = "Dummy message :: 2009-Oct-02 14:46:50 %t INFO   ";
+        TS_ASSERT_EQUALS( entry.getLogString( format ), expected );
+    }
+
+    /**
+     * If the default format string is used then the time, level and message
+     * should be printed in a special format.
+     */
+    void testDefaultFormatString( void )
+    {
+        WLogEntry entry( "now", "msg", LL_WARNING );
+        std::string expected( "[now] *WARNING* msg \n" );
+        TS_ASSERT_EQUALS( expected, entry.getLogString() );
+    }
+
+    /**
+     * If an empty format string is given, then an empty string should be
+     * returned.
+     */
+    void testEmptyStringAsFormatString( void )
+    {
+        WLogEntry entry( "now", "msg", LL_INFO, "WLogEntryTest" );
+        TS_ASSERT_EQUALS( entry.getLogString( "" ), "" );
+    }
+
+    /**
+     * If ever an unknown log level was used to construct the entry then no
+     * replacement should be done.
+     */
+    void testUnkownLogLevel( void )
+    {
+        WLogEntry entry( "now", "msg", static_cast< LogLevel >( 4711 ), "WLogEntryTest" );
+        std::string expected( "[now] *%l* msg \n" );
+        TS_ASSERT_EQUALS( entry.getLogString(), expected );
+    }
+};
+
+#endif  // WLOGENTRY_TEST_H

src/common/test/WLogger_test.h

+//---------------------------------------------------------------------------
+//
+// Project: OpenWalnut ( http://www.openwalnut.org )
+//
+// Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
+// For more information see http://www.openwalnut.org/copying
+//
+// This file is part of OpenWalnut.
+//
+// OpenWalnut is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// OpenWalnut is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
+//
+//---------------------------------------------------------------------------
+
+#ifndef WLOGGER_TEST_H
+#define WLOGGER_TEST_H
+
+#include <cxxtest/TestSuite.h>
+
+#include "../WLogger.h"
+
+/**
+ * Unit tests our WLogger facility.
+ */
+class WLoggerTest : public CxxTest::TestSuite
+{
+public:
+    /**
+     * If the logger is set to do logging only on errors and warnings then
+     * no debug messages or infos should be logged.
+     */
+    void testSomething( void )
+    {
+    }
+};
+
+#endif  // WLOGGER_TEST_H