From c7d2841fb4ac97c0edec175cf37abd90167ea56e Mon Sep 17 00:00:00 2001 From: Nizar Benalla Date: Thu, 6 Jun 2024 07:27:58 +0000 Subject: [PATCH] 8332070: Convert package.html files in `java.management` to package-info.java Reviewed-by: alanb --- .../java/lang/management/package-info.java | 239 +++++++++++ .../classes/java/lang/management/package.html | 243 ----------- .../management/loading/package-info.java | 57 +++ .../javax/management/loading/package.html | 61 --- .../management/modelmbean/package-info.java | 120 ++++++ .../javax/management/modelmbean/package.html | 124 ------ .../management/monitor/package-info.java | 187 +++++++++ .../javax/management/monitor/package.html | 191 --------- .../management/openmbean/package-info.java | 146 +++++++ .../javax/management/openmbean/package.html | 151 ------- .../javax/management/package-info.java | 393 +++++++++++++++++ .../classes/javax/management/package.html | 397 ------------------ .../management/relation/package-info.java | 140 ++++++ .../javax/management/relation/package.html | 145 ------- .../javax/management/remote/package-info.java | 197 +++++++++ .../javax/management/remote/package.html | 203 --------- .../javax/management/timer/package-info.java | 45 ++ .../javax/management/timer/package.html | 50 --- 18 files changed, 1524 insertions(+), 1565 deletions(-) create mode 100644 src/java.management/share/classes/java/lang/management/package-info.java delete mode 100644 src/java.management/share/classes/java/lang/management/package.html create mode 100644 src/java.management/share/classes/javax/management/loading/package-info.java delete mode 100644 src/java.management/share/classes/javax/management/loading/package.html create mode 100644 src/java.management/share/classes/javax/management/modelmbean/package-info.java delete mode 100644 src/java.management/share/classes/javax/management/modelmbean/package.html create mode 100644 src/java.management/share/classes/javax/management/monitor/package-info.java delete mode 100644 src/java.management/share/classes/javax/management/monitor/package.html create mode 100644 src/java.management/share/classes/javax/management/openmbean/package-info.java delete mode 100644 src/java.management/share/classes/javax/management/openmbean/package.html create mode 100644 src/java.management/share/classes/javax/management/package-info.java delete mode 100644 src/java.management/share/classes/javax/management/package.html create mode 100644 src/java.management/share/classes/javax/management/relation/package-info.java delete mode 100644 src/java.management/share/classes/javax/management/relation/package.html create mode 100644 src/java.management/share/classes/javax/management/remote/package-info.java delete mode 100644 src/java.management/share/classes/javax/management/remote/package.html create mode 100644 src/java.management/share/classes/javax/management/timer/package-info.java delete mode 100644 src/java.management/share/classes/javax/management/timer/package.html diff --git a/src/java.management/share/classes/java/lang/management/package-info.java b/src/java.management/share/classes/java/lang/management/package-info.java new file mode 100644 index 00000000000..2ea0d7bb9a7 --- /dev/null +++ b/src/java.management/share/classes/java/lang/management/package-info.java @@ -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. + * + *

Platform MXBean

+ *

+ * A platform MXBean is a managed bean 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}. + *

ManagementFactory

+ * + *

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. + * + *

A platform MBeanServer 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. + * + *

Interoperability

+ * + *

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 + * MXBean specification for details. + * + *

Ways to Access MXBeans

+ * + *

An application can monitor the instrumentation of the + * Java virtual machine and the runtime in the following ways: + *

+ * 1. Direct access to an MXBean interface + *

+ *

+ * 2. Indirect access to an MXBean interface via MBeanServer + *

+ * + * + *

Platform Extension

+ * + *

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 ManagementFactory class will + * return the MXBeans with the platform extension. + * + *

+ * 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. + * + *

Below is an example showing how to access an attribute + * from the platform extension: + * + *

+ * 1) Direct access to the Oracle-specific MXBean interface + *

+ * 
+ *    List<com.sun.management.GarbageCollectorMXBean> 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();
+ *        ...
+ *    }
+ *
+ *
+ * + *

+ * 2) Access the Oracle-specific MXBean interface via MBeanServer + * through proxy + * + * 

+ *    MBeanServerConnection mbs;
+ *
+ *    // Connect to a running JVM (or itself) and get MBeanServerConnection
+ *    // that has the JVM MXBeans registered in it
+ *    ...
+ *
+ *    List<com.sun.management.GarbageCollectorMXBean> 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();
+ *        ...
+ *    }
+ *
+ * + *

Unless otherwise noted, passing a null 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. + * + *

