A Logger object is used to log messages for a specific system or application component. More...

#include <src/main/decaf/util/logging/Logger.h>

Public Member Functions
virtual	~Logger ()
const std::string &	getName () const
	Gets the name of this Logger.
Logger *	getParent () const
	Gets the parent of this Logger which will be the nearest existing Logger in this Loggers namespace.
void	setParent (Logger *parent)
	Set the parent for this Logger.
void	addHandler (Handler *handler)
	Add a log Handler to receive logging messages.
void	removeHandler (Handler *handler)
	Removes the specified Handler from this logger, ownership of the Handler pointer is returned to the caller.
const std::list< Handler * > &	getHandlers () const
	Gets a vector containing all the handlers that this class has been assigned to use.
void	setFilter (Filter *filter)
	Set a filter to control output on this Logger.
const Filter *	getFilter () const
	Gets the Filter object that this class is using.
Level	getLevel () const
	Get the log Level that has been specified for this Logger.
void	setLevel (const Level &level)
	Set the log level specifying which message levels will be logged by this logger.
bool	getUseParentHandlers () const
	Discover whether or not this logger is sending its output to its parent logger.
void	setUseParentHandlers (bool value)
	Specify whether or not this logger should send its output to it's parent Logger.
virtual void	entering (const std::string &blockName, const std::string &file, const int line)
	Logs an Block Enter message.
virtual void	exiting (const std::string &blockName, const std::string &file, const int line)
	Logs an Block Exit message.
virtual void	severe (const std::string &file, const int line, const std::string functionName, const std::string &message)
	Log a SEVERE Level Log.
virtual void	warning (const std::string &file, const int line, const std::string functionName, const std::string &message)
	Log a WARN Level Log.
virtual void	info (const std::string &file, const int line, const std::string functionName, const std::string &message)
	Log a INFO Level Log.
virtual void	debug (const std::string &file, const int line, const std::string functionName, const std::string &message)
	Log a DEBUG Level Log.
virtual void	config (const std::string &file, const int line, const std::string functionName, const std::string &message)
	Log a CONFIG Level Log.
virtual void	fine (const std::string &file, const int line, const std::string functionName, const std::string &message)
	Log a FINE Level Log.
virtual void	finer (const std::string &file, const int line, const std::string functionName, const std::string &message)
	Log a FINER Level Log.
virtual void	finest (const std::string &file, const int line, const std::string functionName, const std::string &message)
	Log a FINEST Level Log.
virtual void	throwing (const std::string &file, const int line, const std::string functionName, const decaf::lang::Throwable &thrown)
	Log throwing an exception.
virtual bool	isLoggable (const Level &level) const
	Check if a message of the given level would actually be logged by this logger.
virtual void	log (LogRecord &record)
	Log a LogRecord.
virtual void	log (const Level &level, const std::string &message)
	Log a message, with no arguments.
virtual void	log (const Level &levels, const std::string &file, const int line, const std::string &message,...)
	Log a message, with the list of params that is formatted into the message string.
virtual void	log (const Level &level, const std::string &file, const int line, const std::string &message, lang::Exception &ex)
	Log a message, with associated Throwable information.
Static Public Member Functions
static Logger *	getAnonymousLogger ()
	Creates an anonymous logger.
static Logger *	getLogger (const std::string &name)
	Find or create a logger for a named subsystem.
Protected Member Functions
	Logger (const std::string &name)
	Creates a new instance of the Logger with the given name.

Detailed Description

A Logger object is used to log messages for a specific system or application component.

Loggers are normally named, using a hierarchical dot-separated namespace. Logger names can be arbitrary strings, but they should normally be based on the namespace or class name of the logged component, such as decaf.net or org.apache.decaf. In addition it is possible to create "anonymous" Loggers that are not stored in the Logger namespace.

Logger objects may be obtained by calls on one of the getLogger factory methods. These will either create a new Logger or return a suitable existing Logger.

Logging messages will be forwarded to registered Handler objects, which can forward the messages to a variety of destinations, including consoles, files, OS logs, etc.

Each Logger keeps track of a "parent" Logger, which is its nearest existing ancestor in the Logger namespace.

Each Logger has a "Level" associated with it. This reflects a minimum Level that this logger cares about. If a Logger's level is set to Level::INHERIT, then its effective level is inherited from its parent, which may in turn obtain it recursively from its parent, and so on up the tree.

