com.ibm.ras
Class WsJrasTraceLogger

java.lang.Object
  |
  +--com.ibm.ras.RASObject
        |
        +--com.ibm.ras.RASLogger
              |
              +--com.ibm.ras.RASTraceLogger
                    |
                    +--com.ibm.ras.WsJrasTraceLogger
All Implemented Interfaces:
java.util.EventListener, RASILogger, RASIMaskChangeListener, RASIObject, RASITraceLogger, com.ibm.ejs.ras.TraceStateChangeListener

public class WsJrasTraceLogger
extends RASTraceLogger
implements RASITraceLogger, com.ibm.ejs.ras.TraceStateChangeListener

The WsJRasTraceLogger class extends the RASTraceLogger class and implements the RASITraceLogger interface. Users must not directly create an instance of a WsJRasTraceLogger. Instead, the Manager class must be used to obtain an instance.

A WsJrasTraceLogger is fully integrated with the native WebSphere trace facility. As such, existing Systems Management facilities can be used to dynamically enable or disable trace, direct where trace output is sent to, choose how the trace is formatted or to provide static configuration state.

Four basic tracing methods are provided by the RASITraceLogger interface. They are entry, exit, trace and exception. When tracing in non-static methods, the entry, exit, trace and exception methods that take a "this" (the object being traced) as the second parameter. This is a convenience to the programmer, as the class name can be derived from any Object. For static methods, an object does not exist. Use the entry, exit, trace and exception methods which take String className as the second parameter.

The set of types that may be used in the entry, exit, trace and exception methods is defined in the RASITraceEvent class. The type assigned to any trace point is arbitrary and up to the user. It should be noted that the types defined in the RASITraceEvent class are mapped to existing trace types supported by the WebSphere runtime. This mapping may vary with edition. See the documentation for your edition to determine the mappings in effect.

Note that the entry and exit methods always add RASITraceEvent.TYPE_ENTRY_EXIT to whatever type is selected. It is not necessary to explicitly include TYPE_ENTRY_EXIT.


Fields inherited from class com.ibm.ras.RASLogger
isLogging
 
Fields inherited from interface com.ibm.ejs.ras.TraceStateChangeListener
COPYRIGHT
 
Method Summary
 void addHandler(RASIHandler handler)
          Register a RASIHandler handler with this logger.
 void entry(long type, java.lang.Object obj, java.lang.String methodName)
          Trace entry into a non-static method.
 void entry(long type, java.lang.Object obj, java.lang.String methodName, java.lang.Object parm1)
          Trace entry into a non-static method.
 void entry(long type, java.lang.Object obj, java.lang.String methodName, java.lang.Object[] parms)
          Trace entry into a non-static method.
 void entry(long type, java.lang.Object obj, java.lang.String methodName, java.lang.Object parm1, java.lang.Object parm2)
          Trace entry into a non-static method.
 void entry(long type, java.lang.String className, java.lang.String methodName)
          Trace entry into a static method.
 void entry(long type, java.lang.String className, java.lang.String methodName, java.lang.Object parm1)
          Trace entry into a static method.
 void entry(long type, java.lang.String className, java.lang.String methodName, java.lang.Object[] parms)
          Trace entry into a static method.
 void entry(long type, java.lang.String className, java.lang.String methodName, java.lang.Object parm1, java.lang.Object parm2)
          Trace entry into a static method.
 void exception(long type, java.lang.Object obj, java.lang.String methodName, java.lang.Exception exc)
          Trace an Exception in a non-static method.
 void exception(long type, java.lang.String className, java.lang.String methodName, java.lang.Exception exc)
          Trace an Exception in a static method.
 void exit(long type, java.lang.Object obj, java.lang.String methodName)
          Trace exit from a non-static method.
 void exit(long type, java.lang.Object obj, java.lang.String methodName, java.lang.Object retValue)
          Trace exit from a non-static method.
 void exit(long type, java.lang.String className, java.lang.String methodName)
          Trace exit from a static method.
 void exit(long type, java.lang.String className, java.lang.String methodName, java.lang.Object retValue)
          Trace exit from a static method.
 java.util.Hashtable getConfig()
          Get the configuration of this object.
 java.lang.String getDescription()
          Get the description field for this object.
 java.util.Enumeration getHandlers()
          Get all of the handlers associated with this logger.
 java.lang.String getName()
          Get the name field of this object.
 long getTraceMask()
          Get the mask which defines the set of trace types that will be processed by this object.
 boolean isLoggable(long type)
          Determine if the specified RASITraceEvent type is currently enabled for this WsJrasTraceLogger.
 boolean isSynchronous()
          Determine if synchronous logging is in effect.
 void removeHandler(RASIHandler handler)
          Remove a RASIHandler from this logger.
 void setConfig(java.util.Hashtable ht)
          Set the configuration of this object.
 void setDescription(java.lang.String desc)
          Set the description field of this object to the specified value.
 void setName(java.lang.String name)
          Set the name by which this object is known.
 void setSynchronous(boolean flag)
          Set a flag to tell the logger whether to log data synchronously or asynchronously.
 void setTraceMask(long mask)
          Set the mask which defines the set of trace types that will be processed by this object.
 void trace(long type, java.lang.Object obj, java.lang.String methodName, java.lang.String text)
          Trace data in a non-static method.
 void trace(long type, java.lang.Object obj, java.lang.String methodName, java.lang.String text, java.lang.Object parm1)
          Trace data in a non-static method.
 void trace(long type, java.lang.Object obj, java.lang.String methodName, java.lang.String text, java.lang.Object[] parms)
          Trace data in a non-static method.
 void trace(long type, java.lang.Object obj, java.lang.String methodName, java.lang.String text, java.lang.Object parm1, java.lang.Object parm2)
          Trace data in a non-static method.
 void trace(long type, java.lang.String className, java.lang.String methodName, java.lang.String text)
          Trace data in a static method.
 void trace(long type, java.lang.String className, java.lang.String methodName, java.lang.String text, java.lang.Object parm1)
          Trace data in a static method.
 void trace(long type, java.lang.String className, java.lang.String methodName, java.lang.String text, java.lang.Object[] parms)
          Trace data in a static method.
 void trace(long type, java.lang.String className, java.lang.String methodName, java.lang.String text, java.lang.Object parm1, java.lang.Object parm2)
          Trace data in a static method.
 void traceStateChanged()
          Set the state of the traceMask from the underlying state in the TraceComponent hierarchy and update the isLogging boolean accordingly.
 
Methods inherited from class com.ibm.ras.RASTraceLogger
maskValueChanged
 
Methods inherited from class com.ibm.ras.RASLogger
getClient, getServer, setClient, setServer
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getConfig

public java.util.Hashtable getConfig()
Get the configuration of this object.

WebSphere WsJrasTraceLoggers are fully configured by the runtime when created. The configuration data has no significant meaning outside of the runtime context. Null will always be returned.

Specified by:
getConfig in interface RASITraceLogger
Overrides:
getConfig in class RASTraceLogger
Returns:
null

setConfig

public void setConfig(java.util.Hashtable ht)
Set the configuration of this object.

WebSphere WsJrasTraceLoggers are fully configured by the runtime when created. Users are not allowed to reconfigure or change the internal configuration state of a WsJrasTraceLogger via this interface. Calling this method results in a no-op.

Specified by:
setConfig in interface RASITraceLogger
Overrides:
setConfig in class RASTraceLogger
Following copied from interface: com.ibm.ras.RASITraceLogger
Parameters:
ht - A Hashtable containing the configuration. This object searches for the following keys:
            "traceMask" The mask which selects the trace types to be
                        processed.
            
All values are Strings. If a key is not found, that configuration element is not updated. The parent and extensions of this object may use additional keys.

getDescription

public java.lang.String getDescription()
Get the description field for this object.

The WebSphere runtime does not utilize this field. For performance and memory footprint reasons it is recommended that users do not use this field.

Specified by:
getDescription in interface RASIObject
Overrides:
getDescription in class RASObject
Returns:
the value of the description set via the setDescription() method or the empty String if no value has been set.

setDescription

public void setDescription(java.lang.String desc)
Set the description field of this object to the specified value.

The WebSphere runtime does not utilize the description field. For performance and memory footprint reasons, it is recommended that users do not utilize this field.

Specified by:
setDescription in interface RASIObject
Overrides:
setDescription in class RASObject
Parameters:
desc - the new value for the description field. If null is passed, the current value is not changed.

getName

public java.lang.String getName()
Get the name field of this object.

The name field specfied when then WsJrasTraceLogger was created is returned. This field is settable only on creation and is otherwise immutable.

Specified by:
getName in interface RASIObject
Overrides:
getName in class RASObject
Returns:
the value specified for the name of this object when it was created.

setName

public void setName(java.lang.String name)
Set the name by which this object is known.

