infernap12/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2026-02-22 16:26:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

8332070: Convert package.html files in java.management to package-info.java

Browse Source 
Reviewed-by: alanb
This commit is contained in:
Nizar Benalla 2024-06-06 07:27:58 +00:00 committed by Jaikiran Pai
parent 7ef2831293
commit c7d2841fb4
18 changed files with 1524 additions and 1565 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

239
src/java.management/share/classes/java/lang/management/package-info.java Normal file
View File

@ -0,0 +1,239 @@
/*
* Copyright (c) 2003, 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.
*/
/**
* Provides the management interfaces for monitoring and management of the
* Java virtual machine and other components in the Java runtime.
* It allows both local and remote
* monitoring and management of the running Java virtual machine.
*
* <h2><a id="MXBean">Platform MXBean</a></h2>
* <p>
* A platform MXBean is a <i>managed bean</i> that
* conforms to the {@linkplain javax.management JMX}
* Instrumentation Specification and only uses a set of basic data types.
* Each platform MXBean is a {@link java.lang.management.PlatformManagedObject}
* with a unique
* {@linkplain java.lang.management.PlatformManagedObject#getObjectName name}.
* <h2>ManagementFactory</h2>
*
* <p>The {@link java.lang.management.ManagementFactory} class is the management
* factory class for the Java platform. This class provides a set of
* static factory methods to obtain the MXBeans for the Java platform
* to allow an application to access the MXBeans directly.
*
* <p>A <em>platform MBeanServer</em> can be accessed with the
* {@link java.lang.management.ManagementFactory#getPlatformMBeanServer
* getPlatformMBeanServer} method. On the first call to this method,
* it creates the platform MBeanServer and registers all platform MXBeans
* including {@linkplain java.lang.management.PlatformManagedObject
* platform MXBeans}.
* Each platform MXBean is registered with a unique name defined in
* the specification of the management interface.
* This is a single MBeanServer that can be shared by different managed
* components running within the same Java virtual machine.
*
* <h2>Interoperability</h2>
*
* <p>A management application and a platform MBeanServer of a running
* virtual machine can interoperate
* without requiring classes used by the platform MXBean interfaces.
* The data types being transmitted between the JMX connector
* server and the connector client are JMX
* {@linkplain javax.management.openmbean.OpenType open types} and
* this allows interoperation across versions.
* A data type used by the MXBean interfaces are mapped to an
* open type when being accessed via MBeanServer interface.
* See the <a href="{@docRoot}/java.management/javax/management/MXBean.html#MXBean-spec">
* MXBean</a> specification for details.
*
* <h2><a id="examples">Ways to Access MXBeans</a></h2>
*
* <p>An application can monitor the instrumentation of the
* Java virtual machine and the runtime in the following ways:
* <p>
* <b>1. Direct access to an MXBean interface</b>
* <ul>
* <li>Get an MXBean instance locally in the running Java virtual machine:
* <pre>
* RuntimeMXBean mxbean = ManagementFactory.getRuntimeMXBean();
*
* // Get the standard attribute "VmVendor"
* String vendor = mxbean.getVmVendor();
* </pre>
* <p>Or by calling the
* {@link java.lang.management.ManagementFactory#getPlatformMXBean(Class)
* getPlatformMXBean} or
* {@link java.lang.management.ManagementFactory#getPlatformMXBeans(Class)
* getPlatformMXBeans} method:
* <pre>
* RuntimeMXBean mxbean = ManagementFactory.getPlatformMXBean(RuntimeMXBean.class);
*
* // Get the standard attribute "VmVendor"
* String vendor = mxbean.getVmVendor();
* </pre>
* </li>
* <li>Construct an MXBean proxy instance that forwards the
* method calls to a given MBeanServer:
* <pre>
* MBeanServerConnection mbs;
*
* // Connect to a running JVM (or itself) and get MBeanServerConnection
* // that has the JVM MBeans registered in it
* ...
*
* // Get a MBean proxy for RuntimeMXBean interface
* RuntimeMXBean proxy =
* {@link java.lang.management.ManagementFactory#getPlatformMXBean(MBeanServerConnection, Class)
* ManagementFactory.getPlatformMXBean}(mbs,
* RuntimeMXBean.class);
* // Get standard attribute "VmVendor"
* String vendor = proxy.getVmVendor();
* </pre>
* <p>A proxy is typically used to access an MXBean
* in a remote Java virtual machine.
* An alternative way to create an MXBean proxy is:
* <pre>
* RuntimeMXBean proxy =
* {@link java.lang.management.ManagementFactory#newPlatformMXBeanProxy
* ManagementFactory.newPlatformMXBeanProxy}(mbs,
* ManagementFactory.RUNTIME_MXBEAN_NAME,
* RuntimeMXBean.class);
* </pre>
* </li>
* </ul>
* <p>
* <b>2. Indirect access to an MXBean interface via MBeanServer</b>
* <ul>
* <li>Go through the
* {@link java.lang.management.ManagementFactory#getPlatformMBeanServer
* platform MBeanServer} to access MXBeans locally or
* a specific {@code MBeanServerConnection} to access
* MXBeans remotely.
* The attributes and operations of an MXBean use only
* <em>JMX open types</em> which include basic data types,
* {@link javax.management.openmbean.CompositeData CompositeData},
* and {@link javax.management.openmbean.TabularData TabularData}
* defined in {@link javax.management.openmbean.OpenType OpenType}.
* <pre>
* MBeanServerConnection mbs;
*
* // Connect to a running JVM (or itself) and get MBeanServerConnection
* // that has the JVM MXBeans registered in it
* ...
*
* try {
* // Assuming the RuntimeMXBean has been registered in mbs
* ObjectName oname = new ObjectName(ManagementFactory.RUNTIME_MXBEAN_NAME);
*
* // Get standard attribute "VmVendor"
* String vendor = (String) mbs.getAttribute(oname, "VmVendor");
* } catch (....) {
* // Catch the exceptions thrown by ObjectName constructor
* // and MBeanServer.getAttribute method
* ...
* }
* </pre>
* </li>
* </ul>
*
*
* <h2><a id="extension">Platform Extension</a></h2>
*
* <p>A Java virtual machine implementation may add its platform extension to
* the management interface by defining platform-dependent
* interfaces that extend the standard management interfaces to include
* platform-specific metrics and management operations.
* The static factory methods in the <code>ManagementFactory</code> class will
* return the MXBeans with the platform extension.
*
* <p>
* It is recommended to name the platform-specific attributes with
* a vendor-specific prefix such as the vendor's name to
* avoid collisions of the attribute name between the future extension
* to the standard management interface and the platform extension.
* If the future extension to the standard management interface defines
* a new attribute for a management interface and the attribute name
* is happened to be same as some vendor-specific attribute's name,
* the applications accessing that vendor-specific attribute would have
* to be modified to cope with versioning and compatibility issues.
*
* <p>Below is an example showing how to access an attribute
* from the platform extension:
*
* <p>
* 1) Direct access to the Oracle-specific MXBean interface
* <blockquote>
* <pre>
* List&lt;com.sun.management.GarbageCollectorMXBean&gt; mxbeans =
* ManagementFactory.getPlatformMXBeans(com.sun.management.GarbageCollectorMXBean.class);
*
* for (com.sun.management.GarbageCollectorMXBean gc : mxbeans) {
* // Get the standard attribute "CollectionCount"
* String count = mxbean.getCollectionCount();
*
* // Get the platform-specific attribute "LastGcInfo"
* GcInfo gcinfo = gc.getLastGcInfo();
* ...
* }
* </pre>
* </blockquote>
*
* <p>
* 2) Access the Oracle-specific MXBean interface via <code>MBeanServer</code>
* through proxy
*
* <blockquote><pre>
* MBeanServerConnection mbs;
*
* // Connect to a running JVM (or itself) and get MBeanServerConnection
* // that has the JVM MXBeans registered in it
* ...
*
* List&lt;com.sun.management.GarbageCollectorMXBean&gt; mxbeans =
* ManagementFactory.getPlatformMXBeans(mbs, com.sun.management.GarbageCollectorMXBean.class);
*
* for (com.sun.management.GarbageCollectorMXBean gc : mxbeans) {
* // Get the standard attribute "CollectionCount"
* String count = mxbean.getCollectionCount();
*
* // Get the platform-specific attribute "LastGcInfo"
* GcInfo gcinfo = gc.getLastGcInfo();
* ...
* }
* </pre></blockquote>
*
* <p> Unless otherwise noted, passing a <code>null</code> argument to a constructor
* or method in any class or interface in this package will cause a {@link
* java.lang.NullPointerException NullPointerException} to be thrown.
*
* <p> The java.lang.management API is thread-safe.
*
* @see javax.management JMX Specification
*
* @author Mandy Chung
* @since 1.5
*/
package java.lang.management;

243
src/java.management/share/classes/java/lang/management/package.html
View File

