Package net.sf.eBusx.monitor

Class Monitor

java.lang.Object

net.sf.eBusx.monitor.Monitor

All Implemented Interfaces:

EObject

public final class Monitor
extends java.lang.Object
implements EObject

This class provides the ability to instrument eBus objects and monitor those instrumented object's status. The first step is to open a Monitor instance. Note that only one Monitor may be opened and it stays open as long as the JVM is running. The next step is registering eBus objects. Once registered, these objects may report on-going status and transient events. When an eBus object is no longer operational, it should be de-registered from Monitor.

Note: Monitor does not maintain a strong reference to registered eBus objects. This means that an eBus object can be finalized while still registered with Montior. If this happens, Monitor will automatically de-register the finalized eBus object.

Monitor publishes:

• ApplicationInfo reporting the monitor's opening,
• PersistentStatusMessage reporting an update to an eBus object's on-going status, and
• TransientStatusMessage reporting an eBus object's transient event.

Monitor also handles the following requests:

• ApplicationInfoRequest: request for monitor's application information. ApplicationInfoReply is sent in reply.
• MonitoredObjectRequest: request for current on-going registered eBus objects. MonitoredObjectReply is sent in reply containing PersistentStatusMessages.

Note: there is no way to request previously post transient events. These can only be received when actively subscribed to transient status events.

See package documentation for a detailed explanation on how to use Monitor. The package documentation provides detailed explanation on how to instrument an eBus object and monitor updates.

Author:

Charles Rapp

See Also:

openMonitor(String, String, String, String, String, EField), getMonitor()

Field Summary

Fields

Modifier and Type	Field	Description
static java.lang.String	APP_INFO_REQUEST_SUBJECT	ApplicationInfoRequest is advertised with the subject "/eBus/monitor/request/app-info" to form request key.
static java.lang.String	DEREGISTER_ACTION_NAME	MonitorUpdate action name is "deregistered".
static java.lang.String	MONITOR_NAME	eBus object name is ""eBus monitor"".
static long	MONITOR_PUBLISHER_ID	Monitor publisher identifier is -2001L.
static java.lang.String	MONITOR_UPDATE_FORMAT	MONITOR_UPDATE_FORMAT is advertised with the subject "/eBus/monitor/update/%s/%s" with host and application name to form this notification key.
static java.lang.String	ONGOING_REQUEST_SUBJECT	MonitoredObjectRequest is advertised with the subject "/eBus/monitor/request/on-going" to form request key.
static java.lang.String	REGISTER_ACTION_NAME	MonitorUpdate action name is "registered".

Fields inherited from interface net.sf.eBus.client.EObject

NAME_NOT_SET

Method Summary

Modifier and Type	Method	Description
java.lang.String	applicationName()	Returns configured application name.
EField	attributes()	Returns application attributes.
java.lang.String	copyright()	Returns application copyright.
void	deregister(EObject obj)	Removes a registered eBus object from the monitor subsystem, retracting its published status and transient event feeds.
java.lang.String	description()	Returns application description.
static Monitor	getMonitor()	Returns singleton monitor instance.
java.lang.String	hostName()	Returns configured host name.
java.lang.String	name()	Returns MONITOR_NAME.
static Monitor	openMonitor(java.lang.String host, java.lang.String appName, java.lang.String version, java.lang.String copyright, java.lang.String description, EField attributes)	Creates, starts, and returns singleton monitor instance.
void	register(EObject obj)	Registers a monitorable object and returns unique monitor identifier associated with registered object.
void	startup()	Creates, registers, and starts monitor publisher and replier eBus objects.
void	transientStatus(ActionLevel actionLevel, java.lang.String actionName, java.lang.String actionMsg, EObject obj)	Posts a one-time transient event for the given monitorable object.
void	update(ActionLevel actionLevel, java.lang.String actionName, java.lang.String actionMsg, EObject obj)	Updates the monitorable object on-going status with the given parameters.
java.lang.String	version()	Returns configured application version.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface net.sf.eBus.client.EObject

shutdown

Field Detail

MONITOR_PUBLISHER_ID

public static final long MONITOR_PUBLISHER_ID

Monitor publisher identifier is -2001L.

See Also:

Constant Field Values

MONITOR_NAME

public static final java.lang.String MONITOR_NAME

eBus object name is ""eBus monitor"".

See Also:

Constant Field Values

REGISTER_ACTION_NAME

public static final java.lang.String REGISTER_ACTION_NAME

MonitorUpdate action name is "registered".

See Also:

Constant Field Values

DEREGISTER_ACTION_NAME

public static final java.lang.String DEREGISTER_ACTION_NAME

MonitorUpdate action name is "deregistered".

See Also:

Constant Field Values

MONITOR_UPDATE_FORMAT

public static final java.lang.String MONITOR_UPDATE_FORMAT

MONITOR_UPDATE_FORMAT is advertised with the subject "/eBus/monitor/update/%s/%s" with host and application name to form this notification key.

See Also:

Constant Field Values

APP_INFO_REQUEST_SUBJECT

public static final java.lang.String APP_INFO_REQUEST_SUBJECT

ApplicationInfoRequest is advertised with the subject "/eBus/monitor/request/app-info" to form request key.

See Also:

Constant Field Values

ONGOING_REQUEST_SUBJECT

public static final java.lang.String ONGOING_REQUEST_SUBJECT

MonitoredObjectRequest is advertised with the subject "/eBus/monitor/request/on-going" to form request key.

