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.

Note: The JRas framework described in this task and its sub-tasks is deprecated. However, one can achieve similar results using Java logging.

As described previously, use the WAS 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. We 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, 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, 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 WAS runtime. Manage these logs using the provided systems management interfaces.

  • We 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 WAS handler from the logger by calling the logger's removeHandler() method, passing in the reference to the WAS 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 one can change all bits of the masks.