Log4j 1.1.3

org.apache.log4j
Class AsyncAppender

java.lang.Object
  |
  +--org.apache.log4j.AppenderSkeleton
        |
        +--org.apache.log4j.AsyncAppender
All Implemented Interfaces:
Appender, AppenderAttachable, OptionHandler

public class AsyncAppender
extends AppenderSkeleton
implements AppenderAttachable

The AsyncAppender lets users log events asynchronously. It uses a bounded buffer to store logging events.

The AsyncAppender will collect the events sent to it and then dispatch them to all the appenders that are attached to it. You can attach multiple appenders to an AsyncAppender.

The AsyncAppender uses a separate thread to serve the events in its bounded buffer.

Refer to the results in Logging for the impact of using this appender.

Important note: The AsyncAppender can only be script configured using the DOMConfigurator. Refer to example configuration files sample4.xml and sample5.xml.

Since:
version 0.9.1
Author:
Ceki Gülcü

Field Summary
static String BUFFER_SIZE_OPTION
          Deprecated. Options are now handled using the JavaBeans paradigm. This constant is not longer needed and will be removed in the near term.
static int DEFAULT_BUFFER_SIZE
          The default buffer size is set to 128 events.
static String LOCATION_INFO_OPTION
          Deprecated. Options are now handled using the JavaBeans paradigm. This constant is not longer needed and will be removed in the near term.
 
Fields inherited from class org.apache.log4j.AppenderSkeleton
closed, errorHandler, headFilter, layout, name, tailFilter, threshold, THRESHOLD_OPTION
 
Constructor Summary
AsyncAppender()
           
 
Method Summary
 void addAppender(Appender newAppender)
          Add an appender.
 void append(LoggingEvent event)
          Subclasses of AppenderSkeleton should implement this method to perform actual logging.
 void close()
          Close this AsyncAppender by interrupting the dispatcher thread which will process all pending events before exiting.
 Enumeration getAllAppenders()
          Get all previously added appenders as an Enumeration.
 Appender getAppender(String name)
          Get an appender by name.
 int getBufferSize()
          Returns the current value of the BufferSize option.
 boolean getLocationInfo()
          Returns the current value of the LocationInfo option.
 String[] getOptionStrings()
          Deprecated. We now use JavaBeans introspection to configure components. Options strings are no longer needed.
 void removeAllAppenders()
          Remove all previously added appenders.
 void removeAppender(Appender appender)
          Remove the appender passed as parameter from the list of appenders.
 void removeAppender(String name)
          Remove the appender with the name passed as parameter from the list of appenders.
 boolean requiresLayout()
          The AsyncAppender does not require a layout.
 void setBufferSize(int size)
          The BufferSize option takes a non-negative integer value.
 void setLocationInfo(boolean flag)
          The LocationInfo option takes a boolean value.
 void setOption(String option, String value)
          Deprecated. Use the setter method for the option directly instead of the generic setOption method.
 
Methods inherited from class org.apache.log4j.AppenderSkeleton
activateOptions, 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

LOCATION_INFO_OPTION

public static final String LOCATION_INFO_OPTION
Deprecated. Options are now handled using the JavaBeans paradigm. This constant is not longer needed and will be removed in the near term.

A string constant used in naming the option for setting the location information flag. Current value of this string constant is LocationInfo.

Note that all option keys are case sensitive.


BUFFER_SIZE_OPTION

public static final String BUFFER_SIZE_OPTION
Deprecated. Options are now handled using the JavaBeans paradigm. This constant is not longer needed and will be removed in the near term.

A string constant used in naming the option for setting the size of the internal buffer where logging events are stored until they are written. Current value of this string constant is BufferSize.

Note that all option keys are case sensitive.


DEFAULT_BUFFER_SIZE

public static final int DEFAULT_BUFFER_SIZE
The default buffer size is set to 128 events.
Constructor Detail

AsyncAppender

public AsyncAppender()
Method Detail

