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 (helpers::Pool &p) override

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

virtual pattern::PatternMap getFormatSpecifiers () const =0

A map from a name to the object implementing the (date or index) formatting.

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
	A map from "d" and "date" to a date conversion formatter.

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 & )

overridevirtual

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

Logs a warning if an option is not valid.

See also: RollingPolicyBase::activateOptions()

Reimplemented from log4cxx::rolling::RollingPolicyBase.

◆ getFormatSpecifiers()

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

overrideprotectedvirtual

A map from "d" and "date" to a date conversion formatter.

See also: FileDatePatternConverter

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.

Supported options	Supported values	Default value
ThrowIOExceptionOnForkFailure	True,False	True

See also: RollingPolicyBase::setOption()

Reimplemented from log4cxx::rolling::RollingPolicyBase.

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

timebasedrollingpolicy.h

Public Member Functions

Protected Member Functions

Detailed Description

Automatic file compression

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

Constructor & Destructor Documentation

◆ TimeBasedRollingPolicy()

◆ ~TimeBasedRollingPolicy()

Member Function Documentation

◆ activateOptions()

◆ getFormatSpecifiers()

◆ initialize()

◆ isTriggeringEvent()

◆ rollover()

◆ setMultiprocess()

◆ setOption()