Package org.apache.log4j.rolling

Class TimeBasedRollingPolicy

  • All Implemented Interfaces:
    RollingPolicy, TriggeringPolicy, org.apache.log4j.spi.OptionHandler
    public final 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 archived 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 those 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.

    • Field Detail

      • nextCheck

        private long nextCheck
        Time for next determination if time for rollover.

      • lastFileName

        private java.lang.String lastFileName
        File name at last rollover.

      • suffixLength

        private int suffixLength
        Length of any file type suffix (.gz, .zip).

    • Constructor Detail

      • TimeBasedRollingPolicy

        public TimeBasedRollingPolicy()
        Constructs a new instance.

    • Method Detail

      • activateOptions

        public void activateOptions()
        Prepares instance of use.
        Specified by:
        activateOptions in interface org.apache.log4j.spi.OptionHandler
        Overrides:
        activateOptions in class RollingPolicyBase

      • initialize

        public RolloverDescription initialize​(java.lang.String currentActiveFile,
                                      boolean append)
        Initialize the policy and return any initial actions for rolling file appender..
        Specified by:
        initialize in interface RollingPolicy
        Parameters:
        currentActiveFile - current value of RollingFileAppender.getFile().
        append - current value of RollingFileAppender.getAppend().
        Returns:
        Description of the initialization, may be null to indicate no initialization needed.

      • rollover

        public RolloverDescription rollover​(java.lang.String currentActiveFile)
        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.
        Specified by:
        rollover in interface RollingPolicy
        Parameters:
        currentActiveFile - file name for current active log file.
        Returns:
        Description of pending rollover, may be null to indicate no rollover at this time.

      • isTriggeringEvent

        public boolean isTriggeringEvent​(org.apache.log4j.Appender appender,
                                 org.apache.log4j.spi.LoggingEvent event,
                                 java.lang.String filename,
                                 long fileLength)
        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.
        Specified by:
        isTriggeringEvent in interface TriggeringPolicy
        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.