com.ibm.ras

Class RASLogger

  • All Implemented Interfaces:
    RASConstants, RASILogger, RASIMaskChangeGenerator, RASIMaskChangeListener, RASIObject, java.io.Serializable, java.lang.Cloneable, java.util.EventListener
    Direct Known Subclasses:
    RASMessageLogger, RASTraceLogger
    Deprecated. 
    As of WAS 6.0, recommend using java.util.logging

    public abstract class RASLogger
extends RASMaskChangeGenerator
implements RASConstants, RASILogger, RASIMaskChangeListener
    RASLogger is the parent of all classes which create message and trace data. These classes provide the primary interface to the application programmer by supplying the methods for information logging.

    Before you can use a RASLogger, you must associate with it at least one RASIHandler Use the addHandler method to accomplish this. A handler directs the log events to a destination (such as a file, a console or a TCP socket). It is possible to associate more than one handler with a logger to send the data to multiple destinations, possibly formatted differently for each. Multiple loggers may also be associated with a single handler.

    RASLogger provides several levels of control over which log events are processed. At the highest level, the public boolean variable isLogging is set true when the logger is "on" (logging data) and false when it is "off." To improve performance, this variable may be tested to eliminate unnecessary method calls. For example: 

     if (traceLogger.isLogging)
   traceLogger.trace(...);
    (The methods setLogging and isLogging are available to manipulate the public boolean isLogging as well.)

    For finer control, each message or trace event is assigned a "type," which defines the particular flavor of the object. For example, a message might be one of "informational," "warning," or "error." These types are defined by the classes which extend RASEvent.

    In general, the type assigned to a log event may be the logical OR of any of the defined types. In some cases, this does not make much sense. (A message might be informational or a warning, but not both). But RASEvent extensions might define additional types for which this would make sense. For example, an error might be "internal" (a failure detected within the application) or "external" (a failure detected outside the application). In this case, one might define the log event type to be TYPE_ERROR | TYPE_INTERNAL.

    Every logger and handler is assigned a "mask," which is the subset of RASEvent types that it will process. If any of the types assigned to a log entry are contained in the mask, the logger or handler will process the entry. For example, a trace entry is assigned a type of TYPE_PUBLIC | TYPE_ERROR_EXC. The trace logger mask is set to TYPE_PUBLIC | TYPE_PRIVATE | TYPE_STATIC. Since TYPE_PUBLIC is in the log entry type and the logger's mask, this entry will be processed.

    The default message and trace masks are RASIMessageEvent.DEFAULT_MESSAGE_MASK and RASITraceEvent.DEFAULT_TRACE_MASK, respectively. These values can be changed through the setMessageMask and setTraceMask methods.

    In practice, one is most likely to manipulate the mask of the logger or the handlers, but not both -- although nothing prevents customizing both masks. Different effects can be achieved by manipulating the masks. For example:

    • Logger A is set to process informational messages. Logger B is set to process error messages. Both are connected to the same console handler, which will accept any type of message. In a large application, it may be desirable to define multiple loggers in this manner so that different components within the application can provide varying levels of information.
    • Loggers A and B can generate any type of message. Both loggers are connected to the same console handler and file handler. The console handler is set to process only error messages, but the file handler will accept all messages. The effect is that critical errors go to the console, where they are seen immediately, and all messages go to the file, where they are archived.
    • Logger A is set to process informational messages. Logger B is set to process informational and warning messages. A handler is attached to both loggers and is configured to process only warning messages. Informational messages from both loggers are ignored.

    The isLoggable method compares the type associated with a message or trace point with the mask of the logger and each configured handler. It returns true if the logger and at least one of the handlers will process the log point. Thus, the overhead of building the log entry is avoided if no object is configured to process it. 

     if (traceLogger.isLoggable(TYPE_PUBLIC)
   traceLogger.trace(TYPE_PUBLIC,...);

    A logger can send data to its attached handlers either synchronously or asynchronously. In synchronous mode, a log entry is passed to a handler and written to its destination immediately. The application using the logger is, in effect, "blocked" until this operation completes. In asynchronous mode, a log entry is passed to a handler and queued for processing at whatever rate the handler is capable. The logger returns to the calling application more quickly in this mode. Asynchronous operation is the default. The mode can be changed with the setSynchronous method and tested via isSynchronous.

    Note: A handler can be set to use a circular buffer, which holds the log entries in memory until an explicit request to dump the buffer is made. This buffering mode is only possible if the logger is set for asynchronous operation. In synchronous mode, the handler's buffering mechanism is bypassed entirely.

    RASLogger has several optional fields which may be included in the message. These fields should not vary among messages produced by a given RASLogger, so they are specified through a RASLogger constructor or by the appropriate "set" and "get" methods of this class. These fields are:

    • A server associated with the creation of the messages.
    • The client on whose behalf the messages are created.
    If not specified, each of these fields defaults to an empty string.

    RASLogger is an abstract class, primarily because it lacks methods to send information to its associated handlers. (The message methods of RASMessageLogger and the trace methods of RASTraceLogger provide this needed function.)

    Note: Classes which implement RASILogger should, in their constructors, call the addMessageEventClass and addTraceEventClass methods to register the RASIEvent classes which the logger uses. This will allow a graphical program to query the logger to determine the supported RAS events. The events, in turn, can be queried to determine their set of supported event types.

    See Also:
    Serialized Form

    • Field Detail

      • isLogging

        public boolean isLogging
        Deprecated. 

      • handlerFailures

        protected transient int handlerFailures
        Deprecated. 
        The number of consecutive errors which have occurred trying to send an event to a handler.

      • isLoggableMask

        protected long isLoggableMask
        Deprecated. 

    • Constructor Detail

      • RASLogger

        public RASLogger()
        Deprecated. 
        Creates a RASLogger. The name and description of this object are empty strings.

      • RASLogger

        public RASLogger(java.lang.String name)
        Deprecated. 
        Creates a RASLogger. The description of this object is an empty string.
        Parameters:
        name - The name of this object.

      • RASLogger

        public RASLogger(java.lang.String name,
         java.lang.String desc)
        Deprecated. 
        Creates a RASLogger.
        Parameters:
        name - The name of this object.
        desc - The description of this object.

      • RASLogger

        public RASLogger(java.lang.String name,
         java.lang.String desc,
         java.lang.String server,
         java.lang.String client)
        Deprecated. 
        Creates a RASLogger.
        Parameters:
        name - The name of this object.
        desc - The description of this object.
        server - The server.
        client - The client.

    • Method Detail

      • init

        protected void init()
        Deprecated. 
        Initializes this object, setting default values.
        Overrides:
        init in class RASMaskChangeGenerator

      • getConfig

        public java.util.Hashtable getConfig()
        Deprecated. 
        Gets the configuration of this object.
        Specified by:
        getConfig in interface RASILogger
        Specified by:
        getConfig in interface RASIMaskChangeGenerator
        Specified by:
        getConfig in interface RASIObject
        Overrides:
        getConfig in class RASMaskChangeGenerator
        Returns:
        A Hashtable containing the configuration. This object inserts the following key/value pairs into the configuration:

        isLogging
        true if the logger is logging data; otherwise, false.
        isSync
        true if the logger is logging synchronously; otherwise, false.
        server
        The server.
        client
        The client.
        handlerNames
        The names of the handlers attached to this logger.

        All values are Strings. The parent and extensions of this object may add additional keys.

      • setConfig

        public void setConfig(java.util.Hashtable ht)
        Deprecated. 
        Sets the configuration of this object. This method is used by a RASManager to initialize a RAS object. It should not be necessary for an application to use this method.
        Specified by:
        setConfig in interface RASILogger
        Specified by:
        setConfig in interface RASIMaskChangeGenerator
        Specified by:
        setConfig in interface RASIObject
        Overrides:
        setConfig in class RASMaskChangeGenerator
        Parameters:
        ht - A Hashtable containing the configuration. This object searches for the following keys:

        isLogging
        true if the logger is logging data; otherwise, false.
        isSync
        true if the logger is logging synchronously; otherwise, false.
        server
        The server.
        client
        The client.
        handlerNames
        The names of the handlers attached to this logger.

        All values are Strings. If a key is not found, an internal default for that element is set instead. The parent and extensions of this object may use additional keys.

      • getClient

        public java.lang.String getClient()
        Deprecated. 
        Gets the name of the client which is associated with this logger.
        Specified by:
        getClient in interface RASILogger
        Returns:
        The client name, or an empty string ("") if the client has not been set.

      • setClient

        public void setClient(java.lang.String name)
        Deprecated. 
        Sets the name of the client which is associated with this logger. If the name is null, the current name is not changed.
        Specified by:
        setClient in interface RASILogger
        Parameters:
        name - The client name.

      • getServer

        public java.lang.String getServer()
        Deprecated. 
        Gets the name of the server which is associated with this logger.
        Specified by:
        getServer in interface RASILogger
        Returns:
        The server name, or an empty string ("") if the server has not been set.

      • setServer

        public void setServer(java.lang.String name)
        Deprecated. 
        Sets the name of the server which is associated with this logger. If the name is null, the current name is not changed.
        Specified by:
        setServer in interface RASILogger
        Parameters:
        name - The server name.

      • addHandler

        public void addHandler(RASIHandler handler)
        Deprecated. 
        Registers a RAS handler with this logger. More than one handler may be associated with a logger to direct the RAS data to multiple destinations. If the handler is null or is already registered, this method does nothing.
        Specified by:
        addHandler in interface RASILogger
        Parameters:
        handler - A RAS handler.

      • removeHandler

        public void removeHandler(RASIHandler handler)
        Deprecated. 
        Removes a RAS handler from this logger. If the handler is null or is not registered, this method does nothing.
        Specified by:
        removeHandler in interface RASILogger
        Parameters:
        handler - A RAS handler.

      • getHandlers

        public java.util.Enumeration getHandlers()
        Deprecated. 
        Gets all of the handlers associated with this logger.
        Specified by:
        getHandlers in interface RASILogger
        Returns:
        An Enumeration of handlers. If no handlers are registered, the Enumeration is empty.

      • isSynchronous

        public boolean isSynchronous()
        Deprecated. 
        Determines if synchronous logging is in effect. When logging synchronously, the logger will wait for the handlers to write a log entry before returning to the caller. Otherwise, the log entry is passed to the handler and the logger returns.
        Specified by:
        isSynchronous in interface RASILogger
        Returns:
        true for synchronous logging and false otherwise.

      • setSynchronous

        public void setSynchronous(boolean flag)
        Deprecated. 
        Sets a flag that tells the logger whether to log data synchronously. When logging synchronously, the logger will wait for the handlers to write a log entry before returning to the caller. Otherwise, the log entry is passed to the handler and the logger returns.
        Specified by:
        setSynchronous in interface RASILogger
        Parameters:
        flag - true for synchronous logging and false otherwise.

      • isLogging

        public boolean isLogging()
        Deprecated. 
        Determines if a logger is logging data ("on") or not ("off").
        Specified by:
        isLogging in interface RASILogger
        Returns:
        true when the logger is "on" and false otherwise.

      • setLogging

        public void setLogging(boolean flag)
        Deprecated. 
        Sets a flag that indicates whether the logger is logging data ("on") or not ("off").
        Specified by:
        setLogging in interface RASILogger
        Parameters:
        flag - true when the logger is "on" and false otherwise.

      • isLoggable

        public boolean isLoggable(long type)
        Deprecated. 
        Determines if a log entry will be processed by the logger and any of the handlers. Wrapping a message or trace call with this method can improve performance. Log entries that will not be processed need not even be built. For example: 
         if (isLoggable(RASTraceEvent.TYPE_PUBLIC)
   trace(RASTraceEvent.TYPE_PUBLIC...);
        Specified by:
        isLoggable in interface RASILogger
        Parameters:
        type - The type of the log entry. The set of possible values is defined by the RASIMessageEvent or RASITraceEvent TYPE_XXXX constants.
        Returns:
        true if the logger is enabled and at least one handler will process the log entry; false, otherwise.

      • maskValueChanged

        public abstract void maskValueChanged(RASMaskChangeEvent mc)
        Deprecated. 
        Indicates that the value of the handler's message or trace mask has changed.

        This method is intended to improve the performance of the RASLogger.isLoggable method. When notified of a change in the value of a handler's mask, the logger can update its internal data, which allows the logger to determine if a RAS event will be logged.

        Specified by:
        maskValueChanged in interface RASIMaskChangeListener
        Parameters:
        mc - A mask change event, indicating what has changed.

      • fireRASEvent

        public void fireRASEvent(RASIEvent event)
        Deprecated. 
        Sends a RASIEvent to all handlers which will process the event. A null event is ignored.
        Specified by:
        fireRASEvent in interface RASILogger
        Parameters:
        event - The event to be sent.
IBM WebSphere Application ServerTM
Release 8.5