This section describes JRas message and trace event types.
The JRas framework described in this task and its sub-tasks is deprecated.
However, you can achieve similar results using Java logging.
Event types
The base message and trace event types
defined by the stand-alone JRas logging toolkit are not the same as the "native"
types recognized by the WebSphere Application Server run-time. Instead the
basic JRas types are mapped onto the native types. This mapping may vary by
platform or edition. The mapping is discussed below.
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 provided by the stand-alone
JRas logging toolkit. 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
recognized and processed by the WebSphere Application Server runtime are defined
in the
RASITraceEvent interface provided by the stand-alone JRas
logging toolkit. The
RASITraceEvent interface provides a rich and
overly 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, RASITraceEvent provides TYPE_LEVEL1, TYPE_LEVEL2,
and TYPE_LEVEL3. The implementations provide support for this set
of levels. The levels are hierarchical (that is, enabling level 2 will also
enable 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, RASITraceEvent 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:
Mapping WebSphere Application Server trace types to JRas
RASITraceEvent "Level"
types.
WebSphere Application Server native
type |
JRas RASITraceEvent level type |
Event |
TYPE_LEVEL1 |
EntryExit |
TYPE_LEVEL2 |
Debug |
TYPE_LEVEL3 |
Mapping WebSphere Application Server trace types to 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.
For users who decide to use the non-level types, it is further recommended
that you choose one type from each category and use those consistently throughout
the application to avoid confusion.
Message and Trace parameters
The various message
logging and trace method signatures accept parameter types of
Object,
Object[] and
Throwable.
WebSphere Application Server will process and format the various parameter
types as follows.
- Primitives
- Primitives, such as int and long are not recognized
as subclasses of Object and cannot be directly passed to one of these
methods. A primitive value must be transformed to a proper Object type
(Integer, Long) before being passed as a parameter.
- Object
- toString() is called on the object and the resulting String is
displayed. The toString() method should be implemented appropriately
for any object 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[] is provided for the case when more than one parameter
is passed to a message logging or trace method. toString() is called
on each Object in the array. Nested arrays are not handled. (i.e.
none of the elements in the Object array should be an array).
- Throwable
- The stack trace of the Throwable is retrieved and displayed.
- Array of Primitives
- An array of primitive (e.g. byte[], int[] is recognized
as an Object, but is treated somewhat as a second cousin of Object by
Java code. In general, arrays of primitives should be avoided, if possible.
If arrays of primitives are passed, the results are indeterminate and may
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 should 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 may
result.
- [B@924586a0b - This is deciphered as "a byte array at location X". This
is typically returned when an array is passed as a member of an Object[].
It is the result of calling toString() on the byte[].
- Illegal trace argument : array of long. This 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
may be seen when a byte array is passed to a method taking a single Object.
This behavior is subject to change and should not be relied on.
- "1" "2" ... : The String representation of the members of an int[] formed
by converting each element to an Integer and calling toString on
the Integers. This behavior is subject to change and should not be relied
on.
- [Ljava.lang.Object;@9136fa0b : An array of objects. Typically this 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 defined
in the RASIMessageEvent interface.
- Logging of that message event type must be enabled by the state of the
message logger's mask.
- The message event type must pass any filtering criteria established by
the WebSphere Application Server run-time itself.
When a WebSphere Application Server logger is obtained from the
Manager, the initial setting of the mask is to forward 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's mask.
Some editions of the product allow the user
to specify a message filter level for a server process. When such a filter
level is set, only messages at the specified severity levels are written to
WebSphere Application Server logs. This means that messages types that pass
the message logger's mask check may be filtered out by the WebSphere Application
Server itself.
Controlling Tracing
Each edition of the product
provides a mechanism for enabling or disabling trace. The various editions
may 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 defined in the RASITraceEvent interface.
- Logging of that trace event type must be enabled by the state of the trace
logger's mask.
- The trace event type must pass any filtering criteria established by the
WebSphere Application Server run-time itself.
When a logger is obtained from the Manager, 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 has
been specified. Unlike message loggers, the WebSphere Application Server
may dynamically modify the state of a trace loggers trace mask. WebSphere
Application Server will only modify the portion of the trace logger's mask
corresponding to the values defined in the RASITraceEvent interface.
WebSphere Application Server will not modify undefined bits of the mask that
may be in use for user defined types.
When the dynamic trace enablement
feature available on some platforms is used, the trace state change is reflected
both in the Application Server run-time and the trace loggers trace mask.
If user code programmatically changes the bits in the trace mask corresponding
to the values defined by in the RASITraceEvent interface, the trace
logger's mask state and the run-time state will become unsynchronized and
unexpected results will occur. Therefore, programmatically changing the bits
of the mask corresponding to the values defined in the RASITraceEvent interface
is not allowed.