com.ibm.ras
Class RASHandler

java.lang.Object
  |
  +--com.ibm.ras.RASObject
        |
        +--com.ibm.ras.RASHandler
Direct Known Subclasses:
RASConsoleHandler, RASFileHandler, RASSocketHandler

public abstract class RASHandler
extends RASObject
implements RASIHandler, java.lang.Runnable

RASHandler implements the RASIHandler interface and is the parent of all classes which process the output of the RASLogger classes. At least one RASHandler must be associated with each RASLogger. This is done through the RASLogger.addHandler method.

Each handler operates on its own thread so that log entries can be sent to their destination at whatever rate the transport can manage. This means that an application, for example, does not have to wait for each trace event to be written to disk as it runs. The message and trace data is accepted from the loggers in the form of RASIEvent objects. These are simply an encapsulation of the message or trace data that the application creates through the RASLogger methods.

It is possible to direct both message and trace data to the same destination (the console or a socket, for example). However, it is certainly possible to configure separate handlers to direct message and trace data to different destinations (two separate files, for example).

Each event class which a handler processes may be associated with a formatter, which defines the presentation of the log entries. The use of a formatter depends on the function of the handler. For example, if the handler directs data to the console, it should be formatted. However, if the handler is designed to serialize the message or trace data and transport it across a network, formatting may not be required. The RASHandler write methods require a formatter, but may be overridden if desired. (Because a formatter is not required, the methods to get and set the message and trace formatters are not included in the RASIHandler interface, which this object implements.)

RASMessageFormatter and RASTraceFormatter are automatically registered to process the RASMessageEvent and RASTraceEvent classes, respectively.

See Also:
RASIHandler, RASConsoleHandler, RASFileHandler, RASSocketHandler, RASLogger, RASEvent, RASMessageFormatter, RASTraceFormatter

Field Summary
 boolean deviceOpen
          A flag which indicates whether the device to which this handler sends log entries is open.
 
Constructor Summary
RASHandler()
          Creates a RASHandler.
RASHandler(java.lang.String name)
          Creates a RASHandler.
RASHandler(java.lang.String name, java.lang.String desc)
          Creates a RASHandler.
 
Method Summary
 void addFormatter(RASIFormatter formatter)
          Registers a RAS event formatter with this handler.
 void addMaskChangeListener(RASIMaskChangeListener listener)
          Adds an object that wishes to be informed of changes in the handler's message or trace mask configuration.
 java.util.Hashtable getConfig()
          Gets the configuration of this object.
 java.util.Enumeration getFormatters()
          Gets the set of formatters associated with this handler.
 java.util.Enumeration getMaskChangeListeners()
          Gets the set of objects that wish to be informed of changes in the handler's message or trace mask configuration.
 long getMessageMask()
          Gets the mask which defines the set of message types that will be processed.
 long getTraceMask()
          Gets the mask which defines the set of trace types that will be processed.
 void logEvent(RASIEvent event)
          Passes a RAS event asynchronously from a logger to a handler.
abstract  void openDevice()
          Opens the device to which the handler will send its log entries.
 void removeFormatter(RASIFormatter formatter)
          Removes a RAS event formatter from this handler.
 void removeMaskChangeListener(RASIMaskChangeListener listener)
          Removes an object from the list that wishes to be informed of changes in the handler's message or trace mask configuration.
 void run()
          Processes any log event objects placed on the handler's queue by a logger.
 void setConfig(java.util.Hashtable ht)
          Sets the configuration of this object.
 void setMessageMask(long mask)
          Sets the mask which defines the set of message types that will be processed.
 void setTraceMask(long mask)
          Sets the mask which defines the set of trace types that will be processed.
 void stop()
          Stops the handler.
 void writeEvent(RASIEvent event)
          Passes a RAS event synchronously from a logger to a handler.
 
Methods inherited from class com.ibm.ras.RASObject
getDescription, getName, setDescription, setName
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

deviceOpen

public boolean deviceOpen
A flag which indicates whether the device to which this handler sends log entries is open. It is set true when the device is open and false otherwise.
Constructor Detail

RASHandler

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

RASHandler

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

RASHandler

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

getConfig

public java.util.Hashtable getConfig()
Gets the configuration of this object.
Specified by:
getConfig in interface RASIHandler
Returns:
A Hashtable containing the configuration. This object inserts the following key/value pairs into the the configuration:
         "messageMask" The mask which selects the message types to
                       be processed.
         "traceMask"   The mask which selects the trace types to be
                       processed.
         
All values are Strings. The parent and extensions of this object may use additional keys.
Overrides:
getConfig in class RASObject

setConfig

