The standalone JRas logging toolkit defines interfaces and provides a variety of concrete classes that implement these interfaces. Since the standalone JRas logging toolkit was developed as a general purpose toolkit, the implementation classes do not contain the configuration interfaces and methods necessary for use in the WebSphere Application Server - Express product. In addition, many of the implementation classes are not written appropriately for use in a J2EE environment. To overcome these shortcomings, WebSphere Application Server - Express provides the appropriate implementation classes that allow integration into the WebSphere Application Server - Express environment. The collection of these implementation classes is referred to as the JRas extensions.
JRas extensions
You can use the JRas extensions in three distinct operational modes:
In this mode, message and trace records are written only to logs defined and maintained by the WebSphere Application Server - Express runtime. This is the default mode of operation and is equivalent to the WebSphere Application Server V4.0 mode of operation.
In this mode, message and trace records are written solely to standalone logs defined and maintained by the user. You control which categories of events are written to which logs, and the format in which entries are written. You are responsible for configuration and maintenance of the logs. Message and trace entries are not written to WebSphere Application Server - Express runtime logs.
In this mode message and trace records are written to both WebSphere Application Server - Express runtime logs and to standalone logs that you must define, control, and maintain. You can use filtering controls to determine which categories of messages and trace are written to which logs.
The JRas extensions are specifically targeted to an integrated mode of operation. The integrated mode of operation can be appropriate for some usage scenarios, but there are many scenarios that are not adequately addressed by these extensions. Many usage scenarios require a standalone or combined mode of operation instead. A set of user extension points has been defined that allow the JRas extensions to be used in either a standalone or combined mode of operations.
JRas extension classes
WebSphere Application Server - Express provides a base set of implementation classes that collectively are referred to as the JRas extensions. Many of these classes provide the appropriate implementations of loggers, handlers and formatters for use in a WebSphere Application Server - Express environment. As previously noted, this collection of classes is targeted at an Integrated mode of operation. If you choose to use the JRas extensions in either standalone or combined mode, you can reuse the logger and manager class provided by the extensions, but you must provide your own implementations of handlers and formatters.
WebSphere Application Server - Express Message and Trace loggers
The message and trace loggers provided by the standalone JRas logging toolkit cannot be directly used in the WebSphere Application Server - Express environment. The JRas extensions provide the appropriate logger implementation classes. Instances of these message and trace logger classes are obtained directly and exclusively from the WebSphere Application Server - Express Manager class, described below. You cannot directly instantiate message and trace loggers. Obtaining loggers in any manner other than directly from the Manager is not allowed. Doing so is a direct violation of the programming model.
The message and trace loggers instances obtained from the WebSphere Application Server - Express Manager class are subclasses of the RASMessageLogger() and RASTraceLogger() classes provided by the standalone JRas logging toolkit. The RASMessageLogger() and RASTraceLogger() classes define the set of methods that are directly available. Public methods introduced by the JRas extensions logger subclasses cannot be called directly by user code. Doing so is a violation of the programming model.
Loggers are named objects and are identified by name. When the Manager class is called to obtain a logger, the caller is required to specify a name for the logger. The Manager class maintains a name-to-logger instance mapping. Only one instance of a named logger will ever be created within the lifetime of a process. The first call to the Manager with a particular name will result in the logger being created and configured by the Manager. The Manager will cache a reference to the instance, then return it to the caller. Subsequent calls to the Manager that specify the same name will result in a reference to the cached logger being returned. Separate name spaces are maintained for message and trace loggers. This means a single name can be used to obtain both a message logger and a trace logger from the Manager, without ambiguity, and without causing a name space collision.
In general, loggers have no predefined granularity or scope. A single logger could be used to instrument an entire application. Or users may determine that having a logger per class is more desirable. Or the appropriate granularity may lie somewhere in between. Partitioning an application into logging domains is rightfully determined by the application writer.
The WebSphere Application Server - Express logger classes obtained from the Manager are thread-safe. Although the loggers provided as part of the standalone JRas logging toolkit implement the serializable interface, in fact loggers are not serializable. Loggers are stateful objects, tied to a Java virtual machine instance and are not serializable. Attempting to serialize a logger is a violation of the programming model.
Please note that there is no provision for allowing users to provide their own logger subclasses for use in a WebSphere Application Server - Express environment.
WebSphere Application Server - Express handlers
WebSphere Application Server - Express provides the appropriate handler class that is used to write message and trace events to the WebSphere Application Server - Express runtime logs. You cannot configure the WebSphere Application Server - Express handler to write to any other destination. The creation of a WebSphere Application Server - Express handler is a restricted operation and not available to user code. Every logger obtained from the Manager comes preconfigured with an instance of this handler already installed. You can remove the WebSphere Application Server - Express handler from a logger when you want to run in standalone mode. Once you have removed it, you cannot re-add the WebSphere Application Server - Express handler to the logger from which it was removed (or any other logger). Also, you cannot directly call any method on the WebSphere Application Server - Express handler. Attempting to create an instance of the WebSphere Application Server - Express handler, to call methods on the WebSphere Application Server - Express handler or to add a WebSphere Application Server - Express handler to a logger by user code is a violation of the programming model.
WebSphere Application Server - Express formatters
The WebSphere Application Server - Express handler comes preconfigured with the appropriate formatter for data that is written to WebSphere Application Server - Express logs. The creation of a WebSphere Application Server - Express formatter is a restricted operation and not available to user code. No mechanism exists that allows the user to obtain a reference to a formatter installed in a WebSphere Application Server - Express handler, or to change the formatter a WebSphere Application Server - Express handler is configured to use.
WebSphere Application Server - Express manager
WebSphere Application Server - Express provides a Manager class located in the com.ibm.websphere.ras package. All message and trace loggers must be obtained from this Manager. A reference to the Manager is obtained by calling the static Manager.getManager() method. Message loggers are obtained by calling the createRASMessageLogger() method on the Manager. Trace loggers are obtained by calling the createRASTraceLogger() method on the Manager class.
The manager also supports a group abstraction that is useful when dealing with trace loggers. The group abstraction allows multiple, unrelated trace loggers to be registered as part of a named entity called a group. WebSphere Application Server - Express provides the appropriate systems management facilities to manipulate the trace setting of a group, similar to the trace settings of an individual trace logger.
For example, suppose component A consist of 10 classes. Suppose each class is configured to use a separate trace logger. Suppose all 10 trace loggers in the component are registered as members of the same group (for example Component_A_Group). You can then turn on trace for a single class. Or you can turn on trace for all 10 classes in a single operation using the group name if you want a component trace. Group names are maintained within the name space for trace loggers.