<html>
<head>
<!--
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
under the terms of the GNU General Public License version 2 only, as
published by the Free Software Foundation. Oracle designates this
particular file as subject to the "Classpath" exception as provided
by Oracle in the LICENSE file that accompanied this code.
This code is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
version 2 for more details (a copy is included in the LICENSE file that
accompanied this code).
You should have received a copy of the GNU General Public License version
2 along with this work; if not, write to the Free Software Foundation,
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
or visit www.oracle.com if you need additional information or have any
questions.
-->
</head>
<body bgcolor="white">
<p>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
MonitorNotification}. When the monitor MBean periodically calls
to retrieve the value of the attribute being monitored it does
so within the access control context of the
<p id="complex">The value being monitored can be a simple value
contained within a complex type. For example, the {@link
<tt>HeapMemoryUsage</tt> of type {@link
amount of <i>used</i> memory, described by the <tt>used</tt>
property of <tt>MemoryUsage</tt>, you could monitor
argument to {@link
setObservedAttribute}.</p>
<p>The rules used to interpret an <tt>ObservedAttribute</tt> like
would be <tt>"used"</tt> in the example).</p>
<p>First the value of the attribute <i>A</i> is obtained. Call it
<i>v</i>. A value <i>x</i> is extracted from <i>v</i> as follows:</p>
<ul>
CompositeData} and if <i>v</i>.{@link
returns a value then <i>x</i> is that value.</li>
<li>If <i>v</i> is an array and <i>e</i> is the string <tt>"length"</tt>
then <i>x</i> is the length of the array.</li>
<li>If the above rules do not produce a value, and if {@link
for the class of <i>v</i> (<i>v</i>.<tt>getClass()</tt>) contains a
<i>e</i>, then <i>x</i> is the result of calling the property's {@link
<i>v</i>.</li>
</ul>
<p>The third rule means for example that if the attribute
<tt>HeapMemoryUsage</tt> is a <tt>MemoryUsage</tt>, monitoring
<p>If the <tt>ObservedAttribute</tt> contains more than one period,
above rules are applied iteratively. Here, <i>v</i> would initially be
the value of the attribute <tt>ConnectionPool</tt>, and <i>x</i> would
be derived by applying the above rules with <i>e</i> equal to
<tt>"connectionStats"</tt>. Then <i>v</i> would be set to this <i>x</i>
and a new <i>x</i> derived by applying the rules again with <i>e</i>
equal to <tt>"length"</tt>.</p>
<p>Although it is recommended that attribute names be valid Java
identifiers, it is possible for an attribute to be called
could mean that the value to observe is either an attribute of that
name, or the property <tt>used</tt> within an attribute called
<tt>HeapMemoryUsage</tt>. So for compatibility reasons, when the
<tt>ObservedAttribute</tt> contains a period (<tt>.</tt>), the monitor
will check whether an attribute exists whose name is the full
example). It does this by calling {@link
getMBeanInfo} for the observed MBean and looking for a contained {@link
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
implementation may therefore call <tt>getMBeanInfo</tt> 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.</p>
<p>The exact behavior of monitors is detailed in the
<a href="#spec">JMX Specification</a>. What follows is a
summary.</p>
<p>There are three kinds of Monitors:</p>
<ul>
<li>
CounterMonitor} observes attributes of integer
type. The attributes are assumed to be non-negative, and
monotonically increasing except for a possible
<em>roll-over</em> at a specified <em>modulus</em>. Each
observed attribute has an associated <em>threshold</em>
value. A notification is sent when the attribute exceeds
its threshold.</p>
<p>An <em>offset</em> 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.</p>
<p>A <code>CounterMonitor</code> can operate in
<em>difference mode</em>. In this mode, the value
compared against the threshold is the difference between
two successive observations of an attribute.</p>
</li>
<li>
GaugeMonitor} observes attributes of numerical type. Each
observed attribute has an associated <em>high
threshold</em> and <em>low threshold</em>.</p>
<p>When an observed attribute crosses the high threshold, if
the <em>notify high</em> 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.</p>
<p>When an observed attribute crosses the low threshold, if
the <em>notify low</em> 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.</p>
<p>Typically, only one of the notify high and notify low
flags is set. The other threshold is used to provide a
<em>hysteresis</em> mechanism to avoid the repeated
triggering of notifications when an attribute makes small
oscillations around the threshold value.</p>
<p>A <code>GaugeMonitor</code> can operate in <em>difference
mode</em>. In this mode, the value compared against the
high and low thresholds is the difference between two
successive observations of an attribute.</p>
</li>
<li>
StringMonitor} observes attributes of type
<code>String</code>. A notification is sent when an
given string.</p>
</li>
</ul>
<p id="spec">
Java Platform documentation on JMX technology</a>,
in particular the
<a href="{@docRoot}/technotes/guides/jmx/JMX_1_4_specification.pdf">
JMX Specification, version 1.4(pdf).</a>
@since 1.5
</BODY>
</HTML>