TimeBasedRollingPolicy Class Reference

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

Inherits RollingPolicyBase, and TriggeringPolicy.

## Public Member Functions

| TimeBasedRollingPolicy ()
void | addRef () const
void | releaseRef () const
void | activateOptions (log4cxx::helpers::Pool &)
| Activate the options that were previously set with calls to option setters. More...
RolloverDescriptionPtr | initialize (const LogString &file, const bool append, log4cxx::helpers::Pool &pool)
| Initialize the policy and return any initial actions for rolling file appender. More...
RolloverDescriptionPtr | rollover (const LogString &activeFile, log4cxx::helpers::Pool &pool)
| Prepare for a rollover. More...
virtual bool | isTriggeringEvent (Appender *appender, const log4cxx::spi::LoggingEventPtr &event, const LogString &filename, size_t fileLength)
| Determines if a rollover may be appropriate at this time. More...
Public Member Functions inherited from RollingPolicyBase
| RollingPolicyBase ()
virtual | ~RollingPolicyBase ()
virtual void | setOption (const LogString &option, const LogString &value)
| Set `option` to `value`. More...
void | setFileNamePattern (const LogString &fnp)
| Set file name pattern. More...
LogString | getFileNamePattern () const
| Get file name pattern. More...
Public Member Functions inherited from RollingPolicy
virtual | ~RollingPolicy ()
Public Member Functions inherited from OptionHandler
virtual | ~OptionHandler ()
Public Member Functions inherited from Object
virtual const helpers::Class & | getClass () const
virtual | ~Object ()
virtual bool | instanceof (const Class &clazz) const =0
virtual const void * | cast (const Class &clazz) const =0
Public Member Functions inherited from ObjectImpl
| ObjectImpl ()
virtual | ~ObjectImpl ()
Public Member Functions inherited from TriggeringPolicy
virtual | ~TriggeringPolicy ()
void | addRef () const
void | releaseRef () const

## Protected Member Functions

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

## Additional Inherited Members

Static Public Member Functions inherited from Object
static const helpers::Class & | getStaticClass ()
static const log4cxx::helpers::ClassRegistration & | registerClass ()
Protected Attributes inherited from ObjectImpl
unsigned int volatile | ref

## 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 | ( |  | ) |

## Member Function Documentation

void activateOptions | ( | log4cxx::helpers::Pool & | p | ) |

virtual

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.

Implements RollingPolicyBase.

void addRef | ( |  | ) | const

virtual

Reimplemented from RollingPolicyBase.

log4cxx::pattern::PatternMap getFormatSpecifiers | ( |  | ) | const

protected virtual

Implements RollingPolicyBase.

RolloverDescriptionPtr initialize | ( | const LogString & | file,
|  | const bool | append,
|  | log4cxx::helpers::Pool & | pool
| ) |  |

virtual

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

Parameters

  file | current value of RollingFileAppender.getFile().
  append | current value of RollingFileAppender.getAppend().
  pool | pool for any required allocations.

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

Exceptions

  SecurityException | if denied access to log files.

Implements RollingPolicy.

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

virtual

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 TriggeringPolicy.

void releaseRef | ( |  | ) | const

virtual

Reimplemented from RollingPolicyBase.

RolloverDescriptionPtr rollover | ( | const LogString & | activeFile,
|  | log4cxx::helpers::Pool & | pool
| ) |  |

virtual

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

  activeFile | file name for current active log file.
  pool | pool for any required allocations.

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

Exceptions

  SecurityException | if denied access to log files.

Implements RollingPolicy.

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

- timebasedrollingpolicy.h