Please note that this documentation is not final and is subject to change.

javax.management
Interface MBeanRegistration

All Known Implementing Classes:

CounterMonitor, GaugeMonitor, JMXConnectorServer, MLet, Monitor, PrivateMLet, RelationService, RelationSupport, RequiredModelMBean, RMIConnectorServer, StandardEmitterMBean, StandardMBean, StringMonitor, Timer

public interface MBeanRegistration

Can be implemented by an MBean in order to carry out operations before and after being registered or unregistered from the MBean Server. An MBean can also implement this interface in order to get a reference to the MBean Server and/or its name within that MBean Server.

Resource injection

As an alternative to implementing MBeanRegistration, if all that is needed is the MBean Server or ObjectName then an MBean can use resource injection.

If a field in the MBean object has type ObjectName and has the @Resource annotation, then the ObjectName under which the MBean is registered is assigned to that field during registration. Likewise, if a field has type MBeanServer and the @Resource annotation, then it will be set to the MBeanServer in which the MBean is registered.

For example:

 public Configuration implements ConfigurationMBean {
     @Resource
     private volatile MBeanServer mbeanServer;
     @Resource
     private volatile ObjectName objectName;
     ...
     void unregisterSelf() throws Exception {
         mbeanServer.unregisterMBean(objectName);
     }
 }
 

Resource injection can also be used on fields of type SendNotification to simplify notification sending. Such a field will get a reference to an object of type SendNotification when the MBean is registered, and it can use this reference to send notifications. For example:

 public Configuration implements ConfigurationMBean {
     @Resource
     private volatile SendNotification sender;
     ...
     private void updated() {
         Notification n = new Notification(...);
         sender.sendNotification(n);
     }
 }
 

A field to be injected must not be static. It is recommended that such fields be declared volatile.

It is also possible to use the @Resource annotation on methods. Such a method must have a void return type and a single argument of the appropriate type, for example ObjectName.

Any number of fields and methods may have the @Resource annotation. All fields and methods with type ObjectName (for example) will receive the same ObjectName value.

Resource injection is available for all types of MBeans, not just Standard MBeans.

If an MBean implements the DynamicWrapperMBean interface then resource injection happens on the object returned by that interface's getWrappedObject() method rather than on the MBean object itself.

Resource injection happens after the preRegister method is called (if any), and before the MBean is actually registered in the MBean Server. If a @Resource method throws an exception, the effect is the same as if preRegister had thrown the exception. In particular it will prevent the MBean from being registered.

Resource injection can be used on a field or method where the type is a parent of the injected type, if the injected type is explicitly specified in the @Resource annotation. For example:

     @Resource(type = MBeanServer.class)
     private volatile MBeanServerConnection mbsc;
 

Formally, suppose R is the type in the @Resource annotation and T is the type of the method parameter or field. Then one of R and T must be a subtype of the other (or they must be the same type). Injection happens if this subtype is MBeanServer, ObjectName, or SendNotification. Otherwise the @Resource annotation is ignored.

Resource injection in MBeans is new in version 2.0 of the JMX API.

Since:

1.5

Method Summary

void	postDeregister() Allows the MBean to perform any operations needed after having been unregistered in the MBean server.
void	postRegister(Boolean registrationDone) Allows the MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.
void	preDeregister() Allows the MBean to perform any operations it needs before being unregistered by the MBean server.
ObjectName	preRegister(MBeanServer server, ObjectName name) Allows the MBean to perform any operations it needs before being registered in the MBean Server.

Method Detail

preRegister

ObjectName preRegister(MBeanServer server,
                       ObjectName name)
                       throws Exception

Allows the MBean to perform any operations it needs before being registered in the MBean Server. If the name of the MBean is not specified, the MBean can provide a name for its registration. If any exception is raised, the MBean will not be registered in the MBean Server.

Parameters:

server - The MBean Server in which the MBean will be registered.

name - The object name of the MBean. This name is null if the name parameter to one of the createMBean or registerMBean methods in the MBeanServer interface is null. In that case, this method must return a non-null ObjectName for the new MBean.

Returns:

The name under which the MBean is to be registered. This value must not be null. If the name parameter is not null, it will usually but not necessarily be the returned value.

Throws:

Exception - This exception will be caught by the MBean Server and re-thrown as an MBeanRegistrationException.

postRegister

void postRegister(Boolean registrationDone)

Allows the MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.

Parameters:

registrationDone - Indicates whether or not the MBean has been successfully registered in the MBean server. The value false means that the registration phase has failed.

preDeregister

void preDeregister()
                   throws Exception

Allows the MBean to perform any operations it needs before being unregistered by the MBean server.

Throws:

Exception - This exception will be caught by the MBean server and re-thrown as an MBeanRegistrationException.

postDeregister

void postDeregister()

Allows the MBean to perform any operations needed after having been unregistered in the MBean server.