dcsimg
December 2, 2016
Hot Topics:

Standard MBeans

  • May 23, 2003
  • By O'Reilly & Associates
  • Send Email »
  • More Articles »

Throwing Exceptions from Your MBeans

There will be times when you need to throw an exception from your MBeans—for example, when a setter needs to report that a bad value has been passed. Suppose that the setter for the QueueSize attribute on the Queue class needs to report when an attempt is made to shrink the queue (remember, the queue is allowed only to grow). If I want to throw such an exception, I have to change the declaration on the MBean interface:

public interface QueueMBean extends BasicMBean {
//. . .
  public setQueueSize(int value) throws Exception;
//. . .
}

as well as the implementing class:

//. . .
import sample.exception.*;
//. . .
public class Queue extends Basic implements QueueMBean {
//. . .
  public synchronized setQueueSize(int value) throws Exception {
    if (!_suspended) {
      if (value >_backingStore.length) {
        Object [] newStore == new Object [value ];
        System.arraycopy(_backingStore, 0, newStore, 0,
                         _backingStore.length);
      }
      else {
        throw new GenericException("Queue.setQueueSize(): ERROR: "
        + "Queue size may not be set less than the current size
        of " + this.getQueueSize() + ". The value of " + value
        + "is invalid.");
      }
    }
    notifyAll();
  }
}

If we attempt to set the value of the queue to be less than its current size (i.e., to shrink the queue), an exception containing a message describing the mistake will be thrown to the management application.

It is perfectly fine to use a user-defined exception. In this example, I used one called GenericException, located in the sample.exception package:

package sample.exception;

public class GenericException extends Exception {
  public GenericException(String message) {
    super(message);
    }
}

The Driver Program: Controller.main( )

As its name implies, Controller is the class that contains the main() method that drives the application and controls the activities that occur within it. This class has a number of interesting features. Recall that there are three levels to the JMX architecture: instrumentation, agent, and distributed services. So far, we have been concerned with only the instrumentation level. However, instrumentation by itself isn't very interesting. Controller is part of the agent level, and it performs a few duties that allow the other standard MBeans (e.g., Queue and Worker) to be plugged into the MBean server. In this section, we will discuss some of the duties of this agent program that are unrelated to standard MBeans per se but that are important for understanding JMX.

The ObjectName class

The ObjectName class is provided by the RI and is crucial to the MBean registration process. Every MBean must be represented by an ObjectName in the MBean server and no two MBeans may be represented by the same ObjectName. Each ObjectName contains a string made up of two components: the domain name and the key property list. The combination of domain name and key property list must be unique for any given MBean and has the format:

domain-name:key1=value1 [,key2=value2,...,keyN=valueN ]

where domain-name is the domain name, followed by a colon (no spaces), followed by at least one key property. Think of a domain name as JMX's namespace mechanism. A key property is just a name/value pair, where each property name must be unique. For example, the object name used by the Queue instance into which the Supplier places its work units is:

DefaultDomain:name=Queue

Notice the domain name. Every compliant JMX implementation must provide a default domain name. For the JMX 1.0 RI, that name is DefaultDomain, but you can't depend on this to be the case all of the time. The MBean server provides a method called getDefaultDomain() that returns the name of the default domain.

As a convenience, the JMX 1.0 RI allows you to pass an empty string for the domain name if you want to use the default domain. However, the domain name you pass may never be null, or a MalformedObjectNameException will be thrown.

There is only one restriction on domain names: you cannot use JMImplementation as the domain name for your MBeans. This domain name is reserved for the implementation (hence the name) and contains a single metadata MBean that provides information about the implementation, such as its name, version, and vendor.

To create an ObjectName instance, use one of the three constructors provided. The simplest constructor to use takes a single String parameter that contains the full object name string, as described above:

//. . .
try {
  String myObjName = "UserDomain:Name=Worker, Role=Supplier";
  ObjectName = new ObjectName(myObjName);
} catch (MalformedObjectNameException e){
//. . .
}

In this example, you can also leave off the domain name preceding the colon if you want to use the default domain:

//. . .
try {
  String myObjName = ":Name=Worker, Role=Supplier";
  ObjectName = new ObjectName(myObjName);
}catch (MalformedObjectNameException e){
//. . .
}

The second constructor is provided as a convenience when you want to provide only one key property. It takes three String arguments: the domain name, the key property name, and the key property value.

//. . .
try {
  //String objName = "UserDomain:Name=Controller";
  ObjectName = new ObjectName("UserDomain", "Name", "Controller");
}catch (MalformedObjectNameException e){
//. . .
}

The third constructor is used when you want to use the contents of a Hashtable to set the key property list. It takes two arguments: the domain name and a Hashtable reference containing the name/value pairs that make up the key property list.

//. . .
try {
  Hashtable table = new Hashtable();
  table.put("Name", "Worker");
  table.put("Role", "Supplier");
  ObjectName = new ObjectName("UserDomain", table);
}catch (MalformedObjectNameException e) {
//. . .
}

Once the ObjectName instance for your MBean has been created successfully, you can use that ObjectName to register the MBean.





Page 6 of 7



Comment and Contribute

 


(Maximum characters: 1200). You have characters left.

 

 


Enterprise Development Update

Don't miss an article. Subscribe to our newsletter below.

Sitemap | Contact Us

Thanks for your registration, follow us on our social networks to keep up-to-date
Rocket Fuel