Find JSRs
Submit this Search


Ad Banner
 
 
 
 

 Change Log for JSR 3 Maintenance Review 3

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.

  • 6255956: Descriptor defines equals method and specifies how array values are compared. The Descriptor interface specifies an equals method and its two concrete implementations implement it. This means that MBeanInfo etc can continue to be compared for equality taking the Descriptors into account. So that different implementations of Descriptor can be mixed, a hashCode() method is also specified and implemented.

  • 6267824: Clarify order the returned array is sorted with when calling Descriptor.getFieldValues(null). Previously it was not specified what order the returned values were in.

  • 6273765: Descriptor.getFieldValues(non-empty-array) on an empty descriptor has no special behavior. The array returned by this method has as many elements as there are parameters, with each element being the value associated with the corresponding parameter, or null if there is no such value.

    Through an oversight or an editing error, the @returns clause of this method previously said: If the descriptor is empty, you will get an empty array. Almost certainly, what was meant was that if the list of names is empty, you will get an empty array. As specified, there was a pernicious special case: if some or all of the names in the list are missing from the Descriptor, the corresponding elements in the returned array will be null, except if the Descriptor is empty, in which case there won't be any elements in the array.

    This special case did not show up in the existing use of Descriptors for Model MBeans, because empty Descriptors were not valid in any of the places where they were used. (Every Descriptor had to have at least the "name" and "descriptorType" entries.) However, this is no longer true for the more generalized use of Descriptors. The previously-specified behavior would therefore have generated hard-to-find bugs.

  • 6273613: Specify exception wrapping for Descriptor.setField and Descriptor.setFields. These methods were previously declared to throw RuntimeOperationsException but the specification did not say what the wrapped exception was.

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.

  • 4506105: Previously, to specify the types of notifications that could be sent, it was necessary to subclass NotificationBroadcasterSupport and override the getNotificationInfo() method. In this release, new constructors have been added, that take a MBeanNotificationInfo... as input.

  • 4661545: Previously, the specification was very vague about whether the notification dispatch model was synchronous or asynchronous. When a thread called sendNotification, the NotificationListener.handleNotification method of each listener might be called within that thread (a synchronous model) or within some other thread (an asynchronous model), depending on the class implementation. J2SE 5 implemented the synchronous model, meaning that NotificationBroadcasterSupport used the sender thread to send the notification to all listeners. Users had to create a subclass to override the method handleNotification if they wanted an asynchronous model.

    In Java SE 6, the default model is still synchronous. A constructor has been added to the class NotificationBroadcasterSupport to take a java.util.concurrent.Executor as a parameter. The Executor is used to dispatch the notification to its listeners. This allows users to avoid creating a subclass if they want the asynchronous model.

  • A third constructor combines the functionality of the above two, with both an Executor and an MBeanNotificationInfo... as parameters.

  • 6244863: Specify what happens with NotificationBroadcasterSupport if a filter or listener throws an exception. Previously, the JMX specification did not define what happens when the listeners or filters maintained by a notification broadcaster threw an exception. This behavior has now been specified. An Exception does not prevent other listeners from being invoked. But an Error is propagated to the caller of sendNotification.

  • 6252526: A new class, javax.management.StandardEmitterMBean, has been added. StandardEmitterMBean is a subclass of javax.management.StandardMBean that is a NotificationEmitter.

ObjectName

A number of changes concern the class ObjectName.

  • 4716807: Support key=* wildcard in ObjectName. Previously, it was possible to say domain:key1=value1,* to match MBeans that have key1=value1 in their name, but not domain:key1=* to match MBeans that have key1 in their name. The ObjectName functionality has been extended in this release, so that you can put a wildcard (* and/or ?) anywhere in a value.

    Two new methods, isPropertyValuePattern() and isPropertyValuePattern(String property), allow you to discover whether an ObjectName has a wildcard in the value of some property, and if so which property it might be.

  • 4780400: Two new ObjectName constants added. Users of the JMX API very often need to refer to two ObjectName constants:

        new ObjectName("JMImplementation:type=MBeanServerDelegate")
    new ObjectName("*:*")

    The first of these is hard to remember, and if you get it wrong then your code compiles but doesn't work. Both of these suffer from the problem that the ObjectName constructors throw the checked exception MalformedObjectNameException, so you end up having to wrap your constant in a try/catch block.

    To remedy this situation, two new constants have been added in this release:

  • 5036680: ObjectName implements Comparable<ObjectName>. By implementing Comparable we allow a SortedSet to show its contents in a reasonable order without having to define a custom Comparator. See ObjectName.compareTo(ObjectName).

