com.ibm.ras.mgr
Class RASManager

java.lang.Object
  |
  +--com.ibm.ras.mgr.RASManager

public class RASManager
extends java.lang.Object

RASManager is a manager of RAS objects. It is an additional feature to the RAS Toolkit. That is, an application can use the RAS Tookit without a RAS Manager by creating all of the required toolkit objects in an application. 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 to acquire its logging configuration. This generally lightens the load on the application programmer.

The RAS Manager can also provide RAS configuration information to a graphical program, which would allow an end-user or administrator to reconfigure the RAS system -- turning specific loggers on or off, for example.

The RAS Manager 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.

In some environments, a RAS Manager may be able to get its initial configuration from persistent storage (such as a properties file or an LDAP database) and, possibly, save it there as well. This medium is represented by the RASIDataStore interface, whose restoreConfig and saveConfig methods provide this function. Two examples of a RASIDataStore are provided in this package:

If a persistent store is not available, the RAS Manager is generally not interesting. The configuration can be built by creating one or more RASGroups and passing this to the RAS Manager through the setConfig method. However, this is more work than managing the RAS objects in the application, itself.

The RAS Manager configuration is organized as one or more "groups." Groups are a way for an application to distinguish its loggers and handlers from others that may be controlled by the RAS Manager. It is recommended that each application organize its loggers into one or more RAS groups. Handlers are usually considered to be system-wide resources and are, therfore, typically contained in the "base group."

This base group can also contain other groups. The RAS Manager thus implements a "flat tree" of groups. That is, groups may only be added to the base group. 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.

An application normally only uses the getMessageLogger and getTraceLogger methods. The RAS Manager will attach to the logger any handlers which are included in the logger's configuration and any formatters which are included in the handler's configuration. The RAS Manager will search the group containing the logger and then the base group for the handler configuration information. If no handlers are included in the logger's configuration, the RAS Manager will use the set of default handlers instead. Formatter configurations are searched for in the same manner as handler configurations.

See Also:
RASIDataStore, RASGroup, RASBaseGroup

Method Summary
 void addDataStore(RASIDataStore store)
          Adds a RASIDataStore to this manager.
 RASBaseGroup getBaseGroup()
          Gets the entire RAS configuration.
 java.util.Enumeration getDataStores()
          Gets the data store objects in use by this manager.
 RASIFormatter getFormatter(java.lang.String name)
          Gets a formatter from the base group.
 RASIFormatter getFormatter(java.lang.String name, RASGroup group)
          Gets a formatter from a group.
 RASIFormatter getFormatter(java.lang.String name, java.lang.String groupName)
          Gets a formatter from the named group.
 RASIHandler getHandler(java.lang.String name)
          Gets a handler from the base group.
 RASIHandler getHandler(java.lang.String name, RASGroup group)
          Gets a handler from a group.
 RASIHandler getHandler(java.lang.String name, java.lang.String groupName)
          Gets a handler from the named group.
static RASManager getManager()
          Gets the RASManager.
