The programming model that is described in this section
builds upon and summarizes some of the concepts already introduced.
This section also formalizes usage requirements and restrictions.
Use of the WebSphere® Application Server JRas extensions
in a manner that does not conform to the following programming guidelines
is prohibited.
Note: The JRas framework described in this
task and its sub-tasks is deprecated. However, you can achieve similar
results using Java logging.
You can use the WebSphere Application Server
JRas extensions in three distinct operational modes. The programming
models concepts and restrictions apply equally across all modes of
operation.
- You must not use implementation classes that are provided by the
stand-alone JRas logging toolkit directly, unless specifically noted
otherwise. Direct usage of those classes is not supported. IBM® Support
provides no diagnostic aid or bug fixes relating to the direct use
of classes that are provided by the stand-alone JRas logging toolkit.
- You must obtain message and trace loggers directly from the Manager
class. You cannot directly instantiate loggers.
- You cannot replace the WebSphere Application Server
message and trace logger classes.
- You must guarantee that the logger names that are passed to the
Manager class are unique, and follow the documented naming constraints.
When a logger is obtained from the Manager class, you must not attempt
to change the name of the logger by calling the setName method.
- Named loggers can be used more than once. For any given name,
the first call to the Manager class results in the Manager class creating
a logger that is associated with that name. Subsequent calls to the
Manager class that specify the same name result in a returned reference
to the existing logger.
- The Manager class maintains a hierarchical namespace for loggers.
Use a dot-separated, fully qualified class name to identify any logger.
Other than dots or periods, logger names cannot contain any punctuation
characters, such as an asterisk (*), a comma (.), an equals sign (=),
a colon (:), or quotes.
- Group names must comply with the same naming restrictions as
logger names.
- The loggers returned from the Manager class are subclasses of
the RASMessageLogger and the RASTraceLogger classes that are provided
by the stand-alone JRas logging toolkit. You can call any public method
that is defined by the RASMessageLogger and RASTraceLogger classes.
You cannot call any public method that is introduced by the provided
subclasses.
- If you want to operate in either stand-alone or combined mode,
you must provide your own Handler and Formatter subclasses. You cannot
use the Handler and Formatter classes that are provided by the stand-alone
JRas logging toolkit. User written handlers and formatters must conform
to the documented guidelines.
- Loggers that are obtained from the Manager class come with a WebSphere Application Server handler installed.
This handler writes message and trace records to logs that are defined
by the WebSphere Application Server run time.
Manage these logs using the provided systems management interfaces.
- You can programmatically add and remove user-defined handlers
from a logger at any time. Multiple additions and removals of user
defined handlers are supported. You are responsible for creating an
instance of the handler to add, configuring the handler by setting
the handler mask value and formatter appropriately, then adding the
handler to the logger using the addHandler method. You are responsible
for programmatically updating the masks of user-defined handlers,
as appropriate.
- You might get a reference to the handler that is installed within
a logger by calling the getHandlers method on the logger and processing
the results. You must not call any methods on the handler that are
obtained in this way. You can remove the WebSphere Application
Server handler from the logger by calling the logger removeHandler
method, passing in the reference to the WebSphere Application
Server handler. When removed, the WebSphere Application
Server handler cannot be added again to the logger.
- You can define your own message type. The behavior of user-defined
message types and restrictions on their definitions is discussed in JRas framework (deprecated).
- You can define your own message event classes. The use of user-defined
message event classes is discussed in JRas framework (deprecated).
- You can define your own trace types. The behavior of user-defined
trace types and restrictions on your definitions is discussed in JRas framework (deprecated).
- You can define your own trace event classes. The use of user-defined
trace event classes is discussed in JRas framework (deprecated).
- You must programmatically maintain the bits in the message and
trace logger masks that correspond to any user-defined types. If WebSphere Application Server facilities
are used to manage the predefined types, these updates must not modify
the state of any of the bits that correspond to those types. If you
are assuming ownership responsibility for the predefined types, then
you can change all bits of the masks.