The log level can be configured based on the properties from the logging configuration file, as described in the description of the LogManager class. However it may also be dynamically changed by calls on the Logger.setLevel method. If a logger's level is changed the change may also affect child loggers, since any child logger that has 'inherit' as its level will inherit its effective level from its parent.

On each logging call the Logger initially performs a cheap check of the request level (e.g. SEVERE or FINE) against the effective log level of the logger. If the request level is lower than the log level, the logging call returns immediately.

After passing this initial (cheap) test, the Logger will allocate a LogRecord to describe the logging message. It will then call a Filter (if present) to do a more detailed check on whether the record should be published. If that passes it will then publish the LogRecord to its output Handlers. By default, loggers also publish to their parent's Handlers, recursively up the tree.

Formatting is the responsibility of the output Handler, which will typically call a Formatter.

Note that formatting need not occur synchronously. It may be delayed until a LogRecord is actually written to an external sink.

All methods on Logger are thread safe.

Since:: 1.0

Constructor & Destructor Documentation

decaf::util::logging::Logger::Logger ( const std::string & name ) [protected]

Creates a new instance of the Logger with the given name.

The logger will be initially configured with a null Level and with useParentHandlers true.

Parameters:

name	A name for the logger. This should be a dot-separated name and should normally be based on the package name or class name of the subsystem, such as decaf.net or org.apache.decaf. It may be empty for anonymous Loggers.

virtual decaf::util::logging::Logger::~Logger ( ) [virtual]

Member Function Documentation

void decaf::util::logging::Logger::addHandler ( Handler * handler )

Add a log Handler to receive logging messages.

By default, Loggers also send their output to their parent logger. Typically the root Logger is configured with a set of Handlers that essentially act as default handlers for all loggers.

The ownership of the given Handler is passed to the Logger and the Handler will be deleted when this Logger is destroyed unless the caller first calls removeHandler with the same pointer value as was originally given.

Parameters:

handler A Logging Handler

Exceptions:

NullPointerException if the Handler given is NULL.

virtual void decaf::util::logging::Logger::config	(	const std::string &	file,
		const int	line,
		const std::string	functionName,
		const std::string &	message
	)		`[virtual]`

Log a CONFIG Level Log.

If the logger is currently enabled for the CONFIG message level then the given message is forwarded to all the registered output Handler objects.

Parameters:

file	The file name where the log was generated.
line	The line number where the log was generated.
functionName	The name of the function that logged this.
message	The message to log at this Level.

virtual void decaf::util::logging::Logger::debug	(	const std::string &	file,
		const int	line,
		const std::string	functionName,
		const std::string &	message
	)		`[virtual]`

Log a DEBUG Level Log.

If the logger is currently enabled for the DEBUG message level then the given message is forwarded to all the registered output Handler objects.

Parameters:

file	The file name where the log was generated.
line	The line number where the log was generated.
functionName	The name of the function that logged this.
message	The message to log at this Level.

virtual void decaf::util::logging::Logger::entering	(	const std::string &	blockName,
		const std::string &	file,
		const int	line
	)		`[virtual]`

Logs an Block Enter message.

This is a convenience method that is used to tag a block enter, a log record with the given information is logged at the Level::FINER log level.

Parameters:

blockName	The source block name, (usually ClassName::MethodName, or MethodName).
file	The source file name where this method was called from.
line	The source line number where this method was called from.

virtual void decaf::util::logging::Logger::exiting	(	const std::string &	blockName,
		const std::string &	file,
		const int	line
	)		`[virtual]`

Logs an Block Exit message.

This is a convenience method that is used to tag a block enter, a log record with the given information is logged at the Level::FINER log level.

Parameters:

blockName	The source block name, (usually ClassName::MethodName, or MethodName).
file	The source file name where this method was called from.
line	The source line number where this method was called from.

virtual void decaf::util::logging::Logger::fine	(	const std::string &	file,
		const int	line,
		const std::string	functionName,
		const std::string &	message
	)		`[virtual]`

Log a FINE Level Log.

If the logger is currently enabled for the FINE message level then the given message is forwarded to all the registered output Handler objects.

Parameters:

file	The file name where the log was generated.
line	The line number where the log was generated.
functionName	The name of the function that logged this.
message	The message to log at this Level.

