management

Provides the core classes for the Java Management Extensions.

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

• consulting and changing application configuration
• accumulating statistics about application behavior and making them available
• notifying of state changes and erroneous conditions.

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 consisting of:

• named and typed attributes that can be read and/or written
• named and typed operations that can be invoked
• typed notifications that can be emitted by the MBean.

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

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 by delegating to an instance of that class.

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.

@see Java SE 6 Platform documentation on JMX technology in particular the JMX Specification, version 1.4(pdf). @since 1.5

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[])}. The {@link javax.management.loading.MLet MLet} class is an example of such an MBean. It is a {@link java.net.URLClassLoader URLClassLoader}, so the list of URLs to load classes from can be configured.

Additionally, an MLet can read a configuration file that specifies a set of MBeans to be registered in the same MBean Server as the MLet.

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. It is also used by the MLet class when it does not find a class in its own set of URLs.

If an MBean implements the interface {@link javax.management.loading.PrivateClassLoader PrivateClassLoader}, then it is not added to the class loader repository. The class {@link javax.management.loading.PrivateMLet PrivateMLet} is a subclass of MLet that implements PrivateClassLoader.

@see Java SE 6 Platform documentation on JMX technology, in particular the JMX Specification, version 1.4(pdf). @since 1.5

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

• See the JMX 1.4 Specification PDF document available from the Java SE 6 Platform documentation on JMX

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 java.lang.management has an attribute HeapMemoryUsage of type {@link java.lang.management.MemoryUsage MemoryUsage}. To monitor the amount of used memory, described by the used property of MemoryUsage, you could monitor "HeapMemoryUsage.used". That string would be the argument to {@link javax.management.monitor.MonitorMBean#setObservedAttribute(String) setObservedAttribute}.

The rules used to interpret an ObservedAttribute like "HeapMemoryUsage.used" are as follows. Suppose the string is A.e (so A would be "HeapMemoryUsage" and e would be "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:

• If v is a {@link javax.management.openmbean.CompositeData CompositeData} and if v.{@link javax.management.openmbean.CompositeData#get(String) get}(e) returns a value then x is that value.
• If v is an array and e is the string "length" then x is the length of the array.
• If the above rules do not produce a value, and if {@link java.beans.Introspector#getBeanInfo(Class) Introspector.getBeanInfo} for the class of v (v.getClass()) contains a {@link java.beans.PropertyDescriptor PropertyDescriptor} with the name e, then x is the result of calling the property's {@link java.beans.PropertyDescriptor#getReadMethod() read method} on v.

The third rule means for example that if the attribute HeapMemoryUsage is a MemoryUsage, monitoring "HeapMemoryUsage.used" will obtain the observed value by calling MemoryUsage.getUsed().

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

Although it is recommended that attribute names be valid Java identifiers, it is possible for an attribute to be called HeapMemoryUsage.used. This means that an ObservedAttribute that is HeapMemoryUsage.used could mean that the value to observe is either an attribute of that name, or the property used within an attribute called HeapMemoryUsage. So for compatibility reasons, when the ObservedAttribute contains a period (.), the monitor will check whether an attribute exists whose name is the full ObservedAttribute string (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 HeapMemoryUsage.used attribute and others do not. An implementation may therefore call 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:

• A {@link javax.management.monitor.CounterMonitor CounterMonitor} observes attributes of integer type. The attributes are assumed to be non-negative, and monotonically increasing except for a possible roll-over at a specified modulus. Each observed attribute has an associated threshold value. A notification is sent when the attribute exceeds its threshold.

  An offset value can be specified. When an observed value exceeds its threshold, the threshold is incremented by the offset, or by a multiple of the offset sufficient to make the threshold greater than the new observed value.

  A CounterMonitor can operate in difference mode. In this mode, the value compared against the threshold is the difference between two successive observations of an attribute.

• A {@link javax.management.monitor.GaugeMonitor GaugeMonitor} observes attributes of numerical type. Each observed attribute has an associated high threshold and low threshold.

  When an observed attribute crosses the high threshold, if the notify high flag is true, then a notification is sent. Subsequent crossings of the high threshold value will not trigger further notifications until the gauge value becomes less than or equal to the low threshold.

  When an observed attribute crosses the low threshold, if the notify low flag is true, then a notification is sent. Subsequent crossings of the low threshold value will not trigger further notifications until the gauge value becomes greater than or equal to the high threshold.

  Typically, only one of the notify high and notify low flags is set. The other threshold is used to provide a hysteresis mechanism to avoid the repeated triggering of notifications when an attribute makes small oscillations around the threshold value.

  A GaugeMonitor can operate in difference mode. In this mode, the value compared against the high and low thresholds is the difference between two successive observations of an attribute.

• A {@link javax.management.monitor.StringMonitor StringMonitor} observes attributes of type String. A notification is sent when an observed attribute becomes equal and/or not equal to a given string.

@see Java SE 6 Platform documentation on JMX technology, in particular the JMX Specification, version 1.4(pdf). @since 1.5

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:

• {@code defaultValue} defines the value returned by {@link javax.management.openmbean.OpenMBeanParameterInfo#getDefaultValue() getDefaultValue()};
• {@code minValue} defines the value returned by {@link javax.management.openmbean.OpenMBeanParameterInfo#getMinValue() getMinValue()};
• {@code maxValue} defines the value returned by {@link javax.management.openmbean.OpenMBeanParameterInfo#getMaxValue() getMaxValue()};
• {@code legalValues} defines the values returned by {@link javax.management.openmbean.OpenMBeanParameterInfo#getLegalValues() getLegalValues()}.

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:

• the values must be of the appropriate type, or be strings that can be converted to the appropriate type as explained above;
• if {@code legalValues} is present then neither {@code minValue} nor {@code maxValue} must be present;
• if {@code defaultValue} is present then it must satisfy the constraints defined by {@code legalValues}, {@code minValue}, or {@code maxValue} when any of these is also present;
• if {@code minValue} and {@code maxValue} are both present then {@code minValue} must not be greater than {@code maxValue}.

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

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

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:

• The JMX Remote API defines a standard connector, the RMI Connector, which provides remote access to an MBeanServer through RMI.
• The JMX Remote API also defines an optional connector called JMXMP Connector implementing the JMX Message Protocol (JMXMP). As it is optional, it is not part of this bundle (see note below).
• User-defined connector protocols are also possible using the {@link javax.management.remote.JMXConnectorFactory JMXConnectorFactory} and, optionally, the Generic Connector (not part of this bundle, see note below).

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 The Java Language Specification, Second Edition):

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.

The RMI connector is a connector for the JMX Remote API that uses RMI to transmit client requests to a remote MBean server. This package defines the classes that the user of an RMI connector needs to reference directly, for both the client and server sides. It also defines certain classes that the user will not usually reference directly, but that must be defined so that different implementations of the RMI connector can interoperate.

The RMI connector supports both the JRMP and the IIOP transports for RMI.

Like most connectors in the JMX Remote API, an RMI connector usually has an address, which is a {@link javax.management.remote.JMXServiceURL JMXServiceURL}. The protocol part of this address is rmi for a connector that uses the default RMI transport (JRMP), or iiop for a connector that uses RMI/IIOP.

There are two forms for RMI connector addresses:

• In the JNDI form, the URL indicates where to find an RMI stub for the connector. This RMI stub is a Java object of type {@link javax.management.remote.rmi.RMIServer RMIServer} that gives remote access to the connector server. With this address form, the RMI stub is obtained from an external directory entry included in the URL. An external directory is any directory recognized by {@link javax.naming JNDI}, typically the RMI registry, LDAP, or COS Naming.
• In the encoded form, the URL directly includes the information needed to connect to the connector server. When using RMI/JRMP, the encoded form is the serialized RMI stub for the server object, encoded using BASE64 without embedded newlines. When using RMI/IIOP, the encoded form is the CORBA IOR for the server object.

Addresses are covered in more detail below.

Creating an RMI connector server

The usual way to create an RMI connector server is to supply an RMI connector address to the method {@link javax.management.remote.JMXConnectorServerFactory#newJMXConnectorServer JMXConnectorServerFactory.newJMXConnectorServer}. The MBean server to which the connector server is attached can be specified as a parameter to that method. Alternatively, the connector server can be registered as an MBean in that MBean server.

An RMI connector server can also be created by constructing an instance of {@link javax.management.remote.rmi.RMIConnectorServer RMIConnectorServer}, explicitly or through the MBean server's createMBean method.

Choosing the RMI transport

You can choose the RMI transport (JRMP or IIOP) by specifying rmi or iiop in the protocol part of the serviceURL when creating the connector server. You can also create specialised connector servers by instantiating an appropriate subclass of {@link javax.management.remote.rmi.RMIServerImpl RMIServerImpl} and supplying it to the RMIConnectorServer constructor.

Connector addresses generated by the server

If the serviceURL you specify has an empty URL path (after the optional host and port), or if you do not specify a serviceURL, then the connector server will fabricate a new JMXServiceURL that clients can use to connect:

• If the serviceURL looks like:

  	service:jmx:rmi://host:port
  	

  then the connector server will generate an {@link javax.management.remote.rmi.RMIJRMPServerImpl RMIJRMPServerImpl} and the returned JMXServiceURL looks like:

  	service:jmx:rmi://host:port/stub/XXXX
  	

  where XXXX is the serialized form of the stub for the generated object, encoded in BASE64 without newlines.

• If the serviceURL looks like:

  	service:jmx:iiop://host:port
  	

  then the connector server will generate an {@link javax.management.remote.rmi.RMIIIOPServerImpl RMIIIOPServerImpl} and the returned JMXServiceURL looks like:

  	service:jmx:iiop://host:port/ior/IOR:XXXX
  	

  where IOR:XXXX is the standard CORBA encoding of the Interoperable Object Reference for the generated object.

• If there is no serviceURL, there must be a user-provided RMIServerImpl. If the {@link javax.management.remote.rmi.RMIServerImpl#toStub toStub} method on this object returns an instance of {@link javax.rmi.CORBA.Stub}, then the connector server will generate a JMXServiceURL using the iiop form above. Otherwise, it will generate a JMXServiceURL using the rmi form.

The host in a user-provided serviceURL is optional. If present, it is copied into the generated JMXServiceURL but otherwise ignored. If absent, the generated JXMServiceURL will have the local host name.

The port in a user-provided serviceURL is also optional. If present, it is also copied into the generated JMXServiceURL; otherwise, the generated JMXServiceURL has no port. For an serviceURL using the rmi protocol, the port, if present, indicates what port the generated remote object should be exported on. It has no other effect.

If the user provides an RMIServerImpl rather than a JMXServiceURL, then the generated JMXServiceURL will have the local host name in its host part and no port.

Connector addresses based on directory entries

As an alternative to the generated addresses just described, the serviceURL address supplied when creating a connector server can specify a directory address in which to store the provided or generated RMIServer stub. This directory address is then used by both client and server.

In this case, the serviceURL has one of these two forms:

    service:jmx:rmi://host:port/jndi/jndi-name
    service:jmx:iiop://host:port/jndi/jndi-name
    

Here, jndi-name is a string that can be supplied to {@link javax.naming.InitialContext#bind javax.naming.InitialContext.bind}.

As usual, the host and :port can be omitted.

The connector server will generate an RMIServerImpl based on the protocol (rmi or iiop) and, for rmi, the port if any. When the connector server is started, it will derive a stub from this object using its {@link javax.management.remote.rmi.RMIServerImpl#toStub toStub} method and store the object using the given jndi-name. The properties defined by the JNDI API are consulted as usual.

For example, if the JMXServiceURL is:

      service:jmx:rmi://ignoredhost/jndi/rmi://myhost/myname
      

      rmi://myhost/myname
      

In this JMXServiceURL, the first rmi: specifies the RMI connector, while the second rmi: specifies the RMI registry.

As another example, if the JMXServiceURL is:

      service:jmx:iiop://ignoredhost/jndi/ldap://dirhost:9999/cn=this,ou=that
      

      ldap://dirhost:9999/cn=this,ou=that
      

If the JMXServiceURL is:

      service:jmx:iiop://ignoredhost/jndi/cn=this,ou=that
      

      cn=this,ou=that
      

In these examples, the host name ignoredhost is not used by the connector server or its clients. It can be omitted, for example:

      service:jmx:iiop:///jndi/cn=this,ou=that
      

However, it is good practice to use the name of the host where the connector server is running. This is often different from the name of the directory host.

Connector server attributes

When using the default JRMP transport, RMI socket factories can be specified using the attributes jmx.remote.rmi.client.socket.factory and jmx.remote.rmi.server.socket.factory in the environment given to the RMIConnectorServer constructor. The values of these attributes must be of type {@link java.rmi.server.RMIClientSocketFactory} and {@link java.rmi.server.RMIServerSocketFactory}, respectively. These factories are used when creating the RMI objects associated with the connector.

Creating an RMI connector client

An RMI connector client is usually constructed using {@link javax.management.remote.JMXConnectorFactory}, with a JMXServiceURL that has rmi or iiop as its protocol.

If the JMXServiceURL was generated by the server, as described above under "connector addresses generated by the server", then the client will need to obtain it directly or indirectly from the server. Typically, the server makes the JMXServiceURL available by storing it in a file or a lookup service.

If the JMXServiceURL uses the directory syntax, as described above under "connector addresses based on directory entries", then the client may obtain it as just explained, or client and server may both know the appropriate directory entry to use. For example, if the connector server for the Whatsit agent uses the entry whatsit-agent-connector in the RMI registry on host myhost, then client and server can both know that the appropriate JMXServiceURL is:

    service:jmx:rmi:///jndi/rmi://myhost/whatsit-agent-connector
    

If you have an RMI stub of type {@link javax.management.remote.rmi.RMIServer RMIServer}, you can construct an RMI connection directly by using the appropriate constructor of {@link javax.management.remote.rmi.RMIConnector RMIConnector}.

Specifying an ORB for the RMI/IIOP connector

When using the IIOP transport, the client and server can specify what ORB to use with the attribute java.naming.corba.orb. Connection to the ORB happens at {@link javax.management.remote.rmi.RMIConnectorServer#start() start} time for the connector server, and at {@link javax.management.remote.rmi.RMIConnector#connect(java.util.Map) connect} time for the connector client. If the java.naming.corba.orb attribute is contained in the environment Map, then its value (an {@link org.omg.CORBA.ORB ORB}), is used to connect the IIOP Stubs. Otherwise, a new org.omg.CORBA.ORB is created by calling {@link org.omg.CORBA.ORB org.omg.CORBA.ORB.init((String[])null,(Properties)null)}. A later RMI connector client or server in the same JVM can reuse this ORB, or it can create another one in the same way.

If the java.naming.corba.orb attribute is specified and does not point to an {@link org.omg.CORBA.ORB ORB}, then an {@link java.lang.IllegalArgumentException} will be thrown.

The mechanism described here does not apply when the IIOP Remote objects (Stubs or Servers) are created and connected to an ORB manually before being passed to the RMIConnector and RMIConnectorServer.

Dynamic code downloading

If an RMI connector client or server receives from its peer an instance of a class that it does not know, and if dynamic code downloading is active for the RMI connection, then the class can be downloaded from a codebase specified by the peer. The article Dynamic code downloading using Java RMI explains this in more detail.

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.