Change Log for JSR 3 Maintenance Review 3

Éamonn McManus, JSR 3 Maintenance Lead

This is the Change Log for the third Maintenance Review of JSR 3. Questions and comments on this Change Log should be directed to jmx-spec-comments@sun.com.

This Maintenance Review defines version 1.3 of the JMX API as originally defined by JSR 3.

The 7-digit code numbers associated with each change are identifiers in the public bug database at bugs.sun.com.

A larger set of updates to the JMX specification is planned as part of JSR 255, "JMX Specification, version 2.0". The changes proposed in this Maintenance Review are intended as interim steps towards JSR 255. These changes have all been approved by the JSR 255 Expert Group.

An updated standalone TCK will be available that reflects the changes in this Maintenance Review. In addition, it is intended that these changes will be included in the Java SE 6 ("Mustang") release.

Contents

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.