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.
Deprecated: 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 Extending the JRas framework.
- You can define your own message event classes. The use of user-defined
message event classes is discussed in Extending the JRas framework.
- You can define your own trace types. The behavior of user-defined trace
types and restrictions on your definitions is discussed in Extending the JRas framework.
- You can define your own trace event classes. The use of user-defined
trace event classes is discussed in Extending
the JRas framework.
- 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.