The basic JRas message and event types are not the same
as those natively recognized by WebSphere® Application Server, so the JRas types
are mapped onto the types that are native to the runtime environment.
You can control the way JRas message and trace events are processed
using custom filters and message controls.
Event types
The JRas framework described in this task and its sub-tasks
is deprecated. However, you can achieve similar results using Java logging.
The
base message and trace event types that are defined by the stand-alone
JRas logging toolkit are not the same as the native types that are
recognized by the WebSphere Application Server run-time.
Instead, the basic JRas types are mapped onto the native types. This
mapping can vary by platform or edition. The mapping is discussed
in the following section.
Platform message event types
The message
event types that are recognized and processed by the
WebSphere Application Server runtime are defined
in the RASIMessageEvent interface that is provided by the stand-alone
JRas logging toolkit.
Table 1. Platform message event types. These message types are mapped onto the native message types,
as follows.WebSphere Application Server native type |
JRas RASIMessageEvent type |
Audit |
TYPE_INFO, TYPE_INFORMATION |
Warning |
TYPE_WARN, TYPE_WARNING |
Error |
TYPE_ERR, TYPE_ERROR |
Platform trace event types
The trace event
types that are recognized and processed by the
WebSphere Application Server run time are defined
in the RASITraceEvent interface that is provided by the stand-alone
JRas logging toolkit. The RASITraceEvent interface provides a rich
and complex set of types. This interface defines both a simple set
of levels, as well as a set of enumerated types.
- For a user who prefers a simple set of levels, the RASITraceEvent
interface provides TYPE_LEVEL1, TYPE_LEVEL2, and TYPE_LEVEL3.
The implementations provide support for this set of levels. The levels
are hierarchical, enabling level 2 also enables level 1, enabling
level 3 also enables levels 1 and 2.
- For users who prefer a more complex set of values that can be OR'd together,
the RASITraceEvent interface provides TYPE_API, TYPE_CALLBACK, TYPE_ENTRY_EXIT, TYPE_ERROR_EXC, TYPE_MISC_DATA, TYPE_OBJ_CREATE, TYPE_OBJ_DELETE, TYPE_PRIVATE, TYPE_PUBLIC, TYPE_STATIC,
and TYPE_SVC.
The trace event types are mapped onto the native trace
types as follows:
Table 2. WebSphere Application Server native types and
JRas RASITraceEvent level types. Mapping WebSphere Application Server trace types to
the JRas RASITraceEvent level types.WebSphere Application Server native type |
JRas RASITraceEvent level type |
Event |
TYPE_LEVEL1 |
EntryExit |
TYPE_LEVEL2 |
Debug |
TYPE_LEVEL3 |
Table 3. WebSphere Application Server native types and
JRas RASITraceEvent enumerated types. Mapping WebSphere Application Server trace types to
the JRas RASITraceEvent enumerated types.WebSphere Application Server native type |
JRas RASITraceEvent enumerated
types |
Event |
TYPE_ERROR_EXC, TYPE_SVC, TYPE_OBJ_CREATE,
TYPE_OBJ_DELETE |
EntryExit |
TYPE_ENTRY_EXIT, TYPE_API, TYPE_CALLBACK,
TYPE_PRIVATE, TYPE_PUBLIC, TYPE_STATIC |
Debug |
TYPE_MISC_DATA |
For simplicity, it is recommended that one or the other
of the tracing type methodologies is used consistently throughout
the application. If you decide to use the non-level types, choose
one type from each category and use those types consistently throughout
the application, to avoid confusion.
Message and trace parameters
The various
message logging and trace method signatures accept the
Object,
Object[] and
Throwable parameter
types.
WebSphere Application Server processes
and formats the various parameter types as follows:
- Primitives
- Primitives, such as int and long are not recognized as subclasses
of Object type and cannot be directly passed to one of these methods.
A primitive value must be transformed to a proper Object type (Integer,
Long) before passing as a parameter.
- Object
- The toString method is called on the object and the resulting
String is displayed. Implement the toString method appropriately for
any object that is passed to a message logging or trace method. It
is the responsibility of the caller to guarantee that the toString
method does not display confidential data such as passwords in clear
text, and does not cause infinite recursion.
- Object[]
- The Object[] type is provided for the case when more than one
parameter is passed to a message logging or trace method. The toString
method is called on each Object in the array. Nested arrays are not
handled, that is none of the elements in the Object array belong in
an array.
- Throwable
- The stack trace of the Throwable type is retrieved and displayed.
- Array of primitives
- An array of primitive, for example, byte[], int[],
is recognized as an Object, but is loosely associated by Java code. In general, avoid arrays of primitives,
if possible. If arrays of primitives are passed, the results are indeterminate
and can change, depending on the type of array passed, the API used
to pass the array, and the release of the product. For consistent
results, user code needs to preprocess and format the primitive array
into some type of String form before passing it to the method. If
such preprocessing is not performed, the following problems can result:
- [B@924586a0b - This message is deciphered as a byte array at location
X. This message is typically returned when an array is passed as a
member of an Object[] type and results from calling the toString method
on the byte[] type.
- Illegal trace argument : array of long. This response is typically
returned when an array of primitives is passed to a method taking
an Object.
- 01040703: The hex representation of an array of bytes. Typically
this problem can occur when a byte array is passed to a method taking
a single Object. This behavior is subject to change and cannot be
relied on.
- "1" "2": The String representation of the members of an int[]
type formed by converting each element to an integer and calling the
toString method on the integers. This behavior is subject to change
and cannot be relied on.
- [Ljava.lang.Object;@9136fa0b : An array of objects. Typically
this response is seen when an array containing nested arrays is passed.
Controlling message logging
Writing a message
to a
WebSphere Application Server log requires
that the message type passes three levels of filtering or screening:
- The message event type must be one of the message event types
that is defined in the RASIMessageEvent interface.
- Logging of that message event type must be enabled by the state
of the message logger mask.
- The message event type must pass any filtering criteria that is
established by the WebSphere Application Server run-time.
When a WebSphere Application Server logger
is obtained from the Manager class, the initial setting of the mask
forwards all native message event types to the WebSphere Application Server handler. It is
possible to control what messages get logged by programmatically setting
the state of the message logger mask.
Some editions of the product
support user specified message filter levels for a server process.
When such a filter level is set, only messages at the specified severity
levels are written to WebSphere Application Server.
Message types that pass the mask check of the message logger can be
filtered out by WebSphere Application Server.
Control tracing
Each edition of the product
provides a mechanism for enabling or disabling trace. The various
editions can support static trace enablement (trace settings are specified
before the server is started), dynamic trace enablement (trace settings
for a running server process can be dynamically modified), or both.
Writing
a trace record to a
WebSphere Application Server requires
that the trace type passes three levels of filtering or screening:
- The trace event type must be one of the trace event types that
is defined in the RASITraceEvent interface.
- Logging of that trace event type must be enabled by the state
of the trace logger mask.
- The trace event type must pass any filtering criteria that is
established by the WebSphere Application Server run-time.
When a logger is obtained from the Manager class, the
initial setting of the mask is to suppress all trace types. The exception
to this rule is the case where the WebSphere Application Server run time supports
static trace enablement and a non-default startup trace state for
that trace logger is specified. Unlike message loggers, the WebSphere Application Server can dynamically
modify the trace mask state of a trace logger. WebSphere Application Server only modifies
the portion of the trace logger mask that corresponds to the values
that are defined in the RASITraceEvent interface. WebSphere Application Server does not modify
undefined bits of the mask that might be in use for user-defined types.
When
the dynamic trace enablement feature that is available on some platforms
is used, the trace state change is reflected both in the application
server run time and the trace mask of the trace logger. If user code
programmatically changes the bits in the trace mask corresponding
to the values that are defined by in the RASITraceEvent interface,
the mask state of the trace logger and the run time state become unsynchronized
and unexpected results occur. Therefore, programmatically changing
the bits of the mask corresponding to the values that are defined
in the RASITraceEvent interface is not supported.