log4cplus::PropertyConfigurator Class Reference

Provides configuration from an external file. More...

`#include <configurator.h>`

Inheritance diagram for log4cplus::PropertyConfigurator:
[legend]
Collaboration diagram for log4cplus::PropertyConfigurator:
[legend]

## Public Types

enum | PCFlags { fRecursiveExpansion = (1 << 0) , fShadowEnvironment = (1 << 1) , fAllowEmptyVars = (1 << 2) , fEncodingShift = 3 , fEncodingMask = 0x3 , fUnspecEncoding = (0 << fEncodingShift) , fThrow = (1 << 5) }

## Public Member Functions

| PropertyConfigurator (const log4cplus::tstring &propertyFile, Hierarchy &h=Logger::getDefaultHierarchy(), unsigned flags=0)
| PropertyConfigurator (const log4cplus::helpers::Properties &props, Hierarchy &h=Logger::getDefaultHierarchy(), unsigned flags=0)
| PropertyConfigurator (log4cplus::tistream &propertyStream, Hierarchy &h=Logger::getDefaultHierarchy(), unsigned flags=0)
virtual | ~PropertyConfigurator ()
virtual void | configure ()
| Read configuration from a file.
log4cplus::helpers::Properties const & | getProperties () const
log4cplus::tstring const & | getPropertyFilename () const

## Static Public Member Functions

static void | doConfigure (const log4cplus::tstring &configFilename, Hierarchy &h=Logger::getDefaultHierarchy(), unsigned flags=0)
| This method eliminates the need to create a temporary `PropertyConfigurator` to configure log4cplus.

## Protected Types

typedef std::map< log4cplus::tstring, log4cplus::SharedAppenderPtr > | AppenderMap

## Protected Member Functions

void | init ()
void | reconfigure ()
void | replaceEnvironVariables ()
void | configureLoggers ()
void | configureLogger (log4cplus::Logger logger, const log4cplus::tstring &config)
void | configureAppenders ()
void | configureAdditivity ()
virtual Logger | getLogger (const log4cplus::tstring &name)
virtual void | addAppender (Logger &logger, log4cplus::SharedAppenderPtr &appender)

## Protected Attributes

Hierarchy & | h
log4cplus::tstring | propertyFilename
log4cplus::helpers::Properties | properties
AppenderMap | appenders
unsigned | flags

## Detailed Description

Provides configuration from an external file.

See configure() for the expected format.

All option values admit variable substitution. For example, if `userhome` environment property is set to `/home/xyz` and the File option is set to the string `${userhome}/test.log`, then File option will be interpreted as the string `/home/xyz/test.log`.

The syntax of variable substitution is similar to that of UNIX shells. The string between an opening "${" and closing "}" is interpreted as a key. Its value is searched in the environment properties. The corresponding value replaces the ${variableName} sequence.

Configuration files also recognize `include file.properties` directive that allow composing configuration from multiple files. There is no cyclic includes detection mechanism to stop unbound recursion.

Definition at line 67 of file configurator.h.

## Member Typedef Documentation

## AppenderMap

typedef std::map<log4cplus::tstring, log4cplus::SharedAppenderPtr> log4cplus::PropertyConfigurator::AppenderMap

protected

Definition at line 311 of file configurator.h.

## Member Enumeration Documentation

## PCFlags

enum log4cplus::PropertyConfigurator::PCFlags

Enumerator
fRecursiveExpansion |
fShadowEnvironment |
fAllowEmptyVars |
fEncodingShift |
fEncodingMask |
fUnspecEncoding |
fThrow |

Definition at line 70 of file configurator.h.

## Constructor & Destructor Documentation

## PropertyConfigurator() [1/3]

log4cplus::PropertyConfigurator::PropertyConfigurator | ( | const log4cplus::tstring & | propertyFile,
|  | Hierarchy & | h = Logger::getDefaultHierarchy(),
|  | unsigned | flags = 0 )

References flags, log4cplus::Logger::getDefaultHierarchy(), and h.

## PropertyConfigurator() [2/3]

log4cplus::PropertyConfigurator::PropertyConfigurator | ( | const log4cplus::helpers::Properties & | props,
|  | Hierarchy & | h = Logger::getDefaultHierarchy(),
|  | unsigned | flags = 0 )

References flags, log4cplus::Logger::getDefaultHierarchy(), and h.

## PropertyConfigurator() [3/3]

log4cplus::PropertyConfigurator::PropertyConfigurator | ( | log4cplus::tistream & | propertyStream,
|  | Hierarchy & | h = Logger::getDefaultHierarchy(),
|  | unsigned | flags = 0 )

