log.h

日志类封装日志类封装日志类封装日志类封装日志类封装日志类封装

/*============================================================================.
 | Copyright (C) 2006 Gareth Buxton                                           |
 |----------------------------------------------------------------------------|
 | LogPlusPlus 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 2.1 of the License, or (at your option) any later version.         |
 |                                                                            |
 | LogPlusPlus 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 this library; if not, write to the Free Software        |
 | Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA |
 '============================================================================*/
#ifndef LOG_H_
#define LOG_H_
 
#include <liblpp/Types.h>
#include <liblpp/LogStream.h>
#include <liblpp/LogLevel.h>
#include <liblpp/LogMask.h>

#include <string>
#include <iostream>
#include <memory>

//=============================================================================
LPP_NAMESPACE_BEGIN
//=============================================================================

class LogException
: public std::exception
{
private:
	std::string message;
	
public:
	LogException(const std::string& message) throw();
	~LogException()  throw();
	const char* what() const throw();
};

/**
 * The Log is not instantiated directly but a reference
 * to a Log object is obtained through a call to one of the
 * static getLog() methods. Each log has 6 builtin LogStreams
 * each of which recieve messages at a different LogLevel. In this
 * way different LogStreams can be turned on or off at will.
 * 
 * The five primary builtin LogStreams are:
 * <pre>
 * Log.debug
 * Log.info
 * Log.warn
 * Log.error
 * Log.fatal
 * </pre>
 * In addition to these five the Log object itself is
 * also an LogStream.
 * 
 * Usage: In order to use the log the client program
 * sends a message to one of the Log objects
 * LogStream objects. Eg.
 * <pre>
 * log("Final statistics follow:");
 * log.debug("Entering loop:");
 * log.warn("Value to delete does not exist.");
 * </pre>
 * In addition to treating the builtin LogStream objects as
 * methods they can also be used like traditional C++ streams
 * (which they are). Eg.
 * <pre>
 * log << "Vat = " << vatPercent << "%" << std;:endl;
 * log.debug << "value = " << value << std::endl;
 * log.error << "This should never happen at line " << __LINE__;
 * log.error << ", file " << __FILE__ << std::endl;
 * log.fatal << "Bad vibes, exiting..." << std::endl; exit(10);
 * </pre>
 * Both the above approaches can be mixed. Eg.
 * <pre>
 * log("Total annual income = ") << lowIncomeValue << std::endl; 
 * log.debug("variable dv = ") << dv << std::endl;
 * </pre>
 * On top of all this additional LogStream objects can be
 * added to the Log using the addLogStream() method. Eg.
 * <pre>
 * log.addLogStream("report");
 * </pre>
 * This can be subsequently accessed thus:
 * <pre>
 * log.to("report", "Temperature guage initialization.");
 * log.to("report") << "Temperature of core: " << coreTemp << std::endl;
 * </pre>
 * Different levels of reporting can be achieved by setting the LogMask
 * of the Log. Each LogStream operates at a specific LogLevel
 * and the LogLevel of each of the builtin ones is set such that
 * they may be enabled or disabled in a hirarchal manner.
 * For example if you wanted to receive only 'error' and
 * 'fatal' messages you could set the LogMask thus:
 * <pre>
 * log.setLogLevel(log.error.getLogLevel());
 * </pre>
 * This sets the LogMask of the Log to a value such that all
 * LogStream objects operating below the level of 'error'
 * will be turned off.
 * 
 * You may wish your Log to send its output to more than one place.
 * This can be achieved by adding std::ostream objects to the Log.
 * Eg.
 * <pre>
 * // Send the logging over a network.
 * std::ostream* os = socket->get_output();
 * log.addOStream(*os);
 * </pre>
 * This output may subsequently be removed with:
 * <pre>
 * log.delOStream(*os);
 * </pre>
 **/
class Log
: public LogStream
{
private:
	//std::auto_ptr<class LogImpl> impl;

protected:
	static bool useThreads;
	Log(const std::string& name, class LogWriter& writer, const LogLevel& level);

public:

	virtual ~Log();

	/*========================================================================.
	 | Builtin LogStreams                                                     |
	 '========================================================================*/
	 
	/**
	 * Builtin InputStream. 'debug' operates
	 * at a level below all other builtin
	 * input streams.
	 **/
	LogStream debug;

	/**
	 * Builtin InputStream. 'info' operates
	 * at a level above 'debug' and below all
	 * other builtin input streams.
	 **/
	LogStream info;

	/**
	 * Builtin InputStream. 'warn' operates
	 * at a level above 'info' and below all
	 * other builtin input streams.
	 **/
	LogStream warn;

	/**
	 * Builtin InputStream. 'error' operates
	 * at a level above 'warn' and below
	 * 'fatal'.
	 **/
	LogStream error;

	/**
	 * Builtin InputStream. 'fatal' operates
	 * at a level above all other builtin
	 * input streams.
	 **/
	LogStream fatal;
	
	/*========================================================================.
	 | Static Interface                                                       |
	 '========================================================================*/

	static const class LogForm* configuredLogForm(const LogForm* logForm = 0);
	static const class ThreadMill* configuredThreadMill(const ThreadMill* threadMill = 0);

	/**
	 * Close all LogStreams freeing all resources.
	 **/
	static void closedown();

	/**
	 * Turn on or off the use of threads by the logging system.
	 **/
	static void setUseThreads(bool useThreads = true);

	/**
	 * Either create or retrieve a previously
	 * created, unnamed, Log. If this method has
	 * been called previously, the same log will
	 * be returned, otherwise a new one is created.
	 * @param os An optional std::ostream to report to.
	 * If not specified then std::clog will be used.
	 **/
	static Log& getLog(std::ostream& os = std::clog);

	/**
	 * Either create or retrieve a previously
	 * created, named Log. If this method has
	 * been called previously with the same value in
	 * the parameter the same log will
	 * be returned, otherwise a new one is created.
	 * 
	 * @param name The name of the Log to create/return.
	 * @param os An optional std::ostream to report to.
	 * If not specified then std::clog will be used.
	 **/
	static Log& getLog(const char* name, std::ostream& os = std::clog);
	
	/**
	 * Either create or retrieve a previously
	 * created, named Log. If this method has
	 * been called previously with the same value in
	 * the parameter the same log will
	 * be returned, otherwise a new one is created.
	 * 
	 * @param name The name of the Log to create/return.
	 * @param os An optional std::ostream to report to.
	 * If not specified then std::clog will be used.
	 * 
	 **/
	static Log& getLog(const std::string& name, std::ostream& os = std::clog);
	
	/**
	 * Set the logging level at which all new logs will operate.
	 * 
	 * @param level This value is used internally to determine
	 * whether or not to publish messages to the log based on the
	 * current mask setting of the log.
	 **/
	static void setDefaultLogLevel(const LogLevel& level);
	
	/**
	 * Set the logging mask that which all new logs will apply
	 * to received messages.
	 * 
	 * @param mask This value is used internally to determine
	 * whether or not to publish messages to the log based on the
	 * the messages current logging level setting.
	 **/
	static void setDefaultLogMask(const LogMask& mask);

	// TODO: setInternalLogMask()
	// sets the log mask of the log's log.