@ -1,243 +0,0 @@
<!--
Copyright (c) 2003, 2019, 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.
-->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<body bgcolor="white">
Provides the management interfaces for monitoring and management of the
Java virtual machine and other components in the Java runtime.
It allows both local and remote
monitoring and management of the running Java virtual machine.
<h2><a id="MXBean">Platform MXBean</a></h2>
<p>
A platform MXBean is a <i>managed bean</i> that
conforms to the {@linkplain javax.management JMX}
Instrumentation Specification and only uses a set of basic data types.
Each platform MXBean is a {@link java.lang.management.PlatformManagedObject}
with a unique
{@linkplain java.lang.management.PlatformManagedObject#getObjectName name}.
<h2>ManagementFactory</h2>
<p>The {@link java.lang.management.ManagementFactory} class is the management
factory class for the Java platform. This class provides a set of
static factory methods to obtain the MXBeans for the Java platform
to allow an application to access the MXBeans directly.
<p>A <em>platform MBeanServer</em> can be accessed with the
{@link java.lang.management.ManagementFactory#getPlatformMBeanServer
getPlatformMBeanServer} method. On the first call to this method,
it creates the platform MBeanServer and registers all platform MXBeans
including {@linkplain java.lang.management.PlatformManagedObject
platform MXBeans}.
Each platform MXBean is registered with a unique name defined in
the specification of the management interface.
This is a single MBeanServer that can be shared by different managed
components running within the same Java virtual machine.
<h2>Interoperability</h2>
<p>A management application and a platform MBeanServer of a running
virtual machine can interoperate
without requiring classes used by the platform MXBean interfaces.
The data types being transmitted between the JMX connector
server and the connector client are JMX
{@linkplain javax.management.openmbean.OpenType open types} and
this allows interoperation across versions.
A data type used by the MXBean interfaces are mapped to an
open type when being accessed via MBeanServer interface.
See the <a href="{@docRoot}/java.management/javax/management/MXBean.html#MXBean-spec">
MXBean</a> specification for details.
<h2><a id="examples">Ways to Access MXBeans</a></h2>
<p>An application can monitor the instrumentation of the
Java virtual machine and the runtime in the following ways:
<p>
<b>1. Direct access to an MXBean interface</b>
<ul>
<li>Get an MXBean instance locally in the running Java virtual machine:
<pre>
RuntimeMXBean mxbean = ManagementFactory.getRuntimeMXBean();
// Get the standard attribute "VmVendor"
String vendor = mxbean.getVmVendor();
</pre>
<p>Or by calling the
{@link java.lang.management.ManagementFactory#getPlatformMXBean(Class)
getPlatformMXBean} or
{@link java.lang.management.ManagementFactory#getPlatformMXBeans(Class)
getPlatformMXBeans} method:
<pre>
RuntimeMXBean mxbean = ManagementFactory.getPlatformMXBean(RuntimeMXBean.class);
// Get the standard attribute "VmVendor"
String vendor = mxbean.getVmVendor();
</pre>
</li>
<li>Construct an MXBean proxy instance that forwards the
method calls to a given MBeanServer:
<pre>
MBeanServerConnection mbs;
// Connect to a running JVM (or itself) and get MBeanServerConnection
// that has the JVM MBeans registered in it
...
// Get a MBean proxy for RuntimeMXBean interface
RuntimeMXBean proxy =
{@link java.lang.management.ManagementFactory#getPlatformMXBean(MBeanServerConnection, Class)
ManagementFactory.getPlatformMXBean}(mbs,
RuntimeMXBean.class);
// Get standard attribute "VmVendor"
String vendor = proxy.getVmVendor();
</pre>
<p>A proxy is typically used to access an MXBean
in a remote Java virtual machine.
An alternative way to create an MXBean proxy is:
<pre>
RuntimeMXBean proxy =
{@link java.lang.management.ManagementFactory#newPlatformMXBeanProxy
ManagementFactory.newPlatformMXBeanProxy}(mbs,
ManagementFactory.RUNTIME_MXBEAN_NAME,
RuntimeMXBean.class);
</pre>
</li>
</ul>
<p>
<b>2. Indirect access to an MXBean interface via MBeanServer</b>
<ul>
<li>Go through the
{@link java.lang.management.ManagementFactory#getPlatformMBeanServer
platform MBeanServer} to access MXBeans locally or
a specific {@code MBeanServerConnection} to access
MXBeans remotely.
The attributes and operations of an MXBean use only
<em>JMX open types</em> which include basic data types,
{@link javax.management.openmbean.CompositeData CompositeData},
and {@link javax.management.openmbean.TabularData TabularData}
defined in {@link javax.management.openmbean.OpenType OpenType}.
<pre>
MBeanServerConnection mbs;
// Connect to a running JVM (or itself) and get MBeanServerConnection
// that has the JVM MXBeans registered in it
...
try {
// Assuming the RuntimeMXBean has been registered in mbs
ObjectName oname = new ObjectName(ManagementFactory.RUNTIME_MXBEAN_NAME);
// Get standard attribute "VmVendor"
String vendor = (String) mbs.getAttribute(oname, "VmVendor");
} catch (....) {
// Catch the exceptions thrown by ObjectName constructor
// and MBeanServer.getAttribute method
...
}
</pre>
</li>
</ul>
<h2><a id="extension">Platform Extension</a></h2>
<p>A Java virtual machine implementation may add its platform extension to
the management interface by defining platform-dependent
interfaces that extend the standard management interfaces to include
platform-specific metrics and management operations.
The static factory methods in the <code>ManagementFactory</code> class will
return the MXBeans with the platform extension.
<p>
It is recommended to name the platform-specific attributes with
a vendor-specific prefix such as the vendor's name to
avoid collisions of the attribute name between the future extension
to the standard management interface and the platform extension.
If the future extension to the standard management interface defines
a new attribute for a management interface and the attribute name
is happened to be same as some vendor-specific attribute's name,
the applications accessing that vendor-specific attribute would have
to be modified to cope with versioning and compatibility issues.
<p>Below is an example showing how to access an attribute
from the platform extension:
<p>
1) Direct access to the Oracle-specific MXBean interface
<blockquote>
<pre>
List&lt;com.sun.management.GarbageCollectorMXBean&gt; mxbeans =
ManagementFactory.getPlatformMXBeans(com.sun.management.GarbageCollectorMXBean.class);
for (com.sun.management.GarbageCollectorMXBean gc : mxbeans) {
// Get the standard attribute "CollectionCount"
String count = mxbean.getCollectionCount();
// Get the platform-specific attribute "LastGcInfo"
GcInfo gcinfo = gc.getLastGcInfo();
...
}
</pre>
</blockquote>
<p>
2) Access the Oracle-specific MXBean interface via <code>MBeanServer</code>
through proxy
<blockquote><pre>
MBeanServerConnection mbs;
// Connect to a running JVM (or itself) and get MBeanServerConnection
// that has the JVM MXBeans registered in it
...
List&lt;com.sun.management.GarbageCollectorMXBean&gt; mxbeans =
ManagementFactory.getPlatformMXBeans(mbs, com.sun.management.GarbageCollectorMXBean.class);
for (com.sun.management.GarbageCollectorMXBean gc : mxbeans) {
// Get the standard attribute "CollectionCount"
String count = mxbean.getCollectionCount();
// Get the platform-specific attribute "LastGcInfo"
GcInfo gcinfo = gc.getLastGcInfo();
...
}
</pre></blockquote>
<p> Unless otherwise noted, passing a <code>null</code> argument to a constructor
or method in any class or interface in this package will cause a {@link
java.lang.NullPointerException NullPointerException} to be thrown.
<p> The java.lang.management API is thread-safe.
@see javax.management JMX Specification
@author Mandy Chung
@since 1.5
</body>
</html>

57
src/java.management/share/classes/javax/management/loading/package-info.java Normal file
View File

