org.apache.log4j.rolling

## Class RollingFileAppender

- java.lang.Object
- - org.apache.log4j.AppenderSkeleton
  - - org.apache.log4j.WriterAppender
    - - org.apache.log4j.FileAppender
      - - org.apache.log4j.rolling.RollingFileAppender

- All Implemented Interfaces:
    org.apache.log4j.Appender, org.apache.log4j.spi.OptionHandler, org.apache.log4j.xml.UnrecognizedElementHandler

      public final class RollingFileAppender
      extends org.apache.log4j.FileAppender
      implements org.apache.log4j.xml.UnrecognizedElementHandler

  `RollingFileAppender` extends `FileAppender` to backup the log files depending on `RollingPolicy` and `TriggeringPolicy`.

  To be of any use, a `RollingFileAppender` instance must have both a `RollingPolicy` and a `TriggeringPolicy` set up. However, if its `RollingPolicy` also implements the `TriggeringPolicy` interface, then only the former needs to be set up. For example, `TimeBasedRollingPolicy` acts both as a `RollingPolicy` and a `TriggeringPolicy`.

  `RollingFileAppender` can be configured programattically or using `DOMConfigurator` or `DOMConfigurator` in log4j 1.2.15 or later. Here is a sample configration file:

      <?xml version="1.0" encoding="UTF-8" ?>
      <!DOCTYPE log4j:configuration>

      <log4j:configuration debug="true">

        <appender name="ROLL" class="org.apache.log4j.rolling.RollingFileAppender">
          <rollingPolicy class="org.apache.log4j.rolling.TimeBasedRollingPolicy">
            <param name="FileNamePattern" value="/wombat/foo.%d{yyyy-MM}.gz"/>
          </rollingPolicy>

          <layout class="org.apache.log4j.PatternLayout">
            <param name="ConversionPattern" value="%c{1} - %m%n"/>
          </layout>
        </appender>

        <root">
          <appender-ref ref="ROLL"/>
        </root>

      </log4j:configuration>

  This configuration file specifies a monthly rollover schedule including automatic compression of the archived files. See `TimeBasedRollingPolicy` for more details.

  Since:
    1.3
  Author:
    Heinz Richter, Ceki Gülcü

- - ### Field Summary

    - ### Fields inherited from class org.apache.log4j.FileAppender

      `bufferedIO, bufferSize, fileAppend, fileName`

    - ### Fields inherited from class org.apache.log4j.WriterAppender

      `encoding, immediateFlush, qw`

    - ### Fields inherited from class org.apache.log4j.AppenderSkeleton

      `closed, errorHandler, headFilter, layout, name, tailFilter, threshold`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RollingFileAppender()` Construct a new instance.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `activateOptions()` Prepare instance of use.
    `void` | `close()` Close appender.
    `protected OutputStreamWriter` | `createWriter(OutputStream os)` Returns an OutputStreamWriter when passed an OutputStream.
    `long` | `getFileLength()` Get byte length of current active log file.
    `RollingPolicy` | `getRollingPolicy()` Get rolling policy.
    `TriggeringPolicy` | `getTriggeringPolicy()` Get triggering policy.
    `void` | `incrementFileLength(int increment)` Increments estimated byte length of current active log file.
    `boolean` | `parseUnrecognizedElement(Element element, Properties props)`
    `boolean` | `rollover()` Implements the usual roll over behaviour.
    `void` | `setRollingPolicy(RollingPolicy policy)` Sets the rolling policy.
    `void` | `setTriggeringPolicy(TriggeringPolicy policy)` Set triggering policy.
    `protected void` | `subAppend(org.apache.log4j.spi.LoggingEvent event)`

    - ### Methods inherited from class org.apache.log4j.FileAppender

      `closeFile, getAppend, getBufferedIO, getBufferSize, getFile, reset, setAppend, setBufferedIO, setBufferSize, setFile, setFile, setQWForFiles`

    - ### Methods inherited from class org.apache.log4j.WriterAppender

      `append, checkEntryConditions, closeWriter, getEncoding, getImmediateFlush, requiresLayout, setEncoding, setErrorHandler, setImmediateFlush, setWriter, shouldFlush, writeFooter, writeHeader`

    - ### Methods inherited from class org.apache.log4j.AppenderSkeleton

      `addFilter, clearFilters, doAppend, finalize, getErrorHandler, getFilter, getFirstFilter, getLayout, getName, getThreshold, isAsSevereAsThreshold, setLayout, setName, setThreshold`

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

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

- - ### Constructor Detail

    - #### RollingFileAppender

          public RollingFileAppender()

      Construct a new instance.

  - ### Method Detail

    - #### activateOptions

          public void activateOptions()

      Prepare instance of use.
      Specified by:
        `activateOptions` in interface `org.apache.log4j.spi.OptionHandler`
      Overrides:
        `activateOptions` in class `org.apache.log4j.FileAppender`

    - #### rollover

          public boolean rollover()

      Implements the usual roll over behaviour.

      If `MaxBackupIndex` is positive, then files {`File.1`, ..., `File.MaxBackupIndex -1`} are renamed to {`File.2`, ..., `File.MaxBackupIndex`}. Moreover, `File` is renamed `File.1` and closed. A new `File` is created to receive further log output.

      If `MaxBackupIndex` is equal to zero, then the `File` is truncated with no backup files created.

      Returns:
        true if rollover performed.

    - #### subAppend

          protected void subAppend(org.apache.log4j.spi.LoggingEvent event)

      Overrides:
        `subAppend` in class `org.apache.log4j.WriterAppender`

    - #### getRollingPolicy

          public RollingPolicy getRollingPolicy()

      Get rolling policy.
      Returns:
        rolling policy.

    - #### getTriggeringPolicy

          public TriggeringPolicy getTriggeringPolicy()

      Get triggering policy.
      Returns:
        triggering policy.

    - #### setRollingPolicy

          public void setRollingPolicy(RollingPolicy policy)

      Sets the rolling policy.
      Parameters:
        `policy` - rolling policy.

    - #### setTriggeringPolicy

          public void setTriggeringPolicy(TriggeringPolicy policy)

      Set triggering policy.
      Parameters:
        `policy` - triggering policy.

    - #### close

          public void close()

      Close appender. Waits for any asynchronous file compression actions to be completed.
      Specified by:
        `close` in interface `org.apache.log4j.Appender`
      Overrides:
        `close` in class `org.apache.log4j.WriterAppender`

    - #### createWriter

          protected OutputStreamWriter createWriter(OutputStream os)

      Returns an OutputStreamWriter when passed an OutputStream. The encoding used will depend on the value of the `encoding` property. If the encoding value is specified incorrectly the writer will be opened using the default system encoding (an error message will be printed to the loglog.
      Overrides:
        `createWriter` in class `org.apache.log4j.WriterAppender`
      Parameters:
        `os` - output stream, may not be null.
      Returns:
        new writer.

    - #### getFileLength

          public long getFileLength()

      Get byte length of current active log file.
      Returns:
        byte length of current active log file.

    - #### incrementFileLength

          public void incrementFileLength(int increment)

      Increments estimated byte length of current active log file.
      Parameters:
        `increment` - additional bytes written to log file.

    - #### parseUnrecognizedElement

          public boolean parseUnrecognizedElement(Element element,
                                         Properties props)
                                           throws Exception

      Specified by:
        `parseUnrecognizedElement` in interface `org.apache.log4j.xml.UnrecognizedElementHandler`
      Throws:
        `Exception`

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.