The getAttribute() and getAttributes() methods are used by the agent to retrieve the values of the management attributes from the Dynamic MBean. When you create a Dynamic MBean, it is up to you to map the named attributes to their corresponding values in the MBean implementation and then return these values to the agent on request. The full declaration of the getAttribute() method is as follows:

public Object getAttribute(String attribute) throws
   AttributeNotFoundException, MBeanException, ReflectionException;

The returned object must contain the value of the attribute. The runtime type of the returned object must also match the Java type defined in the Dynamic MBean's metadata classes. You can use the AttributeNotFoundException class to indicate to the agent that the named attribute was not found or its value could not be retrieved. The MBeanException class can be used for wrapping any checked exceptions that may be thrown by the getAttribute() implementation, such as the java.io.IOException. The ReflectionException class can be used to propagate exceptions resulting from the use of the java.lang.reflect package back to the agent. You will learn more about the JMX agent exception mechanism and each declared exception in Chapter 6, “MBean Server.”

Listing 4.2 is an example implementation of the getAttribute() method that processes the attributes of the User MBean you built as an example for Standard MBeans. This code snippet shows how you would deal with readable attributes for dynamic User MBean.

...

 public Object getAttribute(String attribute) throws
                               AttributeNotFoundException,
                               MBeanException,
                               ReflectionException {

    if (attribute == null || attribute.equals(""))
        throw new IllegalArgumentException(
            "null or empty attribute name"
        );

    // map the named attributes to fields
    if (attribute.equals("Name"))
        return name;

    if (attribute.equals("Address"))
        return address;

    if (attribute.equals("PhoneNumbers"))
        return numbers;

    if (attribute.equals("ID"))
        return new Long(id);

    throw new AttributeNotFoundException(
        "Attribute " + attribute + " not found."
    );
}

...

In Listing 4.2, you first check the attribute parameter for a null reference and empty strings. An attempt to retrieve an attribute with a null or empty name will yield an IllegalArgumentException being thrown from the implementation. The agent will catch this and other runtime exceptions and will wrap them in a subclass of javax.management.JMRuntimeException.

If the given attribute parameter is valid, a simple comparison for the parameter string is made next. Remember that the MBean attribute names are case sensitive, so don't confuse the MBean attribute names with the field names in the implementation class. In a more robust implementation than that shown here, it would be a good idea to define the attribute names as constants to eliminate the possibility of simple typing errors.

Again, notice that the management attribute names can be independent of the underlying implementation names. You can use names in the management interface that are more self-explanatory and consistent than the names used in the resource implementation. With Dynamic MBeans it is up to you to map the attribute name to the object field names.

The getAttributes() method returns the values of several MBean attributes. The return type is an AttributeList class defined in the JMX API, which is a subclass of the ArrayList class in the Java Collections framework. The returned list must contain a set of Attribute objects that hold the name and the value of the requested attribute.

The getAttributes() method does not signal errors using the Java exception mechanism. Instead, any attributes whose value retrieval caused an error condition should be left out of the return list.

The setAttribute() and setAttributes() methods are the corresponding setter methods to the getter methods in the Dynamic MBean interface. Again, setAttribute() is used for setting a single MBean attribute value, and it is up to the MBean implementation to map the given attribute name in the implementation and set the attribute value. The setAttribute() method uses the Attribute class as a wrapper for passing the attribute name and value. The full declaration of the setAttribute() method defines several exceptions that can be used for signaling error conditions.

public void setAttribute(Attribute attribute) throws
         AttributeNotFoundException, InvalidAttributeValueException,
         MBeanException, ReflectionException;

The AttributeNotFoundException class can be used to indicate if the given attribute does not exist in the MBean. InvalidAttributeValueException should be used to indicate the value given in the Attribute object is not acceptable for the given attribute or the value is of the wrong type. The use of MBeanException class is similar to that seen with the getAttribute() method. If the attribute-set operation causes a checked exception to be thrown in the MBean implementation, it can be caught, wrapped into an MBeanException object, and rethrown to be managed by the agent. Similarly, the ReflectionException class can be used to wrap exceptions resulting from using the operations of java.lang.reflect package in setting the MBean's state.