The java.lang.management API is thread-safe. + * + * @see javax.management JMX Specification + * + * @author Mandy Chung + * @since 1.5 + */ +package java.lang.management; diff --git a/src/java.management/share/classes/java/lang/management/package.html b/src/java.management/share/classes/java/lang/management/package.html deleted file mode 100644 index c10a97618f3..00000000000 --- a/src/java.management/share/classes/java/lang/management/package.html +++ /dev/null @@ -1,243 +0,0 @@ - - - - - - -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. - -

Platform MXBean

-

-A platform MXBean is a managed bean 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}. -

ManagementFactory

- -

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. - -

A platform MBeanServer 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. - -

Interoperability

- -

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 -MXBean specification for details. - -

Ways to Access MXBeans

- -

An application can monitor the instrumentation of the -Java virtual machine and the runtime in the following ways: -

-1. Direct access to an MXBean interface -

-

-2. Indirect access to an MXBean interface via MBeanServer -

- - -

Platform Extension

- -

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 ManagementFactory class will -return the MXBeans with the platform extension. - -

-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. - -

Below is an example showing how to access an attribute -from the platform extension: - -

-1) Direct access to the Oracle-specific MXBean interface -

-
-   List<com.sun.management.GarbageCollectorMXBean> 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();
-       ...
-   }
-
-
- -

-2) Access the Oracle-specific MXBean interface via MBeanServer - through proxy - -

-   MBeanServerConnection mbs;
-
-   // Connect to a running JVM (or itself) and get MBeanServerConnection
-   // that has the JVM MXBeans registered in it
-   ...
-
-   List<com.sun.management.GarbageCollectorMXBean> 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();
-       ...
-   }
-
- -

Unless otherwise noted, passing a null 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. - -

The java.lang.management API is thread-safe. - -@see javax.management JMX Specification - -@author Mandy Chung -@since 1.5 - - - diff --git a/src/java.management/share/classes/javax/management/loading/package-info.java b/src/java.management/share/classes/javax/management/loading/package-info.java new file mode 100644 index 00000000000..a260005c425 --- /dev/null +++ b/src/java.management/share/classes/javax/management/loading/package-info.java @@ -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. + */ + +/** + *

Provides the classes which implement advanced dynamic + * loading. See the chapter Advanced Dynamic Loading in + * the JMX Specification.

+ * + *

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[])}.

+ * + *

Every MBean Server has a class loader repository + * 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 + * createMBean and instantiate methods + * in the {@link javax.management.MBeanServer MBeanServer} + * interface that do not have an explicit loader parameter.

+ * + *

If an MBean implements the interface {@link + * javax.management.loading.PrivateClassLoader PrivateClassLoader}, + * then it is not added to the class loader repository.

+ * + * @see + * JMX Specification, version 1.4 + * + * @since 1.5 + */ +package javax.management.loading; diff --git a/src/java.management/share/classes/javax/management/loading/package.html b/src/java.management/share/classes/javax/management/loading/package.html deleted file mode 100644 index 0174f574ab4..00000000000 --- a/src/java.management/share/classes/javax/management/loading/package.html +++ /dev/null @@ -1,61 +0,0 @@ - - -javax.management.loading package - - - - -

Provides the classes which implement advanced dynamic - loading. See the chapter Advanced Dynamic Loading in - the JMX Specification.

- -

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[])}.

- -

Every MBean Server has a class loader repository - 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 - createMBean and instantiate methods - in the {@link javax.management.MBeanServer MBeanServer} - interface that do not have an explicit loader parameter.

- -

If an MBean implements the interface {@link - javax.management.loading.PrivateClassLoader PrivateClassLoader}, - then it is not added to the class loader repository.

- - @see - JMX Specification, version 1.4 - - @since 1.5 - - diff --git a/src/java.management/share/classes/javax/management/modelmbean/package-info.java b/src/java.management/share/classes/javax/management/modelmbean/package-info.java new file mode 100644 index 00000000000..b44bcc3c0a0 --- /dev/null +++ b/src/java.management/share/classes/javax/management/modelmbean/package-info.java @@ -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. + */ + + +/** + *

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.

+ * + *

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}.

+ * + *

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 MBeanInfo with {@link + * javax.management.Descriptor Descriptor}s that encode + * additional information in the form of (key,value) pairs. + * Usually, Descriptors are instances of {@link + * javax.management.modelmbean.DescriptorSupport + * DescriptorSupport}.

+ * + *

The class {@link + * javax.management.modelmbean.RequiredModelMBean + * RequiredModelMBean} provides a standard Model MBean + * implementation.

+ * + *

The following example shows a Model MBean being used to make + * the get method of a HashMap + * available for management through an MBean server. No other + * methods are available through the MBean server. There is + * nothing special about HashMap here. Public + * methods from any public class can be exposed for management in + * the same way.

+ * + * 
+ * 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"
+ *
+ * + *

Package Specification

+ * + * + * + * @since 1.5 + */ +package javax.management.modelmbean; diff --git a/src/java.management/share/classes/javax/management/modelmbean/package.html b/src/java.management/share/classes/javax/management/modelmbean/package.html deleted file mode 100644 index c5589a6ef1e..00000000000 --- a/src/java.management/share/classes/javax/management/modelmbean/package.html +++ /dev/null @@ -1,124 +0,0 @@ - - -javax.management.modelmbean package - - - - -

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.