@ -0,0 +1,57 @@
/*
* 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 classes which implement advanced dynamic
* loading. See the chapter <em>Advanced Dynamic Loading</em> in
* the <a href="#spec">JMX Specification</a>.</p>
*
* <p>An MBean that is of a subclass of {@link
* java.lang.ClassLoader} can be used as a class loader to create
* other MBeans via the method {@link
* javax.management.MBeanServer#createMBean(String, ObjectName,
* ObjectName, Object[], String[])}, and to instantiate arbitrary
* objects via the method {@link
* javax.management.MBeanServer#instantiate(String, ObjectName,
* Object[], String[])}.</p>
*
* <p>Every MBean Server has a <em>class loader repository</em>
* containing all MBeans registered in that MBean Server that
* are of a subclass of {@link java.lang.ClassLoader}. The class
* loader repository is used by the forms of the
* <code>createMBean</code> and <code>instantiate</code> methods
* in the {@link javax.management.MBeanServer MBeanServer}
* interface that do not have an explicit loader parameter.</p>
*
* <p>If an MBean implements the interface {@link
* javax.management.loading.PrivateClassLoader PrivateClassLoader},
* then it is not added to the class loader repository.</p>
*
* @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.loading;

61
src/java.management/share/classes/javax/management/loading/package.html
View File

@ -1,61 +0,0 @@
<html>
<head>
<title>javax.management.loading package</title>
<!--
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.
-->
</head>
<body bgcolor="white">
<p>Provides the classes which implement advanced dynamic
loading. See the chapter <em>Advanced Dynamic Loading</em> in
the <a href="#spec">JMX Specification</a>.</p>
<p>An MBean that is of a subclass of {@link
java.lang.ClassLoader} can be used as a class loader to create
other MBeans via the method {@link
javax.management.MBeanServer#createMBean(String, ObjectName,
ObjectName, Object[], String[])}, and to instantiate arbitrary
objects via the method {@link
javax.management.MBeanServer#instantiate(String, ObjectName,
Object[], String[])}.</p>
<p>Every MBean Server has a <em>class loader repository</em>
containing all MBeans registered in that MBean Server that
are of a subclass of {@link java.lang.ClassLoader}. The class
loader repository is used by the forms of the
<code>createMBean</code> and <code>instantiate</code> methods
in the {@link javax.management.MBeanServer MBeanServer}
interface that do not have an explicit loader parameter.</p>
<p>If an MBean implements the interface {@link
javax.management.loading.PrivateClassLoader PrivateClassLoader},
then it is not added to the class loader repository.</p>
@see <a id="spec" href="https://jcp.org/aboutJava/communityprocess/mrel/jsr160/index2.html">
JMX Specification, version 1.4</a>
@since 1.5
</BODY>
</HTML>

120
src/java.management/share/classes/javax/management/modelmbean/package-info.java Normal file
View File

@ -0,0 +1,120 @@
/*
* Copyright (c) 2000, 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 definition of the ModelMBean classes. A Model
* MBean is an 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.</p>
*
* <p>A Model MBean implements the {@link
* javax.management.modelmbean.ModelMBean ModelMBean} interface.
* It is a {@link javax.management.DynamicMBean DynamicMBean}
* whose {@link javax.management.DynamicMBean#getMBeanInfo()
* getMBeanInfo} method returns an object implementing {@link
* javax.management.modelmbean.ModelMBeanInfo
* ModelMBeanInfo}.</p>
*
* <p>Every MBean has an {@link javax.management.MBeanInfo
* MBeanInfo} with information about the MBean itself, and its
* attributes, operations, constructors, and notifications. A
* Model MBean augments this <code>MBeanInfo</code> with {@link
* javax.management.Descriptor Descriptor}s that encode
* additional information in the form of (key,value) pairs.
* Usually, <code>Descriptor</code>s are instances of {@link
* javax.management.modelmbean.DescriptorSupport
* DescriptorSupport}.</p>
*
* <p>The class {@link
* javax.management.modelmbean.RequiredModelMBean
* RequiredModelMBean} provides a standard Model MBean
* implementation.</p>
*
* <p>The following example shows a Model MBean being used to make
* the <code>get</code> method of a <code>HashMap</code>
* available for management through an MBean server. No other
* methods are available through the MBean server. There is
* nothing special about <code>HashMap</code> here. Public
* methods from any public class can be exposed for management in
* the same way.</p>
*
* <pre>
* import java.lang.reflect.Method;
* import java.util.HashMap;
* import javax.management.*;
* import javax.management.modelmbean.*;
*
* // ...
*
* MBeanServer mbs = MBeanServerFactory.createMBeanServer();
* // The MBean Server
*
* HashMap map = new HashMap();
* // The resource that will be managed
*
* // Construct the management interface for the Model MBean
* Method getMethod = HashMap.class.getMethod("get", new Class[] {Object.class});
* ModelMBeanOperationInfo getInfo =
* new ModelMBeanOperationInfo("Get value for key", getMethod);
* ModelMBeanInfo mmbi =
* new ModelMBeanInfoSupport(HashMap.class.getName(),
* "Map of keys and values",
* null, // no attributes
* null, // no constructors
* new ModelMBeanOperationInfo[] {getInfo},
* null); // no notifications
*
* // Make the Model MBean and link it to the resource
* ModelMBean mmb = new RequiredModelMBean(mmbi);
* mmb.setManagedResource(map, "ObjectReference");
*
* // Register the Model MBean in the MBean Server
* ObjectName mapName = new ObjectName(":type=Map,name=whatever");
* mbs.registerMBean(mmb, mapName);
*
* // Resource can evolve independently of the MBean
* map.put("key", "value");
*
* // Can access the "get" method through the MBean Server
* mbs.invoke(mapName, "get", new Object[] {"key"}, new String[] {Object.class.getName()});
* // returns "value"
* </pre>
*
* <h2><a id="spec">Package Specification</a></h2>
*
* <ul>
* <li>See the <i>JMX 1.4 Specification</i>
* <a href="https://jcp.org/aboutJava/communityprocess/mrel/jsr160/index2.html">
* JMX Specification, version 1.4</a>
* </ul>
*
* @since 1.5
*/
package javax.management.modelmbean;

124
src/java.management/share/classes/javax/management/modelmbean/package.html
View File

@ -1,124 +0,0 @@
<html>
<head>
<title>javax.management.modelmbean package</title>
<!--
Copyright (c) 2000, 2017, 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.
-->
</head>
<body bgcolor="white">
<p>Provides the definition of the ModelMBean classes. A Model
MBean is an 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.</p>
<p>A Model MBean implements the {@link
javax.management.modelmbean.ModelMBean ModelMBean} interface.
It is a {@link javax.management.DynamicMBean DynamicMBean}
whose {@link javax.management.DynamicMBean#getMBeanInfo()
getMBeanInfo} method returns an object implementing {@link
javax.management.modelmbean.ModelMBeanInfo
ModelMBeanInfo}.</p>
<p>Every MBean has an {@link javax.management.MBeanInfo
MBeanInfo} with information about the MBean itself, and its
attributes, operations, constructors, and notifications. A
Model MBean augments this <code>MBeanInfo</code> with {@link
javax.management.Descriptor Descriptor}s that encode
additional information in the form of (key,value) pairs.
Usually, <code>Descriptor</code>s are instances of {@link
javax.management.modelmbean.DescriptorSupport
DescriptorSupport}.</p>
<p>The class {@link
javax.management.modelmbean.RequiredModelMBean
RequiredModelMBean} provides a standard Model MBean
implementation.</p>
<p>The following example shows a Model MBean being used to make
the <code>get</code> method of a <code>HashMap</code>
available for management through an MBean server. No other
methods are available through the MBean server. There is
nothing special about <code>HashMap</code> here. Public
methods from any public class can be exposed for management in
the same way.</p>
<pre>
import java.lang.reflect.Method;
import java.util.HashMap;
import javax.management.*;
import javax.management.modelmbean.*;
// ...
MBeanServer mbs = MBeanServerFactory.createMBeanServer();
// The MBean Server
HashMap map = new HashMap();
// The resource that will be managed
// Construct the management interface for the Model MBean
Method getMethod = HashMap.class.getMethod("get", new Class[] {Object.class});
ModelMBeanOperationInfo getInfo =
new ModelMBeanOperationInfo("Get value for key", getMethod);
ModelMBeanInfo mmbi =
new ModelMBeanInfoSupport(HashMap.class.getName(),
"Map of keys and values",
null, // no attributes
null, // no constructors
new ModelMBeanOperationInfo[] {getInfo},
null); // no notifications
// Make the Model MBean and link it to the resource
ModelMBean mmb = new RequiredModelMBean(mmbi);
mmb.setManagedResource(map, "ObjectReference");
// Register the Model MBean in the MBean Server
ObjectName mapName = new ObjectName(":type=Map,name=whatever");
mbs.registerMBean(mmb, mapName);
// Resource can evolve independently of the MBean
map.put("key", "value");
// Can access the "get" method through the MBean Server
mbs.invoke(mapName, "get", new Object[] {"key"}, new String[] {Object.class.getName()});
// returns "value"
</pre>
<h2><a id="spec">Package Specification</a></h2>
<ul>
<li>See the <i>JMX 1.4 Specification</i>
<a href="https://jcp.org/aboutJava/communityprocess/mrel/jsr160/index2.html">
JMX Specification, version 1.4</a>
</ul>
@since 1.5
</BODY>
</HTML>

187
src/java.management/share/classes/javax/management/monitor/package-info.java Normal file
View File

