Apache

Introduction

This handler provides JMX management of component instance. It could be useful to manage instance remotely. As the handler exposes MBeans, you must have the MOSGi MBean Server.

Features

The handler allows to:

  • Expose attributes to be accessed through JMX, with rights management (read, write).
  • Expose methods to be called through JMX
  • Get notification when an attribute is modified

Prerequisites

To be functional this handler must register on an MBean Server, thus you obviously need it. The MBean Server used is MOSGi provided with Felix.
To deploy MOSGi, you can compile the Felix trunk and deploy at least three bundles of MOSGi:

Download

You can download the jmx handler. Binaries are available here (Jar compiled with Java 1.5). Sources are available here.
Sources are hosted inside the Felix sandbox on http://svn.apache.org/repos/asf/felix/sandbox/clement/jmx.handler.

How to use it

The handler needs to be added in the metadata.xml, you just add a namespace 'jmx' like:

<iPOJO xmlns:jmx=" org.apache.felix.ipojo.handlers.jmx.MBeanHandler ">

So, you could now declare properties and methods expose in JMX. They are surrounded by the <jmx:config> tag.

Example:

<jmx:config>
   <property name="string hello" field="m_str" rights="w" notification="true"/>
   <property name="integer" field="m_int" rights="w"/>
   <method   name="printMsg"/>
   <method   name="modifyInt"/>
</jmx:config>

The two tags allowed are (square brackets indicate optional properties):

<property	[name]		= name of the property which will appears in JMX
					Default value: the field name.
		field			= name of the attribute corresponding in the POJO
		[rights]		= 'w' allow read and write
					   'r'  allow only read
					Default value: 'r'.
[notification] 	= 'true' or 'false' enable/disable sending notifications when   the property is modified.
		Default value: 'false'.
>
<method	name	= name of the target method 
>

Note: Be careful that the argument and return type of methods must be serializable. In case of several methods have the same name, each of them will be exposed.

In the second part I will present a complete utilisation example.

Examples

In this part I will give you a complete example of a POJO managed with JMX, using the JConsole provides by SUN. To connect to the MBean server, please refer to the MOSGi documentation (http://cwiki.apache.org/FELIX/mosgi-managed-osgi-framework.html).

Exposing Attributes

In first time we create a simple POJO with a single class named Test. We add two fields named m_str (String) and m_int (Integer).

public class Test{
	private String m_str = "hello";
	private int m_int = 12;

We expose now the attributes in the jmx:config tag in metadata:

<iPOJO xmlns:jmx="org.apache.felix.ipojo.handlers.jmx.MBeanHandler">
<component className="jmx.iPOJO.handler.Test" factory="no" immediate="true" architecture="true">
	<provides/>
 
	<jmx:config>
		<property name="string hello" field="m_str" rights="w"/>
		<property name="integer" field="m_int" rights="w"/>
	</jmx:config>

</component>
<instance name="handler test" component="jmx.iPOJO.handler.Test"/>
</iPOJO>

Now we could get and write the properties in the JConsole:

Exposing Methods

We could now add methods in the initial class:

public String printMsg(){
		return m_str;
	}
	
	public int modifyInt(int newValue){
		int oldValue = m_int;
		m_int = newValue;
		return oldValue;
	}

The first one returns a String, and the second changes m_int value and returns the old one.

We add corresponding tag in metadata to expose those methods:

<method name="printMsg"/>
<method name="modifyInt"/>

Now the operations tab is available in the JConsole, and displays two methods, when we call "modifyInt" with a new value, JConsole show the result in a Message Box:

Attribute Notifications:

You could subscribe to attribute notification by adding the 'notification' attribute in property tag. In our example if we want to be notified when m_str is modified, we change the property line in metatada like this:

<property name="string hello" field="m_str" rights="w" notification="true"/>

So now if we change the string through JConsole or if the POJO was modified in other way, a notification will be sent to every listener.
For example with the JConsole, we subscribe in the notification tab, and we get notification when the message changes:
Overview
Getting Started
User Guide
Tools
Developer Guide
Misc & Contact