net.sf.eBusx.monitor.package-info Maven / Gradle / Ivy
/*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later
* version.
*
* This library is distributed in the hope that it will be
* useful, but WITHOUT ANY WARRANTY; without even the implied
* warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
* PURPOSE. See the GNU Lesser General Public License for more
* details.
*
* You should have received a copy of the GNU Lesser General
* Public License along with this library; if not, write to the
*
* Free Software Foundation, Inc.,
* 59 Temple Place, Suite 330,
* Boston, MA
* 02111-1307 USA
*
* The Initial Developer of the Original Code is Charles W. Rapp.
* Portions created by Charles W. Rapp are
* Copyright 2012. Charles W. Rapp
* All Rights Reserved.
*/
/**
* This package provides messages to monitor both the on-going
* state and transient events of an eBus application at the
* object-level.
*
* An on-going state is one that persists over time. An example
* is a disconnected connection. This state continues until
* either re-established or explicitly closed by the application.
* A transient event occurs in an instant, with no on-going
* impact to the application. An example of a transient event
* would be the application catching exception from which it
* immediately recovers. This exception is reported as a
* transient event so administrators are aware of the problem.
*
*
* Both on-going status and transient events are reported with
* a given
* {@link net.sf.eBusx.monitor.ActionLevel action level}.
* This action level
* informs administrators about the event severity. The need to
* report
* {@link net.sf.eBusx.monitor.ActionLevel#POSSIBLE_ACTION},
* {@link net.sf.eBusx.monitor.ActionLevel#ACTION_REQUIRED} and
* {@link net.sf.eBusx.monitor.ActionLevel#FATAL_ERROR} events is
* obvious: there is a problem occurring which must be corrected.
* But there is debate about reporting
* {@link net.sf.eBusx.monitor.ActionLevel#NO_ACTION},
* information-only events. One view is that an application may
* be considered to be operating correctly unless stated
* otherwise. The opposing view is that,
* "if it goes without saying, then it goes even better with
* saying it." By reporting "no action" events, it is an
* explicit statement of correct operation.
*
* Making your application monitorable
* The starting point is to report your application name,
* version, copyright, description and optional name/value
* attributes using
* {@link net.sf.eBusx.monitor.Monitor#applicationInfo(String, String, String, String, net.sf.eBus.messages.EField)}.
* This method should be called once at system start although
* there is nothing to prevent the information from being
* modified.
*
* Classes that you want to monitor should implement
* {@link net.sf.eBusx.monitor.Monitorable} interface. This
* interface contains a single method:
* {@link net.sf.eBusx.monitor.Monitorable#instanceName}. The
* implemented version should return a unique name for each class
* instance. This allows administrators to determine
* which instance is reporting a problem. The monitorable object
* must next be
* {@link net.sf.eBusx.monitor.Monitor#register(Monitorable) registered}.
* The initial monitorable state is:
*
*
* -
* Action level: {@link net.sf.eBusx.monitor.ActionLevel#NO_ACTION}
*
* -
* Action name: Registered
*
* -
* Action message: Registered with monitor subsystem
*
*
* {@link net.sf.eBusx.monitor.Monitor} reports object
* registration via the
* {@link net.sf.eBusx.monitor.MonitorUpdate} notification message
* which contains the
* {@link net.sf.eBusx.monitor.MonitorId} and
* {@link net.sf.eBusx.monitor.MonitorUpdate#updateFlag}
* set to {@code true}.
*
* Once registered, a monitorable object may
* {@link net.sf.eBusx.monitor.Monitor#update(net.sf.eBusx.monitor.ActionLevel, String, String, net.sf.eBusx.monitor.Monitorable) update}
* its on-going, persistent state and report
* {@link net.sf.eBusx.monitor.Monitor#transientStatus(net.sf.eBusx.monitor.ActionLevel, String, String, net.sf.eBusx.monitor.Monitorable) transient events}.
* If a registered monitorable object is to be discarded prior
* to application termination, it should be
* {@link net.sf.eBusx.monitor.Monitor#deregister(net.sf.eBusx.monitor.Monitorable) deregistered}
* because the monitor subsystem maintains a reference to the
* monitorable object, preventing its garbage collection. Again,
* a {@code MonitorUpdate} notification is published with the
* {@code updateFlag} set to {@code false} to inform subscribers
* that the object is no longer available for monitoring.
*
Monitoring eBus applications
* The steps involved in monitoring eBus applications are:
*
* -
* Open a connection to each of the eBus applications you
* will be monitoring.
*
* -
* Subscribe to the
* {@link net.sf.eBusx.monitor.MonitorUpdate} using the
* subject
* {@link net.sf.eBusx.monitor.Monitor#MONITOR_UPDATE_SUBJECT}.
*
* -
* Request the currently registered monitored objects with
* {@link net.sf.eBusx.monitor.MonitoredObjectRequest}
* using the subject {@code Monitor.MONITOR_UPDATE_SUBJECT}.
*
* Note: because you are subscribe to {@code MonitorUpdate},
* which reports monitor object registrations and
* deregistrations as they happen, there is a possibility of
* overlapping
* {@link net.sf.eBusx.monitor.MonitorId monitor identifiers}
* as reported in
* {@link net.sf.eBusx.monitor.MonitoredObjectReply}.
*
* -
* Subscribe to the
* {@link net.sf.eBusx.monitor.PersistentStatusMessage}
* and/or
* {@link net.sf.eBusx.monitor.TransientStatusMessage} for
* those monitor identifiers in which you are interested
* using {@link net.sf.eBusx.monitor.MonitorId#toString} as
* the notification subject.
*
*
* An optional step is to subscribe to
* {@link net.sf.eBusx.monitor.ApplicationInfo} with the subject
* {@code Monitor.MONITOR_UPDATE_SUBJECT}. This will each
* application's name, version, copyright, description and
* optional name, value attributes.
*/
package net.sf.eBusx.monitor;