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