Listing 4.3 is an example implementation of the setAttribute() method. It implements the attributes for the example User MBean you built as a Standard MBean example and shows how similar functionality is achieved with Dynamic MBeans. Each attribute name is matched individually and cast to String or to an array of String objects. In case there is a type mismatch between the provided attribute type and the expected type, the resulting ClassCastException is caught and rethrown as an InvalidAttributeValueException.

...

 public void setAttribute(Attribute attribute) throws
                        AttributeNotFoundException,
                        InvalidAttributeValueException,
                        MBeanException,
                        ReflectionException {

   if (attribute == null) throw new
       AttributeNotFoundException("null attribute");

   // map the attributes to fields
   try {
      if (attribute.getName().equals("Name"))
         this.name = (String)attribute.getValue();

      else if (attribute.getName().equals("Address"))
         this.address = (String)attribute.getValue();

      else if (attribute.getName().equals("PhoneNumbers"))
         this.numbers = (String[])attribute.getValue();

      else if (attribute.getName().equals("Password"))
         this.passwd = (String)attribute.getValue();

      else
         throw new AttributeNotFoundException(
            "attribute "+attribute.getName()+" not found."
         );
   }
   catch (ClassCastException e) {

      // In case of the type mismatch, throw an
      // InvalidAttributeValueException
      throw new InvalidAttributeValueException(
          "Invalid attribute type " +
          attribute.getValue().getClass().getName()
      );
   }
}

...

The setAttributes() method takes an AttributeList as a parameter and allows for the setting of several MBean attributes at once. Similar to getAttributes(), this method does not indicate error conditions using the exception mechanism but returns a list of attributes whose values were successfully set. In case there were errors in setting some of the attributes, they will not be added to the returned result set. You can quickly determine if all attributes were successfully set by comparing the sizes of the input list and return list.

The invoke() method is called by the agent when a request to invoke a management operation has been made. The parameters passed with the call include the operation's name, an array of objects containing the values for the operation parameters, and an array of strings declaring the types of the parameter values. Again, the MBean implementation is responsible for parsing all of this information and mapping the invoke call to the appropriate methods in the implementation. The checked exceptions thrown by the implementation can be passed back to the agent by wrapping them with the MBeanException class. The return type from the invoke operation must match the type declared in the management operation metadata for this Dynamic MBean.

Listing 4.4 shows a code snippet that handles the management operation invocation of a Dynamic MBean. Notice that each of the management operations are mapped from their names to method calls in the implementation class.

...

