4230N/ACopyright (c) 1999, 2011, Oracle and/or its affiliates. All rights reserved. 0N/ADO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/AThis code is free software; you can redistribute it and/or modify it 0N/Aunder the terms of the GNU General Public License version 2 only, as 2362N/Apublished by the Free Software Foundation. Oracle designates this 0N/Aparticular file as subject to the "Classpath" exception as provided 2362N/Aby Oracle in the LICENSE file that accompanied this code. 0N/AThis code is distributed in the hope that it will be useful, but WITHOUT 0N/AANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/AFITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/Aversion 2 for more details (a copy is included in the LICENSE file that 0N/Aaccompanied this code). 0N/AYou should have received a copy of the GNU General Public License version 0N/A2 along with this work; if not, write to the Free Software Foundation, 0N/AInc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2365N/APlease contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 0N/A<
body bgcolor="white">
0N/A <
p>Provides the definition of the monitor classes. A Monitor is
0N/A an MBean that periodically observes the value of an attribute in
0N/A one or more other MBeans. If the attribute meets a certain
0N/A condition, the Monitor emits a {@link
0N/A MonitorNotification}. When the monitor MBean periodically calls
0N/A to retrieve the value of the attribute being monitored it does
0N/A so within the access control context of the
406N/A <
p id="complex">The value being monitored can be a simple value
406N/A contained within a complex type. For example, the {@link
406N/A <
tt>HeapMemoryUsage</
tt> of type {@link
406N/A amount of <
i>used</
i> memory, described by the <
tt>used</
tt>
406N/A property of <
tt>MemoryUsage</
tt>, you could monitor
0N/A setObservedAttribute}.</
p>
0N/A <
p>The rules used to interpret an <
tt>ObservedAttribute</
tt> like
0N/A <
i>
A.e</
i> (so <
i>A</
i> would be <
tt>"HeapMemoryUsage"</
tt> and <
i>e</
i>
0N/A would be <
tt>"used"</
tt> in the example).</
p>
0N/A <
p>First the value of the attribute <
i>A</
i> is obtained. Call it
0N/A <
i>v</
i>. A value <
i>x</
i> is extracted from <
i>v</
i> as follows:</
p>
0N/A CompositeData} and if <
i>v</
i>.{@link
0N/A returns a value then <
i>x</
i> is that value.</
li>
0N/A <
li>If <
i>v</
i> is an array and <
i>e</
i> is the string <
tt>"length"</
tt>
0N/A then <
i>x</
i> is the length of the array.</
li>
0N/A <
li>If the above rules do not produce a value, and if {@link
0N/A for the class of <
i>v</
i> (<
i>v</
i>.<
tt>getClass()</
tt>) contains a
0N/A <
i>e</
i>, then <
i>x</
i> is the result of calling the property's {@link
0N/A <
p>The third rule means for example that if the attribute
0N/A <
tt>HeapMemoryUsage</
tt> is a <
tt>MemoryUsage</
tt>, monitoring
0N/A <
p>If the <
tt>ObservedAttribute</
tt> contains more than one period,
0N/A above rules are applied iteratively. Here, <
i>v</
i> would initially be
0N/A the value of the attribute <
tt>ConnectionPool</
tt>, and <
i>x</
i> would
0N/A be derived by applying the above rules with <
i>e</
i> equal to
0N/A <
tt>"connectionStats"</
tt>. Then <
i>v</
i> would be set to this <
i>x</
i>
0N/A and a new <
i>x</
i> derived by applying the rules again with <
i>e</
i>
0N/A equal to <
tt>"length"</
tt>.</
p>
0N/A <
p>Although it is recommended that attribute names be valid Java
0N/A identifiers, it is possible for an attribute to be called
0N/A could mean that the value to observe is either an attribute of that
0N/A name, or the property <
tt>used</
tt> within an attribute called
0N/A <
tt>HeapMemoryUsage</
tt>. So for compatibility reasons, when the
0N/A <
tt>ObservedAttribute</
tt> contains a period (<
tt>.</
tt>), the monitor
0N/A will check whether an attribute exists whose name is the full
0N/A example). It does this by calling {@link
0N/A getMBeanInfo} for the observed MBean and looking for a contained {@link
0N/A name. If one is found, then that is what is monitored. If more than one
0N/A MBean is being observed, the behavior is unspecified if some of them have
0N/A implementation may therefore call <
tt>getMBeanInfo</
tt> on just one of
0N/A the MBeans in this case. The behavior is also unspecified if the result
0N/A of the check changes while the monitor is active.</
p>
0N/A <
p>The exact behavior of monitors is detailed in the
0N/A <
a href="#spec">JMX Specification</
a>. What follows is a
0N/A <
p>There are three kinds of Monitors:</
p>
0N/A CounterMonitor} observes attributes of integer
0N/A type. The attributes are assumed to be non-negative, and
0N/A monotonically increasing except for a possible
0N/A <
em>roll-over</
em> at a specified <
em>modulus</
em>. Each
0N/A observed attribute has an associated <
em>threshold</
em>
0N/A value. A notification is sent when the attribute exceeds
0N/A <
p>An <
em>offset</
em> value can be specified. When an
0N/A observed value exceeds its threshold, the threshold is
0N/A incremented by the offset, or by a multiple of the offset
0N/A sufficient to make the threshold greater than the new
0N/A <
p>A <
code>CounterMonitor</
code> can operate in
0N/A <
em>difference mode</
em>. In this mode, the value
0N/A compared against the threshold is the difference between
0N/A two successive observations of an attribute.</
p>
0N/A GaugeMonitor} observes attributes of numerical type. Each
0N/A observed attribute has an associated <
em>high
0N/A threshold</
em> and <
em>low threshold</
em>.</
p>
0N/A <
p>When an observed attribute crosses the high threshold, if
0N/A the <
em>notify high</
em> flag is true, then a notification
0N/A is sent. Subsequent crossings of the high threshold value
0N/A will not trigger further notifications until the gauge value
0N/A becomes less than or equal to the low threshold.</
p>
0N/A <
p>When an observed attribute crosses the low threshold, if
0N/A the <
em>notify low</
em> flag is true, then a notification
0N/A is sent. Subsequent crossings of the low threshold value
0N/A will not trigger further notifications until the gauge
0N/A value becomes greater than or equal to the high
0N/A <
p>Typically, only one of the notify high and notify low
0N/A flags is set. The other threshold is used to provide a
0N/A <
em>hysteresis</
em> mechanism to avoid the repeated
0N/A triggering of notifications when an attribute makes small
0N/A oscillations around the threshold value.</
p>
0N/A <
p>A <
code>GaugeMonitor</
code> can operate in <
em>difference
0N/A mode</
em>. In this mode, the value compared against the
0N/A high and low thresholds is the difference between two
0N/A successive observations of an attribute.</
p>
0N/A StringMonitor} observes attributes of type
0N/A <
code>String</
code>. A notification is sent when an
0N/A observed attribute becomes equal
and/
or not equal to a
4230N/A Java Platform documentation on JMX technology</
a>,
0N/A JMX Specification, version 1.4(pdf).</
a>