The WebSphere runtime is dependent upon the name field to coherently manage the state of a WsJrasTraceLogger. The name for a WsJrasTraceLogger is specified to the Manager when the WsJrasTraceLogger is created. Users are not allowed to subsequently change the name. This operation is a no-op.

Specified by:
setName in interface RASIObject
Overrides:
setName in class RASObject
Parameters:
name - The name of this object.

addHandler

public void addHandler(RASIHandler handler)
Register a RASIHandler handler with this logger.

The WebSphere runtime configures this object with the appropriate system-integrated handlers when the object is created. Currently, users ar not allowed to add other RASIHandlers. This method is a no-op.

Specified by:
addHandler in interface RASILogger
Overrides:
addHandler in class RASLogger
Parameters:
handler - A RASIHandler handler.

removeHandler

public void removeHandler(RASIHandler handler)
Remove a RASIHandler from this logger.

The WebSphere runtime configures this object with the appropriate system-integrated handlers when the object is created. Currently, users cannot get a reference to any system-supplied handler and are not allowed to add their own. This method is a no-op.

Specified by:
removeHandler in interface RASILogger
Overrides:
removeHandler in class RASLogger
Parameters:
handler - A RASIHandler handler.

getHandlers

public java.util.Enumeration getHandlers()
Get all of the handlers associated with this logger.

The WebSphere runtime does not support users adding RASIHandlers to this object and does not return references to WebSphere-created handlers to user code. This method will always returns null.

Specified by:
getHandlers in interface RASILogger
Overrides:
getHandlers in class RASLogger
Returns:
null.

setSynchronous

public void setSynchronous(boolean flag)
Set a flag to tell the logger whether to log data synchronously or asynchronously.

The WebSphere runtime dictates that all logging must be performed synchronously and the user is not allowed to override that behavior. This method is a no-op.

Specified by:
setSynchronous in interface RASILogger
Overrides:
setSynchronous in class RASLogger
Following copied from interface: com.ibm.ras.RASILogger
Parameters:
flag - A boolean set true for synchronous logging and false otherwise.

isSynchronous

public boolean isSynchronous()
Determine if synchronous logging is in effect.

The WebSphere runtime dictates that all logging must be performed synchronously and the user is not allowed to override that behavior. This method always returns true.

Specified by:
isSynchronous in interface RASILogger
Overrides:
isSynchronous in class RASLogger
Returns:
true

isLoggable

public boolean isLoggable(long type)
Determine if the specified RASITraceEvent type is currently enabled for this WsJrasTraceLogger.

This method also provides an efficiency mechanism to wrap a trace call. Log entries that will not be processed need not even be built. For example:

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

Specified by:
isLoggable in interface RASILogger
Overrides:
isLoggable in class RASLogger
Parameters:
type - The type of the log entry. The set of possible values is defined by the RASITraceEvent constants
Returns:
true if the trace event will be logged, false otherwise.

getTraceMask

public long getTraceMask()
Get the mask which defines the set of trace types that will be processed by this object.

Specified by:
getTraceMask in interface RASITraceLogger
Overrides:
getTraceMask in class RASTraceLogger
Returns:
The trace mask.

setTraceMask

public void setTraceMask(long mask)
Set the mask which defines the set of trace types that will be processed by this object. Possible values are defined by the RASITraceEvent.TYPE_XXXX constants. The specified mask value is not validated against these types.

Note: Using this method to set the trace mask does not have the side effect of updating the settings maintained by the WebSphere runtime. Therefore setting the trace mask to a less restrictive state will generally not have the desired side effect of enabling trace.

To enable trace, use the existing Systems Management facilities instead.

Specified by:
setTraceMask in interface RASITraceLogger
Overrides:
setTraceMask in class RASTraceLogger
Parameters:
mask - The trace mask.

entry

public void entry(long type,
                  java.lang.Object obj,
                  java.lang.String methodName)
Trace entry into a non-static method.

Specified by:
entry in interface RASITraceLogger
Overrides:
entry in class RASTraceLogger
Parameters:
type - The type of the trace point.
obj - The traced object ("this").
methodName - The name of the traced method.

entry

public void entry(long type,
                  java.lang.Object obj,
                  java.lang.String methodName,
                  java.lang.Object parm1)
Trace entry into a non-static method.

Specified by:
entry in interface RASITraceLogger
Overrides:
entry in class RASTraceLogger
Parameters:
type - The type of the trace point.
obj - The traced object ("this").
methodName - The name of the traced method.
parm1 - An element to be displayed as trace data.

