Programming model summary
The programming model 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.
As described previously, 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 provided by the stand-alone JRas
logging toolkit directly, unless specifically noted otherwise. Direct usage
of those classes is not supported. IBM Support will provide no diagnostic
aid or bug fixes relating to direct usage of classes 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.
- There is no provision that allows you to replace the WebSphere Application
Server message and trace logger classes.
- You must guarantee that the logger names passed to the Manager are unique,
and follow the naming constraints documented below. Once a logger is obtained
from the Manager, 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 results in the Manager creating a logger
that is associated with that name. Subsequent calls to the Manager that specify
the same name result in a reference to the existing logger being returned.
- The Manager maintains a hierarchical namespace for loggers. It is recommended
but not required that a dot-separated, fully qualified class name be used
to identify any given logger. Other than dots or periods, logger names cannot
contain any punctuation characters, such as asterisk (*), comma(.), equals
sign(=), colon(:), or quotes.
- Group names must comply with the same naming restrictions as logger names.
- The loggers returned from the Manager are subclasses of the RASMessageLogger
and RASTraceLogger provided by the stand-alone JRas logging toolkit. You are
allowed to call any public method defined by the RASMessageLogger and RASTraceLogger
classes. You are not allowed to call any public method 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 are not allowed to
use the Handler and Formatter classes provided by the stand-alone JRas logging
toolkit. User written Handlers and Formatters must conform to the documented
guidelines.
- Loggers obtained from the Manager come with a WebSphere Application Server
handler installed. This handler will write message and trace records to logs
defined by the WebSphere Application Server runtime. 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 allowed. You are responsible for creating an instance of the handler to
add, configuring the handler by setting the handler's 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 may get a reference to the handler 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 obtained in this fashion. You
are allowed to remove the WebSphere Application Server handler from the logger
by calling the logger's removeHandler() method, passing in the reference
to the WebSphere Application Server handler. Once removed, the WebSphere Application
Server handler cannot be re-added to the logger.
- You are allowed to 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 are allowed to define your own message event classes. The usage
of user-defined message event classes is discussed in Extending the JRas framework.
- You are allowed to 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 are allowed to define your own trace event classes. The usage 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 being used to manage the predefined types, these updates
must not modify the state of any of the bits corresponding to those types.
If you are assuming ownership responsibility for the predefined types then
you can change all bits of the masks.
Searchable topic ID:
ctrb_jrasprgsum
Last updated: Jun 21, 2007 9:56:50 PM CDT
WebSphere Application Server for z/OS, Version 5.0.2
http://publib.boulder.ibm.com/infocenter/wasinfo/index.jsp?topic=/com.ibm.websphere.zseries.doc/info/zseries/ae/ctrb_jrasprgsum.html