- -

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}.

- -

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 MBeanInfo with {@link - javax.management.Descriptor Descriptor}s that encode - additional information in the form of (key,value) pairs. - Usually, Descriptors are instances of {@link - javax.management.modelmbean.DescriptorSupport - DescriptorSupport}.

- -

The class {@link - javax.management.modelmbean.RequiredModelMBean - RequiredModelMBean} provides a standard Model MBean - implementation.

- -

The following example shows a Model MBean being used to make - the get method of a HashMap - available for management through an MBean server. No other - methods are available through the MBean server. There is - nothing special about HashMap here. Public - methods from any public class can be exposed for management in - the same way.

- - 
-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"
-
- -

Package Specification

- - - - @since 1.5 - - - diff --git a/src/java.management/share/classes/javax/management/monitor/package-info.java b/src/java.management/share/classes/javax/management/monitor/package-info.java new file mode 100644 index 00000000000..9da0040d20d --- /dev/null +++ b/src/java.management/share/classes/javax/management/monitor/package-info.java @@ -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. + */ + +/** + *

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.

+ * + *

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 used 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}.

+ * + *

The rules used to interpret an {@code ObservedAttribute} like + * {@code "HeapMemoryUsage.used"} are as follows. Suppose the string is + * A.e (so A would be {@code "HeapMemoryUsage"} and e + * would be {@code "used"} in the example).

+ * + *

First the value of the attribute A is obtained. Call it + * v. A value x is extracted from v as follows:

+ * + * + * + *

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()}.

+ * + *

If the {@code ObservedAttribute} contains more than one period, + * for example {@code "ConnectionPool.connectionStats.length"}, then the + * above rules are applied iteratively. Here, v would initially be + * the value of the attribute {@code ConnectionPool}, and x would + * be derived by applying the above rules with e equal to + * {@code "connectionStats"}. Then v would be set to this x + * and a new x derived by applying the rules again with e + * equal to {@code "length"}.

+ * + *

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.

+ * + *

The exact behavior of monitors is detailed in the + * JMX Specification. What follows is a + * summary.

+ * + *

There are three kinds of Monitors:

+ * + * + * @see + * JMX Specification, version 1.4 + * @since 1.5 + */ +package javax.management.monitor; diff --git a/src/java.management/share/classes/javax/management/monitor/package.html b/src/java.management/share/classes/javax/management/monitor/package.html deleted file mode 100644 index f4092ec9208..00000000000 --- a/src/java.management/share/classes/javax/management/monitor/package.html +++ /dev/null @@ -1,191 +0,0 @@ - - -javax.management.monitor package - - - -

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.

- -

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 used 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}.

- -

The rules used to interpret an {@code ObservedAttribute} like - {@code "HeapMemoryUsage.used"} are as follows. Suppose the string is - A.e (so A would be {@code "HeapMemoryUsage"} and e - would be {@code "used"} in the example).

- -

First the value of the attribute A is obtained. Call it - v. A value x is extracted from v as follows:

- - - -

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()}.

- -

If the {@code ObservedAttribute} contains more than one period, - for example {@code "ConnectionPool.connectionStats.length"}, then the - above rules are applied iteratively. Here, v would initially be - the value of the attribute {@code ConnectionPool}, and x would - be derived by applying the above rules with e equal to - {@code "connectionStats"}. Then v would be set to this x - and a new x derived by applying the rules again with e - equal to {@code "length"}.

- -

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.

- -

The exact behavior of monitors is detailed in the - JMX Specification. What follows is a - summary.

- -

There are three kinds of Monitors:

