Version 4

    The AlarmManager Helper


    The org.jboss.monitor.alarm.AlarmManager is a helper class that can be used

    from mbeans that need to produce stateful or stateless

    org.jboss.monitor.alarm.AlarmNotification notifications.


    Instantiating AlarmManager


    To use the AlarmManager from an mbean extending ServiceMBeanSupport

    simply do:

       import org.jboss.monitor.alarm.Alarm;
       import org.jboss.monitor.alarm.AlarmManager;
       /** The alarm manager helper */
       private AlarmManager alm = new AlarmManager(this);


    If your mbean does not extend ServiceMBeanSupport, you need to provide

    an implementation of MBeanImplAccess (essentially an adapter class),

    so that AlarmManager has a way to:

    1. find out the producing mbean ObjectName

    2. generate unique sequence numbers

    3. emit notifications


    An example MBeanImplAccess for ServiceMBeanSupport is shown below:

        import org.jboss.monitor.alarm.MBeanImplAccess;
        /** alarm manager */
        AlarmManager alm =
          new AlarmManager(
             new MBeanImplAccess() {
                public ObjectName getMBeanName() { return getServiceName(); }
                public long getSequenceNumber() { return getNextNotificationSequenceNumber(); }
                public void emitNotification(Notification n) { sendNotification(n); }


    Producing stateless alarm notifications


    The method of interest that will create and emit a stateless alarm notification,

    with the source, sequenceNumber and timeStamp automatically filled in, is

    the following:

        * Generates and sends an AlarmNotification.
        * source, sequenceNumber, timeStamp
        * will be automatically filled.
       public void sendAlarm(String type, int severity, String message, Object userData)

    severity should correspond to one of the severities defined in

    org.jboss.monitor.alarm.Alarm. For example:

       alm.sendAlarm("", SEVERITY_MAJOR, "unauthorized access detected", extraInfo);

    If you want to include more than a single userData object in the alarm

    notification, you can store a Map instead. There is already a method on

    AlarmManager that will create a HashMap with a single entry:

       public void sendAlarm(String type, int severity, String message, String key, Object value)

    You can also produce alarm notifications on behalf of other mbeans.

    AlarmNotification has a target field that contains the ObjectName

    of the target mbean, in case the notification refers to a different mbean

    from the one that produced it. The ActiveAlarmTable knows how to correctly

    interpret this. AlarmManager provides a similar set of methods that take an

    additional target paramater, i.e.:

       public void sendAlarm(ObjectName target, String type, int severity, String message, Object userData)
       public void sendAlarm(ObjectName target, String type, int severity, String message, String key, Object value)   


    Producing stateful alarm notifications


    The first thing to understand is that stateful alarms are identified

    by notification type (e.g. jboss.alarm.memory.low) and that at any

    given point in time, for every mbean instance there is one logical

    fault state for that alarm: the alarm may be raised, or cleared.


    In the raised state the alarm has a severity described in

    org.jboss.monitor.alarm.Alarm that can vary from WARNING to UNKNOWN.

    In the cleared state the alarm has a NORMAL severity.


    The mbean should produce AlarmNotification notifications to describe

    the state changes of the alarm. The alarm is first CREATED with an

    initial severity, then CHANGED with an altered severity, then CLEARED,

    then CREATED again, and so on.


    AlarmManager helps generating those alarm state change notifications

    by keeping a internal type->severity map. Use setSeverity() to

    set the initial severity for an alarm, without producing any notification.

    If you don't, an initial severity Alarm.SEVERITY_NORMAL will be assumed.

        * Sets the severity of an Alarm, keyed by its type, without producing
        * an AlarmNotification, for the current mbean.
       public void setSeverity(String type, int severity)

    Then just call setAlarm() whenever the severity for that alarm (type)

    changes. You can also provide a String message and the a userData object.

    If the provided severity, is different from the one stored in the internal

    map, for that particular alarm type, then the proper state change

    notification will be emitted. Otherwise, nothing will happen.

        * Sets the alarm for the current mbean, keyed by its type.
        * If severity has changed an AlarmNotification will be thrown.
        * The alarmState of the AlarmNotification will be either
       public void setAlarm(String type, int severity, String message, Object userData)

    It is possible to produce stateful alarms on behalf of other mbeans,

    and there is also a convenience method for including a single key/value

    pair HashMap as userData.


    For an example of using the AlarmManager, look in the MemoryMonitor service:

      if (freeMemory <= criticalThreshold)
             "Free memory in critical state",
             new Long(freeMemory));
       else if (freeMemory <= warningThreshold)
             "Free memory getting low",
             new Long(freeMemory));
             "Free memory at normal levels",
             new Long(freeMemory));







    Referenced by: