com.ibm.ras
Class RASLogger

java.lang.Object
  |
  +--com.ibm.ras.RASObject
        |
        +--com.ibm.ras.RASMaskChangeGenerator
              |
              +--com.ibm.ras.RASLogger
All Implemented Interfaces:
java.lang.Cloneable, java.util.EventListener, RASConstants, RASILogger, RASIMaskChangeGenerator, RASIMaskChangeListener, RASIObject, java.io.Serializable
Direct Known Subclasses:
RASMessageLogger, RASTraceLogger

public abstract class RASLogger
extends RASMaskChangeGenerator
implements RASConstants, RASILogger, RASIMaskChangeListener

RASLogger is the parent of all classes which create message and trace data. These classes provide the primary interface to the application programmer by supplying the methods for information logging.

Before you can use a RASLogger, associate with it at least one RASIHandler Use the addHandler method to accomplish this. A handler directs the log events to a destination (such as a file, a console or a TCP socket). It is possible to associate more than one handler with a logger to send the data to multiple destinations, possibly formatted differently for each. Multiple loggers may also be associated with a single handler.

RASLogger provides several levels of control over which log events are processed. At the highest level, the public boolean variable isLogging is set true when the logger is "on" (logging data) and false when it is "off." To improve performance, this variable may be tested to eliminate unnecessary method calls. For example:

 if (traceLogger.isLogging)
   traceLogger.trace(...);
 
(The methods setLogging and isLogging are available to manipulate the public boolean isLogging as well.)

For finer control, each message or trace event is assigned a "type," which defines the particular flavor of the object. For example, a message might be one of "informational," "warning," or "error." These types are defined by the classes which extend RASEvent.

In general, the type assigned to a log event may be the logical OR of any of the defined types. In some cases, this does not make much sense. (A message might be informational or a warning, but not both). But RASEvent extentions might define additional types for which this would make sense. For example, an error might be "internal" (a failure detected within the application) or "external" (a failure detected outside the application). In this case, one might define the log event type to be TYPE_ERROR | TYPE_INTERNAL.

Every logger and handler is assigned a "mask," which is the subset of RASEvent types that it will process. If any of the types assigned to a log entry are contained in the mask, the logger or handler will process the entry. For example, a trace entry is assigned a type of TYPE_PUBLIC | TYPE_ERROR_EXC. The trace logger mask is set to TYPE_PUBLIC | TYPE_PRIVATE | TYPE_STATIC. Since TYPE_PUBLIC is in the log entry type and the logger's mask, this entry will be processed.

The default message and trace masks are RASIMessageEvent.DEFAULT_MESSAGE_MASK and RASITraceEvent.DEFAULT_TRACE_MASK, respectively. These values can be changed through the setMessageMask and setTraceMask methods.

In practice, one is most likely to manipulate the mask of the logger or the handlers, but not both -- although nothing prevents customizing both masks. Different effects can be achieved by manipulating the masks. For example:

The isLoggable method compares the type associated with a message or trace point with the mask of the logger and each configured handler. It returns true if the logger and at least one of the handlers will process the log point. Thus, the overhead of building the log entry is avoided if no object is configured to process it.

 if (traceLogger.isLoggable(TYPE_PUBLIC)
   traceLogger.trace(TYPE_PUBLIC,...);
 

A logger can send data to its attached handlers either synchronously or asynchronously. In synchronous mode, a log entry is passed to a handler and written to its destination immediately. The application using the logger is, in effect, "blocked" until this operation completes. In asynchronous mode, a log entry is passed to a handler and queued for processing at whatever rate the handler is capable. The logger returns to the calling application more quickly in this mode. Asynchronous operation is the default. The mode can be changed with the setSynchronous method and tested via isSynchronous.

Note: A handler can be set to use a circular buffer, which holds the log entries in memory until an explicit request to dump the buffer is made. This buffering mode is only possible if the logger is set for asynchronous operation. In synchronous mode, the handler's buffering mechanism is bypassed entirely.

RASLogger has several optional fields which may be included in the message. These fields should not vary among messages produced by a given RASLogger, so they are specified through a RASLogger constructor or by the appropriate "set" and "get" methods of this class. These fields are:

If not specified, each of these fields defaults to an empty string.

RASLogger is an abstract class, primarily because it lacks methods to send information to its associated handlers. (The message methods of RASMessageLogger and the trace methods of RASTraceLogger provide this needed function.)

Note: Classes which implement RASILogger should, in their constructors, call the addMessageEventClass and addTraceEventClass methods to register the RASIEvent classes which the logger uses. This will allow a graphical program to query the logger to determine the supported RAS events. The events, in turn, can be queried to determine their set of supported event types.

See Also:
Serialized Form

Field Summary
protected  int handlerFailures
          The number of consecutive errors which have occurred trying to send an event to a handler.
protected  long isLoggableMask
           
 boolean isLogging
           
 
Fields inherited from interface com.ibm.ras.RASConstants
KEY_CLASS_NAME, KEY_CLIENT, KEY_COMPONENT, KEY_DATE_FORMAT, KEY_DEFAULT_HANDLERS, KEY_DEFAULT_MESSAGE_HANDLERS, KEY_DEFAULT_TRACE_HANDLERS, KEY_DESCRIPTION, KEY_ENCODING, KEY_EXCEPTION, KEY_EXCEPTION_TRACE, KEY_FILE_NAME, KEY_FORMATTER_NAMES, KEY_GROUP, KEY_HANDLER_NAMES, KEY_HEX_DATA, KEY_IS_CIRCULAR, KEY_IS_LOGGING, KEY_IS_SYNC, KEY_LOGGER, KEY_LOGGING_CLASS, KEY_LOGGING_METHOD, KEY_MAX_FILE_SIZE, KEY_MAX_FILES, KEY_MAX_QUEUE_SIZE, KEY_MESSAGE_EVENT_CLASSES, KEY_MESSAGE_FILE, KEY_MESSAGE_MASK, KEY_NAME, KEY_ORGANIZATION, KEY_PRODUCT, KEY_RETRY_INTERVAL, KEY_SEPARATOR, KEY_SERVER, KEY_SOCKET_PORT, KEY_SOCKET_SERVER, KEY_SUPPRESSED_KEYS, KEY_THREAD_ID, KEY_TIME_FORMAT, KEY_TRACE_EVENT_CLASSES, KEY_TRACE_MASK, RAS_VERSION
 
Constructor Summary
RASLogger()
          Creates a RASLogger.
RASLogger(java.lang.String name)
          Creates a RASLogger.
RASLogger(java.lang.String name, java.lang.String desc)
          Creates a RASLogger.
RASLogger(java.lang.String name, java.lang.String desc, java.lang.String server, java.lang.String client)
          Creates a RASLogger.
 
Method Summary
 void addHandler(RASIHandler handler)
          Registers a RAS handler with this logger.
 void fireRASEvent(RASIEvent event)
          Sends a RASIEvent to all handlers which will process the event.
 java.lang.String getClient()
          Gets the name of the client which is associated with this logger.
 java.util.Hashtable getConfig()
          Gets the configuration of this object.
 java.util.Enumeration getHandlers()
          Gets all of the handlers associated with this logger.
 java.lang.String getServer()
          Gets the name of the server which is associated with this logger.
protected  void init()
          Initializes this object, setting default values.
 boolean isLoggable(long type)
          Determines if a log entry will be processed by the logger and any of the handlers.
 boolean isLogging()
          Determines if a logger is logging data ("on") or not ("off").
 boolean isSynchronous()
          Determines if synchronous logging is in effect.
abstract  void maskValueChanged(RASMaskChangeEvent mc)
          Indicates that the value of the handler's message or trace mask has changed.
 void removeHandler(RASIHandler handler)
          Removes a RAS handler from this logger.
 void setClient(java.lang.String name)
          Sets the name of the client which is associated with this logger.
 void setConfig(java.util.Hashtable ht)
          Sets the configuration of this object.
 void setLogging(boolean flag)
          Sets a flag that indicates whether the logger is logging data ("on") or not ("off").
 void setServer(java.lang.String name)
          Sets the name of the server which is associated with this logger.
 void setSynchronous(boolean flag)
          Sets a flag that tells the logger whether to log data synchronously.
 
Methods inherited from class com.ibm.ras.RASMaskChangeGenerator
addMaskChangeListener, addMessageEventClass, addTraceEventClass, fireMaskChangedEvent, getMaskChangeListeners, getMessageEventClasses, getMessageMask, getTraceEventClasses, getTraceMask, messageMaskLongValue, messageMaskToString, removeMaskChangeListener, removeMessageEventClass, removeTraceEventClass, setMessageMask, setTraceMask, traceMaskLongValue, traceMaskToString
 
Methods inherited from class com.ibm.ras.RASObject
clone, getDescription, getGroup, getName, setDescription, setName
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.ibm.ras.RASIMaskChangeGenerator
addMaskChangeListener, addMessageEventClass, addTraceEventClass, fireMaskChangedEvent, getMaskChangeListeners, getMessageEventClasses, getMessageMask, getTraceEventClasses, getTraceMask, removeMaskChangeListener, removeMessageEventClass, removeTraceEventClass, setMessageMask, setTraceMask
 
Methods inherited from interface com.ibm.ras.RASIObject
getDescription, getGroup, getName, setDescription, setName
 

Field Detail

isLogging

public boolean isLogging

handlerFailures

protected transient int handlerFailures
The number of consecutive errors which have occurred trying to send an event to a handler.

isLoggableMask

protected long isLoggableMask
Constructor Detail

RASLogger

public RASLogger()
Creates a RASLogger. The name and description of this object are empty strings.

RASLogger

public RASLogger(java.lang.String name)
Creates a RASLogger. The description of this object is an empty string.
Parameters:
name - The name of this object.

RASLogger

public RASLogger(java.lang.String name,
                 java.lang.String desc)
Creates a RASLogger.
Parameters:
name - The name of this object.
desc - The description of this object.

RASLogger

public RASLogger(java.lang.String name,
                 java.lang.String desc,
                 java.lang.String server,
                 java.lang.String client)
Creates a RASLogger.
Parameters:
name - The name of this object.
desc - The description of this object.
server - The server.
client - The client.
Method Detail

init

protected void init()
Initializes this object, setting default values.
Overrides:
init in class RASMaskChangeGenerator

getConfig

public java.util.Hashtable getConfig()
Gets the configuration of this object.
Specified by:
getConfig in interface RASILogger
Overrides:
getConfig in class RASMaskChangeGenerator
Returns:
A Hashtable containing the configuration. This object inserts the following key/value pairs into the configuration:

isLogging

true if the logger is logging data; otherwise, false.

isSync

true if the logger is logging synchronously; otherwise, false.

server

The server.

client

The client.

handlerNames

The names of the handlers attached to this logger.

All values are Strings. The parent and extensions of this object may add additional keys.


setConfig

public void setConfig(java.util.Hashtable ht)
Sets the configuration of this object. This method is used by a RASManager>/code> to initialize a RAS object. It should not be necessary for an application to use this method.
Specified by:
setConfig in interface RASILogger
Overrides:
setConfig in class RASMaskChangeGenerator
Parameters:
ht - A Hashtable containing the configuration. This object searches for the following keys:

isLogging

true if the logger is logging data; otherwise, false.

isSync

true if the logger is logging synchronously; otherwise, false.

server

The server.

client

The client.

handlerNames

The names of the handlers attached to this logger.

All values are Strings. If a key is not found, an internal default for that element is set instead. The parent and extensions of this object may use additional keys.


getClient

public java.lang.String getClient()
Gets the name of the client which is associated with this logger.
Specified by:
getClient in interface RASILogger
Returns:
The client name, or an empty string ("") if the client has not been set.

setClient

public void setClient(java.lang.String name)
Sets the name of the client which is associated with this logger. If the name is null, the current name is not changed.
Specified by:
setClient in interface RASILogger
Parameters:
name - The client name.

getServer

public java.lang.String getServer()
Gets the name of the server which is associated with this logger.
Specified by:
getServer in interface RASILogger
Returns:
The server name, or an empty string ("") if the server has not been set.

setServer

public void setServer(java.lang.String name)
Sets the name of the server which is associated with this logger. If the name is null, the current name is not changed.
Specified by:
setServer in interface RASILogger
Parameters:
name - The server name.

addHandler

public void addHandler(RASIHandler handler)
Registers a RAS handler with this logger. More than one handler may be associated with a logger to direct the RAS data to multiple destinations. If the handler is null or is already registered, this method does nothing.
Specified by:
addHandler in interface RASILogger
Parameters:
handler - A RAS handler.

removeHandler

public void removeHandler(RASIHandler handler)
Removes a RAS handler from this logger. If the handler is null or is not registered, this method does nothing.
Specified by:
removeHandler in interface RASILogger
Parameters:
handler - A RAS handler.

getHandlers

public java.util.Enumeration getHandlers()
Gets all of the handlers associated with this logger.
Specified by:
getHandlers in interface RASILogger
Returns:
An Enumeration of handlers. If no handlers are registered, the Enumeration is empty.

isSynchronous

public boolean isSynchronous()
Determines if synchronous logging is in effect. When logging synchronously, the logger will wait for the handlers to write a log entry before returning to the caller. Otherwise, the log entry is passed to the handler and the logger returns.
Specified by:
isSynchronous in interface RASILogger
Returns:
true for synchronous logging and false otherwise.

setSynchronous

public void setSynchronous(boolean flag)
Sets a flag that tells the logger whether to log data synchronously. When logging synchronously, the logger will wait for the handlers to write a log entry before returning to the caller. Otherwise, the log entry is passed to the handler and the logger returns.
Specified by:
setSynchronous in interface RASILogger
Parameters:
flag - true for synchronous logging and false otherwise.

isLogging

public boolean isLogging()
Determines if a logger is logging data ("on") or not ("off").
Specified by:
isLogging in interface RASILogger
Returns:
true when the logger is "on" and false otherwise.

setLogging

public void setLogging(boolean flag)
Sets a flag that indicates whether the logger is logging data ("on") or not ("off").
Specified by:
setLogging in interface RASILogger
Parameters:
flag - true when the logger is "on" and false otherwise.

isLoggable

public boolean isLoggable(long type)
Determines if a log entry will be processed by the logger and any of the handlers. Wrapping a message or trace call with this method can improve performance. Log entries that will not be processed need not even be built. For example:
 if (isLoggable(RASTraceEvent.TYPE_PUBLIC)
   trace(RASTraceEvent.TYPE_PUBLIC...);
 
Specified by:
isLoggable in interface RASILogger
Parameters:
type - The type of the log entry. The set of possible values is defined by the RASIMessageEvent or RASITraceEvent TYPE_XXXX constants.
Returns:
true if the logger is enabled and at least one handler will process the log entry; false, otherwise.

maskValueChanged

public abstract void maskValueChanged(RASMaskChangeEvent mc)
Indicates that the value of the handler's message or trace mask has changed.

This method is intended to improve the performance of the RASLogger.isLoggable method. When notified of a change in the value of a handler's mask, the logger can update its internal data, which allows the logger to determine if a RAS event will be logged.

Specified by:
maskValueChanged in interface RASIMaskChangeListener
Parameters:
mc - A mask change event, indicating what has changed.

fireRASEvent

public void fireRASEvent(RASIEvent event)
Sends a RASIEvent to all handlers which will process the event. A null event is ignored.
Specified by:
fireRASEvent in interface RASILogger
Parameters:
event - The event to be sent.