entry

public void entry(long type,
                  java.lang.Object obj,
                  java.lang.String methodName,
                  java.lang.Object parm1,
                  java.lang.Object parm2)
Trace entry into a non-static method.

Specified by:
entry in interface RASITraceLogger
Overrides:
entry in class RASTraceLogger
Parameters:
type - The type of the trace point.
obj - The traced object ("this").
methodName - The name of the traced method.
parm1 - An element to be displayed as trace data.
parm2 - An element to be displayed as trace data.

entry

public void entry(long type,
                  java.lang.Object obj,
                  java.lang.String methodName,
                  java.lang.Object[] parms)
Trace entry into a non-static method.

Specified by:
entry in interface RASITraceLogger
Overrides:
entry in class RASTraceLogger
Parameters:
type - The type of the trace point.
obj - The traced object ("this").
methodName - The name of the traced method.
parms - An array of parameters passed to the method.

entry

public void entry(long type,
                  java.lang.String className,
                  java.lang.String methodName)
Trace entry into a static method.

Specified by:
entry in interface RASITraceLogger
Overrides:
entry in class RASTraceLogger
Parameters:
type - The type of the trace point.
className - The name of the traced class.
methodName - The name of the traced method.

entry

public void entry(long type,
                  java.lang.String className,
                  java.lang.String methodName,
                  java.lang.Object parm1)
Trace entry into a static method.

Specified by:
entry in interface RASITraceLogger
Overrides:
entry in class RASTraceLogger
Parameters:
type - The type of the trace point.
className - The name of the traced class.
methodName - The name of the traced method.
parm1 - An element to be displayed as trace data.

entry

public void entry(long type,
                  java.lang.String className,
                  java.lang.String methodName,
                  java.lang.Object parm1,
                  java.lang.Object parm2)
Trace entry into a static method.

Specified by:
entry in interface RASITraceLogger
Overrides:
entry in class RASTraceLogger
Parameters:
type - The type of the trace point.
className - The name of the traced class.
methodName - The name of the traced method.
parm1 - An element to be displayed as trace data.
parm2 - An element to be displayed as trace data.

entry

public void entry(long type,
                  java.lang.String className,
                  java.lang.String methodName,
                  java.lang.Object[] parms)
Trace entry into a static method.

Specified by:
entry in interface RASITraceLogger
Overrides:
entry in class RASTraceLogger
Parameters:
type - The type of the trace point.
className - The name of the traced class.
methodName - The name of the traced method.
parms - An array of elements to be displayed as trace data.

exit

public void exit(long type,
                 java.lang.Object obj,
                 java.lang.String methodName)
Trace exit from a non-static method.

Specified by:
exit in interface RASITraceLogger
Overrides:
exit in class RASTraceLogger
Parameters:
type - The type of the trace point.
obj - The traced object ("this").
methodName - The name of the traced method.

exit

public void exit(long type,
                 java.lang.Object obj,
                 java.lang.String methodName,
                 java.lang.Object retValue)
Trace exit from a non-static method.

Specified by:
exit in interface RASITraceLogger
Overrides:
exit in class RASTraceLogger
Parameters:
type - The type of the trace point.
obj - The traced object ("this").
methodName - The name of the traced method.
retValue - The returned value.

exit

public void exit(long type,
                 java.lang.String className,
                 java.lang.String methodName)
Trace exit from a static method.

Specified by:
exit in interface RASITraceLogger
Overrides:
exit in class RASTraceLogger
Parameters:
type - The type of the trace point.
className - The name of the traced class.
methodName - The name of the traced method.

exit

public void exit(long type,
                 java.lang.String className,
                 java.lang.String methodName,
                 java.lang.Object retValue)
Trace exit from a static method.

Specified by:
exit in interface RASITraceLogger
Overrides:
exit in class RASTraceLogger
Parameters:
type - The type of the trace point.
className - The name of the traced class.
methodName - The name of the traced method.
retValue - The returned value.

trace

public void trace(long type,
                  java.lang.Object obj,
                  java.lang.String methodName,
                  java.lang.String text)
Trace data in a non-static method.

Specified by:
trace in interface RASITraceLogger
Overrides:
trace in class RASTraceLogger
Parameters:
type - The type of the trace point.
obj - The traced object ("this").
methodName - The name of the traced method.
text - The trace text.

trace

public void trace(long type,
                  java.lang.Object obj,
                  java.lang.String methodName,
                  java.lang.String text,
                  java.lang.Object parm1)
