Programming model summary

The programming model described in this topic builds upon and summarizes some of the concepts already introduced. This section also formalizes usage requirements and restrictions. Use of the WebSphere Application Server - Express 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 - Express 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 standalone 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 standalone 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 - Express 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.
• 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 standalone 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 standalone 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 standalone 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 - Express handler installed. This handler will write message and trace records to logs defined by the WebSphere Application Server - Express 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 - Express handler from the logger by calling the logger's removeHandler() method, passing in the reference to the WebSphere Application Server - Express handler. Once removed, the WebSphere Application Server - Express 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 - Express 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.