< prev index next >

src/java.management/share/classes/java/lang/management/package.html

Print this page


   1 <!--
   2  Copyright (c) 2003, 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
  23  questions.
  24 -->
  25 
  26 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  27 <html>
  28 <body bgcolor="white">
  29 
  30 Provides the management interfaces for monitoring and management of the
  31 Java virtual machine and other components in the Java runtime.
  32 It allows both local and remote
  33 monitoring and management of the running Java virtual machine.
  34 
  35 <h2><a id="MXBean">Platform MXBean</a></h2>
  36 <p>
  37 A platform MXBean is a <i>managed bean</i> that
  38 conforms to the {@linkplain javax.management JMX}
  39 Instrumentation Specification and only uses a set of basic data types.
  40 Each platform MXBean is a {@link java.lang.management.PlatformManagedObject}
  41 with a unique
  42 {@linkplain java.lang.management.PlatformManagedObject#getObjectName name}.
  43 <h2>ManagementFactory</h2>
  44 
  45 <p>The {@link java.lang.management.ManagementFactory} class is the management
  46 factory class for the Java platform.  This class provides a set of
  47 static factory methods to obtain the MXBeans for the Java platform
  48 to allow an application to access the MXBeans directly.
  49 
  50 <p>A <em>platform MBeanServer</em> can be accessed with the
  51 {@link java.lang.management.ManagementFactory#getPlatformMBeanServer
  52  getPlatformMBeanServer} method.  On the first call to this method,
  53 it creates the platform MBeanServer and registers all platform MXBeans
  54 including {@linkplain java.lang.management.PlatformManagedObject
  55 platform MXBeans}.
  56 Each platform MXBean is registered with a unique name defined in
  57 the specification of the management interface.
  58 This is a single MBeanServer that can be shared by different managed
  59 components running within the same Java virtual machine.
  60 
  61 <h2>Interoperability</h2>
  62 
  63 <p>A management application and a platform MBeanServer of a running
  64 virtual machine can interoperate
  65 without requiring classes used by the platform MXBean interfaces.
  66 The data types being transmitted between the JMX connector
  67 server and the connector client are JMX
  68 {@linkplain javax.management.openmbean.OpenType open types} and
  69 this allows interoperation across versions.
  70 A data type used by the MXBean interfaces are mapped to an
  71 open type when being accessed via MBeanServer interface.
  72 See the <a href="{@docRoot}/java.management/javax/management/MXBean.html#MXBean-spec">
  73 MXBean</a> specification for details.
  74 
  75 <h2><a id="examples">Ways to Access MXBeans</a></h2>
  76 
  77 <p>An application can monitor the instrumentation of the
  78 Java virtual machine and the runtime in the following ways:
  79 <p>
  80 <b>1. Direct access to an MXBean interface</b>
  81 <ul>
  82 <li>Get an MXBean instance locally in the running Java virtual machine:
  83 <pre>
  84    RuntimeMXBean mxbean = ManagementFactory.getRuntimeMXBean();
  85 
  86    // Get the standard attribute "VmVendor"
  87    String vendor = mxbean.getVmVendor();
  88 </pre>
  89 <p>Or by calling the
  90         {@link java.lang.management.ManagementFactory#getPlatformMXBean(Class)
  91                getPlatformMXBean} or
  92         {@link java.lang.management.ManagementFactory#getPlatformMXBeans(Class)
  93                getPlatformMXBeans} method:
  94 <pre>
  95    RuntimeMXBean mxbean = ManagementFactory.getPlatformMXBean(RuntimeMXBean.class);


 146    // Connect to a running JVM (or itself) and get MBeanServerConnection
 147    // that has the JVM MXBeans registered in it
 148    ...
 149 
 150    try {
 151        // Assuming the RuntimeMXBean has been registered in mbs
 152        ObjectName oname = new ObjectName(ManagementFactory.RUNTIME_MXBEAN_NAME);
 153 
 154        // Get standard attribute "VmVendor"
 155        String vendor = (String) mbs.getAttribute(oname, "VmVendor");
 156    } catch (....) {
 157        // Catch the exceptions thrown by ObjectName constructor
 158        // and MBeanServer.getAttribute method
 159        ...
 160    }
 161 </pre>
 162 </li>
 163 </ul>
 164 
 165 
 166 <h2><a id="extension">Platform Extension</a></h2>
 167 
 168 <p>A Java virtual machine implementation may add its platform extension to
 169 the management interface by defining platform-dependent
 170 interfaces that extend the standard management interfaces to include
 171 platform-specific metrics and management operations.
 172 The static factory methods in the <code>ManagementFactory</code> class will
 173 return the MXBeans with the platform extension.
 174 
 175 <p>
 176 It is recommended to name the platform-specific attributes with
 177 a vendor-specific prefix such as the vendor's name to
 178 avoid collisions of the attribute name between the future extension
 179 to the standard management interface and the platform extension.
 180 If the future extension to the standard management interface defines
 181 a new attribute for a management interface and the attribute name
 182 is happened to be same as some vendor-specific attribute's name,
 183 the applications accessing that vendor-specific attribute would have
 184 to be modified to cope with versioning and compatibility issues.
 185 
 186 <p>Below is an example showing how to access an attribute


   1 <!--
   2  Copyright (c) 2003, 2018, 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
  23  questions.
  24 -->
  25 
  26 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  27 <html>
  28 <body bgcolor="white">
  29 
  30 Provides the management interfaces for monitoring and management of the
  31 Java virtual machine and other components in the Java runtime.
  32 It allows both local and remote
  33 monitoring and management of the running Java virtual machine.
  34 
  35 <h3><a id="MXBean">Platform MXBean</a></h3>
  36 <p>
  37 A platform MXBean is a <i>managed bean</i> that
  38 conforms to the {@linkplain javax.management JMX}
  39 Instrumentation Specification and only uses a set of basic data types.
  40 Each platform MXBean is a {@link java.lang.management.PlatformManagedObject}
  41 with a unique
  42 {@linkplain java.lang.management.PlatformManagedObject#getObjectName name}.
  43 <h3>ManagementFactory</h3>
  44 
  45 <p>The {@link java.lang.management.ManagementFactory} class is the management
  46 factory class for the Java platform.  This class provides a set of
  47 static factory methods to obtain the MXBeans for the Java platform
  48 to allow an application to access the MXBeans directly.
  49 
  50 <p>A <em>platform MBeanServer</em> can be accessed with the
  51 {@link java.lang.management.ManagementFactory#getPlatformMBeanServer
  52  getPlatformMBeanServer} method.  On the first call to this method,
  53 it creates the platform MBeanServer and registers all platform MXBeans
  54 including {@linkplain java.lang.management.PlatformManagedObject
  55 platform MXBeans}.
  56 Each platform MXBean is registered with a unique name defined in
  57 the specification of the management interface.
  58 This is a single MBeanServer that can be shared by different managed
  59 components running within the same Java virtual machine.
  60 
  61 <h3>Interoperability</h3>
  62 
  63 <p>A management application and a platform MBeanServer of a running
  64 virtual machine can interoperate
  65 without requiring classes used by the platform MXBean interfaces.
  66 The data types being transmitted between the JMX connector
  67 server and the connector client are JMX
  68 {@linkplain javax.management.openmbean.OpenType open types} and
  69 this allows interoperation across versions.
  70 A data type used by the MXBean interfaces are mapped to an
  71 open type when being accessed via MBeanServer interface.
  72 See the <a href="{@docRoot}/java.management/javax/management/MXBean.html#MXBean-spec">
  73 MXBean</a> specification for details.
  74 
  75 <h3><a id="examples">Ways to Access MXBeans</a></h3>
  76 
  77 <p>An application can monitor the instrumentation of the
  78 Java virtual machine and the runtime in the following ways:
  79 <p>
  80 <b>1. Direct access to an MXBean interface</b>
  81 <ul>
  82 <li>Get an MXBean instance locally in the running Java virtual machine:
  83 <pre>
  84    RuntimeMXBean mxbean = ManagementFactory.getRuntimeMXBean();
  85 
  86    // Get the standard attribute "VmVendor"
  87    String vendor = mxbean.getVmVendor();
  88 </pre>
  89 <p>Or by calling the
  90         {@link java.lang.management.ManagementFactory#getPlatformMXBean(Class)
  91                getPlatformMXBean} or
  92         {@link java.lang.management.ManagementFactory#getPlatformMXBeans(Class)
  93                getPlatformMXBeans} method:
  94 <pre>
  95    RuntimeMXBean mxbean = ManagementFactory.getPlatformMXBean(RuntimeMXBean.class);


 146    // Connect to a running JVM (or itself) and get MBeanServerConnection
 147    // that has the JVM MXBeans registered in it
 148    ...
 149 
 150    try {
 151        // Assuming the RuntimeMXBean has been registered in mbs
 152        ObjectName oname = new ObjectName(ManagementFactory.RUNTIME_MXBEAN_NAME);
 153 
 154        // Get standard attribute "VmVendor"
 155        String vendor = (String) mbs.getAttribute(oname, "VmVendor");
 156    } catch (....) {
 157        // Catch the exceptions thrown by ObjectName constructor
 158        // and MBeanServer.getAttribute method
 159        ...
 160    }
 161 </pre>
 162 </li>
 163 </ul>
 164 
 165 
 166 <h3><a id="extension">Platform Extension</a></h3>
 167 
 168 <p>A Java virtual machine implementation may add its platform extension to
 169 the management interface by defining platform-dependent
 170 interfaces that extend the standard management interfaces to include
 171 platform-specific metrics and management operations.
 172 The static factory methods in the <code>ManagementFactory</code> class will
 173 return the MXBeans with the platform extension.
 174 
 175 <p>
 176 It is recommended to name the platform-specific attributes with
 177 a vendor-specific prefix such as the vendor's name to
 178 avoid collisions of the attribute name between the future extension
 179 to the standard management interface and the platform extension.
 180 If the future extension to the standard management interface defines
 181 a new attribute for a management interface and the attribute name
 182 is happened to be same as some vendor-specific attribute's name,
 183 the applications accessing that vendor-specific attribute would have
 184 to be modified to cope with versioning and compatibility issues.
 185 
 186 <p>Below is an example showing how to access an attribute


< prev index next >