static RASManager getManager(RASIDataStore store)
          Gets the RASManager.
 RASIMessageLogger getMessageLogger(java.lang.String name)
          Gets a message logger from the base group.
 RASIMessageLogger getMessageLogger(java.lang.String name, RASGroup group)
          Gets a message logger from a group.
 RASIMessageLogger getMessageLogger(java.lang.String name, java.lang.String groupName)
          Gets a message logger from the named group.
 RASITraceLogger getTraceLogger(java.lang.String name)
          Gets a trace logger from the base group.
 RASITraceLogger getTraceLogger(java.lang.String name, RASGroup group)
          Gets a trace logger from a group.
 RASITraceLogger getTraceLogger(java.lang.String name, java.lang.String groupName)
          Gets a trace logger from the named group.
 void removeDataStore(RASIDataStore store)
          Removes a RASIDataStore from this manager.
 void restoreConfig()
          Restores the RASManager configuration from persistent storage.
 void returnFormatter(RASIFormatter formatter)
          Returns a formatter to the base group.
 void returnFormatter(RASIFormatter formatter, RASGroup group)
          Returns a formatter to a group.
 void returnFormatter(RASIFormatter formatter, java.lang.String groupName)
          Returns a formatter to the named group.
 void returnHandler(RASIHandler handler)
          Returns a handler to the base group.
 void returnHandler(RASIHandler handler, RASGroup group)
          Returns a handler to a group.
 void returnHandler(RASIHandler handler, java.lang.String groupName)
          Returns a handler to the named group.
 void returnMessageLogger(RASIMessageLogger logger)
          Returns a message logger to the base group.
 void returnMessageLogger(RASIMessageLogger logger, RASGroup group)
          Returns a message logger to a group.
 void returnMessageLogger(RASIMessageLogger logger, java.lang.String groupName)
          Returns a message logger to the named group.
 void returnTraceLogger(RASITraceLogger logger)
          Returns a trace logger to the base group.
 void returnTraceLogger(RASITraceLogger logger, RASGroup group)
          Returns a trace logger to a group.
 void returnTraceLogger(RASITraceLogger logger, java.lang.String groupName)
          Returns a trace logger to the named group.
 void saveConfig()
          Saves the RASManager configuration to persistent storage.
 void setBaseGroup(RASBaseGroup baseGroup)
          Sets the entire RAS configuration.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getManager

public static RASManager getManager()
Gets the RASManager. If the RAS Manager has already been created through a previous call to getManager, that manager is returned. Otherwise, a new manager is created and returned.

A manager created with this method has no data store from which it can read a configuration. The addDataStore method can be used to add a data store to an existing manager.

Returns:
The RAS manager.

getManager

public static RASManager getManager(RASIDataStore store)
Gets the RASManager. If the RAS Manager has already been created through a previous call to getManager, that manager is returned. Otherwise, a new manager is created and returned.
Parameters:
store - An object which implements the RASIDataStore interface.
Returns:
The RAS manager.

addDataStore

public void addDataStore(RASIDataStore store)
Adds a RASIDataStore to this manager.

(In this implementation, only one data store is supported. A new data store simply replaces the current store.)

Parameters:
store - An object which implements the RASIDataStore interface.

removeDataStore

public void removeDataStore(RASIDataStore store)
Removes a RASIDataStore from this manager.

(In this implementation, only one data store is supported. If the requested store is in use, it is removed. Otherwise, nothing is changed.)

Parameters:
store - An object which implements the RASIDataStore interface.

getDataStores

public java.util.Enumeration getDataStores()
Gets the data store objects in use by this manager.

(In this implementation, only one data store is supported. It is returned in a Vector to support future enhancements.)

Returns:
An Enumeration of data stores.

getMessageLogger

public RASIMessageLogger getMessageLogger(java.lang.String name)
Gets a message logger from the base group.

If the logger configuration includes handlers, they will automatically be attached to the logger. It should not be necessary for an application to use the getHandler method.

Parameters:
name - The name of the message logger.
Returns:
A message logger or null if the requested logger was not found.

getMessageLogger

public RASIMessageLogger getMessageLogger(java.lang.String name,
                                          java.lang.String groupName)
Gets a message logger from the named group.

If the logger configuration includes handlers, they will automatically be attached to the logger. It should not be necessary for an application to use the getHandler method.

Parameters:
name - The name of the message logger.
groupName - The name of the RASGroup.
Returns:
A message logger or null if the requested logger was not found.

getMessageLogger

public RASIMessageLogger getMessageLogger(java.lang.String name,
                                          RASGroup group)
Gets a message logger from a group.

If the logger configuration includes handlers, they will automatically be attached to the logger. It should not be necessary for an application to use the getHandler method.

