/*
* Copyright (c) 2005, 2006, 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.
*/
package javax.management;
import com.sun.jmx.mbeanserver.Introspector;
import java.lang.reflect.InvocationHandler;
import java.lang.reflect.Modifier;
import java.lang.reflect.Proxy;
import sun.reflect.misc.ReflectUtil;
/**
* Static methods from the JMX API. There are no instances of this class.
*
* @since 1.6
*/
public class JMX {
/* Code within this package can prove that by providing this instance of
* this class.
*/
static final JMX proof = new JMX();
private JMX() {}
/**
* The name of the <a href="Descriptor.html#defaultValue">{@code
* defaultValue}</a> field.
*/
public static final String DEFAULT_VALUE_FIELD = "defaultValue";
/**
* The name of the <a href="Descriptor.html#immutableInfo">{@code
* immutableInfo}</a> field.
*/
public static final String IMMUTABLE_INFO_FIELD = "immutableInfo";
/**
* The name of the <a href="Descriptor.html#interfaceClassName">{@code
* interfaceClassName}</a> field.
*/
public static final String INTERFACE_CLASS_NAME_FIELD = "interfaceClassName";
/**
* The name of the <a href="Descriptor.html#legalValues">{@code
* legalValues}</a> field.
*/
public static final String LEGAL_VALUES_FIELD = "legalValues";
/**
* The name of the <a href="Descriptor.html#maxValue">{@code
* maxValue}</a> field.
*/
public static final String MAX_VALUE_FIELD = "maxValue";
/**
* The name of the <a href="Descriptor.html#minValue">{@code
* minValue}</a> field.
*/
public static final String MIN_VALUE_FIELD = "minValue";
/**
* The name of the <a href="Descriptor.html#mxbean">{@code
* mxbean}</a> field.
*/
public static final String MXBEAN_FIELD = "mxbean";
/**
* The name of the <a href="Descriptor.html#openType">{@code
* openType}</a> field.
*/
public static final String OPEN_TYPE_FIELD = "openType";
/**
* The name of the <a href="Descriptor.html#originalType">{@code
* originalType}</a> field.
*/
public static final String ORIGINAL_TYPE_FIELD = "originalType";
/**
* <p>Make a proxy for a Standard MBean in a local or remote
* MBean Server.</p>
*
* <p>If you have an MBean Server {@code mbs} containing an MBean
* with {@link ObjectName} {@code name}, and if the MBean's
* management interface is described by the Java interface
* {@code MyMBean}, you can construct a proxy for the MBean like
* this:</p>
*
* <pre>
* MyMBean proxy = JMX.newMBeanProxy(mbs, name, MyMBean.class);
* </pre>
*
* <p>Suppose, for example, {@code MyMBean} looks like this:</p>
*
* <pre>
* public interface MyMBean {
* public String getSomeAttribute();
* public void setSomeAttribute(String value);
* public void someOperation(String param1, int param2);
* }
* </pre>
*
* <p>Then you can execute:</p>
*
* <ul>
*
* <li>{@code proxy.getSomeAttribute()} which will result in a
* call to {@code mbs.}{@link MBeanServerConnection#getAttribute
* getAttribute}{@code (name, "SomeAttribute")}.
*
* <li>{@code proxy.setSomeAttribute("whatever")} which will result
* in a call to {@code mbs.}{@link MBeanServerConnection#setAttribute
* setAttribute}{@code (name, new Attribute("SomeAttribute", "whatever"))}.
*
* <li>{@code proxy.someOperation("param1", 2)} which will be
* translated into a call to {@code mbs.}{@link
* MBeanServerConnection#invoke invoke}{@code (name, "someOperation", <etc>)}.
*
* </ul>
*
* <p>The object returned by this method is a
* {@link Proxy} whose {@code InvocationHandler} is an
* {@link MBeanServerInvocationHandler}.</p>
*
* <p>This method is equivalent to {@link
* #newMBeanProxy(MBeanServerConnection, ObjectName, Class,
* boolean) newMBeanProxy(connection, objectName, interfaceClass,
* false)}.</p>
*
* @param connection the MBean server to forward to.
* @param objectName the name of the MBean within
* {@code connection} to forward to.
* @param interfaceClass the management interface that the MBean
* exports, which will also be implemented by the returned proxy.
*
* @param <T> allows the compiler to know that if the {@code
* interfaceClass} parameter is {@code MyMBean.class}, for
* example, then the return type is {@code MyMBean}.
*
* @return the new proxy instance.
*
* @throws IllegalArgumentException if {@code interfaceClass} is not
* a <a href="package-summary.html#mgIface">compliant MBean
* interface</a>
*/
public static <T> T newMBeanProxy(MBeanServerConnection connection,
ObjectName objectName,
Class<T> interfaceClass) {
return newMBeanProxy(connection, objectName, interfaceClass, false);
}
/**
* <p>Make a proxy for a Standard MBean in a local or remote MBean
* Server that may also support the methods of {@link
* NotificationEmitter}.</p>
*
* <p>This method behaves the same as {@link
* #newMBeanProxy(MBeanServerConnection, ObjectName, Class)}, but
* additionally, if {@code notificationEmitter} is {@code
* true}, then the MBean is assumed to be a {@link
* NotificationBroadcaster} or {@link NotificationEmitter} and the
* returned proxy will implement {@link NotificationEmitter} as
* well as {@code interfaceClass}. A call to {@link
* NotificationBroadcaster#addNotificationListener} on the proxy
* will result in a call to {@link
* MBeanServerConnection#addNotificationListener(ObjectName,
* NotificationListener, NotificationFilter, Object)}, and
* likewise for the other methods of {@link
* NotificationBroadcaster} and {@link NotificationEmitter}.</p>
*
* @param connection the MBean server to forward to.
* @param objectName the name of the MBean within
* {@code connection} to forward to.
* @param interfaceClass the management interface that the MBean
* exports, which will also be implemented by the returned proxy.
* @param notificationEmitter make the returned proxy
* implement {@link NotificationEmitter} by forwarding its methods
* via {@code connection}.
*
* @param <T> allows the compiler to know that if the {@code
* interfaceClass} parameter is {@code MyMBean.class}, for
* example, then the return type is {@code MyMBean}.
*
* @return the new proxy instance.
*
* @throws IllegalArgumentException if {@code interfaceClass} is not
* a <a href="package-summary.html#mgIface">compliant MBean
* interface</a>
*/
public static <T> T newMBeanProxy(MBeanServerConnection connection,
ObjectName objectName,
Class<T> interfaceClass,
boolean notificationEmitter) {
return createProxy(connection, objectName, interfaceClass, notificationEmitter, false);
}
/**
* <p>Make a proxy for an MXBean in a local or remote
* MBean Server.</p>
*
* <p>If you have an MBean Server {@code mbs} containing an
* MXBean with {@link ObjectName} {@code name}, and if the
* MXBean's management interface is described by the Java
* interface {@code MyMXBean}, you can construct a proxy for
* the MXBean like this:</p>
*
* <pre>
* MyMXBean proxy = JMX.newMXBeanProxy(mbs, name, MyMXBean.class);
* </pre>
*
* <p>Suppose, for example, {@code MyMXBean} looks like this:</p>
*
* <pre>
* public interface MyMXBean {
* public String getSimpleAttribute();
* public void setSimpleAttribute(String value);
* public {@link java.lang.management.MemoryUsage} getMappedAttribute();
* public void setMappedAttribute(MemoryUsage memoryUsage);
* public MemoryUsage someOperation(String param1, MemoryUsage param2);
* }
* </pre>
*
* <p>Then:</p>
*
* <ul>
*
* <li><p>{@code proxy.getSimpleAttribute()} will result in a
* call to {@code mbs.}{@link MBeanServerConnection#getAttribute
* getAttribute}{@code (name, "SimpleAttribute")}.</p>
*
* <li><p>{@code proxy.setSimpleAttribute("whatever")} will result
* in a call to {@code mbs.}{@link
* MBeanServerConnection#setAttribute setAttribute}<code>(name,
* new Attribute("SimpleAttribute", "whatever"))</code>.<p>
*
* <p>Because {@code String} is a <em>simple type</em>, in the
* sense of {@link javax.management.openmbean.SimpleType}, it
* is not changed in the context of an MXBean. The MXBean
* proxy behaves the same as a Standard MBean proxy (see
* {@link #newMBeanProxy(MBeanServerConnection, ObjectName,
* Class) newMBeanProxy}) for the attribute {@code
* SimpleAttribute}.</p>
*
* <li><p>{@code proxy.getMappedAttribute()} will result in a call
* to {@code mbs.getAttribute("MappedAttribute")}. The MXBean
* mapping rules mean that the actual type of the attribute {@code
* MappedAttribute} will be {@link
* javax.management.openmbean.CompositeData CompositeData} and
* that is what the {@code mbs.getAttribute} call will return.
* The proxy will then convert the {@code CompositeData} back into
* the expected type {@code MemoryUsage} using the MXBean mapping
* rules.</p>
*
* <li><p>Similarly, {@code proxy.setMappedAttribute(memoryUsage)}
* will convert the {@code MemoryUsage} argument into a {@code
* CompositeData} before calling {@code mbs.setAttribute}.</p>
*
* <li><p>{@code proxy.someOperation("whatever", memoryUsage)}
* will convert the {@code MemoryUsage} argument into a {@code
* CompositeData} and call {@code mbs.invoke}. The value returned
* by {@code mbs.invoke} will be also be a {@code CompositeData},
* and the proxy will convert this into the expected type {@code
* MemoryUsage} using the MXBean mapping rules.</p>
*
* </ul>
*
* <p>The object returned by this method is a
* {@link Proxy} whose {@code InvocationHandler} is an
* {@link MBeanServerInvocationHandler}.</p>
*
* <p>This method is equivalent to {@link
* #newMXBeanProxy(MBeanServerConnection, ObjectName, Class,
* boolean) newMXBeanProxy(connection, objectName, interfaceClass,
* false)}.</p>
*
* @param connection the MBean server to forward to.
* @param objectName the name of the MBean within
* {@code connection} to forward to.
* @param interfaceClass the MXBean interface,
* which will also be implemented by the returned proxy.
*
* @param <T> allows the compiler to know that if the {@code
* interfaceClass} parameter is {@code MyMXBean.class}, for
* example, then the return type is {@code MyMXBean}.
*
* @return the new proxy instance.
*
* @throws IllegalArgumentException if {@code interfaceClass} is not
* a {@link javax.management.MXBean compliant MXBean interface}
*/
public static <T> T newMXBeanProxy(MBeanServerConnection connection,
ObjectName objectName,
Class<T> interfaceClass) {
return newMXBeanProxy(connection, objectName, interfaceClass, false);
}
/**
* <p>Make a proxy for an MXBean in a local or remote MBean
* Server that may also support the methods of {@link
* NotificationEmitter}.</p>
*
* <p>This method behaves the same as {@link
* #newMXBeanProxy(MBeanServerConnection, ObjectName, Class)}, but
* additionally, if {@code notificationEmitter} is {@code
* true}, then the MXBean is assumed to be a {@link
* NotificationBroadcaster} or {@link NotificationEmitter} and the
* returned proxy will implement {@link NotificationEmitter} as
* well as {@code interfaceClass}. A call to {@link
* NotificationBroadcaster#addNotificationListener} on the proxy
* will result in a call to {@link
* MBeanServerConnection#addNotificationListener(ObjectName,
* NotificationListener, NotificationFilter, Object)}, and
* likewise for the other methods of {@link
* NotificationBroadcaster} and {@link NotificationEmitter}.</p>
*
* @param connection the MBean server to forward to.
* @param objectName the name of the MBean within
* {@code connection} to forward to.
* @param interfaceClass the MXBean interface,
* which will also be implemented by the returned proxy.
* @param notificationEmitter make the returned proxy
* implement {@link NotificationEmitter} by forwarding its methods
* via {@code connection}.
*
* @param <T> allows the compiler to know that if the {@code
* interfaceClass} parameter is {@code MyMXBean.class}, for
* example, then the return type is {@code MyMXBean}.
*
* @return the new proxy instance.
*
* @throws IllegalArgumentException if {@code interfaceClass} is not
* a {@link javax.management.MXBean compliant MXBean interface}
*/
public static <T> T newMXBeanProxy(MBeanServerConnection connection,
ObjectName objectName,
Class<T> interfaceClass,
boolean notificationEmitter) {
return createProxy(connection, objectName, interfaceClass, notificationEmitter, true);
}
/**
* <p>Test whether an interface is an MXBean interface.
* An interface is an MXBean interface if it is public,
* annotated {@link MXBean @MXBean} or {@code @MXBean(true)}
* or if it does not have an {@code @MXBean} annotation
* and its name ends with "{@code MXBean}".</p>
*
* @param interfaceClass The candidate interface.
*
* @return true if {@code interfaceClass} is a
* {@link javax.management.MXBean compliant MXBean interface}
*
* @throws NullPointerException if {@code interfaceClass} is null.
*/
public static boolean isMXBeanInterface(Class<?> interfaceClass) {
if (!interfaceClass.isInterface())
return false;
if (!Modifier.isPublic(interfaceClass.getModifiers()) &&
!Introspector.ALLOW_NONPUBLIC_MBEAN) {
return false;
}
MXBean a = interfaceClass.getAnnotation(MXBean.class);
if (a != null)
return a.value();
return interfaceClass.getName().endsWith("MXBean");
// We don't bother excluding the case where the name is
// exactly the string "MXBean" since that would mean there
// was no package name, which is pretty unlikely in practice.
}
/**
* Centralised M(X)Bean proxy creation code
* @param connection {@linkplain MBeanServerConnection} to use
* @param objectName M(X)Bean object name
* @param interfaceClass M(X)Bean interface class
* @param notificationEmitter Is a notification emitter?
* @param isMXBean Is an MXBean?
* @return Returns an M(X)Bean proxy generated for the provided interface class
* @throws SecurityException
* @throws IllegalArgumentException
*/
private static <T> T createProxy(MBeanServerConnection connection,
ObjectName objectName,
Class<T> interfaceClass,
boolean notificationEmitter,
boolean isMXBean) {
try {
if (isMXBean) {
// Check interface for MXBean compliance
Introspector.testComplianceMXBeanInterface(interfaceClass);
} else {
// Check interface for MBean compliance
Introspector.testComplianceMBeanInterface(interfaceClass);
}
} catch (NotCompliantMBeanException e) {
throw new IllegalArgumentException(e);
}
InvocationHandler handler = new MBeanServerInvocationHandler(
connection, objectName, isMXBean);
final Class<?>[] interfaces;
if (notificationEmitter) {
interfaces =
new Class<?>[] {interfaceClass, NotificationEmitter.class};
} else
interfaces = new Class<?>[] {interfaceClass};
Object proxy = Proxy.newProxyInstance(
interfaceClass.getClassLoader(),
interfaces,
handler);
return interfaceClass.cast(proxy);
}
}