The invoke() method is interesting in that it plays a vital part in decoupling the management clients from the managed resources. As discussed in Chapter 2, “Architecture,” and earlier in this chapter, the decoupling of the management applications from the resource is one of the key design points of the JMX-based architecture. In the signature of the invoke() method, this design becomes evident to the application developer. You will notice that the MBeans are always referenced via the ObjectName reference—never directly.

The complete signature of the invoke() method of the MBeanServer interface is as follows:

public Object invoke(ObjectName name, String operationName,
                     Object[] params, String[] signature)
              throws InstanceNotFoundException, MBeanException,
                     ReflectionException

The indirection provided by the object name references allows you to change the component implementation without affecting the existing clients. It is not necessary to detach the client-server communication while components are being updated. If the component is momentarily unavailable, the MBean server could suspend the invocation or redirect it to another MBean. If the MBeans are synchronizing their state, through a database for example, they can implement a simple failover functionality this way.

Another significant point to notice in the invoke() method declaration is how the management operation invocation is detyped and does not rely on a statically typed Java interface that the resource implements. All operation invocations are carried through the invoke() method, which contains the name and signature of the operation you want to invoke. This means that in addition to switching the implementation “behind the scenes” from the client, it is possible for the management interface of a component to evolve—to add a new management attributes and operations. Due to the detyped invocation, this evolution of the component's management interface can occur without affecting existing clients. A new management application can take advantage of the recently added management operation, but the existing clients will continue to work as long as the management interface for the operations they require does not change.

The exception types included in the invoke() method declaration are as follows:

The invoke() method returns an object reference that represents the return value of the management operation. Notice that implicit type conversion between primary return types of a Standard MBean interface to corresponding object types is performed by the agent.

The createMBean() method is overloaded with four different versions in the MBeanServer interface. The different versions of the createMBean() method allow you to create an MBean instance in the agent with a given ObjectName reference, optionally with an explicit constructor signature if the default constructor cannot be used, and an explicit class loader.

The following are declarations of the createMBean() methods in the MBeanServer interface. The exceptions have been left out for the sake of brevity.

public ObjectInstance createMBean(String className,
                                  ObjectName name);

public ObjectInstance createMBean(String className,
                                  ObjectName name,
                                  Object[] params,
                                  String[] signature);
public ObjectInstance createMBean(String className,
                                  ObjectName name,
                                  ObjectName loaderName);

public ObjectInstance createMBean(String className,
                                  ObjectName name,
                                  ObjectName loaderName,
                                  Object[] params,
                                  String[] signature);

The first overloaded version of the createMBean() method instantiates the given class using the default constructor and attempts to register the object as an MBean to the server. If successful, it binds the MBean to a given ObjectName reference.

The second overloaded version of the createMBean() method allows you to define the signature of the constructor that the agent uses to instantiate the MBean component. You can specify the constructor by providing an array of objects that contain the values of the constructor call and an array of String objects that contain the fully qualified classnames of the value objects. The agent can determine the signature of the constructor from the String array with classnames and pass the objects as values to the instantiation call.

The last two overloaded versions of the createMBean() method are identical to the first two with an additional ObjectName reference to a class loader. The loaderName parameter can be used to explicitly define a class loader that should be used to load the MBean component.

The createMBean() method call declares five common exception types to indicate error conditions in either the MBean object initialization or in the MBean registration phase. The ReflectionException can be thrown if the class cannot be loaded with the default class loader or with the explicitly declared class loader. A ReflectionException is also thrown if there were any other exceptions thrown while trying to invoke the MBean's constructor, for example, if the MBean did not declare a public, no-args constructor. You can retrieve the original exception via the getTargetException() method of the ReflectionException class.

The InstanceAlreadyExistsException can be thrown from the createMBean() method call if the ObjectName reference is already in use and mapped to another MBean component. The MBeanRegistrationException can be thrown if the MBean component implements the MBeanRegistration interface and throws an exception in its preRegister() method. You will see the details of the MBeanRegistration interface in the section of the same name later in this chapter.

Also, the MBeanRegistrationException class exposes the original exception class via the getTargetException() method.

