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

# Class StringMonitor

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

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

public class StringMonitor extends Monitor implements StringMonitorMBean
Defines a monitor MBean designed to observe the values of a string attribute.

A string monitor sends notifications as follows:

- if the attribute value matches the string to compare value, a `match notification` is sent. The notify match flag must be set to `true`.
  Subsequent matchings of the string to compare values do not cause further notifications unless the attribute value differs from the string to compare value.
- if the attribute value differs from the string to compare value, a `differ notification` is sent. The notify differ flag must be set to `true`.
  Subsequent differences from the string to compare value do not cause further notifications unless the attribute value matches the string to compare value.

Since:
  1.5

- ## Field Summary

  ### Fields declared in class Monitor

  `alreadyNotified, alreadyNotifieds, capacityIncrement, dbgTag, elementCount, OBSERVED_ATTRIBUTE_ERROR_NOTIFIED, OBSERVED_ATTRIBUTE_TYPE_ERROR_NOTIFIED, OBSERVED_OBJECT_ERROR_NOTIFIED, RESET_FLAGS_ALREADY_NOTIFIED, RUNTIME_ERROR_NOTIFIED, server`
  Modifier and Type
  Field
  Description
  `protected int`
  `alreadyNotified`
  Deprecated.
  equivalent to `Monitor.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
  `StringMonitor()`
  Default constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `String`
  `getDerivedGauge()`
  Deprecated.
  As of JMX 1.2, replaced by `getDerivedGauge(ObjectName)`
  `String`
  `getDerivedGauge(ObjectName object)`
  Gets the derived gauge of the specified object, if this object is contained in the set of observed MBeans, or `null` otherwise.
  `long`
  `getDerivedGaugeTimeStamp()`
  Deprecated.
  As of JMX 1.2, replaced by `getDerivedGaugeTimeStamp(ObjectName)`
  `long`
  `getDerivedGaugeTimeStamp(ObjectName object)`
  Gets the derived gauge timestamp of the specified object, if this object is contained in the set of observed MBeans, or `0` otherwise.
  `MBeanNotificationInfo[]`
  `getNotificationInfo()`
  Returns a `NotificationInfo` object containing the name of the Java class of the notification and the notification types sent by the string monitor.
  `boolean`
  `getNotifyDiffer()`
  Gets the differing notification's on/off switch value common to all observed MBeans.
  `boolean`
  `getNotifyMatch()`
  Gets the matching notification's on/off switch value common to all observed MBeans.
  `String`
  `getStringToCompare()`
  Gets the string to compare with the observed attribute common to all observed MBeans.
  `void`
  `setNotifyDiffer(boolean value)`
  Sets the differing notification's on/off switch value common to all observed MBeans.
  `void`
  `setNotifyMatch(boolean value)`
  Sets the matching notification's on/off switch value common to all observed MBeans.
  `void`
  `setStringToCompare(String value)`
  Sets the string to compare with the observed attribute common to all observed MBeans.
  `void`
  `start()`
  Starts the string monitor.
  `void`
  `stop()`
  Stops the string monitor.

  ### Methods declared in class Monitor

  `addObservedObject, containsObservedObject, getGranularityPeriod, getObservedAttribute, getObservedObject, getObservedObjects, isActive, postDeregister, postRegister, preDeregister, preRegister, removeObservedObject, setGranularityPeriod, setObservedAttribute, setObservedObject`
  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 `Monitor.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 `Monitor.addObservedObject(ObjectName)`

  ### Methods declared in class NotificationBroadcasterSupport

  `addNotificationListener, handleNotification, removeNotificationListener, removeNotificationListener, sendNotification`
  Modifier and Type
  Method
  Description
  `void`
  `addNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback)`
  Adds a listener.
  `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.

- ## Constructor Details

  - ### StringMonitor

    public StringMonitor()
    Default constructor.

- ## Method Details

  - ### start

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

  - ### stop

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

  - ### getDerivedGauge

    public String getDerivedGauge(ObjectName object)
    Gets the derived gauge of the specified object, if this object is contained in the set of observed MBeans, or `null` otherwise.
    Specified by:
      `getDerivedGauge` in interface `StringMonitorMBean`
    Parameters:
      `object` - the name of the MBean whose derived gauge is required.
    Returns:
      The derived gauge of the specified object.

  - ### getDerivedGaugeTimeStamp

    public long getDerivedGaugeTimeStamp(ObjectName object)
    Gets the derived gauge timestamp of the specified object, if this object is contained in the set of observed MBeans, or `0` otherwise.
    Specified by:
      `getDerivedGaugeTimeStamp` in interface `StringMonitorMBean`
    Parameters:
      `object` - the name of the object whose derived gauge timestamp is to be returned.
    Returns:
      The derived gauge timestamp of the specified object.

  - ### getDerivedGauge

    @Deprecated public String getDerivedGauge()
    Deprecated.
    As of JMX 1.2, replaced by `getDerivedGauge(ObjectName)`
    Returns the derived gauge of the first object in the set of observed MBeans.
    Specified by:
      `getDerivedGauge` in interface `StringMonitorMBean`
    Returns:
      The derived gauge.

  - ### getDerivedGaugeTimeStamp

    @Deprecated public long getDerivedGaugeTimeStamp()
    Deprecated.
    As of JMX 1.2, replaced by `getDerivedGaugeTimeStamp(ObjectName)`
    Gets the derived gauge timestamp of the first object in the set of observed MBeans.
    Specified by:
      `getDerivedGaugeTimeStamp` in interface `StringMonitorMBean`
    Returns:
      The derived gauge timestamp.

  - ### getStringToCompare

    public String getStringToCompare()
    Gets the string to compare with the observed attribute common to all observed MBeans.
    Specified by:
      `getStringToCompare` in interface `StringMonitorMBean`
    Returns:
      The string value.
    See Also:
      - `setStringToCompare(String)`

  - ### setStringToCompare

    public void setStringToCompare(String value) throws IllegalArgumentException
    Sets the string to compare with the observed attribute common to all observed MBeans.
    Specified by:
      `setStringToCompare` in interface `StringMonitorMBean`
    Parameters:
      `value` - The string value.
    Throws:
      `IllegalArgumentException` - The specified string to compare is null.
    See Also:
      - `getStringToCompare()`

  - ### getNotifyMatch

    public boolean getNotifyMatch()
    Gets the matching notification's on/off switch value common to all observed MBeans.
    Specified by:
      `getNotifyMatch` in interface `StringMonitorMBean`
    Returns:
      `true` if the string monitor notifies when matching the string to compare, `false` otherwise.
    See Also:
      - `setNotifyMatch(boolean)`

  - ### setNotifyMatch

    public void setNotifyMatch(boolean value)
    Sets the matching notification's on/off switch value common to all observed MBeans.
    Specified by:
      `setNotifyMatch` in interface `StringMonitorMBean`
    Parameters:
      `value` - The matching notification's on/off switch value.
    See Also:
      - `getNotifyMatch()`

  - ### getNotifyDiffer

    public boolean getNotifyDiffer()
    Gets the differing notification's on/off switch value common to all observed MBeans.
    Specified by:
      `getNotifyDiffer` in interface `StringMonitorMBean`
    Returns:
      `true` if the string monitor notifies when differing from the string to compare, `false` otherwise.
    See Also:
      - `setNotifyDiffer(boolean)`

  - ### setNotifyDiffer

    public void setNotifyDiffer(boolean value)
    Sets the differing notification's on/off switch value common to all observed MBeans.
    Specified by:
      `setNotifyDiffer` in interface `StringMonitorMBean`
    Parameters:
      `value` - The differing notification's on/off switch value.
    See Also:
      - `getNotifyDiffer()`

  - ### getNotificationInfo

    public MBeanNotificationInfo[] getNotificationInfo()
    Returns a `NotificationInfo` object containing the name of the Java class of the notification and the notification types sent by the string monitor.
    Specified by:
      `getNotificationInfo` in interface `NotificationBroadcaster`
    Returns:
      the array of possible notifications.