public Object invoke(String actionName, Object[] params,
                     String[] signature) throws
                     MBeanException, ReflectionException {

   if (actionName == null || actionName.equals(""))
     throw new IllegalArgumentException("null operation");

   // map management operations
   if (actionName.equals("printInfo")
     return printInfo();

   else if (actionName.equals("addPhoneNumber")) {
     addPhoneNumber((String)params[0]);
     return null;
   }

   else if (actionName.equals("removePhoneNumber")) {
      removePhoneNumber(((Integer)params[0]).intValue());
      return null;
   }

   else throw new IllegalArgumentException(
             "unknown operation " + actionName);
}

...

You have now seen how to implement the basic mechanisms for readable and writable management attributes with Dynamic MBeans and how management operation invocations are implemented. Next, you'll look into the metadata structures of the Dynamic MBeans.

When creating Dynamic MBeans, the metadata needs to be explicitly declared by the programmer. In the case of the Standard MBeans, the metadata was automatically built by the agent via Java language introspection. Now you will see what it is that the agent actually created from the Standard MBean's interface.

The MBeanInfo class fully describes the management interface of an MBean. Using the methods of this class, you can retrieve metadata for the attributes, operations, constructors, and notifications of the MBean.

Table 4.1 lists the methods of the MBeanInfo class with short descriptions of their use.

The metadata classes are available to all clients through the MBeanServer interface. The metadata can also be extended to provide a richer description of the management interface to the agent and the management applications. You will see an example of this in Chapter 5, “Model MBeans.”

The MBeanFeatureInfo class is a superclass for all the metadata classes in the javax.management package, except the MBeanInfo class. This class provides an access to two fields, the name and the description of an MBean metadata object. The subclasses use the name to return the name of the MBean attribute, operation, parameter, constructor, or notification. The description is used to return a human readable string describing the purpose and effects of the MBean metadata element. This is often a string that gives a short description of the management operation or describes the semantics of an attribute, parameter, or a notification. The description string can be used by the management tools to describe the managed resource and its properties to the user.

Notice that when creating Standard MBeans, it is not possible to set the descriptions for the management interface elements. The agent created the metadata structures automatically by introspecting the Standard MBean interface and had no access to any descriptive information. Unfortunately, there isn't a mechanism defined in the JMX specification that would allow the Standard MBeans to relay this type of information to the agent. You need to use Dynamic MBeans or their extensions to be able to provide additional metadata, such as the attribute and operation descriptions.

The MBeanAttributeInfo class is used to describe the attributes of an MBean. The class contains the information about the attribute's runtime type, name, description, and its access type. The name is the programmatic name of the management attribute. The description should be a human readable description of the attribute and its intended use.

The runtime type string must be a fully qualified name of the class, meaning that the package declaration must be included in the classname, such as java.lang.String. Also note that this rule applies to the Java array types as well as the primitive types. For example, the fully qualified classname of an array of String objects is "[Ljava.lang.String;", and a two-dimensional array of String objects is "[[Ljava.lang.String;". For arrays of primitive types, it gets even hairier. For example, the fully qualified classname of an array of long types is "[J".

Table 4.2 shows examples of some fully qualified class names.

More details on the string representation of the classnames can be found in the API documentation of the java.lang.Class.getName() method.

Because trying to remember the fully qualified names can be difficult and error-prone, especially in the case of arrays, there's a workaround you can use when creating the metadata classes. The Java language specification defines an expression called a class literal. You can use the class literal with all types in the Java language, including primitive types and type void, to access the Class object. This is useful, because the Class object implements the getName() method, which returns a fully-qualified name of the class. For example, when creating the MBeanAttributeInfo object for the array attribute PhoneNumbers in the User MBean, you could write the code as follows:

...

 MBeanAttributeInfo numbers = new MBeanAttributeInfo(
   "PhoneNumbers",
   String[].class.getName(), // fully qualified class name
   "User's phone numbers.",
   true, true, false
 );

...

So, instead of using the cumbersome textual representation of "[Ljava.lang.String;" for an array of strings, you can let the Java class libraries do the work for you by accessing the array class and then calling its getName() method. The same approach works for a multidimensional array of primitive types, for example, long[][][] or even for type void. You can test it with the following snippet of Java code:

System.out.println(void.class.getName());
System.out.println(long[][][].class.getName());

The MBeanParameterInfo describes the parameters for MBean constructors and operations. As with the other metadata classes, the MBeanParameterInfo inherits the name and description properties from its superclass MBeanFeatureInfo. The name property, along with the description string, is often displayed to the user with generic management tools and should contain the required information for the user to be able to either create a new instance of the MBean or invoke one of its operations. In addition, the MBeanParameterInfo class contains the type of the parameter, again a fully qualified classname of the type. This string is accessible through the getType() method of the MBeanParameterInfo class.

The MBeanOperationInfo class describes the management operations of an MBean. The object contains information about the operation's name and the description, both inherited from the MBeanFeatureInfo class, the type of the method's return value, the method's signature, and the impact of the operation on the MBean.

The signature consists of an array of MBeanParameterInfo objects that distinguishes overloaded methods from one another. The return type, as usual, must be a fully qualified classname of the returned object instance. The impact value can be used by the MBean developer to give the management application some idea how the invocation of the operation is going to affect the MBean's state.

The JMX API defines four values that can be used to describe the method's impact. The constants shown in Table 4.3 are declared in the MBeanOperationInfo class.

The impact field can be used to implement a coarse-grained scheme of determining which operations should be exposed to the user in the client. It is the responsibility of the Dynamic MBean developer to assign the correct impact values in the MBeanOperationInfo metadata objects. The class provides the accessor method getImpact() for querying the impact of the operation.

Listing 4.5 shows the metadata implementation of one of the User MBean operations, addPhoneNumber(), as it would be implemented with a Dynamic MBean. Notice that the signature of the management operation is built using an array of MBeanParameterInfo objects, each of which will include the name of the parameter, its runtime type, and a description of its purpose. The impact value is set to MBeanOperationInfo.ACTION as the addPhoneNumber() changes the state of the DynamicUser object.

...

 // addPhoneNumber operation metadata
 MBeanOperationInfo addPhoneNumber =
   new MBeanOperationInfo(
     "addPhoneNumber",               // operation name
     "Add a new phone number.",      // description

         // parameters
         new MBeanParameterInfo[] {
           new MBeanParameterInfo(
             "number",               // parameter name
             String.class.getName(), // parameter type
             "The number to add."    // parameter descr.
           )
         } ,

     void.class.getName(),           // return type void
     MBeanOperationInfo.ACTION       // impact: ACTION
 );

...

The MBeanConstructorInfo class describes the constructors of an MBean that are exposed to management. The MBeanConstructorInfo contains a name for the constructor, a description string for the management applications to display to the user, and an array of metadata objects describing the parameters of the constructor. The parameters make up the signature of the constructor that is used to differentiate a set of constructors from each other. You build up the parameters by using the MBeanParameterInfo objects and can query the array by calling the getSignature() method of the MBeanConstructorInfo class.

For example, to define a default, no-args constructor for the User MBean, create the metadata object in Listing 4.6.

...

 MBeanConstructorInfo defaultConstructor =
    new MBeanConstructorInfo(
          "Default Constructor",           // name
          "Creates a new user instance.",  // description
          null                             // parameters
    );
...

Notifications are part of the MBean's management interface, so the MBeanNotificationInfo class is required to describe the notifications broadcast by the MBean. The management applications can use the MBeanNotificationInfo object to discover the details of the notifications emitted by the MBean.

The use of the name field in the MBeanNotificationInfo class differs slightly from the other metadata classes in the JMX API. In the case of the notifications, the meaning of the field is restricted to contain the fully qualified classname of the actual notification object that is being broadcast. The description can be freely formed to describe the purpose of the notification to the management applications.

In addition to the name and description, the MBeanNotificationInfo class describes all the notification types that are sent using the class declared in the name field. The notification types are accessible to the management applications via the getNotifTypes() method of the MBeanNotificationInfo class.

You may remember from Chapter 3, “Standard MBeans,” where notifications were discussed, that the MBeanNotificationInfo is used with both the Standard MBean and Dynamic MBean implementations.

In the BroadcastingUser MBean, you created the following MBeanNotificationInfo instances (see Listing 4.7).

new MBeanNotificationInfo[] {

  // notification for the remove operation
  new MBeanNotificationInfo(
    new String[]
      {  "example.user.remove" } ,  // notif. types
    Notification.class.getName(),   // notif. class
    "User Notifications."           // description
  ),

  // attribute change notification type
  new MBeanNotificationInfo(
    new String[] {
      AttributeChangeNotification.ATTRIBUTE_CHANGE
    } ,
    AttributeChangeNotification.class.getName(),
    "User attribute change notification."
  )
} ;

This code snippet creates the metadata for two different notification class types, Notification and AttributeChangeNotification, each of which is used for sending one notification type.

The Attribute class is a convenience class in the JMX API for representing the management attributes of an MBean. The class associates the attribute name with its value and provides the accessor methods for reading these values. It is used in the JMX interfaces, such as the DynamicMBean interface in getAttribute() and setAttribute() methods.

The AttributeList class is a subclass of the ArrayList class in the Java Collection framework. It has been extended to accept Attribute object instances in its insertion methods to ensure type safety in the collection. The AttributeList is used in the DynamicMBean interface setAttributes() and getAttributes() methods.