virtual void decaf::util::logging::Logger::finer	(	const std::string &	file,
		const int	line,
		const std::string	functionName,
		const std::string &	message
	)		`[virtual]`

Log a FINER Level Log.

If the logger is currently enabled for the FINER message level then the given message is forwarded to all the registered output Handler objects.

Parameters:

file	The file name where the log was generated.
line	The line number where the log was generated.
functionName	The name of the function that logged this.
message	The message to log at this Level.

virtual void decaf::util::logging::Logger::finest	(	const std::string &	file,
		const int	line,
		const std::string	functionName,
		const std::string &	message
	)		`[virtual]`

Log a FINEST Level Log.

If the logger is currently enabled for the FINEST message level then the given message is forwarded to all the registered output Handler objects.

Parameters:

file	The file name where the log was generated.
line	The line number where the log was generated.
functionName	The name of the function that logged this.
message	The message to log at this Level.

static Logger* decaf::util::logging::Logger::getAnonymousLogger ( ) [static]

Creates an anonymous logger.

The newly created Logger is not registered in the LogManager namespace. There will be no access checks on updates to the logger. Even although the new logger is anonymous, it is configured to have the root logger ("") as its parent. This means that by default it inherits its effective level and handlers from the root logger.

The caller is responsible for destroying the returned logger.

Returns:: Newly created anonymous logger

const Filter* decaf::util::logging::Logger::getFilter ( ) const [inline]

Gets the Filter object that this class is using.

Returns:: the Filter in use, (can be NULL).

const std::list<Handler*>& decaf::util::logging::Logger::getHandlers ( ) const

Gets a vector containing all the handlers that this class has been assigned to use.

Returns:: a list of handlers that are used by this logger

Level decaf::util::logging::Logger::getLevel ( ) const [inline]

Get the log Level that has been specified for this Logger.

The result may be the INHERIT level, which means that this logger's effective level will be inherited from its parent.

Returns:: the level that is currently set

static Logger* decaf::util::logging::Logger::getLogger ( const std::string & name ) [static]

Find or create a logger for a named subsystem.

If a logger has already been created with the given name it is returned. Otherwise a new logger is created.

If a new logger is created its log level will be configured based on the LogManager and it will configured to also send logging output to its parent loggers Handlers. It will be registered in the LogManager global namespace.

Parameters:

name	- A name for the logger. This should be a dot-separated name and should normally be based on the package name or class name of the subsystem, such as cms or activemq.core.ActiveMQConnection

Returns:: a suitable logger.

const std::string& decaf::util::logging::Logger::getName ( ) const [inline]

Gets the name of this Logger.

Returns:: logger name

Logger* decaf::util::logging::Logger::getParent ( ) const [inline]

Gets the parent of this Logger which will be the nearest existing Logger in this Loggers namespace.

If this is the Root Logger than this method returns NULL.

Returns:: Pointer to this Loggers nearest parent Logger.

bool decaf::util::logging::Logger::getUseParentHandlers ( ) const [inline]

Discover whether or not this logger is sending its output to its parent logger.

Returns:: true if using Parent Handlers

virtual void decaf::util::logging::Logger::info	(	const std::string &	file,
		const int	line,
		const std::string	functionName,
		const std::string &	message
	)		`[virtual]`

Log a INFO Level Log.

If the logger is currently enabled for the INFO message level then the given message is forwarded to all the registered output Handler objects.

Parameters:

file	The file name where the log was generated.
line	The line number where the log was generated.
functionName	The name of the function that logged this.
message	The message to log at this Level.

virtual bool decaf::util::logging::Logger::isLoggable ( const Level & level ) const [virtual]

Check if a message of the given level would actually be logged by this logger.

This check is based on the Loggers effective level, which may be inherited from its parent.

Parameters:

level - a message logging level

Returns:: true if the given message level is currently being logged.

virtual void decaf::util::logging::Logger::log	(	const Level &	levels,
		const std::string &	file,
		const int	line,
		const std::string &	message,
			...
	)		`[virtual]`

Log a message, with the list of params that is formatted into the message string.

If the logger is currently enabled for the given message level then the given message is forwarded to all the registered output Handler objects

Parameters:

level	the Level to log at
file	the message to log
line	the line in the file
...	variable length argument to format the message string.

virtual void decaf::util::logging::Logger::log ( LogRecord & record ) [virtual]

