FileDocCategorySizeDatePackage
GaugeStatisticMonitor.javaAPI DocGlassfish v2 API29959Fri May 04 22:33:44 BST 2007com.sun.enterprise.admin.selfmanagement.event

GaugeStatisticMonitor

public class GaugeStatisticMonitor extends StatisticMonitor implements GaugeStatisticMonitorMBean
Defines a monitor MBean designed to observe the values of a gauge attribute. Used for JDK version greater than 1.5.

A gauge statistic monitor observes an attribute that is continuously variable with time. A gauge statistic monitor sends notifications as follows:

  • if the attribute value is increasing and becomes equal to or greater than the high threshold value, a {@link StatisticMonitorNotification#THRESHOLD_HIGH_VALUE_EXCEEDED threshold high notification} is sent. The notify high flag must be set to true.
    Subsequent crossings of the high threshold value do not cause further notifications unless the attribute value becomes equal to or less than the low threshold value.
  • if the attribute value is decreasing and becomes equal to or less than the low threshold value, a {@link StatisticMonitorNotification#THRESHOLD_LOW_VALUE_EXCEEDED threshold low notification} is sent. The notify low flag must be set to true.
    Subsequent crossings of the low threshold value do not cause further notifications unless the attribute value becomes equal to or greater than the high threshold value.
This provides a hysteresis mechanism to avoid repeated triggering of notifications when the attribute value makes small oscillations around the high or low threshold value.

If the gauge difference mode is used, the value of the derived gauge is calculated as the difference between the observed gauge values for two successive observations.
The derived gauge value (V[t]) is calculated using the following method:

  • V[t] = gauge[t] - gauge[t-GP]
This implementation of the gauge statistic monitor requires the observed attribute to be of the type integer or floating-point (Byte, Integer, Short, Long, Float, Double).
author
Sun Microsystems, Inc

Fields Summary
private Number
highThreshold
Gauge high threshold.
The default value is a null Integer object.
private Number
lowThreshold
Gauge low threshold.
The default value is a null Integer object.
private boolean
notifyHigh
Flag indicating if the gauge statistic monitor notifies when exceeding the high threshold.
The default value is false.
private boolean
notifyLow
Flag indicating if the gauge statistic monitor notifies when exceeding the low threshold.
The default value is false.
private boolean
differenceMode
Flag indicating if the gauge difference mode is used. If the gauge difference mode is used, the derived gauge is the difference between two consecutive observed values. Otherwise, the derived gauge is directly the value of the observed attribute.
The default value is set to false.
private Number[]
previousScanGauge
Scan gauge values captured by the previous observation.
Each element in this array corresponds to an observed object in the list.
private int[]
status
This attribute is used to handle the hysteresis mechanism.
Each element in this array corresponds to an observed object in the list.
private NumericalType[]
type
This attribute is used to keep the derived gauge type.
Each element in this array corresponds to an observed object in the list.
private boolean[]
derivedGaugeValid
Derived gauge valid.
Each element in this array corresponds to an observed object in the list.
private static final String[]
types
private static final MBeanNotificationInfo[]
notifsInfo
private static final int
RISING
private static final int
FALLING
private static final int
RISING_OR_FALLING
protected static final Logger
_logger
Constructors Summary
public GaugeStatisticMonitor()
Default constructor.



    /*
     * ------------------------------------------
     *  CONSTRUCTORS
     * ------------------------------------------
     */

           
      
    
Methods Summary
com.sun.appserv.management.event.StatisticMonitorNotificationbuildAlarmNotification(javax.management.ObjectName object, java.lang.String attribute, java.lang.Comparable value)

        int index = indexOf(object);
        
        // Notify the listeners if the updated derived
        // gauge value is valid.
        //
        StatisticMonitorNotification alarm = null;
        if (derivedGaugeValid[index])
            alarm = updateNotifications(index);
        return alarm;
    
public synchronized java.lang.NumbergetDerivedGauge(javax.management.ObjectName object)
Gets the derived gauge of the specified object, if this object is contained in the set of observed MBeans, or null otherwise.

param
object the name of the MBean.
return
The derived gauge of the specified object.
since.unbundled
JMX 1.2

        return (Number) super.getDerivedGauge(object);
    
public synchronized java.lang.NumbergetDerivedGauge()
Returns the derived gauge of the first object in the set of observed MBeans.

return
The derived gauge.
deprecated
As of JMX 1.2, replaced by {@link #getDerivedGauge(ObjectName)}

        return (Number) derivedGauge[0];
    
java.lang.ComparablegetDerivedGaugeFromComparable(javax.management.ObjectName object, java.lang.String attribute, java.lang.Comparable value)

        int index = indexOf(object);

        // Update the derived gauge attributes and check the
        // validity of the new value. The derived gauge value
        // is invalid when the differenceMode flag is set to
        // true and it is the first notification, i.e. we
        // haven't got 2 consecutive values to update the
        // derived gauge.
        //
        derivedGaugeValid[index] = updateDerivedGauge(value, index);

        return (Comparable<?>) derivedGauge[index];
    
public synchronized longgetDerivedGaugeTimeStamp(javax.management.ObjectName object)
Gets the derived gauge timestamp of the specified object, if this object is contained in the set of observed MBeans, or null otherwise.

param
object the name of the object whose derived gauge timestamp is to be returned.
return
The derived gauge timestamp of the specified object.
since.unbundled
JMX 1.2

        return super.getDerivedGaugeTimeStamp(object);
    
public synchronized longgetDerivedGaugeTimeStamp()
Gets the derived gauge timestamp of the first object in the set of observed MBeans.

return
The derived gauge timestamp.
deprecated
As of JMX 1.2, replaced by {@link #getDerivedGaugeTimeStamp(ObjectName)}

        return derivedGaugeTimestamp[0];
    
public synchronized booleangetDifferenceMode()
Gets the difference mode flag value common to all observed MBeans.

return
true if the difference mode is used, false otherwise.
see
#setDifferenceMode

        return differenceMode;
    
public synchronized java.lang.NumbergetHighThreshold()
Gets the high threshold value common to all observed MBeans.

return
The high threshold value.
see
#setThresholds

        return highThreshold;
    
public synchronized java.lang.NumbergetLowThreshold()
Gets the low threshold value common to all observed MBeans.

return
The low threshold value.
see
#setThresholds

        return lowThreshold;
    
public javax.management.MBeanNotificationInfo[]getNotificationInfo()
Returns a NotificationInfo object containing the name of the Java class of the notification and the notification types sent by the gauge monitor.

        return notifsInfo.clone();
    
public synchronized booleangetNotifyHigh()
Gets the high notification's on/off switch value common to all observed MBeans.

return
true if the gauge monitor notifies when exceeding the high threshold, false otherwise.
see
#setNotifyHigh

        return notifyHigh;
    
public synchronized booleangetNotifyLow()
Gets the low notification's on/off switch value common to all observed MBeans.

return
true if the gauge monitor notifies when exceeding the low threshold, false otherwise.
see
#setNotifyLow

        return notifyLow;
    
synchronized voidinsertSpecificElementAt(int index)
This method is called when adding a new observed object in the vector. It updates all the gauge specific arrays.

param
index The index of the observed object.

        // Update previousScanGauge, status, type and derivedGaugeValid arrays.
        //
        if (elementCount >= previousScanGauge.length) {
            previousScanGauge = expandArray(previousScanGauge);
            status = expandArray(status);
            type = expandArray(type);
            derivedGaugeValid = expandArray(derivedGaugeValid);
        }
        previousScanGauge[index] = null;
        status[index] = RISING_OR_FALLING;
        type[index] = INTEGER;
        derivedGaugeValid[index] = false;
    
booleanisComparableTypeValid(javax.management.ObjectName object, java.lang.String attribute, java.lang.Comparable value)
This method globally sets the derived gauge type for the given "object" and "attribute" after checking that the type of the supplied observed attribute value is one of the value types supported by this monitor.

        int index = indexOf(object);

        // Check that the observed attribute is either of type
        // "Integer" or "Float".
        //
        if (value instanceof Integer) {
            type[index] = INTEGER;
        } else if (value instanceof Byte) {
            type[index] = BYTE;
        } else if (value instanceof Short) {
            type[index] = SHORT;
        } else if (value instanceof Long) {
            type[index] = LONG;
        } else if (value instanceof Float) {
            type[index] = FLOAT;
        } else if (value instanceof Double) {
            type[index] = DOUBLE;
        } else {
            return false;
        }
        return true;
    
private booleanisFirstGreaterThanLast(java.lang.Number greater, java.lang.Number less, NumericalType type)
Tests if the first specified Number is greater than or equal to the last. Both integer and floating-point types are allowed.

param
greater The first Number to compare with the second.
param
less The second Number to compare with the first.
param
type The number type.
return
true if the first specified Number is greater than or equal to the last, false otherwise.


        switch(type) {
        case INTEGER:
        case BYTE:
        case SHORT:
        case LONG:
            return (greater.longValue() >= less.longValue());
        case FLOAT:
        case DOUBLE:
            return (greater.doubleValue() >= less.doubleValue());
        default:
            // Should never occur...
            if ( _logger.isLoggable(Level.WARNING) )
                _logger.log(Level.WARNING,"The threshold type is invalid");
            return false;
        }
    
private booleanisFirstStrictlyGreaterThanLast(java.lang.Number greater, java.lang.Number less, java.lang.String className)
Tests if the first specified Number is strictly greater than the last. Both integer and floating-point types are allowed.

param
greater The first Number to compare with the second.
param
less The second Number to compare with the first.
param
className The number class name.
return
true if the first specified Number is strictly greater than the last, false otherwise.


        if (className.equals("java.lang.Integer") ||
            className.equals("java.lang.Byte") ||
            className.equals("java.lang.Short") ||
            className.equals("java.lang.Long")) {

            return (greater.longValue() > less.longValue());
        }
        else if (className.equals("java.lang.Float") ||
                 className.equals("java.lang.Double")) {

            return (greater.doubleValue() > less.doubleValue());
        }
        else {
            // Should never occur...
            if ( _logger.isLoggable(Level.WARNING) )
                _logger.log(Level.WARNING,"The threshold type is invalid");
            return false;
        }
    
synchronized booleanisThresholdTypeValid(javax.management.ObjectName object, java.lang.String attribute, java.lang.Comparable value)
Tests if the threshold high and threshold low are both of the same type as the gauge. Both integer and floating-point types are allowed. Note: If the optional lowThreshold or highThreshold have not been initialized, their default value is an Integer object with a value equal to zero.

param
object The observed object.
param
attribute The observed attribute.
param
value The sample value.
return
true if type is the same, false otherwise.

        int index = indexOf(object);
        Class<? extends Number> c = classForType(type[index]);
        return (isValidForType(highThreshold, c) &&
                isValidForType(lowThreshold, c));
    
voidonErrorNotification(com.sun.appserv.management.event.StatisticMonitorNotification notification)

        int index = indexOf(notification.getObservedObject());
        synchronized(this) {
            // Reset values.
            //
            status[index] = RISING_OR_FALLING;
            previousScanGauge[index] = null;
        }
    
synchronized voidremoveSpecificElementAt(int index)
This method is called when removing an observed object from the vector. It updates all the gauge specific arrays.

param
index The index of the observed object.

        // Update previousScanGauge, status, type and derivedGaugeValid arrays.
        //
        removeElementAt(previousScanGauge, index);
        removeElementAt(status, index);
        removeElementAt(type, index);
        removeElementAt(derivedGaugeValid, index);
    
private synchronized voidsetDerivedGaugeWithDifference(java.lang.Number scanGauge, int index)
Sets the derived gauge when the differenceMode flag is set to true. Both integer and floating-point types are allowed.

param
scanGauge The value of the observed attribute.
param
index The index of the observed object.

        Number prev = previousScanGauge[index];
        Number der;
        switch (type[index]) {
        case INTEGER:
            der = new Integer(((Integer)scanGauge).intValue() -
                              ((Integer)prev).intValue());
            break;
        case BYTE:
            der = new Byte((byte)(((Byte)scanGauge).byteValue() -
                                  ((Byte)prev).byteValue()));
            break;
        case SHORT:
            der = new Short((short)(((Short)scanGauge).shortValue() -
                                    ((Short)prev).shortValue()));
            break;
        case LONG:
            der = new Long(((Long)scanGauge).longValue() -
                           ((Long)prev).longValue());
            break;
        case FLOAT:
            der = new Float(((Float)scanGauge).floatValue() -
                            ((Float)prev).floatValue());
            break;
        case DOUBLE:
            der = new Double(((Double)scanGauge).doubleValue() -
                             ((Double)prev).doubleValue());
            break;
        default:
            // Should never occur...
            if ( _logger.isLoggable(Level.WARNING) )
                _logger.log(Level.WARNING,"The threshold type is invalid");
            return;
        }
        derivedGauge[index] = der;
    
public synchronized voidsetDifferenceMode(boolean value)
Sets the difference mode flag value common to all observed MBeans.

param
value The difference mode flag value.
see
#getDifferenceMode

        differenceMode = value;

        // Reset values.
        //
        for (int i = 0; i < elementCount; i++) {
            status[i] = RISING_OR_FALLING;
            previousScanGauge[i] = null;
        }
    
public synchronized voidsetNotifyHigh(boolean value)
Sets the high notification's on/off switch value common to all observed MBeans.

param
value The high notification's on/off switch value.
see
#getNotifyHigh

        notifyHigh = value;
    
public synchronized voidsetNotifyLow(boolean value)
Sets the low notification's on/off switch value common to all observed MBeans.

param
value The low notification's on/off switch value.
see
#getNotifyLow

        notifyLow = value;
    
public synchronized voidsetThresholds(java.lang.Number highValue, java.lang.Number lowValue)
Sets the high and the low threshold values common to all observed MBeans.

param
highValue The high threshold value.
param
lowValue The low threshold value.
exception
IllegalArgumentException The specified high/low threshold is null or the low threshold is greater than the high threshold or the high threshold and the low threshold are not of the same type.
see
#getHighThreshold
see
#getLowThreshold


        if ((highValue == null) || (lowValue == null)) {
            throw new IllegalArgumentException("Null threshold value");
        }

        if (highValue.getClass() != lowValue.getClass()) {
            throw new IllegalArgumentException("Different type " +
                                               "threshold values");
        }

        if (isFirstStrictlyGreaterThanLast(lowValue, highValue,
                                           highValue.getClass().getName())) {
            throw new IllegalArgumentException("High threshold less than " +
                                               "low threshold");
        }

        highThreshold = highValue;
        lowThreshold = lowValue;

        for (int i = 0; i < elementCount; i++) {
            resetAlreadyNotified(i, THRESHOLD_ERROR_NOTIFIED);

            // Reset values.
            //
            status[i] = RISING_OR_FALLING;
        }
    
public synchronized voidstart()
Starts the gauge statistic monitor.

        // Reset values.
        //
        for (int i = 0; i < elementCount; i++) {
            status[i] = RISING_OR_FALLING;
            previousScanGauge[i] = null;
        }
        doStart();
    
public synchronized voidstop()
Stops the gauge statistic monitor.

        doStop();
    
private synchronized booleanupdateDerivedGauge(java.lang.Object scanGauge, int index)
Updates the derived gauge attribute of the observed object at the specified index.

param
scanGauge The value of the observed attribute.
param
index The index of the observed object.
return
true if the derived gauge value is valid, false otherwise. The derived gauge value is invalid when the differenceMode flag is set to true and it is the first notification (so we haven't 2 consecutive values to update the derived gauge).


        boolean is_derived_gauge_valid;

        // The gauge difference mode is used.
        //
        if (differenceMode) {

            // The previous scan gauge has been initialized.
            //
            if (previousScanGauge[index] != null) {
                setDerivedGaugeWithDifference((Number)scanGauge, index);
                is_derived_gauge_valid = true;
            }
            // The previous scan gauge has not been initialized.
            // We cannot update the derived gauge...
            //
            else {
                is_derived_gauge_valid = false;
            }
            previousScanGauge[index] = (Number)scanGauge;
        }
        // The gauge difference mode is not used.
        //
        else {
            derivedGauge[index] = (Number)scanGauge;
            is_derived_gauge_valid = true;
        }

        return is_derived_gauge_valid;
    
private com.sun.appserv.management.event.StatisticMonitorNotificationupdateNotifications(int index)
Updates the notification attribute of the observed object at the specified index and notifies the listeners only once if the notify flag is set to true.

param
index The index of the observed object.


        StatisticMonitorNotification n = null;

        // Send high notification if notifyHigh is true.
        // Send low notification if notifyLow is true.
        //
        synchronized(this) {
            if (status[index] == RISING_OR_FALLING) {
                if (isFirstGreaterThanLast((Number)derivedGauge[index],
                                           highThreshold,
                                           type[index])) {
                    if (notifyHigh) {
                        n = new StatisticMonitorNotification(
                                THRESHOLD_HIGH_VALUE_EXCEEDED,
                                this,
                                0,
                                0,
                                "",
                                null,
                                null,
                                null,
                                highThreshold);
                    }
                    status[index] = FALLING;
                } else if (isFirstGreaterThanLast(lowThreshold,
                                                  (Number)derivedGauge[index],
                                                  type[index])) {
                    if (notifyLow) {
                        n = new StatisticMonitorNotification(
                                THRESHOLD_LOW_VALUE_EXCEEDED,
                                this,
                                0,
                                0,
                                "",
                                null,
                                null,
                                null,
                                lowThreshold);
                    }
                    status[index] = RISING;
                }
            } else {
                if (status[index] == RISING) {
                    if (isFirstGreaterThanLast((Number)derivedGauge[index],
                                               highThreshold,
                                               type[index])) {
                        if (notifyHigh) {
                            n = new StatisticMonitorNotification(
                                    THRESHOLD_HIGH_VALUE_EXCEEDED,
                                    this,
                                    0,
                                    0,
                                    "",
                                    null,
                                    null,
                                    null,
                                    highThreshold);
                        }
                        status[index] = FALLING;
                    }
                } else if (status[index] == FALLING) {
                    if (isFirstGreaterThanLast(lowThreshold,
                                               (Number)derivedGauge[index],
                                               type[index])) {
                        if (notifyLow) {
                            n = new StatisticMonitorNotification(
                                    THRESHOLD_LOW_VALUE_EXCEEDED,
                                    this,
                                    0,
                                    0,
                                    "",
                                    null,
                                    null,
                                    null,
                                    lowThreshold);
                        }
                        status[index] = RISING;
                    }
                }
            }
        }    

        return n;