EasyMBean

From jManage

Contents 1 Introduction 2 Download 3 Quick Start for the impatient: 4 Example 4.1 Step 1. Annotate the desired class with annotations: 4.2 Step 2: Create an instance of MBeanServer and the annotated class: 4.3 Step 3: Call the static method getMBean of class EasyMBean 4.4 Step 4: Nothing! 5 Understanding EasyMBean annotations for the cool headed 5.1 1. @ManagedResource: 5.2 2. @ManagedAttribute: 5.3 3. @ManagedOperation: 5.4 4. @ManagedConstructor: 5.5 5. @ManagedNotification: 6 EasyMBean Class 6.1 public static ObjectInstance getMBean(Object obj, ObjectName oname, MBeanServer mbs) 7 Rodents and Pests

Introduction

EasyMBean is a framework that allows developers to create ModelMBeans by simply applying annotations to plain Java classes. They no longer need to extend from xxxMBean interface or write numerous descriptor and meta data classes for creating ModelMBeans.

The idea behind EasyMBean is quite similar to JMX support in [[1]] Spring, with one big difference - EasyMBean removes the dependence on Spring container so that it can be used with any container or even without a container.

EasyMBean framework provides following features:

• Automatic creation and registration of any class as ModelMBean provided it uses annotations as described.
• No need to write even a single line of descriptor code
• Support for all JMX ModelMBean attributes for attributes, methods, constructors and notifications (Source level Meta data as called by Spring)
• Supports JMX Notifications
• Can be embedded inside your code and does not require any container
• Since it does not require any container it is extremely lightweight

Download

EasyMBean framework can be downloaded from http://sourceforge.net/projects/easymbean/.

Quick Start for the impatient:

To export and register your class as a MBean in a JMX MBeanServer you need to do the following:

1 Annotate your class elements with corresponding annotations -

• • @ManagedResource
  • @ManagedAttribute
  • @ManagedConstructor
  • @ManagedOperation and
  • @ManagedNotification.

@ManagedResource can only be used at Class level, @ManagedAttribute for a variable, @ManagedConstructor for a constructor, @ManagedOperation for a method and @ManagedNotification for an object of type Notification.

2 Create an instance of MBeanServer where you want to register your MBeans and create an instance your annotated class.

3 Call the static method getMBean of class EasyMBean passing in instance of your annotated class, the desired ObjectName instance and a reference to MBeanServer as parameters

4 The Method if successful, returns and ObjectInstance of the newly created MBean

Example

Step 1. Annotate the desired class with annotations:

import org.jmanage.easymbean.annotations.ManagedAttribute;

import org.jmanage.easymbean.annotations.ManagedConstructor;

import org.jmanage.easymbean.annotations.ManagedNotification;

import org.jmanage.easymbean.annotations.ManagedOperation;


import org.jmanage.easymbean.annotations.ManagedResource;


import javax.management.Notifications;


@ManagedResource(name=”TestClass”, displayName=”My ModelMBean”)
public class TestClass {


@ManagedAttribute(name=”testAttribute” displayName=”Test Attribute”, value=”5”, getMethod=”gettestAttribute”, setMethod=”settestAttribute”)
int testAttribute;


@ManagedNotification(name=”testNotification”, type=”org.jmanage.test”)
Notification notif = new Notification(“org.jmanage.test”, this, 1L);


@ManagedConstructor(name=”TestClass”)
public TestClass() {
System.out.println(“Hello, managed world!”);
testAttribute = 10;
}


@ManagedOperation(name=”testMethod”, targetClass=”TestClass”)
public void testMethod() {
System.out.println(“testing the managed world!”);
}


public int gettestAttribute() { return testAttribute; }

public void settestAttribute(int val) { testAttribute = val; } }

Step 2: Create an instance of MBeanServer and the annotated class:

MBeanServer mbs = ManagementFactor.getPlatformMBeanServer();
TestClass tc = new TestClass();


Step 3: Call the static method getMBean of class EasyMBean

passing in instance of your annotated class, the desired ObjectName instance and a reference to MBeanServer as parameters.

//Do not forget to import org.jmanage.easymbean.EasyMBean
ObjectInstance oi;
ObjectName oname = new ObjectName(“Test:domain=EasyMBean”);
oi = EasyMBean.getMBean(tc, oname, mbs);


Step 4: Nothing!

If all goes well, your annotated class will be registered as ModelMBean in the passed in 
MBeanServer and an ObjectInstance to same will be returned.

Understanding EasyMBean annotations for the cool headed

The org.jmanage.easymbean.annotation package defines annotations to describe ModelMBean attributes, constructors, operations, notifications and the MBean itself. The package defines following annotations:

1. @ManagedResource:

Meant to be used at class level, this annotation marks the class as a ModelMBean. Any class is to be exported as MBean must be tagged by @ManagedResource annotation. If not tagged, the class will not be exported as MBean. This annotation supports the following descriptor elements (correspond directly to JMX MBean descriptors):