public void setConfig(java.util.Hashtable ht)
Sets the configuration of this object. This method is used by a RASManager to initialize a RAS object. It should not be necessary for an application to use this method.
Specified by:
setConfig in interface RASIHandler
Parameters:
ht - A Hashtable containing the configuration. This object searches for the following keys:
            "messageMask" The mask which selects the message types to
                          be processed.
            "traceMask"   The mask which selects the trace types to be
                          processed.
            
All values are Strings. If a key is not found, that configuration element is not updated. The parent and extensions of this object may use additional keys.
Overrides:
setConfig in class RASObject

getMessageMask

public long getMessageMask()
Gets the mask which defines the set of message types that will be processed. Possible values are defined by the logical OR of the RASIMessageEvent.TYPE_XXXX constants.
Specified by:
getMessageMask in interface RASIHandler
Returns:
The trace mask.

setMessageMask

public void setMessageMask(long mask)
Sets the mask which defines the set of message types that will be processed. Possible values are defined by the RASIMessageEvent.TYPE_XXXX constants. The mask value is not validated against these types.
Specified by:
setMessageMask in interface RASIHandler
Parameters:
mask - The message mask.

getTraceMask

public long getTraceMask()
Gets the mask which defines the set of trace types that will be processed. Possible values are defined by the logical OR of the RASITraceEvent.TYPE_XXXX constants.
Specified by:
getTraceMask in interface RASIHandler
Returns:
The trace mask.

setTraceMask

public void setTraceMask(long mask)
Sets the mask which defines the set of trace types that will be processed. Possible values are defined by the RASITraceEvent.TYPE_XXXX constants. The mask value is not validated against these types.
Specified by:
setTraceMask in interface RASIHandler
Parameters:
mask - The trace mask.

addMaskChangeListener

public void addMaskChangeListener(RASIMaskChangeListener listener)
Adds an object that wishes to be informed of changes in the handler's message or trace mask configuration. If the listener is null or is already registered, this method does nothing.
Specified by:
addMaskChangeListener in interface RASIHandler
Parameters:
listener - The mask change listener.

removeMaskChangeListener

public void removeMaskChangeListener(RASIMaskChangeListener listener)
Removes an object from the list that wishes to be informed of changes in the handler's message or trace mask configuration. If the listener is null or is not registered, this method does nothing.
Specified by:
removeMaskChangeListener in interface RASIHandler
Parameters:
listener - The mask change listener.

getMaskChangeListeners

public java.util.Enumeration getMaskChangeListeners()
Gets the set of objects that wish to be informed of changes in the handler's message or trace mask configuration.
Specified by:
getMaskChangeListeners in interface RASIHandler
Returns:
An Enumeration of mask change listeners. If no listeners are registered, the Enumeration is empty.

addFormatter

public void addFormatter(RASIFormatter formatter)
Registers a RAS event formatter with this handler. The formatter must be configured with the set of RASIEvent classes which it supports before this method is called. If the formatter is null, this method does nothing. If the formatter supports an event class which is already registered with this handler, this new formatter replaces the old one.
Specified by:
addFormatter in interface RASIHandler
Parameters:
formatter - The event formatter.

removeFormatter

public void removeFormatter(RASIFormatter formatter)
Removes a RAS event formatter from this handler. If the formatter is null or is not registered, this method does nothing.
Specified by:
removeFormatter in interface RASIHandler
Parameters:
formatter - The event formatter.

getFormatters

public java.util.Enumeration getFormatters()
Gets the set of formatters associated with this handler.
Specified by:
getFormatters in interface RASIHandler
Returns:
An Enumeration of registered formatters. If no formatters have been registered, the Enumeration is empty.

run

public void run()
Processes any log event objects placed on the handler's queue by a logger.
Specified by:
run in interface java.lang.Runnable

stop

public void stop()
Stops the handler. This method should be called when a handler is no longer needed. Be careful not to stop a handler prematurely if it is shared by more than one logger.
Specified by:
stop in interface RASIHandler

openDevice

public abstract void openDevice()
Opens the device to which the handler will send its log entries. If an error occurs during this process, the handler will write a message to System.err.

The caller should ensure that this method is not called if the device is already open or if cannot tolerate attempts to reopen it.

Specified by:
openDevice in interface RASIHandler

logEvent

public void logEvent(RASIEvent event)
Passes a RAS event asynchronously from a logger to a handler. The log entry is saved for processing by the handler. The logger must compare the message type against the handler's message mask before calling this method. If the log event is null, this method does nothing.
Specified by:
logEvent in interface RASIHandler
Parameters:
event - A RAS event.

writeEvent

public void writeEvent(RASIEvent event)
Passes a RAS event synchronously from a logger to a handler. The handler processes the log entry immediately by calling the format method of the configured formatter and then the println method of the configured print writer. The logger must compare the event type against the handler's message or trace mask before calling this method. If the log event is null, this method does nothing.
Specified by:
writeEvent in interface RASIHandler
Parameters:
event - A RAS event.