The RASLogger class is the parent of all classes which create message or trace data. When constructing a RASLogger, a name by which this RASLogger is known should be specified. We recommend that a description also be provided. In simple environments, say, in which a Java application is being developed for personal use, a RASLogger description may not be necessary. But, in more complex environments, such as a business in which many applets are served, a "RAS manager" may be included to provide graphical tools which control message and trace logging. Here, the name is required and a description of each RASLogger is very useful.
Before you can use a RASLogger, you must associate with it at least one RASHandler. Use the RASLogger.addHandler method to accomplish this. It is possible to associate more than one RASHandler with a RASLogger to send the log entries to multiple destinations, possibly formatted differently for each. RASLogger is an abstract class because it lacks methods to send data to its RASHandlers. Extensions to RASLogger, RASMessageLogger and RASTraceLogger provide these functions for message logging and tracing, respectively.
RASHandler is the parent of all classes which process the output of the RASLogger classes. A RASHandler may be configured directly, but the convenience classes RASConsoleHandler, RASFileHandler and RASSocketHandler are provided to direct log entries to the console, a file or a TCP socket, respectively.
Since it is possible to direct both message and trace data to the same destination (the console or a socket, for example), the RASHandler has methods to support the logging of message and trace data. However, if the message and trace data are bound for different destinations (two separate files, for example), two RASHandlers can be configured. Naturally, only the methods appropriate to the type of logged data will be used in each RASHandler.
For those applications which would rather be, rather than use, loggers or handlers, interfaces are provided to allow such implementations:
The logging service provides for three different types of log messages: informational, warning and error. For warning and error messages, you would normally provide details telling the customer how to rectify the situation.
The RASMessageLogger class extends RASLogger to provide message-specific function. By default, message logging is enabled when a RASMessageLogger is created.
Since message logging is intended to provide information to the end-user of an application, message texts must be translated into different national languages and displayed according to a selected locale. 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 file to search. Two mechanisms are available to accomplish this:
Message files are implemented in the RAS Toolkit through ResourceBundles. Typically, applications will use either a ListResourceBundle or a PropertyResourceBundle to contains its messages. The choice is arbitrary, though some believe that there is less chance of translation problems with the PropertyResourceBundle, which just contains a set of "key=value" pairs and no Java code.
The message and msg methods each include in their parameters the name of the class and method which generated the message. In all cases, one can use the methods which take String className as the second parameter. When tracing in non-static methods, one can use the message and msg 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. (In static methods, an object does not exist, so these methods cannot be used.) The price for convenience, however, is performance. It takes more effort to derive the class name from "this" than to use the hard-coded string.
The format method in the RASMessageEvent class makes use of the java.text.MessageFormat class to substitute into the message text information known only at run-time. Consider the following. In a message file, a key/message pair might be:
HOT_DAY=On {0}, it is {1} degrees.Your message method call might be:
String day = "Monday";The logged message text is: "On Monday, it is 75 degrees."
Integer temp = new Integer(75);
logger.message(RASMessageEvent.INFO, this, "methodName", "HOT_DAY", day, temp);
To support this variable substitution, an overloaded set of message and msg methods is provided by RASMessageLogger that take zero to two individual objects. One method (of each type) takes an array of inserts, to handle any cases in which a message requires more than two inserts.
1999.01.05 11:11:03.612 com.ibm.ras.samples.RASSample messageSample IBM Cool Java Stuff Communications orion.raleigh.ibm.com JohnDoe Starting the RAS Log Server.
The components of the message are:
It is tempting to leave the addition of trace to your code until the very end of your development cycle. Experience shows this to be a mistake. If done correctly, a trace facility can be a great aid in tracking down and solving bugs during development. If you find that your trace files are not helping you in problem diagnosis, then they most likely do not contain sufficient information. If you can't find a problem in your code using a trace file, what chance will a service team have? Bite the bullet, improve your tracing!
The RASTraceLogger class extends RASLogger to provide trace-specific function. By default, tracing is disabled when a RASTraceLogger is created. Four groups of methods are available to trace program flow and key checkpoints:
Because tracing is intended for developers and service teams, no provision for the translation of trace data to different national languages is provided.
As a convenience, the entry and exit methods will automatically add TYPE_ENTRY_EXIT to the type specified on the method call. The set of trace types can be altered, if necessary, by extending the RASTraceEvent class.
06:56:34:965 Thread-1 TLogger RASTest run
Test trace logging
11:11:02.921 com.ibm.ras.samples.RASSample traceSample Thread-1
TrcLogger Trace is valuable when Bad Things happen to Gooodd Code.
The components of the trace entry are:
if (traceLogger.isLogging)For additional control, the RASTraceLogger.isLoggable method will compare the type associated with trace point with the mask of the RASTraceLogger and each configured RASHandler. It will return true if the logger and at least one of the handlers will process the trace point. Thus, the overhead of building the trace entry is avoided if no object is configured to process it. An example:
traceLogger.trace(...);
if (traceLogger.isLoggable(RASTraceEvent.TYPE_PUBLIC)
traceLogger.trace(RASTraceEvent.TYPE_PUBLIC,...);
For finer control, every log point (a place in an application where a call is made to the RAS Toolkit to log message or trace data) is associated with a "type." For example, a message type might be "warning," or "error." The set of possible message types is different than the set of trace types and are defined in the RASMessageEvent and RASTraceEvent classes, respectively.
In general, the type of a log point can be the logical OR of any of the types defined by the RASIMessageEvent or RASITraceEvent TYPE_XXXX constants. Be careful in assigning types, as certain combinations do not make sense. For example, TYPE_ENTRY_EXIT | TYPE_PUBLIC makes sense and defines the point as an entry to or exit from a public method. However, TYPE_PUBLIC | TYPE_PRIVATE doesn't make much sense. A method can't be public and private at the same time.
Loggers and handlers make use of a "mask," which determines the set of types that it will process. Message and trace data are handled separately, so each type of data has its own mask, which can be changed by the setMessageMask and setTraceMask methods, respectively. When a log entry is processed, its type is compared to the mask. If the type is contained in the mask, the log entry is processed; otherwise, it is not. For example, an informational message will not be processed if the logger's mask only includes warning messages. It will be processed if the logger's mask is set for informational and warning messages.
Although nothing prohibits this, in general, one would not manipulate the masks of both the loggers and the handlers. It can be very confusing! But, different effects can be achieved by controlling the masks in the loggers or the handlers. A few examples:
Chris Barlock
barlock@us.ibm.com
(919) 254-9964
IBM Tie-line 444-9964