Package com.ibm.ras.mgr

The RAS Toolkit contained in the com.ibm.ras package is designed to stand on its own.  That is, an application developer can create the desired loggers and handlers, configure their masks, choose an output format, etc.  This may be suitable for "smaller" applications in which the trace state and output device can be hard-coded, or passed to the application when it starts.  In more complex environments, an application can be written to use a RAS Manager (part of the com.ibm.ras.mgr package) to acquire its logging configuration.  This generally lightens the load on the application programmer.

See:
          Description

Interface Summary
RASIDataStore RASIDataStore defines an interface to allow RAS configuration data to be saved to and restored from persistent storage (such as a properties file on disk).
 

Class Summary
RASBaseGroup RASBaseGroup is an extension of RASGroup.
RASConfig RASConfig contains the configuration data for a RAS object (a logger or handler).
RASDefaultDataStore RASDefaultDataStore is a default implementation of the RASIDataStore interface.
RASGroup RASGroup organizes the configuration data for a related set of RAS objects (loggers, handlers and formatters).
RASManager RASManager is a manager of RAS objects.
RASPropertyDataStore RASPropertyDataStore is an implementation of the RASIDataStore interface which uses a properties file of a specific format to contain the RAS configuration.
 

Package com.ibm.ras.mgr Description

The RAS Toolkit contained in the com.ibm.ras package is designed to stand on its own.  That is, an application developer can create the desired loggers and handlers, configure their masks, choose an output format, etc.  This may be suitable for "smaller" applications in which the trace state and output device can be hard-coded, or passed to the application when it starts.  In more complex environments, an application can be written to use a RAS Manager (part of the com.ibm.ras.mgr package) to acquire its logging configuration.  This generally lightens the load on the application programmer.

The RAS Manager (class com.ibm.ras.mgr.RASManager) deals primarily in configuration data.  That is, it must be told which RAS objects it can create, what their options are and how they are connected.  When an object, such as a message logger, is requested by an application, the RAS Manager creates it from its configuration data and returns the object.  Only one instance of a RAS object is created.  This allows different applications, or components of a single application, to share RAS objects.

To be useful, then, the RAS Manager must be able to get its configuration data from some type of persistent storage.  (Configuration data can be created programmatically and passed to the RAS Manager, but this is as much work, or more, than creating the objects themselves.)  This persistent store is modeled through the interface RASDataStore, which contains only two methods:  restoreConfig and saveConfig.  Two classes which implement RASDataStore are provided:

Classes can be written to support other persistent stores, as needed.

To use a RAS Manager, an application must first create one:

RASManager mgr = RASManager.getManager(new RASDefaultDataStore());
This static method ensures that only one RASManager is created.  Subsequent calls to getManager will return the existing RAS Manager.  Once a RAS Manager is instantiated, it can be used to retrieve a logger by name:
RASTraceLogger trcLogger = mgr.getTraceLogger("MyTrcLogger");
RASMessageLogger msgLogger = mgr.getMessageLogger("MyMsgLogger");
These objects can then, of course, be used to log message and trace data as described in the package com.ibm.ras.

When the RAS Manager is created, it loads its configuration from persistent store into a RASBaseGroup.  This group can contain message loggers, trace loggers, handlers and other groups (RASGroups, in fact).  Handlers are typically considered to be system-wide resources, so it is recommended that they be placed in the RASBaseGroup.  However, loggers are generally tied to an application, so each application should place its loggers in its own RASGroup.

The structure that results from this model is "flat" in that only the base group can contain other groups.  An application can impose a logical structure of groups within groups by carefully selecting group names.  One way to do this is to use a naming scheme similar to Java package names.  This would be very useful to a graphical problem that wished to display RAS configurations to an end-user.

Two major benefits follow from using groups: