/*
 * @(#)Monitor.java	4.42 04/05/18
 *
 * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package javax.management.monitor;

// java imports
//
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Iterator;
import java.util.List;

// jmx imports
//
import javax.management.MBeanServer;
import javax.management.MBeanRegistration;
import javax.management.ObjectName;

import com.sun.jmx.trace.Trace;

/**
 * Defines the common part to all monitor MBeans.
 * A monitor MBean monitors values of an attribute common to a set of observed
 * MBeans. The observed attribute is monitored at intervals specified by the
 * granularity period. A gauge value (derived gauge) is derived from the values
 * of the observed attribute.
 *
 * @version     4.42     05/18/04
 * @author      Sun Microsystems, Inc
 *
 * @since 1.5
 */
public abstract class Monitor
  extends javax.management.NotificationBroadcasterSupport
  implements MonitorMBean, javax.management.MBeanRegistration
{
    /*
     * ------------------------------------------
     *  PRIVATE VARIABLES
     * ------------------------------------------
     */

    /**
     * List of MBeans to which the attribute to observe belongs.
     * <BR>The default value is set to null.
     */
    private List observedObjects = new ArrayList();

    /**
     * Attribute to observe.
     * <BR>The default value is set to null.
     */
    private String observedAttribute = null;

    /**
     * Monitor granularity period (in milliseconds).
     * <BR>The default value is set to 10 seconds.
     */
    private long granularityPeriod = 10000;


    /*
     * ------------------------------------------
     *  PROTECTED VARIABLES
     * ------------------------------------------
     */

    /**
     * The amount by which the capacity of the monitor arrays are
     * automatically incremented when their size becomes greater than
     * their capacity.
     */
    protected final static int capacityIncrement = 16;

    /**
     * The number of valid components in the vector of observed objects.
     *
     * @since.unbundled JMX 1.2
     */
    protected int elementCount = 0;

    /**
     * Monitor errors that have already been notified.
     * @deprecated equivalent to {@link #alreadyNotifieds}[0].
     */
    @Deprecated
    protected int alreadyNotified = 0;

    /**
     * <p>Selected monitor errors that have already been notified.</p>
     *
     * <p>Each element in this array corresponds to an observed object
     * in the vector.  It contains a bit mask of the flags {@link
     * #OBSERVED_OBJECT_ERROR_NOTIFIED} etc, indicating whether the
     * corresponding notification has already been sent for the MBean
     * being monitored.</p>
     *
     * @since.unbundled JMX 1.2
     */
    protected int alreadyNotifieds[] = new int[capacityIncrement];

    /**
     * Reference on the MBean server.  This reference is null when the
     * monitor MBean is not registered in an MBean server.  This
     * reference is initialized before the monitor MBean is registered
     * in the MBean server.
     * @see #preRegister(MBeanServer server, ObjectName name)
     */
    protected MBeanServer server = null;

    // Flags defining possible monitor errors.
    //

    /**
     * This flag is used to reset the {@link #alreadyNotifieds
     * alreadyNotifieds} monitor attribute.
     */
    protected static final int RESET_FLAGS_ALREADY_NOTIFIED             = 0;

    /**
     * Flag denoting that a notification has occurred after changing
     * the observed object.  This flag is used to check that the new
     * observed object is registered in the MBean server at the time
     * of the first notification.
     */
    protected static final int OBSERVED_OBJECT_ERROR_NOTIFIED           = 1;

    /**
     * Flag denoting that a notification has occurred after changing
     * the observed attribute.  This flag is used to check that the
     * new observed attribute belongs to the observed object at the
     * time of the first notification.
     */
    protected static final int OBSERVED_ATTRIBUTE_ERROR_NOTIFIED        = 2;

    /**
     * Flag denoting that a notification has occurred after changing
     * the observed object or the observed attribute.  This flag is
     * used to check that the observed attribute type is correct
     * (depending on the monitor in use) at the time of the first
     * notification.
     */
    protected static final int OBSERVED_ATTRIBUTE_TYPE_ERROR_NOTIFIED   = 4;

    /**
     * Flag denoting that a notification has occurred after changing
     * the observed object or the observed attribute.  This flag is
     * used to notify any exception (except the cases described above)
     * when trying to get the value of the observed attribute at the
     * time of the first notification.
     */
    protected static final int RUNTIME_ERROR_NOTIFIED                   = 8;

    /**
     * This field is retained for compatibility but should not be referenced.
     *
     * @deprecated No replacement.
     */
    @Deprecated
    protected String dbgTag = "Monitor";


    /*
     * ------------------------------------------
     *  PACKAGE VARIABLES
     * ------------------------------------------
     */

    /**
     * Monitor state.
     * The default value is set to <CODE>false</CODE>.
     */
    boolean isActive = false;

    /**
     * Monitor sequence number.
     * The default value is set to 0.
     */
    long sequenceNumber = 0;

    // TRACES & DEBUG
    //---------------

    static boolean isTraceOn() {
        return Trace.isSelected(Trace.LEVEL_TRACE, Trace.INFO_MONITOR);
    }

    static void trace(String clz, String func, String info) {
        Trace.send(Trace.LEVEL_TRACE, Trace.INFO_MONITOR, clz, func, info);
    }

    void trace(String func, String info) {
        trace(dbgTag, func, info);
    }

    static boolean isDebugOn() {
        return Trace.isSelected(Trace.LEVEL_DEBUG, Trace.INFO_MONITOR);
    }

    static void debug(String clz, String func, String info) {
        Trace.send(Trace.LEVEL_DEBUG, Trace.INFO_MONITOR, clz, func, info);
    }

    void debug(String func, String info) {
        debug(dbgTag, func, info);
    }

    /*
     * ------------------------------------------
     *  PUBLIC METHODS
     * ------------------------------------------
     */

    /**
     * Allows the monitor MBean to perform any operations it needs
     * before being registered in the MBean server.
     * <P>
     * Initializes the reference to the MBean server.
     *
     * @param server The MBean server in which the monitor MBean will
     * be registered.
     * @param name The object name of the monitor MBean.
     *
     * @return The name of the monitor MBean registered.
     *
     * @exception java.lang.Exception
     */
    public ObjectName preRegister(MBeanServer server, ObjectName name)
        throws java.lang.Exception {

        if (isTraceOn()) {
            trace("preRegister",
		  "initialize the reference on the MBean server");
        }

        this.server = server;
        return name;
    }

    /**
     * Allows the monitor MBean to perform any operations needed after
     * having been registered in the MBean server or after the
     * registration has failed.
     * <P>
     * Not used in this context.
     */
    public void postRegister (Boolean registrationDone) {
    }

    /**
     * Allows the monitor MBean to perform any operations it needs
     * before being unregistered by the MBean server.
     * <P>
     * Stops the monitor.
     *
     * @exception java.lang.Exception
     */
    public void preDeregister() throws java.lang.Exception {

        if (isTraceOn()) {
            trace("preDeregister", "stop the monitor");
        }

        // Stop the Monitor.
        //
        stop();
    }

    /**
     * Allows the monitor MBean to perform any operations needed after
     * having been unregistered by the MBean server.
     * <P>
     * Not used in this context.
     */
    public void postDeregister() {
    }

    /**
     * Starts the monitor.
     */
    public abstract void start();

    /**
     * Stops the monitor.
     */
    public abstract void stop();

    // GETTERS AND SETTERS
    //--------------------

    /**
     * Returns the object name of the first object in the set of observed
     * MBeans, or <code>null</code> if there is no such object.
     *
     * @return The object being observed.
     *
     * @see #setObservedObject(ObjectName)
     *
     * @deprecated As of JMX 1.2, replaced by {@link #getObservedObjects}
     */
    @Deprecated
    public ObjectName getObservedObject() {
	synchronized(this) {
	    if (observedObjects.isEmpty()) {
		return null;
	    } else {
        return (ObjectName)observedObjects.get(0);
    }
	}
    }

    /**
     * Removes all objects from the set of observed objects, and then adds the
     * specified object.
     *
     * @param object The object to observe.
     * @exception java.lang.IllegalArgumentException The specified
     * object is null.
     *
     * @see #getObservedObject()
     *
     * @deprecated As of JMX 1.2, replaced by {@link #addObservedObject}
     */
    @Deprecated
    public synchronized void setObservedObject(ObjectName object)
	    throws IllegalArgumentException {
	while (!observedObjects.isEmpty()) {
	    removeObservedObject((ObjectName)observedObjects.get(0));
	}

	addObservedObject(object);
    }

    /**
     * Adds the specified object in the set of observed MBeans, if this object
     * is not already present.
     *
     * @param object The object to observe.
     * @exception IllegalArgumentException The specified object is null.
     *
     * @since.unbundled JMX 1.2
     */
    public synchronized void addObservedObject(ObjectName object)
	    throws IllegalArgumentException {

        if (object == null) {
            throw new IllegalArgumentException("Null observed object");
        }

	// Check that the specified object is not already contained
	//
	if (observedObjects.contains(object)) {
	    return;
	}

	// Add the specified object in the list.
	//
	observedObjects.add(object);

	// Update alreadyNotified array.
	//
	int value = RESET_FLAGS_ALREADY_NOTIFIED;
	value &= ~(OBSERVED_OBJECT_ERROR_NOTIFIED |
		   OBSERVED_ATTRIBUTE_ERROR_NOTIFIED |
		   OBSERVED_ATTRIBUTE_TYPE_ERROR_NOTIFIED);
	if (alreadyNotifieds.length >= elementCount)
	    alreadyNotifieds = expandArray(alreadyNotifieds);
	alreadyNotifieds[elementCount] = value;

	updateDeprecatedAlreadyNotified();

	// Update other specific arrays.
	//
	insertSpecificElementAt(elementCount);

	// Update elementCount.
	//
	elementCount++;
    }

    /**
     * Removes the specified object from the set of observed MBeans.
     *
     * @param object The object to remove.
     *
     * @since.unbundled JMX 1.2
     */
    public void removeObservedObject(ObjectName object) {
	synchronized(this) {
            int index = observedObjects.indexOf(object);
	    if (index >= 0) {
		observedObjects.remove(index);

            // Update alreadyNotifieds array.
            //
            removeElementAt(alreadyNotifieds, index);
	    updateDeprecatedAlreadyNotified();

            // Update other specific arrays.
            //
            removeSpecificElementAt(index);

            // Update elementCount.
            //
            elementCount--;
        }
    }
    }

    /**
     * Tests whether the specified object is in the set of observed MBeans.
     *
     * @param object The object to check.
     * @return <CODE>true</CODE> if the specified object is present,
     * <CODE>false</CODE> otherwise.
     *
     * @since.unbundled JMX 1.2
     */
    public boolean containsObservedObject(ObjectName object) {
	synchronized(this) {
        return observedObjects.contains(object);
    }
    }

    /**
     * Returns an array containing the objects being observed.
     *
     * @return The objects being observed.
     *
     * @since.unbundled JMX 1.2
     */
    public ObjectName[] getObservedObjects() {
	ObjectName[] objects;
	synchronized(this) {
	    objects = new ObjectName[elementCount];
	    for (int i=0; i<elementCount; i++) {
          objects[i] = (ObjectName)observedObjects.get(i);
        }
	}
        return objects;
    }

    /**
     * Gets the attribute being observed.
     * <BR>The observed attribute is not initialized by default (set to null).
     *
     * @return The attribute being observed.
     *
     * @see #setObservedAttribute
     */
    public String getObservedAttribute() {
        return observedAttribute;
    }

    /**
     * Sets the attribute to observe.
     * <BR>The observed attribute is not initialized by default (set to null).
     *
     * @param attribute The attribute to observe.
     * @exception java.lang.IllegalArgumentException The specified
     * attribute is null.
     *
     * @see #getObservedAttribute
     */
    public void setObservedAttribute(String attribute)
	    throws IllegalArgumentException {

        if (attribute == null) {
            throw new IllegalArgumentException("Null observed attribute");
        }

        // Update alreadyNotified array.
        //
	synchronized(this) {
	    observedAttribute = attribute;

        for (int i = 0; i < elementCount; i++) {
	    resetAlreadyNotified(i,
				 OBSERVED_ATTRIBUTE_ERROR_NOTIFIED |
				 OBSERVED_ATTRIBUTE_TYPE_ERROR_NOTIFIED);
        }
    }
    }

    /**
     * Gets the granularity period (in milliseconds).
     * <BR>The default value of the granularity period is 10 seconds.
     *
     * @return The granularity period value.
     *
     * @see #setGranularityPeriod
     */
    public synchronized long getGranularityPeriod() {
        return granularityPeriod;
    }

    /**
     * Sets the granularity period (in milliseconds).
     * <BR>The default value of the granularity period is 10 seconds.
     *
     * @param period The granularity period value.
     * @exception java.lang.IllegalArgumentException The granularity
     * period is less than or equal to zero.
     *
     * @see #getGranularityPeriod
     */
    public synchronized void setGranularityPeriod(long period)
	    throws IllegalArgumentException {

        if (period <= 0) {
            throw new IllegalArgumentException("Nonpositive granularity " +
					       "period");
        }
        granularityPeriod = period;
    }

    /**
     * Tests whether the monitor MBean is active.  A monitor MBean is
     * marked active when the {@link #start start} method is called.
     * It becomes inactive when the {@link #stop stop} method is
     * called.
     *
     * @return <CODE>true</CODE> if the monitor MBean is active,
     * <CODE>false</CODE> otherwise.
     */
    /* This method must be synchronized so that the monitoring thread will
       correctly see modifications to the isActive variable.  See the various
       AlarmClock threads in the subclasses.  */
    public synchronized boolean isActive() {
        return isActive;
    }

    /*
     * ------------------------------------------
     *  PACKAGE METHODS
     * ------------------------------------------
     */

    /**
     * Gets the {@link ObjectName} of the object at the specified
     * index in the list of observed MBeans.
     * @return The observed object at the specified index.
     * @exception ArrayIndexOutOfBoundsException If the index is invalid.
     */
    synchronized ObjectName getObservedObject(int index)
	    throws ArrayIndexOutOfBoundsException {
        return (ObjectName)observedObjects.get(index);
    }

    /**
     * Update the deprecated {@link #alreadyNotified} field.
     */
    synchronized void updateDeprecatedAlreadyNotified() {
	if (elementCount > 0)
	    alreadyNotified = alreadyNotifieds[0];
	else
	    alreadyNotified = 0;
    }

    /**
     * Set the given bits in the given element of {@link #alreadyNotifieds}.
     * Ensure the deprecated {@link #alreadyNotified} field is updated
     * if appropriate.
     */
    synchronized void setAlreadyNotified(int index, int mask) {
	alreadyNotifieds[index] |= mask;
	if (index == 0)
	    updateDeprecatedAlreadyNotified();
    }

    /**
     * Reset the given bits in the given element of {@link #alreadyNotifieds}.
     * Ensure the deprecated {@link #alreadyNotified} field is updated
     * if appropriate.
     */
    synchronized void resetAlreadyNotified(int index, int mask) {
	alreadyNotifieds[index] &= ~mask;
	if (index == 0)
	    updateDeprecatedAlreadyNotified();
    }

    synchronized boolean alreadyNotified(int index, int mask) {
	return ((alreadyNotifieds[index] & mask) != 0);
    }

    /**
     * Reset all bits in the given element of {@link #alreadyNotifieds}.
     * Ensure the deprecated {@link #alreadyNotified} field is updated
     * if appropriate.
     */
    synchronized void resetAllAlreadyNotified(int index) {
	alreadyNotifieds[index] = 0;
	if (index == 0)
	    updateDeprecatedAlreadyNotified();
    }

    int[] expandArray(int[] array) {
	int[] newArray = new int[array.length + capacityIncrement];
	System.arraycopy(array, 0, newArray, 0, array.length);
	return newArray;
    }

    long[] expandArray(long[] array) {
	long[] newArray = new long[array.length + capacityIncrement];
	System.arraycopy(array, 0, newArray, 0, array.length);
	return newArray;
    }

    Number[] expandArray(Number[] array) {
	Number[] newArray = new Number[array.length + capacityIncrement];
	System.arraycopy(array, 0, newArray, 0, array.length);
	return newArray;
    }

    boolean[] expandArray(boolean[] array) {
	boolean[] newArray = new boolean[array.length + capacityIncrement];
	System.arraycopy(array, 0, newArray, 0, array.length);
	return newArray;
    }

    String[] expandArray(String[] array) {
	String[] newArray = new String[array.length + capacityIncrement];
	System.arraycopy(array, 0, newArray, 0, array.length);
	return newArray;
    }

    /**
     * Removes the component at the specified index from the specified
     * int array.
     */
    synchronized void removeElementAt(int[] array, int index) {
        if (index < 0 || index >= elementCount)
            return;
        int j = elementCount - index - 1;
        if (j > 0) {
            System.arraycopy(array, index + 1, array, index, j);
        }
    }

    /**
     * Removes the component at the specified index from the specified
     * long array.
     */
    synchronized void removeElementAt(long[] array, int index) {
        if (index < 0 || index >= elementCount)
            return;
        int j = elementCount - index - 1;
        if (j > 0) {
            System.arraycopy(array, index + 1, array, index, j);
        }
    }

    /**
     * Removes the component at the specified index from the specified
     * boolean array.
     */
    synchronized void removeElementAt(boolean[] array, int index) {
        if (index < 0 || index >= elementCount)
            return;
        int j = elementCount - index - 1;
        if (j > 0) {
            System.arraycopy(array, index + 1, array, index, j);
        }
    }

    /**
     * Removes the component at the specified index from the specified
     * Number array.
     */
    synchronized void removeElementAt(Object[] array, int index) {
        if (index < 0 || index >= elementCount)
            return;
        int j = elementCount - index - 1;
        if (j > 0) {
            System.arraycopy(array, index + 1, array, index, j);
        }
	array[elementCount - 1] = null;
    }

    /**
     * Searches for the first occurence of the given argument, testing
     * for equality using the equals method.
     */
    synchronized int indexOf(ObjectName object) {
        return observedObjects.indexOf(object);
    }

    /**
     * This method is overridden by the specific monitor classes
     * (Counter, Gauge and String).  It updates all the specific
     * arrays after adding a new observed object in the list.
     *
     * The method is not abstract so that this class can be subclassed
     * by classes outside this package.
     */
    void insertSpecificElementAt(int index) {}

    /**
     * This method is overridden by the specific monitor classes
     * (Counter, Gauge and String).  It updates all the specific
     * arrays after removing an observed object from the vector.
     *
     * The method is not abstract so that this class can be subclassed
     * by classes outside this package.
     */
    void removeSpecificElementAt(int index) {}

    /**
     * This method is used by the monitor MBean create and send a
     * monitor notification to all the listeners registered for this
     * kind of notification.
     *
     * @param type The notification type.
     * @param timeStamp The notification emission date.
     * @param msg The notification message.
     * @param derGauge The derived gauge.
     * @param trigger The threshold/string (depending on the monitor
     * type) that triggered off the notification.
     * @param index The index of the observed object that triggered
     * off the notification.
     */
    void sendNotification(String type, long timeStamp, String msg,
			  Object derGauge, Object trigger, int index) {

	if (isTraceOn()) {
	    trace("sendNotification", "send notification:" +
		  "\n\tNotification observed object = " +
		  getObservedObject(index) +
		  "\n\tNotification observed attribute = " +
		  observedAttribute +
		  "\n\tNotification derived gauge = " +
		  derGauge);
	}

	long seqno;
	synchronized (this) {
	    seqno = sequenceNumber++;
	}

	sendNotification(new MonitorNotification(type,
						 this,
						 seqno,
						 timeStamp,
						 msg,
						 getObservedObject(index),
						 observedAttribute,
						 derGauge,
						 trigger));
    }
}