Standard MBeans

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

  • 4949203: Correct text about invoking getters and setters. The JMX 1.2 specification document was supposed to clarify, per the Maintenance Review change list, that getters and setters in a Standard MBean cannot be invoked through MBeanServer.invoke. But the text to this effect erroneously appeared in the section about Dynamic MBeans. It should obviously be in the section about Standard MBeans.

    Also, this text mentioned the property "jmx.invoke.getters". Since it appears in the spec, one might conclude that an implementation is required to respect this property. But that's not what was stated during the Maintenance Review and it's not what was intended. Rather, this property is a feature of the Reference Implementation to ease the transition for code that may have incorrectly relied on being able to invoke getters before. So it should appear in the Release Notes of the RI, not in the spec.

  • 6190628: Standard MBeans support covariant return types in MBean interfaces. J2SE 5 introduced covariant return types in classes and interfaces. However, MBean servers would reject Standard MBeans created with covariant types as they would appear inconsistent. In this release, covariance is allowed for operations (methods other than getters and setters) and for read-only attributes (getters without corresponding setters).

Dynamic MBeans

The following changes have been made concerning Dynamic MBeans.

  • 6306219: Clarify MBeanServer.isInstanceOf semantics for Dynamic MBeans. The specification of this method omitted an important case where it should return true, namely where the MBean's ClassLoader can load the named class and the MBean is an instance of that class. The RI did in fact return true in this case. It makes a difference when a DynamicMBean returns in its MBeanInfo a class name of which it is not an instance. For example, an instance of javax.management.StandardMBean (which is a DynamicMBean) could return an MBeanInfo whose getClassName() returned "javax.management.timer.TimerMBean". Under the current specification, the call mbeanServer.isInstanceOf(objectName, "javax.management.StandardMBean") would then return false, since TimerMBean is not an instance of StandardMBean. In fact, it returns true, since the actual MBean object is an instance of StandardMBean.

    With the addition of the class StandardEmitterMBean, and the existing practice of using isInstanceOf to determine whether an MBean is a NotificationBroadcaster, it becomes important to change the spec to reflect the implementation. A StandardEmitterMBean will typically return an MBeanInfo with a class name that is not an NotificationBroadcaster; however, we want isInstanceOf(..., "javax.management.NotificationBroadcaster") to return true.

Model MBeans

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

  • 4883709: "value" and "displayName" fields in Model MBean descriptors should be in italics. This is a bug in the PDF spec. Optional fields are supposed to be in italics but these ones were not.

  • 4997033: RequiredModelMBean.setAttribute should throw exception if no setMethod and no currencyTimeLimit. This change resolves a contradiction between the PDF and Javadoc texts. The specification is clarified so that an exception is thrown only when there is no setMethod and no caching, so that the setAttribute operation would have no effect.

  • 5043245: Attribute type check is too restrictive in RequiredModelMBean.getAttribute(). The specification was unclear as to whether the returned value had to be of the exact type declared for the attribute or could be of a subtype. It is changed to allow a subtype explicitly.

  • 5046781: Spec should say role field in ModelMBeanOperationInfo descriptor is optional. The PDF spec is clarified to allow this field to be omitted, reflecting the behavior of the Reference Implementation.

  • 5046784: Value of targetType in Model MBean descriptors is case insensitive. Although the specification implied through its examples that this field is case-insensitive, it was omitted from the explicit list of case-insensitive fields.

  • 5104947: Clarify whether ModelMBeanInfoSupport.clone is deep or shallow. The specification is modified to state the existing behavior whereby the clone is shallow.

  • 6175387: Add new OnUnregister persistPolicy value to Model MBean descriptor. When persistence is supported for Model MBean data, you can define how it works using a persistPolicy value in the Descriptor for an MBean attribute. Previously, these values were Never, OnUpdate, OnTimer, NoMoreOftenThan, and Always. This release has added a new value, OnUnregister, that means that the value of the attribute is persisted when the MBean containing it is unregistered from the MBean Server. The specification of the methods that consult this field has been updated accordingly, as has the list of persistPolicy values that do not result in a store in RequiredModelMBean.store() and RequiredModelMBean.setAttribute.

  • 6241620: DescriptorSupport(String[],Object[]) doc contradictory concerning null parameters. A contradiction in the spec is resolved to reflect the behavior of the RI, which was already required by the TCK.

  • 6332962: Problem serializing DescriptorSupport containing targetObject field. A Descriptor for an attribute or operation in a Model MBean can contain a targetObject field to direct accesses to that attribute or operation towards a different resource from the one defined for the Model MBean as a whole. As such, its value is often a non-serializable object, and in any case it does not make sense to serialize it. Therefore the spec is updated to exclude it from the serialization of DescriptorSupport so that RequiredModelMBean.getMBeanInfo() returns a serializable object.

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

  • 6222961: Monitor Service supports complex types. Previously with the Monitor Service, you could only monitor an attribute of simple type. Often, the value you want to monitor is buried inside a more complex type. For example, if you are dealing with the J2EE instrumentation defined by JSR 77, then to set a monitor on a servlet's service time, you want to get the ServiceTime attribute for the servlet and monitor serviceTime.getMaxTime(). The spec is changed so that you can monitor ServiceTime.maxTime to get this effect. The detailed specification is in javax.management.monitor.

  • 6239455: Specify that monitor tasks are run within the access control context of the monitor.start() caller. When security is active, the security checks carried out to see if the caller has access to the attribute or to any security protected operation the attribute implementation might perform are based on the access control context of the monitor.start() caller and not on the access control context of the monitor creator. This is stated in the package documentation for javax.management.monitor.

