javax.management.monitor package

Provides the definition of the monitor classes. A Monitor is an MBean that periodically observes the value of an attribute in one or more other MBeans. If the attribute meets a certain condition, the Monitor emits a {@link javax.management.monitor.MonitorNotification MonitorNotification}. When the monitor MBean periodically calls {@link javax.management.MBeanServer#getAttribute getAttribute} to retrieve the value of the attribute being monitored it does so within the access control context of the {@link javax.management.monitor.Monitor#start} caller.

The value being monitored can be a simple value contained within a complex type. For example, the {@link java.lang.management.MemoryMXBean MemoryMXBean} defined in {@code java.lang.management} has an attribute {@code HeapMemoryUsage} of type {@link java.lang.management.MemoryUsage MemoryUsage}. To monitor the amount of used memory, described by the {@code used} property of {@code MemoryUsage}, you could monitor "{@code HeapMemoryUsage.used}". That string would be the argument to {@link javax.management.monitor.MonitorMBean#setObservedAttribute(String) setObservedAttribute}.

The rules used to interpret an {@code ObservedAttribute} like {@code "HeapMemoryUsage.used"} are as follows. Suppose the string is A.e (so A would be {@code "HeapMemoryUsage"} and e would be {@code "used"} in the example).

First the value of the attribute A is obtained. Call it v. A value x is extracted from v as follows:

- If v is a {@link javax.management.openmbean.CompositeData CompositeData} and if v.{@link javax.management.openmbean.CompositeData#get(String) get}(e) returns a value then x is that value.
- If v is an array and e is the string {@code "length"} then x is the length of the array.
- If the above rules do not produce a value, and if introspection, as if by calling {@link java.beans.Introspector#getBeanInfo(Class) Introspector.getBeanInfo}, for the class of v (v.{@code getClass()}) identifies a property with the name e, then x is the result of reading the property value.

The third rule means for example that if the attribute {@code HeapMemoryUsage} is a {@code MemoryUsage}, monitoring {@code "HeapMemoryUsage.used"} will obtain the observed value by calling {@code MemoryUsage.getUsed()}.

If the {@code ObservedAttribute} contains more than one period, for example {@code "ConnectionPool.connectionStats.length"}, then the above rules are applied iteratively. Here, v would initially be the value of the attribute {@code ConnectionPool}, and x would be derived by applying the above rules with e equal to {@code "connectionStats"}. Then v would be set to this x and a new x derived by applying the rules again with e equal to {@code "length"}.

Although it is recommended that attribute names be valid Java identifiers, it is possible for an attribute to be called {@code HeapMemoryUsage.used}. This means that an {@code ObservedAttribute} that is {@code HeapMemoryUsage.used} could mean that the value to observe is either an attribute of that name, or the property {@code used} within an attribute called {@code HeapMemoryUsage}. So for compatibility reasons, when the {@code ObservedAttribute} contains a period ({@code .}), the monitor will check whether an attribute exists whose name is the full {@code ObservedAttribute} string ({@code HeapMemoryUsage.used} in the example). It does this by calling {@link javax.management.MBeanServer#getMBeanInfo(javax.management.ObjectName) getMBeanInfo} for the observed MBean and looking for a contained {@link javax.management.MBeanAttributeInfo MBeanAttributeInfo} with the given name. If one is found, then that is what is monitored. If more than one MBean is being observed, the behavior is unspecified if some of them have a {@code HeapMemoryUsage.used} attribute and others do not. An implementation may therefore call {@code getMBeanInfo} on just one of the MBeans in this case. The behavior is also unspecified if the result of the check changes while the monitor is active.

The exact behavior of monitors is detailed in the JMX Specification. What follows is a summary.

There are three kinds of Monitors:

- A {@link javax.management.monitor.CounterMonitor CounterMonitor} observes attributes of integer type. The attributes are assumed to be non-negative, and monotonically increasing except for a possible roll-over at a specified modulus. Each observed attribute has an associated threshold value. A notification is sent when the attribute exceeds its threshold.

  An offset value can be specified. When an observed value exceeds its threshold, the threshold is incremented by the offset, or by a multiple of the offset sufficient to make the threshold greater than the new observed value.

  A `CounterMonitor` can operate in difference mode. In this mode, the value compared against the threshold is the difference between two successive observations of an attribute.

- A {@link javax.management.monitor.GaugeMonitor GaugeMonitor} observes attributes of numerical type. Each observed attribute has an associated high threshold and low threshold.

  When an observed attribute crosses the high threshold, if the notify high flag is true, then a notification is sent. Subsequent crossings of the high threshold value will not trigger further notifications until the gauge value becomes less than or equal to the low threshold.

  When an observed attribute crosses the low threshold, if the notify low flag is true, then a notification is sent. Subsequent crossings of the low threshold value will not trigger further notifications until the gauge value becomes greater than or equal to the high threshold.

  Typically, only one of the notify high and notify low flags is set. The other threshold is used to provide a hysteresis mechanism to avoid the repeated triggering of notifications when an attribute makes small oscillations around the threshold value.

  A `GaugeMonitor` can operate in difference mode. In this mode, the value compared against the high and low thresholds is the difference between two successive observations of an attribute.

- A {@link javax.management.monitor.StringMonitor StringMonitor} observes attributes of type `String`. A notification is sent when an observed attribute becomes equal and/or not equal to a given string.

@see JMX Specification, version 1.4 @since 1.5