RASLogger (IBM WebSphere Application Server [ras])

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.

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.

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.

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

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.

com.ibm.ras Class RASLogger

isLogging

handlerFailures

isLoggableMask

RASLogger

RASLogger

RASLogger

RASLogger

init

getConfig

setConfig

getClient

setClient

getServer

setServer

addHandler

removeHandler

getHandlers

isSynchronous

setSynchronous

isLogging

setLogging

isLoggable

maskValueChanged

fireRASEvent

com.ibm.ras
Class RASLogger