JRas extensions

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 WAS product. In addition, many of the implementation classes are not written appropriately for use in a J2EE environment. To overcome these shortcomings, WAS provides the appropriate implementation classes that allow integration into the WAS environment. The collection of these implementation classes is referred to as the JRas extensions.

JRas extensions

Use the JRas extensions in three distinct operational modes:

• Integrated

  In this mode, message and trace records are written only to logs defined and maintained by the WAS runtime. This is the default mode of operation and is equivalent to the WAS 4.0 mode of operation.

• Standalone

  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 WAS runtime logs.

• Combined

  In this mode message and trace records are written to both WAS runtime logs and to standalone logs that define, control, and maintain. 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 many scenarios 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

WAS 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 standalone or combined mode, you can reuse the logger and manager class provided by the extensions, but provide your own implementations of handlers and formatters.

• WAS Message and Trace loggers

  The message and trace loggers provided by the standalone 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 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 WAS 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 WAS environment.

• WAS handlers

  WAS provides the appropriate handler class that is used to write message and trace events to the WAS runtime logs. You 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. You can remove the WAS handler from a logger when you want to run in standalone mode. Once you have removed it, you cannot re-add the WAS handler to the logger from which it was removed (or any other logger). Also, you 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 WAS handler to a logger by user code is a violation of the programming model.

• WAS 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.

• WAS manager

  WAS 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). 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.