Name	Type	Default
name	String	null
description	String	managed resource
descriptorType	String	mbean (always)
displayName	String	Manged Resource
persistPolicy	String	Never
persistPeriod	String	0
persistLocation	String	empty
log	String	false
logFile	String	MBeanLog.log
currencyTimeLimit	String	-1
export	String	F
visibility	String	1
presentationString	String	[undefined]

For an explanation of each of these descriptor types, please refer to JMX documentation.

2. @ManagedAttribute:

This annotations defines what properties of the class are exposed as MBeanAttributes. Any variable that has to be exposed as MBeanAttribute must be tagged with this annotation. If not tagged, it will not be exposed as MBeanAttribute. Those of you who have worked with MBeans in Spring will immediately notice one difference. While in spring you associate variables with getters and setters whereas in EasyMBean you do the reverse - associate getters and setters with variables e.g. instead of doing the following (as in Spring):

private String name;
@ManagedAttribute(description=”The Name Attribute”, currencyTimeLimit=20)
public void setName(String name) {
this.name = name;
}


you will do the following:

@ManagedAttribute(name=”name”, currencyTimeLimit=”20”, setter=”setName”)
private String name;
................. ............ public void setName(String name) {
this.name = name;
}
The following descriptors are supported:

Name	Type	Default
description	String	attribute
descriptorType	String	attribute
value	String	unassigned
displayName	String	managedAttribute
getMethod	String	unassigned
setMethod	String	unassigned
protocolMap	String	unassigned
persistPolicy	String	Never
persistPeriod	String	0
currencyTimeLimit	String	-1
lastUpdatedTimeStamp	String	0
visibility	String	1
persentationString	String	unassigned

For a detailed discussion of each, see JMX specification.

3. @ManagedOperation:

To expose your methods as operations of a MBean, tag your method with @ManagedOperation annotation. If the method is not tagged by this annotation, it will not be exposed as MBeanOperation. Another important difference between Spring JMX and EasyMBean framework is the way operation parameters are declared. In Spring you will define operation parameters by @ManagedOperationParameter annotation. However, for the sake of simplicity, EasyMBean hides this from the developer. It implicitly generates descriptors by reflectively examining the method. Thus a developer simply needs to mark the method by @MangedOperation annotation and does not need to worry about parameters. EasyMBean does not provide or support user defined ManagedOperationParameters like Spring for sake of simplicity.

For example: @ManagedOperation(name=”add” description=”Add two numbers”)
public int add(int x, int y) { //No need to specify ManagedOperationParameters
return x + y;
}

Following descriptors are supported:

Name	Type	Default
name	String	No Default
description	String	Operation
descriptorType	String	Operation
targetClass	String	No default
role	String	Operation
targetType	String	ObjectReference
displayName	String	managedOperaiton
lastReturnedValue	String	undefined
currencyTimeLimit	String	0
lastReturnedTimeStamp	String	0
visibility	String	1
presentationString	String	ManagedOperation

For explanation and details, refer to JMX specification.

4. @ManagedConstructor:

To expose constructors of a class as JMX managed constructor, simply tag it with @ManagedConstructor annoation. This is same as annotating a method, except that parameters for annotations are different. Following descriptors are supported:

Name	Type	Default
name	String	No Default
description	String	constructor
descriptorType	String	Operation
role	String	Constructor
displayName	String	ManagedConstructor
visibility	String	1
presentationString	String	undefined

For details of each descriptor, refer to JMX specification

5. @ManagedNotification:

If your class needs to emit notifications, all you need to do to expose your notification is tag them with @ManagedNotification annotation. Please note that at this point in time, EasyMBean simply generates descriptors and registers them with MBeanServer. It does either produce code to implement NotificationEmittor or NotificationBroadcaster interface nor it checks whether the annotated class implements those methods. Though desirable, I’ll add these features when I get more time! To expose a notification, declare an object of type Notification and tag it with @ManagedNotification annotation e.g.

@ManagedNotification(name=”myNotification” type=”org.jmanage.test”)

Notification myNotification; Following descriptors are supported for @ManagedNotifications:

Name	Type	Default
name	String	No Default
description	String	Notification
type	String	No Default
descriptorType	String	Notification
Severity	String	6
messageID	String	0
messageText	String	Notification
log	String	false
logFile	String	logFile
visibility	String	1
presentationString	String	undefined

EasyMBean Class

EasyMBean class defined in org.jmanage.easymbean package is a utility class that containes only one static method called as getMBean. The Method is defined as follows:

public static ObjectInstance getMBean(Object obj, ObjectName oname, MBeanServer mbs)

Arguments:

• • Object Obj: The first argument is your object which you wish to expose as MBean and that uses EasyMBean annotations.
  • ObjectName oname: ObjectName with which you wish to register this object in MBeanServer
  • MbeanServer mbs: The last parameter is the MBeanServer where you wish to register your MBean.

      Return: The objectinstance for newly created and registered MBean.

Thus, once you have annotated your class, create and instance and invoke EasyMBean.getMBean method passing in the above mentioned parameters. If the call succeeds, it returns an ObjectInstance of the newly registered MBean.

Rodents and Pests

If you come across any rodents and pests or feel like contacting me drop a mail at sanketsharma at gmail dot com