FileDocCategorySizeDatePackage
DatagramStringAppender.javaAPI DocApache log4j 1.2.159729Sat Aug 25 00:09:34 BST 2007org.apache.log4j.net

DatagramStringAppender

public class DatagramStringAppender extends AppenderSkeleton
Use DatagramStringAppender to send log messages to a remote daemon which accepts Datagram (UDP) messages.

The benefits of UDP are that the client is guarunteed not to slow down if the network or remote log daemon is slow, and that no permanent TCP connection between client and server exists.

The disadvantages are that log messages can be lost if the network or remote daemon are under excessive load.

This class builts the final message string before sending the UDP packet, hence the "string" component in the class name. This means that the receiving application can be written in any language. The data is transmitted in whatever encoding is specified in the configuration file; this may be an 8-bit encoding (eg ISO-8859-1, also known as LATIN-1) or a larger encoding, eg UTF-16.

An alternative to building the message string within DatagramStringAppender would be to serialize & send the complete logging event object (perhaps such a class could be called a DatagramSerialAppender??). The receiving end could then be configured with appropriate Layout objects to generate the actual logged messages. This would ensure that the logging of messages from different sources is done in a consistent format, and give a central place to configure that format. It would ensure (by transmitting messages as unicode) that the receiving end could control the encoding in which the output is generated. It also would possibly allow he receiving end to use the full log4j flexibility to pass the event to different appenders at the receiving end, as the category information is retained, etc. However, this does require that the receiving end is in java, and that all clients of the logging daemon are java applications. In contrast, this DatagramStringAppender can send mesages to a log daemon that accepts messages from a variety of sources.

author
Simon Kitching

Fields Summary
public static final String
DATAGRAM_HOST_OPTION
A string constant used in naming the option for setting the destination server for messages. Current value of this string constant is DatagramHost.
public static final String
DATAGRAM_PORT_OPTION
A string constant used in naming the option for setting the destination port for messages. Current value of this string constant is DatagramPort.
public static final String
DATAGRAM_ENCODING_OPTION
A string constant used in naming the option for setting the character encoding used when generating the log message. Current value of this string constant is DatagramEncoding.
public static final String
DEFAULT_HOST
The default value for the "host" attribute, ie the machine to which messages are sent. Current value of this string constant is localhost.
public static final int
DEFAULT_PORT
The default value for the "port" attribute, ie the UDP port to which messages are sent. Current value of this integer constant is 8200. This value was chosen for no particular reason.
public static final String
DEFAULT_ENCODING
The default value for the "encoding" attribute, ie the way in which unicode message strings are converted into a stream of bytes before their transmission as a UDP packet. The current value of this constant is null, which means that the default platform encoding will be used.
String
host
int
port
String
encoding
org.apache.log4j.helpers.SingleLineTracerPrintWriter
stp
QuietWriter
qw
Constructors Summary
public DatagramStringAppender()


  
   
    this.setDestination(DEFAULT_HOST, DEFAULT_PORT, DEFAULT_ENCODING);
public DatagramStringAppender(Layout layout)

    this.setLayout(layout);
    this.setDestination(DEFAULT_HOST, DEFAULT_PORT, DEFAULT_ENCODING);
public DatagramStringAppender(Layout layout, String host, int port)

    this.setLayout(layout);
    this.setDestination(host, port, DEFAULT_ENCODING);
public DatagramStringAppender(Layout layout, String host, int port, String encoding)

    this.setLayout(layout);
    this.setDestination(host, port, encoding);
Methods Summary
public voidactivateOptions()
Activate the options set via the setOption method.

see
#setOption

    this.setDestination(this.host, this.port, this.encoding);
public voidappend(org.apache.log4j.spi.LoggingEvent event)

    if(!isAsSevereAsThreshold(event.priority))
      return;

    // We must not attempt to append if qw is null.
    if(qw == null) {
      errorHandler.error(
        "No host is set for DatagramStringAppender named \""
        +	this.name + "\".");
      return;
    }

    String buffer = layout.format(event);
    qw.write(buffer);

    if(event.throwable != null)
      event.throwable.printStackTrace(stp);
    else if (event.throwableInformation != null) {
      // we must be the receiver of a serialized/deserialized LoggingEvent;
      // the event's throwable member is transient, ie becomes null when
      // deserialized, but that's ok because throwableInformation should
      // have the string equivalent of the same info (ie stack trace)
      qw.write(event.throwableInformation);
    }
public voidclose()
Release any resources held by this Appender

    closed = true;
    // A DatagramWriter is UDP based and needs no opening. Hence, it
    // can't be closed. We just unset the variables here.
    qw = null;
    stp = null;
public java.lang.String[]getOptionStrings()
Returns the option names for this component, namely the string array consisting of {{@link #DATAGRAM_HOST_OPTION}, {@link #DATAGRAM_PORT_OPTION}, {@link #DATAGRAM_ENCODING_OPTION}

    return OptionConverter.concatanateArrays(super.getOptionStrings(),
		      new String[] {
            DATAGRAM_HOST_OPTION,
            DATAGRAM_PORT_OPTION,
            DATAGRAM_ENCODING_OPTION});
public booleanrequiresLayout()
The DatagramStringAppender requires a layout. Hence, this method return true.

since
0.8.4

    return true;
public voidsetDestination(java.lang.String host, int port, java.lang.String encoding)

    if (host==null) {
      LogLog.error("setDestination: host is null");
      host = DEFAULT_HOST;
    }
    
    this.host = host;
    this.port = port;
    this.encoding = encoding;

    this.qw = new QuietWriter(
        new DatagramStringWriter(host, port, encoding),
        errorHandler);
    this.stp = new SingleLineTracerPrintWriter(qw);
public voidsetLayout(org.apache.log4j.Layout layout)

    this.layout = layout;
public voidsetOption(java.lang.String option, java.lang.String value)
Set DatagramStringAppender specific parameters.

The recognized options are DatagramHost, DatagramPort and DatagramEncoding, i.e. the values of the string constants {@link #DATAGRAM_HOST_OPTION}, {@link #DATAGRAM_PORT_OPTION} and {@link #DATAGRAM_ENCODING_OPTION} respectively.

DatagramHost
The name (or ip address) of the host machine where log output should go. If the DatagramHost is not set, then this appender will default to {@link #DEFAULT_HOST}.

DatagramPort
The UDP port number where log output should go. See {@link #DEFAULT_PORT}

DatagramEncoding
The ISO character encoding to be used when converting the Unicode message to a sequence of bytes within a UDP packet. If not defined, then the encoding defaults to the default platform encoding. 

    if(value == null) return;

    super.setOption(option, value);

    if(option.equals(DATAGRAM_HOST_OPTION))
    {
      this.host = value;
    }
    else if(option.equals(DATAGRAM_PORT_OPTION))
    {
      this.port = OptionConverter.toInt(value, DEFAULT_PORT);
    }
    else if(option.equals(DATAGRAM_ENCODING_OPTION))
    {
      this.encoding = value;
    }