ojluni/src/main/java/javax/management/monitor/package.html - platform/libcore - Git at Google

 <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 it
 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
       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>
	<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 it
	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
	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>