Log4j 1.3alpha-1

org.apache.log4j.spi
Class LoggingEvent

java.lang.Object
  |
  +--org.apache.log4j.spi.LoggingEvent
All Implemented Interfaces:
java.io.Serializable

public class LoggingEvent
extends java.lang.Object
implements java.io.Serializable

The internal representation of logging events. When an affirmative decision is made to log then a LoggingEvent instance is created. This instance is passed around to the different log4j components.

This class is of concern to those wishing to extend log4j.

Writers of log4j components such as appenders and receivers should be aware of that some of the LoggingEvent fields are initialized lazily. Therefore, an appender wishing to output data to be later correctly read by a receiver, must initialize "lazy" fields prior to writing them out. See the prepareForDeferredProcessing() method for the exact list.

Moreover, in the absence of certain fields, receivers must set the values of null fields to a default non-null value. For example, in the absence of the locationInfo data, the locationInfo field should be set to LocationInfo.NA_LOCATION_INFO.

Author:
Ceki Gülcü, James P. Cakalic
See Also:
Serialized Form

Constructor Summary
LoggingEvent()
          The no-argument constructor for LoggingEvent.
LoggingEvent(java.lang.String fqnOfLoggerClass, Logger logger, Level level, java.lang.Object message, java.lang.Throwable throwable)
          Instantiate a LoggingEvent from the supplied parameters.
LoggingEvent(java.lang.String fqnOfCategoryClass, Logger logger, long timeStamp, Level level, java.lang.Object message, java.lang.Throwable throwable)
          Deprecated. Please use the no argument constructor and the setter methods instead.
 
Method Summary
 boolean equals(java.lang.Object rObject)
          Two events are considerd equal if they refer to the same instance, or if both their timestamps and sequence numbers match.
 java.lang.String getFQNOfLoggerClass()
          Get the fully qualified name of the calling logger sub-class/wrapper.
 Level getLevel()
          Return the level of this event.
 org.apache.log4j.spi.location.LocationInfo getLocationInformation()
          Get the location information for this logging event.
 Logger getLogger()
          Returns the logger of this event.
 java.lang.String getLoggerName()
          Return the name of the logger.
 java.lang.Object getMessage()
          Return the message for this logging event.
 java.lang.String getNDC()
          This method returns the NDC for this event.
 java.util.Map getProperties()
           
 java.lang.String getProperty(java.lang.String key)
          Return a property for this event.
 java.util.Set getPropertyKeySet()
          Returns the set of of the key values in the properties for the event.
 java.lang.String getRenderedMessage()
          Returns the rendered version of the message according to the renderers registered in the logger repository.
static long getSequenceCount()
           
 long getSequenceNumber()
           
static long getStartTime()
          Returns the time when the application started, in milliseconds elapsed since 01.01.1970.
 java.lang.String getThreadName()
           
 ThrowableInformation getThrowableInformation()
          Returns the throwable information contained within this event.
 java.lang.String[] getThrowableStrRep()
          Return this event's throwable's string[] representaion.
 long getTimeStamp()
          Getter for the event's time stamp.
 int hashCode()
          The hashcode is computed as XOR of the lower 32 bits of sequenceNumber and the higher 32 bits of timeStamp;
 void initializeProperties()
          If the properties field is null, this method creates a new properties map containing a copy of MDC context and a copy of the properites in LoggerRepository generating this event.
 boolean locationInformationExists()
          Check for the existence of location information without creating it (a byproduct of calling getLocationInformation).
 void prepareForDeferredProcessing()
          This method should be called prior to serializing an event.
 void setFQNOfLoggerClass(java.lang.String fqnOfLoggerClass)
          Set the fully qualified name of the calling logger sub-class/wrapper.
 void setLevel(Level level)
          Set the level of this event.
 void setLocationInformation(org.apache.log4j.spi.location.LocationInfo li)
          Set the location information for this logging event.
 void setLogger(Logger logger)
          Set the logger of this event.
 void setLoggerName(java.lang.String loggerName)
          Set the loggerName for this event.
 void setMessage(java.lang.Object message)
          Set the message for this event.
 void setNDC(java.lang.String ndcString)
          This method sets the NDC string for this event.
 void setProperties(java.util.Hashtable properties)
           
 void setProperty(java.lang.String key, java.lang.String value)
          Set a string property using a key and a string value.
 void setRenderedMessage(java.lang.String renderedMessage)
           
 void setSequenceNumber(long sequenceNumber)
           
 void setThreadName(java.lang.String threadName)
           
 void setThrowableInformation(ThrowableInformation ti)
          Set this event's throwable information.
 void setTimeStamp(long timeStamp)
          Setter for the even'ts time stamp.
 void xgetMDCCopy()
          Obtain a copy of this thread's MDC prior to serialization or asynchronous logging.
 java.lang.Object XXgetMDC(java.lang.String key)
          Returns the the context corresponding to the key parameter.
 java.util.Set XXgetMDCKeySet()
          Returns the set of of the key values in the MDC for the event.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

