Log4j 0.9.1

org.log4j
Class FileAppender

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

public class FileAppender
extends AppenderSkeleton

FileAppender appends log events to the console, to a file, to a Writer or an OutputStream depending on the user's choice.

Since:
version 0.7.1
Author:
Ceki Gülcü

Field Summary
static String APPEND_OPTION
          A string constant used in naming the option that determines whether the output file will be truncated or appended to.
static String FILE_OPTION
          A string constant used in naming the option for setting the output file.
protected  boolean fileAppend
          Append to or truncate the file? The default value for this variable is true, meaning that by default a FileAppender will append to an existing file and not truncate it.
protected  String fileName
          The name of the log file.
static String IMMEDIATE_FLUSH_OPTION
          A string constant used in naming the option for immediate flushing of the output stream at the end of each append operation.
protected  boolean immediateFlush
          Immediate flush means that the undelying writer or stream will be flushed at the end of each append operation.
protected  QuietWriter qw
          This is the quietWriter where we will write to.
protected  boolean qwIsOurs
          Is the QuietWriter ours or was it created and passed by the user?
protected  TracerPrintWriter tp
          TracerPrintWriter is specialized in optimized printing of stack traces (obtained from throwables) to a Writer.
 
Fields inherited from class org.log4j.AppenderSkeleton
closed, errorHandler, headFilter, layout, name, tailFilter, threshold, THRESHOLD_OPTION
 
Constructor Summary
FileAppender()
          The default constructor does no longer set a default layout nor a default output target.
FileAppender(Layout layout, OutputStream os)
          Instantiate a FileAppender and set the output destination to a new OutputStreamWriter initialized with os as its OutputStream.
FileAppender(Layout layout, String filename)
          Instantiate a FileAppender and open the file designated by filename.
FileAppender(Layout layout, String filename, boolean append)
          Instantiate a FileAppender and open the file designated by filename.
FileAppender(Layout layout, Writer writer)
          Instantiate a FileAppender and set the output destination to writer.
 
Method Summary
 void activateOptions()
          If the a value for FILE_OPTION is non-null, then setFile(java.lang.String, boolean) is called with the values of FILE_OPTION and APPEND_OPTION.
 void append(LoggingEvent event)
          This method called by AppenderSkeleton.doAppend(org.log4j.spi.LoggingEvent) method.
protected  boolean checkEntryConditions()
          This method determines if there is a sense in attempting to append.
 void close()
          Will close the stream opened by a previos setFile(java.lang.String, boolean) call.
protected  void closeWriterIfOurs()
          Close this.writer if opened by setFile or FileAppend(filename..)
 String[] getOptionStrings()
          Retuns the option names for this component, namely the string array {FILE_OPTION, APPEND_OPTION} in addition to the options of its super class AppenderSkeleton.
 boolean requiresLayout()
          The FileAppender requires a layout.
protected  void reset()
           
 void setErrorHandler(ErrorHandler eh)
          Set the ErrorHandler for this FileAppender and also the undelying QuietWriter if any.
 void setFile(String fileName)
          Sets and opens the file where the log output will go.
 void setFile(String fileName, boolean append)
          Sets and opens the file where the log output will go.
 void setOption(String key, String value)
          Set FileAppender specific options.
protected  void setQWForFiles(Writer writer)
           
 void setWriter(Writer writer)
          Sets the Writer where the log output will go.
protected  void subAppend(LoggingEvent event)
          Actual writing occurs here.
 
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

FILE_OPTION

public static final String FILE_OPTION
A string constant used in naming the option for setting the output file. Current value of this string constant is File.

Note that all option keys are case sensitive.


IMMEDIATE_FLUSH_OPTION

public static final String IMMEDIATE_FLUSH_OPTION
A string constant used in naming the option for immediate flushing of the output stream at the end of each append operation. Current value of this string constant is ImmediateFlush.

Note that all option keys are case sensitive.

Since:
0.9.1

APPEND_OPTION

public static final String APPEND_OPTION
A string constant used in naming the option that determines whether the output file will be truncated or appended to. Current value of this string constant is Append.

Note that all option keys are case sensitive.


fileAppend

protected boolean fileAppend
Append to or truncate the file? The default value for this variable is true, meaning that by default a FileAppender will append to an existing file and not truncate it.

This option is meaningful only if the FileAppender opens the file.


immediateFlush

protected boolean immediateFlush
Immediate flush means that the undelying writer or stream will be flushed at the end of each append operation. Immediate flush is slower but ensures that each append request is actually written. If immediateFlush is set to false, then there is a good chance that the last few logs events are not actually written to persistent media when the application crashes.

The immediateFlush variable is set to true by default.

Since:
0.9.1

qw

protected QuietWriter qw
This is the quietWriter where we will write to.

tp

protected TracerPrintWriter tp
TracerPrintWriter is specialized in optimized printing of stack traces (obtained from throwables) to a Writer.