References flags, log4cplus::Logger::getDefaultHierarchy(), and h.

## ~PropertyConfigurator()

virtual log4cplus::PropertyConfigurator::~PropertyConfigurator | ( |  | ) |

virtual

## Member Function Documentation

## addAppender()

virtual void log4cplus::PropertyConfigurator::addAppender | ( | Logger & | logger,
|  | log4cplus::SharedAppenderPtr & | appender )

protected virtual

## configure()

virtual void log4cplus::PropertyConfigurator::configure | ( |  | ) |

virtual

Read configuration from a file.

The existing configuration is not cleared nor reset. If you require a different behavior, then call `resetConfiguration` method before calling `doConfigure`.

The configuration file consists of statements in the format `key=value`. The syntax of different configuration elements are discussed below.

### Appender configuration

Appender configuration syntax is:

    # For appender named appenderName, set its class.
    # Note: The appender name can contain dots.
    log4cplus.appender.appenderName=fully.qualified.name.of.appender.class

    # Set appender specific options.
    log4cplus.appender.appenderName.option1=value1
    ...
    log4cplus.appender.appenderName.optionN=valueN

For each named appender you can configure its `Layout`. The syntax for configuring an appender's layout is:

    log4cplus.appender.appenderName.layout=fully.qualified.name.of.layout.class
    log4cplus.appender.appenderName.layout.option1=value1
    ....
    log4cplus.appender.appenderName.layout.optionN=valueN

### Configuring loggers

The syntax for configuring the root logger is:

    log4cplus.rootLogger=[LogLevel], appenderName, appenderName, ...

This syntax means that an optional LogLevel value can be supplied followed by appender names separated by commas.

The LogLevel value can consist of the string values FATAL, ERROR, WARN, INFO, DEBUG or a custom LogLevel value.

If a LogLevel value is specified, then the root LogLevel is set to the corresponding LogLevel. If no LogLevel value is specified, then the root LogLevel remains untouched.

The root logger can be assigned multiple appenders.

Each appenderName (separated by commas) will be added to the root logger. The named appender is defined using the appender syntax defined above.

For non-root loggers the syntax is almost the same:

    log4cplus.logger.logger_name=[LogLevel|INHERITED], appenderName, appenderName, ...

The meaning of the optional LogLevel value is discussed above in relation to the root logger. In addition however, the value INHERITED can be specified meaning that the named logger should inherit its LogLevel from the logger hierarchy.

By default loggers inherit their LogLevel from the hierarchy. However, if you set the LogLevel of a logger and later decide that that logger should inherit its LogLevel, then you should specify INHERITED as the value for the LogLevel value.

Similar to the root logger syntax, each appenderName (separated by commas) will be attached to the named logger.

See the appender additivity rule in the user manual for the meaning of the `additivity` flag.

The user can override any of the `Hierarchy#disable` family of methods by setting the a key "log4cplus.disableOverride" to `true` or any value other than false. As in

    log4cplus.disableOverride=true

### Global configuration

- Property

      log4cplus.threadPoolSize

  can be used to adjust size of log4cplus' internal thread pool.
- Property

      log4cplus.threadPoolBlockOnFull

  can be used to change behaviour of the thread pool when its queue is full. The default value is

      true

  , to block the thread until there is a space in the queue. Setting this property to

      false

  makes the thread pool not to block when it is full. The items that could not be inserted are dropped instead.
- Property

      log4cplus.threadPoolQueueSizeLimit

  can be used to set thread pool queue size limit.

### Example

