tonva / pojo-mbean Goto Github PK

Run FindBugs to identify possible code problems and fix all major ones.

Let the MBean control a "paused" attribute, and supply helper methods to 
sleepWhilePaused().

Allow a timeout to allow the caller to log that it is currently paused.

The invoke method in IntrospectedDynamicMBean wraps all exceptions from 
method.invoke(...) in IllegalArgumentException.

This makes it harder to signal error messages to the client.

Possible solution:
Method.invoke throws InvocationTargetException where the original exception can 
be accessed with getCause(). Rethrow the original exception wrapped in  an 
MBeanException. JConsole will then correctly show the cause.

Use Cobertura to measure code coverage of unit tests and improve, with a 90% 
target

When the reset() MBean operation is performed, the delayMinimum is set to 0.

Add unit test to reproduce and fix.

This probably has to do with the automatic detection of processing time 
performed, when no input date is available.

Currently, the duration notification notifyStop() and reporting 
(getDurationXxxMillis()) are hardcoded to report durations in milliseconds.

Certain systems may prefer or demand reporting in alternative time units 
(microseconds or seconds), so we should separate duration metrics from its 
units, and let units be settable with TimeUnit.MILLISECONDS default.

A new MBean attribute: (durationUnit?) should be added.
Existing MBean attributes should be renamed, removing the "Millis" suffix.

Again, great project!

Would you update IntrospectedDynamicMBean to match annotations by simple class 
name rather than full class name?

This is tricky in that you need to scan all annotations on a method & only 
check the simple class name, rather than simply lookup a particular annotation.

The other tricky bit is working out how to recover the annotation fields (e.g., 
Description, etc.).

It might be easier to have two mbeans - one for org.softee annotations & one 
for JDK annotations.  Long term I'd expect your codebase to recommend to the 
standard annotations for new code.

I may be able to help here, if you need some coding time.

Add pom.xml and add build artifacts for download

Read up on Descriptor 
http://download.oracle.com/javase/6/docs/api/javax/management/Descriptor.html 
and figure out whether it is worth generating by the IntrospectionDynamicMBean

Heavily inspired by Project Lombok's @Data annotation that, when applied to a 
class, will automatically generate getters and setters for all appropriate 
fields, we should support something similar on pojo-mbean.

A class that is annotated with @MBean(automatic=ATTRIBUTE), any bean compliant 
accessor method (getter/setter) on the class and any superclass with the same 
@MBean annotation will be automatically treated as if they were annotated with 
@ManagedAttribute.

Any method on a class, and all of its superclasses that satisfies all of:
1. its class is annotated with @MBean(automatic=OPERATION)
2. it is NOT considered a bean accessor (getter/setter)
3. it is a public instance (non static) method
Will be automatically treated as if they were annotated with @ManagedOperation.

Choose Maven repository, possibly sonatype.

The closer to maven central, the better!

Currently, IntrospectedDynamicMBean uses @Override annotation to indicate 
implementation of DynamicMBean interface methods, otherwise we could have 1.5 
target platform.

But to support Descriptors (see issue 4) we'd have to use JDK 6 API's. 
Possibly, we could use subclassing to leave base-functionality JRE 5 compatible.

In line with "prefer composition over inheritance" guidelines as well as 
"separation of concerns", the bean registration capabilities of the 
AbstractMbean class should be moved to a separate MBeanRegistration class, that 
handles construction of ObjectName as well as registering MBeans with the MBean 
server.

Id like to register my mBeans to a specific mBeanServer
not to the default one ManagementFactory.getPlatformMBeanServer()

This could be done by adding a new constructor MBeanRegistration that takes a 
MBeanServer as a parameter

<code>
/**
  * @param mBean
  *            an MBean instance in the form of a traditional MBean (implementing a sibling *MBean interface) or an
  *            MXBean (implementing an interface annotated with {@code @MXBean}), or an instance implementing the
  *            DynamicMBean interface.
  * @param mBeanObjectName
  *            the object name with which {@code mBean} will be registered
  * @param mBeanServer
  *            the MBeanServer to register the mBean in
  */
public MBeanRegistration(Object mBean, ObjectName mBeanObjectName, MBeanServer 
mBeanServer)
{
   this.mBean = mBean;
   this.mBeanObjectName = mBeanObjectName;
   this.mBeanServer = mBeanServer;
}
</code>

my solution is to add an optional attribute to @MBean which names an operation 
returning an string which would be added to beans name.

here are 3 changes needed to do so:

1) add new attribute

public @interface MBean {
...
   String instanceName() default "";
...
}

2) add code to use it in creating name as ObjectNameBuilder constructor

   public ObjectNameBuilder(Object mbean) throws MalformedObjectNameException {
        Class<?> mBeanClass = mbean.getClass();
        MBean annotation = mBeanClass.getAnnotation(MBean.class);
        if (annotation == null) {
            throw new IllegalArgumentException(mBeanClass + " is not annotated with " + MBean.class);
        }
        String name = annotation.objectName();
        if (!"".equals(annotation.instanceName())) {
            try {
                Method m = mBeanClass.getMethod(annotation.instanceName());
                m.setAccessible(true);
                Object instanceName = m.invoke(mbean);
                // ,instance=xxx
                name = name + instanceName;
            } 
            catch (Exception x) {
                throw new IllegalArgumentException("error calling instance name operation in bean " + MBean.class);
            }
        }
        this.objectName = ObjectName.getInstance(name);
    }


3) change MBeanRegistration constructor to use it

    public MBeanRegistration(Object mBean) throws MalformedObjectNameException {
        this(mBean, new ObjectNameBuilder(mBean).build());
    }

The annotations should themselves be annotated with @Documented 
(java.lang.annotations).  That an interface/class participates in JMX should be 
part of the javadocs, e.g.:

@MBean
public class CoolThing {
    // ...
}

If @MBean were annotated with @Documented, then generated javadocs for 
"CoolThing" would note the @MBean annotation.

If a field is annotated with @Property, it should also be explicitly marked as 
READ, WRITE or READ_WRITE.

Using field @Property annotations means you don't need getters/setters for 
simple beans.

Access in the IntrospectedDynamicMBean will be by means of field reflection

The current public release in maven central is version 1.1 from 2011.

Is there a next release to push out to maven central?  What plans do you have 
around that?

Thanks

It is not currently possible to construct an ObjectName by way of an annotated 
class, when using ObjectNameFactory. An instance of the class is required.

This presents a problem when having to construct an ObjectName from within the 
constructor of an annotated MBean.

See 
http://download.oracle.com/javase/6/docs/api/javax/management/openmbean/package-
summary.html#package_description

Currently, one and only one of...
- Field
- Getter method
- Setter method
... should be annotated with @ManagedAttribute, and the access level may be 
defined using @ManagedAttribute(access=Access.READ_WRITE)

So you could see a setter method annotated with @ManagedAttribute which would 
in fact make the related field available for READ only, since Access.READ is 
the default access.

A couple of suggestions:

