Much of the code for a dynamic MBean is similar from one dynamic MBean to another. Hence, there are two primary tasks on which to focus:
• Creating metadata to describe each feature of the MBean • Implementing the DynamicMBean interface
Dynamic MBean metadata classes are immutable, so the only way to set their various properties is to use a constructor. In addition, a metadata class must be created—and code written—for every feature on the management interface of a resource, resulting in lots of code that basically looks the same. A simplified approach to creating dynamic MBean metadata would help to reduce code clutter (and hence, readability). Here is an example of how to create a dynamic MBean metadata class for an attribute called MyAttribute of type Integer that is read-only:
MBeanAttributeInfo attribute = new MBeanAttributeInfo( "MyAttribute", // Name
Integer.class.getName( ), // Type "My very own attribute.", // Description true, // Is Readable? false, // Is Writeable?
false); // isIs (i.e., is boolean?)
Of course, you could have squeezed all the parameters onto one line of code, but that would sacrifice readability (and could introduce errors). For example, JMX will allow you to create incorrect metadata for the attribute we just looked at:
MBeanAttributeInfo attribute = new MBeanAttributeInfo( "MyAttribute", // Name
Long.class.getName( ), // Type
"My very own attribute.", // Description true, // Is Readable? false, // Is Writeable?
false); // isIs (i.e., is boolean?)
In this example, this attribute is incorrectly described as a java.lang.Long instead of its correct type, java.lang.Integer. This mistake will not be caught until runtime, and can lead to hours of needless debugging to fix. The reverse situation could also occur if the data type of the attribute changes (as a result
O’Reilly – Java Enterprise Best Practices １８７
of, say, maintenance to the resource class), but you forget to modify the metadata to match the attribute's new type. Again, this could lead to wasted hours of debugging.
Much of the code for the second task, to implement the DynamicMBean interface, is similar from
implementation to implementation. For example, the getAttribute( ) method is passed the name of an attribute and retrieves its value. Suppose MBean A has an attribute A, and MBean B has an attribute B. MBean A's implementation of getAttribute( ) might look like this:
public class MBeanA implements DynamicMBean { // . . .
public Object getAttribute(String name) throws // Some exceptions { try { if (name.equals("A") { return this.getA( ); } } catch (Exception e) { // Handle . . . } } }
while MBean B's implementation might look like this: public class MBeanB implements DynamicMBean { // . . .
public Object getAttribute(String name) throws // Some exceptions { try { if (name.equals("B") { return this.getB( ); } } catch (Exception e) { // Handle . . . } } }
In this extremely simple example, only the highlighted lines of code are different, and all they do is figure out if the requested attribute is supported and delegate to the appropriate getter. Suppose you introduce a class called DynamicMBeanFacade, which looks similar to the class shown in Example 7-3.
O’Reilly – Java Enterprise Best Practices １８８
Example 7-3. DynamicMBeanFacade
public class DynamicMBeanFacade implements DynamicMBean { public DynamicMBeanFacade(Object managedResource) { // . . .
}
public void addAttribute(String name, String description) { // . . .
}
public void removeAttribute(String name) { // . . .
}
public void addOperation(String name, String description) { // . . .
}
public void removeOperation(String name) { // . . .
}
public void addNotification(String type, String description) { // . . .
}
public void removeNotification(String type) { // . . .
}
// DynamicMBean interface implementation here . . . }
There is a method that adds and removes each feature to be defined on the management interface of the resource. For example, to add the MyAttribute attribute that we saw earlier, the agent code looks like this: public void someAgentMethod( ) {
try {
MBeanServer mbs = /* Obtain somehow. */ DynamicMBeanFacade resource =
(DynamicMBeanFacade) mbs.instantiate("MyClass");
resource.addAttribute("MyAttribute", "My very own attribute"); // . . .
} catch (Exception e) { // Handle . . . }
}
O’Reilly – Java Enterprise Best Practices １８９
• Metadata creation is hidden behind the façade, resulting in cleaner, more readable code.
• Metadata creation is less error-prone for attributes and operations because the reflection API is used to introspect the managed resource class to ensure correct data types.
• The number of lines of code to be maintained in your application is reduced because the DynamicMBean implementation is hidden behind the façade class and can be reused for every MBean in your application.
Here's how it works. The agent creates an instance of DynamicMBeanFacade and invokes the appropriate methods to describe the attributes, operations, and notifications (i.e., the features) that will be part of the management interface of the managed resource. The agent is only required to pass the name and description of the feature. DynamicMBeanFacade uses Java's reflection API to introspect the managed resource and discover data type information for attributes. For operations, DynamicMBeanFacade determines the return type and any parameter names and their types. Only those attributes and operations that actually exist on the underlying resource can be added to the management interface, which presupposes some knowledge of the underlying resource on the part of the agent.
In the following sections, we will take a quick look at some of the methods of DynamicMBeanFacade and how they can be implemented for each MBean feature type, which should give you an idea of how an implementation of DynamicMBeanFacade might look. For a complete source listing of the
DynamicMBeanFacade, refer to http://www.oreilly.com/catalog/javaebp for information on how to download the sample application code for this chapter.
You can employ two strategies when using this pattern:
• The managed resource class is a subclass of the DynamicMBeanFacade class.
• The managed resource is already a subclass of some other class and uses DynamicMBeanFacade via containment.
For the sake of brevity, the examples in this section will use the first strategy because it is slightly easier to implement. However, the implementations are remarkably similar, and I will briefly describe the differences at the end of this section.
To implement the addAttribute( ) and addOperation( ) methods of DynamicMBeanFacade, follow
these steps:
O’Reilly – Java Enterprise Best Practices １９０
2. Set various properties of the feature. For attributes, these include whether the attribute is readable and writeable, and its type. For operations, these properties indicate the return type and information about the operation's parameters.
3. Create dynamic MBean metadata specific to that feature. For attributes, the metadata class is MBeanAttributeInfo, and for operations, it is MBeanOperationInfo (and
MBeanParameterInfo for the operation's parameters).
4. Add the newly created metadata to the MBeanInfo object that describes the management interface of the managed resource.
7.2.4.1 Attributes
For each attribute in the managed resource, the agent calls addAttribute( ), passing the name and description of the attribute. Based on the JMX design patterns, DynamicMBeanFacade is expecting the name of the attribute to be preceded by get or is for readable attributes and/or set for writeable attributes. If the attribute is called MyAttribute, the implementation of addAttribute( ) will introspect the managed resource for getMyAttribute( ) and/or setMyAttribute( ) (isMyAttribute( ) is allowed as a getter for boolean attribute types).
As you saw earlier, describing the management interface is very simple. Of course, the trade-off is that the bulk of the work falls to the implementation of DynamicMBeanFacade. Even still, it's not terribly complicated. Let's look at a very simple implementation of the addAttribute( ) method, as shown in Example 7-4.
Example 7-4. Implementation of the addAttribute( ) method
public class DynamicMBeanFacade implements DynamicMBean { // . . .
public synchronized void addAttribute(String name, String description) throws DynamicMBeanFacadeException {
Class current = this.getClass( ); boolean isReadable = false;
boolean isWriteable = false; boolean isIs = false;
String type = null;
Method[ ] methods = current.getMethods( ); for (int aa = 0; aa < methods.length; aa++) { String methodName = methods[aa].getName( ); if (methodName.equals("get" + name)) {
O’Reilly – Java Enterprise Best Practices １９１
isReadable = true;
type = methods[aa].getReturnType( ).getName( ); } else if (methodName.equals("set" + name)) {
Class[ ] parmTypes = methods[aa].getParameterTypes( ); if (parmTypes.length > 1) { continue; } else { isWriteable = true; type = parmTypes[0].getName( ); }
} else if (methodName.equals("is" + name)) { type = methods[aa].getReturnType( ).getName( ); if (type.equals(Boolean.TYPE.getName( ))) { isReadable = true;
isIs = true; } else type = null; }
}
if (!isReadable && !isWriteable)
throw new DynamicMBeanFacadeException("Attribute not found."); MBeanAttributeInfo attribute = new MBeanAttributeInfo(
name, type, description, isReadable, isWriteable, isIs); // Recreate MBeanInfo using new attribute metadata.
} }
This method searches all the public methods of the managed resource class for a getter and/or setter for the specified attribute. If the attribute is found, an MBeanAttributeInfo metadata object for the attribute is created and added to the existing attribute metadata by recreating the MBeanAttributeInfo array. The MBeanInfo object that describes the management interface is recreated (because MBeanInfo instances are immutable) using this new attribute metadata array.
When an agent wishes to remove an attribute from the management interface, it invokes the removeAttribute( ) method, passing the name of the attribute to remove. In this case,
DynamicMBeanFacade does not need to introspect the managed resource class; it only needs to search the metadata that describes the attributes of the management interface and remove the metadata describing the specified attribute.
O’Reilly – Java Enterprise Best Practices １９２
7.2.4.2 Operations
When the agent wishes to add an operation to the management interface, it invokes the addOperation( ) method, passing the name and description of the operation. The implementation of addOperation( ) must then introspect the managed resource to ensure that the operation actually exists and create the necessary metadata to describe the operation, including metadata for any parameters to the operation. The metadata is then added to the MBeanOperationInfo array that is part of the MBeanInfo object that describes the management interface, as shown in Example 7-5.
Example 7-5. DynamicMBeanFacade using metadata
public class DynamicMBeanFacade implements DynamicMBean { // . . .
public synchronized void addOperation(String name, String description) throws DynamicMBeanFacadeException {
Class current = this.getClass( ); StringreturnType = null;
Method[ ] methods = current.getMethods( ); Method theMethod = null;
for (int aa = 0; aa < methods.length; aa++) { if (methods[aa].getName( ).equals(name)) { theMethod = methods[aa];
break; // Take only the first one encountered. }
}
if (theMethod = = null)
throw new DynamicMBeanFacadeException("Operation not found.");
MBeanOperationInfo newOp =
new MBeanOperationInfo(description, theMethod); // Recreate MBeanInfo using new operation metadata. }
// . . . }
The algorithm used to create the operation metadata, adding it to the operation metadata array, and recreating the MBeanInfo object should look familiar: this process is almost identical to addAttribute( ). In Example 7-5, I have used an alternate constructor of MBeanOperationInfo that takes a
O’Reilly – Java Enterprise Best Practices １９３
java.reflect.Method object. This constructor will perform further introspection and create the necessary metadata to describe the operation's parameters.
When an agent wishes to remove an operation from the management interface, it invokes the removeOperation( ) method, passing the name of the operation to remove. In this case,
DynamicMBeanFacade does not need to introspect the managed resource class; it only needs to search the metadata that describes the operations of the management interface and remove the metadata describing the specified operation.
7.2.4.3 Notifications
When the agent wishes to add a notification emitted by a managed resource to the resource's management interface, it invokes the addNotification( ) method, passing the type (i.e., name) of the notification and a description of the notification. Unlike attributes and operations, there is really no way for
DynamicMBeanFacade to introspect the managed resource class to see if the notifications exist because it is entirely up to the managed resource to define and emit JMX notifications and communicate this information to the agent developer a priori through, say, documentation. Assume that the managed resource implements the NotificationBroadcaster interface, as shown in Example 7-6.
Example 7-6. Implementing the NotificationBroadcaster interface
public class DynamicMBeanFacade implements DynamicMBean { // . . .
public synchronized void addNotification(String type, String description) throws DynamicMBeanFacadeException {
MBeanNotificationInfo notif = new MBeanNotificationInfo( new String[ ] {type},
"javax.management.Notification", description);
MBeanNotificationInfo[ ] notifs = _mbi.getNotifications( ); MBeanNotificationInfo[ ] newNotifs =
new MBeanNotificationInfo[notifs.length + 1];
System.arraycopy(notifs, 0, newNotifs, 0, notifs.length); newNotifs[notifs.length] = notif;
// Recreate MBeanInfo with new notification metadata array.
O’Reilly – Java Enterprise Best Practices １９４
// . . . }
When an agent wishes to remove a notification from the management interface, it invokes removeNotification( ) , passing the notification type.
7.2.4.4 DynamicMBean implementation
Implementing the DynamicMBean interface is actually very straightforward, as you'll see. Example 7-7 shows how to implement invoke( ) , which you can use as the implementation backbone of all the other methods of DynamicMBean.
Example 7-7. Implementing the DynamicMBean invoke( ) method
public class DynamicMBeanFacade implements DynamicMBean { // . . .
public Object invoke(String actionName, Object[ ] params, String[ ] signature) throws javax.management.MBeanException, javax.management.ReflectionException { Object ret = null; // Return code
try {
Class[ ] sig = new Class[signature.length]; for (int bb = 0; bb < signature.length; bb++)
sig[bb] = this.getClassFromClassName(signature[bb]); Class mr = this.getClass( );
Method method = mr.getMethod(actionName, sig); ret = method.invoke(_managedResource, params); } catch (Exception e) {
throw new ReflectionException(e); }
return ret; } // . . . }
This is not the most robust implementation possible, but even this simple implementation does a lot in remarkably few lines of code. This method creates the array of Class objects that represents the method signature, uses this signature to obtain a Method object from the reflection API, and invokes the method. Any exceptions that arise will be caught and rethrown in the form of a
O’Reilly – Java Enterprise Best Practices １９５