org.apache.log4j.rolling

## Class TimeBasedRollingPolicy

- java.lang.Object
- - org.apache.log4j.rolling.RollingPolicyBase
  - - org.apache.log4j.rolling.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`.

  Author:
    Ceki Gülcü, Curt Arnold

- - ### Field Summary

    - ### Fields inherited from class org.apache.log4j.rolling.RollingPolicyBase

      `activeFileName`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TimeBasedRollingPolicy()` Constructs a new instance.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `activateOptions()` Prepares instance of use.
    `RolloverDescription` | `initialize(String currentActiveFile, boolean append)` Initialize the policy and return any initial actions for rolling file appender..
    `boolean` | `isTriggeringEvent(org.apache.log4j.Appender appender, org.apache.log4j.spi.LoggingEvent event, String filename, long fileLength)` Determines if a rollover may be appropriate at this time.
    `RolloverDescription` | `rollover(String currentActiveFile)` Prepare for a rollover.

    - ### Methods inherited from class org.apache.log4j.rolling.RollingPolicyBase

      `formatFileName, getActiveFileName, getDatePatternConverter, getFileNamePattern, getIntegerPatternConverter, parseFileNamePattern, setActiveFileName, setFileNamePattern`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### 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(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(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,
                                  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.

Copyright © 2013 The Apache Software Foundation. Licensed under the Apache License, Version 2.0

Apache Extras for Apache log4j, Apache log4j and Apache are trademarks of the Apache Software Foundation.