If a method is annotated with @ManagedAttribute, that method is made available 
(e.g. if only the setter method has the annotation the attribute would be WRITE 
only. This would require default access to be "IMPLIED" or "CONTEXT". And it 
would be considered an error, if a @ManagedAttribute annotated method would 
have any explicit READ/WRITE/READ_WRITE access. These would be reserved for 
@ManagedAttribute anotations on fields.

Having two @ManagedAttribute annotation for a single attribute (getter and 
setter method) would cause another problem: Which description to use, if both 
annotations define a description attribute.

Possibly, it would be better to remove the description attribute from the 
@ManagedAttribute annotation, and move it into a separate @Description 
annotation which would also replace the description attribute for 
@ManagedOperation and @Parameter. It would be considered an error, if more than 
one @Description attribute was added 

This last change would also solve the issue of using the "value" annotation 
attribute for adding description. This is not ideal, since ...
@ManagedAttribute(value="This is the description", access=Access.READ_WRITE)
... just doesn't seem fluent. I'd rather see ...
@ManagedAttribute(Access.READ_WRITE) @Description("This is the description")

An added bonus is that the above change gets us a little closer to the 
(defunct) JMX 2.0/JSR 255 proposal.

Default sorting of MBean attributes and operations are alphabetically (String 
comparator order).

We could allow a sort order override attribute to either @ManagedOperation/ 
@ManagedAttribute or to the @Description annotation, since we can only have one 
sort order per attribute, whereas we can have two @ManagedAttribute annotations 
(Read + Write).

Possibly...

@Description(value="This is ordered as x1", order="x1");

Default ordering should still be by operation/attribute name.

TODO: Should ordering be case insensitive?

@Property -> @ManagedAttribute
@Operation -> @ManagedOperation (impact parameter seems OK)

JMX 2.0 @Description seems more complex than simply continuing with using an 
annotation parameter, but for forward compatibility, I could be swayed...

It is redundant to name Pojo classes XxxxPojoYyyy, so do away with the Pojo 
part of any name.

Consider using the @MBean annotation could be used for specifying domain, type 
and possibly name, e.g.

@MBean(domain="com.loremipsum", type="org.softee.management.ProcessingMbean", 
name="MyMBean")

... resulting in the ObjectName:

"com.loremipsum:name=MyMBean,type=org.softee.management.ProcessingMbean"

Rather than using separate "domain", "type" and "name" attributes on the @MBean 
annotation, consider having a single "objectName" attribute containing the 
entire ObjectName.

This would allow adding alternate attributes, such as "application", similar to 
what is available in Spring, see 
http://static.springsource.com/projects/instrumentation/instrument/html/ch05.htm
l#exportexample

Add the @Inherited annotation 
http://download.oracle.com/javase/6/docs/api/java/lang/annotation/Inherited.html
 to @MBean, @Operation, @Property and @Parameter to allow inheritance/extension 
of Annotated MBeans

The annotated methods on an interface implemented by a JDK dynamic proxy 
handler are not discoverable presently.

Suggestion:

A. Use Proxy.isProxyClass
B. When proxy use Proxy.getInvocationHandler

From here it gets tricky.  At a minimum the handler should be annotated with 
@MBean.  Potentially you could scan the handler for annotated methods.

I'm happy to kick out a prototype if intersted.

Currently virtually no synchronized blocks are used to ensure atomicity of 
notifyXxx() operations.

This could lead to marginal inconsistencies in the statistics of the 
ProcessingPojoMBean

It should be investigated how to improve atomicity while maintaining 
concurrency of operation.

Hello,

It is proposal of enhancement because we would like pojo-mbean to be 
OSGi-compliant.

To do so, we've just repackaged the framework as a bundle using 
maven-bundle-plugin and we have separated the annotation layer from the 
implementation layer. By this way, only the annotations are available (and 
visible) to the user and the registration process is delegated to the OSGi 
framework.

Please find the patch enclosed.

Regards,

Hugo Loos

Add usage examples on the wiki:

1. Java code examples
1.1 An annotated MBean that extends AbstractMBean
1.2 Instantiating, starting and stopping the MBean
2. Screen-dumps
2.1 JConsole
2.2 JMX console (JBoss)

To serve as examples, we should create a number of "demo" MBeans that contain 
all variations of permitted annotations:

@MBean (with and without specification of domain, type and name)
@Property (on getters, is'ers, setters and fields)
@Operation (with and without impact attribute)
@Parameter (on @Operation)

Also, various techniques for extending/overriding annotated beans, including: 
adding MBean annotations, overriding methods and removing MBean annotations.

The MBeans should probably reside in src/test/java, and each should have a 
matching unit test alongside the MBean.

MBeans that are generally usable should, however, be located in src/main/java 
to allow use and extension by API client users.

Run FindBugs to identify possible code problems and fix all major ones.

The IntrospectedDynamicMBean should implement MBeanRegistration 
http://download.oracle.com/javase/6/docs/api/javax/management/MBeanRegistration.
html and delegate calls to the interface methods to the POJO MBean being 
introspected, provided the POJO MBean implements this very interface.

This way we allow client programmers to receive lifecycle callbacks without 
imposing any requirements or conceptual footprint to the 99+% who won't need it.

When an annotated MBean's accessor methods (attributes and operations) are not 
visible (methods are private or MBean class is a private inner class), the 
following happens:

# Readable attributes are shown as "Unavailable" in jconsole
# Operations return an "IllegalArgumentException" without further info.