net.sf.eBusx.monitor.package-info Maven / Gradle / Ivy
//
// Copyright 2012 Charles W. Rapp
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
/**
* 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;