Kea  2.3.6-git
isc::log::Formatter< Logger > Class Template Reference

The log message formatter. More...

#include <log_formatter.h>

Public Member Functions

 Formatter (const Severity &severity=NONE, boost::shared_ptr< std::string > message=boost::make_shared< std::string >(), Logger *logger=NULL)
 Constructor of "active" formatter. More...
 Formatter (const Formatter &other)
 Copy constructor. More...
 ~Formatter ()
 Destructor. More...
template<class Arg >
Formatterarg (const Arg &value)
 Replaces another placeholder. More...
Formatterarg (const std::string &arg)
 String version of arg. More...
void deactivate ()
 Turn off the output of this logger. More...
Formatteroperator= (const Formatter &other)
 Assignment operator. More...

Detailed Description

template<class Logger>
class isc::log::Formatter< Logger >

The log message formatter.

This class allows us to format logging messages conveniently. We call something like logger.warn(WARN_MSG).arg(15).arg(dnsMsg). This outputs some text with placeholders replaced by the arguments, if the logging verbosity is at WARN level or more.

To make this work, we use the Formatter. The warn (or whatever logging function) returns a Formatter object. That one holds the string to be output with the placeholders. It also remembers if there should be any output at all (eg. if the logging is enabled for this level). When there's no .arg call on the object, it is destroyed right away and we use the destructor to output the text (but only in case we should output anything).

If there's an .arg call, we return reference to the same object, so another .arg can be called on it. After the last .arg call is done, the object is destroyed and, again, we can produce the output.

Of course, if the logging is turned off, we don't bother with any replacing and just return.

User of logging code should not really care much about this class, only call the .arg method to generate the correct output.

The class is a template to allow easy testing. Also, we want everything here in the header anyway and it doesn't depend on the details of what Logger really is, so it doesn't hurt anything.

Also, if you are interested in the internals, you might find the copy constructor a bit strange. It deactivates the original formatter. We don't really want to support copying of the Formatter by user, but C++ needs a copy constructor when returning from the logging functions, so we need one. And if we did not deactivate the original Formatter, that one would get destroyed before any call to .arg, producing an output, and then the one the .arg calls are called on would get destroyed as well, producing output again. So, think of this behavior as soul moving from one to another.

Definition at line 105 of file log_formatter.h.

Constructor & Destructor Documentation

◆ Formatter() [1/2]

template<class Logger>
isc::log::Formatter< Logger >::Formatter ( const Severity severity = NONE,
boost::shared_ptr< std::string >  message = boost::make_shared<std::string>(),
Logger logger = NULL 

Constructor of "active" formatter.

This will create a formatter. If the arguments are set, it will be active (will produce output). If you leave them all as NULL, it will create an inactive Formatter – one that'll produce no output.

It is not expected to be called by user of logging system directly.

severityThe severity of the message (DEBUG, ERROR etc.)
messageThe message with placeholders. We take ownership of it and we will modify the string. Must not be NULL unless logger is also NULL, but it's not checked.
loggerThe logger where the final output will go, or NULL if no output is wanted.

Definition at line 137 of file log_formatter.h.

◆ Formatter() [2/2]

template<class Logger>
isc::log::Formatter< Logger >::Formatter ( const Formatter< Logger > &  other)

Copy constructor.

"Control" is passed to the created object in that it is the created object that will have responsibility for outputting the formatted message - the object being copied relinquishes that responsibility.

Definition at line 149 of file log_formatter.h.

◆ ~Formatter()

template<class Logger>
isc::log::Formatter< Logger >::~Formatter ( )


This is the place where output happens if the formatter is active.

Definition at line 158 of file log_formatter.h.

References isc::log::checkExcessPlaceholders().

+ Here is the call graph for this function:

Member Function Documentation

◆ arg() [1/2]

template<class Logger>
template<class Arg >
Formatter& isc::log::Formatter< Logger >::arg ( const Arg &  value)

Replaces another placeholder.

Replaces another placeholder and returns a new formatter with it. Deactivates the current formatter. In case the formatter is not active, only produces another inactive formatter.

valueThe argument to place into the placeholder.

Definition at line 192 of file log_formatter.h.

References isc_throw, and isc::Exception::what().

Referenced by isc::log::LoggerManager::readLocalMessageFile().

+ Here is the call graph for this function:

◆ arg() [2/2]

template<class Logger>
Formatter& isc::log::Formatter< Logger >::arg ( const std::string &  arg)

String version of arg.

argThe text to place into the placeholder.

Definition at line 219 of file log_formatter.h.

References isc::log::replacePlaceholder().

+ Here is the call graph for this function:

◆ deactivate()

template<class Logger>
void isc::log::Formatter< Logger >::deactivate ( )

Turn off the output of this logger.

If the logger would output anything at the end, now it won't. Also, this turns off the strict checking of placeholders, if it is compiled in.

The expected use is when there was an exception processing the arguments for the message.

Definition at line 252 of file log_formatter.h.

◆ operator=()

template<class Logger>
Formatter& isc::log::Formatter< Logger >::operator= ( const Formatter< Logger > &  other)

Assignment operator.

Essentially the same function as the assignment operator - the object being assigned to takes responsibility for outputting the message.

Definition at line 173 of file log_formatter.h.

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