The MBeanException wraps any application exceptions that can be thrown from the implementation of the MBean's constructor. The NotCompliantMBeanException is thrown if the classname supplied is not a compliant MBean. This can occur if the agent is unable to find the corresponding Standard MBean interface or the DynamicMBean interface in the class hierarchy.

In addition to these exceptions described, the InstanceNotFoundException object can be thrown by the two createMBean() methods that require an ObjectName reference to the class loader to load the MBean component. In case the ObjectName reference is not found in the agent, the InstanceNotFoundException can be thrown.

Notice that the functionality of the createMBean() invocation is roughly the equivalent of calling the instantiate() and then registerMBean() methods on the server. However, because the createMBean() method does not expose or require direct references to resource objects but works with the ObjectName references, it is better suited for management applications trying to create and register new MBean components remotely. You will see the details of both the instantiate() and registerMBean() methods a bit later in this chapter in the “RegisterMBean and UnregisterMBean” section.

Recall from Chapter 3 the discussion of the JMX notification mechanism. It requires that all MBeans wanting to broadcast management notifications must implement the NotificationBroadcaster interface. This interface includes the addNotificationListener() and removeNotificationListener() methods that are almost identical to the ones declared in the MBeanServer interface. Again, the difference is in the MBeanServer interface where the ObjectName reference is required as a first argument for both method implementations. As with the invoke() method, the addNotificationListener() and removeNotificationListener() methods look up the corresponding MBean reference based on the supplied ObjectName and delegate the method invocation to the registered MBean.

public void addNotificationListener(ObjectName name,
                                    NotificationListener listener,
                                    NotificationFilter filter,
                                    Object handback)
                       throws InstanceNotFoundException;

public void addNotificationListener(ObjectName name,
                                    ObjectName listener,
                                    NotificationFilter filter,
                                    Object handback)
                       throws InstanceNotFoundException;
public void removeNotificationListener(
                                    ObjectName name,
                                    NotificationListener listener)
                       throws InstanceNotFoundException,
                              ListenerNotFoundException;

public void removeNotificationListener(
                                    ObjectName name,
                                    ObjectName listener)
                       throws InstanceNotFoundException,
                              ListenerNotFoundException;

The second variation of both the addNotificationListener() and removeNotificationListener() methods allows you to register another MBean directly as a listener to the broadcaster MBean. This will become especially useful when dealing with remote notifications.

The getAttribute() and setAttribute()methods also have their corresponding equivalents in the DynamicMBean interface. In the case of the Standard MBean instrumentation, the agent attempts to invoke a correct accessor method by introspecting the MBean class and building the invocation based on the Standard MBean naming conventions.

The registerMBean() call allows you to register a pre-existing object as an MBean to the server. Notice that if the ObjectName argument is null, the MBean may provide an ObjectName itself by implementing the MBeanRegistration interface. You will see how this works in practice when the interface is covered in detail.

The following is the declaration of registerMBean() and unregisterMBean() methods:

public ObjectInstance registerMBean(Object object,
                                    ObjectName name)
                            throws InstanceAlreadyExistsException,
                                   MBeanRegistrationException,
                                   NotCompliantMBeanException;

public void unregisterMBean(ObjectName name)
                            throws InstanceNotFoundException,
                                   MBeanRegistrationException;

The MBean may cancel the registration by throwing an exception from its preRegister() method of an MBeanRegistration interface. In that case, the exception will be wrapped in the MBeanRegistrationException instance and can be retrieved through the getTargetException() method. In a similar fashion, the unregistering of an MBean can be prevented by an exception thrown from the preDeregister() method of the MBeanRegistration interface. Also, notice that the agent does attempt to verify that the class being registered is a valid MBean. If a validation error occurs, a NotCompliantMBeanException is thrown by the registerMBean() method.

Because the registerMBean() method takes a reference to a pre-existing Java object as an argument, it often does not make sense to use this method from a remote location. Because the distribution layer for the JMX is not yet defined, some JMX connectors may choose to not allow this method to be accessed remotely at all. Remember that you can always use the createMBean() methods instead.

The queryMBeans() and queryNames() methods allow you to query the server for MBean object instances or object names. The query can be built by defining a name pattern as an ObjectName argument or by providing a query expression to the server. The queries are explained in detail at the end of this chapter.