@ -0,0 +1,187 @@
/*
* 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 definition of the monitor classes. A Monitor is
* an MBean that periodically observes the value of an attribute in
* one or more other MBeans. If the attribute meets a certain
* condition, the Monitor emits a {@link
* javax.management.monitor.MonitorNotification
* MonitorNotification}. When the monitor MBean periodically calls
* {@link javax.management.MBeanServer#getAttribute getAttribute}
* to retrieve the value of the attribute being monitored it does
* so within the access control context of the
* {@link javax.management.monitor.Monitor#start} caller.</p>
*
* <p id="complex">The value being monitored can be a simple value
* contained within a complex type. For example, the {@link
* java.lang.management.MemoryMXBean MemoryMXBean} defined in
* {@code java.lang.management} has an attribute
* {@code HeapMemoryUsage} of type {@link
* java.lang.management.MemoryUsage MemoryUsage}. To monitor the
* amount of <i>used</i> memory, described by the {@code used}
* property of {@code MemoryUsage}, you could monitor
* "{@code HeapMemoryUsage.used}". That string would be the
* argument to {@link
* javax.management.monitor.MonitorMBean#setObservedAttribute(String)
* setObservedAttribute}.</p>
*
* <p>The rules used to interpret an {@code ObservedAttribute} like
* {@code "HeapMemoryUsage.used"} are as follows. Suppose the string is
* <i>A.e</i> (so <i>A</i> would be {@code "HeapMemoryUsage"} and <i>e</i>
* would be {@code "used"} in the example).</p>
*
* <p>First the value of the attribute <i>A</i> is obtained. Call it
* <i>v</i>. A value <i>x</i> is extracted from <i>v</i> as follows:</p>
*
* <ul>
*
* <li>If <i>v</i> is a {@link javax.management.openmbean.CompositeData
* CompositeData} and if <i>v</i>.{@link
* javax.management.openmbean.CompositeData#get(String) get}(<i>e</i>)
* returns a value then <i>x</i> is that value.</li>
* <li>If <i>v</i> is an array and <i>e</i> is the string {@code "length"}
* then <i>x</i> is the length of the array.</li>
*
* <li>If the above rules do not produce a value, and if introspection, as
* if by calling <a href="{@docRoot}/java.desktop/java/beans/Introspector.html#getBeanInfo(java.lang.Class)">Introspector.getBeanInfo</a>
* , for the class of <i>v</i>
* (<i>v</i>.{@code getClass()}) identifies a property with the name
* <i>e</i>, then <i>x</i> is the result of reading the property value. </li>
*
* </ul>
*
* <p>The third rule means for example that if the attribute
* {@code HeapMemoryUsage} is a {@code MemoryUsage}, monitoring
* {@code "HeapMemoryUsage.used"} will obtain the observed value by
* calling {@code MemoryUsage.getUsed()}.</p>
*
* <p>If the {@code ObservedAttribute} contains more than one period,
* for example {@code "ConnectionPool.connectionStats.length"}, then the
* above rules are applied iteratively. Here, <i>v</i> would initially be
* the value of the attribute {@code ConnectionPool}, and <i>x</i> would
* be derived by applying the above rules with <i>e</i> equal to
* {@code "connectionStats"}. Then <i>v</i> would be set to this <i>x</i>
* and a new <i>x</i> derived by applying the rules again with <i>e</i>
* equal to {@code "length"}.</p>
*
* <p>Although it is recommended that attribute names be valid Java
* identifiers, it is possible for an attribute to be called
* {@code HeapMemoryUsage.used}. This means that an
* {@code ObservedAttribute} that is {@code HeapMemoryUsage.used}
* could mean that the value to observe is either an attribute of that
* name, or the property {@code used} within an attribute called
* {@code HeapMemoryUsage}. So for compatibility reasons, when the
* {@code ObservedAttribute} contains a period ({@code .}), the monitor
* will check whether an attribute exists whose name is the full
* {@code ObservedAttribute} string ({@code HeapMemoryUsage.used} in the
* example). It does this by calling {@link
* javax.management.MBeanServer#getMBeanInfo(javax.management.ObjectName)
* getMBeanInfo} for the observed MBean and looking for a contained {@link
* javax.management.MBeanAttributeInfo MBeanAttributeInfo} with the given
* name. If one is found, then that is what is monitored. If more than one
* MBean is being observed, the behavior is unspecified if some of them have
* a {@code HeapMemoryUsage.used} attribute and others do not. An
* implementation may therefore call {@code getMBeanInfo} on just one of
* the MBeans in this case. The behavior is also unspecified if the result
* of the check changes while the monitor is active.</p>
*
* <p>The exact behavior of monitors is detailed in the
* <a href="#spec">JMX Specification</a>. What follows is a
* summary.</p>
*
* <p>There are three kinds of Monitors:</p>
*
* <ul>
* <li>
*
* <p>A {@link javax.management.monitor.CounterMonitor
* CounterMonitor} observes attributes of integer
* type. The attributes are assumed to be non-negative, and
* monotonically increasing except for a possible
* <em>roll-over</em> at a specified <em>modulus</em>. Each
* observed attribute has an associated <em>threshold</em>
* value. A notification is sent when the attribute exceeds
* its threshold.</p>
*
* <p>An <em>offset</em> value can be specified. When an
* observed value exceeds its threshold, the threshold is
* incremented by the offset, or by a multiple of the offset
* sufficient to make the threshold greater than the new
* observed value.</p>
*
* <p>A <code>CounterMonitor</code> can operate in
* <em>difference mode</em>. In this mode, the value
* compared against the threshold is the difference between
* two successive observations of an attribute.</p>
*
* </li>
* <li>
*
* <p>A {@link javax.management.monitor.GaugeMonitor
* GaugeMonitor} observes attributes of numerical type. Each
* observed attribute has an associated <em>high
* threshold</em> and <em>low threshold</em>.</p>
*
* <p>When an observed attribute crosses the high threshold, if
* the <em>notify high</em> flag is true, then a notification
* is sent. Subsequent crossings of the high threshold value
* will not trigger further notifications until the gauge value
* becomes less than or equal to the low threshold.</p>
*
* <p>When an observed attribute crosses the low threshold, if
* the <em>notify low</em> flag is true, then a notification
* is sent. Subsequent crossings of the low threshold value
* will not trigger further notifications until the gauge
* value becomes greater than or equal to the high
* threshold.</p>
*
* <p>Typically, only one of the notify high and notify low
* flags is set. The other threshold is used to provide a
* <em>hysteresis</em> mechanism to avoid the repeated
* triggering of notifications when an attribute makes small
* oscillations around the threshold value.</p>
*
* <p>A <code>GaugeMonitor</code> can operate in <em>difference
* mode</em>. In this mode, the value compared against the
* high and low thresholds is the difference between two
* successive observations of an attribute.</p>
*
* </li>
* <li>
*
* <p>A {@link javax.management.monitor.StringMonitor
* StringMonitor} observes attributes of type
* <code>String</code>. A notification is sent when an
* observed attribute becomes equal and/or not equal to a
* given string.</p>
*
* </li>
* </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.monitor;

191
src/java.management/share/classes/javax/management/monitor/package.html
View File

@ -1,191 +0,0 @@
<html>
<head>
<title>javax.management.monitor package</title>
<!--
Copyright (c) 1999, 2017, 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.
-->
</head>
<body bgcolor="white">
<p>Provides the definition of the monitor classes. A Monitor is
an MBean that periodically observes the value of an attribute in
one or more other MBeans. If the attribute meets a certain
condition, the Monitor emits a {@link
javax.management.monitor.MonitorNotification
MonitorNotification}. When the monitor MBean periodically calls
{@link javax.management.MBeanServer#getAttribute getAttribute}
to retrieve the value of the attribute being monitored it does
so within the access control context of the
{@link javax.management.monitor.Monitor#start} caller.</p>
<p id="complex">The value being monitored can be a simple value
contained within a complex type. For example, the {@link
java.lang.management.MemoryMXBean MemoryMXBean} defined in
{@code java.lang.management} has an attribute
{@code HeapMemoryUsage} of type {@link
java.lang.management.MemoryUsage MemoryUsage}. To monitor the
amount of <i>used</i> memory, described by the {@code used}
property of {@code MemoryUsage}, you could monitor
"{@code HeapMemoryUsage.used}". That string would be the
argument to {@link
javax.management.monitor.MonitorMBean#setObservedAttribute(String)
setObservedAttribute}.</p>
<p>The rules used to interpret an {@code ObservedAttribute} like
{@code "HeapMemoryUsage.used"} are as follows. Suppose the string is
<i>A.e</i> (so <i>A</i> would be {@code "HeapMemoryUsage"} and <i>e</i>
would be {@code "used"} in the example).</p>
<p>First the value of the attribute <i>A</i> is obtained. Call it
<i>v</i>. A value <i>x</i> is extracted from <i>v</i> as follows:</p>
<ul>
<li>If <i>v</i> is a {@link javax.management.openmbean.CompositeData
CompositeData} and if <i>v</i>.{@link
javax.management.openmbean.CompositeData#get(String) get}(<i>e</i>)
returns a value then <i>x</i> is that value.</li>
<li>If <i>v</i> is an array and <i>e</i> is the string {@code "length"}
then <i>x</i> is the length of the array.</li>
<li>If the above rules do not produce a value, and if introspection, as
if by calling {@link java.beans.Introspector#getBeanInfo(Class)
Introspector.getBeanInfo}, for the class of <i>v</i>
(<i>v</i>.{@code getClass()}) identifies a property with the name
<i>e</i>, then <i>x</i> is the result of reading the property value. </li>
</ul>
<p>The third rule means for example that if the attribute
{@code HeapMemoryUsage} is a {@code MemoryUsage}, monitoring
{@code "HeapMemoryUsage.used"} will obtain the observed value by
calling {@code MemoryUsage.getUsed()}.</p>
<p>If the {@code ObservedAttribute} contains more than one period,
for example {@code "ConnectionPool.connectionStats.length"}, then the
above rules are applied iteratively. Here, <i>v</i> would initially be
the value of the attribute {@code ConnectionPool}, and <i>x</i> would
be derived by applying the above rules with <i>e</i> equal to
{@code "connectionStats"}. Then <i>v</i> would be set to this <i>x</i>
and a new <i>x</i> derived by applying the rules again with <i>e</i>
equal to {@code "length"}.</p>
<p>Although it is recommended that attribute names be valid Java
identifiers, it is possible for an attribute to be called
{@code HeapMemoryUsage.used}. This means that an
{@code ObservedAttribute} that is {@code HeapMemoryUsage.used}
could mean that the value to observe is either an attribute of that
name, or the property {@code used} within an attribute called
{@code HeapMemoryUsage}. So for compatibility reasons, when the
{@code ObservedAttribute} contains a period ({@code .}), the monitor
will check whether an attribute exists whose name is the full
{@code ObservedAttribute} string ({@code HeapMemoryUsage.used} in the
example). It does this by calling {@link
javax.management.MBeanServer#getMBeanInfo(javax.management.ObjectName)
getMBeanInfo} for the observed MBean and looking for a contained {@link
javax.management.MBeanAttributeInfo MBeanAttributeInfo} with the given
name. If one is found, then that is what is monitored. If more than one
MBean is being observed, the behavior is unspecified if some of them have
a {@code HeapMemoryUsage.used} attribute and others do not. An
implementation may therefore call {@code getMBeanInfo} on just one of
the MBeans in this case. The behavior is also unspecified if the result
of the check changes while the monitor is active.</p>
<p>The exact behavior of monitors is detailed in the
<a href="#spec">JMX Specification</a>. What follows is a
summary.</p>
<p>There are three kinds of Monitors:</p>
<ul>
<li>
<p>A {@link javax.management.monitor.CounterMonitor
CounterMonitor} observes attributes of integer
type. The attributes are assumed to be non-negative, and
monotonically increasing except for a possible
<em>roll-over</em> at a specified <em>modulus</em>. Each
observed attribute has an associated <em>threshold</em>
value. A notification is sent when the attribute exceeds
its threshold.</p>
<p>An <em>offset</em> value can be specified. When an
observed value exceeds its threshold, the threshold is
incremented by the offset, or by a multiple of the offset
sufficient to make the threshold greater than the new
observed value.</p>
<p>A <code>CounterMonitor</code> can operate in
<em>difference mode</em>. In this mode, the value
compared against the threshold is the difference between
two successive observations of an attribute.</p>
</li>
<li>
<p>A {@link javax.management.monitor.GaugeMonitor
GaugeMonitor} observes attributes of numerical type. Each
observed attribute has an associated <em>high
threshold</em> and <em>low threshold</em>.</p>
<p>When an observed attribute crosses the high threshold, if
the <em>notify high</em> flag is true, then a notification
is sent. Subsequent crossings of the high threshold value
will not trigger further notifications until the gauge value
becomes less than or equal to the low threshold.</p>
<p>When an observed attribute crosses the low threshold, if
the <em>notify low</em> flag is true, then a notification
is sent. Subsequent crossings of the low threshold value
will not trigger further notifications until the gauge
value becomes greater than or equal to the high
threshold.</p>
<p>Typically, only one of the notify high and notify low
flags is set. The other threshold is used to provide a
<em>hysteresis</em> mechanism to avoid the repeated
triggering of notifications when an attribute makes small
oscillations around the threshold value.</p>
<p>A <code>GaugeMonitor</code> can operate in <em>difference
mode</em>. In this mode, the value compared against the
high and low thresholds is the difference between two
successive observations of an attribute.</p>
</li>
<li>
<p>A {@link javax.management.monitor.StringMonitor
StringMonitor} observes attributes of type
<code>String</code>. A notification is sent when an
observed attribute becomes equal and/or not equal to a
given string.</p>
</li>
</ul>
@see <a id="spec" href="https://jcp.org/aboutJava/communityprocess/mrel/jsr160/index2.html">
JMX Specification, version 1.4</a>
@since 1.5
</BODY>
</HTML>

146
src/java.management/share/classes/javax/management/openmbean/package-info.java Normal file
View File

@ -0,0 +1,146 @@
/*
* Copyright (c) 2001, 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 open data types and Open MBean descriptor classes.
* An <em>Open MBean</em> is an 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.</p>
*
* <p>Every MBean has an {@link javax.management.MBeanInfo
* MBeanInfo} with information about the MBean itself, and its
* attributes, operations, constructors, and notifications. In an
* Open MBean, this <code>MBeanInfo</code> implements the {@link
* javax.management.openmbean.OpenMBeanInfo OpenMBeanInfo}
* interface, usually by being an instance of {@link
* javax.management.openmbean.OpenMBeanInfoSupport
* OpenMBeanInfoSupport}.</p>
*
* <p>The attribute information returned by {@link
* javax.management.MBeanInfo#getAttributes()
* MBeanInfo.getAttributes} for an Open MBean is an array of
* objects implementing {@link
* javax.management.openmbean.OpenMBeanAttributeInfo
* OpenMBeanAttributeInfo}, usually instances of {@link
* javax.management.openmbean.OpenMBeanAttributeInfoSupport
* OpenMBeanAttributeInfoSupport}. In addition to the usual
* information about attributes, an
* <code>OpenMBeanAttributeInfo</code> specifies the {@link
* javax.management.openmbean.OpenType OpenType} of the attribute.
* The possible <code>OpenType</code> values are predefined, which
* is what ensures that remote managers will understand them.</p>
*
* <p>Similar remarks apply to the parameter types of operations and
* constructors, and to the return types of operations.</p>
*
* <p>There is a distinction between an attribute's Java language
* type, as returned by {@link
* javax.management.MBeanAttributeInfo#getType() getType()}, and
* its <code>OpenType</code>, as returned by {@link
* javax.management.openmbean.OpenMBeanAttributeInfo#getOpenType()
* getOpenType()}. For example, if the Java language type is
* <code>java.lang.String</code>, the <code>OpenType</code> will be
* {@link javax.management.openmbean.SimpleType#STRING
* SimpleType.String}. If the Java language type is {@link
* javax.management.openmbean.CompositeData}, the
* <code>OpenType</code> will be a {@link
* javax.management.openmbean.CompositeType CompositeType} that
* describes the items in the <code>CompositeData</code> instances
* for the attribute.</p>
*
* <h2><a id="constraints">Default values and constraints</a></h2>
*
* <p>In Open MBeans, attributes and parameters can have default values
* and/or constraints associated with them in the {@code
* OpenMBeanAttributeInfo} or {@code OpenMBeanParameterInfo}.
* There are two ways to specify these constraints. Either the
* values are directly specified as parameters to one of the
* constructors of {@code OpenMBeanAttributeInfoSupport} or
* {@code OpenMBeanParameterInfoSupport}, for example
* {@link
* javax.management.openmbean.OpenMBeanParameterInfoSupport#OpenMBeanParameterInfoSupport(
*String, String, OpenType, Object, Object[])}; or the values are
* specified in a {@link javax.management.Descriptor Descriptor} given
* as a parameter to one of the constructors.</p>
*
* <p>When a {@code Descriptor} is used, the fields of interest are
* these:</p>
*
* <ul>
*
* <li>{@code defaultValue} defines the value returned by
* {@link javax.management.openmbean.OpenMBeanParameterInfo#getDefaultValue()
* getDefaultValue()};
*
* <li>{@code minValue} defines the value returned by {@link
* javax.management.openmbean.OpenMBeanParameterInfo#getMinValue() getMinValue()};
*
* <li>{@code maxValue} defines the value returned by {@link
* javax.management.openmbean.OpenMBeanParameterInfo#getMaxValue() getMaxValue()};
*
* <li>{@code legalValues} defines the values returned by {@link
* javax.management.openmbean.OpenMBeanParameterInfo#getLegalValues() getLegalValues()}.
*
* </ul>
*
* <p>For {@code defaultValue}, {@code minValue}, and {@code
* maxValue}, the associated value must either be of the Java type
* corresponding to {@code openType}, or be a string that can be
* converted into that type. The conversion uses the static method
* {@code valueOf(String)} if it finds one; otherwise a constructor
* with a single {@code String} parameter if it finds one; otherwise
* it fails.</p>
*
* <p>For {@code legalValues}, the associated value must be either
* an array or a {@code Set}, and the elements of the array or set
* must be convertible as described for {@code defaultValue} etc.</p>
*
* <p>The following conditions must be met for these fields:</p>
*
* <ul>
* <li>the values must be of the appropriate type, or be strings
* that can be converted to the appropriate type as explained
* above;
*
* <li>if {@code legalValues} is present then neither {@code
* minValue} nor {@code maxValue} must be present;
*
* <li>if {@code defaultValue} is present then it must satisfy the
* constraints defined by {@code legalValues}, {@code minValue}, or
* {@code maxValue} when any of these is also present;
*
* <li>if {@code minValue} and {@code maxValue} are both present
* then {@code minValue} must not be greater than {@code maxValue}.
* </ul>
*
* @see <a href="https://jcp.org/aboutJava/communityprocess/mrel/jsr160/index2.html">
* JMX Specification, version 1.4</a>
*
* @since 1.5
*/
package javax.management.openmbean;

