Class RASLogger
- java.lang.Object
-
- com.ibm.ras.RASObject
-
- com.ibm.ras.RASMaskChangeGenerator
-
- com.ibm.ras.RASLogger
-
- All Implemented Interfaces:
- RASConstants, RASILogger, RASIMaskChangeGenerator, RASIMaskChangeListener, RASIObject, java.io.Serializable, java.lang.Cloneable, java.util.EventListener
- Direct Known Subclasses:
- RASMessageLogger, RASTraceLogger
Deprecated.As of WAS 6.0, recommend using java.util.logging
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
, you must associate with it at least oneRASIHandler
Use theaddHandler
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, thepublic boolean
variableisLogging
is settrue
when the logger is "on" (logging data) andfalse
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 methodssetLogging
andisLogging
are available to manipulate thepublic 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
extensions 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 beTYPE_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 ofTYPE_PUBLIC | TYPE_ERROR_EXC
. The trace logger mask is set toTYPE_PUBLIC | TYPE_PRIVATE | TYPE_STATIC
. SinceTYPE_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
andRASITraceEvent.DEFAULT_TRACE_MASK
, respectively. These values can be changed through thesetMessageMask
andsetTraceMask
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 returnstrue
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 viaisSynchronous
.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 givenRASLogger
, so they are specified through aRASLogger
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.
RASLogger
is an abstract class, primarily because it lacks methods to send information to its associated handlers. (Themessage
methods ofRASMessageLogger
and thetrace
methods ofRASTraceLogger
provide this needed function.)Note: Classes which implement
RASILogger
should, in their constructors, call theaddMessageEventClass
andaddTraceEventClass
methods to register theRASIEvent
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
Fields Modifier and Type Field and Description protected int
handlerFailures
Deprecated.The number of consecutive errors which have occurred trying to send an event to a handler.protected long
isLoggableMask
Deprecated.boolean
isLogging
Deprecated.-
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
Constructors Constructor and Description RASLogger()
Deprecated.Creates aRASLogger
.RASLogger(java.lang.String name)
Deprecated.Creates aRASLogger
.RASLogger(java.lang.String name, java.lang.String desc)
Deprecated.Creates aRASLogger
.RASLogger(java.lang.String name, java.lang.String desc, java.lang.String server, java.lang.String client)
Deprecated.Creates aRASLogger
.
-
Method Summary
Methods Modifier and Type Method and Description void
addHandler(RASIHandler handler)
Deprecated.Registers a RAS handler with this logger.void
fireRASEvent(RASIEvent event)
Deprecated.Sends aRASIEvent
to all handlers which will process the event.java.lang.String
getClient()
Deprecated.Gets the name of the client which is associated with this logger.java.util.Hashtable
getConfig()
Deprecated.Gets the configuration of this object.java.util.Enumeration
getHandlers()
Deprecated.Gets all of the handlers associated with this logger.java.lang.String
getServer()
Deprecated.Gets the name of the server which is associated with this logger.protected void
init()
Deprecated.Initializes this object, setting default values.boolean
isLoggable(long type)
Deprecated.Determines if a log entry will be processed by the logger and any of the handlers.boolean
isLogging()
Deprecated.Determines if a logger is logging data ("on") or not ("off").boolean
isSynchronous()
Deprecated.Determines if synchronous logging is in effect.abstract void
maskValueChanged(RASMaskChangeEvent mc)
Deprecated.Indicates that the value of the handler's message or trace mask has changed.void
removeHandler(RASIHandler handler)
Deprecated.Removes a RAS handler from this logger.void
setClient(java.lang.String name)
Deprecated.Sets the name of the client which is associated with this logger.void
setConfig(java.util.Hashtable ht)
Deprecated.Sets the configuration of this object.void
setLogging(boolean flag)
Deprecated.Sets a flag that indicates whether the logger is logging data ("on") or not ("off").void
setServer(java.lang.String name)
Deprecated.Sets the name of the server which is associated with this logger.void
setSynchronous(boolean flag)
Deprecated.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
Deprecated.
-
handlerFailures
protected transient int handlerFailures
Deprecated.The number of consecutive errors which have occurred trying to send an event to a handler.
-
isLoggableMask
protected long isLoggableMask
Deprecated.
-
-
Constructor Detail
-
RASLogger
public RASLogger()
Deprecated.Creates aRASLogger
. The name and description of this object are empty strings.
-
RASLogger
public RASLogger(java.lang.String name)
Deprecated.Creates aRASLogger
. 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)
Deprecated.Creates aRASLogger
.- 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)
Deprecated.Creates aRASLogger
.- 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()
Deprecated.Initializes this object, setting default values.- Overrides:
init
in classRASMaskChangeGenerator
-
getConfig
public java.util.Hashtable getConfig()
Deprecated.Gets the configuration of this object.- Specified by:
getConfig
in interfaceRASILogger
- Specified by:
getConfig
in interfaceRASIMaskChangeGenerator
- Specified by:
getConfig
in interfaceRASIObject
- Overrides:
getConfig
in classRASMaskChangeGenerator
- 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)
Deprecated.Sets the configuration of this object. This method is used by aRASManager
to initialize a RAS object. It should not be necessary for an application to use this method.- Specified by:
setConfig
in interfaceRASILogger
- Specified by:
setConfig
in interfaceRASIMaskChangeGenerator
- Specified by:
setConfig
in interfaceRASIObject
- Overrides:
setConfig
in classRASMaskChangeGenerator
- Parameters:
ht
- AHashtable
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()
Deprecated.Gets the name of the client which is associated with this logger.- Specified by:
getClient
in interfaceRASILogger
- Returns:
- The client name, or an empty string ("") if the client has not been set.
-
setClient
public void setClient(java.lang.String name)
Deprecated.Sets the name of the client which is associated with this logger. If the name isnull
, the current name is not changed.- Specified by:
setClient
in interfaceRASILogger
- Parameters:
name
- The client name.
-
getServer
public java.lang.String getServer()
Deprecated.Gets the name of the server which is associated with this logger.- Specified by:
getServer
in interfaceRASILogger
- Returns:
- The server name, or an empty string ("") if the server has not been set.
-
setServer
public void setServer(java.lang.String name)
Deprecated.Sets the name of the server which is associated with this logger. If the name isnull
, the current name is not changed.- Specified by:
setServer
in interfaceRASILogger
- Parameters:
name
- The server name.
-
addHandler
public void addHandler(RASIHandler handler)
Deprecated.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 isnull
or is already registered, this method does nothing.- Specified by:
addHandler
in interfaceRASILogger
- Parameters:
handler
- A RAS handler.
-
removeHandler
public void removeHandler(RASIHandler handler)
Deprecated.Removes a RAS handler from this logger. If the handler isnull
or is not registered, this method does nothing.- Specified by:
removeHandler
in interfaceRASILogger
- Parameters:
handler
- A RAS handler.
-
getHandlers
public java.util.Enumeration getHandlers()
Deprecated.Gets all of the handlers associated with this logger.- Specified by:
getHandlers
in interfaceRASILogger
- Returns:
- An
Enumeration
of handlers. If no handlers are registered, theEnumeration
is empty.
-
isSynchronous
public boolean isSynchronous()
Deprecated.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 interfaceRASILogger
- Returns:
true
for synchronous logging andfalse
otherwise.
-
setSynchronous
public void setSynchronous(boolean flag)
Deprecated.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 interfaceRASILogger
- Parameters:
flag
-true
for synchronous logging andfalse
otherwise.
-
isLogging
public boolean isLogging()
Deprecated.Determines if a logger is logging data ("on") or not ("off").- Specified by:
isLogging
in interfaceRASILogger
- Returns:
true
when the logger is "on" andfalse
otherwise.
-
setLogging
public void setLogging(boolean flag)
Deprecated.Sets a flag that indicates whether the logger is logging data ("on") or not ("off").- Specified by:
setLogging
in interfaceRASILogger
- Parameters:
flag
-true
when the logger is "on" andfalse
otherwise.
-
isLoggable
public boolean isLoggable(long type)
Deprecated.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 interfaceRASILogger
- Parameters:
type
- The type of the log entry. The set of possible values is defined by theRASIMessageEvent
orRASITraceEvent
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)
Deprecated.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 interfaceRASIMaskChangeListener
- Parameters:
mc
- A mask change event, indicating what has changed.
-
fireRASEvent
public void fireRASEvent(RASIEvent event)
Deprecated.Sends aRASIEvent
to all handlers which will process the event. Anull
event is ignored.- Specified by:
fireRASEvent
in interfaceRASILogger
- Parameters:
event
- The event to be sent.
-
-