log4cxx::rolling::TimeBasedRollingPolicy Class Reference

TimeBasedRollingPolicy is both easy to configure and quite powerful. More...

#include <timebasedrollingpolicy.h>

Inheritance diagram for log4cxx::rolling::TimeBasedRollingPolicy:

Public Member Functions
	TimeBasedRollingPolicy ()
virtual	~TimeBasedRollingPolicy ()
void	activateOptions (helpers::Pool &) override
	Activate the options that were previously set with calls to option setters.
void	setMultiprocess (bool multiprocess)
RolloverDescriptionPtr	initialize (const LogString &currentActiveFile, const bool append, helpers::Pool &pool) override
	Initialize the policy and return any initial actions for rolling file appender. Parameters currentActiveFile current value of RollingFileAppender.getFile(). append current value of RollingFileAppender.getAppend(). pool pool for memory allocations during call. Returns Description of the initialization, may be null to indicate no initialization needed. Exceptions SecurityException if denied access to log files.
RolloverDescriptionPtr	rollover (const LogString &currentActiveFile, const bool append, helpers::Pool &pool) override
	Prepare for a rollover.This method is called prior to closing the active log file, performs any necessary preliminary actions and describes actions needed after close of current log file. Parameters currentActiveFile file name for current active log file. append current value of the parent FileAppender.getAppend(). pool pool for memory allocations during call. Returns Description of pending rollover, may be null to indicate no rollover at this time. Exceptions SecurityException if denied access to log files.
bool	isTriggeringEvent (Appender *appender, const spi::LoggingEventPtr &event, const LogString &filename, size_t fileLength) override
	Determines if a rollover may be appropriate at this time.
void	setOption (const LogString &option, const LogString &value) override
	Set option to value.
Public Member Functions inherited from log4cxx::rolling::RollingPolicyBase
	RollingPolicyBase ()
virtual	~RollingPolicyBase ()
void	activateOptions (log4cxx::helpers::Pool &p) override
	Activate the options that were previously set with calls to option setters.
virtual log4cxx::pattern::PatternMap	getFormatSpecifiers () const =0
void	setOption (const LogString &option, const LogString &value) override
	Set option to value.
void	setFileNamePattern (const LogString &fnp)
	Set file name pattern.
LogString	getFileNamePattern () const
	Get file name pattern.
bool	getCreateIntermediateDirectories () const
void	setCreateIntermediateDirectories (bool createIntermediate)
PatternConverterList	getPatternConverterList () const
Public Member Functions inherited from log4cxx::rolling::RollingPolicy
virtual	~RollingPolicy ()
virtual RolloverDescriptionPtr	initialize (const LogString &currentActiveFile, const bool append, log4cxx::helpers::Pool &pool)=0
	Initialize the policy and return any initial actions for rolling file appender.
virtual RolloverDescriptionPtr	rollover (const LogString &currentActiveFile, const bool append, log4cxx::helpers::Pool &pool)=0
	Prepare for a rollover.
Public Member Functions inherited from log4cxx::spi::OptionHandler
virtual	~OptionHandler ()
virtual void	activateOptions (helpers::Pool &p)=0
	Activate the options that were previously set with calls to option setters.
virtual void	setOption (const LogString &option, const LogString &value)=0
	Set option to value.
Public Member Functions inherited from log4cxx::helpers::Object
virtual	~Object ()
virtual const helpers::Class &	getClass () const =0
virtual bool	instanceof (const Class &clazz) const =0
virtual const void *	cast (const Class &clazz) const =0
Public Member Functions inherited from log4cxx::rolling::TriggeringPolicy
virtual	~TriggeringPolicy ()
virtual bool	isTriggeringEvent (Appender *appender, const spi::LoggingEventPtr &event, const LogString &filename, size_t fileLength)=0
	Determines if a rollover may be appropriate at this time.

Protected Member Functions
log4cxx::pattern::PatternMap	getFormatSpecifiers () const override
Protected Member Functions inherited from log4cxx::rolling::RollingPolicyBase
	RollingPolicyBase (LOG4CXX_PRIVATE_PTR(RollingPolicyBasePrivate) priv)
void	parseFileNamePattern ()
	Parse file name pattern.
void	formatFileName (const helpers::ObjectPtr &obj, LogString &buf, helpers::Pool &p) const
	Format file name.
log4cxx::pattern::PatternConverterPtr	getIntegerPatternConverter () const
log4cxx::pattern::PatternConverterPtr	getDatePatternConverter () const

Detailed Description

TimeBasedRollingPolicy is both easy to configure and quite powerful.

In order to use TimeBasedRollingPolicy, the FileNamePattern option must be set. It basically specifies the name of the rolled log files. The value FileNamePattern should consist of the name of the file, plus a suitably placed d conversion specifier. The d conversion specifier may contain a date and time pattern as specified by the log4cxx::helpers::SimpleDateFormat class. If the date and time pattern is ommitted, then the default pattern of "yyyy-MM-dd" is assumed. The following examples should clarify the point.

FileNamePattern value	Rollover schedule	Example
/wombat/folder/foo.d	Daily rollover (at midnight). Due to the omission of the optional time and date pattern for the d token specifier, the default pattern of "yyyy-MM-dd" is assumed, which corresponds to daily rollover.	During November 23rd, 2004, logging output will go to the file /wombat/foo.2004-11-23. At midnight and for the rest of the 24th, logging output will be directed to /wombat/foo.2004-11-24.
/wombat/foo.d{yyyy-MM}.log	Rollover at the beginning of each month.	During the month of October 2004, logging output will go to /wombat/foo.2004-10.log. After midnight of October 31st and for the rest of November, logging output will be directed to /wombat/foo.2004-11.log.