fileName

protected String fileName
The name of the log file.

qwIsOurs

protected boolean qwIsOurs
Is the QuietWriter ours or was it created and passed by the user?
Constructor Detail

FileAppender

public FileAppender()
The default constructor does no longer set a default layout nor a default output target.

FileAppender

public FileAppender(Layout layout,
                    OutputStream os)
Instantiate a FileAppender and set the output destination to a new OutputStreamWriter initialized with os as its OutputStream.

FileAppender

public FileAppender(Layout layout,
                    Writer writer)
Instantiate a FileAppender and set the output destination to writer.

The writer must have been opened by the user.


FileAppender

public FileAppender(Layout layout,
                    String filename,
                    boolean append)
             throws IOException
Instantiate a FileAppender 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.


FileAppender

public FileAppender(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

activateOptions

public void activateOptions()
If the a value for FILE_OPTION is non-null, then setFile(java.lang.String, boolean) is called with the values of FILE_OPTION and APPEND_OPTION.
Overrides:
activateOptions in class AppenderSkeleton
Since:
0.8.1

append

public void append(LoggingEvent event)
This method called by AppenderSkeleton.doAppend(org.log4j.spi.LoggingEvent) method.

If the output stream exists an is writable then write a log statement to the output stream. Otherwise, write a single warning message to System.err.

The format of the output will depend on this appender's layout.

Overrides:
append in class AppenderSkeleton

checkEntryConditions

protected boolean checkEntryConditions()
This method determines if there is a sense in attempting to append.

It checks whether there is a set output target and also if there is a set layout. If these checks fail, then the boolean value false is returned.


close

public void close()
Will close the stream opened by a previos setFile(java.lang.String, boolean) call. If the writer is owned by the user it remains untouched.
Since:
0.8.4
See Also:
setFile(java.lang.String, boolean), setWriter(java.io.Writer)

closeWriterIfOurs

protected void closeWriterIfOurs()
Close this.writer if opened by setFile or FileAppend(filename..)

getOptionStrings

public String[] getOptionStrings()
Retuns the option names for this component, namely the string array {FILE_OPTION, APPEND_OPTION} in addition to the options of its super class AppenderSkeleton.
Overrides:
getOptionStrings in class AppenderSkeleton

setErrorHandler

public void setErrorHandler(ErrorHandler eh)
Set the ErrorHandler for this FileAppender and also the undelying QuietWriter if any.
Overrides:
setErrorHandler in class AppenderSkeleton

setFile

public void setFile(String fileName,
                    boolean append)
             throws IOException

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.

Parameters:
fileName - The path to the log file.
boolean - If true will append to fileName. Otherwise will truncate fileName.

setFile

public void setFile(String fileName)
             throws IOException

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

The open mode (append/truncate) will depend on the value of FileAppend option. If undefined, append mode is used.

Parameters:
fileName - The name of the log file.

setOption

public void setOption(String key,
                      String value)
Set FileAppender specific options. The recognized options are File and Append, i.e. the values of the string constants FILE_OPTION and respectively APPEND_OPTION. The options of the super class AppenderSkeleton are also recognized.

The File option takes a string value which should be one of the strings "System.out" or "System.err" or the name of a file.

If the option is set to "System.out" or "System.err" the output will go to the corresponding stream. Otherwise, if the option is set to the name of a file, then the file will be opened and output will go there.

The File option admits variable substitution. For example, if java.home system property is set to /home/xyz and the File option is set to the string ${java.home}/test.log, then File option will be interpreted as the string /home/xyz/test.log.

The syntax of variable substituion is similar to that of UNIX shells. The string between an opening "${" and closing "}" is interpreted as a key. Its value is searched in the system properties and the corresponding value replaces the ${var} sequence. See also OptionConverter.substituteVars(java.lang.String).

The Append option takes a boolean value. It is set to true by default. If true, then File will be opened in append mode by setFile (see above). Otherwise, setFile will open File in truncate mode.

Note: Actual opening of the file is made when activateOptions() is called, not when the options are set.

Overrides:
setOption in class AppenderSkeleton
Since:
0.8.1

setWriter

public void setWriter(Writer writer)

Sets the Writer where the log output will go. The specified Writer must be opened by the user and be writable.

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

WARNING: Logging to an unopened Writer will fail.

Parameters:
Writer - An already opened Writer.
Returns:
Writer The previously attached Writer.

setQWForFiles

protected void setQWForFiles(Writer writer)

subAppend

protected void subAppend(LoggingEvent event)
Actual writing occurs here.

Most sub-classes of FileAppender will need to override this method.

Since:
0.9.0

requiresLayout

public boolean requiresLayout()
The FileAppender requires a layout. Hence, this method returns true.
Since:
0.8.4

reset

protected void reset()

Log4j 0.9.1

Please notify me about new log4j releases.