org.apache.log4j.rolling
Class RollingFileAppender

java.lang.Object
  extended by org.apache.log4j.AppenderSkeleton
      extended by org.apache.log4j.WriterAppender
          extended by org.apache.log4j.FileAppender
              extended by org.apache.log4j.rolling.RollingFileAppender
All Implemented Interfaces:
org.apache.log4j.Appender, org.apache.log4j.spi.OptionHandler, UnrecognizedElementHandler

public final class RollingFileAppender
extends org.apache.log4j.FileAppender
implements 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
RollingFileAppender()
          Construct a new instance.
 
Method Summary
 void activateOptions()
          Prepare instance of use.
 void close()
          Close appender.
protected  java.io.OutputStreamWriter createWriter(java.io.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(org.w3c.dom.Element element, java.util.Properties props)
          Called to inform a configured object when an unrecognized child element is encountered.
 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 java.io.OutputStreamWriter createWriter(java.io.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(org.w3c.dom.Element element,
                                        java.util.Properties props)
                                 throws java.lang.Exception
Called to inform a configured object when an unrecognized child element is encountered.

Specified by:
parseUnrecognizedElement in interface UnrecognizedElementHandler
Parameters:
element - element, may not be null.
props - properties in force, may be null.
Returns:
true if configured object recognized the element
Throws:
java.lang.Exception - throw an exception to prevent activation of the configured object.


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

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