src/java.management/share/classes/javax/management/package-info.java - master - githubmirror/panama-vector

src/java.management/share/classes/javax/management/package-info.java
393 строки17 KB
Nizar Benalla
8332070: Convert package.html files in `java.management` to package-info.java
06 июн 2024, 10:27
06 июн 2024, 10:27c7d2841
/*
 * 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;