public Set queryMBeans(ObjectName name, QueryExp query);

public Set queryNames(ObjectName name, QueryExp query);

Both methods return either a set of ObjectInstance objects or ObjectName objects that represent the matching MBeans for the given query or object name pattern.

The getDefaultDomain() method returns the default domain string used by the agent. If the MBean is registered with an object name that does not contain the domain part, the return value of this method is used as a default domain value.

The getMBeanCount() method returns the number of MBeans registered to the MBean server.

The getMBeanInfo() method returns the metadata of a given MBean. The management applications can use the returned MBeanInfo object to discover the management operations, attributes, and notifications of the MBean.

The isInstanceOf() method allows you to test if a given MBean is an instance of a class type. The classname is given as an argument to this method.

The isRegistered() method allows you to test whether an MBean registered to a given object name already exists in the MBean server.

The preRegister() method has two parameters—a MBeanServer reference and an ObjectName reference. The MBeanServer reference is a reference to the MBean server to which the MBean is being registered. If the MBean requires interaction with the server, for example to use services of other MBeans, this reference should be stored by the MBean component.

The object name reference is the name that was given as a parameter with the registerMBean() or createMBean() method call on the MBean server. Notice that the return type of the preRegister() method is an ObjectName type. If a null pointer is passed as an object name when the MBean is being registered, the MBean is free to supply its own ObjectName instance to the agent.

It is also possible to cancel the registration of the MBean by throwing an exception from the preRegister() method. If any exceptions from the method are thrown, the agent will not register the MBean to the server. In this case, the agent will create an MBeanRegistrationException Java Management Extensions Specification that wraps the original exception and propagates it to the original caller.

The preRegister() method is useful for initializing the resources the MBean may need. It is also possible for the MBean to investigate the MBean server if it supports the required services and has them available. It is also possible to cancel the registration of an MBean in the preRegister() method.

The sequence of calls invoked when the MBean is being registered and implements the MBeanRegistration interface is shown in Figure 6.2.

Figure 6.2. Sequence of MBeanRegistration interface callbacks on MBean registration.

The preDeregister() method should be used to clean up any resources the MBean may have acquired before it is unregistered from the server. If there is an exception thrown from invocation of the preDeregister() method, it is caught by the agent and wrapped into an MBeanRegistrationException instance before it's propagated to the caller. The postDeregister() method callback is made by the agent after the MBean has been unregistered from the MBean server. This method can be used for any additional cleanup operations that are required after the MBean is no longer registered to the agent.

The sequence of calls invoked when the MBean is being unregistered from the server is shown in Figure 6.3.

Figure 6.3. Sequence of MBeanRegistration interface callbacks on MBean unregistration.

The scope is defined by creating an object name that matches a pattern of MBean names in the agent. For example, all MBeans in the Connector management domain can be matched by creating the following object name:

Connector:*

Any query executed with this scope will only be applied to the MBeans registered under the specific domain. Setting the query scope to null indicates that all MBeans in the server will be within the scope of the query. This is the equivalent of setting the scope to *:*.

The domain part of the object name can also use the '?' sign for defining patterns that match a single character. For example, an object name pattern

Domain?:*

will match management domain names such as DomainA, DomainB, and so on.

The key property list part of the object name can also use the asterisk (*) wildcard to create a name pattern. Notice, however, that only complete property key-value pairs are considered. For example, you cannot use the wildcard to match a specific property value. You can use the wildcard to require that the scope of the query contains only MBeans whose object names have a specific property value set. For example,

Service:type=automatic,*
Service:type=*           // NOT VALID !!

The first scope will match all MBeans in the Service domain that have a type property with value automatic set. However, the second scope is not valid because no pattern matching is performed on the property values.

The JMX specification does not define a specific query language for the MBean server queries. Instead, the queries are built programmatically with the help of a Query class. The Query class contains a set of static methods that return query expressions based on the given parameters. These query expressions are represented by the QueryExp interface that both the queryMBeans() and queryNames() methods use.

The Query class contains methods for query expressions, such as greater than, less than, equals, and so on. These query expressions can be combined with relational query expressions and, or, not, and so on. In addition, there are query expressions for string values such as "starts With", "ends With", and "contains" string. These types of queries are represented in the JMX API with a QueryExp interface. The Query class returns instances of this interface when you use the query expression methods.

