Java tutorial
/* * Copyright (c) 2005, 2013, 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); } /** * Make a proxy for an MXBean in a local or remote MBean Server. * * <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); } }