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.
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.
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:
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 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.
A new class
javax.management.JMX has been added to house
constants and static methods.
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.
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 SortedSetObjectName.compareTo(ObjectName).
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).
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.
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.
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:
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.
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.
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.
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.
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.
The new
javax.managent.Query.isInstanceOf(StringValueExp
className) method allows users to get all MBeans
that are instances of a specific class (5072174).
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.
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.