gnu.cajo.utils

Class MonitorItem

java.lang.Object

gnu.cajo.utils.MonitorItem

All Implemented Interfaces:

Invoke, Serializable

public class MonitorItem
extends 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

Fields

Modifier and Type	Field and Description
static boolean	CLASSOFF This flag can be used to selectively enable and disable monitoring on a class-wide level.
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

Constructors

Constructor and Description
MonitorItem(Object item) This creates the monitor object, to instrument the target object's use.
MonitorItem(Object item, ObjectOutputStream os) This creates the monitor object, to instrument the target object's use.
MonitorItem(Object item, OutputStream os) This creates the monitor object, to instrument the target object's use.

Method Summary

Methods

Modifier and Type	Method and Description
Object	invoke(String method, 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 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(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(Object item,
           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(Object item,
           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 Object invoke(String method,
            Object args)
              throws Exception

This method logs the incoming calls, passing the caller's data to the internal item. It records the following information:

• The name of the item being called
• The host address of the caller (or localhost w/trace)
• The method the caller is invoking
• The data the caller is sending
• The data resulting from the invocation, or the Exception
• The number of times this method has been called
• The idle time between invocations, in milliseconds.
• The run time of the invocation time, in milliseconds
• The free memory percentage, following the invocation

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:

RemoteException - For a network related failure.

NoSuchMethodException - If the method/agruments signature cannot be matched to the internal object's public method interface.

Exception - If the internal object's method rejects the invocation.