- - - @see - JMX Specification, version 1.4 - @since 1.5 - - - diff --git a/src/java.management/share/classes/javax/management/openmbean/package-info.java b/src/java.management/share/classes/javax/management/openmbean/package-info.java new file mode 100644 index 00000000000..7c1c5bafcef --- /dev/null +++ b/src/java.management/share/classes/javax/management/openmbean/package-info.java @@ -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. + */ + +/** + *

Provides the open data types and Open MBean descriptor classes. + * An Open MBean 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.

+ * + *

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 MBeanInfo implements the {@link + * javax.management.openmbean.OpenMBeanInfo OpenMBeanInfo} + * interface, usually by being an instance of {@link + * javax.management.openmbean.OpenMBeanInfoSupport + * OpenMBeanInfoSupport}.

+ * + *

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 + * OpenMBeanAttributeInfo specifies the {@link + * javax.management.openmbean.OpenType OpenType} of the attribute. + * The possible OpenType values are predefined, which + * is what ensures that remote managers will understand them.

+ * + *

Similar remarks apply to the parameter types of operations and + * constructors, and to the return types of operations.

+ * + *

There is a distinction between an attribute's Java language + * type, as returned by {@link + * javax.management.MBeanAttributeInfo#getType() getType()}, and + * its OpenType, as returned by {@link + * javax.management.openmbean.OpenMBeanAttributeInfo#getOpenType() + * getOpenType()}. For example, if the Java language type is + * java.lang.String, the OpenType will be + * {@link javax.management.openmbean.SimpleType#STRING + * SimpleType.String}. If the Java language type is {@link + * javax.management.openmbean.CompositeData}, the + * OpenType will be a {@link + * javax.management.openmbean.CompositeType CompositeType} that + * describes the items in the CompositeData instances + * for the attribute.

+ * + *

Default values and constraints

+ * + *

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.

+ * + *

When a {@code Descriptor} is used, the fields of interest are + * these:

+ * + * + * + *

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.

+ * + *

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.

+ * + *

The following conditions must be met for these fields:

+ * + * + * + * @see + * JMX Specification, version 1.4 + * + * @since 1.5 + */ +package javax.management.openmbean; diff --git a/src/java.management/share/classes/javax/management/openmbean/package.html b/src/java.management/share/classes/javax/management/openmbean/package.html deleted file mode 100644 index dbe6091ef86..00000000000 --- a/src/java.management/share/classes/javax/management/openmbean/package.html +++ /dev/null @@ -1,151 +0,0 @@ - - -javax.management.openmbean package - - - - -

Provides the open data types and Open MBean descriptor classes. - An Open MBean 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.

- -

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 MBeanInfo implements the {@link - javax.management.openmbean.OpenMBeanInfo OpenMBeanInfo} - interface, usually by being an instance of {@link - javax.management.openmbean.OpenMBeanInfoSupport - OpenMBeanInfoSupport}.

- -

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 - OpenMBeanAttributeInfo specifies the {@link - javax.management.openmbean.OpenType OpenType} of the attribute. - The possible OpenType values are predefined, which - is what ensures that remote managers will understand them.

- -

Similar remarks apply to the parameter types of operations and - constructors, and to the return types of operations.

- -

There is a distinction between an attribute's Java language - type, as returned by {@link - javax.management.MBeanAttributeInfo#getType() getType()}, and - its OpenType, as returned by {@link - javax.management.openmbean.OpenMBeanAttributeInfo#getOpenType() - getOpenType()}. For example, if the Java language type is - java.lang.String, the OpenType will be - {@link javax.management.openmbean.SimpleType#STRING - SimpleType.String}. If the Java language type is {@link - javax.management.openmbean.CompositeData}, the - OpenType will be a {@link - javax.management.openmbean.CompositeType CompositeType} that - describes the items in the CompositeData instances - for the attribute.

- -

Default values and constraints

- -

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.

- -

When a {@code Descriptor} is used, the fields of interest are - these:

- - - -

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.

- -

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.

- -

The following conditions must be met for these fields:

- - - - @see - JMX Specification, version 1.4 - - @since 1.5 - - - diff --git a/src/java.management/share/classes/javax/management/package-info.java b/src/java.management/share/classes/javax/management/package-info.java new file mode 100644 index 00000000000..ea1bebf3fe2 --- /dev/null +++ b/src/java.management/share/classes/javax/management/package-info.java @@ -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. + */ + +/** + *

Provides the core classes for the Java Management Extensions.

+ * + *

The Java Management Extensions + * (JMX) API is a standard + * API for management and monitoring. Typical uses include:

+ * + * + * + *

The JMX API can also be used as part of a solution for + * managing systems, networks, and so on.

+ * + *

The API includes remote access, so a remote management + * program can interact with a running application for these + * purposes.

+ * + *

MBeans

+ * + *

The fundamental notion of the JMX API is the MBean. + * An MBean is a named managed object representing a + * resource. It has a management interface + * which must be public and consist of:

+ * + * + * + *

For example, an MBean representing an application's + * configuration could have attributes representing the different + * configuration items. Reading the CacheSize + * 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 + * save could store the current configuration + * persistently. A notification such as + * ConfigurationChangedNotification could be sent + * every time the configuration is changed.

+ * + *

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.

+ * + * + *

Standard MBeans

+ * + *

To make MBean implementation simple, the JMX API includes the + * notion of Standard MBeans. 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:

+ * + * 
+ * public interface ConfigurationMBean {
+ *      public int getCacheSize();
+ *      public void setCacheSize(int size);
+ *      public long getLastChangedTime();
+ *      public void save();
+ * }
+ *
+ * + *

The methods getCacheSize and + * setCacheSize define a read-write attribute of + * type int called CacheSize (with an + * initial capital, unlike the JavaBeans convention).

+ * + *

The method getLastChangedTime defines an + * attribute of type long called + * LastChangedTime. This is a read-only attribute, + * since there is no method setLastChangedTime.

+ * + *

The method save defines an operation called + * save. It is not an attribute, since its name + * does not begin with get, set, or + * is.

+ * + *

The exact naming patterns for Standard MBeans are detailed in + * the JMX Specification.

+ * + *

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 MBean suffix. So in + * the example the object would be of the class + * Configuration, in the same Java package as + * ConfigurationMBean. The second way is to use the + * {@link javax.management.StandardMBean StandardMBean} + * class.

+ * + * + *

MXBeans

+ * + *

An MXBean 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}.

+ * + * + *

Dynamic MBeans

+ * + *

A Dynamic MBean 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.

+ * + *

Any Java object of a class that implements the {@link + * javax.management.DynamicMBean DynamicMBean} interface is a + * Dynamic MBean.

+ * + * + *

Open MBeans

+ * + *

An Open MBean 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 + * javax.management.openmbean.

+ * + * + *

Model MBeans

+ * + *

A Model MBean 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 + * + * javax.management.modelmbean.

+ * + * + *

MBean Server

+ * + *

To be useful, an MBean must be registered in an MBean + * Server. 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.

+ * + *

An MBean Server is an object implementing the interface + * {@link javax.management.MBeanServer MBeanServer}. + * The most convenient MBean Server to use is the + * Platform MBean Server. 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()}.

+ * + *

Application code can also create a new MBean Server, or + * access already-created MBean Servers, using the {@link + * javax.management.MBeanServerFactory MBeanServerFactory} class.

+ * + * + *

Creating MBeans in the MBean Server

+ * + *

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.

+ * + *

The registerMBean method is simpler for local + * use, but cannot be used remotely. The + * createMBean method can be used remotely, but + * sometimes requires attention to class loading issues.

+ * + *

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.

+ * + * + *

Accessing MBeans in the MBean Server

+ * + *

Given an ObjectName name and an + * MBeanServer mbs, you can access + * attributes and operations as in this example:

+ * + * 
+ * 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]);
+ *
+ * + *

Alternatively, if you have a Java interface that + * corresponds to the management interface for the MBean, you can use an + * MBean proxy like this:

+ * + * 
+ * ConfigurationMBean conf =
+ *     {@link javax.management.JMX#newMBeanProxy
+ *         JMX.newMBeanProxy}(mbs, name, ConfigurationMBean.class);
+ * int cacheSize = conf.getCacheSize();
+ * conf.setCacheSize(2000);
+ * conf.save();
+ *
+ * + *

Using an MBean proxy is just a convenience. The second + * example ends up calling the same MBeanServer + * operations as the first one.

+ * + *

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.

+ * + * + *

MBean lifecycle

+ * + *

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 MBeanServer + * object and to get its ObjectName within the MBean + * Server.

+ * + * + *

Notifications

+ * + *

A notification is an instance of the {@link + * javax.management.Notification Notification} class or a + * subclass. In addition to its Java class, it has a + * type string that can distinguish it from other + * notifications of the same class.

+ * + *

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:

+ * + * 
+ * public class Configuration extends NotificationBroadcasterSupport
+ *         implements ConfigurationMBean {
+ *     ...
+ *     private void updated() {
+ *         Notification n = new Notification(...);
+ *         {@link javax.management.NotificationBroadcasterSupport#sendNotification
+ *         sendNotification}(n);
+ *     }
+ * }
+ *
+ * + * + *

Notifications can be received by a listener, 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 filter to this method, to + * select only notifications of interest. A filter is an object + * that implements the {@link javax.management.NotificationFilter + * NotificationFilter} interface.

+ * + *

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.

+ * + * + *

Remote Access to MBeans

+ * + *

An MBean Server can be accessed remotely through a + * connector. A connector allows a remote Java + * application to access an MBean Server in essentially the same + * way as a local one. The package + * + * javax.management.remote defines connectors.

+ * + *

The JMX specification also defines the notion of an + * adaptor. 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 + * getAttribute on the MBean Server.

+ * + *

Interoperability between versions of the JMX + * specification

+ * + *

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.

+ * + *

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.

+ * + *

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}.

+ * + *

If the remote MBean Server is 1.2

+ * + * + * + * @see + * JMX Specification, version 1.4 + * + * @since 1.5 + */ +package javax.management; diff --git a/src/java.management/share/classes/javax/management/package.html b/src/java.management/share/classes/javax/management/package.html deleted file mode 100644 index c32da88c494..00000000000 --- a/src/java.management/share/classes/javax/management/package.html +++ /dev/null @@ -1,397 +0,0 @@ - - - javax.management package - - - -

Provides the core classes for the Java Management Extensions.

- -

The Java Management Extensions - (JMX) API is a standard - API for management and monitoring. Typical uses include:

- - - -

The JMX API can also be used as part of a solution for - managing systems, networks, and so on.

- -

The API includes remote access, so a remote management - program can interact with a running application for these - purposes.

- -

MBeans

- -

The fundamental notion of the JMX API is the MBean. - An MBean is a named managed object representing a - resource. It has a management interface - which must be public and consist of:

- - - -

For example, an MBean representing an application's - configuration could have attributes representing the different - configuration items. Reading the CacheSize - 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 - save could store the current configuration - persistently. A notification such as - ConfigurationChangedNotification could be sent - every time the configuration is changed.

- -

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.

- - -

Standard MBeans

- -

To make MBean implementation simple, the JMX API includes the - notion of Standard MBeans. 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:

- - 
-    public interface ConfigurationMBean {
-         public int getCacheSize();
-         public void setCacheSize(int size);
-         public long getLastChangedTime();
-         public void save();
-    }
-
- -

The methods getCacheSize and - setCacheSize define a read-write attribute of - type int called CacheSize (with an - initial capital, unlike the JavaBeans convention).

- -

The method getLastChangedTime defines an - attribute of type long called - LastChangedTime. This is a read-only attribute, - since there is no method setLastChangedTime.

- -

The method save defines an operation called - save. It is not an attribute, since its name - does not begin with get, set, or - is.

- -

The exact naming patterns for Standard MBeans are detailed in - the JMX Specification.

- -

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 MBean suffix. So in - the example the object would be of the class - Configuration, in the same Java package as - ConfigurationMBean. The second way is to use the - {@link javax.management.StandardMBean StandardMBean} - class.

- - -

MXBeans

- -

An MXBean 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}.

- - -

Dynamic MBeans

- -

A Dynamic MBean 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.

- -

Any Java object of a class that implements the {@link - javax.management.DynamicMBean DynamicMBean} interface is a - Dynamic MBean.

- - -

Open MBeans

- -

An Open MBean 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 - javax.management.openmbean.

- - -

Model MBeans

- -

A Model MBean 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 - - javax.management.modelmbean.

- - -

MBean Server

- -

To be useful, an MBean must be registered in an MBean - Server. 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.

- -

An MBean Server is an object implementing the interface - {@link javax.management.MBeanServer MBeanServer}. - The most convenient MBean Server to use is the - Platform MBean Server. 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()}.

- -

Application code can also create a new MBean Server, or - access already-created MBean Servers, using the {@link - javax.management.MBeanServerFactory MBeanServerFactory} class.

- - -

Creating MBeans in the MBean Server

- -

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.

- -

The registerMBean method is simpler for local - use, but cannot be used remotely. The - createMBean method can be used remotely, but - sometimes requires attention to class loading issues.

- -

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.

- - -

Accessing MBeans in the MBean Server

- -

Given an ObjectName name and an - MBeanServer mbs, you can access - attributes and operations as in this example:

- - 
-    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]);
-
- -

Alternatively, if you have a Java interface that - corresponds to the management interface for the MBean, you can use an - MBean proxy like this:

- - 
-    ConfigurationMBean conf =
-        {@link javax.management.JMX#newMBeanProxy
-            JMX.newMBeanProxy}(mbs, name, ConfigurationMBean.class);
-    int cacheSize = conf.getCacheSize();
-    conf.setCacheSize(2000);
-    conf.save();
-
- -

Using an MBean proxy is just a convenience. The second - example ends up calling the same MBeanServer - operations as the first one.

- -

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.

- - -

MBean lifecycle

- -

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 MBeanServer - object and to get its ObjectName within the MBean - Server.

- - -

Notifications

- -

A notification is an instance of the {@link - javax.management.Notification Notification} class or a - subclass. In addition to its Java class, it has a - type string that can distinguish it from other - notifications of the same class.

- -

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:

- - 
-    public class Configuration extends NotificationBroadcasterSupport
-            implements ConfigurationMBean {
-        ...
-        private void updated() {
-            Notification n = new Notification(...);
-            {@link javax.management.NotificationBroadcasterSupport#sendNotification
-            sendNotification}(n);
-        }
-    }
-
- - -

Notifications can be received by a listener, 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 filter to this method, to - select only notifications of interest. A filter is an object - that implements the {@link javax.management.NotificationFilter - NotificationFilter} interface.

- -

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.

- - -

Remote Access to MBeans

- -

An MBean Server can be accessed remotely through a - connector. A connector allows a remote Java - application to access an MBean Server in essentially the same - way as a local one. The package - - javax.management.remote defines connectors.

- -

The JMX specification also defines the notion of an - adaptor. 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 - getAttribute on the MBean Server.

- -

Interoperability between versions of the JMX - specification

- -

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.

- -

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.

- -

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}.

- -

If the remote MBean Server is 1.2

- - - - @see - JMX Specification, version 1.4 - - @since 1.5 - - - diff --git a/src/java.management/share/classes/javax/management/relation/package-info.java b/src/java.management/share/classes/javax/management/relation/package-info.java new file mode 100644 index 00000000000..26525e6e060 --- /dev/null +++ b/src/java.management/share/classes/javax/management/relation/package-info.java @@ -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. + */ +/** + *

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.

+ * + *

A relation type defines a relationship between MBeans. + * It contains roles that the MBeans play in the + * relationship. Usually there are at least two roles in a + * relation type.

+ * + *

A relation is a named instance of a relation type, + * where specific MBeans appear in the roles, represented by + * their {@link javax.management.ObjectName ObjectName}s.

+ * + *

For example, suppose there are Module MBeans, + * representing modules within an application. A + * DependsOn 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 DependsOn relation type + * would have two roles, dependent and + * dependedOn.

+ * + *

Every role is typed, meaning that an MBean that + * appears in that role must be an instance of the role's type. + * In the DependsOn example, both roles would be of + * type Module.

+ * + *

Every role has a cardinality, 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 DependsOn 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 + * dependent module with exactly one + * dependedOn module.

+ * + *

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.

+ * + *

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 RelationSupport 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.

+ * + *

The DependsOn example might be coded as follows.

+ * + * 
+ * 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<ObjectName,List<String>> dependentAMap =
+ *     relSvc.findAssociatedMBeans(moduleA, "DependsOn", "dependent");
+ * Set<ObjectName> dependentASet = dependentAMap.keySet();
+ * // Set of ObjectName containing moduleB
+ *
+ * + * @see + * JMX Specification, version 1.4 + * + * @since 1.5 + */ +package javax.management.relation; diff --git a/src/java.management/share/classes/javax/management/relation/package.html b/src/java.management/share/classes/javax/management/relation/package.html deleted file mode 100644 index 4eeeba8a923..00000000000 --- a/src/java.management/share/classes/javax/management/relation/package.html +++ /dev/null @@ -1,145 +0,0 @@ - - -javax.management.relation package - - - -

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.

- -

A relation type defines a relationship between MBeans. - It contains roles that the MBeans play in the - relationship. Usually there are at least two roles in a - relation type.

- -

A relation is a named instance of a relation type, - where specific MBeans appear in the roles, represented by - their {@link javax.management.ObjectName ObjectName}s.

- -

For example, suppose there are Module MBeans, - representing modules within an application. A - DependsOn 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 DependsOn relation type - would have two roles, dependent and - dependedOn.

- -

Every role is typed, meaning that an MBean that - appears in that role must be an instance of the role's type. - In the DependsOn example, both roles would be of - type Module.

- -

Every role has a cardinality, 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 DependsOn 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 - dependent module with exactly one - dependedOn module.

- -

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.

- -

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 RelationSupport 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.

- -

The DependsOn example might be coded as follows.

- -
-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<ObjectName,List<String>> dependentAMap =
-    relSvc.findAssociatedMBeans(moduleA, "DependsOn", "dependent");
-Set<ObjectName> dependentASet = dependentAMap.keySet();
-// Set of ObjectName containing moduleB
-
- - @see - JMX Specification, version 1.4 - - @since 1.5 - - - diff --git a/src/java.management/share/classes/javax/management/remote/package-info.java b/src/java.management/share/classes/javax/management/remote/package-info.java new file mode 100644 index 00000000000..d198030c302 --- /dev/null +++ b/src/java.management/share/classes/javax/management/remote/package-info.java @@ -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. + */ + +/** + *

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 + * + * JMX Specification, version 1.4

+ * + *

The JMX specification defines the notion of connectors. + * 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.

+ * + *

A connector makes an MBean server remotely accessible through + * a given protocol. The JMX Remote API allows the use of different + * type of connectors: + * + *

+ * + *

Note: the optional packages implementing + * the optional part of the JMX Remote API + * are not included in the Java SE Platform + * but are available from the JMX Remote API + * + * Reference Implementation.

+ * + * + *

Connector addresses

+ * + *

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:

+ * + * 
+ *       service:jmx:rmi:///jndi/rmi://myhost:1099/myname
+ *
+ * + *

In this JMXServiceURL, the first rmi: + * specifies the RMI connector, while the second rmi: + * specifies the RMI registry into which the RMI connector server + * has stored its stub. + * + *

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 + * javax.management.remote.rmi.

+ * + *

Creating a connector server

+ * + *

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}.

+ * + *

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.

+ * + *

Creating a connector client

+ * + *

A connector client is usually created by supplying the + * JMXServiceURL of the connector server to connect to + * to the {@link + * javax.management.remote.JMXConnectorFactory#connect(JMXServiceURL) + * JMXConnectorFactory.connect} method.

+ * + *

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 RMIConnector.

+ * + *

Additional client or server parameters

+ * + *

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 "jmx.remote.". The document + * JMX Remote API lists these standard keys.

+ * + *

Connection identifiers

+ * + *

Every connection opened by a connector server has a string + * identifier, called its connection id. 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.

+ * + *

As an example, a connection ID can look something like this:

+ * + * 
+ * rmi://192.18.1.9 username 1
+ *
+ * + *

The formal grammar for connection ids that follow this + * convention is as follows (using the grammar notation from section 2.4 of + * The Java Language Specification):

+ * 
+ * ConnectionId:
+ *     Protocol : ClientAddressopt Space ClientIdopt Space ArbitraryText
+ *
+ * ClientAddress:
+ *     // HostAddress ClientPortopt
+ *
+ * ClientPort
+ *     : HostPort
+ *
+ * + *

The Protocol is a protocol that would + * be recognized by {@link + * javax.management.remote.JMXConnectorFactory + * JMXConnectorFactory}.

+ * + *

The ClientAddress is the + * address and port of the connecting client, if these can be + * determined, otherwise nothing. The + * HostAddress 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 + * []. The HostPort is the + * decimal port number that the client is connecting from.

+ * + *

The ClientId 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.

+ * + *

The ArbitraryText 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.

+ * + * + * @see + * JMX Specification, version 1.4 + * + * @since 1.5 + */ +package javax.management.remote; diff --git a/src/java.management/share/classes/javax/management/remote/package.html b/src/java.management/share/classes/javax/management/remote/package.html deleted file mode 100644 index 3673d8dd8ed..00000000000 --- a/src/java.management/share/classes/javax/management/remote/package.html +++ /dev/null @@ -1,203 +0,0 @@ - - - JMX Remote API. - - - -

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 - - JMX Specification, version 1.4