151
src/java.management/share/classes/javax/management/openmbean/package.html
View File

@ -1,151 +0,0 @@
<html>
<head>
<title>javax.management.openmbean package</title>
<!--
Copyright (c) 2001, 2017, 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.
-->
</head>
<body bgcolor="white">
<p>Provides the open data types and Open MBean descriptor classes.
An <em>Open MBean</em> is an 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.</p>
<p>Every MBean has an {@link javax.management.MBeanInfo
MBeanInfo} with information about the MBean itself, and its
attributes, operations, constructors, and notifications. In an
Open MBean, this <code>MBeanInfo</code> implements the {@link
javax.management.openmbean.OpenMBeanInfo OpenMBeanInfo}
interface, usually by being an instance of {@link
javax.management.openmbean.OpenMBeanInfoSupport
OpenMBeanInfoSupport}.</p>
<p>The attribute information returned by {@link
javax.management.MBeanInfo#getAttributes()
MBeanInfo.getAttributes} for an Open MBean is an array of
objects implementing {@link
javax.management.openmbean.OpenMBeanAttributeInfo
OpenMBeanAttributeInfo}, usually instances of {@link
javax.management.openmbean.OpenMBeanAttributeInfoSupport
OpenMBeanAttributeInfoSupport}. In addition to the usual
information about attributes, an
<code>OpenMBeanAttributeInfo</code> specifies the {@link
javax.management.openmbean.OpenType OpenType} of the attribute.
The possible <code>OpenType</code> values are predefined, which
is what ensures that remote managers will understand them.</p>
<p>Similar remarks apply to the parameter types of operations and
constructors, and to the return types of operations.</p>
<p>There is a distinction between an attribute's Java language
type, as returned by {@link
javax.management.MBeanAttributeInfo#getType() getType()}, and
its <code>OpenType</code>, as returned by {@link
javax.management.openmbean.OpenMBeanAttributeInfo#getOpenType()
getOpenType()}. For example, if the Java language type is
<code>java.lang.String</code>, the <code>OpenType</code> will be
{@link javax.management.openmbean.SimpleType#STRING
SimpleType.String}. If the Java language type is {@link
javax.management.openmbean.CompositeData}, the
<code>OpenType</code> will be a {@link
javax.management.openmbean.CompositeType CompositeType} that
describes the items in the <code>CompositeData</code> instances
for the attribute.</p>
<h2><a id="constraints">Default values and constraints</a></h2>
<p>In Open MBeans, attributes and parameters can have default values
and/or constraints associated with them in the {@code
OpenMBeanAttributeInfo} or {@code OpenMBeanParameterInfo}.
There are two ways to specify these constraints. Either the
values are directly specified as parameters to one of the
constructors of {@code OpenMBeanAttributeInfoSupport} or
{@code OpenMBeanParameterInfoSupport}, for example
{@link
javax.management.openmbean.OpenMBeanParameterInfoSupport#OpenMBeanParameterInfoSupport(
String, String, OpenType, Object, Object[])}; or the values are
specified in a {@link javax.management.Descriptor Descriptor} given
as a parameter to one of the constructors.</p>
<p>When a {@code Descriptor} is used, the fields of interest are
these:</p>
<ul>
<li>{@code defaultValue} defines the value returned by
{@link javax.management.openmbean.OpenMBeanParameterInfo#getDefaultValue()
getDefaultValue()};
<li>{@code minValue} defines the value returned by {@link
javax.management.openmbean.OpenMBeanParameterInfo#getMinValue() getMinValue()};
<li>{@code maxValue} defines the value returned by {@link
javax.management.openmbean.OpenMBeanParameterInfo#getMaxValue() getMaxValue()};
<li>{@code legalValues} defines the values returned by {@link
javax.management.openmbean.OpenMBeanParameterInfo#getLegalValues() getLegalValues()}.
</ul>
<p>For {@code defaultValue}, {@code minValue}, and {@code
maxValue}, the associated value must either be of the Java type
corresponding to {@code openType}, or be a string that can be
converted into that type. The conversion uses the static method
{@code valueOf(String)} if it finds one; otherwise a constructor
with a single {@code String} parameter if it finds one; otherwise
it fails.</p>
<p>For {@code legalValues}, the associated value must be either
an array or a {@code Set}, and the elements of the array or set
must be convertible as described for {@code defaultValue} etc.</p>
<p>The following conditions must be met for these fields:</p>
<ul>
<li>the values must be of the appropriate type, or be strings
that can be converted to the appropriate type as explained
above;
<li>if {@code legalValues} is present then neither {@code
minValue} nor {@code maxValue} must be present;
<li>if {@code defaultValue} is present then it must satisfy the
constraints defined by {@code legalValues}, {@code minValue}, or
{@code maxValue} when any of these is also present;
<li>if {@code minValue} and {@code maxValue} are both present
then {@code minValue} must not be greater than {@code maxValue}.
</ul>
@see <a href="https://jcp.org/aboutJava/communityprocess/mrel/jsr160/index2.html">
JMX Specification, version 1.4</a>
@since 1.5
</BODY>
</HTML>

393
src/java.management/share/classes/javax/management/package-info.java Normal file
View File

@ -0,0 +1,393 @@
/*
* 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;

397
src/java.management/share/classes/javax/management/package.html
View File

@ -1,397 +0,0 @@
<html>
<head>
<title>javax.management package</title>
<!--
Copyright (c) 1999, 2017, 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.
-->
</head>
<body bgcolor="white">
<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
</body>
</html>

140
src/java.management/share/classes/javax/management/relation/package-info.java Normal file
View File

@ -0,0 +1,140 @@
/*
* Copyright (c) 2000, 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 definition of the Relation Service. The
* Relation Service is used to record relationships between
* MBeans in an MBean Server. The Relation Service is itself an
* MBean. More than one instance of a {@link
* javax.management.relation.RelationService RelationService}
* MBean can be registered in an MBean Server.</p>
*
* <p>A <em>relation type</em> defines a relationship between MBeans.
* It contains <em>roles</em> that the MBeans play in the
* relationship. Usually there are at least two roles in a
* relation type.</p>
*
* <p>A <em>relation</em> is a named instance of a relation type,
* where specific MBeans appear in the roles, represented by
* their {@link javax.management.ObjectName ObjectName}s.</p>
*
* <p>For example, suppose there are <code>Module</code> MBeans,
* representing modules within an application. A
* <code>DependsOn</code> relation type could express the
* relationship that some modules depend on others, which could
* be used to determine the order in which the modules are
* started or stopped. The <code>DependsOn</code> relation type
* would have two roles, <code>dependent</code> and
* <code>dependedOn</code>.</p>
*
* <p>Every role is <em>typed</em>, meaning that an MBean that
* appears in that role must be an instance of the role's type.
* In the <code>DependsOn</code> example, both roles would be of
* type <code>Module</code>.</p>
*
* <p>Every role has a <em>cardinality</em>, which provides lower
* and upper bounds on the number of MBeans that can appear in
* that role in a given relation instance. Usually, the lower
* and upper bounds are both 1, with exactly one MBean appearing
* in the role. The cardinality only limits the number of MBeans
* in the role per relation instance. The same MBean can appear
* in the same role in any number of instances of a relation
* type. In the <code>DependsOn</code> example, a given module
* can depend on many other modules, and be depended on by many
* others, but any given relation instance links exactly one
* <code>dependent</code> module with exactly one
* <code>dependedOn</code> module.</p>
*
* <p>A relation type can be created explicitly, as an object
* implementing the {@link javax.management.relation.RelationType
* RelationType} interface, typically a {@link
* javax.management.relation.RelationTypeSupport
* RelationTypeSupport}. Alternatively, it can be created
* implicitly using the Relation Service's {@link
* javax.management.relation.RelationServiceMBean#createRelationType(String,
* RoleInfo[]) createRelationType} method.</p>
*
* <p>A relation instance can be created explicitly, as an object
* implementing the {@link javax.management.relation.Relation
* Relation} interface, typically a {@link
* javax.management.relation.RelationSupport RelationSupport}.
* (A <code>RelationSupport</code> is itself a valid MBean, so it
* can be registered in the MBean Server, though this is not
* required.) Alternatively, a relation instance can be created
* implicitly using the Relation Service's {@link
* javax.management.relation.RelationServiceMBean#createRelation(String,
* String, RoleList) createRelation} method.</p>
*
* <p>The <code>DependsOn</code> example might be coded as follows.</p>
*
* <pre>
* import java.util.*;
* import javax.management.*;
* import javax.management.relation.*;
*
* // ...
* MBeanServer mbs = ...;
*
* // Create the Relation Service MBean
* ObjectName relSvcName = new ObjectName(":type=RelationService");
* RelationService relSvcObject = new RelationService(true);
* mbs.registerMBean(relSvcObject, relSvcName);
*
* // Create an MBean proxy for easier access to the Relation Service
* RelationServiceMBean relSvc =
* MBeanServerInvocationHandler.newProxyInstance(mbs, relSvcName,
* RelationServiceMBean.class,
* false);
*
* // Define the DependsOn relation type
* RoleInfo[] dependsOnRoles = {
* new RoleInfo("dependent", Module.class.getName()),
* new RoleInfo("dependedOn", Module.class.getName())
* };
* relSvc.createRelationType("DependsOn", dependsOnRoles);
*
* // Now define a relation instance "moduleA DependsOn moduleB"
*
* ObjectName moduleA = new ObjectName(":type=Module,name=A");
* ObjectName moduleB = new ObjectName(":type=Module,name=B");
*
* Role dependent = new Role("dependent", Collections.singletonList(moduleA));
* Role dependedOn = new Role("dependedOn", Collections.singletonList(moduleB));
* Role[] roleArray = {dependent, dependedOn};
* RoleList roles = new RoleList(Arrays.asList(roleArray));
* relSvc.createRelation("A-DependsOn-B", "DependsOn", roles);
*
* // Query the Relation Service to find what modules moduleA depends on
* Map&lt;ObjectName,List&lt;String&gt;&gt; dependentAMap =
* relSvc.findAssociatedMBeans(moduleA, "DependsOn", "dependent");
* Set&lt;ObjectName&gt; dependentASet = dependentAMap.keySet();
* // Set of ObjectName containing moduleB
* </pre>
*
* @see <a href="https://jcp.org/aboutJava/communityprocess/mrel/jsr160/index2.html">
* JMX Specification, version 1.4</a>
*
* @since 1.5
*/
package javax.management.relation;

145
src/java.management/share/classes/javax/management/relation/package.html
View File

@ -1,145 +0,0 @@
<html>
<head>
<title>javax.management.relation package</title>
<!--
Copyright (c) 2000, 2017, 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.
-->
</head>
<body bgcolor="white">
<p>Provides the definition of the Relation Service. The
Relation Service is used to record relationships between
MBeans in an MBean Server. The Relation Service is itself an
MBean. More than one instance of a {@link
javax.management.relation.RelationService RelationService}
MBean can be registered in an MBean Server.</p>
<p>A <em>relation type</em> defines a relationship between MBeans.
It contains <em>roles</em> that the MBeans play in the
relationship. Usually there are at least two roles in a
relation type.</p>
<p>A <em>relation</em> is a named instance of a relation type,
where specific MBeans appear in the roles, represented by
their {@link javax.management.ObjectName ObjectName}s.</p>
<p>For example, suppose there are <code>Module</code> MBeans,
representing modules within an application. A
<code>DependsOn</code> relation type could express the
relationship that some modules depend on others, which could
be used to determine the order in which the modules are
started or stopped. The <code>DependsOn</code> relation type
would have two roles, <code>dependent</code> and
<code>dependedOn</code>.</p>
<p>Every role is <em>typed</em>, meaning that an MBean that
appears in that role must be an instance of the role's type.
In the <code>DependsOn</code> example, both roles would be of
type <code>Module</code>.</p>
<p>Every role has a <em>cardinality</em>, which provides lower
and upper bounds on the number of MBeans that can appear in
that role in a given relation instance. Usually, the lower
and upper bounds are both 1, with exactly one MBean appearing
in the role. The cardinality only limits the number of MBeans
in the role per relation instance. The same MBean can appear
in the same role in any number of instances of a relation
type. In the <code>DependsOn</code> example, a given module
can depend on many other modules, and be depended on by many
others, but any given relation instance links exactly one
<code>dependent</code> module with exactly one
<code>dependedOn</code> module.</p>
<p>A relation type can be created explicitly, as an object
implementing the {@link javax.management.relation.RelationType
RelationType} interface, typically a {@link
javax.management.relation.RelationTypeSupport
RelationTypeSupport}. Alternatively, it can be created
implicitly using the Relation Service's {@link
javax.management.relation.RelationServiceMBean#createRelationType(String,
RoleInfo[]) createRelationType} method.</p>
<p>A relation instance can be created explicitly, as an object
implementing the {@link javax.management.relation.Relation
Relation} interface, typically a {@link
javax.management.relation.RelationSupport RelationSupport}.
(A <code>RelationSupport</code> is itself a valid MBean, so it
can be registered in the MBean Server, though this is not
required.) Alternatively, a relation instance can be created
implicitly using the Relation Service's {@link
javax.management.relation.RelationServiceMBean#createRelation(String,
String, RoleList) createRelation} method.</p>
<p>The <code>DependsOn</code> example might be coded as follows.</p>
<pre>
import java.util.*;
import javax.management.*;
import javax.management.relation.*;
// ...
MBeanServer mbs = ...;
// Create the Relation Service MBean
ObjectName relSvcName = new ObjectName(":type=RelationService");
RelationService relSvcObject = new RelationService(true);
mbs.registerMBean(relSvcObject, relSvcName);
// Create an MBean proxy for easier access to the Relation Service
RelationServiceMBean relSvc =
MBeanServerInvocationHandler.newProxyInstance(mbs, relSvcName,
RelationServiceMBean.class,
false);
// Define the DependsOn relation type
RoleInfo[] dependsOnRoles = {
new RoleInfo("dependent", Module.class.getName()),
new RoleInfo("dependedOn", Module.class.getName())
};
relSvc.createRelationType("DependsOn", dependsOnRoles);
// Now define a relation instance "moduleA DependsOn moduleB"
ObjectName moduleA = new ObjectName(":type=Module,name=A");
ObjectName moduleB = new ObjectName(":type=Module,name=B");
Role dependent = new Role("dependent", Collections.singletonList(moduleA));
Role dependedOn = new Role("dependedOn", Collections.singletonList(moduleB));
Role[] roleArray = {dependent, dependedOn};
RoleList roles = new RoleList(Arrays.asList(roleArray));
relSvc.createRelation("A-DependsOn-B", "DependsOn", roles);
// Query the Relation Service to find what modules moduleA depends on
Map&lt;ObjectName,List&lt;String&gt;&gt; dependentAMap =
relSvc.findAssociatedMBeans(moduleA, "DependsOn", "dependent");
Set&lt;ObjectName&gt; dependentASet = dependentAMap.keySet();
// Set of ObjectName containing moduleB
</pre>
@see <a href="https://jcp.org/aboutJava/communityprocess/mrel/jsr160/index2.html">
JMX Specification, version 1.4</a>
@since 1.5
</BODY>
</HTML>