Trace data in a non-static method.

Specified by:
trace in interface RASITraceLogger
Overrides:
trace in class RASTraceLogger
Parameters:
type - The type of the trace point.
obj - The traced object ("this").
methodName - The name of the traced method.
text - The trace text.
parm1 - An element to be displayed as trace data.

trace

public void trace(long type,
                  java.lang.Object obj,
                  java.lang.String methodName,
                  java.lang.String text,
                  java.lang.Object parm1,
                  java.lang.Object parm2)
Trace data in a non-static method.

Specified by:
trace in interface RASITraceLogger
Overrides:
trace in class RASTraceLogger
Parameters:
type - The type of the trace point.
obj - The traced object ("this").
methodName - The name of the traced method.
text - The trace text.
parm1 - An element to be displayed as trace data.
parm2 - An element to be displayed as trace data.

trace

public void trace(long type,
                  java.lang.Object obj,
                  java.lang.String methodName,
                  java.lang.String text,
                  java.lang.Object[] parms)
Trace data in a non-static method.

Specified by:
trace in interface RASITraceLogger
Overrides:
trace in class RASTraceLogger
Parameters:
type - The type of the trace point.
obj - The traced object ("this").
methodName - The name of the traced method.
text - The trace text.
parms - An array of elements to be displayed with the text.

trace

public void trace(long type,
                  java.lang.String className,
                  java.lang.String methodName,
                  java.lang.String text)
Trace data in a static method.

Specified by:
trace in interface RASITraceLogger
Overrides:
trace in class RASTraceLogger
Parameters:
type - The type of the trace point.
className - The name of the traced class.
methodName - The name of the traced method.
text - The trace text.

trace

public void trace(long type,
                  java.lang.String className,
                  java.lang.String methodName,
                  java.lang.String text,
                  java.lang.Object parm1)
Trace data in a static method.

Specified by:
trace in interface RASITraceLogger
Overrides:
trace in class RASTraceLogger
Parameters:
type - The type of the trace point.
className - The name of the traced class.
methodName - The name of the traced method.
text - The trace text.
parm1 - An element to be displayed as trace data.

trace

public void trace(long type,
                  java.lang.String className,
                  java.lang.String methodName,
                  java.lang.String text,
                  java.lang.Object parm1,
                  java.lang.Object parm2)
Trace data in a static method.

Specified by:
trace in interface RASITraceLogger
Overrides:
trace in class RASTraceLogger
Parameters:
type - The type of the trace point.
className - The name of the traced class.
methodName - The name of the traced method.
text - The trace text.
parm1 - An element to be displayed as trace data.
parm2 - An element to be displayed as trace data.

trace

public void trace(long type,
                  java.lang.String className,
                  java.lang.String methodName,
                  java.lang.String text,
                  java.lang.Object[] parms)
Trace data in a static method.

Specified by:
trace in interface RASITraceLogger
Overrides:
trace in class RASTraceLogger
Parameters:
type - The type of the trace point.
className - The name of the traced class.
methodName - The name of the traced method.
text - The trace text.
parms - An array of elements to be displayed as trace data.

exception

public void exception(long type,
                      java.lang.Object obj,
                      java.lang.String methodName,
                      java.lang.Exception exc)
Trace an Exception in a non-static method.

Specified by:
exception in interface RASITraceLogger
Overrides:
exception in class RASTraceLogger
Parameters:
type - The type of the trace point.
obj - The traced object ("this").
methodName - The name of the traced method.
exc - An exception.

exception

public void exception(long type,
                      java.lang.String className,
                      java.lang.String methodName,
                      java.lang.Exception exc)
Trace an Exception in a static method.

Specified by:
exception in interface RASITraceLogger
Overrides:
exception in class RASTraceLogger
Parameters:
type - The type of the trace point.
className - The name of the traced class.
methodName - The name of the traced method.
exc - An exception.

traceStateChanged

public void traceStateChanged()
Set the state of the traceMask from the underlying state in the TraceComponent hierarchy and update the isLogging boolean accordingly.

This method can either be called from the TraceLogger constructor or from the TraceComponent. The TraceComponent will call back on this method when the underlying trace state has changed and this method will then update the mask in the TraceLogger accordingly. of trace state changes. In order for this to work, TraceLoggers must register themselves with the TraceComponent when the TraceLogger is created.

Specified by:
traceStateChanged in interface com.ibm.ejs.ras.TraceStateChangeListener