Jerome/Kohsuke et al,
[More to come on this area, this just covers proposed annotations.]
Below are two proposed annotations for supporting MBeans
(ObjectNameInfo and MBeanMetadata). The idea is that @Configured
interfaces (and possibly other classes) would be annotated in order
to obtain automated support for registration as an MBean (AMX or
not), following the required conventions. The framework knowledge of
containment (parent/child) would also be used to complete the
ObjectName.
Example of an annotated ConfigBeanProxy interface (all annotation
fields included for clarity):
@Configured
@ObjectNameInfo(jmxDomain="amx",
j2eeType=XTypes.VIRTUAL_SERVER_CONFIG, singleton=false,
objectNameBuilder="")
@MBeanMetadata(immutableMBeanInfo=true, category="config")
public interface VirtualServer extends ConfigBeanProxy, Injectable {
@Attribute(required = true)
public String getId();
public void setId(String value) throws PropertyVetoException;
@Attribute
public String getHttpListeners();
...
}
The framework would generate the ObjectName based on the
ObjectNameInfo annotation and the relationship of the ConfigBean to
others (eg parent/ancestors). Based on the MBeanMetadata
annotation, it would also inject various things into it, then
register it as an MBean.
ISSUES
1. Offering support for MBeans in HK2 without AMX-isms. For
example, it would be convenient to offer the following default value:
String jmxDomain() default "amx";
This is relatively minor, it just means that Configs desiring to be
AMXConfig MBeans would have to do:
@ObjectNameInfo(jmxDomain="amx")
----------------------
package org.jvnet.hk2.config;
import org.jvnet.hk2.annotations.Contract;
import static java.lang.annotation.ElementType.TYPE;
import java.lang.annotation.Retention;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
import java.lang.annotation.Target;
/**
Metadata for generating an appropriate {_at_link
javax.management.ObjectName}.
<p>
The complete ObjectName with which an MBean is registered will
be generated
based in part upon this information; additional ObjectName
properties can
(and usual are) inserted in addition to the required ones,
including
ones that define the containment hierarchy (following the same
convention
as does JSR 77).
<p>
<p>
@author Lloyd Chambers
*/
@Retention(RUNTIME)
@Target(TYPE)
public @interface ObjectNameInfo {
/**
Defines the value of the "j2eeType" property used in an
ObjectName.
<p>
For backward compatibility, MBeans representing V2 domain.xml
elements
should use the Glassfish V2 J2EE_TYPE defined by the V2 AMX
interface.
<p>
The convention for the j2eeType property in the ObjectName is
for camel-case
types beginning with "X-" and ending with an appropriate
suffix corresponding to
the type of MBean. Example:<br>
<pre>
amx:j2eeType=X-DomainConfig,...
amx:j2eeType=X-ServerMonitor,...
amx:j2eeType=X-QueryMgr,...
</pre>
<p>
A further convention (consistent with the JSR 77 ObjectName
approach), is that
an MBean logically contained by another MBean must include
properties in its
ObjectName that specify its place in a tree of MBeans
("containment").
For example:<br>
<pre>
amx:j2eeType=J2EEServer,name=server
amx:j2eeType=JVM,name=jvm1234,J2EEServer=server
amx:j2eeType=X-JVMInfo,name=na,JVM=jvm1234,J2EEServer=server
</pre>
In the example above, the property "J2EEServer=server" in
effect defines a containment
hierarchy ("tree") in which the j2eeType=JVM MBean is a
"child" (Containee) of the
parent ("Container") amx:j2eeType=J2EEServer,name=server .
The j2eeType=X-JVMINfo
ObjectName continues that arrangement, specifing its parent
and parent's parent.
This convention allows traversal of registered MBeans, the
ability to build a generic management
interface which relates MBeans to each other structurally, etc.
<p>
The preceeding convention is enforced by the framework for
config beans based on
information available from @Configured interfaces, relying
upon the fact that registration
of a parent ("Container") MBean must occur before
registration of a child ("Containee").
*/
String j2eeType();
/**
Register the MBean in the specified JMX domain. For the
formal AMX
MBeans (public API), the domain "amx" should always be used.
Conversely
MBeans defined for other reasons/purposes that are not part
of AMX
should use a different JMX domain.
*/
String jmxDomain() default "amx";
/**
Declares that there may be at most one MBean registered with
this {_at_link #j2eeType}
<em>within its parent’s scope</em>.
By convention, singleton MBeans should all use the same name
("na"),
because the j2eeType alone effectively denotes the name.
*/
boolean singleton() default false;
/**
Classname of the class to be used for building the ObjectName.
The framework will use the default approach is not specified.
*/
String objectNameBuilder() default "";
}
/**
Holds meta information useful in generating and/or supplementing
the default
MBeanInfo as well as other runtime fields or optimizations for
auto-generated MBeans.
@author Lloyd Chambers
*/
@Retention(RUNTIME)
@Target(TYPE)
public @interface MBeanMetadata {
/**
If true, states that the MBeanInfo is immutable; that once
MBeanInfo is
obtained it may be cached, avoiding needless/repeated
invocations of getMBeanInfo().
Very few MBeans have mutable MBeanInfo, so this defaults to
'true'.
*/
boolean immutableMBeanInfo() default true;
/**
TODO: where to define constants for these? Is this really
useful? Should category
be part of the ObjectName? (somewhat redundant with the type
potentially).
Defines a category of MBean. Any non-empty string usable in
an ObjectName may be used,
but by convention the value should be one of "config", "monitor"
Legal values include "config", "monitoring", "control", "misc".
*/
String category() default "misc";
}
On Feb 7, 2008, at 2:53 PM, Jerome Dochez wrote:
>> 1. Should HK2 directly support JMX MBeans? By "directly", I mean
>> include annotations and hooks that support registration of MBeans;
>> registering them could be optional, driven by independent means.
> yes, I am fine with that as long as it is optional. Please
> coordinate with me and KK
---
Lloyd L Chambers
lloyd.chambers_at_sun.com
Sun Microsystems, Inc
---
Lloyd L Chambers
lloyd.chambers_at_sun.com
Sun Microsystems, Inc