|
|||||||||
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.RASLogger
RASLogger
implements the RASILogger
interface and 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 RASHandler
(implemented here by the
RASHandler
classes). 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(...);
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
.
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
pecified 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.)
RASILogger
,
RASMessageLogger
,
RASTraceLogger
,
RASHandler
Field Summary | |
boolean |
isLogging
A flag which is true when this object is logging data
and false otherwise. |
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. |
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. |
boolean |
isLoggable(long type)
Determines if a log entry will be processed by the logger and any of the handlers. |
boolean |
isSynchronous()
Determines if synchronous logging is in effect. |
abstract void |
maskValueChanged()
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 |
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 |
getDescription,
getName,
setDescription,
setName |
Methods inherited from class java.lang.Object |
equals,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait |
Field Detail |
public boolean isLogging
true
when this object is logging data
and false
otherwise.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 |
public java.util.Hashtable getConfig()
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.All values are
Strings
.
The parent and extensions of this object may add additional keys.public void setConfig(java.util.Hashtable ht)
RASManager
to initialize a RAS object. It should not
be necessary for an application to use this method.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.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.public java.lang.String getClient()
public void setClient(java.lang.String name)
null
, the current name is not changed.name
- The client name.public java.lang.String getServer()
public void setServer(java.lang.String name)
null
, the current name is not changed.name
- The server name.public void addHandler(RASIHandler handler)
null
or is already
registered, this method does nothing.handler
- A RAS handler.public void removeHandler(RASIHandler handler)
null
or is not registered, this method does nothing.handler
- A RAS handler.public java.util.Enumeration getHandlers()
Enumeration
of handlers. If no handlers
are registered, the Enumeration
is empty.public void setSynchronous(boolean flag)
flag
- A boolean
set true
for
synchronous logging and false
otherwise.public boolean isSynchronous()
true
for synchronous logging and
false
otherwise.public boolean isLoggable(long type)
if (isLoggable(RASTraceEvent.TYPE_PUBLIC) trace(RASTraceEvent.TYPE_PUBLIC...);
type
- The type of the log entry. The set of possible values is
defined by the RASIMessageEvent.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()
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.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |