/* * Copyright 2003-2008 Sun Microsystems, Inc. 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. Sun designates this * particular file as subject to the "Classpath" exception as provided * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, * CA 95054 USA or visit www.sun.com if you need additional information or * have any questions. */ package java.lang.management; import javax.management.DynamicMBean; import javax.management.MBeanServer; import javax.management.MBeanServerConnection; import javax.management.MBeanServerFactory; import javax.management.MBeanServerPermission; import javax.management.NotificationEmitter; import javax.management.ObjectInstance; import javax.management.ObjectName; import javax.management.InstanceAlreadyExistsException; import javax.management.InstanceNotFoundException; import javax.management.MalformedObjectNameException; import javax.management.MBeanRegistrationException; import javax.management.NotCompliantMBeanException; import javax.management.StandardEmitterMBean; import javax.management.StandardMBean; import java.util.Collections; import java.util.ArrayList; import java.util.List; import java.security.AccessController; import java.security.Permission; import java.security.PrivilegedAction; import java.security.PrivilegedActionException; import java.security.PrivilegedExceptionAction; import javax.management.JMX; import sun.management.ManagementFactoryHelper; /** * The ManagementFactory class is a factory class for getting * managed beans for the Java platform. * This class consists of static methods each of which returns * one or more platform MXBean(s) representing * the management interface of a component of the Java virtual * machine. * *

* An application can access a platform MXBean in the following ways: *

* *

Platform MXBeans

* A platform MXBean is a managed bean that conforms to * the JMX Instrumentation Specification and only uses * a set of basic data types described below. * See * the specification of MXBeans for details. * All platform MXBean interfaces extend {@link PlatformManagedObject}s * and new methods may be added in these interfaces * in future Java SE releases. *

* A JMX management application and the platform MBeanServer * can interoperate without requiring classes for MXBean specific * data types. * The data types being transmitted between the JMX connector * server and the connector client are * {@linkplain javax.management.openmbean.OpenType open types} * and this allows interoperation across versions. *

* The platform MXBean interfaces use only the following data types: *

* *

* When an attribute or operation of a platform MXBean * is accessed via an MBeanServer, the data types are mapped * as follows: *

* * The {@link javax.management.MBeanInfo MBeanInfo} * for a platform MXBean * describes the data types of the attributes and operations * as primitive or open types mapped as specified above. * *

* For example, the {@link MemoryMXBean} * interface has the following getter and setter methods: * *

 * public MemoryUsage getHeapMemoryUsage();
 * public boolean isVerbose();
 * public void setVerbose(boolean value);
 * 
* * These attributes in the MBeanInfo * of the MemoryMXBean have the following names and types: * *
* * * * * * * * * * * * * *
Attribute NameType
HeapMemoryUsage{@link MemoryUsage#from * CompositeData representing MemoryUsage}
Verboseboolean
*
* *

MXBean Names

* Each platform MXBean for a Java virtual machine has a unique * {@link javax.management.ObjectName ObjectName} for * registration in the platform MBeanServer that can * be obtained by calling the {@link PlatformManagedObject#getObjectName} * method. * * A Java virtual machine has a single instance of the following management * interfaces: * *
* * * * * * * * * * * * * * * * * * * * * * * * * *
Management InterfaceObjectName
{@link ClassLoadingMXBean} {@link #CLASS_LOADING_MXBEAN_NAME * java.lang:type=ClassLoading}
{@link MemoryMXBean} {@link #MEMORY_MXBEAN_NAME * java.lang:type=Memory}
{@link ThreadMXBean} {@link #THREAD_MXBEAN_NAME * java.lang:type=Threading}
{@link RuntimeMXBean} {@link #RUNTIME_MXBEAN_NAME * java.lang:type=Runtime}
{@link OperatingSystemMXBean} {@link #OPERATING_SYSTEM_MXBEAN_NAME * java.lang:type=OperatingSystem}
*
* *

* A Java virtual machine has zero or a single instance of * the following management interfaces. * *

* * * * * * * * * *
Management InterfaceObjectName
{@link CompilationMXBean} {@link #COMPILATION_MXBEAN_NAME * java.lang:type=Compilation}
*
* *

* A Java virtual machine may have one or more instances of the following * management interfaces. *

* * * * * * * * * * * * * * * * * *
Management InterfaceObjectName
{@link GarbageCollectorMXBean} {@link #GARBAGE_COLLECTOR_MXBEAN_DOMAIN_TYPE * java.lang:type=GarbageCollector},name=collector's name
{@link MemoryManagerMXBean} {@link #MEMORY_MANAGER_MXBEAN_DOMAIN_TYPE * java.lang:type=MemoryManager},name=manager's name
{@link MemoryPoolMXBean} {@link #MEMORY_POOL_MXBEAN_DOMAIN_TYPE * java.lang:type=MemoryPool},name=pool's name
*
* * @see * JMX Specification * @see * Ways to Access Management Metrics * @see java.util.logging.LoggingMXBean * @see javax.management.MXBean * * @author Mandy Chung * @since 1.5 */ public class ManagementFactory { // A class with only static fields and methods. private ManagementFactory() {}; /** * String representation of the * ObjectName for the {@link ClassLoadingMXBean}. */ public final static String CLASS_LOADING_MXBEAN_NAME = "java.lang:type=ClassLoading"; /** * String representation of the * ObjectName for the {@link CompilationMXBean}. */ public final static String COMPILATION_MXBEAN_NAME = "java.lang:type=Compilation"; /** * String representation of the * ObjectName for the {@link MemoryMXBean}. */ public final static String MEMORY_MXBEAN_NAME = "java.lang:type=Memory"; /** * String representation of the * ObjectName for the {@link OperatingSystemMXBean}. */ public final static String OPERATING_SYSTEM_MXBEAN_NAME = "java.lang:type=OperatingSystem"; /** * String representation of the * ObjectName for the {@link RuntimeMXBean}. */ public final static String RUNTIME_MXBEAN_NAME = "java.lang:type=Runtime"; /** * String representation of the * ObjectName for the {@link ThreadMXBean}. */ public final static String THREAD_MXBEAN_NAME = "java.lang:type=Threading"; /** * The domain name and the type key property in * the ObjectName for a {@link GarbageCollectorMXBean}. * The unique ObjectName for a GarbageCollectorMXBean * can be formed by appending this string with * ",name=collector's name". */ public final static String GARBAGE_COLLECTOR_MXBEAN_DOMAIN_TYPE = "java.lang:type=GarbageCollector"; /** * The domain name and the type key property in * the ObjectName for a {@link MemoryManagerMXBean}. * The unique ObjectName for a MemoryManagerMXBean * can be formed by appending this string with * ",name=manager's name". */ public final static String MEMORY_MANAGER_MXBEAN_DOMAIN_TYPE= "java.lang:type=MemoryManager"; /** * The domain name and the type key property in * the ObjectName for a {@link MemoryPoolMXBean}. * The unique ObjectName for a MemoryPoolMXBean * can be formed by appending this string with * ,name=pool's name. */ public final static String MEMORY_POOL_MXBEAN_DOMAIN_TYPE= "java.lang:type=MemoryPool"; /** * Returns the managed bean for the class loading system of * the Java virtual machine. * * @return a {@link ClassLoadingMXBean} object for * the Java virtual machine. */ public static ClassLoadingMXBean getClassLoadingMXBean() { return ManagementFactoryHelper.getClassLoadingMXBean(); } /** * Returns the managed bean for the memory system of * the Java virtual machine. * * @return a {@link MemoryMXBean} object for the Java virtual machine. */ public static MemoryMXBean getMemoryMXBean() { return ManagementFactoryHelper.getMemoryMXBean(); } /** * Returns the managed bean for the thread system of * the Java virtual machine. * * @return a {@link ThreadMXBean} object for the Java virtual machine. */ public static ThreadMXBean getThreadMXBean() { return ManagementFactoryHelper.getThreadMXBean(); } /** * Returns the managed bean for the runtime system of * the Java virtual machine. * * @return a {@link RuntimeMXBean} object for the Java virtual machine. */ public static RuntimeMXBean getRuntimeMXBean() { return ManagementFactoryHelper.getRuntimeMXBean(); } /** * Returns the managed bean for the compilation system of * the Java virtual machine. This method returns null * if the Java virtual machine has no compilation system. * * @return a {@link CompilationMXBean} object for the Java virtual * machine or null if the Java virtual machine has * no compilation system. */ public static CompilationMXBean getCompilationMXBean() { return ManagementFactoryHelper.getCompilationMXBean(); } /** * Returns the managed bean for the operating system on which * the Java virtual machine is running. * * @return an {@link OperatingSystemMXBean} object for * the Java virtual machine. */ public static OperatingSystemMXBean getOperatingSystemMXBean() { return ManagementFactoryHelper.getOperatingSystemMXBean(); } /** * Returns a list of {@link MemoryPoolMXBean} objects in the * Java virtual machine. * The Java virtual machine can have one or more memory pools. * It may add or remove memory pools during execution. * * @return a list of MemoryPoolMXBean objects. * */ public static List getMemoryPoolMXBeans() { return ManagementFactoryHelper.getMemoryPoolMXBeans(); } /** * Returns a list of {@link MemoryManagerMXBean} objects * in the Java virtual machine. * The Java virtual machine can have one or more memory managers. * It may add or remove memory managers during execution. * * @return a list of MemoryManagerMXBean objects. * */ public static List getMemoryManagerMXBeans() { return ManagementFactoryHelper.getMemoryManagerMXBeans(); } /** * Returns a list of {@link GarbageCollectorMXBean} objects * in the Java virtual machine. * The Java virtual machine may have one or more * GarbageCollectorMXBean objects. * It may add or remove GarbageCollectorMXBean * during execution. * * @return a list of GarbageCollectorMXBean objects. * */ public static List getGarbageCollectorMXBeans() { return ManagementFactoryHelper.getGarbageCollectorMXBeans(); } private static MBeanServer platformMBeanServer; /** * Returns the platform {@link javax.management.MBeanServer MBeanServer}. * On the first call to this method, it first creates the platform * MBeanServer by calling the * {@link javax.management.MBeanServerFactory#createMBeanServer * MBeanServerFactory.createMBeanServer} * method and registers the platform MXBeans in this platform * MBeanServer using the MXBean names * defined in the class description. * This method, in subsequent calls, will simply return the * initially created platform MBeanServer. *

* MXBeans that get created and destroyed dynamically, for example, * memory {@link MemoryPoolMXBean pools} and * {@link MemoryManagerMXBean managers}, * will automatically be registered and deregistered into the platform * MBeanServer. *

* If the system property javax.management.builder.initial * is set, the platform MBeanServer creation will be done * by the specified {@link javax.management.MBeanServerBuilder}. *

* It is recommended that this platform MBeanServer also be used * to register other application managed beans * besides the platform MXBeans. * This will allow all MBeans to be published through the same * MBeanServer and hence allow for easier network publishing * and discovery. * Name conflicts with the platform MXBeans should be avoided. * * @return the platform MBeanServer; the platform * MXBeans are registered into the platform MBeanServer * at the first time this method is called. * * @exception SecurityException if there is a security manager * and the caller does not have the permission required by * {@link javax.management.MBeanServerFactory#createMBeanServer}. * * @see javax.management.MBeanServerFactory * @see javax.management.MBeanServerFactory#createMBeanServer */ public static synchronized MBeanServer getPlatformMBeanServer() { SecurityManager sm = System.getSecurityManager(); if (sm != null) { Permission perm = new MBeanServerPermission("createMBeanServer"); sm.checkPermission(perm); } if (platformMBeanServer == null) { platformMBeanServer = MBeanServerFactory.createMBeanServer(); for (PlatformComponent pc : PlatformComponent.values()) { List list = pc.getMXBeans(pc.getMXBeanInterface()); for (PlatformManagedObject o : list) { // Each PlatformComponent represents one management // interface. Some MXBean may extend another one. // The MXBean instances for one platform component // (returned by pc.getMXBeans()) might be also // the MXBean instances for another platform component. // e.g. com.sun.management.GarbageCollectorMXBean // // So need to check if an MXBean instance is registered // before registering into the platform MBeanServer if (!platformMBeanServer.isRegistered(o.getObjectName())) { addMXBean(platformMBeanServer, o); } } } } return platformMBeanServer; } /** * Returns a proxy for a platform MXBean interface of a * given MXBean name * that forwards its method calls through the given * MBeanServerConnection. * *

This method is equivalent to: *

* {@link java.lang.reflect.Proxy#newProxyInstance * Proxy.newProxyInstance}(mxbeanInterface.getClassLoader(), * new Class[] { mxbeanInterface }, handler) *
* * where handler is an {@link java.lang.reflect.InvocationHandler * InvocationHandler} to which method invocations to the MXBean interface * are dispatched. This handler converts an input parameter * from an MXBean data type to its mapped open type before forwarding * to the MBeanServer and converts a return value from * an MXBean method call through the MBeanServer * from an open type to the corresponding return type declared in * the MXBean interface. * *

* If the MXBean is a notification emitter (i.e., * it implements * {@link javax.management.NotificationEmitter NotificationEmitter}), * both the mxbeanInterface and NotificationEmitter * will be implemented by this proxy. * *

* Notes: *

    *
  1. Using an MXBean proxy is a convenience remote access to * a platform MXBean of a running virtual machine. All method * calls to the MXBean proxy are forwarded to an * MBeanServerConnection where * {@link java.io.IOException IOException} may be thrown * when the communication problem occurs with the connector server. * An application remotely accesses the platform MXBeans using * proxy should prepare to catch IOException as if * accessing with the MBeanServerConnector interface.
  2. * *
  3. When a client application is designed to remotely access MXBeans * for a running virtual machine whose version is different than * the version on which the application is running, * it should prepare to catch * {@link java.io.InvalidObjectException InvalidObjectException} * which is thrown when an MXBean proxy receives a name of an * enum constant which is missing in the enum class loaded in * the client application.
  4. * *
  5. {@link javax.management.MBeanServerInvocationHandler * MBeanServerInvocationHandler} or its * {@link javax.management.MBeanServerInvocationHandler#newProxyInstance * newProxyInstance} method cannot be used to create * a proxy for a platform MXBean. The proxy object created * by MBeanServerInvocationHandler does not handle * the properties of the platform MXBeans described in * the class specification. *
  6. *
* * @param connection the MBeanServerConnection to forward to. * @param mxbeanName the name of a platform MXBean within * connection to forward to. mxbeanName must be * in the format of {@link ObjectName ObjectName}. * @param mxbeanInterface the MXBean interface to be implemented * by the proxy. * * @throws IllegalArgumentException if *
    *
  • mxbeanName is not with a valid * {@link ObjectName ObjectName} format, or
  • *
  • the named MXBean in the connection is * not a MXBean provided by the platform, or
  • *
  • the named MXBean is not registered in the * MBeanServerConnection, or
  • *
  • the named MXBean is not an instance of the given * mxbeanInterface
  • *
* * @throws java.io.IOException if a communication problem * occurred when accessing the MBeanServerConnection. */ public static T newPlatformMXBeanProxy(MBeanServerConnection connection, String mxbeanName, Class mxbeanInterface) throws java.io.IOException { final Class interfaceClass = mxbeanInterface; // Only allow MXBean interfaces from rt.jar loaded by the // bootstrap class loader final ClassLoader loader = AccessController.doPrivileged(new PrivilegedAction() { public ClassLoader run() { return interfaceClass.getClassLoader(); } }); if (loader != null) { throw new IllegalArgumentException(mxbeanName + " is not a platform MXBean"); } try { final ObjectName objName = new ObjectName(mxbeanName); if (!connection.isInstanceOf(objName, interfaceClass.getName())) { throw new IllegalArgumentException(mxbeanName + " is not an instance of " + interfaceClass); } final Class[] interfaces; // check if the registered MBean is a notification emitter boolean emitter = connection.isInstanceOf(objName, NOTIF_EMITTER); // create an MXBean proxy return JMX.newMXBeanProxy(connection, objName, mxbeanInterface, emitter); } catch (InstanceNotFoundException e) { final IllegalArgumentException iae = new IllegalArgumentException(mxbeanName + " not found in the connection."); iae.initCause(e); throw iae; } catch (MalformedObjectNameException e) { final IllegalArgumentException iae = new IllegalArgumentException(mxbeanName + " is not a valid ObjectName format."); iae.initCause(e); throw iae; } } /** * Returns the list of platform MXBeans that implement * the given {@code mxbeanInterface} in the running Java * virtual machine. * The returned list may contain zero, one, or more instances. * The number of instances in the returned list is defined * in the specification of the given management interface. * * @param mxbeanInterface a management interface for a platform * MXBean * * @return the list of platform MXBeans that implements * {@code mxbeanInterface}. * * @throws IllegalArgumentException if {@code mxbeanInterface} * is not a management interface for the platform. * * @since 1.7 */ public static List getPlatformMXBeans(Class mxbeanInterface) { String className = mxbeanInterface.getName(); for (PlatformComponent component: PlatformComponent.values()) { // comparing the class name first instead of the Class instance // to avoid causing unnecessary class loading of // the other MXBean interfaces if (className.equals(component.getMXBeanInterfaceName())) { if (component.getMXBeanInterface() == mxbeanInterface) { return component.getMXBeans(mxbeanInterface); } } } throw new IllegalArgumentException(mxbeanInterface.getName() + " is not implemented by any of the platform MXBeans."); } /** * Returns the list of the platform MXBean proxies for * forwarding the method calls of the {@code mxbeanInterface} * through the given {@code MBeanServerConnection}. * The returned list may contain zero, one, or more instances. * The number of instances in the returned list is defined * in the specification of the given management interface. * * @param connection the {@code MBeanServerConnection} to forward to. * @param mxbeanInterface a management interface for a platform * MXBean * * @return the list of platform MXBean proxies for * forwarding the method calls of the {@code mxbeanInterface} * through the given {@code MBeanServerConnection}. * * @throws IllegalArgumentException if {@code mxbeanInterface} * is not a management interface for the platform. * * @throws java.io.IOException if a communication problem * occurred when accessing the {@code MBeanServerConnection}. * * @since 1.7 */ public static List getPlatformMXBeans(MBeanServerConnection connection, Class mxbeanInterface) throws java.io.IOException { String className = mxbeanInterface.getName(); for (PlatformComponent component: PlatformComponent.values()) { // comparing the class name first instead of the Class instance // to avoid causing unnecessary class loading of // the other MXBean interfaces if (className.equals(component.getMXBeanInterfaceName())) { if (component.getMXBeanInterface() == mxbeanInterface) { return component.getMXBeans(connection, mxbeanInterface); } } } throw new IllegalArgumentException(mxbeanInterface.getName() + " is not implemented by any of the platform MXBeans."); } /** * Returns a list of {@code Class} objects, subinterface of * {@link PlatformManagedObject}, representing * all management interfaces for * monitoring and managing the Java platform. * * @return a list of {@code Class} objects, subinterface of * {@link PlatformManagedObject} representing * the management interfaces for * monitoring and managing the Java platform. * * @since 1.7 */ public static List> getAllPlatformMXBeanInterfaces() { List> result = new ArrayList>(); for (PlatformComponent component: PlatformComponent.values()) { result.add(component.getMXBeanInterface()); } return result; } private static final String NOTIF_EMITTER = "javax.management.NotificationEmitter"; /** * Registers an MXBean. */ private static void addMXBean(final MBeanServer mbs, final PlatformManagedObject pmo) { // Make DynamicMBean out of MXBean by wrapping it with a StandardMBean final DynamicMBean dmbean; if (pmo instanceof NotificationEmitter) { dmbean = new StandardEmitterMBean(pmo, null, true, (NotificationEmitter) pmo); } else { dmbean = new StandardMBean(pmo, null, true); } try { AccessController.doPrivileged(new PrivilegedExceptionAction() { public Void run() throws InstanceAlreadyExistsException, MBeanRegistrationException, NotCompliantMBeanException { mbs.registerMBean(dmbean, pmo.getObjectName()); return null; } }); } catch (PrivilegedActionException e) { throw new RuntimeException(e.getException()); } } }