Parameters:
name - The name of the message logger.
group - The RASGroup.
Returns:
A message logger or null if the requested logger was not found.

returnMessageLogger

public void returnMessageLogger(RASIMessageLogger logger)
Returns a message logger to the base group.

If the logger configuration includes handlers, they will automatically be detached from the logger. It should not be necessary for an application to use the returnHandler method.

Parameters:
logger - The logger being returned.

returnMessageLogger

public void returnMessageLogger(RASIMessageLogger logger,
                                java.lang.String groupName)
Returns a message logger to the named group.

If the logger configuration includes handlers, they will automatically be detached from the logger. It should not be necessary for an application to use the returnHandler method.

Parameters:
logger - The logger being returned.
groupName - The name of the RASGroup.

returnMessageLogger

public void returnMessageLogger(RASIMessageLogger logger,
                                RASGroup group)
Returns a message logger to a group.

If the logger configuration includes handlers, they will automatically be detached from the logger. It should not be necessary for an application to use the returnHandler method.

Parameters:
logger - The logger being returned.
group - The RASGroup.

getTraceLogger

public RASITraceLogger getTraceLogger(java.lang.String name)
Gets a trace logger from the base group.

If the logger configuration includes handlers, they will automatically be attached to the logger. It should not be necessary for an application to use the getHandler method.

Parameters:
name - The name of the trace logger.
Returns:
A trace logger or null if the requested logger was not found.

getTraceLogger

public RASITraceLogger getTraceLogger(java.lang.String name,
                                      java.lang.String groupName)
Gets a trace logger from the named group.

If the logger configuration includes handlers, they will automatically be attached to the logger. It should not be necessary for an application to use the getHandler method.

Parameters:
name - The name of the trace logger.
groupName - The name of the RASGroup.
Returns:
A trace logger or null if the requested logger was not found.

getTraceLogger

public RASITraceLogger getTraceLogger(java.lang.String name,
                                      RASGroup group)
Gets a trace logger from a group.

If the logger configuration includes handlers, they will automatically be attached to the logger. It should not be necessary for an application to use the getHandler method.

Parameters:
name - The name of the trace logger.
group - The RASGroup.
Returns:
A trace logger or null if the requested logger was not found.

returnTraceLogger

public void returnTraceLogger(RASITraceLogger logger)
Returns a trace logger to the base group.

If the logger configuration includes handlers, they will automatically be detached from the logger. It should not be necessary for an application to use the returnHandler method.

Parameters:
logger - The logger being returned.

returnTraceLogger

public void returnTraceLogger(RASITraceLogger logger,
                              java.lang.String groupName)
Returns a trace logger to the named group.

If the logger configuration includes handlers, they will automatically be detached from the logger. It should not be necessary for an application to use the returnHandler method.

Parameters:
logger - The logger being returned.
groupName - The name of the RASGroup.

returnTraceLogger

public void returnTraceLogger(RASITraceLogger logger,
                              RASGroup group)
Returns a trace logger to a group.

If the logger configuration includes handlers, they will automatically be detached from the logger. It should not be necessary for an application to use the returnHandler method.

Parameters:
logger - The logger being returned.
group - The RASGroup.

getHandler

public RASIHandler getHandler(java.lang.String name)
Gets a handler from the base group.

If the logger configuration includes handlers, they will automatically be attached to the logger. It should not be necessary for an application to use the getHandler method.

Parameters:
name - The name of the handler.
Returns:
A handler or null if the requested handler was not found.

getHandler

public RASIHandler getHandler(java.lang.String name,
                              java.lang.String groupName)
Gets a handler from the named group.

If the logger configuration includes handlers, they will automatically be attached to the logger. It should not be necessary for an application to use the getHandler method.

Parameters:
name - The name of the handler.
groupName - The name of the RASGroup.
Returns:
A handler or null if the requested handler was not found.

getHandler

public RASIHandler getHandler(java.lang.String name,
                              RASGroup group)