197
src/java.management/share/classes/javax/management/remote/package-info.java Normal file
View File

@ -0,0 +1,197 @@
/*
* Copyright (c) 2002, 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>Interfaces for remote access to
* JMX MBean servers.
* This package defines the essential interfaces for making a JMX
* MBean server manageable remotely. The specification of this
* functionality is completed by Part III of the
* <a href="https://jcp.org/aboutJava/communityprocess/mrel/jsr160/index2.html">
* JMX Specification, version 1.4</a></p>
*
* <p>The JMX specification defines the notion of <b>connectors</b>.
* A connector is attached to a JMX API MBean server and makes it
* accessible to remote Java clients. The client end of a
* connector exports essentially the same interface as the MBean
* server, specifically the {@link
* javax.management.MBeanServerConnection MBeanServerConnection}
* interface.</p>
*
* <p>A connector makes an MBean server remotely accessible through
* a given protocol. The JMX Remote API allows the use of different
* type of connectors:
*
* <ul>
* <li>The JMX Remote API defines a standard connector,
* the <b>RMI Connector</b>, which provides remote access to an
* MBeanServer through RMI.
*
* <li>The JMX Remote API also defines an optional connector called
* <b>JMXMP Connector</b> implementing the JMX Message Protocol
* (JMXMP). As it is optional, it is not part of this bundle (see
* note below).
*
* <li>User-defined connector protocols are also possible using the
* {@link javax.management.remote.JMXConnectorFactory
* JMXConnectorFactory} and, optionally, the Generic Connector
* (not part of this bundle, see note below).
* </ul>
*
* <p><u>Note</u>: the optional packages implementing
* the optional part of the <em>JMX Remote API</em>
* are not included in the <em>Java SE Platform</em>
* but are available from the <em>JMX Remote API
* <a href="https://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-java-plat-419418.html">
* Reference Implementation</a></em>.</p>
*
*
* <h2>Connector addresses</h2>
*
* <p>Typically, a connector server has an address, represented by the
* class {@link javax.management.remote.JMXServiceURL
* JMXServiceURL}. An address for the RMI Connector can look
* like this:</p>
*
* <pre>
* service:jmx:rmi:///jndi/rmi://myhost:1099/myname
* </pre>
*
* <p>In this <code>JMXServiceURL</code>, the first <code>rmi:</code>
* specifies the RMI connector, while the second <code>rmi:</code>
* specifies the RMI registry into which the RMI connector server
* has stored its stub.
*
* <p>The example above shows only one form of address.
* An address for the RMI Connector can take several forms,
* as detailed in the documentation for the package
* <code><a href="{@docRoot}/java.management.rmi/javax/management/remote/rmi/package-summary.html">javax.management.remote.rmi</a></code>.</p>
*
* <h2>Creating a connector server</h2>
*
* <p>A connector server is created by constructing an instance of
* a subclass of {@link
* javax.management.remote.JMXConnectorServer
* JMXConnectorServer}. Usually, this instance is created
* using the method {@link
* javax.management.remote.JMXConnectorServerFactory#newJMXConnectorServer(JMXServiceURL,
* java.util.Map, javax.management.MBeanServer)
* JMXConnectorServerFactory.newJMXConnectorServer}.</p>
*
* <p>Typically, a connector server is associated with an MBean
* server either by registering it in that MBean server, or by
* supplying the MBean server as a parameter when creating the
* connector server.</p>
*
* <h2>Creating a connector client</h2>
*
* <p>A connector client is usually created by supplying the
* <code>JMXServiceURL</code> of the connector server to connect to
* to the {@link
* javax.management.remote.JMXConnectorFactory#connect(JMXServiceURL)
* JMXConnectorFactory.connect} method.</p>
*
* <p>For more specialized uses, a connector client can be created
* by directly instantiating a class that implements the {@link
* javax.management.remote.JMXConnector JMXConnector} interface,
* for example the class <a href="{@docRoot}/java.management.rmi/javax/management/remote/rmi/RMIConnector.html">RMIConnector</a>.</p>
*
* <h2>Additional client or server parameters</h2>
*
* <p>When creating a connector client or server, it is possible to
* supply an object of type {@link java.util.Map Map} that defines
* additional parameters. Each entry in this Map has a key that is
* a string and an associated value whose type is appropriate for
* that key. The standard keys defined by the JMX Remote API all
* begin with the string "<code>jmx.remote.</code>". The document
* <em>JMX Remote API</em> lists these standard keys.</p>
*
* <h2>Connection identifiers</h2>
*
* <p>Every connection opened by a connector server has a string
* identifier, called its <b>connection id</b>. This identifier
* appears in the {@link
* javax.management.remote.JMXConnectionNotification
* JMXConnectionNotification} events emitted by the connector
* server, in the list returned by {@link
* javax.management.remote.JMXConnectorServerMBean#getConnectionIds()
* getConnectionIds()}, and in the value
* returned by the client's {@link
* javax.management.remote.JMXConnector#getConnectionId()
* getConnectionId()} method.</p>
*
* <p>As an example, a connection ID can look something like this:</p>
*
* <pre>
* rmi://192.18.1.9 username 1
* </pre>
*
* <p>The formal grammar for connection ids that follow this
* convention is as follows (using the grammar notation from section 2.4 of
* <em>The Java Language Specification</em>):</p>
* <pre>
* <em>ConnectionId:</em>
* <em>Protocol</em> : <em>ClientAddress<sub>opt</sub></em> Space <em>ClientId<sub>opt</sub></em> Space <em>ArbitraryText</em>
*
* <em>ClientAddress:</em>
* // <em>HostAddress</em> <em>ClientPort<sub>opt</sub></em>
*
* <em>ClientPort</em>
* : <em>HostPort</em>
* </pre>
*
* <p>The <code><em>Protocol</em></code> is a protocol that would
* be recognized by {@link
* javax.management.remote.JMXConnectorFactory
* JMXConnectorFactory}.</p>
*
* <p>The <code><em>ClientAddress</em></code> is the
* address and port of the connecting client, if these can be
* determined, otherwise nothing. The
* <code><em>HostAddress</em></code> is the Internet address of
* the host that the client is connecting from, in numeric or DNS
* form. Numeric IPv6 addresses are enclosed in square brackets
* <code>[]</code>. The <code><em>HostPort</em></code> is the
* decimal port number that the client is connecting from.</p>
*
* <p>The <code><em>ClientId</em></code> is the identity of the
* client entity, typically a string returned by {@link
* javax.management.remote.JMXPrincipal#getName()
* JMXPrincipal.getName()}. This string must not contain
* spaces.</p>
*
* <p>The <code><em>ArbitraryText</em></code> is any additional
* text that the connector server adds when creating the client id.
* At a minimum, it must be enough to distinguish this connection
* ID from the ID of any other connection currently opened by this
* connector server.</p>
*
*
* @see <a href="https://jcp.org/aboutJava/communityprocess/mrel/jsr160/index2.html">
* JMX Specification, version 1.4</a>
*
* @since 1.5
*/
package javax.management.remote;

203
src/java.management/share/classes/javax/management/remote/package.html
View File

@ -1,203 +0,0 @@
<html>
<head>
<title>JMX Remote API.</title>
<!--
Copyright (c) 2002, 2019, 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.
-->
</head>
<body bgcolor="white">
<p>Interfaces for remote access to
JMX MBean servers.
This package defines the essential interfaces for making a JMX
MBean server manageable remotely. The specification of this
functionality is completed by Part III of the
<a href="https://jcp.org/aboutJava/communityprocess/mrel/jsr160/index2.html">
JMX Specification, version 1.4</a></p>
<p>The JMX specification defines the notion of <b>connectors</b>.
A connector is attached to a JMX API MBean server and makes it
accessible to remote Java clients. The client end of a
connector exports essentially the same interface as the MBean
server, specifically the {@link
javax.management.MBeanServerConnection MBeanServerConnection}
interface.</p>
<p>A connector makes an MBean server remotely accessible through
a given protocol. The JMX Remote API allows the use of different
type of connectors:
<ul>
<li>The JMX Remote API defines a standard connector,
the <b>RMI Connector</b>, which provides remote access to an
MBeanServer through RMI.
<li>The JMX Remote API also defines an optional connector called
<b>JMXMP Connector</b> implementing the JMX Message Protocol
(JMXMP). As it is optional, it is not part of this bundle (see
note below).
<li>User-defined connector protocols are also possible using the
{@link javax.management.remote.JMXConnectorFactory
JMXConnectorFactory} and, optionally, the Generic Connector
(not part of this bundle, see note below).
</ul>
<p><u>Note</u>: the optional packages implementing
the optional part of the <em>JMX Remote API</em>
are not included in the <em>Java SE Platform</em>
but are available from the <em>JMX Remote API
<a href="https://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-java-plat-419418.html">
Reference Implementation</a></em>.</p>
<h2>Connector addresses</h2>
<p>Typically, a connector server has an address, represented by the
class {@link javax.management.remote.JMXServiceURL
JMXServiceURL}. An address for the RMI Connector can look
like this:</p>
<pre>
service:jmx:rmi:///jndi/rmi://myhost:1099/myname
</pre>
<p>In this <code>JMXServiceURL</code>, the first <code>rmi:</code>
specifies the RMI connector, while the second <code>rmi:</code>
specifies the RMI registry into which the RMI connector server
has stored its stub.
<p>The example above shows only one form of address.
An address for the RMI Connector can take several forms,
as detailed in the documentation for the package
<code>{@link javax.management.remote.rmi}</code>.</p>
<h2>Creating a connector server</h2>
<p>A connector server is created by constructing an instance of
a subclass of {@link
javax.management.remote.JMXConnectorServer
JMXConnectorServer}. Usually, this instance is created
using the method {@link
javax.management.remote.JMXConnectorServerFactory#newJMXConnectorServer(JMXServiceURL,
java.util.Map, javax.management.MBeanServer)
JMXConnectorServerFactory.newJMXConnectorServer}.</p>
<p>Typically, a connector server is associated with an MBean
server either by registering it in that MBean server, or by
supplying the MBean server as a parameter when creating the
connector server.</p>
<h2>Creating a connector client</h2>
<p>A connector client is usually created by supplying the
<code>JMXServiceURL</code> of the connector server to connect to
to the {@link
javax.management.remote.JMXConnectorFactory#connect(JMXServiceURL)
JMXConnectorFactory.connect} method.</p>
<p>For more specialized uses, a connector client can be created
by directly instantiating a class that implements the {@link
javax.management.remote.JMXConnector JMXConnector} interface,
for example the class {@link
javax.management.remote.rmi.RMIConnector
RMIConnector}.</p>
<h2>Additional client or server parameters</h2>
<p>When creating a connector client or server, it is possible to
supply an object of type {@link java.util.Map Map} that defines
additional parameters. Each entry in this Map has a key that is
a string and an associated value whose type is appropriate for
that key. The standard keys defined by the JMX Remote API all
begin with the string "<code>jmx.remote.</code>". The document
<em>JMX Remote API</em> lists these standard keys.</p>
<h2>Connection identifiers</h2>
<p>Every connection opened by a connector server has a string
identifier, called its <b>connection id</b>. This identifier
appears in the {@link
javax.management.remote.JMXConnectionNotification
JMXConnectionNotification} events emitted by the connector
server, in the list returned by {@link
javax.management.remote.JMXConnectorServerMBean#getConnectionIds()
getConnectionIds()}, and in the value
returned by the client's {@link
javax.management.remote.JMXConnector#getConnectionId()
getConnectionId()} method.</p>
<p>As an example, a connection ID can look something like this:</p>
<pre>
rmi://192.18.1.9 username 1
</pre>
<p>The formal grammar for connection ids that follow this
convention is as follows (using the grammar notation from section 2.4 of
<em>The Java Language Specification</em>):</p>
<pre>
<em>ConnectionId:</em>
<em>Protocol</em> : <em>ClientAddress<sub>opt</sub></em> Space <em>ClientId<sub>opt</sub></em> Space <em>ArbitraryText</em>
<em>ClientAddress:</em>
// <em>HostAddress</em> <em>ClientPort<sub>opt</sub></em>
<em>ClientPort</em>
: <em>HostPort</em>
</pre>
<p>The <code><em>Protocol</em></code> is a protocol that would
be recognized by {@link
javax.management.remote.JMXConnectorFactory
JMXConnectorFactory}.</p>
<p>The <code><em>ClientAddress</em></code> is the
address and port of the connecting client, if these can be
determined, otherwise nothing. The
<code><em>HostAddress</em></code> is the Internet address of
the host that the client is connecting from, in numeric or DNS
form. Numeric IPv6 addresses are enclosed in square brackets
<code>[]</code>. The <code><em>HostPort</em></code> is the
decimal port number that the client is connecting from.</p>
<p>The <code><em>ClientId</em></code> is the identity of the
client entity, typically a string returned by {@link
javax.management.remote.JMXPrincipal#getName()
JMXPrincipal.getName()}. This string must not contain
spaces.</p>
<p>The <code><em>ArbitraryText</em></code> is any additional
text that the connector server adds when creating the client id.
At a minimum, it must be enough to distinguish this connection
ID from the ID of any other connection currently opened by this
connector server.</p>
@see <a href="https://jcp.org/aboutJava/communityprocess/mrel/jsr160/index2.html">
JMX Specification, version 1.4</a>
@since 1.5
</body>
</html>

45
src/java.management/share/classes/javax/management/timer/package-info.java Normal file
View File

@ -0,0 +1,45 @@
/*
* 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 definition of the Timer MBean. A Timer MBean
* maintains a list of scheduled notifications and, because it is a
* {@link javax.management.NotificationBroadcaster
* NotificationBroadcaster}, a list of listeners for those
* notifications. Whenever the time for one of the scheduled
* notifications is reached, each listener receives the
* notification. Notifications can be repeated at a fixed
* interval, and the number of repetitions can be bounded.</p>
*
* <p>A listener for a Timer MBean can itself be an MBean, using
* the method {@link
* javax.management.MBeanServer#addNotificationListener(ObjectName,
* ObjectName, NotificationFilter, Object)}. In this way, a
* management application can create an MBean representing a task,
* then schedule that task using a Timer MBean.</p>
*
* @since 1.5
*/
package javax.management.timer;

50
src/java.management/share/classes/javax/management/timer/package.html
View File

@ -1,50 +0,0 @@
<html>
<head>
<title>javax.management.timer package</title>
<!--
Copyright (c) 1999, 2003, 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.
-->
</head>
<body bgcolor="white">
<p>Provides the definition of the Timer MBean. A Timer MBean
maintains a list of scheduled notifications and, because it is a
{@link javax.management.NotificationBroadcaster
NotificationBroadcaster}, a list of listeners for those
notifications. Whenever the time for one of the scheduled
notifications is reached, each listener receives the
notification. Notifications can be repeated at a fixed
interval, and the number of repetitions can be bounded.</p>
<p>A listener for a Timer MBean can itself be an MBean, using
the method {@link
javax.management.MBeanServer#addNotificationListener(ObjectName,
ObjectName, NotificationFilter, Object)}. In this way, a
management application can create an MBean representing a task,
then schedule that task using a Timer MBean.</p>
@since 1.5
</BODY>
</HTML>