The number one question I get about the JMX API at conferences
and other public events is whether there will be support for
defining MBeans using annotations. People see that they can
make EJBs or Web Services just by adding annotations to a POJO,
and they ask why they can't make MBeans the same way. In
version 2.0 of the JMX API, being defined by JSR 255, this
will be possible.
The exact details are still subject to change as a result of
discussions within the JSR 255 Expert Group, but here's a snapshot
of where we are now. I think the final version will be fairly
close to this.
In addition to defining MBeans with annotations, there are some
new proposed annotations that will also apply to MBeans defined
in the existing ways.
Prior art
Several projects already exist that provide this functionality,
but the most developed is probably Spring. So our starting point
was Spring's
MBean annotations (see also API
documentation).
Defining an MBean
In the proposed design, an MBean can be defined through
annotations to achieve the same effect as a Standard
MBean. In this and other examples, I'll show what you write
with today's API, and what you'll be able to write with the new
annotations.
| Today | Tomorrow |
|---|
public interface CacheMBean {
public int getSize();
public void setSize(int size);
public int getUsed();
public int dropOldest(int n);
}
public class Cache implements CacheMBean {
public int getSize() {...}
public void setSize(int size) {...}
public int getUsed() {...}
public int dropOldest(int n) {...}
} |
@MBean
public class Cache {
@ManagedAttribute
public int getSize() {...}
@ManagedAttribute
public void setSize(int size) {...}
@ManagedAttribute
public int getUsed() {...}
@ManagedOperation
public int dropOldest(int n) {...}
} |
This defines an MBean with read-only attribute Used,
read-write attribute Size, and operation
dropOldest.
I'll call an MBean defined this way an @MBean.
One way to look at this is that with the existing Standard MBeans,
public methods from the class are picked out as being management
methods by virtue of being in the Standard MBean interface that
the class implements. So in this example the
CacheMBean interface defines which methods in
Cache are the management methods. In the new form,
the methods are picked out by being annotated, and there is no
need to define an interface.
Pros and cons of @MBeans
The new style appears considerably more convenient than
Standard MBeans. You only have to maintain one source file,
rather than managing a class and an interface.
There is a downside, however, which may show up in bigger
projects. The advantage of the Standard MBean approach is that
the MBean interface tells you exactly what the attributes and
operations of the MBean are. There is no extraneous information
in the MBean interface: every method defines an attribute or an
operation.
On the other hand, with @MBeans the management attributes and
operations are potentially mixed in with many other methods,
public or private. So it is not immediately obvious what the
management interface of the MBean is.
This disadvantage applies both when reading the source code and
when looking at the Javadoc output.
A second disadvantage is that it is no longer possible to
construct a proxy.
Proxies simplify client code by allowing it to access attributes
and operations as compiler-checked method calls. They don't
matter if you are only going to interact with your MBeans
through a graphical interface like JConsole,
but they are a big help if you are writing an application that
will interact with your MBeans specifically.
For smallish projects, these disadvantages are likely to be
minor. Furthermore, it should be possible to define an annotation
processor that extracts a Standard MBean interface from an
@MBean, so it can be used for documentation and proxying. In
the example above, the annotation processor could create the
CacheMBean interface every time you compile your
program, based on the @ManagedAttribute and
@ManagedOperation annotations in the
Cache class.
Defining an MXBean
The existing @MXBean
annotation can be used instead of @MBean to define
an MXBean
rather than a Standard MBean.
@MXBean
public class Cache {
...remainder as above...
}
Descriptions
Although the JMX API allows for textual descriptions to be
associated with attributes, operations, and parameters, when you
use a Standard MBean today these descriptions have meaningless
default values. I've written before
about how you can add meaningful descriptions, but it isn't
easy. This is a really obvious use for annotations.
The proposed new @Description annotation can be used with
Standard MBeans, MXBeans, and @MBeans. (Notice that both
columns use the new API here!)
| Tomorrow's Standard MBean | Tomorrow's @MBean |
|---|
@Description("some sort of cache")
public interface CacheMBean {
@Description("number of cache slots in use")
public int getUsed();
...
}
public class Cache implements CacheMBean {
public int getUsed() {...}
...
} | @Description("some sort of cache")
public class Cache {
@ManagedAttribute
@Description("number of cache slots in use")
public int getUsed() {...}
...
}
|
We international types will of course be thinking about
internationalization, and I'll have more to say about that below.
Finding the MBeanServer and/or ObjectName
Often an MBean needs to know what MBean Server it is registered
in, or what its name is in that MBean Server. To do this it
currently needs to implement the MBeanRegistration
callback interface. The required values are passed to that
interface's preRegister
method. But the interface contains three other methods, which
the MBean must implement even if it has nothing interesting to
do in them.
In the new proposal, the @Resource
annotation from javax.annotation
can be used instead of implementing
MBeanRegistration when all that's needed is to
discover what the MBeanServer or ObjectName is:
| Today | Tomorrow |
|---|
public class Cache
implements CacheMBean, MBeanRegistration {
private volatile MBeanServer mbs;
private volatile ObjectName myName;
public ObjectName preRegister(
MBeanServer mbs, ObjectName name) {
this.mbs = mbs;
this.myName = name;
return name;
}
public void postRegister(Boolean done) {}
public void preDeregister() {}
public void postDeregister() {}
...
} | @MBean
public class Cache {
@Resource
private volatile MBeanServer mbs;
@Resource
private volatile ObjectName myName;
...
}
|
When the MBean is registered, the MBean Server will inject
the appropriate values into these fields.
This possibility is open to all types of MBeans, not just
@MBeans. You could continue to have a Standard MBean as today,
but stop implementing MBeanRegistration in favour
of @Resource annotations.
Simplified notification handling
Today, if an MBean emits notifications then it must implement
the NotificationBroadcaster
or NotificationEmitter
interface. This means it must keep track of the set of listeners,
as listeners are added
and removed.
It must also define the list of notification types that it can
emit, by implementing getNotificationInfo().
In practice, everybody uses the NotificationBroadcasterSupport
class instead of doing all this work themselves. In the simplest
case, you just inherit from that class, and pass the list of
notification types to the superclass constructor. If you already
have a superclass, then you need to have a private
NotificationBroadcasterSupport instance and delegate
the NotificationBroadcaster methods to it.
New annotations allow you to define the list of notification
types more simply, and to emit notifications without having to
keep track of listeners.
| Today | Tomorrow |
|---|
public class Cache
extends NotificationBroadcasterSupport
implements CacheMBean {
public Cache() {
super(new MBeanNotificationInfo[] {
new MBeanNotificationInfo(
new String[] {"my.notif.type"},
Notification.class.getName(),
"my notification"
)}
);
}
...
void somethingHappened() {
Notification n = new Notification(...);
super.sendNotification(n);
}
...
} | @MBean
@NotificationInfo(types={"my.notif.type"},
description=@Description("my notification"))
public class Cache {
@Resource
private volatile SendNotification send;
...
void somethingHappened() {
Notification n = new Notification(...);
send.sendNotification(n);
}
...
}
|
The @NotificationInfo annotation is what allows
you to avoid constructing an MBeanNotificationInfo
as in the messy "Today" code.
The new SendNotification interface contains just
the method sendNotification.
When you register this MBean in the MBean Server, it will inject
an object into the send field which allows the MBean
to send notifications. The MBean no longer has to be concerned
with managing listeners, which happens somewhere behind the
scenes.
Resource injection of SendNotification is
available to all types of MBeans. Defining the notification types
with @NotificationInfo is not available to Dynamic
MBeans, which are expected to provide a complete MBeanInfo,
including the MBeanNotificationInfo[] array.
More detail than you want to know about
@NotificationInfo appears below.
You can stop reading now
If your eyes are already glazing over with all this code, you
can safely stop here, and you'll have seen the main ideas. The
remainder of this entry is about secondary items, and further
details about the main ones.
Descriptor contents
In the JMX API included in the Java SE 6 platform, we
introduced a way to define your own annotations to specify
Descriptor contents. So you might define @Units like this:
@Documented @Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Units {
@DescriptorKey("units")
String value();
}
The new API accepts such annotations on classes or methods that
also have the @ManagedX annotations. For example:
@MBean
public class Cache {
...
@Units("bytes")
@ManagedAttribute
public int getUsed() {...}
...
}
We've also added a new @DesriptorFields
annotation, since the use of @DescriptorKey is
somewhat non-obvious, and overkill for occasional use. So you
can achieve the same effect like this:
@MBean
public class Cache {
...
@DescriptorFields("units=bytes")
@ManagedAttribute
public int getUsed() {...}
...
}
This annotation can be used in Standard MBeans and MXBeans as well
as @MBeans and @MXBeans.
Operation impact
The @ManagedOperation annotation has an optional element impact
of type Impact. This is a new enum with values
{INFO, ACTION, ACTION_INFO, UNKNOWN} corresponding
to the integer codes defined by MBeanOperationInfo.
So you can do this:
@MBean
public class Cache {
...
@ManagedOperation(impact = Impact.ACTION)
public int dropOldest(int n) {...}
}
You can also apply @ManagedOperation to a method in a
Standard MBean interface or an MXBean interface in order to
specify the impact.
MBean constructors
Each public constructor in an @MBean or @MXBean is converted into an
MBeanConstructorInfo inside the MBean's
MBeanInfo. This is exactly the same as for
existing Standard MBeans and MXBeans.
StandardMBean class
The class StandardMBean
can be used to customize an @MBean or an @MXBean in the same way
as for a Standard MBean or MXBean today. You simply supply
null for the mbeanInterface parameter in
the constructor.
Details on Resource injection
The @Resource annotation can be used to inject an
ObjectName, MBeanServer, or
SendNotification. The annotation can be applied to
a field or to a void method with a single
parameter. For example:
@Resource // field injection
private volatile ObjectName name;
private MBeanServer mbs;
@Resource // method injection
private synchronized void setMBeanServer(MBeanServer mbs) {
this.mbs = mbs;
}
The MBean Server determines what to inject based on the
type. The type is either the declared type of the field or
parameter, or it is specified explicitly in the
@Resource annotation. For example, the following
annotations have the same effect:
@Resource
private volatile ObjectName name;
@Resource(type = ObjectName.class)
private volatile Object name;
I don't think the second form will be used very often, but it might
be used to inject the MBeanServer into a field of
type MBeanServerConnection, for example.
The ObjectName (etc) will be injected as many times as there are
appropriate @Resource annotations, including in parent
classes.
@Resource annotations that don't match one of the given
types are ignored. (Perhaps they are for some other API.) But
even if the type is not recognized, @Resource
fields and methods must be instance (not static), and
@Resource methods must have exactly one parameter
and return void.
I've used volatile in all these examples because the Java Memory
Model would not otherwise guarantee that the MBean would actually
see the injected values. For method-based injection,
synchronized is an alternative, provided the MBean
also uses synchronized to access the injected
value. Notice that the same considerations apply to the
existing MBeanRegistration technique.
Resource injection happens after the MBean's preRegister
method (if any) is called, but before the MBean is registered in the
MBean Server. If an injection method throws an exception, then postRegister(false)
will be called and the exception will be thrown in the same way
as for preRegister.
More on descriptions
In addition to the description text, the @Description
annotation can specify the values of the descriptionResourceBundleBaseName
and descriptionResourceKey fields in the corresponding Descriptor.
This is enough to allow for internationalization:
@Description(value="some sort of cache",
key="cache.mbean.description",
bundleBaseName="MyResources")
To complete the story here, we need to have something that is
able to apply these Descriptor fields to localize the
MBeanInfo. We have some ideas on what that
something might look like, but they are not yet fully
formed.
More on @NotificationInfo
As I threatened, here is more information than you wanted to
know about @NotificationInfo.
If an MBean has a @NotificationInfo annotation, then that
annotation is translated into an MBeanNotificationInfo
in the MBean's MBeanInfo.
MBeanNotificationInfo includes a name
which is the name of the notification class. It is usually
"javax.management.Notification", but it might be a
subclass. So @NotificationInfo has an optional
notificationClass element which is a
Class<? extends Notification>. For
example:
@NotificationInfo(types = {AttributeChangeNotification.ATTRIBUTE_CHANGE},
notificationClass = AttributeChangeNotification.class)
If the MBean can emit more than one class of MBean, then it can
use @NotificationInfos:
@NotificationInfos(
@NotificationInfo(types = {"my.first.notif", "my.second.notif"})
@NotificationInfo(types = {AttributeChangeNotification.ATTRIBUTE_CHANGE},
notificationClass = AttributeChangeNotification.class)
)
The @NotificationInfo is applied to an MBean
class, but a @Description on that class applies to
the MBean, not its notifications. The existence of
@NotificationInfos is another reason why we cannot
use @Description straightforwardly.
This is why there is an optional element of type
@Description
inside @NotificationInfo, so you would write:
@NotificationInfo(types={"my.notif.type"},
description=@Description(value="my notification", key="my.notif.descr"))
You cannot use @DescriptorFields, for the same
reason as @Description, so there's another optional
element that allows you to write:
@NotificationInfo(types={"my.notif.type"},
descriptorFields={"foo=bar"})
Ideas still in progress
We're studying the possibility of providing a way to cause a
notification that is sent every time a given operation is
completed.
We're looking at ways in which an MBean could say what its ObjectName
is. Probably the MBean would only provide a subset of the
information needed to construct the name. It's still unclear
exactly what this might look like.
What next?
This is still work in progress, as you'll have gathered. I'm
very much interested in comments and suggestions, either here or
at jmx-spec-comments@sun.com.
Thanks!
[Tags:
jmx
jsr
jsr255
annotations]
]]>