Automatic file compression

TimeBasedRollingPolicy supports automatic file compression. This feature is enabled if the value of the FileNamePattern option ends with .gz or .zip.

FileNamePattern value	Rollover schedule	Example
/wombat/foo.d.gz	Daily rollover (at midnight) with automatic GZIP compression of the arcived files.	During November 23rd, 2004, logging output will go to the file /wombat/foo.2004-11-23. However, at midnight that file will be compressed to become /wombat/foo.2004-11-23.gz. For the 24th of November, logging output will be directed to /wombat/folder/foo.2004-11-24 until its rolled over at the beginning of the next day.

Decoupling the location of the active log file and the archived log files

The active file is defined as the log file for the current period whereas archived files are thos files which have been rolled over in previous periods.

By setting the ActiveFileName option you can decouple the location of the active log file and the location of the archived log files.

FileNamePattern value	ActiveFileName	Rollover schedule	Example
/wombat/foo.log.d	/wombat/foo.log	Daily rollover.	During November 23rd, 2004, logging output will go to the file /wombat/foo.log. However, at midnight that file will archived as /wombat/foo.log.2004-11-23. For the 24th of November, logging output will be directed to /wombat/folder/foo.log until its archived as /wombat/foo.log.2004-11-24 at the beginning of the next day.

If configuring programatically, do not forget to call activateOptions method before using this policy. Moreover, activateOptions of TimeBasedRollingPolicy must be called before calling the activateOptions method of the owning RollingFileAppender.

Constructor & Destructor Documentation

TimeBasedRollingPolicy()

log4cxx::rolling::TimeBasedRollingPolicy::TimeBasedRollingPolicy

(

)

~TimeBasedRollingPolicy()

virtual log4cxx::rolling::TimeBasedRollingPolicy::~TimeBasedRollingPolicy ( )

virtual

Member Function Documentation

activateOptions()

void log4cxx::rolling::TimeBasedRollingPolicy::activateOptions ( helpers::Pool &  p )

overridevirtual

Activate the options that were previously set with calls to option setters.

This allows to defer activiation of the options until all options have been set. This is required for components which have related options that remain ambigous until all are set.

For example, the FileAppender has the File and Append options both of which are ambigous until the other is also set.

Reimplemented from log4cxx::rolling::RollingPolicyBase.

getFormatSpecifiers()

log4cxx::pattern::PatternMap log4cxx::rolling::TimeBasedRollingPolicy::getFormatSpecifiers ( ) const

overrideprotectedvirtual

Implements log4cxx::rolling::RollingPolicyBase.

initialize()

RolloverDescriptionPtr log4cxx::rolling::TimeBasedRollingPolicy::initialize ( const LogString &  currentActiveFile, const bool  append, helpers::Pool &  pool  )

overridevirtual

Initialize the policy and return any initial actions for rolling file appender.

Parameters

currentActiveFile	current value of RollingFileAppender.getFile().
append	current value of RollingFileAppender.getAppend().
pool	pool for memory allocations during call.

Returns

Description of the initialization, may be null to indicate no initialization needed.

Exceptions

SecurityException

if denied access to log files.

Implements log4cxx::rolling::RollingPolicy.

isTriggeringEvent()

bool log4cxx::rolling::TimeBasedRollingPolicy::isTriggeringEvent ( Appender *  appender, const spi::LoggingEventPtr &  event, const LogString &  filename, size_t  fileLength  )

overridevirtual

Determines if a rollover may be appropriate at this time.

If true is returned, RolloverPolicy.rollover will be called but it can determine that a rollover is not warranted.

Parameters

appender	A reference to the appender.
event	A reference to the currently event.
filename	The filename for the currently active log file.
fileLength	Length of the file in bytes.

Returns

true if a rollover should occur.

Implements log4cxx::rolling::TriggeringPolicy.

rollover()

RolloverDescriptionPtr log4cxx::rolling::TimeBasedRollingPolicy::rollover ( const LogString &  currentActiveFile, const bool  append, helpers::Pool &  pool  )

overridevirtual

Prepare for a rollover.This method is called prior to closing the active log file, performs any necessary preliminary actions and describes actions needed after close of current log file.

Parameters

currentActiveFile	file name for current active log file.
append	current value of the parent FileAppender.getAppend().
pool	pool for memory allocations during call.

Returns

Description of pending rollover, may be null to indicate no rollover at this time.

Exceptions

SecurityException

if denied access to log files.

Implements log4cxx::rolling::RollingPolicy.

setMultiprocess()

void log4cxx::rolling::TimeBasedRollingPolicy::setMultiprocess

(

bool

multiprocess

)

setOption()

void log4cxx::rolling::TimeBasedRollingPolicy::setOption ( const LogString &  option, const LogString &  value  )

overridevirtual

Set option to value.

The handling of each option depends on the OptionHandler instance. Some options may become active immediately whereas other may be activated only when activateOptions is called.

Reimplemented from log4cxx::rolling::RollingPolicyBase.

---

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

• timebasedrollingpolicy.h