org.stanwood.media.logging
Class StreamAppender

java.lang.Object
  extended by org.apache.log4j.AppenderSkeleton
      extended by org.stanwood.media.logging.StreamAppender
All Implemented Interfaces:
org.apache.log4j.Appender, org.apache.log4j.spi.OptionHandler

public class StreamAppender
extends org.apache.log4j.AppenderSkeleton

The StreamAppender will log events Streams. Error and Fatal level events will be sent to a error stream, and the other levels to the output stream. By default, the error and output streams are set to use the console streams.


Field Summary
protected  boolean immediateFlush
          Immediate flush means that the underlying writer or output stream will be flushed at the end of each append operation.
 
Fields inherited from class org.apache.log4j.AppenderSkeleton
closed, errorHandler, headFilter, layout, name, tailFilter, threshold
 
Constructor Summary
StreamAppender()
          This default constructor does nothing.
StreamAppender(org.apache.log4j.Layout layout)
          Creates a configured appender using the console streams.
StreamAppender(org.apache.log4j.Layout layout, java.io.PrintStream outputStream, java.io.PrintStream errorStream)
          Creates a configured appender using the given streams.
 
Method Summary
 void activateOptions()
          Prepares the appender for use.
 void append(org.apache.log4j.spi.LoggingEvent event)
          This method is called by the AppenderSkeleton.doAppend(org.apache.log4j.spi.LoggingEvent) method.
protected  boolean checkEntryConditions()
          This method determines if there is a sense in attempting to append.
 void close()
          Close this appender instance.
protected  void closeStreams()
          Close the underlying streams
 boolean getImmediateFlush()
          Returns value of the ImmediateFlush option.
 boolean isPrintStackTrace()
          Returns true if stack traces should be printed to the log
 boolean requiresLayout()
          The WriterAppender requires a layout.
protected  void reset()
          Clear internal references to the writer and other variables.
 void setImmediateFlush(boolean value)
          If the ImmediateFlush option is set to true, the appender will flush at the end of each write.
 void setPrintStackTrace(boolean printStackTrace)
          If this is set to true, the stack traces will be printed
protected  void subAppend(org.apache.log4j.spi.LoggingEvent event)
          Actual writing occurs here.
protected  void writeFooter()
          Write a footer as produced by the embedded layout's Layout.getFooter() method.
protected  void writeHeader()
          Write a header as produced by the embedded layout's Layout.getHeader() method.
 
Methods inherited from class org.apache.log4j.AppenderSkeleton
addFilter, clearFilters, doAppend, finalize, getErrorHandler, getFilter, getFirstFilter, getLayout, getName, getThreshold, isAsSevereAsThreshold, setErrorHandler, setLayout, setName, setThreshold
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

immediateFlush

protected boolean immediateFlush
Immediate flush means that the underlying writer or output 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 if and when the application crashes.

The immediateFlush variable is set to true by default.

Constructor Detail

StreamAppender

public StreamAppender()
This default constructor does nothing.


StreamAppender

public StreamAppender(org.apache.log4j.Layout layout)
Creates a configured appender using the console streams.

Parameters:
layout - The layout to use.

StreamAppender

public StreamAppender(org.apache.log4j.Layout layout,
                      java.io.PrintStream outputStream,
                      java.io.PrintStream errorStream)
Creates a configured appender using the given streams.

Parameters:
layout - The layout to use.
outputStream - The output stream to use
errorStream - The error stream to use
Method Detail

setImmediateFlush

public void setImmediateFlush(boolean value)
If the ImmediateFlush option is set to true, the appender will flush at the end of each write. This is the default behaviour. If the option is set to false, then the underlying stream can defer writing to physical medium to a later time.

Avoiding the flush operation at the end of each append results in a performance gain of 10 to 20 percent. However, there is safety tradeoff involved in skipping flushing. Indeed, when flushing is skipped, then it is likely that the last few log events will not be recorded on disk when the application exits. This is a high price to pay even for a 20% performance gain.

Parameters:
value - True to enable immediate flush, otherwise false.

getImmediateFlush

public boolean getImmediateFlush()
Returns value of the ImmediateFlush option.

Returns:
True if immediate flush is enabled, otherwise false.

activateOptions

public void activateOptions()
Prepares the appender for use.

Specified by:
activateOptions in interface org.apache.log4j.spi.OptionHandler
Overrides:
activateOptions in class org.apache.log4j.AppenderSkeleton

append

public void append(org.apache.log4j.spi.LoggingEvent event)

This method is called by the AppenderSkeleton.doAppend(org.apache.log4j.spi.LoggingEvent) method.

This will write ERROR and FATAL messages to the error stream and the other levels to the output stream. If it is unable to write to the stream, then a single warning message is written to System.err.

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

Specified by:
append in class org.apache.log4j.AppenderSkeleton
Parameters:
event - The event to log

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.

Returns:
true if message should be appended, otherwise false

close

public void close()
Close this appender instance. The underlying stream or writer is also closed.

Closed appenders cannot be reused.


closeStreams

protected void closeStreams()
Close the underlying streams


subAppend

protected void subAppend(org.apache.log4j.spi.LoggingEvent event)
Actual writing occurs here.

Most subclasses of WriterAppender will need to override this method.

Parameters:
event - The logging event

requiresLayout

public boolean requiresLayout()
The WriterAppender requires a layout. Hence, this method returns true.

Returns:
Always returns true.

reset

protected void reset()
Clear internal references to the writer and other variables. Subclasses can override this method for an alternate closing behavior.


writeFooter

protected void writeFooter()
Write a footer as produced by the embedded layout's Layout.getFooter() method.


writeHeader

protected void writeHeader()
Write a header as produced by the embedded layout's Layout.getHeader() method.


isPrintStackTrace

public boolean isPrintStackTrace()
Returns true if stack traces should be printed to the log

Returns:
true if stack traces should be printed to the log

setPrintStackTrace

public void setPrintStackTrace(boolean printStackTrace)
If this is set to true, the stack traces will be printed

Parameters:
printStackTrace - set to true, the stack traces will be printed