Java (tm)

JMX API Enhancements

Documentation Contents

The Java Management Extensions (JMX) technology became a part of the Java platform in the Java 2 Platform, Standard Edition (J2SE) 5.0. The most significant enhancements that have been made to the JMX API in the Java Platform, Standard Edition (Java SE) 6 are listed below.

The following is the full list of changes made to the JMX API in the Java SE 6 platform. Where relevant, links to the related bug report or request for enhancement (RFE) are included.

Generification

Constraints due to the integration of version 1.2 of the JMX API in both J2EE 1.4 and J2SE 5.0 meant that it could not be generified in the latter. This is now rectified (4847959). Most of the generification consists of application of the generified collections API (java.util.List, and so on). So for example, where MBeanServer.queryNames previously returned just Set, it now returns Set<ObjectName>. The javax.management.openmbean.OpenType class and its subclasses have also been generified to allow type constraints to be expressed. OpenMBeanAttributeInfoSupport and OpenMBeanParameterInfoSupport acquire type constraints in their constructors such that the default or legal values must be of the correct type. The StandardMBean constructor likewise acquires a type constraint so that the resource parameter must implement the interface specified by the interface parameter.

The following classes and methods have been updated:

MLetMBean and MLet's getMBeansFromURL methods cannot use generics because the elements of the returned Set can be either ObjectInstance or Throwable. AttributeList, RoleList, and RoleUnresolvedList extend ArrayList<Object> rather than the more natural ArrayList<Attribute> etc., because the latter would introduce an inconsistency due to the existing add and set methods which return void rather than boolean and Object, respectively.

New methods AttributeList.asList(), RoleList.asList(), and RoleUnresolvedList.asList() produce a List view of the underlying object with the correct type parameter. A new constructor AttributeList(List<Attribute>) converts in the opposite direction (RoleList and RoleUnresolvedList already had such constructors).

A detailed generification rationale details the choices that were made during generification of the API.

MXBeans

Previously, portable modelling of complex types had to be performed using Open MBeans, which are difficult to use. A feature, MXBeans, was added in J2SE 5 to make modelling with complex types easier. In this release, MXBeans have been generalized (6175517). MXBeans are a special kind of Standard MBean that provide a non-identity mapping between types in the Java interface and types in the management interface. In the same way as for Standard MBeans, MXBeans contain attributes that are defined by getX and setX methods, and other methods are operations. With MXBeans, however, the MBean that is actually registered in the MBean Server does not have exactly the same types for its attributes and operation parameters and return values. Instead, each type that occurs in the MXBean interface is converted to a type built from the fixed set defined in javax.management.openmbean. The MBean that is actually registered in the MBean Server is an Open MBean that references these converted types. When it is accessed, it converts values between the original MXBean interface type and the converted Open MBean type.

In this way, a client can access an MXBean without needing to know any model-specific types that might be referenced in the MXBean interface. The client only needs to know the standard Open MBean types.

The complete MXBean specification appears in the documentation for the annotation @MXBean.

The introduction of MXBeans has added or affected the following classes and interfaces:

Descriptors

Descriptors can be used to supply additional metadata about an MBean. Previously, only Model MBeans supported Descriptors. In this release, support for Descriptors has been extended to all types of MBean (6204469). In addition to the general utility of metadata for all types of MBeans, the change removes certain gratuitous differences between various kinds of MBeans. In particular, it makes it feasible to have an MBean that is both an Open MBean and a Model MBean.

For most constructors in the classes MBean*Info (MBeanInfo, MBeanAttributeInfo, etc), a parallel constructor has been added with the same parameters plus an additional Descriptor parameter. Likewise for OpenMBean*InfoSupport.

Open MBeans return information about default and legal values from the getDefaultValue(), getLegalValues(), getMaxValue(), getMinValue() methods of OpenMBeanParameterInfo and OpenMBeanAttributeInfo. This information is now also present in the corresponding Descriptors, and other types of MBean can also return the information in their Descriptors.

A parent interface of DescriptorAccess called javax.management.DescriptorRead has been added, that contains the getDescriptor method but not the setDescriptor method. The MBean*Info classes implement DescriptorRead.

A second, immutable implementation of the Descriptor interface called javax.management.ImmutableDescriptor has also been added. This preserves the property that all MBeans except Model MBeans have immutable metadata.

A number of new conventional Descriptor items ("fields") are documented in the Descriptor specification (6254721). Some of these items must be understood by the implementation (in italics in the specification) while others are left uninterpreted. The predefined field names have corresponding string constants in the new JMX class (6282502).

A new annotation DescriptorKey can be used to add information to the Descriptors for a Standard MBean (or MXBean) via annotations in the Standard MBean (or MXBean) interface (6221321). This makes it possible for a tool that generates Standard MBeans from an existing management model to include information from the model in the generated MBean interfaces, rather than in separate files.

The method Descriptor.getFieldValues(String...) and the constructor DescriptorSupport(String...) previously took a String[] parameter. The varargs syntax makes them easier to use.

A number of other changes have been made regarding descriptors, as follows.

New class javax.management.JMX

A new class javax.management.JMX has been added to house constants and static methods.

NotificationBroadcaster and NotificationBroadcasterSupport

A number of changes concern the interface NotificationBroadcaster and its default implementation NotificationBroadcasterSupport.

ObjectName

A number of changes concern the class ObjectName.

Standard MBeans

The following changes have been made to the specification of Standard MBeans.

Dynamic MBeans

The following changes have been made concerning Dynamic MBeans.

Model MBeans

A large number of small changes are applied to the specification for Model MBeans.

Open MBeans

Many of the changes to Open MBeans were inspired by the addition of user-defined MXBeans. Here is the complete set of changes.

Monitor Service

The following changes are made to the specification of the Monitor Service (package javax.management.monitor).

Timer Service

The following changes are made to the specification of the Timer Service (package javax.management.timer).

MLet Service

The following changes are made to the specification of the MLet Service (package javax.management.loading).

Relation Service

The following changes are made to the specification of the Relation Service (package javax.management.relation).

Query

The new javax.managent.Query.isInstanceOf(StringValueExp className) method allows users to get all MBeans that are instances of a specific class (5072174).

MBeanServerInvocationHandler

The following changes are made to the specification of MBeanServerInvocationHandler:

A new method JMX.newMBeanProxy provides an easier-to-remember alternative to MBeanServerInvocationHandler.newProxyInstance.

Serial forms

The specification of the serial form of the classes in the JMX API has been clarified as follows.

Permission checks

The JMX specification previously said that permission checks were made if and only if there is a non-null SecurityManager. This has been changed to say that an implementation is free not to make checks if there is no SecurityManager. In other words, an implementation may now choose to make checks even in the absence of a SecurityManager. (6419572)

MBean RuntimeException handling

The JMX spec was unclear as to what happens when a method implementing an attribute or an operation in an MBean throws a RuntimeException (5043152). Close reading implied that it should wrap the exception in a RuntimeMBeanException, but it was not completely clear that it could not wrap it in a RuntimeOperationsException. The spec now explicitly says that it is a RuntimeMBeanException, and that RuntimeOperationsException wraps exceptions that occur before any MBean method is invoked, e.g. getAttribute with a null attribute.

Model MBeans wrap exceptions coming from methods invoked on the ManagedResource in RuntimeOperationsException, not RuntimeMBeanException.
Although this was not clearly specified, changing it would risk breaking existing code. So the existing behaviour is specified explicitly, and also that when an MBean throws a RuntimeOperationsException it is not further wrapped.

JMX Remote API

The following changes are made to the specification of the JMX Remote API.


Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Feedback
Sun