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 JMX API now fully supports Generics.
• MXBeans have been added. MXBeans are MBeans that provide a convenient way to bundle related values together without requiring clients to be specially configured to handle the bundles. A defined set of MXBeans already existed in the J2SE 5.0 platform, but Java SE 6 introduces an API to allow you to program your own custom MXBeans. See Introducing MXBeans in the JMX Technology Tutorial for information.
• MBean Descriptors have been added. Descriptors allow you to give additional information about MBeans to management clients. See MBean Descriptors in the JMX Technology Tutorial for information.
• A new class, javax.management.JMX, has been added to house constants and static methods.
• Improvements have been made to the JMX Monitor API to support complex types. Previously, only attributes of simple types could be monitored, but often, the value to be monitored is buried inside a more complex type. See the JMX Specification, version 1.4, for details of the behavior of monitors.
• key=* wildcards are now supported in ObjectName. Previously, "domain:key1=value1,*" could be used to match MBeans that have key1=value1 in their name, but "domain:key1=*" could not be used to match MBeans that have key1 in their name. This is now possible.

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
• MXBeans
• Descriptors
• New class javax.management.JMX
• NotificationBroadcaster and NotificationBroadcasterSupport
• ObjectName
• Standard MBeans
• Dynamic MBeans
• Model MBeans
• Open MBeans
• Monitor Service
• Timer Service
• MLet Service
• Relation Service
• Query
• MBeanServerInvocationHandler
• Serial forms
• Permission checks
• MBean RuntimeException handling
• JMX Remote API Enhancements

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:

• MBeanServer[Connection].queryMBeans returns Set<ObjectInstance>
• MBeanServer[Connection].queryNames returns Set<ObjectName>.
• AttributeChangeNotificationFilter.getEnabledAttributes returns Vector<String>
• AttributeList extends ArrayList<Object>
• MBeanServerFactory.findMBeanServer returns ArrayList<MBeanServer>
• NotificationFilterSupport.getEnabledTypes returns Vector<String>
• The ObjectName class's constructor and getInstance method that formerly took a Hashtable now take a Hashtable<String,String>
• ObjectName.getKeyPropertyList returns Hashtable<String,String>
• openmbean.CompositeType.keySet returns Set<String>
• TabularType.getIndexNames returns List<String>
• Relation.getReferencedMBeans returns Map<ObjectName,ArrayList<String>>
• In RelationServiceMBean:
  • findAssociatedMBeans returns Map<ObjectName,ArrayList<String>>
  • findRelationsOfType returns List<String>
  • getRole returns List<ObjectName>
  • findReferencingRelations returns Map<String,ArrayList<String>>
  • getAllRelationIds returns List<String>
  • getAllRelationTypeNames returns List<String>
  • getRoleInfos returns List<RoleInfo>
  • getReferencedMBeans returns Map<ObjectName,ArrayList<String>>
  • sendRelationRemovalNotification takes List<ObjectName>
  • updateRoleMap takes List<ObjectName>
  • sendRoleUpdateNotification takes List<ObjectName>
  • sendRoleUpdateNotification takes List<ArrayList>
• RelationType.getRoleInfos returns List<RoleInfo>
• MBeanServerNotificationFilter.get{Enabled|Disabled}ObjectNames returns Vector<ObjectName>
• RelationNotification:
  • constructor arg theUnregMBeanList is now List<ObjectName>
  • constructor args the{New|Old}RoleValue are now List<ObjectName>
  • getMBeansToUnregister returns List<ObjectName>
  • get{Old|New}RoleValue returns List<ObjectName>
• RelationService methods specified by RelationServiceMBean have received the same changes as RelationServiceMBean
• RelationSupport methods specified by Relation have received the same changes as Relation.
• RelationTypeSupport.getRoleInfos returns List<RoleInfo>
• Role constructor and getRoleValue use List<ObjectName>
• RoleList extends ArrayList<Object>
• RoleUnresolved uses List<ObjectName>
• RoleUnresolvedList extends ArrayList<Object>
• Timer[MBean].get[All]NotificationIDs returns Vector<Integer>

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:

• javax.management.StandardMBean can now be used for MXBeans as well as Standard MBeans.
• javax.management.MBeanServerInvocationHandler: can now be used for MXBean proxies as well as Standard MBean proxies.
• javax.management.JMX: new class, with 4 new methods.
• javax.management.MXBean: new annotation.
• javax.management.openmbean.CompositeDataInvocationHandler : new class, with 2 new methods.
• javax.management.openmbean.CompositeDataView: new interface, with one new method.
• Class StandardMBean can be used to make an MXBean. Also, this class now implements MBeanRegistration. This allows it to track the name under which an MXBean is registered, in order to handle inter-MXBean references correctly.

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.

• 6289244: Clarify behaviour when null Descriptor parameter to MBeanInfo etc. The specification of the constructors of MBeanInfo and related classes previously stated that a null input value for the Descriptor parameter would produce an empty Descriptor. In fact it is equivalent to an empty Descriptor input value, to which the implementation can add certain standard fields.

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:

  • javax.management.MBeanServerDelegate.DELEGATE_NAME
  • javax.management.ObjectName.WILDCARD

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

• 6392494: Specify that // is reserved in ObjectName domains. It is planned to use the string // in ObjectName domains as part of the "cascading" feature in the next version of the JMX API. A warning has been added to the specification that this string should be avoided, even though the string does not yet have any special meaning to the implementation.

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 Reference Implementation, 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 Reference Implementation 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.

• 6236765: ModelMBeanConstructorInfo says certain fields invalid, but doesn't check. The specification of ModelMBeanConstructorInfo previously said that the persistPolicy and currencyTimeLimit fields were invalid, but the Reference Implementation did not check this. To avoid breaking existing code that might have included those fields, the specification has been changed to say that they are meaningless but are not considered invalid.

• 6241620: DescriptorSupport(String[],Object[]) doc contradictory concerning null parameters. A contradiction in the spec is resolved to reflect the behavior of the Reference Implementation.

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

• 5045358: Allow Open MBeans to reference arrays of primitive type. Previously, the set of types that could be referenced by an Open MBean only included the primitive wrapper types such as java.lang.Integer and java.lang.Boolean. However, it did not include the primitive types such as int and boolean. Arrays of these primitives are now included. The ArrayType class has been extended so that primitive types such as an int[] can be expressed as an OpenType. This new functionality allows MXBeans to map arrays of primitive types in the MXBean interface to the corresponding OpenTypes.

  The following methods have been added to the ArrayType class:

  • javax.management.openmbean.ArrayType.getArrayType(OpenType)
  • javax.management.openmbean.ArrayType.getPrimitiveArrayType(Class)
  • javax.management.openmbean.ArrayType.isPrimitiveArray()
  • javax.management.openmbean.ArrayType(SimpleType,boolean)

  In the constructor ArrayType(int dimension, OpenType<?> elementType), the elementType parameter can now be an ArrayType instance (6252649). The ArrayType.equals and ArrayType.hashcode methods now take the new primitiveArray flag into account.

• 5095277: CompositeDataSupport.equals compares arrays element-by-element. Previously, if two CompositeDataSupport elements each had the same CompositeType containing at least one ArrayType item, calling CompositeDataSupport.equals would only compare the identities of the arrays. Consequently, CompositeDataSupport.equals would only return true if the objects referred to the same array. Now, calling CompositeDataSupport.equals compares the the arrays element-by-element, so it will return true if the two objects refer to different arrays with the same contents. A corresponding change is made to CompositeDataSupport.hashCode.

• 6228130: TabularDataSupport.entrySet() specifies key in the returned Set is wrapped into a List. The documentation was previously unclear about the contents of the returned Set. This is now clarified by making it a Set<Map.Entry<Object,Object>> but detailing that it is in fact a Set<Map.Entry<List<?>,CompositeData>>. For compatibility reasons, the latter declaration is not directly possible.

• 6320104: Add ability to set to UNKNOWN the OperationInfo impact of an Open MBean. The allowed values for the impact of an MBeanOperationInfo are ACTION, INFO, ACTION_INFO and UNKNOWN. The last of these values was previously not allowed for an OpenMBeanOperationInfoSupport.

• 5072004: Better support for schema evolution in CompositeData and CompositeType. Given a CompositeType ct, the method javax.management.openmbean.CompositeType.isValue(x) previously returned true only if x was a CompositeData and x.getCompositeType() was equal to ct. This rule has been relaxed. The type returned by x.getCompositeType() must still have the same name as ct, and it must have all the same items as ct, but it can have additional items. This change also impacts the rules for TabularType.isValue and ArrayType.isValue regarding CompositeData items contained by the TabularData or the array.

• 6333582: OpenType should not declare public static array ALLOWED_CLASSNAMES. This field is deprecated in favour of a new field ALLOWED_CLASSNAMES_LIST.

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.

• 6387340: Remove javax.management.timer.TimerAlarmClockNotification. This class is unusable by code outside the package it is defined in, because its only visible constructor has a parameter whose type is a non-public class. If you call that constructor with a null parameter, you get an immediate exception. Therefore, exceptionally, this public class can safely be deleted from the Java SE API.

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.

• 6223396: MLet support for native libraries is underspecified and should be optional. The specification of MLet.findLibrary has been updated to detail the algorithm used to find native libraries inside jar files, and to add a @throws clause for implementations that do not support this functionality. The PDF specification has been updated similarly (section 8.3.2).

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.

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.

• 6343209: Specify how SubjectDelegationPermission works for ConnectorServer creators. The creator of a JMXConnectorServer no longer needs to have all the permissions that connection created by the connector server will use. It can have a SubjectDelegationPermission for each remotely-authenticated identity instead. This simplifies deployment in security-conscious environments.

• 5021246: Spec for RMI connector should say code downloading used if applicable. The RMI connector will use code downloading as specified in the article Dynamic code downloading using Java RMI if applicable. The Reference Implementation has always behaved this way, and the specification has been updated to reflect that.

• 6375696: CORBA tie classes for JMX Remote API should be in javax.management.remote.rmi For compliance with the OMG's "IDL to Java Language Mapping Specification", the CORBA "tie classes" for the remote objects javax.management.remote.rmi.RMIServerImpl and javax.management.remote.rmi.RMIConnectionImpl should be in the javax.management.remote.rmi package.

• 6231888: JMXConnector implements Closeable The interface java.io.Closeable defines the single method
  public void close() throws IOException; and since JMXConnector contains a method with the same signature, the JMXConnector interface can extend the Closeable interface.

• 6234398: JMX connection provider API exception handling unclear. The interfaces JMXConnectorProvider and JMXConnectorServerProvider are clarified so that methods throw MalformedURLException if the protocol in the URL is not recognized by the provider, JMXProviderException if this is the right provider for the URL but it cannot be used for some reason, and some other IOException in other cases.

• 6238076: Serialized form of javax.management.remote.rmi.RMIConnector included clientNotifID field. This field was inadvertently included in the serial form. Its purpose is to track the notification sequence number in JMXConnectionNotifications from the RMIConnector. An RMIConnector is typically only serialized if it is the value returned by RMIConnectorServer.toJMXConnector, in which case it will not have been connected and will have a sequence number of 0. Even if an RMIConnector is serialized in other circumstances, there is little or no interest in continuing the notification sequence numbers when it is subsequently deserialized.

• 6238815: Add a way to get the address to which a connector client is connected. The new interface JMXAddressable can be implemented by a given connector client. When this is so, users can cast the JMXConnector instance to JMXAddressable and call getAddress() to discover the address to which the client is connected. RMI client connectors are specified to implement this interface. The JMXConnectorServer class also implements this interface, via its existing getAddress() method.

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