|
|||||||||
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 | +--com.ibm.ras.RASMessageLogger
The RASMessageLogger
is one of two RASLogger
sub-classes provided in this package. (The other is
RASTraceLogger
.) The purpose of message logging is to
provide information to the users of an application. (Contrast this
with tracing, which is intended for software developers and service
teams.) As a general guideline, a message should be logged only if
the information it contains is of value to the user.
By default, message logging is on when a RASMessageLogger
is created.
Normally, the text for a set of messages is stored in one or more message files. Text strings are accessed by a "key," which is a name for the message text. This mechanism allows the message text to be separated from the program that uses it, making translation into different national languages easier.
A message logger, therefore, must be told which message files to search. Two mechanisms are available to accomplish this:
msg
methods in this class do this.
setMessageFile
method to register one message file
with the message logger. If more than one message file is required,
the msg
methods can be used with the additional message files.
The message
methods in this class assume that one
message file has been registered.
The message key can be any desired string. For example, a key
HUNGRY
might select the message text, "Are you ready
to eat?" This key may be displayed as part of a formatted message
and can be used more formally to identify messages. For example, instead
of HUNGRY
, the key might be RAS0001I
. In this
scheme the first three characters identify the product or, perhaps,
component -- the RAS Toolkit, in this case. The next four numbers select
a RAS message. The last character is set to I
for
informational messages, W
for warning messages and E
for error messages.
If a message file is not specified, or the message key is not found in the message file, an error message is formatted instead.
Run-time substitution of variables into the message text is possible.
The message, msg
and textMessage
methods accept
a number of Objects
whose String
representations
may be inserted into the message text according to the rules of the
java.text.MessageFormat
class. The only restriction is that
the Objects
are converted to Strings
before they
are passed to the MessageFormat class, so that the MessageFormat style options
(such as {1,time}
) may not be used.
If a message file is not specified or does not exist, or the message key is not found in the message file, an error message is formatted instead.
RASMessageLogger
provides the ability to suppress individual
messages. This feature might be used if a program were logging the same
message again and again and the system administrator did not want to see any
more of them. The addSuppressedKey
method is used to stop the
logging of specific messages.
The message
and msg
methods all include the name of
the class and method which generated the message. When logging messages in
non-static methods, you may use the methods that take "this" (the object
being traced) as the second parameter. This is a convenience to the
programmer, as the class name can be derived from any Object
.
For static methods, an object does not exist. Use the methods which take
"String className
" as the second parameter. Of course,
this latter approach may be used in all methods, if desired. It will
also result in better performance (significant if many messages are logged), as
the RAS system will not have to translate an Object
to a class name.
RASMessageLogger
provides minimal support for the
logging of plain text messages which do not use message catalogs.
The textMessage
methods are available for this. They are
provided as a convenience for an application developer who might want to
log a quick debug message that will not make it into the final product.
The textMessage
method takes an arbitrary text string in
place of a message key. Objects
may be included with the
message, but they are simply displayed with the message text (according to
their toString
representation), not substituted into the
message text.
RASMessageLogger
has several optional fields which may be
included in the message. These fields should not vary among
messages produced by a given RASMessageLogger
, so they are
not included in the message
methods of this class. They can,
however, be specified through a RASMessageLogger
constructor
or by the appropriate "set" and "get" methods of this class. These fields
are:
RASMessageLogger
supports three types of messages:
information, warning and error. For warning and error messages, you should
provide details telling the customer how to rectify the situation. These
types are formally defined in the RASIMessageEvent
class.
The message, msg
and textMessage
methods do not validate
the type assigned to a message, so an error could result in the failure
to log the message.
RASIMessageLogger
,
RASLogger
,
RASMessageEvent
,
RASHandler
Fields inherited from class com.ibm.ras.RASLogger |
isLogging |
Constructor Summary | |
RASMessageLogger()
Creates a RASMessageLogger . |
|
RASMessageLogger(java.lang.String name)
Creates a RASMessageLogger . |
|
RASMessageLogger(java.lang.String name,
java.lang.String desc)
Creates a RASMessageLogger . |
|
RASMessageLogger(java.lang.String name,
java.lang.String desc,
java.lang.String org,
java.lang.String prod,
java.lang.String comp,
java.lang.String server,
java.lang.String client)
Creates a RASMessageLogger . |
Method Summary | |
void |
addSuppressedKey(java.lang.String key)
Adds a message key to a set of keys which should not be logged. |
void |
exception(long type,
java.lang.Object obj,
java.lang.String methodName,
java.lang.Exception exc)
Logs an Exception in a non-static method. |
void |
exception(long type,
java.lang.String className,
java.lang.String methodName,
java.lang.Exception exc)
Logs an Exception in a static method. |
java.lang.String |
getComponent()
Gets the name of the component that is using this logger. |
java.util.Hashtable |
getConfig()
Gets the configuration of this object. |
java.lang.String |
getMessageFile()
Gets the message file associated with this logger. |
long |
getMessageMask()
Gets the mask which defines the set of message types that will be processed. |
java.lang.String |
getOrganization()
Gets the name of the organization which wrote the application that is using this logger. |
java.lang.String |
getProduct()
Gets the name of the product that is using this logger. |
java.util.Vector |
getSuppressedKeys()
Gets all of the suppressed message keys associated with this logger. |
void |
maskValueChanged()
Indicates that the value of the handler's message mask has changed. |
void |
message(long type,
java.lang.Object obj,
java.lang.String methodName,
java.lang.String key)
Logs a message, by key, with no parameters. |
void |
message(long type,
java.lang.Object obj,
java.lang.String methodName,
java.lang.String key,
java.lang.Object parm1)
Logs a message, by key, with one parameter. |
void |
message(long type,
java.lang.Object obj,
java.lang.String methodName,
java.lang.String key,
java.lang.Object[] parms)
Logs a message, by key, with an array of parameters. |
void |
message(long type,
java.lang.Object obj,
java.lang.String methodName,
java.lang.String key,
java.lang.Object parm1,
java.lang.Object parm2)
Logs a message, by key, with two parameters. |
void |
message(long type,
java.lang.String className,
java.lang.String methodName,
java.lang.String key)
Logs a message, by key, with no parameters. |
void |
message(long type,
java.lang.String className,
java.lang.String methodName,
java.lang.String key,
java.lang.Object parm1)
Logs a message, by key, with one parameter. |
void |
message(long type,
java.lang.String className,
java.lang.String methodName,
java.lang.String key,
java.lang.Object[] parms)
Logs a message, by key, with an array of parameters. |
void |
message(long type,
java.lang.String className,
java.lang.String methodName,
java.lang.String key,
java.lang.Object parm1,
java.lang.Object parm2)
Logs a message, by key, with two parameters. |
void |
msg(long type,
java.lang.Object obj,
java.lang.String methodName,
java.lang.String key,
java.lang.String file)
Logs a message, by key and file, with no parameters. |
void |
msg(long type,
java.lang.Object obj,
java.lang.String methodName,
java.lang.String key,
java.lang.String file,
java.lang.Object parm1)
Logs a message, by key and file with one parameter. |
void |
msg(long type,
java.lang.Object obj,
java.lang.String methodName,
java.lang.String key,
java.lang.String file,
java.lang.Object[] parms)
Logs a message, by key and file, with an array of parameters. |
void |
msg(long type,
java.lang.Object obj,
java.lang.String methodName,
java.lang.String key,
java.lang.String file,
java.lang.Object parm1,
java.lang.Object parm2)
Logs a message, by key and file, with two parameters. |
void |
msg(long type,
java.lang.String className,
java.lang.String methodName,
java.lang.String key,
java.lang.String file)
Logs a message, by key and file, with no parameters. |
void |
msg(long type,
java.lang.String className,
java.lang.String methodName,
java.lang.String key,
java.lang.String file,
java.lang.Object parm1)
Logs a message, by key and file, with one parameter. |
void |
msg(long type,
java.lang.String className,
java.lang.String methodName,
java.lang.String key,
java.lang.String file,
java.lang.Object[] parms)
Logs a message, by key and file, with an array of parameters. |
void |
msg(long type,
java.lang.String className,
java.lang.String methodName,
java.lang.String key,
java.lang.String file,
java.lang.Object parm1,
java.lang.Object parm2)
Logs a message, by key and file, with two parameters. |
void |
removeSuppressedKey(java.lang.String key)
Removes a message key from the set of keys which should not be logged. |
void |
setComponent(java.lang.String name)
Sets the name of the component that is using this logger. |
void |
setConfig(java.util.Hashtable ht)
Sets the configuration of this object. |
void |
setMessageFile(java.lang.String file)
Sets the message file associated with this logger. |
void |
setMessageMask(long mask)
Sets the mask which defines the set of message types that will be processed. |
void |
setOrganization(java.lang.String name)
Sets the name of the organization which wrote the application that is using this logger. |
void |
setProduct(java.lang.String name)
Sets the name of the product that is using this logger. |
void |
textMessage(long type,
java.lang.Object obj,
java.lang.String methodName,
java.lang.String text)
Logs a text message (no key) with no parameters. |
void |
textMessage(long type,
java.lang.Object obj,
java.lang.String methodName,
java.lang.String text,
java.lang.Object parm1)
Logs a text message (no key) with one parameter. |
void |
textMessage(long type,
java.lang.Object obj,
java.lang.String methodName,
java.lang.String text,
java.lang.Object[] parms)
Logs a text message (no key) with an array of parameters. |
void |
textMessage(long type,
java.lang.Object obj,
java.lang.String methodName,
java.lang.String text,
java.lang.Object parm1,
java.lang.Object parm2)
Logs a text message (no key) with two parameters. |
void |
textMessage(long type,
java.lang.String className,
java.lang.String methodName,
java.lang.String text)
Logs a text message (no key) with no parameters. |
void |
textMessage(long type,
java.lang.String className,
java.lang.String methodName,
java.lang.String text,
java.lang.Object parm1)
Logs a text message (no key) with one parameter. |
void |
textMessage(long type,
java.lang.String className,
java.lang.String methodName,
java.lang.String text,
java.lang.Object[] parms)
Logs a text message (no key) with an array of parameters. |
void |
textMessage(long type,
java.lang.String className,
java.lang.String methodName,
java.lang.String text,
java.lang.Object parm1,
java.lang.Object parm2)
Logs a text message (no key) with two parameters. |
Methods inherited from class com.ibm.ras.RASLogger |
addHandler,
getClient,
getHandlers,
getServer,
isLoggable,
isSynchronous,
removeHandler,
setClient,
setServer,
setSynchronous |
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 |
Constructor Detail |
public RASMessageLogger()
RASMessageLogger
. The name and
description of this object are empty strings.public RASMessageLogger(java.lang.String name)
RASMessageLogger
. The description
of this object is an empty string.name
- The name of this object.public RASMessageLogger(java.lang.String name, java.lang.String desc)
RASMessageLogger
.name
- The name of this object.desc
- The description of this object.public RASMessageLogger(java.lang.String name, java.lang.String desc, java.lang.String org, java.lang.String prod, java.lang.String comp, java.lang.String server, java.lang.String client)
RASMessageLogger
. (See the description in the
prologue for each of these elements.)name
- The name of this logger.desc
- The description of this logger.org
- The organization.prod
- The product.comp
- The component.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:
"organization" The organization. "product" The product. "component" The component. "messageMask" The mask which selects the message types to be processed. "messageFile" A message file name, used to translate message keys. "suppressedKeys" A blank-delimited set of message keys which are not to be processed.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:
"organization" The organization. "product" The product. "component" The component. "messageMask" The mask which selects the message types to be processed. "messageFile" A message file name, used to translate message keys. "suppressedKeys" A blank-delimited set of message keys which are not 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.public long getMessageMask()
RASIMessageEvent.TYPE_XXXX
constants.public void setMessageMask(long mask)
RASIMessageEvent.TYPE_XXXX
constants.
The mask value is not validated against these types.mask
- The message mask.public java.lang.String getOrganization()
public void setOrganization(java.lang.String name)
null
, the current
name is not changed.name
- The organization name.public java.lang.String getProduct()
public void setProduct(java.lang.String name)
null
, the current name is not changed.name
- The product name.public java.lang.String getComponent()
public void setComponent(java.lang.String name)
null
, the current name is not changed.name
- The component name.public java.lang.String getMessageFile()
null
if a message file
has not been added to the logger.public void setMessageFile(java.lang.String file)
null
, the current message file is not changed.
If the message file does not exist, a message indicating this will
be displayed in place of the formatted message.file
- The message file name.public void addSuppressedKey(java.lang.String key)
null
or is already registered, this method does nothing.key
- The message key which is not to be logged.public void removeSuppressedKey(java.lang.String key)
null
or is not registered, this method
does nothing.key
- The message key to be removed.public java.util.Vector getSuppressedKeys()
Vector
of message keys. If no suppressed keys
are registered, the Vector
is empty.public void message(long type, java.lang.Object obj, java.lang.String methodName, java.lang.String key)
type
- The type of the message.obj
- The logging object ("this").methodName
- The name of the logging method.key
- The message key.public void message(long type, java.lang.Object obj, java.lang.String methodName, java.lang.String key, java.lang.Object parm1)
type
- The type of the message.obj
- The logging object ("this").methodName
- The name of the logging method.key
- The message key.parm1
- An element to be inserted into the message.public void message(long type, java.lang.Object obj, java.lang.String methodName, java.lang.String key, java.lang.Object parm1, java.lang.Object parm2)
type
- The type of the message.obj
- The logging object ("this").methodName
- The name of the logging method.key
- The message key.parm1
- An element to be inserted into the message.parm2
- An element to be inserted into the message.public void message(long type, java.lang.Object obj, java.lang.String methodName, java.lang.String key, java.lang.Object[] parms)
type
- The type of the message.obj
- The logging object ("this").methodName
- The name of the logging method.key
- The message key.parms
- An array of elements to be inserted into the message.public void message(long type, java.lang.String className, java.lang.String methodName, java.lang.String key)
type
- The type of the message.className
- The name of the logging class.methodName
- The name of the logging method.key
- The message key.public void message(long type, java.lang.String className, java.lang.String methodName, java.lang.String key, java.lang.Object parm1)
type
- The type of the message.className
- The name of the logging class.methodName
- The name of the logging method.key
- The message key.parm1
- An element to be inserted into the message.public void message(long type, java.lang.String className, java.lang.String methodName, java.lang.String key, java.lang.Object parm1, java.lang.Object parm2)
type
- The type of the message.className
- The name of the logging class.methodName
- The name of the logging method.key
- The message key.parm1
- An element to be inserted into the message.parm2
- An element to be inserted into the message.public void message(long type, java.lang.String className, java.lang.String methodName, java.lang.String key, java.lang.Object[] parms)
type
- The type of the message.className
- The name of the logging class.methodName
- The name of the logging method.key
- The message key.parms
- An array of elements to be inserted into the message.public void msg(long type, java.lang.Object obj, java.lang.String methodName, java.lang.String key, java.lang.String file)
type
- The type of the message.obj
- The logging object ("this").methodName
- The name of the logging method.key
- The message key.file
- The name of the message file to use.public void msg(long type, java.lang.Object obj, java.lang.String methodName, java.lang.String key, java.lang.String file, java.lang.Object parm1)
type
- The type of the message.obj
- The logging object ("this").methodName
- The name of the logging method.key
- The message key.file
- The name of the message file to use.parm1
- An element to be inserted into the message.public void msg(long type, java.lang.Object obj, java.lang.String methodName, java.lang.String key, java.lang.String file, java.lang.Object parm1, java.lang.Object parm2)
type
- The type of the message.obj
- The logging object ("this").methodName
- The name of the logging method.key
- The message key.file
- The name of the message file to use.parm1
- An element to be inserted into the message.parm2
- An element to be inserted into the message.public void msg(long type, java.lang.Object obj, java.lang.String methodName, java.lang.String key, java.lang.String file, java.lang.Object[] parms)
type
- The type of the message.obj
- The logging object ("this").methodName
- The name of the logging method.key
- The message key.file
- The name of the message file to use.parms
- An array of elements to be inserted into the message.public void msg(long type, java.lang.String className, java.lang.String methodName, java.lang.String key, java.lang.String file)
type
- The type of the message.className
- The name of the logging class.methodName
- The name of the logging method.key
- The message key.file
- The name of the message file to use.public void msg(long type, java.lang.String className, java.lang.String methodName, java.lang.String key, java.lang.String file, java.lang.Object parm1)
type
- The type of the message.className
- The name of the logging class.methodName
- The name of the logging method.key
- The message key.file
- The name of the message file to use.parm1
- An element to be inserted into the message.public void msg(long type, java.lang.String className, java.lang.String methodName, java.lang.String key, java.lang.String file, java.lang.Object parm1, java.lang.Object parm2)
type
- The type of the message.className
- The name of the logging class.methodName
- The name of the logging method.key
- The message key.file
- The name of the message file to use.parm1
- An element to be inserted into the message.parm2
- An element to be inserted into the message.public void msg(long type, java.lang.String className, java.lang.String methodName, java.lang.String key, java.lang.String file, java.lang.Object[] parms)
type
- The type of the message.className
- The name of the logging class.methodName
- The name of the logging method.key
- The message key.file
- The name of the message file to use.parms
- An array of elements to be inserted into the message.public void textMessage(long type, java.lang.Object obj, java.lang.String methodName, java.lang.String text)
type
- The type of the message.obj
- The logging object ("this").methodName
- The name of the logging method.text
- The message text.public void textMessage(long type, java.lang.Object obj, java.lang.String methodName, java.lang.String text, java.lang.Object parm1)
type
- The type of the message.obj
- The logging object ("this").methodName
- The name of the logging method.text
- The message text.parm1
- An element to be displayed with the message.public void textMessage(long type, java.lang.Object obj, java.lang.String methodName, java.lang.String text, java.lang.Object parm1, java.lang.Object parm2)
type
- The type of the message.obj
- The logging object ("this").methodName
- The name of the logging method.text
- The message text.parm1
- An element to be displayed with the message.parm2
- An element to be displayed with the message.public void textMessage(long type, java.lang.Object obj, java.lang.String methodName, java.lang.String text, java.lang.Object[] parms)
type
- The type of the message.obj
- The logging object ("this").methodName
- The name of the logging method.text
- The message text.parms
- An array of elements to be displayed with the message.public void textMessage(long type, java.lang.String className, java.lang.String methodName, java.lang.String text)
type
- The type of the message.className
- The name of the logging class.methodName
- The name of the logging method.text
- The message text.public void textMessage(long type, java.lang.String className, java.lang.String methodName, java.lang.String text, java.lang.Object parm1)
type
- The type of the message.className
- The name of the logging class.methodName
- The name of the logging method.text
- The message text.parm1
- An element to be displayed with the message.public void textMessage(long type, java.lang.String className, java.lang.String methodName, java.lang.String text, java.lang.Object parm1, java.lang.Object parm2)
type
- The type of the message.className
- The name of the logging class.methodName
- The name of the logging method.text
- The message text.parm1
- An element to be displayed with the message.parm2
- An element to be displayed with the message.public void textMessage(long type, java.lang.String className, java.lang.String methodName, java.lang.String text, java.lang.Object[] parms)
type
- The type of the message.className
- The name of the logging class.methodName
- The name of the logging method.text
- The message text.parms
- An array of elements to be displayed with the message.public void exception(long type, java.lang.Object obj, java.lang.String methodName, java.lang.Exception exc)
Exception
in a non-static method.type
- The type of the trace point.obj
- The traced object ("this").methodName
- The name of the traced method.exc
- An exception.public void exception(long type, java.lang.String className, java.lang.String methodName, java.lang.Exception exc)
Exception
in a static method.type
- The type of the trace point.className
- The name of the traced class.methodName
- The name of the traced method.exc
- An exception.public 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 |