Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / libcore / 319a3b994703aac84df7bcde272adfcb3cdbbbf0 / . / jdk / src / share / classes / javax / management / monitor / package.html
blob: 5ccb72c9660831900eb0c66541bf26935981acf7 [file] [log] [blame]
J. Duke319a3b92007-12-01 00:00:00 +0000[diff] [blame^]1<html>
2<head>
3<title>javax.management.monitor package</title>
4<!--
5Copyright 1999-2006 Sun Microsystems, Inc. All Rights Reserved.
6DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
7
8This code is free software; you can redistribute it and/or modify it
9under the terms of the GNU General Public License version 2 only, as
10published by the Free Software Foundation. Sun designates this
11particular file as subject to the "Classpath" exception as provided
12by Sun in the LICENSE file that accompanied this code.
13
14This code is distributed in the hope that it will be useful, but WITHOUT
15ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
16FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
17version 2 for more details (a copy is included in the LICENSE file that
18accompanied this code).
19
20You should have received a copy of the GNU General Public License version
212 along with this work; if not, write to the Free Software Foundation,
22Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
23
24Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
25CA 95054 USA or visit www.sun.com if you need additional information or
26have any questions.
27-->
28</head>
29<body bgcolor="white">
30 <p>Provides the definition of the monitor classes. A Monitor is
31 an MBean that periodically observes the value of an attribute in
32 one or more other MBeans. If the attribute meets a certain
33 condition, the Monitor emits a {@link
34 javax.management.monitor.MonitorNotification
35 MonitorNotification}. When the monitor MBean periodically calls
36 {@link javax.management.MBeanServer#getAttribute getAttribute}
37 to retrieve the value of the attribute being monitored it does
38 so within the access control context of the
39 {@link javax.management.monitor.Monitor#start} caller.</p>
40
41 <p>The value being monitored can be a simple value contained within a
42 complex type. For example, the {@link java.lang.management.MemoryMXBean
43 MemoryMXBean} defined in <tt>java.lang.management</tt> has an attribute
44 <tt>HeapMemoryUsage</tt> of type {@link java.lang.management.MemoryUsage
45 MemoryUsage}. To monitor the amount of <i>used</i> memory, described by
46 the <tt>used</tt> property of <tt>MemoryUsage</tt>, you could monitor
47 "<tt>HeapMemoryUsage.used</tt>". That string would be the argument to
48 {@link javax.management.monitor.MonitorMBean#setObservedAttribute(String)
49 setObservedAttribute}.</p>
50
51 <p>The rules used to interpret an <tt>ObservedAttribute</tt> like
52 <tt>"HeapMemoryUsage.used"</tt> are as follows. Suppose the string is
53 <i>A.e</i> (so <i>A</i> would be <tt>"HeapMemoryUsage"</tt> and <i>e</i>
54 would be <tt>"used"</tt> in the example).</p>
55
56 <p>First the value of the attribute <i>A</i> is obtained. Call it
57 <i>v</i>. A value <i>x</i> is extracted from <i>v</i> as follows:</p>
58
59 <ul>
60 <li>If <i>v</i> is a {@link javax.management.openmbean.CompositeData
61 CompositeData} and if <i>v</i>.{@link
62 javax.management.openmbean.CompositeData#get(String) get}(<i>e</i>)
63 returns a value then <i>x</i> is that value.</li>
64 <li>If <i>v</i> is an array and <i>e</i> is the string <tt>"length"</tt>
65 then <i>x</i> is the length of the array.</li>
66 <li>If the above rules do not produce a value, and if {@link
67 java.beans.Introspector#getBeanInfo(Class) Introspector.getBeanInfo}
68 for the class of <i>v</i> (<i>v</i>.<tt>getClass()</tt>) contains a
69 {@link java.beans.PropertyDescriptor PropertyDescriptor} with the name
70 <i>e</i>, then <i>x</i> is the result of calling the property's {@link
71 java.beans.PropertyDescriptor#getReadMethod() read method} on
72 <i>v</i>.</li>
73 </ul>
74
75 <p>The third rule means for example that if the attribute
76 <tt>HeapMemoryUsage</tt> is a <tt>MemoryUsage</tt>, monitoring
77 <tt>"HeapMemoryUsage.used"</tt> will obtain the observed value by
78 calling <tt>MemoryUsage.getUsed()</tt>.</p>
79
80 <p>If the <tt>ObservedAttribute</tt> contains more than one period,
81 for example <tt>"ConnectionPool.connectionStats.length"</tt>, then the
82 above rules are applied iteratively. Here, <i>v</i> would initially be
83 the value of the attribute <tt>ConnectionPool</tt>, and <i>x</i> would
84 be derived by applying the above rules with <i>e</i> equal to
85 <tt>"connectionStats"</tt>. Then <i>v</i> would be set to this <i>x</i>
86 and a new <i>x</i> derived by applying the rules again with <i>e</i>
87 equal to <tt>"length"</tt>.</p>
88
89 <p>Although it is recommended that attribute names be valid Java
90 identifiers, it is possible for an attribute to be called
91 <tt>HeapMemoryUsage.used</tt>. This means that an
92 <tt>ObservedAttribute</tt> that is <tt>HeapMemoryUsage.used</tt>
93 could mean that the value to observe is either an attribute of that
94 name, or the property <tt>used</tt> within an attribute called
95 <tt>HeapMemoryUsage</tt>. So for compatibility reasons, when the
96 <tt>ObservedAttribute</tt> contains a period (<tt>.</tt>), the monitor
97 will check whether an attribute exists whose name is the full
98 <tt>ObservedAttribute</tt> string (<tt>HeapMemoryUsage.used</tt> in the
99 example). It does this by calling {@link
100 javax.management.MBeanServer#getMBeanInfo(javax.management.ObjectName)
101 getMBeanInfo} for the observed MBean and looking for a contained {@link
102 javax.management.MBeanAttributeInfo MBeanAttributeInfo} with the given
103 name. If one is found, then that is what is monitored. If more than one
104 MBean is being observed, the behavior is unspecified if some of them have
105 a <tt>HeapMemoryUsage.used</tt> attribute and others do not. An
106 implementation may therefore call <tt>getMBeanInfo</tt> on just one of
107 the MBeans in this case. The behavior is also unspecified if the result
108 of the check changes while the monitor is active.</p>
109
110 <p>The exact behavior of monitors is detailed in the
111 <a href="#spec">JMX Specification</a>. What follows is a
112 summary.</p>
113
114 <p>There are three kinds of Monitors:</p>
115
116 <ul>
117 <li>
118
119 <p>A {@link javax.management.monitor.CounterMonitor
120 CounterMonitor} observes attributes of integer
121 type. The attributes are assumed to be non-negative, and
122 monotonically increasing except for a possible
123 <em>roll-over</em> at a specified <em>modulus</em>. Each
124 observed attribute has an associated <em>threshold</em>
125 value. A notification is sent when the attribute exceeds
126 its threshold.</p>
127
128 <p>An <em>offset</em> value can be specified. When an
129 observed value exceeds its threshold, the threshold is
130 incremented by the offset, or by a multiple of the offset
131 sufficient to make the threshold greater than the new
132 observed value.</p>
133
134 <p>A <code>CounterMonitor</code> can operate in
135 <em>difference mode</em>. In this mode, the value
136 compared against the threshold is the difference between
137 two successive observations of an attribute.</p>
138
139 </li>
140 <li>
141
142 <p>A {@link javax.management.monitor.GaugeMonitor
143 GaugeMonitor} observes attributes of numerical type. Each
144 observed attribute has an associated <em>high
145 threshold</em> and <em>low threshold</em>.</p>
146
147 <p>When an observed attribute crosses the high threshold, if
148 the <em>notify high</em> flag is true, then a notification
149 is sent. Subsequent crossings of the high threshold value
150 will not trigger further notifications until the gauge value
151 becomes less than or equal to the low threshold.</p>
152
153 <p>When an observed attribute crosses the low threshold, if
154 the <em>notify low</em> flag is true, then a notification
155 is sent. Subsequent crossings of the low threshold value
156 will not trigger further notifications until the gauge
157 value becomes greater than or equal to the high
158 threshold.</p>
159
160 <p>Typically, only one of the notify high and notify low
161 flags is set. The other threshold is used to provide a
162 <em>hysteresis</em> mechanism to avoid the repeated
163 triggering of notifications when an attribute makes small
164 oscillations around the threshold value.</p>
165
166 <p>A <code>GaugeMonitor</code> can operate in <em>difference
167 mode</em>. In this mode, the value compared against the
168 high and low thresholds is the difference between two
169 successive observations of an attribute.</p>
170
171 </li>
172 <li>
173
174 <p>A {@link javax.management.monitor.StringMonitor
175 StringMonitor} observes attributes of type
176 <code>String</code>. A notification is sent when an
177 observed attribute becomes equal and/or not equal to a
178 given string.</p>
179
180 </li>
181 </ul>
182 <p id="spec">
183 @see <a href="{@docRoot}/../technotes/guides/jmx/">
184 Java SE 6 Platform documentation on JMX technology</a>,
185 in particular the
186 <a href="{@docRoot}/../technotes/guides/jmx/JMX_1_4_specification.pdf">
187 JMX Specification, version 1.4(pdf).</a>
188 @since 1.5
189
190</BODY>
191</HTML>