This section discusses the use of JRas loggers in WebSphere applications. Message and trace parameters discusses the message and trace parameters used with JRas objects. The RASILogger interface discusses the RASILogger interface, The RASIMessageLogger interface discusses the RASIMessageLogger interface, and The RASITraceLogger interface discusses the RASITraceLogger interface. Figure 3 shows examples of using these methods.
The JRas methods accept parameter types of Object, Object[], and Exception. The following is a list of parameter types and how they are handled by the WebSphere implementation of JRas.
The RASILogger interface is the base interface for both the RASIMessageLogger and RASITraceLogger classes. This section discusses topics that are common to both of these classes, including the isLoggable, getName and setName, and isSynchronous and setSynchronous methods. See Figure 3 for examples of the classes and methods being used in context.
The RASILogger interface provides the isLoggable method to determine whether a logger is currently enabled to log a particular event type. The event type to be checked is passed to the method. The definition is as follows:
public boolean isLoggable(long type);
where type is a valid message or trace type. See Message and trace event types for a discussion of message and trace types.
The getName and setName methods provide access to logger names. Because all loggers are assigned an unchangeable name by the manager when they are created, the setName method results in a null operation if used. The getName method can be used at any time to retrieve a logger's name. The definitions of these methods are as follows:
public String getName(); public void setName (String name);
where name is the logger's name.
The isSynchronous and setSynchronous methods enable applications to configure loggers to perform synchronous or asynchronous logging, assuming that the logger can accept the configuration. The configuration is set by the WebSphere run time, so the setSynchronous method is currently implemented as a null operation. The definitions of these methods are as follows:
public boolean isSynchronous(); public void setSynchronous(boolean flag);
where flag is a Boolean value indicating True (for synchronous logging) or False (for asynchronous logging).
The RASIMessageLogger interface provides methods that enable localizable message logging. These methods include getMessageFile and setMessageFile, message, msg, and textMessage. When an instance of RASIMessageLogger is obtained from the manager, you must provide nonnull strings that specify the logger's organization name, product name, and component information. These strings are unchangeable for the lifetime of the logger.
The logger interface includes support for an internal mask that identifies which categories of messages are to be logged and which categories are to be disregarded. The mask is set by the WebSphere run time when the logger is created.
The getMessageFile method enables you to specify a resource bundle that the logger uses to localize messages. If the name of the resource bundle is not specified, a default name is assumed. The setMessageFile enables you to configure the message logger with a message file that is used by a message logged by the message interface. There is no default value for the message file; if this value is not specified, using the message interface can have unpredictable results. See Creating resource bundles and message files for information on resource bundles. The definitions of the methods are as follows:
public String getMessageFile(); public void setMessageFile(String file);
where file is the name of the resource bundle.
The message method provides flexible access to message strings. The definition of the method is as follows:
public void message(long type, Object obj, String methodName, String key, Object parameter);
where:
The msg method also provides access to message strings; unlike the message method, it enables you to specify the resource bundle from which message text is to be retrieved. The definition of the method is as follows:
public void msg(long type, Object obj, String methodName, String key, String file, Object parameter);
where:
The textMessage method enables applications to send text messages that are not accessed from a resource bundle. This method is intended for use in development environments or environments in which localization support is not required. This method is not intended to be used in production code. The definition of the method is as follows:
public void textMessage(long type, Object obj, String methodName, String text, Object parameter);
where:
The RASITraceLogger interface provides methods that enable generic tracing mechanisms. These methods include entry, exit, trace, and exception. When an instance of RASITraceLogger is obtained from the manager, you must provide nonnull strings that specify the logger's organization name, product name, and component information. These strings are unchangeable for the lifetime of the logger.
The logger interface includes support for an internal mask that identifies which categories of trace events are to be logged and which categories are to be disregarded. The mask is set by the WebSphere run time when the logger is created.
The entry method provides access to trace entry events. The definition of the method is as follows:
public void entry(long type, Object obj, String methodName, Object parameter);
where:
The exit method provides access to trace exit events. The definition of the method is as follows:
public void exit(long type, Object obj, String methodName, Object retValue);
where:
The trace method provides a way to write text strings as trace events. The definition of the method is as follows:
public void trace(long type, Object obj, String methodName, String text, Object parameter);
where:
The exception method provides access to exceptions. The definition of the method is as follows:
public void exception(long type, Object obj, String methodName, Exception exc);
where:
Figure 3 shows an example of using a message logger and a trace logger.
Figure 3. Example code: Using a message logger and a trace logger
private void methodX(int x, String y, Foo z) { // Trace an entry point. Use the guard to ensure tracing is enabled. Do this // checking before we waste cycles gathering parameters to be traced. if (trcLogger.isLoggable(RASITraceEvent.TYPE_ENTRY_EXIT)) { // Because we want to trace three parameters, package them into an Object[] Object[] parms = {new Integer(x), y, z}; trcLogger.entry(RASITraceEvent.TYPE_ENTRY_EXIT, this, "methodX", parms); } // ...additional logic here... // A debug or verbose trace point if (trcLogger.isLoggable(RASITraceEvent.TYPE_MISC_DATA)) { trcLogger.trace(RASITraceEvent.TYPE_MISC_DATA, this, "methodX", "reached here"); } // ... // Call methodY on Foo. Assume that Foo is provided by another vendor or user. // This method throws no Exceptions, so any run-time exceptions such as a // NullPointerException coming out of it must be logged as errors. // Although it is not good practice to put stack traces into message, // it is not explicitly prohibited. try { z.methodY(...); } catch (Throwable t) { msgLogger.message(RASIMessageEvent.TYPE_ERR, this, "methodX", "MSG_KEY_01", t); } // ... // Another classification of trace event. An important state change was // detected, so a different trace type is used. if (trcLogger.isLoggable(RASITraceEvent.TYPE_SVC)) { trcLogger.trace(RASITraceEvent.TYPE_SVC, this, "methodX", "an important event"); } // ... // Ready to exit method, trace. No return value to trace. if (trcLogger.isLoggable(RASITraceEvent.TYPE_ENTRY_EXIT)) { trcLogger.exit(RASITraceEvent.TYPE_ENTRY_EXIT, this, "methodX"); } } |