Log4j 0.9.1

org.log4j
Class RollingFileAppender

java.lang.Object
  |
  +--org.log4j.AppenderSkeleton
        |
        +--org.log4j.FileAppender
              |
              +--org.log4j.RollingFileAppender
All Implemented Interfaces:
Appender, OptionHandler
Direct Known Subclasses:
ExternallyRolledFileAppender

public class RollingFileAppender
extends FileAppender

RollingFileAppender extends FileAppender to backup the log files when they reach a certain size.

Since:
version 0.8.1
Author:
Heinz Richter, Ceki Gülcü

Field Summary
static String MAX_BACKUP_INDEX_OPTION
          A string constant used in naming the option for setting the the number of backup files to retain.
static String MAX_FILE_SIZE_OPTION
          A string constant used in naming the option for setting the maximum size of the log file.
protected  int maxBackupIndex
          There is one backup file by default.
protected  long maxFileSize
          The default maximum file size is 10MB.
 
Fields inherited from class org.log4j.FileAppender
APPEND_OPTION, FILE_OPTION, fileAppend, fileName, IMMEDIATE_FLUSH_OPTION, immediateFlush, qw, qwIsOurs, tp
 
Fields inherited from class org.log4j.AppenderSkeleton
closed, errorHandler, headFilter, layout, name, tailFilter, threshold, THRESHOLD_OPTION
 
Constructor Summary
RollingFileAppender()
          The default constructor simply calls its parents constructor.
RollingFileAppender(Layout layout, OutputStream os)
          Deprecated. This constructor does not allow to roll files and will disappear in the near future.
RollingFileAppender(Layout layout, String filename)
          Instantiate a FileAppender and open the file designated by filename.
RollingFileAppender(Layout layout, String filename, boolean append)
          Instantiate a RollingFileAppender and open the file designated by filename.
RollingFileAppender(Layout layout, Writer writer)
          Deprecated. This constructor does not allow to roll files and will disappear in the near future.
 
Method Summary
 String[] getOptionStrings()
          Retuns the option names for this component, namely MAX_FILE_SIZE_OPTION and MAX_BACKUP_INDEX_OPTION in addition to the options of FileAppender.
 void rollOver()
          Implemetns the usual roll over behaviour.
 void setFile(String fileName, boolean append)
          Sets and opens the file where the log output will go.
 void setMaxBackupIndex(int maxBackups)
          Set the maximum number of backup files to keep around.
 void setMaxFileSize(long maxFileSize)
          Set the maximum size that the output file is allowed to reach before being rolled over.
 void setOption(String key, String value)
          Set RollingFileAppender specific options.
protected  void setQWForFiles(Writer writer)
           
protected  void subAppend(LoggingEvent event)
          This method differentiates RollingFileAppender from its super class.
 
Methods inherited from class org.log4j.FileAppender
activateOptions, append, checkEntryConditions, close, closeWriterIfOurs, requiresLayout, reset, setErrorHandler, setFile, setWriter
 
Methods inherited from class org.log4j.AppenderSkeleton
addFilter, clearFilters, doAppend, finalize, getErrorHandler, getFirstFilter, getName, isAsSevereAsThreshold, setLayout, setName, setThreshold
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MAX_FILE_SIZE_OPTION

public static final String MAX_FILE_SIZE_OPTION
A string constant used in naming the option for setting the maximum size of the log file. Current value of this string constant is MaxFileSize.

MAX_BACKUP_INDEX_OPTION

public static final String MAX_BACKUP_INDEX_OPTION
A string constant used in naming the option for setting the the number of backup files to retain. Current value of this string constant is MaxBackupIndex.

maxFileSize

protected long maxFileSize
The default maximum file size is 10MB.

maxBackupIndex

protected int maxBackupIndex
There is one backup file by default.
Constructor Detail

RollingFileAppender

public RollingFileAppender()
The default constructor simply calls its parents constructor.

RollingFileAppender

public RollingFileAppender(Layout layout,
                           OutputStream os)
Deprecated. This constructor does not allow to roll files and will disappear in the near future.

Instantiate a RollingFileAppender and set the output destination to a new OutputStreamWriter initialized with os as its OutputStream.

RollingFileAppender

public RollingFileAppender(Layout layout,
                           Writer writer)
Deprecated. This constructor does not allow to roll files and will disappear in the near future.

Instantiate a RollingFileAppender and set the output destination to writer.

The writer must have been opened by the user.


RollingFileAppender

public RollingFileAppender(Layout layout,
                           String filename,
                           boolean append)
                    throws IOException
Instantiate a RollingFileAppender and open the file designated by filename. The opened filename will become the ouput destination for this appender.

If the append parameter is true, the file will be appended to. Otherwise, the file desginated by filename will be truncated before being opened.


RollingFileAppender

public RollingFileAppender(Layout layout,
                           String filename)
                    throws IOException
Instantiate a FileAppender and open the file designated by filename. The opened filename will become the output destination for this appender.

The file will be appended to.

Method Detail

getOptionStrings

public String[] getOptionStrings()
Retuns the option names for this component, namely MAX_FILE_SIZE_OPTION and MAX_BACKUP_INDEX_OPTION in addition to the options of FileAppender.
Overrides:
getOptionStrings in class FileAppender

setFile

public void setFile(String fileName,
                    boolean append)
             throws IOException
Description copied from class: FileAppender

Sets and opens the file where the log output will go. The specified file must be writable.

If there was already an opened stream opened through this method, then the previous stream is closed first. If the stream was opened by the user and passed to setWriter, then the previous stream remains untouched. It is the users responsability to close it.

Overrides:
setFile in class FileAppender
Following copied from class: org.log4j.FileAppender
Parameters:
fileName - The path to the log file.
boolean - If true will append to fileName. Otherwise will truncate fileName.

rollOver

public void rollOver()
Implemetns 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.


setMaxBackupIndex

public void setMaxBackupIndex(int maxBackups)
Set the maximum number of backup files to keep around.

setMaxFileSize

public void setMaxFileSize(long maxFileSize)
Set the maximum size that the output file is allowed to reach before being rolled over.

setOption

public void setOption(String key,
                      String value)
Set RollingFileAppender specific options. In addition to FileAppender options RollingFileAppender recognizes the options MaxFileSize and MaxBackupIndex.

The MaxFileSize determines the size of log file before it is rolled over to backup files. This option takes an long integer in the range 0 - 2^63. You can specify the value with the suffixes "KB", "MB" or "GB" so that the integer is interpreted being expressed respectively in kilobytes, megabytes or gigabytes. For example, the value "10KB" will be interpreted as 10240.

The MaxBackupIndex option determines how many backup files are kept before the oldest being erased. This option takes a positive integer value. If set to zero, then there will be no backup files and the log file will be truncated when it reaches MaxFileSize.

Overrides:
setOption in class FileAppender

setQWForFiles

protected void setQWForFiles(Writer writer)
Overrides:
setQWForFiles in class FileAppender

subAppend

protected void subAppend(LoggingEvent event)
This method differentiates RollingFileAppender from its super class.
Overrides:
subAppend in class FileAppender
Since:
0.9.0

Log4j 0.9.1

Please notify me about new log4j releases.