gnu.cajo.utils
Class MonitorItem

java.lang.Object
  extended by gnu.cajo.utils.MonitorItem
All Implemented Interfaces:
Invoke, java.io.Serializable

public class MonitorItem
extends java.lang.Object
implements Invoke

This class is used to instrument an object for invocation logging purposes. It is intended as a replacement for standard RMI logging, in that this logger is aware of the Invoke package methodology, and can decode it properly. Specifically, it will gather information about the calling client, the method called, the inbound and outbound data. It will also record the approximate time between client invocations, the time used to service the invocation, and the approximate percentage of free memory available at the completion of the operation. Subclassing of MonitorItem is allowed; primarily to create self-monitoring classes.

Note: monitoring an object can be expensive in runtime efficiency. It is best used for debug and performance analysis, during development, or in production, for objects that would not be called very frequently.

Version:
1.0, 01-Nov-99 Initial release
Author:
John Catherino
See Also:
Serialized Form

Field Summary
static boolean CLASSOFF
          This flag can be used to selectively enable and disable monitoring on a class-wide level.
 java.lang.Object item
          The object being monitored.
 boolean LOCALOFF
          This flag can be used to selectively enable and disable monitoring on a instance-wide level.
 
Constructor Summary
MonitorItem(java.lang.Object item)
          This creates the monitor object, to instrument the target object's use.
MonitorItem(java.lang.Object item, java.io.ObjectOutputStream os)
          This creates the monitor object, to instrument the target object's use.
MonitorItem(java.lang.Object item, java.io.OutputStream os)
          This creates the monitor object, to instrument the target object's use.
 
Method Summary
 java.lang.Object invoke(java.lang.String method, java.lang.Object args)
          This method logs the incoming calls, passing the caller's data to the internal item.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CLASSOFF

public static boolean CLASSOFF
This flag can be used to selectively enable and disable monitoring on a class-wide level. By default it is set to false, when true, no output to any logstream will take place.


LOCALOFF

public boolean LOCALOFF
This flag can be used to selectively enable and disable monitoring on a instance-wide level. By default it is set to false, when true, no output to the logstream will take place.


item

public final java.lang.Object item
The object being monitored. It is declared as public to allow the reference of the MontorItem, and its wrapped object, from a single instance of MonitorItem.

Constructor Detail

MonitorItem

public MonitorItem(java.lang.Object item)
This creates the monitor object, to instrument the target object's use. The the logging information will be sent to System.out automatically.

Parameters:
item - The object to receive the client invocation.

MonitorItem

public MonitorItem(java.lang.Object item,
                   java.io.OutputStream os)
This creates the monitor object, to instrument the target object's use. The the logging information is passed to the OutputStream, where it can be logged to a file, a socket, or simply sent to the console (System.out). The logged data is in text format.

Parameters:
item - The object to receive the client invocation.
os - The OutputStream to send the formatted log information.

MonitorItem

public MonitorItem(java.lang.Object item,
                   java.io.ObjectOutputStream os)
This creates the monitor object, to instrument the target object's use. The the logging information is passed to an ObjectOutputStream. Note: this type of monitoring provides both the greatest detail, and can be most easily manipulated programmatically. However, it is even more expensive than text logging. The log file can become extremely large, if the objects passed in or out are complex, or if the object is called frequently. Therefore, it is highly recommended to implement the ObjectOutputStream on top of a GZipOutputStream. Note: to preserve remote object codebase annotation, all of the objects associated with the particular method invocation log are stored, in order, in an Object array, contained within a java.rmi.MarshalledObject.

Parameters:
item - The object to receive the client invocation.
os - The ObjectOutputStream to send input and result objects.
Method Detail

invoke

public java.lang.Object invoke(java.lang.String method,
                               java.lang.Object args)
                        throws java.lang.Exception
This method logs the incoming calls, passing the caller's data to the internal item. It records the following information: If the write operation to the log file results in an exception, the stack trace of will be printed to System.err.

Note: Logging may be activated and deactivated administratively as needed on both an instance-wide basis via the field LOCALOFF, and on a class-wide basis via the static field CLASSOFF.

Specified by:
invoke in interface Invoke
Parameters:
method - The internal object's public method being called.
args - The arguments to pass to the internal object's method.
Returns:
The sychronous data, if any, resulting from the invocation.
Throws:
java.rmi.RemoteException - For a network related failure.
java.lang.NoSuchMethodException - If the method/agruments signature cannot be matched to the internal object's public method interface.
java.lang.Exception - If the internal object's method rejects the invocation.