LoggingEvent

public LoggingEvent()
The no-argument constructor for LoggingEvent. This method is the recommended constructor for creating LoggingEvent instances.

Since:
1.3

LoggingEvent

public LoggingEvent(java.lang.String fqnOfLoggerClass,
                    Logger logger,
                    Level level,
                    java.lang.Object message,
                    java.lang.Throwable throwable)
Instantiate a LoggingEvent from the supplied parameters.

Note that many of the LoggingEvent fields are initialized when actually needed. For more information please refer to the comments for the LoggingEvent class at the top of this page.

Parameters:
logger - The logger of this event.
level - The level of this event.
message - The message of this event.
throwable - The throwable of this event.

LoggingEvent

public LoggingEvent(java.lang.String fqnOfCategoryClass,
                    Logger logger,
                    long timeStamp,
                    Level level,
                    java.lang.Object message,
                    java.lang.Throwable throwable)
Deprecated. Please use the no argument constructor and the setter methods instead.

Instantiate a LoggingEvent from the supplied parameters.

Note that many of the LoggingEvent fields are initialized lazily. For more information please refer to the comments for the LoggingEvent class at the top of this page.

Parameters:
fqnOfCategoryClass - The category of this event.
logger - The logger
timeStamp - the timestamp of this logging event
level - The level of this event.
message - The message of this event.
throwable - The throwable of this event.
Method Detail

getSequenceCount

public static long getSequenceCount()
Returns:
The current sequenceCount for this JVM.

equals

public boolean equals(java.lang.Object rObject)
Two events are considerd equal if they refer to the same instance, or if both their timestamps and sequence numbers match.

Overrides:
equals in class java.lang.Object

hashCode

public int hashCode()
The hashcode is computed as XOR of the lower 32 bits of sequenceNumber and the higher 32 bits of timeStamp;

Overrides:
hashCode in class java.lang.Object

locationInformationExists

public boolean locationInformationExists()
Check for the existence of location information without creating it (a byproduct of calling getLocationInformation).


getLocationInformation

public org.apache.log4j.spi.location.LocationInfo getLocationInformation()
Get the location information for this logging event. If location information is null at the time of its invocation, this method extracts location information. The collected information is cached for future use.

Note that after serialisation, it is impossible to correctly extract location information. In that case null is returned.


setLocationInformation

public void setLocationInformation(org.apache.log4j.spi.location.LocationInfo li)
Set the location information for this logging event.

Since:
1.3

getLevel

public Level getLevel()
Return the level of this event.


setLevel

public void setLevel(Level level)
Set the level of this event. The level can be set at most once.

Parameters:
level - The level to set.
Throws:
java.lang.IllegalStateException - if the level has been already set.
Since:
1.3

getLogger

public Logger getLogger()
Returns the logger of this event. May be null because events after serialization do not have a logger.

Since:
1.3

setLogger

public void setLogger(Logger logger)
Set the logger of this event. Calling this method also sets the loggerName for the event. The logger can be set at most once. Moreover, if the loggerName has been already set, this method will throw an IllegalStateException.

Throws:
java.lang.IllegalStateException

getLoggerName

public java.lang.String getLoggerName()
Return the name of the logger.


setLoggerName

public void setLoggerName(java.lang.String loggerName)
                   throws java.lang.IllegalStateException
Set the loggerName for this event. The loggerName can be set at most once.

Parameters:
loggerName - The loggerName to set.
Throws:
java.lang.IllegalStateException - if loggerName is already set
Since:
1.3

getMessage

public java.lang.Object getMessage()
Return the message for this logging event.

Before serialization, the returned object is the message passed by the user to generate the logging event. After serialization, the returned value equals the String form of the message possibly after object rendering.

Since:
1.1

setMessage

public void setMessage(java.lang.Object message)
Set the message for this event. The

Parameters:
message - The message to set.
Since:
1.3

getNDC

public java.lang.String getNDC()
This method returns the NDC for this event. It will return the correct content even if the event was generated in a different thread or even on a different machine. The NDC.get() method should never be called directly.


setNDC

