JRas extension classes
The JRas framework described in this task and its sub-tasks is deprecated. However, one can achieve similar results using Java logging.
WebSphere Application Server 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 WAS 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 stand-alone or combined mode, one can reuse the logger and manager class provided by the extensions, but provide your own implementations of handlers and formatters.
WebSphere Application Server Message and Trace loggers
The message and trace loggers provided by the stand-alone JRas logging toolkit cannot be directly used in the WAS 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 WAS 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 WAS Manager class are subclasses of the RASMessageLogger() and RASTraceLogger() classes provided by the stand-alone 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 namespaces 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 namespace 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 logger classes obtained from the Manager are thread-safe. Although the loggers provided as part of the stand-alone 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 WAS environment.
WebSphere Application Server handlers
WebSphere Application Server provides the appropriate handler class that is used to write message and trace events to the WAS run-time logs. We cannot configure the WAS handler to write to any other destination. The creation of a WAS 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. We can remove the WAS handler from a logger when you want to run in stand-alone mode. Once you have removed it, one cannot add the WAS handler again to the logger from which it was removed (or any other logger). Also, one cannot directly call any method on the WAS handler. Attempting to create an instance of the WAS handler, to call methods on the WAS handler or to add a WebSphere Application Server handler to a logger by user code is a violation of the programming model.
WebSphere Application Server formatters
The WAS handler comes preconfigured with the appropriate formatter for data that is written to WAS logs. The creation of a WAS 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 WAS handler, or to change the formatter a WAS handler is configured to use.
WebSphere Application Server manager
WebSphere Application Server 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. WAS provides the appropriate systems management facilities to manipulate the trace setting of a group, similar to the way 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). We can then turn on trace for a single class. Or one 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 namespace for trace loggers.