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. 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 |
Application developers can use JRas to issue
an MVS WTO (write to operator) message by using a JRas RASIMessageEvent type
of TYPE_INFO or TYPE_INFORMATION to issue a WebSphere Application Server for
z/OS Audit trace. A WebSphere Application Server for z/OS Audit trace maps
to an MVS route code 11 WTO (hardcopy WTO).
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:
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 |
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 treated somewhat as a second cousin of
Object 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.