Timer Service

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

  • 6235077: javax.management.timer.Timer doc was inconsistent about what happens for Date in the past. Prior to version 1.2 of the JMX Specification, the Timer service was defined to throw an exception if a notification was scheduled for a time in the past. Starting from version 1.2, the more logical behaviour of sending the notification immediately in this case was introduced. However, some of the documentation for javax.management.timer.Timer still reflected the old behaviour. In particular, the Notes in the class documentation included one that said that past-time notifications will be ignored, and the @throws documentation for the IllegalArgumentException said it was thrown for a past date.

MLet Service

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

  • 4796780: MLetContent class should be public. In the last release, the MLet.check method was made public, but one of its parameters was of type javax.management.loading.MLetContent, and that class remained private. This introduced an inconsistency in that a publicly-visible method referenced a non-visible class. This has been corrected by making MLetContent public.

Relation Service

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

  • 4892674: Problem serializing RelationNotification. The RelationNotification constructors required their source parameter to be an instance of RelationService, relying on the MBean Server to rewrite this to the ObjectName of the RelationService before forwarding the notification to users. This is fragile, and in particular makes it hard to reconstruct a RelationNotification instance, for example from a serialized XML form. The constructor is modified to also allow the source to be an ObjectName.

  • 5053367: RelationService.addRelationType spec rejects null relation type name. RelationService.addRelationType (and RelationServiceMBean.addRelationType) are explicitly specified to throw IllegalArgumentException if the RelationType argument returns null from its getRelationTypeName(). RelationService.addRelationType (and RelationServiceMBean.addRelationType) are explicitly specified to throw IllegalArgumentException if the RelationType argument returns null from its getRelationTypeName(). The other RelationService methods that take a relation type name are all specified to reject a null name. Thus if addRelationType allowed one, you would end up with a RelationType that you could do nothing with. In particular, you couldn't even remove it again.

  • 6229880: RelationSupport javadoc was unclear. RelationSupport.setRole specified that a RoleNotFoundException is thrown if the role is not writable. In fact, a RoleNotFoundException is also thrown when there is no defined role for the given name (same condition as the getRole method).

    RelationSupport.setRoles specified that an IllegalArgumentException was thrown if the role name was null. This should be the role list.

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:

  • 6177524: MBeanServerInvocationHandler no longer forwards Object methods to proxied MBean. Previously, MBeanServerInvocationHandler forwarded the methods hashCode(), toString(), and equals(Object) to proxied MBeans, meaning that an MBean proxy could not be used as a key in a HashMap (for example to look up a cached MBeanInfo for the proxy). MBeanServerInvocationHandler now only forwards these methods if they are explicitly mentioned in the MBean interface for which it is a handler. The javax.management.MBeanServerInvocationHandler.invoke method has been updated to examine the MBean interface to check whether it contains the methods in question.

  • 6278707: MBeanServerInvocationHandler acquires getters to retrieve its constructor parameters. These are the new methods getMBeanServerConnection(), getObjectName(), and isMXBean().

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.

  • 6253903: Specification for JMX API lists serialVersionUID of all serializable classes. For implementation reasons, the Serialized Form page from the Javadoc-generated specification omits the serialVersionUID of certain classes. Independent implementations need this information for compliance, so where necessary it has been supplied in the specification of the classes themselves.

  • 6344759: Mandate more clearly the 12 javax.management.*Exp private classes. For interoperation between implementations, the value returned by the various static Query.* methods (such as Query.and) must be of a given non-public class, or at least must serialize as such. The specification of these methods is updated accordingly.