public void setNDC(java.lang.String ndcString)
This method sets the NDC string for this event.

Throws:
java.lang.IllegalStateException - if ndc had been already set.
Since:
1.3

XXgetMDC

public java.lang.Object XXgetMDC(java.lang.String key)
Returns the the context corresponding to the key parameter. If there is a local MDC copy, possibly because we are in a logging server or running inside AsyncAppender, then we search for the key in MDC copy, if a value is found it is returned. Otherwise, if the search in MDC copy returns a null result, then the current thread's MDC is used.

Note that both the local MDC copy and the current thread's MDC are searched.


XXgetMDCKeySet

public java.util.Set XXgetMDCKeySet()
Returns the set of of the key values in the MDC for the event. The returned set is unmodifiable by the caller.

Returns:
Set an unmodifiable set of the MDC keys.
Since:
1.3

xgetMDCCopy

public void xgetMDCCopy()
Obtain a copy of this thread's MDC prior to serialization or asynchronous logging.


initializeProperties

public void initializeProperties()
If the properties field is null, this method creates a new properties map containing a copy of MDC context and a copy of the properites in LoggerRepository generating this event. If properties is non-null, this method does nothing.

Since:
1.3

getProperty

public java.lang.String getProperty(java.lang.String key)
Return a property for this event. The return value can be null.

The property is searched first in the properties map specific for this event, then in the MDC, then in the logger repository containing the logger of this event.

Since:
1.3

getPropertyKeySet

public java.util.Set getPropertyKeySet()
Returns the set of of the key values in the properties for the event. The returned set is unmodifiable by the caller.

Returns:
Set an unmodifiable set of the property keys.
Since:
1.3

getRenderedMessage

public java.lang.String getRenderedMessage()
Returns the rendered version of the message according to the renderers registered in the logger repository. Only the rendered version survives serialization.


setRenderedMessage

public void setRenderedMessage(java.lang.String renderedMessage)
                        throws java.lang.IllegalStateException
Parameters:
renderedMessage - The renderedMessage to set.
Throws:
java.lang.IllegalStateException - if renderedMessage has been already set.
Since:
1.3

getStartTime

public static long getStartTime()
Returns the time when the application started, in milliseconds elapsed since 01.01.1970.


getSequenceNumber

public long getSequenceNumber()
Since:
1.3

setSequenceNumber

public void setSequenceNumber(long sequenceNumber)
Since:
1.3

getThreadName

public java.lang.String getThreadName()

setThreadName

public void setThreadName(java.lang.String threadName)
                   throws java.lang.IllegalStateException
Parameters:
threadName - The threadName to set.
Throws:
java.lang.IllegalStateException - If threadName has been already set.

getThrowableInformation

public ThrowableInformation getThrowableInformation()
Returns the throwable information contained within this event. May be null if there is no such information.

Note that the Throwable object contained within a ThrowableInformation does not survive serialization.

Since:
1.1

getThrowableStrRep

public java.lang.String[] getThrowableStrRep()
Return this event's throwable's string[] representaion.


setThrowableInformation

public void setThrowableInformation(ThrowableInformation ti)
Set this event's throwable information.

Since:
1.3

getProperties

public java.util.Map getProperties()
Returns:
Returns the properties specific for this event. The returned value can be null.
Since:
1.3

setProperties

public void setProperties(java.util.Hashtable properties)
Parameters:
properties - The properties to set.

setProperty

public void setProperty(java.lang.String key,
                        java.lang.String value)
Set a string property using a key and a string value. since 1.3


prepareForDeferredProcessing

public void prepareForDeferredProcessing()
This method should be called prior to serializing an event. It should also be called when using asynchronous logging, before writing the event on a database, or as an XML element.

Since:
1.3

getTimeStamp

public long getTimeStamp()
Getter for the event's time stamp. The time stamp is calculated starting from 1970-01-01 GMT.

Since:
1.3

setTimeStamp

public void setTimeStamp(long timeStamp)
Setter for the even'ts time stamp. See also getTimeStamp().

Since:
1.3

getFQNOfLoggerClass

public java.lang.String getFQNOfLoggerClass()
Get the fully qualified name of the calling logger sub-class/wrapper.

Since:
1.3

setFQNOfLoggerClass

public void setFQNOfLoggerClass(java.lang.String fqnOfLoggerClass)
Set the fully qualified name of the calling logger sub-class/wrapper.

Parameters:
fqnOfLoggerClass -
Since:
1.3

Log4j 1.3alpha-1

Copyright 2000-2003 Apache Software Foundation.