39 {@link javax.management.monitor.Monitor#start} caller.</p> |
39 {@link javax.management.monitor.Monitor#start} caller.</p> |
40 |
40 |
41 <p id="complex">The value being monitored can be a simple value |
41 <p id="complex">The value being monitored can be a simple value |
42 contained within a complex type. For example, the {@link |
42 contained within a complex type. For example, the {@link |
43 java.lang.management.MemoryMXBean MemoryMXBean} defined in |
43 java.lang.management.MemoryMXBean MemoryMXBean} defined in |
44 <tt>java.lang.management</tt> has an attribute |
44 {@code java.lang.management} has an attribute |
45 <tt>HeapMemoryUsage</tt> of type {@link |
45 {@code HeapMemoryUsage} of type {@link |
46 java.lang.management.MemoryUsage MemoryUsage}. To monitor the |
46 java.lang.management.MemoryUsage MemoryUsage}. To monitor the |
47 amount of <i>used</i> memory, described by the <tt>used</tt> |
47 amount of <i>used</i> memory, described by the {@code used} |
48 property of <tt>MemoryUsage</tt>, you could monitor |
48 property of {@code MemoryUsage}, you could monitor |
49 "<tt>HeapMemoryUsage.used</tt>". That string would be the |
49 "{@code HeapMemoryUsage.used}". That string would be the |
50 argument to {@link |
50 argument to {@link |
51 javax.management.monitor.MonitorMBean#setObservedAttribute(String) |
51 javax.management.monitor.MonitorMBean#setObservedAttribute(String) |
52 setObservedAttribute}.</p> |
52 setObservedAttribute}.</p> |
53 |
53 |
54 <p>The rules used to interpret an <tt>ObservedAttribute</tt> like |
54 <p>The rules used to interpret an {@code ObservedAttribute} like |
55 <tt>"HeapMemoryUsage.used"</tt> are as follows. Suppose the string is |
55 {@code "HeapMemoryUsage.used"} are as follows. Suppose the string is |
56 <i>A.e</i> (so <i>A</i> would be <tt>"HeapMemoryUsage"</tt> and <i>e</i> |
56 <i>A.e</i> (so <i>A</i> would be {@code "HeapMemoryUsage"} and <i>e</i> |
57 would be <tt>"used"</tt> in the example).</p> |
57 would be {@code "used"} in the example).</p> |
58 |
58 |
59 <p>First the value of the attribute <i>A</i> is obtained. Call it |
59 <p>First the value of the attribute <i>A</i> is obtained. Call it |
60 <i>v</i>. A value <i>x</i> is extracted from <i>v</i> as follows:</p> |
60 <i>v</i>. A value <i>x</i> is extracted from <i>v</i> as follows:</p> |
61 |
61 |
62 <ul> |
62 <ul> |
63 |
63 |
64 <li>If <i>v</i> is a {@link javax.management.openmbean.CompositeData |
64 <li>If <i>v</i> is a {@link javax.management.openmbean.CompositeData |
65 CompositeData} and if <i>v</i>.{@link |
65 CompositeData} and if <i>v</i>.{@link |
66 javax.management.openmbean.CompositeData#get(String) get}(<i>e</i>) |
66 javax.management.openmbean.CompositeData#get(String) get}(<i>e</i>) |
67 returns a value then <i>x</i> is that value.</li> |
67 returns a value then <i>x</i> is that value.</li> |
68 <li>If <i>v</i> is an array and <i>e</i> is the string <tt>"length"</tt> |
68 <li>If <i>v</i> is an array and <i>e</i> is the string {@code "length"} |
69 then <i>x</i> is the length of the array.</li> |
69 then <i>x</i> is the length of the array.</li> |
70 |
70 |
71 <li>If the above rules do not produce a value, and if introspection, as |
71 <li>If the above rules do not produce a value, and if introspection, as |
72 if by calling {@link java.beans.Introspector#getBeanInfo(Class) |
72 if by calling {@link java.beans.Introspector#getBeanInfo(Class) |
73 Introspector.getBeanInfo}, for the class of <i>v</i> |
73 Introspector.getBeanInfo}, for the class of <i>v</i> |
74 (<i>v</i>.<tt>getClass()</tt>) identifies a property with the name |
74 (<i>v</i>.{@code getClass()}) identifies a property with the name |
75 <i>e</i>, then <i>x</i> is the result of reading the property value. </li> |
75 <i>e</i>, then <i>x</i> is the result of reading the property value. </li> |
76 |
76 |
77 </ul> |
77 </ul> |
78 |
78 |
79 <p>The third rule means for example that if the attribute |
79 <p>The third rule means for example that if the attribute |
80 <tt>HeapMemoryUsage</tt> is a <tt>MemoryUsage</tt>, monitoring |
80 {@code HeapMemoryUsage} is a {@code MemoryUsage}, monitoring |
81 <tt>"HeapMemoryUsage.used"</tt> will obtain the observed value by |
81 {@code "HeapMemoryUsage.used"} will obtain the observed value by |
82 calling <tt>MemoryUsage.getUsed()</tt>.</p> |
82 calling {@code MemoryUsage.getUsed()}.</p> |
83 |
83 |
84 <p>If the <tt>ObservedAttribute</tt> contains more than one period, |
84 <p>If the {@code ObservedAttribute} contains more than one period, |
85 for example <tt>"ConnectionPool.connectionStats.length"</tt>, then the |
85 for example {@code "ConnectionPool.connectionStats.length"}, then the |
86 above rules are applied iteratively. Here, <i>v</i> would initially be |
86 above rules are applied iteratively. Here, <i>v</i> would initially be |
87 the value of the attribute <tt>ConnectionPool</tt>, and <i>x</i> would |
87 the value of the attribute {@code ConnectionPool}, and <i>x</i> would |
88 be derived by applying the above rules with <i>e</i> equal to |
88 be derived by applying the above rules with <i>e</i> equal to |
89 <tt>"connectionStats"</tt>. Then <i>v</i> would be set to this <i>x</i> |
89 {@code "connectionStats"}. Then <i>v</i> would be set to this <i>x</i> |
90 and a new <i>x</i> derived by applying the rules again with <i>e</i> |
90 and a new <i>x</i> derived by applying the rules again with <i>e</i> |
91 equal to <tt>"length"</tt>.</p> |
91 equal to {@code "length"}.</p> |
92 |
92 |
93 <p>Although it is recommended that attribute names be valid Java |
93 <p>Although it is recommended that attribute names be valid Java |
94 identifiers, it is possible for an attribute to be called |
94 identifiers, it is possible for an attribute to be called |
95 <tt>HeapMemoryUsage.used</tt>. This means that an |
95 {@code HeapMemoryUsage.used}. This means that an |
96 <tt>ObservedAttribute</tt> that is <tt>HeapMemoryUsage.used</tt> |
96 {@code ObservedAttribute} that is {@code HeapMemoryUsage.used} |
97 could mean that the value to observe is either an attribute of that |
97 could mean that the value to observe is either an attribute of that |
98 name, or the property <tt>used</tt> within an attribute called |
98 name, or the property {@code used} within an attribute called |
99 <tt>HeapMemoryUsage</tt>. So for compatibility reasons, when the |
99 {@code HeapMemoryUsage}. So for compatibility reasons, when the |
100 <tt>ObservedAttribute</tt> contains a period (<tt>.</tt>), the monitor |
100 {@code ObservedAttribute} contains a period ({@code .}), the monitor |
101 will check whether an attribute exists whose name is the full |
101 will check whether an attribute exists whose name is the full |
102 <tt>ObservedAttribute</tt> string (<tt>HeapMemoryUsage.used</tt> in the |
102 {@code ObservedAttribute} string ({@code HeapMemoryUsage.used} in the |
103 example). It does this by calling {@link |
103 example). It does this by calling {@link |
104 javax.management.MBeanServer#getMBeanInfo(javax.management.ObjectName) |
104 javax.management.MBeanServer#getMBeanInfo(javax.management.ObjectName) |
105 getMBeanInfo} for the observed MBean and looking for a contained {@link |
105 getMBeanInfo} for the observed MBean and looking for a contained {@link |
106 javax.management.MBeanAttributeInfo MBeanAttributeInfo} with the given |
106 javax.management.MBeanAttributeInfo MBeanAttributeInfo} with the given |
107 name. If one is found, then that is what is monitored. If more than one |
107 name. If one is found, then that is what is monitored. If more than one |
108 MBean is being observed, the behavior is unspecified if some of them have |
108 MBean is being observed, the behavior is unspecified if some of them have |
109 a <tt>HeapMemoryUsage.used</tt> attribute and others do not. An |
109 a {@code HeapMemoryUsage.used} attribute and others do not. An |
110 implementation may therefore call <tt>getMBeanInfo</tt> on just one of |
110 implementation may therefore call {@code getMBeanInfo} on just one of |
111 the MBeans in this case. The behavior is also unspecified if the result |
111 the MBeans in this case. The behavior is also unspecified if the result |
112 of the check changes while the monitor is active.</p> |
112 of the check changes while the monitor is active.</p> |
113 |
113 |
114 <p>The exact behavior of monitors is detailed in the |
114 <p>The exact behavior of monitors is detailed in the |
115 <a href="#spec">JMX Specification</a>. What follows is a |
115 <a href="#spec">JMX Specification</a>. What follows is a |