Log4j 1.3alpha-6

org.apache.log4j.rolling
Class TimeBasedRollingPolicy

java.lang.Object
  |
  +--org.apache.log4j.spi.ComponentBase
        |
        +--org.apache.log4j.rolling.RollingPolicyBase
              |
              +--org.apache.log4j.rolling.TimeBasedRollingPolicy
All Implemented Interfaces:
Component, OptionHandler, RollingPolicy, TriggeringPolicy

public class TimeBasedRollingPolicy
extends RollingPolicyBase
implements TriggeringPolicy

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

Since:
1.3
Author:
Ceki Gülcü

Field Summary
 
Fields inherited from class org.apache.log4j.rolling.RollingPolicyBase
activeFileName, compressionMode, fileNamePattern, fileNamePatternStr
 
Fields inherited from class org.apache.log4j.spi.ComponentBase
repository
 
Constructor Summary
TimeBasedRollingPolicy()
           
 
Method Summary
 void activateOptions()
          Activate the options that were previously set with calls to option setters.
 java.lang.String getActiveFileName()
          The active log file is determined by the value of the activeFileName option if it is set.
 boolean isTriggeringEvent(java.io.File file)
          Should rolllover be triggered at this time?
 void rollover()
          Rolls over log files according to implementation policy.
 
Methods inherited from class org.apache.log4j.rolling.RollingPolicyBase
determineCompressionMode, getFileNamePattern, setActiveFileName, setFileNamePattern
 
Methods inherited from class org.apache.log4j.spi.ComponentBase
getLogger, setLoggerRepository
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

TimeBasedRollingPolicy

public TimeBasedRollingPolicy()
Method Detail

activateOptions

public void activateOptions()
Description copied from interface: OptionHandler
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.

Specified by:
activateOptions in interface OptionHandler
Specified by:
activateOptions in class RollingPolicyBase

rollover

public void rollover()
              throws RolloverFailure
Description copied from interface: RollingPolicy
Rolls over log files according to implementation policy.

This method is invoked by RollingFileAppender, usually at the behest of its TriggeringPolicy.

Specified by:
rollover in interface RollingPolicy
Throws:
RolloverFailure - Thrown if the rollover operation fails for any reason.

getActiveFileName

public java.lang.String getActiveFileName()
The active log file is determined by the value of the activeFileName option if it is set. However, in case the activeFileName is left blank, then, the active log file equals the file name for the current period as computed by the FileNamePattern option.

Specified by:
getActiveFileName in interface RollingPolicy

isTriggeringEvent

public boolean isTriggeringEvent(java.io.File file)
Description copied from interface: TriggeringPolicy
Should rolllover be triggered at this time?

Specified by:
isTriggeringEvent in interface TriggeringPolicy
Parameters:
file - A reference to the currently active log file.

Log4j 1.3alpha-6

Copyright 2000-2005 Apache Software Foundation.