|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--com.ibm.ras.RASObject | +--com.ibm.ras.RASMaskChangeGenerator | +--com.ibm.ras.RASLogger
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 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:
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.
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
|
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.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 |
public boolean isLogging
protected transient int handlerFailures
protected long isLoggableMask
Constructor Detail |
public RASLogger()
RASLogger
. The name and description of this
object are empty strings.public RASLogger(java.lang.String name)
RASLogger
. The description of this object
is an empty string.name
- The name of this object.public RASLogger(java.lang.String name, java.lang.String desc)
RASLogger
.name
- The name of this object.desc
- The description of this object.public RASLogger(java.lang.String name, java.lang.String desc, java.lang.String server, java.lang.String client)
RASLogger
.name
- The name of this object.desc
- The description of this object.server
- The server.client
- The client.Method Detail |
protected void init()
init
in class RASMaskChangeGenerator
public java.util.Hashtable getConfig()
getConfig
in interface RASILogger
getConfig
in class RASMaskChangeGenerator
Hashtable
containing the configuration.
This object inserts the following key/value pairs into the
configuration:
true
if the logger is logging data;
otherwise, false
.
true
if the logger is logging synchronously;
otherwise, false
.
All values are Strings
.
The parent and extensions of this object may add additional keys.
public void setConfig(java.util.Hashtable ht)
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.
public java.lang.String getClient()
getClient
in interface RASILogger
public void setClient(java.lang.String name)
null
, the current name is not changed.setClient
in interface RASILogger
name
- The client name.public java.lang.String getServer()
getServer
in interface RASILogger
public void setServer(java.lang.String name)
null
, the current name is not changed.setServer
in interface RASILogger
name
- The server name.public void addHandler(RASIHandler handler)
null
or is already
registered, this method does nothing.addHandler
in interface RASILogger
handler
- A RAS handler.public void removeHandler(RASIHandler handler)
null
or is not registered, this method does nothing.removeHandler
in interface RASILogger
handler
- A RAS handler.public java.util.Enumeration getHandlers()
getHandlers
in interface RASILogger
Enumeration
of handlers. If no handlers
are registered, the Enumeration
is empty.public boolean isSynchronous()
isSynchronous
in interface RASILogger
true
for synchronous logging and
false
otherwise.public void setSynchronous(boolean flag)
setSynchronous
in interface RASILogger
flag
- true
for synchronous logging and
false
otherwise.public boolean isLogging()
isLogging
in interface RASILogger
true
when the logger is "on" and
false
otherwise.public void setLogging(boolean flag)
setLogging
in interface RASILogger
flag
- true
when the logger is "on" and false
otherwise.public boolean isLoggable(long type)
if (isLoggable(RASTraceEvent.TYPE_PUBLIC) trace(RASTraceEvent.TYPE_PUBLIC...);
isLoggable
in interface RASILogger
type
- The type of the log entry. The set of possible values is
defined by the RASIMessageEvent
or
RASITraceEvent
TYPE_XXXX
constants.true
if the logger is enabled and at least one
handler will process the log entry; false
,
otherwise.public abstract void maskValueChanged(RASMaskChangeEvent mc)
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.
maskValueChanged
in interface RASIMaskChangeListener
mc
- A mask change event, indicating what has changed.public void fireRASEvent(RASIEvent event)
RASIEvent
to all handlers which will process
the event. A null
event is ignored.fireRASEvent
in interface RASILogger
event
- The event to be sent.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |