IBM WebSphere Application ServerTM
Release 8

com.ibm.ras.mgr
Class RASManager

java.lang.Object
  extended by com.ibm.ras.mgr.RASManager
All Implemented Interfaces:
RASIManager, RASConstants

Deprecated. As of WAS 6.0, recommend using java.util.logging

public class RASManager
extends java.lang.Object
implements RASConstants, RASIManager

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 RASLoggers. 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.

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 program 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. Formatter configurations are searched for in the same manner as handler configurations.

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 used. Without persistent storage, you can build the configuration by creating a RASBaseGroup and zero or more RASGroups and passing this to the RAS Manager through the setBaseGroup method. However, the preferred approach is to use persistent storage.


Field Summary
protected static java.lang.Object dsLock
          Deprecated. An object on which the manager can synchronize for data store operations.
protected static java.lang.Object getMgrLock
          Deprecated. An object on which the manager can synchronize when getting the manager.
protected static java.lang.Object getObjLock
          Deprecated. An object on which the manager can synchronize when getting a RAS object such as a logger.
 
Fields inherited from interface com.ibm.ras.RASConstants
KEY_CLASS_NAME, KEY_CLIENT, KEY_COMPONENT, KEY_DATE_FORMAT, KEY_DEFAULT_HANDLERS, KEY_DEFAULT_MESSAGE_HANDLERS, KEY_DEFAULT_TRACE_HANDLERS, KEY_DESCRIPTION, KEY_ENCODING, KEY_EXCEPTION, KEY_EXCEPTION_TRACE, KEY_FILE_NAME, KEY_FORMATTER_NAMES, KEY_GROUP, KEY_HANDLER_NAMES, KEY_HEX_DATA, KEY_IS_CIRCULAR, KEY_IS_LOGGING, KEY_IS_SYNC, KEY_LOGGER, KEY_LOGGING_CLASS, KEY_LOGGING_METHOD, KEY_MAX_FILE_SIZE, KEY_MAX_FILES, KEY_MAX_QUEUE_SIZE, KEY_MESSAGE_EVENT_CLASSES, KEY_MESSAGE_FILE, KEY_MESSAGE_MASK, KEY_NAME, KEY_ORGANIZATION, KEY_PRODUCT, KEY_RETRY_INTERVAL, KEY_SEPARATOR, KEY_SERVER, KEY_SOCKET_PORT, KEY_SOCKET_SERVER, KEY_SUPPRESSED_KEYS, KEY_THREAD_ID, KEY_TIME_FORMAT, KEY_TRACE_EVENT_CLASSES, KEY_TRACE_MASK, RAS_VERSION
 
Constructor Summary
protected RASManager(RASIDataStore store)
          Deprecated. Creates a RASManager.
 
Method Summary
 void addDataStore(RASIDataStore store)
          Deprecated. Adds a RASIDataStore to this manager.
protected  void addFormatters(RASIHandler handler, RASConfig cfg, RASGroup group)
          Deprecated. Add formatters to a newly-created handler, according to the handler's configuration.
protected  void addHandlers(RASILogger logger, RASConfig cfg, RASGroup group)
          Deprecated. Add handlers to a logger, according to the logger's configuration.
protected  void finalize()
          Deprecated. Clean up resources in use before the garbage collector destroys this object.
 RASBaseGroup getBaseGroup()
          Deprecated. Gets the entire RAS configuration.
 java.util.Enumeration getDataStores()
          Deprecated. Gets the data store objects in use by this manager.
 RASIFormatter getFormatter(java.lang.String name)
          Deprecated. Gets a formatter from the base group.
 RASIFormatter getFormatter(java.lang.String name, RASGroup group)
          Deprecated. Gets a formatter from a group.
 RASIFormatter getFormatter(java.lang.String name, java.lang.String groupName)
          Deprecated. Gets a formatter from the named group.
 RASIHandler getHandler(java.lang.String name)
          Deprecated. Gets a handler from the base group.
 RASIHandler getHandler(java.lang.String name, RASGroup group)
          Deprecated. Gets a handler from a group.
 RASIHandler getHandler(java.lang.String name, java.lang.String groupName)
          Deprecated. Gets a handler from the named group.
static RASManager getManager()
          Deprecated. Gets the RASManager.
static RASManager getManager(RASIDataStore store)
          Deprecated. Gets the RASManager.
 RASIMessageLogger getMessageLogger(java.lang.String name)
          Deprecated. Gets a message logger from the base group.
 RASIMessageLogger getMessageLogger(java.lang.String name, RASGroup group)
          Deprecated. Gets a message logger from a group.
 RASIMessageLogger getMessageLogger(java.lang.String name, java.lang.String groupName)
          Deprecated. Gets a message logger from the named group.
protected  RASObject getObject(RASConfig cfg)
          Deprecated. Gets a RASObject from its configuration.
 RASITraceLogger getTraceLogger(java.lang.String name)
          Deprecated. Gets a trace logger from the base group.
 RASITraceLogger getTraceLogger(java.lang.String name, RASGroup group)
          Deprecated. Gets a trace logger from a group.
 RASITraceLogger getTraceLogger(java.lang.String name, java.lang.String groupName)
          Deprecated. Gets a trace logger from the named group.
 void removeDataStore(RASIDataStore store)
          Deprecated. Removes a RASIDataStore from this manager.
protected  void removeFormatters(RASIHandler handler, RASGroup group)
          Deprecated. Removes formatters from a handler.
protected  void removeHandlers(RASILogger logger, RASGroup group)
          Deprecated. Removes handlers from a logger.
 void restoreConfig()
          Deprecated. Restores the RASManager configuration from persistent storage.
 void returnFormatter(RASIFormatter formatter)
          Deprecated. Returns a formatter to its group.
 void returnFormatter(RASIFormatter formatter, RASGroup group)
          Deprecated. Returns a formatter to a group.
 void returnFormatter(RASIFormatter formatter, java.lang.String groupName)
          Deprecated. Returns a formatter to the named group.
 void returnHandler(RASIHandler handler)
          Deprecated. Returns a handler to its group.
 void returnHandler(RASIHandler handler, RASGroup group)
          Deprecated. Returns a handler to a group.
 void returnHandler(RASIHandler handler, java.lang.String groupName)
          Deprecated. Returns a handler to the named group.
 void returnMessageLogger(RASIMessageLogger logger)
          Deprecated. Returns a message logger to its group.
 void returnMessageLogger(RASIMessageLogger logger, RASGroup group)
          Deprecated. Returns a message logger to a group.
 void returnMessageLogger(RASIMessageLogger logger, java.lang.String groupName)
          Deprecated. Returns a message logger to the named group.
 void returnTraceLogger(RASITraceLogger logger)
          Deprecated. Returns a trace logger to its group.
 void returnTraceLogger(RASITraceLogger logger, RASGroup group)
          Deprecated. Returns a trace logger to a group.
 void returnTraceLogger(RASITraceLogger logger, java.lang.String groupName)
          Deprecated. Returns a trace logger to the named group.
 void saveConfig()
          Deprecated. Saves the RASManager configuration to persistent storage.
 void setBaseGroup(RASBaseGroup baseGroup)
          Deprecated. Sets the entire RAS configuration.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

dsLock

protected static final java.lang.Object dsLock
Deprecated. 
An object on which the manager can synchronize for data store operations.


getMgrLock

protected static final java.lang.Object getMgrLock
Deprecated. 
An object on which the manager can synchronize when getting the manager.


getObjLock

protected static final java.lang.Object getObjLock
Deprecated. 
An object on which the manager can synchronize when getting a RAS object such as a logger.

Constructor Detail

RASManager

protected RASManager(RASIDataStore store)
Deprecated. 
Creates a RASManager. This method is protected to force applications to use the factory method getManager.

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

getManager

public static RASManager getManager()
Deprecated. 
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)
Deprecated. 
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)
Deprecated. 
Adds a RASIDataStore to this manager. After adding a data store, use restoreConfig to restore the configuration from the data store.

Only one data store is supported in this implementation. A new data store replaces the current store.

Specified by:
addDataStore in interface RASIManager
Parameters:
store - An object which implements the RASIDataStore interface.

removeDataStore

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

Only one data store is supported in this implementation. If the requested store is in use, it is removed. Otherwise, nothing is changed.

Specified by:
removeDataStore in interface RASIManager
Parameters:
store - An object which implements the RASIDataStore interface.

getDataStores

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

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

Specified by:
getDataStores in interface RASIManager
Returns:
An Enumeration of data stores.

restoreConfig

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

Specified by:
restoreConfig in interface RASIManager
Throws:
RASIOException

saveConfig

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

Specified by:
saveConfig in interface RASIManager
Throws:
RASIOException

getMessageLogger

public RASIMessageLogger getMessageLogger(java.lang.String name)
Deprecated. 
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.

Specified by:
getMessageLogger in interface RASIManager
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)
Deprecated. 
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.

Specified by:
getMessageLogger in interface RASIManager
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)
Deprecated. 
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.

Specified by:
getMessageLogger in interface RASIManager
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)
Deprecated. 
Returns a message logger to its group. The logger is queried to determine the group with which it is associated. If the logger is null, this method does nothing.

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.

Specified by:
returnMessageLogger in interface RASIManager
Parameters:
logger - The logger being returned.

returnMessageLogger

public void returnMessageLogger(RASIMessageLogger logger,
                                java.lang.String groupName)
Deprecated. 
Returns a message logger to the named group. If the logger or group name is null, this method does nothing.

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.

Specified by:
returnMessageLogger in interface RASIManager
Parameters:
logger - The logger being returned.
groupName - The name of the RASGroup.

returnMessageLogger

public void returnMessageLogger(RASIMessageLogger logger,
                                RASGroup group)
Deprecated. 
Returns a message logger to a group. If the logger or group is null, this method does nothing.

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.

Specified by:
returnMessageLogger in interface RASIManager
Parameters:
logger - The logger being returned.
group - The RASGroup.

getTraceLogger

public RASITraceLogger getTraceLogger(java.lang.String name)
Deprecated. 
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.

Specified by:
getTraceLogger in interface RASIManager
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)
Deprecated. 
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.

Specified by:
getTraceLogger in interface RASIManager
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)
Deprecated. 
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.

Specified by:
getTraceLogger in interface RASIManager
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)
Deprecated. 
Returns a trace logger to its group. The logger is queried to determine the group with which it is associated. If the logger is null, this method does nothing.

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.

Specified by:
returnTraceLogger in interface RASIManager
Parameters:
logger - The logger being returned.

returnTraceLogger

public void returnTraceLogger(RASITraceLogger logger,
                              java.lang.String groupName)
Deprecated. 
Returns a trace logger to the named group. If the logger or group name is null, this method does nothing.

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.

Specified by:
returnTraceLogger in interface RASIManager
Parameters:
logger - The logger being returned.
groupName - The name of the RASGroup.

returnTraceLogger

public void returnTraceLogger(RASITraceLogger logger,
                              RASGroup group)
Deprecated. 
Returns a trace logger to a group. If the logger or group is null, this method does nothing.

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.

Specified by:
returnTraceLogger in interface RASIManager
Parameters:
logger - The logger being returned.
group - The RASGroup.

getHandler

public RASIHandler getHandler(java.lang.String name)
Deprecated. 
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.

Specified by:
getHandler in interface RASIManager
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)
Deprecated. 
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.

Specified by:
getHandler in interface RASIManager
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)
Deprecated. 
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.

Specified by:
getHandler in interface RASIManager
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)
Deprecated. 
Returns a handler to its group. The handler is queried to determine the group with which it is associated. If the handler is null, this method does nothing.

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.

Specified by:
returnHandler in interface RASIManager
Parameters:
handler - The handler being returned.

returnHandler

public void returnHandler(RASIHandler handler,
                          java.lang.String groupName)
Deprecated. 
Returns a handler to the named group. If the handler or group name is null, this method does nothing.

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.

Specified by:
returnHandler in interface RASIManager
Parameters:
handler - The handler being returned.
groupName - The name of the RASGroup.

returnHandler

public void returnHandler(RASIHandler handler,
                          RASGroup group)
Deprecated. 
Returns a handler to a group. If the handler or group is null, this method does nothing.

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.

Specified by:
returnHandler in interface RASIManager
Parameters:
handler - The handler being returned.
group - The RASGroup.

getFormatter

public RASIFormatter getFormatter(java.lang.String name)
Deprecated. 
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.

Specified by:
getFormatter in interface RASIManager
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)
Deprecated. 
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.

Specified by:
getFormatter in interface RASIManager
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)
Deprecated. 
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.

Specified by:
getFormatter in interface RASIManager
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)
Deprecated. 
Returns a formatter to its group. The formatter is queried to determine the group with which it is associated. If the formatter is null, this method does nothing.

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.

Specified by:
returnFormatter in interface RASIManager
Parameters:
formatter - The formatter being returned.

returnFormatter

public void returnFormatter(RASIFormatter formatter,
                            java.lang.String groupName)
Deprecated. 
Returns a formatter to the named group. If the formatter or group name is null, this method does nothing.

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.

Specified by:
returnFormatter in interface RASIManager
Parameters:
formatter - The formatter being returned.
groupName - The name of the RASGroup.

returnFormatter

public void returnFormatter(RASIFormatter formatter,
                            RASGroup group)
Deprecated. 
Returns a formatter to a group. If the formatter or group is null, this method does nothing.

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.

Specified by:
returnFormatter in interface RASIManager
Parameters:
formatter - The formatter being returned.
group - The RASGroup.

getBaseGroup

public RASBaseGroup getBaseGroup()
Deprecated. 
Gets the entire RAS configuration.

Specified by:
getBaseGroup in interface RASIManager
Returns:
The base RAS group containing the entire configuration.

setBaseGroup

public void setBaseGroup(RASBaseGroup baseGroup)
Deprecated. 
Sets the entire RAS configuration.

Specified by:
setBaseGroup in interface RASIManager
Parameters:
baseGroup - The base RAS group containing the entire configuration.

getObject

protected RASObject getObject(RASConfig cfg)
Deprecated. 
Gets a RASObject from its configuration. If the object has been created already, it is returned. If not, a new object is instantiated and returned.

Parameters:
cfg - The configuration of the object.
Returns:
A RAS object or null if the requested object was not found.

addHandlers

protected void addHandlers(RASILogger logger,
                           RASConfig cfg,
                           RASGroup group)
Deprecated. 
Add handlers to a logger, according to the logger's configuration. This method will compare any handler's already attached to the logger with the current configuration and add or remove handlers as required to match the configuration.

Parameters:
logger - The RAS logger.
cfg - The RAS logger configuration.
group - The RASGroup in which the logger configuration was found.

removeHandlers

protected void removeHandlers(RASILogger logger,
                              RASGroup group)
Deprecated. 
Removes handlers from a logger.

Parameters:
logger - The RAS logger.
group - The RASGroup in which the logger configuration was found.

addFormatters

protected void addFormatters(RASIHandler handler,
                             RASConfig cfg,
                             RASGroup group)
Deprecated. 
Add formatters to a newly-created handler, according to the handler's configuration.

Parameters:
handler - The RAS handler.
cfg - The RAS handler configuration.
group - The RASGroup in which the handler configuration was found.

removeFormatters

protected void removeFormatters(RASIHandler handler,
                                RASGroup group)
Deprecated. 
Removes formatters from a handler.

Parameters:
handler - The RAS handler.
group - The RASGroup in which the handler configuration was found.

finalize

protected void finalize()
                 throws java.lang.Throwable
Deprecated. 
Clean up resources in use before the garbage collector destroys this object.

Overrides:
finalize in class java.lang.Object
Throws:
java.lang.Throwable

IBM WebSphere Application ServerTM
Release 8