See Also:

Constant Field Values

Method Detail

name

public java.lang.String name()

Returns MONITOR_NAME.

Specified by:

name in interface EObject

Returns:

returns eBus monitor name.

startup

public void startup()

Creates, registers, and starts monitor publisher and replier eBus objects.

Specified by:

startup in interface EObject

See Also:

EObject.shutdown()

hostName

public java.lang.String hostName()

Returns configured host name. Please note that this name is not necessarily a network host name.

Returns:

host name.

applicationName

public java.lang.String applicationName()

Returns configured application name.

Returns:

application name.

version

public java.lang.String version()

Returns configured application version.

Returns:

application version.

copyright

@Nullable
public java.lang.String copyright()

Returns application copyright. May return a null value.

Returns:

application copyright.

description

@Nullable
public java.lang.String description()

Returns application description. May return a null value.

Returns:

application description.

attributes

@Nullable
public EField attributes()

Returns application attributes. May return a null value.

Returns:

application attributes.

getMonitor

@Nullable
public static Monitor getMonitor()

Returns singleton monitor instance. Returns null if monitor was not previously opened.

Returns:

singleton monitor instance.

register

public void register(EObject obj)

Registers a monitorable object and returns unique monitor identifier associated with registered object. The object's initial persistent status is set to ActionLevel.NO_ACTION, "Registered". An eBus object must successfully register prior to updating its status or posting a transient event.

Note: monitor does not maintain a strong references to obj. If this eBus object is finalized while still registered with Monitor, then monitor is informed of this finalization and automatically de-registers the finalized eBus object.

Parameters:

obj - register this monitorable object.

Throws:

java.lang.NullPointerException - if obj is null.

java.lang.IllegalArgumentException - if obj is null or EObject.name() returns a null or empty string.

See Also:

update(ActionLevel, String, String, EObject), transientStatus(ActionLevel, String, String, EObject), deregister(EObject)

update

public void update(ActionLevel actionLevel,
                   java.lang.String actionName,
                   @Nullable
                   java.lang.String actionMsg,
                   EObject obj)

Updates the monitorable object on-going status with the given parameters.

Parameters:

actionLevel - the action level.

actionName - the action name.

actionMsg - the human-readable action message. May be null or an empty string.

obj - the registered monitorable object.

Throws:

java.lang.NullPointerException - if obj is null.

java.lang.IllegalArgumentException - if actionName is either null or an empty string.

java.lang.IllegalStateException - if obj is not registered.

See Also:

transientStatus(ActionLevel, String, String, EObject), register(EObject), deregister(EObject)

transientStatus

public void transientStatus(ActionLevel actionLevel,
                            java.lang.String actionName,
                            @Nullable
                            java.lang.String actionMsg,
                            EObject obj)

Posts a one-time transient event for the given monitorable object.

Parameters:

actionLevel - the action level.

actionName - the action name.

actionMsg - the human-readable action message. May be null or an empty string.

obj - the registered monitorable object.

Throws:

java.lang.NullPointerException - if obj is null.

java.lang.IllegalArgumentException - if actionName is either null or an empty string.

java.lang.IllegalStateException - if obj is not registered.

See Also:

register(EObject), update(ActionLevel, String, String, EObject), deregister(EObject)

deregister

public void deregister(EObject obj)

Removes a registered eBus object from the monitor subsystem, retracting its published status and transient event feeds.

Parameters:

obj - remove this monitorable instance.

Throws:

java.lang.NullPointerException - if obj is null.

See Also:

update(ActionLevel, String, String, EObject), transientStatus(ActionLevel, String, String, EObject), register(EObject)

openMonitor

public static Monitor openMonitor(java.lang.String host,
                                  java.lang.String appName,
                                  java.lang.String version,
                                  @Nullable
                                  java.lang.String copyright,
                                  @Nullable
                                  java.lang.String description,
                                  @Nullable
                                  EField attributes)

Creates, starts, and returns singleton monitor instance. Please note that when calling this method for the first time, the method blocks until Monitor instance is started. Parameter values are left up to the user to decide what constitutes a valid setting. Note that these values should be meaningful to both the application and to those monitoring the application.

For example, consider host. A natural reaction is to use the name configured by the network support team. But these names are often arcane and meaningful only to network support. The application team may refer to this host as "uat-ny-1" - meaning the first user acceptance testing host (uat) site in New York. Since Monitor operates at the application level, this would be a better host name. This also applies to the remaining parameters.

The attributes parameter allows an application to add any number of additional settings by extending an eBus EField. A partial example is:

import net.sf.eBus.messages.EField;

public final class MyAppAttributes
    extends EField {
    // Report when this application was released to production.
    public final ZonedDateTime releaseDate;

    // Text providing production release authorization.
    public final String releaseSignOff;

    // Application is running on this Java version.
    public final String javaVersion;

    // JVM implementation vendor.
    public final String javaVendor;

    // ... and any other attributes deemed necessary for
    // application support.
}

If monitor is already open, then returns the monitor singleton instance.

Parameters:

host - monitor running on this "host". Does not necessary need to be a network host name.

appName - the application name. May not be null or empty.

version - the application version. May not be null or empty.

copyright - the application copyright. May be null.

description - the application description. May be null.

attributes - the application-specific attributes. May be null.

Returns:

singleton monitor instance.

Throws:

java.lang.IllegalArgumentException - if either host, name or version is null or empty.