|
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 java.lang.management has an attribute
HeapMemoryUsage of type {@link java.lang.management.MemoryUsage
MemoryUsage}. To monitor the amount of used memory, described by
the used property of MemoryUsage, you could monitor
"HeapMemoryUsage.used". That string would be the argument to
{@link javax.management.monitor.MonitorMBean#setObservedAttribute(String)
setObservedAttribute}.
The rules used to interpret an ObservedAttribute like
"HeapMemoryUsage.used" are as follows. Suppose the string is
A.e (so A would be "HeapMemoryUsage" and e
would be "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 "length"
then x is the length of the array.
- If the above rules do not produce a value, and if {@link
java.beans.Introspector#getBeanInfo(Class) Introspector.getBeanInfo}
for the class of v (v.getClass()) contains a
{@link java.beans.PropertyDescriptor PropertyDescriptor} with the name
e, then x is the result of calling the property's {@link
java.beans.PropertyDescriptor#getReadMethod() read method} on
v.
The third rule means for example that if the attribute
HeapMemoryUsage is a MemoryUsage, monitoring
"HeapMemoryUsage.used" will obtain the observed value by
calling MemoryUsage.getUsed().
If the ObservedAttribute contains more than one period,
for example "ConnectionPool.connectionStats.length", then the
above rules are applied iteratively. Here, v would initially be
the value of the attribute ConnectionPool, and x would
be derived by applying the above rules with e equal to
"connectionStats". Then v would be set to this x
and a new x derived by applying the rules again with e
equal to "length".
Although it is recommended that attribute names be valid Java
identifiers, it is possible for an attribute to be called
HeapMemoryUsage.used. This means that an
ObservedAttribute that is HeapMemoryUsage.used
could mean that the value to observe is either an attribute of that
name, or the property used within an attribute called
HeapMemoryUsage. So for compatibility reasons, when the
ObservedAttribute contains a period (.), the monitor
will check whether an attribute exists whose name is the full
ObservedAttribute string (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 HeapMemoryUsage.used attribute and others do not. An
implementation may therefore call 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
Java SE 6 Platform documentation on JMX technology,
in particular the
JMX Specification, version 1.4(pdf).
@since 1.5
|