- -

The JMX specification defines the notion of connectors. - 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.

- -

A connector makes an MBean server remotely accessible through - a given protocol. The JMX Remote API allows the use of different - type of connectors: - -

- -

Note: the optional packages implementing - the optional part of the JMX Remote API - are not included in the Java SE Platform - but are available from the JMX Remote API - - Reference Implementation.

- - -

Connector addresses

- -

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:

- - 
-      service:jmx:rmi:///jndi/rmi://myhost:1099/myname
-
- -

In this JMXServiceURL, the first rmi: - specifies the RMI connector, while the second rmi: - specifies the RMI registry into which the RMI connector server - has stored its stub. - -

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 - {@link javax.management.remote.rmi}.

- -

Creating a connector server

- -

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}.

- -

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.

- -

Creating a connector client

- -

A connector client is usually created by supplying the - JMXServiceURL of the connector server to connect to - to the {@link - javax.management.remote.JMXConnectorFactory#connect(JMXServiceURL) - JMXConnectorFactory.connect} method.

- -

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}.

- -

Additional client or server parameters

- -

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 "jmx.remote.". The document - JMX Remote API lists these standard keys.

- -

Connection identifiers

- -

Every connection opened by a connector server has a string - identifier, called its connection id. 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.

- -

As an example, a connection ID can look something like this:

- - 
-rmi://192.18.1.9 username 1
-
- -

The formal grammar for connection ids that follow this - convention is as follows (using the grammar notation from section 2.4 of - The Java Language Specification):

- 
-ConnectionId:
-    Protocol : ClientAddressopt Space ClientIdopt Space ArbitraryText
-
-ClientAddress:
-    // HostAddress ClientPortopt
-
-ClientPort
-    : HostPort
-
- -

The Protocol is a protocol that would - be recognized by {@link - javax.management.remote.JMXConnectorFactory - JMXConnectorFactory}.

- -

The ClientAddress is the - address and port of the connecting client, if these can be - determined, otherwise nothing. The - HostAddress 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 - []. The HostPort is the - decimal port number that the client is connecting from.

- -

The ClientId 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.

- -

The ArbitraryText 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.

- - - @see - JMX Specification, version 1.4 - - @since 1.5 - - - diff --git a/src/java.management/share/classes/javax/management/timer/package-info.java b/src/java.management/share/classes/javax/management/timer/package-info.java new file mode 100644 index 00000000000..34c30ba7239 --- /dev/null +++ b/src/java.management/share/classes/javax/management/timer/package-info.java @@ -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. + */ + +/** + *

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.

+ * + *

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.

+ * + * @since 1.5 + */ +package javax.management.timer; diff --git a/src/java.management/share/classes/javax/management/timer/package.html b/src/java.management/share/classes/javax/management/timer/package.html deleted file mode 100644 index a1cada0e33e..00000000000 --- a/src/java.management/share/classes/javax/management/timer/package.html +++ /dev/null @@ -1,50 +0,0 @@ - - -javax.management.timer package - - - - -

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.

- -

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.

- - @since 1.5 - - -