An example configuration is given below.

    # Set options for appender named "A1".
    # Appender "A1" will be a SyslogAppender
    log4cplus.appender.A1=log4cplus::SyslogAppender

    # The syslog daemon resides on www.abc.net
    log4cplus.appender.A1.SyslogHost=www.abc.net

    # A1's layout is a PatternLayout, using the conversion pattern
    # r %-5p c{2} M.L x - m

    . Thus, the log output will
    # include # the relative time since the start of the application in
    # milliseconds, followed by the LogLevel of the log request,
    # followed by the two rightmost components of the logger name,
    # followed by the callers method name, followed by the line number,
    # the nested disgnostic context and finally the message itself.
    # Refer to the documentation of PatternLayout for further information # on the syntax of the ConversionPattern key. log4cplus.appender.A1.layout=log4cplus::PatternLayout log4cplus.appender.A1.layout.ConversionPattern=%-4r %-5p c{2} M.L x - m

     # Set options for appender named "A2" # A2 should be a RollingFileAppender, with maximum file size of 10 MB # using at most one backup file. A2's layout is TTCC, using the # ISO8061 date format with context printing enabled. log4cplus.appender.A2=log4cplus::RollingFileAppender log4cplus.appender.A2.MaxFileSize=10MB log4cplus.appender.A2.MaxBackupIndex=1 log4cplus.appender.A2.layout=log4cplus::TTCCLayout log4cplus.appender.A2.layout.ContextPrinting=true log4cplus.appender.A2.layout.DateFormat=ISO8601 # Root logger set to DEBUG using the A2 appender defined above. log4cplus.rootLogger=DEBUG, A2 # Logger definitions: # The SECURITY logger inherits is LogLevel from root. However, it's output # will go to A1 appender defined above. It's additivity is non-cumulative. log4cplus.logger.SECURITY=INHERIT, A1 log4cplus.additivity.SECURITY=false # Only warnings or above will be logged for the logger "SECURITY.access". # Output will go to A1. log4cplus.logger.SECURITY.access=WARN # The logger "class.of.the.day" inherits its LogLevel from the # logger hierarchy. Output will go to the appender's of the root # logger, A2 in this case. log4cplus.logger.class.of.the.day=INHERIT

Refer to the setOption method in each Appender and Layout for class specific options.

Use the `#` character at the beginning of a line for comments.

## configureAdditivity()

void log4cplus::PropertyConfigurator::configureAdditivity | ( |  | ) |

protected

## configureAppenders()

void log4cplus::PropertyConfigurator::configureAppenders | ( |  | ) |

protected

## configureLogger()

void log4cplus::PropertyConfigurator::configureLogger | ( | log4cplus::Logger | logger,
|  | const log4cplus::tstring & | config )

protected

## configureLoggers()

void log4cplus::PropertyConfigurator::configureLoggers | ( |  | ) |

protected

## doConfigure()

void log4cplus::PropertyConfigurator::doConfigure | ( | const log4cplus::tstring & | configFilename,
|  | Hierarchy & | h = Logger::getDefaultHierarchy(),
|  | unsigned | flags = 0 )

static

This method eliminates the need to create a temporary `PropertyConfigurator` to configure log4cplus.

It is equivalent to the following:
`PropertyConfigurator config("filename"); config.configure();`

References flags, log4cplus::Logger::getDefaultHierarchy(), and h.

## getLogger()

virtual Logger log4cplus::PropertyConfigurator::getLogger | ( | const log4cplus::tstring & | name | ) |

protected virtual

## getProperties()

log4cplus::helpers::Properties const & log4cplus::PropertyConfigurator::getProperties | ( |  | ) | const

Returns
  The return value is reference to Properties container of properties with the `"log4cplus."` prefix removed and references to other properties and/or environment variables expanded.

## getPropertyFilename()

log4cplus::tstring const & log4cplus::PropertyConfigurator::getPropertyFilename | ( |  | ) | const

Returns
  The return value is a reference to log4cplus::tstring containing filename of properties source file. It will be string "UNAVAILABLE" if the PropertyConfigurator instance has been constructed using one of the other constructors that do not take filename as parameter.

## init()

void log4cplus::PropertyConfigurator::init | ( |  | ) |

protected

## reconfigure()

void log4cplus::PropertyConfigurator::reconfigure | ( |  | ) |

protected

## replaceEnvironVariables()

void log4cplus::PropertyConfigurator::replaceEnvironVariables | ( |  | ) |

protected

## Member Data Documentation

## appenders

AppenderMap log4cplus::PropertyConfigurator::appenders

protected

Definition at line 317 of file configurator.h.

## flags

unsigned log4cplus::PropertyConfigurator::flags

protected

Definition at line 318 of file configurator.h.

Referenced by doConfigure(), PropertyConfigurator(), PropertyConfigurator(), and PropertyConfigurator().

## h

Hierarchy& log4cplus::PropertyConfigurator::h

protected

Definition at line 314 of file configurator.h.

Referenced by log4cplus::BasicConfigurator::BasicConfigurator(), log4cplus::BasicConfigurator::doConfigure(), doConfigure(), PropertyConfigurator(), PropertyConfigurator(), and PropertyConfigurator().

## properties

log4cplus::helpers::Properties log4cplus::PropertyConfigurator::properties

protected

Definition at line 316 of file configurator.h.

## propertyFilename

log4cplus::tstring log4cplus::PropertyConfigurator::propertyFilename

protected

Definition at line 315 of file configurator.h.

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

- configurator.h