Java Management Extensions (JMX) - Specification v1.2 Errata

This document lists the errors and inconsistencies that have been found in the 1.2 Maintenance Release of the Java Management eXtensions (JMX) specification.

The Reference Implementation of the specification is being updated to reflect these corrections. Independent implementors are encouraged to do so too.

The most important corrections are the first two. The others are minor.

The bug numbers given in parentheses are for internal use by the maintainers of the Reference Implementation.

The changes are as follows. Each change is detailed below.

• Class loader repository may contain additional class loaders
• Illegal identifiers no longer produce exceptions
• Clarify notification source rewriting
• Limit problems due to currencyTimeLimit inconsistency
• Clarify allowed values for ModelMBeanNotificationInfo's severity
• Clarify that value and displayName fields in Model MBean descriptors are optional
• Javadoc error in permissions required by getDomains
• Relation service documentation is too specific about types

Class loader repository may contain additional class loaders (4839389)

The JMX 1.2 spec says that in certain cases the class loader used to find classes is the MBean server's own class loader. This worked well when the JMX API was a stand-alone package, because the MBean server's class loader was usually the system class loader (the one that loads classes from the classpath). Provided the application code was also loaded from the system class loader, classes were found as expected.

The problem is that when it is integrated into J2SE, the MBean server's class loader will be the bootstrap class loader. This class loader will not find application classes. A change is needed so that application code that works with JMX today will continue to work when the JMX API is integrated into J2SE.

As a specific example, here is the simplest way to create an MBean:

    MBeanServer mbs;
    mbs.createMBean(className, objectName);
   

Probably most applications that create MBeans do it this way. The class named by className is loaded using the "class loader repository", which by default contains just the MBean server's class loader. This no longer works if this class is an application class but the MBean server is part of J2SE.

The correction is in the section Order of Loaders in the Class Loader Repository on p143. To the paragraph beginning "The first loader in the class loader repository", add the following sentences:

An implementation may include other class loaders in the class loader repository. It is recommended that implementations include the system class loader in this repository. The system class loader is the one returned by ClassLoader.getSystemClassLoader().

Illegal identifiers no longer produce exceptions (4839259)

Version 1.1 of the spec said that identifiers in MBeans (class name strings, attribute, operation, and paramter names) should be valid Java identifiers, but did not enforce this. In version 1.2, the constructors of the various MBean*Info classes were modified so that they do enforce this requirement. This change broke existing code, as people in fact used non-Java-identifiers here.

The correction is that in the constructors for the classes MBeanAttributeInfo, MBeanConstructorInfo, MBeanFeatureInfo, MBeanInfo, MBeanNotificationInfo, MBeanOperationInfo, MBeanParameterInfo, the exception IllegalArgumentException is no longer thrown for illegal names.

Clarify notification source rewriting (4827539)

In version 1.2 of the spec, it is a little unclear how notification sources are rewritten when a notification is forwarded through the MBean server. The documentation for MBeanServer.addNotificationListener is clear, but the documentation for the Notification class is not.

The correction is to replace the sentence in the Javadoc for the Notification class that begins "It contains a reference to the source MBean" with the following sentence:

It contains a reference to the source MBean: if the notification has been forwarded through the MBean server, and the original source of the notification was a reference to the emitting MBean object, then the MBean server replaces it by the MBean's ObjectName.

Limit problems due to currencyTimeLimit inconsistency (4856291)

Version 1.0 of the spec contained an inconsistency regarding the currencyTimeLimit field in Model MBean descriptors. The PDF spec said that the value 0 meant that the value was not cached, while the value -1 meant that it was cached forever. The Javadoc said the opposite. The RI agreed with the PDF.

In version 1.1, the RI was "fixed" to agree with the Javadoc. The inconsistency with the PDF was unfortunately not noticed at this time.

In version 1.2, the PDF was "fixed" to agree with the Javadoc and RI.

This has led to a hopeless situation where the 1.0 RI and most if not all independent implementations of the spec have the "0 means not cached" semantics (which are also the most logical semantics), while the 1.2 RI and spec have the "-1 means not cached" semantics.

The correction is to warn explicitly against using the special values 0 and -1 for currencyTimeLimit. To say that a value is not cached, omit currencyTimeLimit from the descriptor. To say that a value is cached forever, specify an extremely large value for currencyTimeLimit.

Clarify allowed values for ModelMBeanNotificationInfo's severity (4869006)

In versions 1.0 to 1.2 of the spec, the allowed values for this field are specified inconsistently in the PDF document (0 to 6) and the Javadoc (1 to 5). The correction is to change the Javadoc and the RI to use the range 0 to 6. (Resolving the inconsistency the other way would break code that worked with implementations that followed the PDF.)

Clarify that value and displayName Model MBean fields are optional (4883709)

In the section Predefined Descriptor Fields starting on p96 of the spec, italics are used to denote optional fields. However, some fields which are in fact optional are not shown in italics. These are the value field of attribute descriptors, and the displayName field of operation descriptors.

Javadoc error in permissions required by getDomains (4835226)

The Javadoc in the MBeanServer interface says, about the getDomains permission check:

Additionally, for each domain d in the returned array, if the caller's permissions do not imply MBeanPermission(null, null, new ObjectName(" d:x=x"), "queryMBeans") , the domain is eliminated from the array.

This is a cut-and-paste error. Of course, it should say "getDomains", not "queryMBeans".

Also, this permission should appear in the list (" MBeanPermission actions") on p187 of the spec.

Relation service documentation is too specific about types (4848474)

Relation service doc sometimes says parameters or return values are ArrayList instead of saying just List, even when the declared type is in fact List. For return values, this is implicitly a guarantee that the returned value will in fact be of type ArrayList, so compatibility excludes changing that in the documentation or implementation. But for parameters, the documentation is unnecessarily constraining.

Example: RelationNotification constructor args, RelationServiceMBean.sendRoleUpdateNotification.