<html><head><title>javax.management.monitor package</title><!--Copyright (c) 1999, 2011, Oracle and/or its affiliates. All rights reserved.DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. This code is free software; you can redistribute it and/or modify itunder the terms of the GNU General Public License version 2 only, aspublished by the Free Software Foundation.  Oracle designates thisparticular file as subject to the "Classpath" exception as providedby Oracle in the LICENSE file that accompanied this code. This code is distributed in the hope that it will be useful, but WITHOUTANY WARRANTY; without even the implied warranty of MERCHANTABILITY orFITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public Licenseversion 2 for more details (a copy is included in the LICENSE file thataccompanied this code). You should have received a copy of the GNU General Public License version2 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 USAor visit www.oracle.com if you need additional information or have anyquestions.--></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      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.</p>       <p id="complex">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      <tt>java.lang.management</tt> has an attribute      <tt>HeapMemoryUsage</tt> of type {@link      java.lang.management.MemoryUsage MemoryUsage}. To monitor the      amount of <i>used</i> memory, described by the <tt>used</tt>      property of <tt>MemoryUsage</tt>, you could monitor      "<tt>HeapMemoryUsage.used</tt>". That string would be the      argument to {@link      javax.management.monitor.MonitorMBean#setObservedAttribute(String)      setObservedAttribute}.</p>       <p>The rules used to interpret an <tt>ObservedAttribute</tt> like      <tt>"HeapMemoryUsage.used"</tt> are as follows. Suppose the string is      <i>A.e</i> (so <i>A</i> would be <tt>"HeapMemoryUsage"</tt> and <i>e</i>      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>      <li>If <i>v</i> is a {@link javax.management.openmbean.CompositeData      CompositeData} and if <i>v</i>.{@link      javax.management.openmbean.CompositeData#get(String) get}(<i>e</i>)      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      java.beans.Introspector#getBeanInfo(Class) Introspector.getBeanInfo}      for the class of <i>v</i> (<i>v</i>.<tt>getClass()</tt>) contains a      {@link java.beans.PropertyDescriptor PropertyDescriptor} with the name      <i>e</i>, then <i>x</i> is the result of calling the property's {@link      java.beans.PropertyDescriptor#getReadMethod() read method} on      <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      <tt>"HeapMemoryUsage.used"</tt> will obtain the observed value by      calling <tt>MemoryUsage.getUsed()</tt>.</p>       <p>If the <tt>ObservedAttribute</tt> contains more than one period,      for example <tt>"ConnectionPool.connectionStats.length"</tt>, then the      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      <tt>HeapMemoryUsage.used</tt>. This means that an      <tt>ObservedAttribute</tt> that is <tt>HeapMemoryUsage.used</tt>      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      <tt>ObservedAttribute</tt> string (<tt>HeapMemoryUsage.used</tt> 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 <tt>HeapMemoryUsage.used</tt> attribute and others do not. An      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> 	  <p>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	    <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> 	  <p>A {@link javax.management.monitor.GaugeMonitor	    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> 	  <p>A {@link javax.management.monitor.StringMonitor	    StringMonitor} observes attributes of type	    <code>String</code>.  A notification is sent when an	    observed attribute becomes equal and/or not equal to a	    given string.</p> 	</li>      </ul>    <p id="spec">    @see <a href="{@docRoot}/../technotes/guides/jmx/">      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>