For values used in the queries, another interface, ValueExp, is declared in the JMX API. Again, you get the implementations of the value expressions by using the factory methods in the Query class.

For example, to build a simple string matching query on a management attribute Name, you could write the following query generation code:

AttributeValueExp attribute = Query.attr("Name");
StringValueExp name = Query.value("John");
QueryExp query = Query.match(attribute, name);

In this example, both AttributeValueExp and StringValueExp classes implement the ValueExp interface. The match method requires these two classes as parameters and returns an instance of the QueryExp interface representing the query where the attribute Name matches the string John. The query expression can then be invoked on the server:

Set resultSet = server.queryNames(new ObjectName("*:*"), query);

The returned collection would contain the ObjectName references to all MBeans that have a Name management attribute containing the string value "John".

Table 6.2 lists some the methods of the Query class.

and(QueryExp a, QueryExp b)
or(QueryExp a, QueryExp b)
not(QueryExp q)

anySubString(AttributeValueExp attr,
   StringValueExp string)

finalSubString(AttributeValueExp attr,
   StringValueExp string)

initialSubString(AttributeValueExp attr,
   StringValueExp string)

match(AttributeValueExp attr,
   StringValueExp string)

between(ValueExp a, ValueExp b, ValueExp c)
in(ValueExp a, ValueExp[] set)

plus(ValueExp a, ValueExp b)
minus(ValueExp a, ValueExp b)
times(ValueExp a, ValueExp b)
div(ValueExp a, ValueExp b)

eq(ValueExp a, ValueExp b)
geq(ValueExp a, ValueExp b)
gt(ValueExp a, ValueExp b)
leq(ValueExp a, ValueExp b)
It(ValueExp a, ValueExp b

Listing 6.2 shows an example code of some simple queries that can be executed on the MBean server.

package book.jmx.examples;

import java.util.*;
import javax.management.*;

public class Queries {

  public static void main(String[] args) throws Exception {
    MBeanServer server = MBeanServerFactory.createMBeanServer();

    ObjectName john = new ObjectName("DomainA:name=john");
    ObjectName mike = new ObjectName("DomainA:name=mike");
    ObjectName xena = new ObjectName("DomainA:name=xena");

    server.createMBean("book.jmx.examples.User", john);
    server.createMBean("book.jmx.examples.User", mike);
    server.createMBean("book.jmx.examples.User", xena);

    server.setAttribute(john, new Attribute("Name", "John"));
    server.setAttribute(mike, new Attribute("Name", "Mike"));
    server.setAttribute(xena, new Attribute("Name", "Xena"));

    server.setAttribute(john,
        new Attribute("Address", "King's Road 11"));
    server.setAttribute(mike,
        new Attribute("Address", "Strawberry St. 5"));
    server.setAttribute(xena,
        new Attribute("Address", "Strawberry St. 12"));
    testQueries(server);
  }

  static void testQueries(MBeanServer server) throws Exception {

    QueryExp exp =
        Query.match(Query.attr("Name"), Query.value("John"));

    ObjectName scope = new ObjectName("DomainA:*");
    Set set      = server.queryNames(scope, exp);
    Iterator it  = set.iterator();

    System.out.println("MBeans with attribute Name = 'John' n");

    while (it.hasNext()) {
      System.out.println(it.next());
    }

    scope = new ObjectName("DomainA:*");
    exp   = Query.initialSubString(Query.attr("Address"),
                                   Query.value("Strawberry"));

    set   = server.queryNames(scope, exp);
    it    = set.iterator();

    System.out.println(
        " nMBeans with Address startsWith 'Strawberry' n");

    while (it.hasNext()) {
      System.out.println(it.next());
    }
  }

}

When you compile and run the queries example, you should see the following output on your console.

C: Examples> javac -d . -classpath jmx lib jmxri.jar Queries.java

C: Examples> java -classpath .;jmx lib jmxri.jar book.jmx.examples.Queries

MBeans with attribute Name = 'John'
DomainA:name=john

MBeans with Address startsWith 'Strawberry'

DomainA:name=mike
DomainA:name=xena

C: Examples>