< prev index next >

src/java.management/share/classes/javax/management/MXBean.java

Print this page


   1 /*
   2  * Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any


  62     public interface WhatsitMXBean {}
  63 
  64     @MXBean
  65     public interface Whatsit1Interface {}
  66 
  67     @MXBean(true)
  68     public interface Whatsit2Interface {}
  69     </pre>
  70 
  71     <p>The following interfaces are not MXBean interfaces:</p>
  72 
  73     <pre>
  74     interface NonPublicInterfaceNotMXBean{}
  75 
  76     public interface Whatsit3Interface{}
  77 
  78     @MXBean(false)
  79     public interface MisleadingMXBean {}
  80     </pre>
  81 
  82     <h2 id="MXBean-spec">MXBean specification</h2>
  83 
  84     <p>The MXBean concept provides a simple way to code an MBean
  85       that only references a predefined set of types, the ones defined
  86       by {@link javax.management.openmbean}.  In this way, you can be
  87       sure that your MBean will be usable by any client, including
  88       remote clients, without any requirement that the client have
  89       access to <em>model-specific classes</em> representing the types
  90       of your MBeans.</p>
  91 
  92     <p>The concepts are easier to understand by comparison with the
  93       Standard MBean concept.  Here is how a managed object might be
  94       represented as a Standard MBean, and as an MXBean:</p>
  95 
  96     <div style="display:inline-block; margin: 0 3em">
  97         <h3>Standard MBean</h3>
  98         <pre>
  99 public interface MemoryPool<b>MBean</b> {
 100     String getName();
 101     MemoryUsage getUsage();
 102     // ...
 103 }
 104           </pre>
 105     </div>
 106     <div style="display:inline-block; margin: 0 3em">
 107         <h3>MXBean</h3>
 108         <pre>
 109 public interface MemoryPool<b>MXBean</b> {
 110     String getName();
 111     MemoryUsage getUsage();
 112     // ...
 113 }
 114           </pre>
 115     </div>
 116 
 117     <p>As you can see, the definitions are very similar.  The only
 118       difference is that the convention for naming the interface is to use
 119       <code><em>Something</em>MXBean</code> for MXBeans, rather than
 120       <code><em>Something</em>MBean</code> for Standard MBeans.</p>
 121 
 122     <p>In this managed object, there is an attribute called
 123       <code>Usage</code> of type {@link MemoryUsage}.  The point of an
 124       attribute like this is that it gives a coherent snapshot of a set
 125       of data items.  For example, it might include the current amount
 126       of used memory in the memory pool, and the current maximum of the
 127       memory pool.  If these were separate items, obtained with separate
 128       {@link MBeanServer#getAttribute getAttribute} calls, then we could
 129       get values seen at different times that were not consistent.  We
 130       might get a <code>used</code> value that was greater than the
 131       <code>max</code> value.</p>
 132 
 133     <p>So, we might define <code>MemoryUsage</code> like this:</p>
 134 
 135     <div style="display:inline-block; margin: 0 3em">
 136         <h3>Standard MBean</h3>
 137         <pre>
 138 public class MemoryUsage <b>implements Serializable</b> {
 139     // standard JavaBean conventions with getters
 140 
 141     public MemoryUsage(long init, long used,
 142                        long committed, long max) {...}
 143     long getInit() {...}
 144     long getUsed() {...}
 145     long getCommitted() {...}
 146     long getMax() {...}
 147 }
 148         </pre>
 149     </div>
 150     <div style="display:inline-block; margin: 0 3em">
 151         <h3>MXBean</h3>
 152         <pre>
 153 public class MemoryUsage {
 154     // standard JavaBean conventions with getters
 155     <b>@ConstructorParameters({"init", "used", "committed", "max"})</b>
 156     public MemoryUsage(long init, long used,
 157                        long committed, long max) {...}
 158     long getInit() {...}
 159     long getUsed() {...}
 160     long getCommitted() {...}
 161     long getMax() {...}
 162 }
 163         </pre>
 164     </div>
 165 
 166     <p>The definitions are the same in the two cases, except
 167       that with the MXBean, <code>MemoryUsage</code> no longer needs to
 168       be marked <code>Serializable</code> (though it can be).  On
 169       the other hand, we have added a {@link ConstructorParameters @ConstructorParameters}
 170       annotation to link the constructor parameters to the corresponding getters.
 171       We will see more about this below.</p>


 177       based on JMX technology.  Then the console would have to be
 178       configured with the model-specific classes of every application it
 179       might connect to.  The problem is even worse for clients that are
 180       not written in the Java language.  Then there may not be any way
 181       to tell the client what a <code>MemoryUsage</code> looks like.</p>
 182 
 183     <p>This is where MXBeans differ from Standard MBeans.  Although we
 184       define the management interface in almost exactly the same way,
 185       the MXBean framework <em>converts</em> model-specific classes into
 186       standard classes from the Java platform.  Using arrays and the
 187       {@link javax.management.openmbean.CompositeData CompositeData} and
 188       {@link javax.management.openmbean.TabularData TabularData} classes
 189       from the standard {@link javax.management.openmbean} package, it
 190       is possible to build data structures of arbitrary complexity
 191       using only standard classes.</p>
 192 
 193     <p>This becomes clearer if we compare what the clients of the two
 194       models might look like:</p>
 195 
 196     <div style="display:inline-block; margin: 0 3em">
 197         <h3>Standard MBean</h3>
 198         <pre>
 199 String name = (String)
 200     mbeanServer.{@link MBeanServer#getAttribute
 201     getAttribute}(objectName, "Name");
 202 <b>MemoryUsage</b> usage = (<b>MemoryUsage</b>)
 203     mbeanServer.getAttribute(objectName, "Usage");
 204 <b>long used = usage.getUsed();</b>
 205         </pre>
 206     </div>
 207     <div style="display:inline-block; margin: 0 3em">
 208         <h3>MXBean</h3>
 209         <pre>
 210 String name = (String)
 211     mbeanServer.{@link MBeanServer#getAttribute
 212     getAttribute}(objectName, "Name");
 213 <b>{@link CompositeData}</b> usage = (<b>CompositeData</b>)
 214     mbeanServer.getAttribute(objectName, "Usage");
 215 <b>long used = (Long) usage.{@link CompositeData#get get}("used");</b>
 216         </pre>
 217     </div>
 218 
 219     <p>For attributes with simple types like <code>String</code>, the
 220       code is the same.  But for attributes with complex types, the
 221       Standard MBean code requires the client to know the model-specific
 222       class <code>MemoryUsage</code>, while the MXBean code requires no
 223       non-standard classes.</p>
 224 
 225     <p>The client code shown here is slightly more complicated for the
 226       MXBean client.  But, if the client does in fact know the model,
 227       here the interface <code>MemoryPoolMXBean</code> and the
 228       class <code>MemoryUsage</code>, then it can construct a
 229       <em>proxy</em>.  This is the recommended way to interact with
 230       managed objects when you know the model beforehand, regardless
 231       of whether you are using Standard MBeans or MXBeans:</p>
 232 
 233     <div style="display:inline-block; margin: 0 3em">
 234         <h3>Standard MBean</h3>
 235         <pre>
 236 MemoryPool<b>MBean</b> proxy =
 237     JMX.<b>{@link JMX#newMBeanProxy(MBeanServerConnection, ObjectName,
 238               Class) newMBeanProxy}</b>(
 239         mbeanServer,
 240         objectName,
 241         MemoryPool<b>MBean</b>.class);
 242 String name = proxy.getName();
 243 MemoryUsage usage = proxy.getUsage();
 244 long used = usage.getUsed();
 245           </pre>
 246     </div>
 247     <div style="display:inline-block; margin: 0 3em">
 248         <h3>MXBean</h3>
 249         <pre>
 250 MemoryPool<b>MXBean</b> proxy =
 251     JMX.<b>{@link JMX#newMXBeanProxy(MBeanServerConnection, ObjectName,
 252               Class) newMXBeanProxy}</b>(
 253         mbeanServer,
 254         objectName,
 255         MemoryPool<b>MXBean</b>.class);
 256 String name = proxy.getName();
 257 MemoryUsage usage = proxy.getUsage();
 258 long used = usage.getUsed();
 259           </pre>
 260     </div>
 261 
 262     <p>Implementing the MemoryPool object works similarly for both
 263       Standard MBeans and MXBeans.</p>
 264 
 265     <div style="display:inline-block; margin: 0 3em">
 266         <h3>Standard MBean</h3>
 267         <pre>
 268 public class MemoryPool
 269         implements MemoryPool<b>MBean</b> {
 270     public String getName() {...}
 271     public MemoryUsage getUsage() {...}
 272     // ...
 273 }
 274         </pre>
 275     </div>
 276     <div style="display:inline-block; margin: 0 3em">
 277         <h3>MXBean</h3>
 278         <pre>
 279 public class MemoryPool
 280         implements MemoryPool<b>MXBean</b> {
 281     public String getName() {...}
 282     public MemoryUsage getUsage() {...}
 283     // ...
 284 }
 285         </pre>
 286     </div>
 287 
 288     <p>Registering the MBean in the MBean Server works in the same way
 289       in both cases:</p>
 290 
 291     <div style="display:inline-block; margin: 0 3em">
 292         <h3>Standard MBean</h3>
 293         <pre>
 294 {
 295     MemoryPool<b>MBean</b> pool = new MemoryPool();
 296     mbeanServer.{@link MBeanServer#registerMBean
 297     registerMBean}(pool, objectName);
 298 }
 299         </pre>
 300     </div>
 301     <div style="display:inline-block; margin: 0 3em">
 302         <h3>MXBean</h3>
 303         <pre>
 304 {
 305     MemoryPool<b>MXBean</b> pool = new MemoryPool();
 306     mbeanServer.{@link MBeanServer#registerMBean
 307     registerMBean}(pool, objectName);
 308 }
 309         </pre>
 310     </div>
 311 
 312 
 313     <h2 id="mxbean-def">Definition of an MXBean</h2>
 314 
 315     <p>An MXBean is a kind of MBean.  An MXBean object can be
 316       registered directly in the MBean Server, or it can be used as an
 317       argument to {@link StandardMBean} and the resultant MBean
 318       registered in the MBean Server.</p>
 319 
 320     <p>When an object is registered in the MBean Server using the
 321       {@code registerMBean} or {@code createMBean} methods of the
 322       {@link MBeanServer} interface, the object's class is examined


   1 /*
   2  * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any


  62     public interface WhatsitMXBean {}
  63 
  64     @MXBean
  65     public interface Whatsit1Interface {}
  66 
  67     @MXBean(true)
  68     public interface Whatsit2Interface {}
  69     </pre>
  70 
  71     <p>The following interfaces are not MXBean interfaces:</p>
  72 
  73     <pre>
  74     interface NonPublicInterfaceNotMXBean{}
  75 
  76     public interface Whatsit3Interface{}
  77 
  78     @MXBean(false)
  79     public interface MisleadingMXBean {}
  80     </pre>
  81 
  82     <h3 id="MXBean-spec">MXBean specification</h3>
  83 
  84     <p>The MXBean concept provides a simple way to code an MBean
  85       that only references a predefined set of types, the ones defined
  86       by {@link javax.management.openmbean}.  In this way, you can be
  87       sure that your MBean will be usable by any client, including
  88       remote clients, without any requirement that the client have
  89       access to <em>model-specific classes</em> representing the types
  90       of your MBeans.</p>
  91 
  92     <p>The concepts are easier to understand by comparison with the
  93       Standard MBean concept.  Here is how a managed object might be
  94       represented as a Standard MBean, and as an MXBean:</p>
  95 
  96     <div style="display:inline-block; margin: 0 3em">
  97         <h4>Standard MBean</h4>
  98         <pre>
  99 public interface MemoryPool<b>MBean</b> {
 100     String getName();
 101     MemoryUsage getUsage();
 102     // ...
 103 }
 104           </pre>
 105     </div>
 106     <div style="display:inline-block; margin: 0 3em">
 107         <h4>MXBean</h4>
 108         <pre>
 109 public interface MemoryPool<b>MXBean</b> {
 110     String getName();
 111     MemoryUsage getUsage();
 112     // ...
 113 }
 114           </pre>
 115     </div>
 116 
 117     <p>As you can see, the definitions are very similar.  The only
 118       difference is that the convention for naming the interface is to use
 119       <code><em>Something</em>MXBean</code> for MXBeans, rather than
 120       <code><em>Something</em>MBean</code> for Standard MBeans.</p>
 121 
 122     <p>In this managed object, there is an attribute called
 123       <code>Usage</code> of type {@link MemoryUsage}.  The point of an
 124       attribute like this is that it gives a coherent snapshot of a set
 125       of data items.  For example, it might include the current amount
 126       of used memory in the memory pool, and the current maximum of the
 127       memory pool.  If these were separate items, obtained with separate
 128       {@link MBeanServer#getAttribute getAttribute} calls, then we could
 129       get values seen at different times that were not consistent.  We
 130       might get a <code>used</code> value that was greater than the
 131       <code>max</code> value.</p>
 132 
 133     <p>So, we might define <code>MemoryUsage</code> like this:</p>
 134 
 135     <div style="display:inline-block; margin: 0 3em">
 136         <h4>Standard MBean</h4>
 137         <pre>
 138 public class MemoryUsage <b>implements Serializable</b> {
 139     // standard JavaBean conventions with getters
 140 
 141     public MemoryUsage(long init, long used,
 142                        long committed, long max) {...}
 143     long getInit() {...}
 144     long getUsed() {...}
 145     long getCommitted() {...}
 146     long getMax() {...}
 147 }
 148         </pre>
 149     </div>
 150     <div style="display:inline-block; margin: 0 3em">
 151         <h4>MXBean</h4>
 152         <pre>
 153 public class MemoryUsage {
 154     // standard JavaBean conventions with getters
 155     <b>@ConstructorParameters({"init", "used", "committed", "max"})</b>
 156     public MemoryUsage(long init, long used,
 157                        long committed, long max) {...}
 158     long getInit() {...}
 159     long getUsed() {...}
 160     long getCommitted() {...}
 161     long getMax() {...}
 162 }
 163         </pre>
 164     </div>
 165 
 166     <p>The definitions are the same in the two cases, except
 167       that with the MXBean, <code>MemoryUsage</code> no longer needs to
 168       be marked <code>Serializable</code> (though it can be).  On
 169       the other hand, we have added a {@link ConstructorParameters @ConstructorParameters}
 170       annotation to link the constructor parameters to the corresponding getters.
 171       We will see more about this below.</p>


 177       based on JMX technology.  Then the console would have to be
 178       configured with the model-specific classes of every application it
 179       might connect to.  The problem is even worse for clients that are
 180       not written in the Java language.  Then there may not be any way
 181       to tell the client what a <code>MemoryUsage</code> looks like.</p>
 182 
 183     <p>This is where MXBeans differ from Standard MBeans.  Although we
 184       define the management interface in almost exactly the same way,
 185       the MXBean framework <em>converts</em> model-specific classes into
 186       standard classes from the Java platform.  Using arrays and the
 187       {@link javax.management.openmbean.CompositeData CompositeData} and
 188       {@link javax.management.openmbean.TabularData TabularData} classes
 189       from the standard {@link javax.management.openmbean} package, it
 190       is possible to build data structures of arbitrary complexity
 191       using only standard classes.</p>
 192 
 193     <p>This becomes clearer if we compare what the clients of the two
 194       models might look like:</p>
 195 
 196     <div style="display:inline-block; margin: 0 3em">
 197         <h4>Standard MBean</h4>
 198         <pre>
 199 String name = (String)
 200     mbeanServer.{@link MBeanServer#getAttribute
 201     getAttribute}(objectName, "Name");
 202 <b>MemoryUsage</b> usage = (<b>MemoryUsage</b>)
 203     mbeanServer.getAttribute(objectName, "Usage");
 204 <b>long used = usage.getUsed();</b>
 205         </pre>
 206     </div>
 207     <div style="display:inline-block; margin: 0 3em">
 208         <h4>MXBean</h4>
 209         <pre>
 210 String name = (String)
 211     mbeanServer.{@link MBeanServer#getAttribute
 212     getAttribute}(objectName, "Name");
 213 <b>{@link CompositeData}</b> usage = (<b>CompositeData</b>)
 214     mbeanServer.getAttribute(objectName, "Usage");
 215 <b>long used = (Long) usage.{@link CompositeData#get get}("used");</b>
 216         </pre>
 217     </div>
 218 
 219     <p>For attributes with simple types like <code>String</code>, the
 220       code is the same.  But for attributes with complex types, the
 221       Standard MBean code requires the client to know the model-specific
 222       class <code>MemoryUsage</code>, while the MXBean code requires no
 223       non-standard classes.</p>
 224 
 225     <p>The client code shown here is slightly more complicated for the
 226       MXBean client.  But, if the client does in fact know the model,
 227       here the interface <code>MemoryPoolMXBean</code> and the
 228       class <code>MemoryUsage</code>, then it can construct a
 229       <em>proxy</em>.  This is the recommended way to interact with
 230       managed objects when you know the model beforehand, regardless
 231       of whether you are using Standard MBeans or MXBeans:</p>
 232 
 233     <div style="display:inline-block; margin: 0 3em">
 234         <h4>Standard MBean</h4>
 235         <pre>
 236 MemoryPool<b>MBean</b> proxy =
 237     JMX.<b>{@link JMX#newMBeanProxy(MBeanServerConnection, ObjectName,
 238               Class) newMBeanProxy}</b>(
 239         mbeanServer,
 240         objectName,
 241         MemoryPool<b>MBean</b>.class);
 242 String name = proxy.getName();
 243 MemoryUsage usage = proxy.getUsage();
 244 long used = usage.getUsed();
 245           </pre>
 246     </div>
 247     <div style="display:inline-block; margin: 0 3em">
 248         <h4>MXBean</h4>
 249         <pre>
 250 MemoryPool<b>MXBean</b> proxy =
 251     JMX.<b>{@link JMX#newMXBeanProxy(MBeanServerConnection, ObjectName,
 252               Class) newMXBeanProxy}</b>(
 253         mbeanServer,
 254         objectName,
 255         MemoryPool<b>MXBean</b>.class);
 256 String name = proxy.getName();
 257 MemoryUsage usage = proxy.getUsage();
 258 long used = usage.getUsed();
 259           </pre>
 260     </div>
 261 
 262     <p>Implementing the MemoryPool object works similarly for both
 263       Standard MBeans and MXBeans.</p>
 264 
 265     <div style="display:inline-block; margin: 0 3em">
 266         <h4>Standard MBean</h4>
 267         <pre>
 268 public class MemoryPool
 269         implements MemoryPool<b>MBean</b> {
 270     public String getName() {...}
 271     public MemoryUsage getUsage() {...}
 272     // ...
 273 }
 274         </pre>
 275     </div>
 276     <div style="display:inline-block; margin: 0 3em">
 277         <h4>MXBean</h4>
 278         <pre>
 279 public class MemoryPool
 280         implements MemoryPool<b>MXBean</b> {
 281     public String getName() {...}
 282     public MemoryUsage getUsage() {...}
 283     // ...
 284 }
 285         </pre>
 286     </div>
 287 
 288     <p>Registering the MBean in the MBean Server works in the same way
 289       in both cases:</p>
 290 
 291     <div style="display:inline-block; margin: 0 3em">
 292         <h4>Standard MBean</h4>
 293         <pre>
 294 {
 295     MemoryPool<b>MBean</b> pool = new MemoryPool();
 296     mbeanServer.{@link MBeanServer#registerMBean
 297     registerMBean}(pool, objectName);
 298 }
 299         </pre>
 300     </div>
 301     <div style="display:inline-block; margin: 0 3em">
 302         <h4>MXBean</h4>
 303         <pre>
 304 {
 305     MemoryPool<b>MXBean</b> pool = new MemoryPool();
 306     mbeanServer.{@link MBeanServer#registerMBean
 307     registerMBean}(pool, objectName);
 308 }
 309         </pre>
 310     </div>
 311 
 312 
 313     <h2 id="mxbean-def">Definition of an MXBean</h2>
 314 
 315     <p>An MXBean is a kind of MBean.  An MXBean object can be
 316       registered directly in the MBean Server, or it can be used as an
 317       argument to {@link StandardMBean} and the resultant MBean
 318       registered in the MBean Server.</p>
 319 
 320     <p>When an object is registered in the MBean Server using the
 321       {@code registerMBean} or {@code createMBean} methods of the
 322       {@link MBeanServer} interface, the object's class is examined


< prev index next >