Gets a handler from a group.

If the logger configuration includes handlers, they will automatically be attached to the logger. It should not be necessary for an application to use the getHandler method.

Parameters:
name - The name of the handler.
group - The RASGroup.
Returns:
A handler or null if the requested handler was not found.

returnHandler

public void returnHandler(RASIHandler handler)
Returns a handler to the base group.

If the logger configuration includes handlers, they will automatically be detached from the logger. It should not be necessary for an application to use the returnHandler method.

Parameters:
handler - The handler being returned.

returnHandler

public void returnHandler(RASIHandler handler,
                          java.lang.String groupName)
Returns a handler to the named group.

If the logger configuration includes handlers, they will automatically be detached from the logger. It should not be necessary for an application to use the returnHandler method.

Parameters:
handler - The handler being returned.
groupName - The name of the RASGroup.

returnHandler

public void returnHandler(RASIHandler handler,
                          RASGroup group)
Returns a handler to a group.

If the logger configuration includes handlers, they will automatically be detached from the logger. It should not be necessary for an application to use the returnHandler method.

Parameters:
handler - The handler being returned.
group - The RASGroup.

getFormatter

public RASIFormatter getFormatter(java.lang.String name)
Gets a formatter from the base group.

If the handler configuration includes formatters, they will automatically be attached to the handler. It should not be necessary for an application to use the getFormatter method.

Parameters:
name - The name of the formatter.
Returns:
A formatter or null if the requested formatter was not found.

getFormatter

public RASIFormatter getFormatter(java.lang.String name,
                                  java.lang.String groupName)
Gets a formatter from the named group.

If the handler configuration includes formatters, they will automatically be attached to the handler. It should not be necessary for an application to use the getFormatter method.

Parameters:
name - The name of the formatter.
groupName - The name of the RASGroup.
Returns:
A formatter or null if the requested formatter was not found.

getFormatter

public RASIFormatter getFormatter(java.lang.String name,
                                  RASGroup group)
Gets a formatter from a group.

If the handler configuration includes formatters, they will automatically be attached to the handler. It should not be necessary for an application to use the getFormatter method.

Parameters:
name - The name of the formatter.
group - The RASGroup.
Returns:
A formatter or null if the requested formatter was not found.

returnFormatter

public void returnFormatter(RASIFormatter formatter)
Returns a formatter to the base group.

If the handler configuration includes formatters, they will automatically be detached from the handler. It should not be necessary for an application to use the returnFormatter method.

Parameters:
formatter - The formatter being returned.

returnFormatter

public void returnFormatter(RASIFormatter formatter,
                            java.lang.String groupName)
Returns a formatter to the named group.

If the handler configuration includes formatters, they will automatically be detached from the handler. It should not be necessary for an application to use the returnFormatter method.

Parameters:
formatter - The formatter being returned.
groupName - The name of the RASGroup.

returnFormatter

public void returnFormatter(RASIFormatter formatter,
                            RASGroup group)
Returns a formatter to a group.

If the handler configuration includes formatters, they will automatically be detached from the handler. It should not be necessary for an application to use the returnFormatter method.

Parameters:
formatter - The formatter being returned.
group - The RASGroup.

getBaseGroup

public RASBaseGroup getBaseGroup()
Gets the entire RAS configuration.
Returns:
The base RAS group containing the entire configuration.

setBaseGroup

public void setBaseGroup(RASBaseGroup baseGroup)
Sets the entire RAS configuration.
Parameters:
baseGroup - The base RAS group containing the entire configuration.

restoreConfig

public void restoreConfig()
Restores the RASManager configuration from persistent storage. If the RAS Manager has not been given a RASIDataStore to use, this method does nothing.

saveConfig

public void saveConfig()
Saves the RASManager configuration to persistent storage. If the RAS Manager has not been given a RASIDataStore to use, this method does nothing.