Java Management Extensions API Enhancements






Documentation Contents



JMX API Enhancements








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 © 1995-2010 Sun Microsystems, Inc. All Rights Reserved. Please send comments using this Feedback page.

Java Technology