The XMOJO Project
<< Prev Chapter 3.1.1 MBean Registration Next >>

Registering MBeans


A MBeanServer's primary responsibility is to maintain a registry for MBeans in a JMX agent.  The MBeans can be registered in any of the following two methods:

1)  Creating an instance of the MBean and registering it with the MBeanServer using the method:

public ObjectInstance registerMBean(Object object, ObjectName name)

Here, object is the instance of the MBean created and the name part represents a unique identity for the MBean.

2)  Using one of the createMBean methods:

public ObjectInstance createMBean(String classname, ObjectName name)
public ObjectInstance createMBean(String classname, ObjectName name, ObjectName loader)
public ObjectInstance createMBean(String classname, ObjectName name, Object[] params, String[] types)
public ObjectInstance createMBean(String classname, ObjectName name, ObjectName loader, Object[] params, String[] types)
 
The createMBean methods use Java Reflection to create an instance of the MBean.  For all the createMBean methods, two arguments are common.
  1.  String classname -- represents the classname of the MBean for which an instance has to be created.
  2.  ObjectName name -- represents the object name with which the MBean has to be registered.
If the two-argument constructor of createMBean is used, the default class loader is used to load the MBean class and the MBean is instantiated using the default constructor.   If the MBean is instantiated, this instance is registered with the MBeanServer using the object name provided as the second argument.  If you want to load the class using some specific class loader then the three-argument constructor can be used.  The class loader should be registered as one of the MBeans with the MBeanServer.  The object name of the class loader should be passed as the third argument.

While instantiating the class, if any argument has to be passed, then the four-argument createMBean method can be used.  The last two arguments of this createMBean method take the array of Objects (that will be required for instantiating the class) and their signatures respectively.  If the MBean class has to be loaded using some specific class loader, the five-argument constructor can be used.

 Registering Multiple Instances for a Same MBean 

There may be cases where you might need to monitor ten or so Web servers.  If the management information is common for all the Web servers, then you need not have to write ten MBeans.  Instead, just one MBean is sufficient.  We can create many instances and register each instance with a unique object name.

Now comes the importance of using the object names effectively to avoid confusions.

It is obvious that the server port number and the server host name will be unique for any server, that is, in a single machine, you cannot run two servers at the same port.

So, it would be meaningful to create an object name like
Servers:hostName=localhost,portNumber=xxxx
 
Suppose one more server starts up in the same machine, then the object name would be Servers:hostName=localhost,portNumber=yyyy

Since ObjectName is the unique identity with which the registered MBeans are uniquely identified, the multiple instances of the MBean are registered with different ObjectNames.

ObjectNames are normally differentiated using the key value pairs they contain, such as the hostName and portNumber keys and their respective values in a Server MBean. Similarly, to identify the likely grouped MBeans, the ObjectNames will be populated with the respective Key Value pairs. For example, type=ServerMBean denotes that this MBean is of type Server MBean. Hence, the ObjectName value Server:type=ServerMBean,hostName=localhost,portNumber=8050 provides easy grouping of MBeans spawned for the Server MBean implementation and also provides a way to uniquely identify the MBean Instance for the Server running at localhost:8050.

 A Simple Demonstration 


Let the MBean that provides the management information (common for all the Web servers) be a dynamic MBean and let the class name be ServerInfo.  
Let there be two Web servers running in machineA at ports 8080 and 80.  Let there be one Web server running in machineB listening at port 8080, and one more web server running in machineC listening at port 80.  Totally, we need to manage these four Web servers.  We can make use of the ServerInfo class and create four instances to manage each of these Web servers.  The code snippet for registering the four MBeans is shown below:

ServerInfo srvr1 = newServerInfo();
ServerInfo srvr2 = new ServerInfo();
ServerInfo srvr3 = new ServerInfo();
ServerInfo srvr4 = new ServerInfo();

MBeanServer mbs = null;

try
{
    mbs = MBeanServerFactory.createMBeanServer( );
    mbs.registerMBean(srvr1, new ObjectName("Server:hostName=machineA,portNumber=8080"));
    mbs.registerMBean(srvr2, new ObjectName("Server:hostName=machineA,port
Number=80"));
    mbs.registerMBean(srvr3, new ObjectName("Server:hostName=machineB,port
Number=8080"));
    mbs.registerMBean(srvr4, new ObjectName("Server:hostName=machineC,port
Number=80"));
}
catch (Exception e)
{
  e.printStackTrace();
}



 UnRegistering MBeans 

MBeans can be unregistered from the MBeanServer using the method:

public void unregisterMBean(ObjectName name)

Here, name is the ObjectName with which the MBean is registered.

After unregistering the MBean, the MBeanServer will not keep any reference on the MBean instance.

 Controlling MBeanRegistration 

JMX defines an interface named MBeanRegistration.  The purpose of this interface is to allow MBean developers to have some control upon the registering/unregistering of the MBean in the MBeanServer.   This is achieved in the MBean by implementing the javax.management.MBeanRegistration interface.  

The MBeanRegistration interface defines the behavior of the registration control mechanism.  It defines the following four methods:

public ObjectName preRegister(MBeanServer mbs, ObjectName name)
public void postRegister()
public void preDeRegister()
public void postDeRegister()

All the above four methods are callback methods, that is, the MBeanServer will invoke these methods at appropriate times.

If an MBean implements MBeanRegistration and this MBean is registered, the MBeanServer calls the preRegister method before registering the MBean.  The ObjectName returned by this preRegister method will be used while registering the MBean.  After successful registration of the MBean, the MBeanServer calls the postRegister method.

If the above MBean is deregistered, the MBeanServer calls the preDeRegister method before deregistering the MBean and if the deregistration is successful, MBeanServer calls the postDeRegister method.


Points to Remember
  1. For a single MBean class, multiple instances can be created and each of them can be registered provided the object name given while registering the MBean is unique.  
  2. Whenever an MBean is registered, a notification of type jmx.mbean.created is created by the MBeanServer.  The MBeanServerDelegate MBean broadcasts this notification to all the registered listeners.
  3. MBeanRegistration interface provides hook points to monitor the registration and deregistration process.

<< Prev Home Next >>
MBeanServer
Agent Services