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:

• Logger A is set to process informational messages. Logger B is set to process error messages. Both are connected to the same console handler, which will accept any type of message. In a large application, it may be desirable to define multiple loggers in this manner so that different components within the application can provide varying levels of information.
• Loggers A and B can generate any type of message. Both loggers are connected to the same console handler and file handler. The console handler is set to process only error messages, but the file handler will accept all messages. The effect is that critical errors go to the console, where they are seen immediately, and all messages go to the file, where they are archived.
• Logger A is set to process informational messages. Logger B is set to process informational and warning messages. A handler is attached to both loggers and is configured to process only warning messages. Informational messages from both loggers are ignored.

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:

• A server associated with the creation of the messages.
• The client on whose behalf the messages are created.

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.