Log a LogRecord.

All the other logging methods in this class call through this method to actually perform any logging. Subclasses can override this single method to capture all log activity.

Parameters:

record - the LogRecord to be published

virtual void decaf::util::logging::Logger::log	(	const Level &	level,
		const std::string &	message
	)		`[virtual]`

Log a message, with no arguments.

If the logger is currently enabled for the given message level then the given message is forwarded to all the registered output Handler objects

Parameters:

level	the Level to log at
message	the message to log

virtual void decaf::util::logging::Logger::log	(	const Level &	level,
		const std::string &	file,
		const int	line,
		const std::string &	message,
		lang::Exception &	ex
	)		`[virtual]`

Log a message, with associated Throwable information.

If the logger is currently enabled for the given message level then the given arguments are stored in a LogRecord which is forwarded to all registered output handlers. Note that the thrown argument is stored in the LogRecord thrown property, rather than the LogRecord parameters property. Thus is it processed specially by output Formatters and is not treated as a formatting parameter to the LogRecord message property.

Parameters:

level	the Level to log at.
file	File that the message was logged in.
line	the line number where the message was logged at.
message	the message to log.
ex	the Exception to log

void decaf::util::logging::Logger::removeHandler ( Handler * handler )

Removes the specified Handler from this logger, ownership of the Handler pointer is returned to the caller.

Returns silently if the given Handler is not found.

Parameters:

handler The Handler to remove

void decaf::util::logging::Logger::setFilter ( Filter * filter )

Set a filter to control output on this Logger.

After passing the initial "level" check, the Logger will call this Filter to check if a log record should really be published.

The caller releases ownership of this filter to this logger

Parameters:

filter The Filter to use, (can be NULL).

void decaf::util::logging::Logger::setLevel ( const Level & level ) [inline]

Set the log level specifying which message levels will be logged by this logger.

Message levels lower than this value will be discarded. The level value Level::OFF can be used to turn off logging.

If the new level is the INHERIT Level, it means that this node should inherit its level from its nearest ancestor with a specific (non-INHERIT) level value.

Parameters:

level The new Level value to use when logging.

void decaf::util::logging::Logger::setParent ( Logger * parent ) [inline]

Set the parent for this Logger.

This method is used by the LogManager to update a Logger when the namespace changes.

It should not be called from application code.

void decaf::util::logging::Logger::setUseParentHandlers ( bool value ) [inline]

Specify whether or not this logger should send its output to it's parent Logger.

This means that any LogRecords will also be written to the parent's Handlers, and potentially to its parent, recursively up the namespace.

Parameters:

value True is output is to be written to the parent

virtual void decaf::util::logging::Logger::severe	(	const std::string &	file,
		const int	line,
		const std::string	functionName,
		const std::string &	message
	)		`[virtual]`

Log a SEVERE Level Log.

If the logger is currently enabled for the SEVERE message level then the given message is forwarded to all the registered output Handler objects.

Parameters:

file	The file name where the log was generated.
line	The line number where the log was generated.
functionName	The name of the function that logged this.
message	The message to log at this Level.

virtual void decaf::util::logging::Logger::throwing	(	const std::string &	file,
		const int	line,
		const std::string	functionName,
		const decaf::lang::Throwable &	thrown
	)		`[virtual]`

Log throwing an exception.

This is a convenience method to log that a method is terminating by throwing an exception. The logging is done using the FINER level.

If the logger is currently enabled for the given message level then the given arguments are stored in a LogRecord which is forwarded to all registered output handlers. The LogRecord's message is set to "THROW".

Parameters:

file	The file name where the log was generated.
line	The line number where the log was generated.
functionName	The name of the function that logged this.
thrown	The Throwable that will be thrown, will be cloned.

virtual void decaf::util::logging::Logger::warning	(	const std::string &	file,
		const int	line,
		const std::string	functionName,
		const std::string &	message
	)		`[virtual]`

Log a WARN Level Log.

If the logger is currently enabled for the WARN message level then the given message is forwarded to all the registered output Handler objects.

Parameters:

file	The file name where the log was generated.
line	The line number where the log was generated.
functionName	The name of the function that logged this.
message	The message to log at this Level.

The documentation for this class was generated from the following file:

src/main/decaf/util/logging/Logger.h

decaf::util::logging::Logger Class Reference

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation