Monitor (Java SE 26 & JDK 26)
Description: declaration: module: java.management, package: javax.management.monitor, class: Monitor
Keywords: javax.management.monitor.Monitor class

# Class Monitor

java.lang.Object
javax.management.NotificationBroadcasterSupport
javax.management.monitor.Monitor

All Implemented Interfaces:
  `MBeanRegistration, MonitorMBean, NotificationBroadcaster, NotificationEmitter`

Direct Known Subclasses:
  `CounterMonitor, GaugeMonitor, StringMonitor`

public abstract class Monitor extends NotificationBroadcasterSupport implements MonitorMBean, MBeanRegistration
Defines the part common 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.

Since:
  1.5

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected int`
  `alreadyNotified`
  Deprecated.
  equivalent to `alreadyNotifieds`[0].
  `protected int[]`
  `alreadyNotifieds`
  Selected monitor errors that have already been notified.
  `protected static final int`
  `capacityIncrement`
  The amount by which the capacity of the monitor arrays are automatically incremented when their size becomes greater than their capacity.
  `protected String`
  `dbgTag`
  Deprecated.
  No replacement.
  `protected int`
  `elementCount`
  The number of valid components in the vector of observed objects.
  `protected static final int`
  `OBSERVED_ATTRIBUTE_ERROR_NOTIFIED`
  Flag denoting that a notification has occurred after changing the observed attribute.
  `protected static final int`
  `OBSERVED_ATTRIBUTE_TYPE_ERROR_NOTIFIED`
  Flag denoting that a notification has occurred after changing the observed object or the observed attribute.
  `protected static final int`
  `OBSERVED_OBJECT_ERROR_NOTIFIED`
  Flag denoting that a notification has occurred after changing the observed object.
  `protected static final int`
  `RESET_FLAGS_ALREADY_NOTIFIED`
  This flag is used to reset the `alreadyNotifieds` monitor attribute.
  `protected static final int`
  `RUNTIME_ERROR_NOTIFIED`
  Flag denoting that a notification has occurred after changing the observed object or the observed attribute.
  `protected MBeanServer`
  `server`
  Reference to the MBean server.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Monitor()`
  Constructor for subclasses to call.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addObservedObject(ObjectName object)`
  Adds the specified object in the set of observed MBeans, if this object is not already present.
  `boolean`
  `containsObservedObject(ObjectName object)`
  Tests whether the specified object is in the set of observed MBeans.
  `long`
  `getGranularityPeriod()`
  Gets the granularity period (in milliseconds).
  `String`
  `getObservedAttribute()`
  Gets the attribute being observed.
  `ObjectName`
  `getObservedObject()`
  Deprecated.
  As of JMX 1.2, replaced by `getObservedObjects()`
  `ObjectName[]`
  `getObservedObjects()`
  Returns an array containing the objects being observed.
  `boolean`
  `isActive()`
  Tests whether the monitor MBean is active.
  `void`
  `postDeregister()`
  Allows the monitor MBean to perform any operations needed after having been unregistered by the MBean server.
  `void`
  `postRegister(Boolean registrationDone)`
  Allows the monitor MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.
  `void`
  `preDeregister()`
  Allows the monitor MBean to perform any operations it needs before being unregistered by the MBean server.
  `ObjectName`
  `preRegister(MBeanServer server, ObjectName name)`
  Allows the monitor MBean to perform any operations it needs before being registered in the MBean server.
  `void`
  `removeObservedObject(ObjectName object)`
  Removes the specified object from the set of observed MBeans.
  `void`
  `setGranularityPeriod(long period)`
  Sets the granularity period (in milliseconds).
  `void`
  `setObservedAttribute(String attribute)`
  Sets the attribute to observe.
  `void`
  `setObservedObject(ObjectName object)`
  Deprecated.
  As of JMX 1.2, replaced by `addObservedObject(ObjectName)`
  `abstract void`
  `start()`
  Starts the monitor.
  `abstract void`
  `stop()`
  Stops the monitor.

  ### Methods declared in class NotificationBroadcasterSupport

  `addNotificationListener, getNotificationInfo, handleNotification, removeNotificationListener, removeNotificationListener, sendNotification`
  Modifier and Type
  Method
  Description
  `void`
  `addNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback)`
  Adds a listener.
  `MBeanNotificationInfo[]`
  `getNotificationInfo()`
  Returns an array indicating, for each notification this MBean may send, the name of the Java class of the notification and the notification type.
  `protected void`
  `handleNotification(NotificationListener listener, Notification notif, Object handback)`
  This method is called by `sendNotification` for each listener in order to send the notification to that listener.
  `void`
  `removeNotificationListener(NotificationListener listener)`
  Removes a listener from this MBean.
  `void`
  `removeNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback)`
  Removes a listener from this MBean.
  `void`
  `sendNotification(Notification notification)`
  Sends a notification.

  ### Methods declared in class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`
  Modifier and Type
  Method
  Description
  `protected Object`
  `clone()`
  Creates and returns a copy of this object.
  `boolean`
  `equals(Object obj)`
  Indicates whether some other object is "equal to" this one.
  `protected void`
  `finalize()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Finalization is deprecated and subject to removal in a future release.
  `final Class<?>`
  `getClass()`
  Returns the runtime class of this `Object`.
  `int`
  `hashCode()`
  Returns a hash code value for this object.
  `final void`
  `notify()`
  Wakes up a single thread that is waiting on this object's monitor.
  `final void`
  `notifyAll()`
  Wakes up all threads that are waiting on this object's monitor.
  `String`
  `toString()`
  Returns a string representation of the object.
  `final void`
  `wait()`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
  `final void`
  `wait(long timeoutMillis)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
  `final void`
  `wait(long timeoutMillis, int nanos)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

- ## Field Details

  - ### capacityIncrement

    protected static final int capacityIncrement
    The amount by which the capacity of the monitor arrays are automatically incremented when their size becomes greater than their capacity.
    See Also:
      - Constant Field Values

  - ### elementCount

    protected int elementCount
    The number of valid components in the vector of observed objects.

  - ### alreadyNotified

    @Deprecated protected int alreadyNotified
    Deprecated.
    equivalent to `alreadyNotifieds`[0].
    Monitor errors that have already been notified.

  - ### alreadyNotifieds

    protected int[] alreadyNotifieds

    Selected monitor errors that have already been notified.

    Each element in this array corresponds to an observed object in the vector. It contains a bit mask of the flags `OBSERVED_OBJECT_ERROR_NOTIFIED` etc, indicating whether the corresponding notification has already been sent for the MBean being monitored.

  - ### server

    protected MBeanServer server
    Reference to 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 Also:
      - `preRegister(MBeanServer server, ObjectName name)`

  - ### RESET_FLAGS_ALREADY_NOTIFIED

    protected static final int RESET_FLAGS_ALREADY_NOTIFIED
    This flag is used to reset the `alreadyNotifieds` monitor attribute.
    See Also:
      - Constant Field Values

  - ### OBSERVED_OBJECT_ERROR_NOTIFIED

    protected static final int OBSERVED_OBJECT_ERROR_NOTIFIED
    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.
    See Also:
      - Constant Field Values

  - ### OBSERVED_ATTRIBUTE_ERROR_NOTIFIED

    protected static final int OBSERVED_ATTRIBUTE_ERROR_NOTIFIED
    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.
    See Also:
      - Constant Field Values

  - ### OBSERVED_ATTRIBUTE_TYPE_ERROR_NOTIFIED

    protected static final int OBSERVED_ATTRIBUTE_TYPE_ERROR_NOTIFIED
    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.
    See Also:
      - Constant Field Values

  - ### RUNTIME_ERROR_NOTIFIED

    protected static final int RUNTIME_ERROR_NOTIFIED
    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.
    See Also:
      - Constant Field Values

  - ### dbgTag

    @Deprecated protected String dbgTag
    Deprecated.
    No replacement.
    This field is retained for compatibility but should not be referenced.

- ## Constructor Details

  - ### Monitor

    public Monitor()
    Constructor for subclasses to call.

- ## Method Details

  - ### preRegister

    public ObjectName preRegister(MBeanServer server, ObjectName name) throws Exception
    Allows the monitor MBean to perform any operations it needs before being registered in the MBean server.

    Initializes the reference to the MBean server.

    Specified by:
      `preRegister` in interface `MBeanRegistration`
    Parameters:
      `server` - The MBean server in which the monitor MBean will be registered.
      `name` - The object name of the monitor MBean.
    Returns:
      The name of the monitor MBean registered.
    Throws:
      `Exception` - if something goes wrong

  - ### postRegister

    public void postRegister(Boolean registrationDone)
    Allows the monitor MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.

    Not used in this context.

    Specified by:
      `postRegister` in interface `MBeanRegistration`
    Parameters:
      `registrationDone` - Indicates whether or not the MBean has been successfully registered in the MBean server. The value false means that the registration phase has failed.

  - ### preDeregister

    public void preDeregister() throws Exception
    Allows the monitor MBean to perform any operations it needs before being unregistered by the MBean server.

    Stops the monitor.

    Specified by:
      `preDeregister` in interface `MBeanRegistration`
    Throws:
      `Exception` - if something goes wrong

  - ### postDeregister

    public void postDeregister()
    Allows the monitor MBean to perform any operations needed after having been unregistered by the MBean server.

    Not used in this context.

    Specified by:
      `postDeregister` in interface `MBeanRegistration`

  - ### start

    public abstract void start()
    Starts the monitor.
    Specified by:
      `start` in interface `MonitorMBean`

  - ### stop

    public abstract void stop()
    Stops the monitor.
    Specified by:
      `stop` in interface `MonitorMBean`

  - ### getObservedObject

    @Deprecated public ObjectName getObservedObject()
    Deprecated.
    As of JMX 1.2, replaced by `getObservedObjects()`
    Returns the object name of the first object in the set of observed MBeans, or `null` if there is no such object.
    Specified by:
      `getObservedObject` in interface `MonitorMBean`
    Returns:
      The object being observed.
    See Also:
      - `setObservedObject(ObjectName)`

  - ### setObservedObject

    @Deprecated public void setObservedObject(ObjectName object) throws IllegalArgumentException
    Deprecated.
    As of JMX 1.2, replaced by `addObservedObject(ObjectName)`
    Removes all objects from the set of observed objects, and then adds the specified object.
    Specified by:
      `setObservedObject` in interface `MonitorMBean`
    Parameters:
      `object` - The object to observe.
    Throws:
      `IllegalArgumentException` - The specified object is null.
    See Also:
      - `getObservedObject()`

  - ### addObservedObject

    public void addObservedObject(ObjectName object) throws IllegalArgumentException
    Adds the specified object in the set of observed MBeans, if this object is not already present.
    Specified by:
      `addObservedObject` in interface `MonitorMBean`
    Parameters:
      `object` - The object to observe.
    Throws:
      `IllegalArgumentException` - The specified object is null.

  - ### removeObservedObject

    public void removeObservedObject(ObjectName object)
    Removes the specified object from the set of observed MBeans.
    Specified by:
      `removeObservedObject` in interface `MonitorMBean`
    Parameters:
      `object` - The object to remove.

  - ### containsObservedObject

    public boolean containsObservedObject(ObjectName object)
    Tests whether the specified object is in the set of observed MBeans.
    Specified by:
      `containsObservedObject` in interface `MonitorMBean`
    Parameters:
      `object` - The object to check.
    Returns:
      `true` if the specified object is present, `false` otherwise.

  - ### getObservedObjects

    public ObjectName[] getObservedObjects()
    Returns an array containing the objects being observed.
    Specified by:
      `getObservedObjects` in interface `MonitorMBean`
    Returns:
      The objects being observed.

  - ### getObservedAttribute

    public String getObservedAttribute()
    Gets the attribute being observed.
    The observed attribute is not initialized by default (set to null).
    Specified by:
      `getObservedAttribute` in interface `MonitorMBean`
    Returns:
      The attribute being observed.
    See Also:
      - `setObservedAttribute(String)`

  - ### setObservedAttribute

    public void setObservedAttribute(String attribute) throws IllegalArgumentException
    Sets the attribute to observe.
    The observed attribute is not initialized by default (set to null).
    Specified by:
      `setObservedAttribute` in interface `MonitorMBean`
    Parameters:
      `attribute` - The attribute to observe.
    Throws:
      `IllegalArgumentException` - The specified attribute is null.
    See Also:
      - `getObservedAttribute()`

  - ### getGranularityPeriod

    public long getGranularityPeriod()
    Gets the granularity period (in milliseconds).
    The default value of the granularity period is 10 seconds.
    Specified by:
      `getGranularityPeriod` in interface `MonitorMBean`
    Returns:
      The granularity period value.
    See Also:
      - `setGranularityPeriod(long)`

  - ### setGranularityPeriod

    public void setGranularityPeriod(long period) throws IllegalArgumentException
    Sets the granularity period (in milliseconds).
    The default value of the granularity period is 10 seconds.
    Specified by:
      `setGranularityPeriod` in interface `MonitorMBean`
    Parameters:
      `period` - The granularity period value.
    Throws:
      `IllegalArgumentException` - The granularity period is less than or equal to zero.
    See Also:
      - `getGranularityPeriod()`

  - ### isActive

    public boolean isActive()
    Tests whether the monitor MBean is active. A monitor MBean is marked active when the `start` method is called. It becomes inactive when the `stop` method is called.
    Specified by:
      `isActive` in interface `MonitorMBean`
    Returns:
      `true` if the monitor MBean is active, `false` otherwise.