The JRas framework described in this task and its sub-tasks is
deprecated. However, you can achieve similar results using Java logging.
General considerations
You can configure the WebSphere® Application
Server to use Java 2 security to restrict access to protected resources
such as the file system and sockets. Because user-written extensions typically
access such protected resources, user-written extensions must contain the
appropriate security checking calls, using AccessController doPrivileged calls.
In addition, the user-written extensions must contain the appropriate policy
file. In general, locating user-written extensions in a separate package is
a good practice. It is your responsibility to restrict access to the user-written
extensions appropriately.
Writing a handler
User-written handlers must implement
the RASIHandler interface. The RASIHandler interface extends the RASIMaskChangeGenerator
interface, which extends the RASIObject interface. A short discussion of the
methods that are introduced by each of these interfaces follows, along with
implementation pointers. For more in-depth information on any of the particular
interfaces or methods, see the corresponding product API documentation.
RASIObject interface
The RASIObject interface is
the base interface for stand-alone JRas logging toolkit classes that are stateful
or configurable, such as loggers, handlers, and formatters.
- The stand-alone JRas logging tookit supports rudimentary properties-file
based configuration. To implement this configuration support, the configuration
state is stored as a set of key-value pairs in a properties file. The public
Hashtable getConfig and public void setConfig(Hashtable ht) methods are used
to get and set the configuration state. The JRas extensions do not support
properties-based configuration. Implement these methods as no-operations.
You can implement your own properties-based configuration using these methods.
- Loggers, handlers, and formatters can be named objects. For example, the
JRas extensions require the user to provide a name for the loggers that are
retrieved from the manager. You can name your handlers. The public String
getName and public void setName(String name) methods are provided to get or
set the name field. The JRas extensions currently do not call these methods
on user handlers. You can implement these methods as you want, including as
no operations.
- Loggers, handlers, and formatters can also contain a description field.
The public String getDescription and public void setDescription(String desc)
methods can be used to get or set the description field. The JRas extensions
currently do not use the description field. You can implement these methods
as you want, including as no operations.
- The public String getGroup method is provided for use by the RASManager
interface. Since the JRas extensions provide their own Manager class, this
method is never called. Implement this as a no-operation.
RASIMaskChangeGenerator interface
The RASIMaskChangeGenerator
interface is the interface that defines the implementation methods for filtering
of events based on a mask state. It is currently implemented by both loggers
and handlers. By definition, an object that implements this interface contains
both a message mask and a trace mask, although both need not be used. For
example, message loggers contain a trace mask, but the trace mask is never
used because the message logger never generates trace events. Handlers, however,
can actively use both mask values. For example, a single handler can handle
both message and trace events.
- The public long getMessageMask and public void setMessageMask(long mask)
methods are used to get or set the value of the message mask. The public long
getTraceMask and public void setTraceMask(long mask) methods are used to get
or set the value of the trace mask.
In addition, this interface introduces the concept of calling back to
interested parties when a mask changes state. The callback object must implement
the RASIMaskChangeListener interface.
- The public void addMaskChangeListener(RASIMaskChangeListener listener)
and public void removeMaskChangeListener(RASIMaskChangeListener listener)
methods are used to add or remove listeners to the handler. The public Enumeration
getMaskChangeListeners method returns an enumeration over the list of currently
registered listeners. The public void fireMaskChangedEvent(RASMaskChangeEvent
mc) method is used to call back all the registered listeners to inform them
of a mask change event.
For efficiency reasons, the JRas extensions message and trace loggers
implement the RASIMaskChangeListener interface. The logger implementations
maintain a composite mask in addition to the logger mask. The logger composite
mask is formed by logically or'ing the appropriate masks of all handlers
that are registered to that logger, then and'ing the result with the
logger mask. For example, the message logger composite mask is formed by or'ing
the message masks of all handlers that are registered with that logger, then
and'ing the result with the logger message mask.
All handlers are required
to properly implement these methods. In addition, when a user handler is instantiated,
the logger that is added must be registered with the handler; use the addMaskChangeListener
method. When either the message mask or trace mask of the handler is changed,
the logger must be called back to inform it of the mask change. With this
process, the logger can dynamically maintain the composite mask.
The
RASMaskChangedEvent class is defined by the stand-alone JRas logging toolkit.
Direct use of that class by user code is supported in this context.
In
addition, the RASIMaskChangeGenerator interface introduces the concept of
caching the names of all message and trace event classes that the implementing
object process. The intent of these methods is to support a management program
such as a graphical user interface to retrieve the list of names, introspect
the classes to determine the event types that they might possibly process
and display the results. The JRas extensions do not ever call these methods,
so they can be implemented as no operations.
- The public void addMessageEventClass(String name) and public void removeMessageEventClass(String
name) methodscan be called to add or remove a message event class name from
the list. The method public Enumeration getMessageEventClasses returns an
enumeration over the list of message event class names. Similarly, the public
void addTraceEventClass(String name) and public void removeTraceEventClass(String
name) methods can be called to add or remove a trace event class name from
the list. The public Enumeration getTraceEventClasses method returns an enumeration
over the list of trace event class names.
RASIHandler interface
The RASIHandler interface
introduces the methods that are specific to the behavior of a handler.
The
RASIHandler interface, as provided by the stand-alone JRas logging toolkit,
supports handlers that run in either a synchronous or asynchronous mode. In
asynchronous mode, events are typically queued by the calling thread and then
written by a worker thread. Because spawning of threads is not supported in
the WebSphere Application
Server environment, it is expected that handlers do not queue or batch events,
although this activity is not expressly prohibited.
- The public int getMaximumQueueSize() and public void setMaximumQueueSize(int
size) methods create IllegalStateException exceptions to manage the
maximum queue size. The public int getQueueSize method is provided to query
the actual queue size.
- The public int getRetryInterval and public void setRetryInterval(int interval)
methods support the notion of error retry, which implies some type of queueing.
- The public void addFormatter(RASIFormatter formatter), public void removeFormatter(RASIFormatter
formatter) and public Enumeration getFormatters methods are provided to manage
the list of formatters that the handler can be configured with. Different
formatters can be provided for different event classes, if appropriate.
- The public void openDevice, public void closeDevice and public void stop
methods are provided to manage the underlying device that the handler abstracts.
- The public void logEvent(RASIEvent event) and public void writeEvent(RASIEvent
event) methods are provided to pass events to the handler for processing.
Writing a formatter
User-written formatters must
implement the RASIFormatter interface. The RASIFormatter interface extends
the RASIObject interface. The implementation of the RASIObject interface is
the same for both handlers and formatters. A short discussion of the methods
that are introduced by the RASIFormatter interface follows. For more in-depth
information on the methods introduced by this interface, see the corresponding
product API documentation.
RASIFormatter interface
- The public void setDefault(boolean flag) and public boolean isDefault
methods are used by the concrete RASHandler classes that are provided by the
stand-alone JRas logging toolkit to determine if a particular formatter is
the default formatter. Because these RASHandler classes must never be used
in a WebSphere Application
Server environment, the semantic significance of these methods can be determined
by the user.
- The public void addEventClass(String name), public void removeEventClass(String
name) and public Enumeration getEventClasses methods are provided to determine
which event classes a formatter can use to format. You can provide the appropriate
implementations.
- The public String format(RASIEvent event) method is called by handler
objects and returns a formatted String representation of the event.