mirror of
https://github.com/openjdk/jdk.git
synced 2026-03-16 10:53:31 +00:00
394 lines
17 KiB
Java
394 lines
17 KiB
Java
/*
|
|
* Copyright (c) 1999, 2024, 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.
|
|
*/
|
|
|
|
/**
|
|
* <p>Provides the core classes for the Java Management Extensions.</p>
|
|
*
|
|
* <p>The Java Management Extensions
|
|
* (JMX) API is a standard
|
|
* API for management and monitoring. Typical uses include:</p>
|
|
*
|
|
* <ul>
|
|
* <li>consulting and changing application configuration</li>
|
|
*
|
|
* <li>accumulating statistics about application behavior and
|
|
* making them available</li>
|
|
*
|
|
* <li>notifying of state changes and erroneous conditions.</li>
|
|
* </ul>
|
|
*
|
|
* <p>The JMX API can also be used as part of a solution for
|
|
* managing systems, networks, and so on.</p>
|
|
*
|
|
* <p>The API includes remote access, so a remote management
|
|
* program can interact with a running application for these
|
|
* purposes.</p>
|
|
*
|
|
* <h2>MBeans</h2>
|
|
*
|
|
* <p>The fundamental notion of the JMX API is the <em>MBean</em>.
|
|
* An MBean is a named <em>managed object</em> representing a
|
|
* resource. It has a <em id="mgIface">management interface</em>
|
|
* which must be <em>public</em> and consist of:</p>
|
|
*
|
|
* <ul>
|
|
* <li>named and typed attributes that can be read and/or
|
|
* written</li>
|
|
*
|
|
* <li>named and typed operations that can be invoked</li>
|
|
*
|
|
* <li>typed notifications that can be emitted by the MBean.</li>
|
|
* </ul>
|
|
*
|
|
* <p>For example, an MBean representing an application's
|
|
* configuration could have attributes representing the different
|
|
* configuration items. Reading the <code>CacheSize</code>
|
|
* attribute would return the current value of that item.
|
|
* Writing it would update the item, potentially changing the
|
|
* behavior of the running application. An operation such as
|
|
* <code>save</code> could store the current configuration
|
|
* persistently. A notification such as
|
|
* <code>ConfigurationChangedNotification</code> could be sent
|
|
* every time the configuration is changed.</p>
|
|
*
|
|
* <p>In the standard usage of the JMX API, MBeans are implemented
|
|
* as Java objects. However, as explained below, these objects are
|
|
* not usually referenced directly.</p>
|
|
*
|
|
*
|
|
* <h3>Standard MBeans</h3>
|
|
*
|
|
* <p>To make MBean implementation simple, the JMX API includes the
|
|
* notion of <em>Standard MBeans</em>. A Standard MBean is one
|
|
* whose attributes and operations are deduced from a Java
|
|
* interface using certain naming patterns, similar to those used
|
|
* by JavaBeans. For example, consider an interface like this:</p>
|
|
*
|
|
* <pre>
|
|
* public interface ConfigurationMBean {
|
|
* public int getCacheSize();
|
|
* public void setCacheSize(int size);
|
|
* public long getLastChangedTime();
|
|
* public void save();
|
|
* }
|
|
* </pre>
|
|
*
|
|
* <p>The methods <code>getCacheSize</code> and
|
|
* <code>setCacheSize</code> define a read-write attribute of
|
|
* type <code>int</code> called <code>CacheSize</code> (with an
|
|
* initial capital, unlike the JavaBeans convention).</p>
|
|
*
|
|
* <p>The method <code>getLastChangedTime</code> defines an
|
|
* attribute of type <code>long</code> called
|
|
* <code>LastChangedTime</code>. This is a read-only attribute,
|
|
* since there is no method <code>setLastChangedTime</code>.</p>
|
|
*
|
|
* <p>The method <code>save</code> defines an operation called
|
|
* <code>save</code>. It is not an attribute, since its name
|
|
* does not begin with <code>get</code>, <code>set</code>, or
|
|
* <code>is</code>.</p>
|
|
*
|
|
* <p>The exact naming patterns for Standard MBeans are detailed in
|
|
* the <a href="#spec">JMX Specification</a>.</p>
|
|
*
|
|
* <p>There are two ways to make a Java object that is an MBean
|
|
* with this management interface. One is for the object to be
|
|
* of a class that has exactly the same name as the Java
|
|
* interface but without the <code>MBean</code> suffix. So in
|
|
* the example the object would be of the class
|
|
* <code>Configuration</code>, in the same Java package as
|
|
* <code>ConfigurationMBean</code>. The second way is to use the
|
|
* {@link javax.management.StandardMBean StandardMBean}
|
|
* class.</p>
|
|
*
|
|
*
|
|
* <h3>MXBeans</h3>
|
|
*
|
|
* <p>An <em>MXBean</em> is a variant of Standard MBean where complex
|
|
* types are mapped to a standard set of types defined in the
|
|
* {@link javax.management.openmbean} package. MXBeans are appropriate
|
|
* if you would otherwise need to reference application-specific
|
|
* classes in your MBean interface. They are described in detail
|
|
* in the specification for {@link javax.management.MXBean MXBean}.</p>
|
|
*
|
|
*
|
|
* <h3>Dynamic MBeans</h3>
|
|
*
|
|
* <p>A <em>Dynamic MBean</em> is an MBean that defines its
|
|
* management interface at run-time. For example, a configuration
|
|
* MBean could determine the names and types of the attributes it
|
|
* exposes by parsing an XML file.</p>
|
|
*
|
|
* <p>Any Java object of a class that implements the {@link
|
|
* javax.management.DynamicMBean DynamicMBean} interface is a
|
|
* Dynamic MBean.</p>
|
|
*
|
|
*
|
|
* <h3>Open MBeans</h3>
|
|
*
|
|
* <p>An <em>Open MBean</em> is a kind of Dynamic MBean where the
|
|
* types of attributes and of operation parameters and return
|
|
* values are built using a small set of predefined Java classes.
|
|
* Open MBeans facilitate operation with remote management programs
|
|
* that do not necessarily have access to application-specific
|
|
* types, including non-Java programs. Open MBeans are defined by
|
|
* the package <a href="openmbean/package-summary.html"><code>
|
|
* javax.management.openmbean</code></a>.</p>
|
|
*
|
|
*
|
|
* <h3>Model MBeans</h3>
|
|
*
|
|
* <p>A <em>Model MBean</em> is a kind of Dynamic MBean that acts
|
|
* as a bridge between the management interface and the
|
|
* underlying managed resource. Both the management interface and
|
|
* the managed resource are specified as Java objects. The same
|
|
* Model MBean implementation can be reused many times with
|
|
* different management interfaces and managed resources, and it can
|
|
* provide common functionality such as persistence and caching.
|
|
* Model MBeans are defined by the package
|
|
* <a href="modelmbean/package-summary.html"><code>
|
|
* javax.management.modelmbean</code></a>.</p>
|
|
*
|
|
*
|
|
* <h2>MBean Server</h2>
|
|
*
|
|
* <p>To be useful, an MBean must be registered in an <em>MBean
|
|
* Server</em>. An MBean Server is a repository of MBeans.
|
|
* Usually the only access to the MBeans is through the MBean
|
|
* Server. In other words, code no longer accesses the Java
|
|
* object implementing the MBean directly, but instead accesses
|
|
* the MBean by name through the MBean Server. Each MBean has a
|
|
* unique name within the MBean Server, defined by the {@link
|
|
* javax.management.ObjectName ObjectName} class.</p>
|
|
*
|
|
* <p>An MBean Server is an object implementing the interface
|
|
* {@link javax.management.MBeanServer MBeanServer}.
|
|
* The most convenient MBean Server to use is the
|
|
* <em>Platform MBean Server</em>. This is a
|
|
* single MBean Server that can be shared by different managed
|
|
* components running within the same Java Virtual Machine. The
|
|
* Platform MBean Server is accessed with the method {@link
|
|
* java.lang.management.ManagementFactory#getPlatformMBeanServer()}.</p>
|
|
*
|
|
* <p>Application code can also create a new MBean Server, or
|
|
* access already-created MBean Servers, using the {@link
|
|
* javax.management.MBeanServerFactory MBeanServerFactory} class.</p>
|
|
*
|
|
*
|
|
* <h3>Creating MBeans in the MBean Server</h3>
|
|
*
|
|
* <p>There are two ways to create an MBean. One is to construct a
|
|
* Java object that will be the MBean, then use the {@link
|
|
* javax.management.MBeanServer#registerMBean registerMBean}
|
|
* method to register it in the MBean Server. The other is to
|
|
* create and register the MBean in a single operation using one
|
|
* of the {@link javax.management.MBeanServer#createMBean(String,
|
|
* javax.management.ObjectName) createMBean} methods.</p>
|
|
*
|
|
* <p>The <code>registerMBean</code> method is simpler for local
|
|
* use, but cannot be used remotely. The
|
|
* <code>createMBean</code> method can be used remotely, but
|
|
* sometimes requires attention to class loading issues.</p>
|
|
*
|
|
* <p>An MBean can perform actions when it is registered in or
|
|
* unregistered from an MBean Server if it implements the {@link
|
|
* javax.management.MBeanRegistration MBeanRegistration}
|
|
* interface.</p>
|
|
*
|
|
*
|
|
* <h3>Accessing MBeans in the MBean Server</h3>
|
|
*
|
|
* <p>Given an <code>ObjectName</code> <code>name</code> and an
|
|
* <code>MBeanServer</code> <code>mbs</code>, you can access
|
|
* attributes and operations as in this example:</p>
|
|
*
|
|
* <pre>
|
|
* int cacheSize = mbs.getAttribute(name, "CacheSize");
|
|
* {@link javax.management.Attribute Attribute} newCacheSize =
|
|
* new Attribute("CacheSize", new Integer(2000));
|
|
* mbs.setAttribute(name, newCacheSize);
|
|
* mbs.invoke(name, "save", new Object[0], new Class[0]);
|
|
* </pre>
|
|
*
|
|
* <p id="proxy">Alternatively, if you have a Java interface that
|
|
* corresponds to the management interface for the MBean, you can use an
|
|
* <em>MBean proxy</em> like this:</p>
|
|
*
|
|
* <pre>
|
|
* ConfigurationMBean conf =
|
|
* {@link javax.management.JMX#newMBeanProxy
|
|
* JMX.newMBeanProxy}(mbs, name, ConfigurationMBean.class);
|
|
* int cacheSize = conf.getCacheSize();
|
|
* conf.setCacheSize(2000);
|
|
* conf.save();
|
|
* </pre>
|
|
*
|
|
* <p>Using an MBean proxy is just a convenience. The second
|
|
* example ends up calling the same <code>MBeanServer</code>
|
|
* operations as the first one.</p>
|
|
*
|
|
* <p>An MBean Server can be queried for MBeans whose names match
|
|
* certain patterns and/or whose attributes meet certain
|
|
* constraints. Name patterns are constructed using the {@link
|
|
* javax.management.ObjectName ObjectName} class and constraints
|
|
* are constructed using the {@link javax.management.Query Query}
|
|
* class. The methods {@link
|
|
* javax.management.MBeanServer#queryNames queryNames} and {@link
|
|
* javax.management.MBeanServer#queryMBeans queryMBeans} then
|
|
* perform the query.</p>
|
|
*
|
|
*
|
|
* <h3>MBean lifecycle</h3>
|
|
*
|
|
* <p>An MBean can implement the {@link javax.management.MBeanRegistration
|
|
* MBeanRegistration} interface in order to be told when it is registered
|
|
* and unregistered in the MBean Server. Additionally, the {@link
|
|
* javax.management.MBeanRegistration#preRegister preRegister} method
|
|
* allows the MBean to get a reference to the <code>MBeanServer</code>
|
|
* object and to get its <code>ObjectName</code> within the MBean
|
|
* Server.</p>
|
|
*
|
|
*
|
|
* <h2>Notifications</h2>
|
|
*
|
|
* <p>A <em>notification</em> is an instance of the {@link
|
|
* javax.management.Notification Notification} class or a
|
|
* subclass. In addition to its Java class, it has a
|
|
* <em>type</em> string that can distinguish it from other
|
|
* notifications of the same class.</p>
|
|
*
|
|
* <p>An MBean that will emit notifications must implement the
|
|
* {@link javax.management.NotificationBroadcaster
|
|
* NotificationBroadcaster} or {@link
|
|
* javax.management.NotificationEmitter NotificationEmitter}
|
|
* interface. Usually, it does this by subclassing
|
|
* {@link javax.management.NotificationBroadcasterSupport
|
|
* NotificationBroadcasterSupport} or delegating to an instance of
|
|
* that class. Here is an example:</p>
|
|
*
|
|
* <pre>
|
|
* public class Configuration <b>extends NotificationBroadcasterSupport</b>
|
|
* implements ConfigurationMBean {
|
|
* ...
|
|
* private void updated() {
|
|
* Notification n = new Notification(...);
|
|
* <b>{@link javax.management.NotificationBroadcasterSupport#sendNotification
|
|
* sendNotification}(n)</b>;
|
|
* }
|
|
* }
|
|
* </pre>
|
|
*
|
|
*
|
|
* <p>Notifications can be received by a <em>listener</em>, which
|
|
* is an object that implements the {@link
|
|
* javax.management.NotificationListener NotificationListener}
|
|
* interface. You can add a listener to an MBean with the method
|
|
* {@link
|
|
* javax.management.MBeanServer#addNotificationListener(ObjectName,
|
|
* NotificationListener, NotificationFilter, Object)}.
|
|
* You can optionally supply a <em>filter</em> to this method, to
|
|
* select only notifications of interest. A filter is an object
|
|
* that implements the {@link javax.management.NotificationFilter
|
|
* NotificationFilter} interface.</p>
|
|
*
|
|
* <p>An MBean can be a listener for notifications emitted by other
|
|
* MBeans in the same MBean Server. In this case, it implements
|
|
* {@link javax.management.NotificationListener
|
|
* NotificationListener} and the method {@link
|
|
* javax.management.MBeanServer#addNotificationListener(ObjectName,
|
|
* ObjectName, NotificationFilter, Object)} is used to listen.</p>
|
|
*
|
|
*
|
|
* <h2>Remote Access to MBeans</h2>
|
|
*
|
|
* <p>An MBean Server can be accessed remotely through a
|
|
* <em>connector</em>. A connector allows a remote Java
|
|
* application to access an MBean Server in essentially the same
|
|
* way as a local one. The package
|
|
* <a href="remote/package-summary.html"><code>
|
|
* javax.management.remote</code></a> defines connectors.</p>
|
|
*
|
|
* <p>The JMX specification also defines the notion of an
|
|
* <em>adaptor</em>. An adaptor translates between requests in a
|
|
* protocol such as SNMP or HTML and accesses to an MBean Server.
|
|
* So for example an SNMP GET operation might result in a
|
|
* <code>getAttribute</code> on the MBean Server.</p>
|
|
*
|
|
* <h3 id="interop">Interoperability between versions of the JMX
|
|
* specification</h3>
|
|
*
|
|
* <p>When a client connects to a server using the JMX Remote
|
|
* API, it is possible that they do not have the same version
|
|
* of the JMX specification. The version of the JMX
|
|
* specification described here is version 1.4. Previous
|
|
* versions were 1.0, 1.1, and 1.2. (There was no 1.3.)
|
|
* The standard JMX Remote API is defined to work with version
|
|
* 1.2 onwards, so in standards-based deployment the only
|
|
* interoperability questions that arise concern version 1.2
|
|
* onwards.</p>
|
|
*
|
|
* <p>Every version of the JMX specification continues to
|
|
* implement the features of previous versions. So when the
|
|
* client is running an earlier version than the server, there
|
|
* should not be any interoperability concerns.</p>
|
|
*
|
|
* <p>When the client is running a later version than the server,
|
|
* certain newer features may not be available, as detailed in
|
|
* the next sections. The client can determine the server's
|
|
* version by examining the {@link
|
|
* javax.management.MBeanServerDelegateMBean#getSpecificationVersion
|
|
* SpecificationVersion} attribute of the {@code
|
|
* MBeanServerDelegate}.</p>
|
|
*
|
|
* <h4 id="interop-1.2">If the remote MBean Server is 1.2</h4>
|
|
*
|
|
* <ul>
|
|
*
|
|
* <li><p>You cannot use wildcards in a key property of an
|
|
* {@link javax.management.ObjectName ObjectName}, for
|
|
* example {@code domain:type=Foo,name=*}. Wildcards that
|
|
* match whole properties are still allowed, for example
|
|
* {@code *:*} or {@code *:type=Foo,*}.</p>
|
|
*
|
|
* <li><p>You cannot use {@link
|
|
* javax.management.Query#isInstanceOf Query.isInstanceOf}
|
|
* in a query.</p>
|
|
*
|
|
* <li><p>You cannot use dot syntax such as {@code
|
|
* HeapMemoryUsage.used} in the {@linkplain
|
|
* javax.management.monitor.Monitor#setObservedAttribute
|
|
* observed attribute} of a monitor, as described in the
|
|
* documentation for the {@link javax.management.monitor}
|
|
* package.</p>
|
|
*
|
|
* </ul>
|
|
*
|
|
* @see <a id="spec" href="https://jcp.org/aboutJava/communityprocess/mrel/jsr160/index2.html">
|
|
* JMX Specification, version 1.4</a>
|
|
*
|
|
* @since 1.5
|
|
*/
|
|
package javax.management;
|