Please note that this documentation is not final and is subject to change.

javax.management
Class JMX

java.lang.Object
  javax.management.JMX

public class JMX
extends Object

Static methods from the JMX API. There are no instances of this class.

Since:

1.6

Nested Class Summary

Modifier and Type	Class and Description
static class	JMX.MBeanOptions Options to apply to an MBean proxy or to an instance of StandardMBean.
static class	JMX.ProxyOptions Options to apply to an MBean proxy.

Field Summary

Modifier and Type	Field and Description
static String	DEFAULT_VALUE_FIELD The name of the defaultValue field.
static String	DESCRIPTION_RESOURCE_BUNDLE_BASE_NAME_FIELD The name of the descriptionResourceBundleBaseName field.
static String	DESCRIPTION_RESOURCE_KEY_FIELD The name of the descriptionResourceKey field.
static String	EXCEPTIONS_FIELD The name of the exceptions field.
static String	IMMUTABLE_INFO_FIELD The name of the immutableInfo field.
static String	INTERFACE_CLASS_NAME_FIELD The name of the interfaceClassName field.
static String	LEGAL_VALUES_FIELD The name of the legalValues field.
static String	LOCALE_FIELD The name of the locale field.
static String	MAX_VALUE_FIELD The name of the maxValue field.
static String	MIN_VALUE_FIELD The name of the minValue field.
static String	MXBEAN_FIELD The name of the mxbean field.
static String	MXBEAN_MAPPING_FACTORY_CLASS_FIELD The name of the mxbeanMappingFactoryClass field.
static String	OBJECT_NAME_TEMPLATE The name of the objectNameTemplate field.
static String	OPEN_TYPE_FIELD The name of the openType field.
static String	ORIGINAL_TYPE_FIELD The name of the originalType field.
static String	SET_EXCEPTIONS_FIELD The name of the setExceptions field.

Method Summary

Modifier and Type	Method and Description
static String	getSpecificationVersion(MBeanServerConnection mbsc, ObjectName mbeanName) Return the version of the JMX specification that a (possibly remote) MBean Server is using.
static boolean	isMXBeanInterface(Class<?> interfaceClass) Test whether an interface is an MXBean interface.
static boolean	isNotificationSource(Object mbean) Test if an MBean can emit notifications.
static <T> T	newMBeanProxy(MBeanServerConnection connection, ObjectName objectName, Class<T> interfaceClass) Make a proxy for a Standard MBean in a local or remote MBean Server.
static <T> T	newMBeanProxy(MBeanServerConnection connection, ObjectName objectName, Class<T> interfaceClass, boolean notificationEmitter) Make a proxy for a Standard MBean in a local or remote MBean Server that may also support the methods of NotificationEmitter.
static <T> T	newMBeanProxy(MBeanServerConnection connection, ObjectName objectName, Class<T> interfaceClass, JMX.MBeanOptions opts) Make a proxy for a Standard MBean or MXBean in a local or remote MBean Server that may also support the methods of NotificationEmitter and (for an MXBean) that may define custom MXBean type mappings.
static <T> T	newMXBeanProxy(MBeanServerConnection connection, ObjectName objectName, Class<T> interfaceClass) Make a proxy for an MXBean in a local or remote MBean Server.
static <T> T	newMXBeanProxy(MBeanServerConnection connection, ObjectName objectName, Class<T> interfaceClass, boolean notificationEmitter) Make a proxy for an MXBean in a local or remote MBean Server that may also support the methods of NotificationEmitter.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_VALUE_FIELD

public static final String DEFAULT_VALUE_FIELD

The name of the defaultValue field.

See Also:

Constant Field Values

DESCRIPTION_RESOURCE_BUNDLE_BASE_NAME_FIELD

public static final String DESCRIPTION_RESOURCE_BUNDLE_BASE_NAME_FIELD

The name of the descriptionResourceBundleBaseName field.

See Also:

Constant Field Values

DESCRIPTION_RESOURCE_KEY_FIELD

public static final String DESCRIPTION_RESOURCE_KEY_FIELD

The name of the descriptionResourceKey field.

See Also:

Constant Field Values

EXCEPTIONS_FIELD

public static final String EXCEPTIONS_FIELD

The name of the exceptions field.

See Also:

Constant Field Values

IMMUTABLE_INFO_FIELD

public static final String IMMUTABLE_INFO_FIELD

The name of the immutableInfo field.

See Also:

Constant Field Values

INTERFACE_CLASS_NAME_FIELD

public static final String INTERFACE_CLASS_NAME_FIELD

The name of the interfaceClassName field.

See Also:

Constant Field Values

LEGAL_VALUES_FIELD

public static final String LEGAL_VALUES_FIELD

The name of the legalValues field.

See Also:

Constant Field Values

LOCALE_FIELD

public static final String LOCALE_FIELD

The name of the locale field.

See Also:

Constant Field Values

MAX_VALUE_FIELD

public static final String MAX_VALUE_FIELD

The name of the maxValue field.

See Also:

Constant Field Values

MIN_VALUE_FIELD

public static final String MIN_VALUE_FIELD

The name of the minValue field.

See Also:

Constant Field Values

MXBEAN_FIELD

public static final String MXBEAN_FIELD

The name of the mxbean field.

See Also:

Constant Field Values

MXBEAN_MAPPING_FACTORY_CLASS_FIELD

public static final String MXBEAN_MAPPING_FACTORY_CLASS_FIELD

The name of the mxbeanMappingFactoryClass field.

See Also:

Constant Field Values

OPEN_TYPE_FIELD

public static final String OPEN_TYPE_FIELD

The name of the openType field.

See Also:

Constant Field Values

ORIGINAL_TYPE_FIELD

public static final String ORIGINAL_TYPE_FIELD

The name of the originalType field.

See Also:

Constant Field Values

SET_EXCEPTIONS_FIELD

public static final String SET_EXCEPTIONS_FIELD

The name of the setExceptions field.

See Also:

Constant Field Values

OBJECT_NAME_TEMPLATE

public static final String OBJECT_NAME_TEMPLATE

The name of the objectNameTemplate field.

See Also:

Constant Field Values

Method Detail

newMBeanProxy

public static <T> T newMBeanProxy(MBeanServerConnection connection,
                                  ObjectName objectName,
                                  Class<T> interfaceClass)

Make a proxy for a Standard MBean in a local or remote MBean Server.

If you have an MBean Server mbs containing an MBean with ObjectName name, and if the MBean's management interface is described by the Java interface MyMBean, you can construct a proxy for the MBean like this:

 MyMBean proxy = JMX.newMBeanProxy(mbs, name, MyMBean.class);
 

Suppose, for example, MyMBean looks like this:

 public interface MyMBean {
     public String getSomeAttribute();
     public void setSomeAttribute(String value);
     public void someOperation(String param1, int param2);
 }
 

Then you can execute:

• proxy.getSomeAttribute() which will result in a call to mbs.getAttribute(name, "SomeAttribute").
• proxy.setSomeAttribute("whatever") which will result in a call to mbs.setAttribute(name, new Attribute("SomeAttribute", "whatever")).
• proxy.someOperation("param1", 2) which will be translated into a call to mbs.invoke(name, "someOperation", <etc>).

The object returned by this method is a Proxy whose InvocationHandler is an MBeanServerInvocationHandler.

This method is equivalent to newMBeanProxy(connection, objectName, interfaceClass, false).

Type Parameters:

T - allows the compiler to know that if the interfaceClass parameter is MyMBean.class, for example, then the return type is MyMBean.

Parameters:

connection - the MBean server to forward to.

objectName - the name of the MBean within connection to forward to.

interfaceClass - the management interface that the MBean exports, which will also be implemented by the returned proxy.

Returns:

the new proxy instance.

newMBeanProxy

public static <T> T newMBeanProxy(MBeanServerConnection connection,
                                  ObjectName objectName,
                                  Class<T> interfaceClass,
                                  boolean notificationEmitter)

Make a proxy for a Standard MBean in a local or remote MBean Server that may also support the methods of NotificationEmitter.

This method behaves the same as newMBeanProxy(MBeanServerConnection, ObjectName, Class), but additionally, if notificationEmitter is true, then the MBean is assumed to be a NotificationBroadcaster or NotificationEmitter and the returned proxy will implement NotificationEmitter as well as interfaceClass. A call to NotificationBroadcaster.addNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object) on the proxy will result in a call to MBeanServerConnection.addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object), and likewise for the other methods of NotificationBroadcaster and NotificationEmitter.

This method is equivalent to newMBeanProxy(connection, objectName, interfaceClass, opts), where opts is a JMX.ProxyOptions representing the notificationEmitter parameter.

Type Parameters:

T - allows the compiler to know that if the interfaceClass parameter is MyMBean.class, for example, then the return type is MyMBean.

Parameters:

connection - the MBean server to forward to.

objectName - the name of the MBean within connection to forward to.

interfaceClass - the management interface that the MBean exports, which will also be implemented by the returned proxy.

notificationEmitter - make the returned proxy implement NotificationEmitter by forwarding its methods via connection.

Returns:

the new proxy instance.

newMXBeanProxy

public static <T> T newMXBeanProxy(MBeanServerConnection connection,
                                   ObjectName objectName,
                                   Class<T> interfaceClass)

Make a proxy for an MXBean in a local or remote MBean Server.

If you have an MBean Server mbs containing an MXBean with ObjectName name, and if the MXBean's management interface is described by the Java interface MyMXBean, you can construct a proxy for the MXBean like this:

 MyMXBean proxy = JMX.newMXBeanProxy(mbs, name, MyMXBean.class);
 

Suppose, for example, MyMXBean looks like this:

 public interface MyMXBean {
     public String getSimpleAttribute();
     public void setSimpleAttribute(String value);
     public MemoryUsage getMappedAttribute();
     public void setMappedAttribute(MemoryUsage memoryUsage);
     public MemoryUsage someOperation(String param1, MemoryUsage param2);
 }
 

Then:

• proxy.getSimpleAttribute() will result in a call to mbs.getAttribute(name, "SimpleAttribute").

• proxy.setSimpleAttribute("whatever") will result in a call to mbs.setAttribute(name, new Attribute("SimpleAttribute", "whatever")).

  Because String is a simple type, in the sense of SimpleType, it is not changed in the context of an MXBean. The MXBean proxy behaves the same as a Standard MBean proxy (see newMBeanProxy) for the attribute SimpleAttribute.

• proxy.getMappedAttribute() will result in a call to mbs.getAttribute("MappedAttribute"). The MXBean mapping rules mean that the actual type of the attribute MappedAttribute will be CompositeData and that is what the mbs.getAttribute call will return. The proxy will then convert the CompositeData back into the expected type MemoryUsage using the MXBean mapping rules.

• Similarly, proxy.setMappedAttribute(memoryUsage) will convert the MemoryUsage argument into a CompositeData before calling mbs.setAttribute.

• proxy.someOperation("whatever", memoryUsage) will convert the MemoryUsage argument into a CompositeData and call mbs.invoke. The value returned by mbs.invoke will be also be a CompositeData, and the proxy will convert this into the expected type MemoryUsage using the MXBean mapping rules.

This method is equivalent to newMXBeanProxy(connection, objectName, interfaceClass, false).

Type Parameters:

T - allows the compiler to know that if the interfaceClass parameter is MyMXBean.class, for example, then the return type is MyMXBean.

Parameters:

connection - the MBean server to forward to.

objectName - the name of the MBean within connection to forward to.

interfaceClass - the MXBean interface, which will also be implemented by the returned proxy.

Returns:

the new proxy instance.

newMXBeanProxy

public static <T> T newMXBeanProxy(MBeanServerConnection connection,
                                   ObjectName objectName,
                                   Class<T> interfaceClass,
                                   boolean notificationEmitter)

Make a proxy for an MXBean in a local or remote MBean Server that may also support the methods of NotificationEmitter.

This method behaves the same as newMXBeanProxy(MBeanServerConnection, ObjectName, Class), but additionally, if notificationEmitter is true, then the MXBean is assumed to be a NotificationBroadcaster or NotificationEmitter and the returned proxy will implement NotificationEmitter as well as interfaceClass. A call to NotificationBroadcaster.addNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object) on the proxy will result in a call to MBeanServerConnection.addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object), and likewise for the other methods of NotificationBroadcaster and NotificationEmitter.

This method is equivalent to newMBeanProxy(connection, objectName, interfaceClass, opts), where opts is a JMX.ProxyOptions where the MXBeanMappingFactory property is MXBeanMappingFactory.forInterface(interfaceClass) and the notificationEmitter property is equal to the notificationEmitter parameter.

Type Parameters:

T - allows the compiler to know that if the interfaceClass parameter is MyMXBean.class, for example, then the return type is MyMXBean.

Parameters:

connection - the MBean server to forward to.

objectName - the name of the MBean within connection to forward to.

interfaceClass - the MXBean interface, which will also be implemented by the returned proxy.

notificationEmitter - make the returned proxy implement NotificationEmitter by forwarding its methods via connection.

Returns:

the new proxy instance.

newMBeanProxy

public static <T> T newMBeanProxy(MBeanServerConnection connection,
                                  ObjectName objectName,
                                  Class<T> interfaceClass,
                                  JMX.MBeanOptions opts)

Make a proxy for a Standard MBean or MXBean in a local or remote MBean Server that may also support the methods of NotificationEmitter and (for an MXBean) that may define custom MXBean type mappings.

This method behaves the same as newMBeanProxy(MBeanServerConnection, ObjectName, Class) or newMXBeanProxy(MBeanServerConnection, ObjectName, Class), according as opts.isMXBean() is respectively false or true; but with the following changes based on opts.

• If opts.isNotificationEmitter() is true, then the MBean is assumed to be a NotificationBroadcaster or NotificationEmitter and the returned proxy will implement NotificationEmitter as well as interfaceClass. A call to NotificationBroadcaster.addNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object) on the proxy will result in a call to MBeanServerConnection.addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object), and likewise for the other methods of NotificationBroadcaster and NotificationEmitter.
• If opts.getMXBeanMappingFactory() is not null, then the mappings it defines will be applied to convert between arbitrary Java types and Open Types.

The object returned by this method is a Proxy whose InvocationHandler is an MBeanServerInvocationHandler. This means that it is possible to retrieve the parameters that were used to produce the proxy. If the proxy was produced as follows...

 FooMBean proxy =
     JMX.newMBeanProxy(connection, objectName, FooMBean.class, opts);
 

...then you can get the MBeanServerInvocationHandler like this...

 MBeanServerInvocationHandler mbsih = (MBeanServerInvocationHandler)
     Proxy.getInvocationHandler(proxy);
 

...and you can retrieve connection, objectName, and opts using the getMBeanServerConnection(), getObjectName(), and getMBeanOptions() methods on mbsih. You can retrieve FooMBean.class using proxy.getClass().getInterfaces().

Type Parameters:

T - allows the compiler to know that if the interfaceClass parameter is MyMXBean.class, for example, then the return type is MyMXBean.

Parameters:

connection - the MBean server to forward to.

objectName - the name of the MBean within connection to forward to.

interfaceClass - the Standard MBean or MXBean interface, which will also be implemented by the returned proxy.

opts - the options to apply for this proxy. Can be null, in which case default options are applied.

Returns:

the new proxy instance.

Throws:

IllegalArgumentException - if interfaceClass is not a valid MXBean interface.

isMXBeanInterface

public static boolean isMXBeanInterface(Class<?> interfaceClass)

Test whether an interface is an MXBean interface. An interface is an MXBean interface if it is annotated @MXBean or @MXBean(true) or if it does not have an @MXBean annotation and its name ends with "MXBean".

Parameters:

interfaceClass - The candidate interface.

Returns:

true if interfaceClass is an interface and meets the conditions described.

Throws:

NullPointerException - if interfaceClass is null.

isNotificationSource

public static boolean isNotificationSource(Object mbean)
                                    throws NotCompliantMBeanException

Test if an MBean can emit notifications. An MBean can emit notifications if either it implements NotificationBroadcaster (perhaps through its child interface NotificationEmitter), or it uses resource injection to obtain an instance of SendNotification through which it can send notifications.

Parameters:

mbean - an MBean object.

Returns:

true if the given object is a valid MBean that can emit notifications; false if the object is a valid MBean but that cannot emit notifications.

Throws:

NotCompliantMBeanException - if the given object is not a valid MBean.

getSpecificationVersion

public static String getSpecificationVersion(MBeanServerConnection mbsc,
                                             ObjectName mbeanName)
                                      throws IOException

Return the version of the JMX specification that a (possibly remote) MBean Server is using. The JMX specification described in this documentation is version 2.0. The earlier versions that might be reported by this method are 1.0, 1.1, 1.2, and 1.4. (There is no 1.3.) All of these versions and all future versions can be compared using String.compareTo(String). So, for example, to tell if mbsc is running at least version 2.0 you can write:

 String version = JMX.getSpecificationVersion(mbsc, null);
 boolean atLeast2dot0 = (version.compareTo("2.0") >= 0);
 

A remote MBean Server might be running an earlier version of the JMX API, and in that case certain features might not be available in it.

The version of the MBean Server mbsc is not necessarily the version of all namespaces within that MBean Server, for example if some of them use JMXRemoteNamespace. To determine the version of the namespace that a particular MBean is in, give its name as the mbeanName parameter.

Parameters:

mbsc - a connection to an MBean Server.

mbeanName - the name of an MBean within that MBean Server, or null. If non-null, the namespace of this name, as determined by JMXNamespaces.getContainingNamespace, is the one whose specification version will be returned.

Returns:

the JMX specification version reported by that MBean Server.

Throws:

IllegalArgumentException - if mbsc is null, or if mbeanName includes a wildcard character (* or ?) in its namespace.

IOException - if the version cannot be obtained, either because there is a communication problem or because the remote MBean Server does not have the appropriate attribute.

See Also:

Interoperability between versions of the JMX specification, MBeanServerDelegateMBean.getSpecificationVersion()