addAppender

public void addAppender(Appender newAppender)
Description copied from interface: AppenderAttachable
Add an appender.
Specified by:
addAppender in interface AppenderAttachable

append

public void append(LoggingEvent event)
Description copied from class: AppenderSkeleton
Subclasses of AppenderSkeleton should implement this method to perform actual logging. See also AppenderSkeleton.doAppend method.
Overrides:
append in class AppenderSkeleton

close

public void close()
Close this AsyncAppender by interrupting the dispatcher thread which will process all pending events before exiting.

getAllAppenders

public Enumeration getAllAppenders()
Description copied from interface: AppenderAttachable
Get all previously added appenders as an Enumeration.
Specified by:
getAllAppenders in interface AppenderAttachable

getAppender

public Appender getAppender(String name)
Description copied from interface: AppenderAttachable
Get an appender by name.
Specified by:
getAppender in interface AppenderAttachable

getLocationInfo

public boolean getLocationInfo()
Returns the current value of the LocationInfo option.

requiresLayout

public boolean requiresLayout()
The AsyncAppender does not require a layout. Hence, this method always returns false.

removeAllAppenders

public void removeAllAppenders()
Description copied from interface: AppenderAttachable
Remove all previously added appenders.
Specified by:
removeAllAppenders in interface AppenderAttachable

removeAppender

public void removeAppender(Appender appender)
Description copied from interface: AppenderAttachable
Remove the appender passed as parameter from the list of appenders.
Specified by:
removeAppender in interface AppenderAttachable

removeAppender

public void removeAppender(String name)
Description copied from interface: AppenderAttachable
Remove the appender with the name passed as parameter from the list of appenders.
Specified by:
removeAppender in interface AppenderAttachable

setLocationInfo

public void setLocationInfo(boolean flag)
The LocationInfo option takes a boolean value. By default, it is set to false which means there will be no effort to extract the location information related to the event. As a result, the event that will be ultimately logged will likely to contain the wrong location information (if present in the log format).

Location information extraction is comparatively very slow and should be avoided unless performance is not a concern.


setBufferSize

public void setBufferSize(int size)
The BufferSize option takes a non-negative integer value. This integer value determines the maximum size of the bounded buffer. Increasing the size of the buffer is always safe. However, if an existing buffer holds unwritten elements, then decreasing the buffer size will result in event loss. Nevertheless, while script configuring the AsyncAppender, it is safe to set a buffer size smaller than the default buffer size because configurators guarantee that an appender cannot be used before being completely configured.

getBufferSize

public int getBufferSize()
Returns the current value of the BufferSize option.

getOptionStrings

public String[] getOptionStrings()
Deprecated. We now use JavaBeans introspection to configure components. Options strings are no longer needed.

Returns the option names for this component in addition in addition to the options of its super class AppenderSkeleton.
Overrides:
getOptionStrings in class AppenderSkeleton

setOption

public void setOption(String option,
                      String value)
Deprecated. Use the setter method for the option directly instead of the generic setOption method.

Set AsyncAppender specific options:

On top of the options of the super class AppenderSkeleton, the only recognized options are BufferSize and LocationInfo.

The BufferSize option takes a non-negative integer value. This integer value determines the maximum size of the bounded buffer. Increasing the size of the buffer is always safe. However, if an existing buffer holds unwritten elements, then decreasing the buffer size will result in event loss. Nevertheless, while script configuring the AsyncAppender, it is safe to set a buffer size smaller than the default buffer size because configurators guarantee that an appender cannot be used before being completely configured.

The LocationInfo option takes a boolean value. By default, it is set to false which means there will be no effort to extract the location information related to the event. As a result, the event that will be ultimately logged will likely to contain the wrong location information (if present in the log format).

Location information extraction is comparatively very slow and should be avoided unless performance is not a concern.

Overrides:
setOption in class AppenderSkeleton

Log4j 1.1.3

Please notify me about new log4j releases.