5.2 Object Naming

The MBeanServer uses object names to refer to the MBeans it manages . Using an object name rather than a direct object reference to an MBean creates a level of indirection that allows the MBeanServer to help manage the MBean's lifecycle, control access to it, and associate additional information with the MBean.

An object name is associated with an MBean when it is created by or registered with the MBeanServer. All future interactions with that MBean via the MBeanServer use that object name. Management applications never get a direct reference to the MBean. Thus the resource represented by the MBean is manageable only for the duration of its MBeanServer registration. This sort of control is important when an MBean's resource is unavailable periodically, perhaps because of an upgrade or reconfiguration. In addition, using names rather than references prevents the management application from using additional knowledge it might have about an MBean ”for example, the actual class that implements the MBean's interface ”to call methods or access properties outside the MBean's defined management interface.

So what do these object names look like? Here's an example:

 book/examples:name=ExampleName,chapter=5. 

Every object name has two parts : the domain, which is to the left of the colon , and the key properties to the right.

5.2.1 Object Name Domains

According to the JMX specification, the domain part of an object name is a case-sensitive string: "It provides a structure for the naming space within a JMX agent or within a global management solution." A JMX agent might play host to hundreds of MBeans. Selecting an MBean or set of MBeans from a single large MBean pool is tedious , error prone, and possibly computationally expensive. Domains help reduce that complexity by imposing some order on the agent's collection of MBeans ”for example, organizing MBeans by location, associated application, or logical application.

For example, consider a generic service container that hosts various network service components . The container itself would be instrumented by one set of MBeans, and each hosted service would introduce its own set of MBeans. We could use the domain part of the object name to organize this collection of MBeans into the hierarchy illustrated in Figure 5.1.

Figure 5.1. MBean Naming Hierarchy

How the structure of domain is expressed is up to the application developer. In the example in Figure 5.1 we used slashes to separate domain components   la the UNIX file system. But we might have used a period as a separator instead. The only restriction JMX puts on the domain name is that it not contain any of these five characters :

 :     ,     =     *     ? 

5.2.2 Object Name Key Properties

The key properties component of an object name is used to uniquely identify an MBean within its domain. Key properties are a set of name/value pairs that express an MBean's identity. Suppose that we have multiple components from vendor A to manage; we can use the key properties name and owner to tell them apart:

 Component/VendorA:name=goldQueue,owner=HttpService  Component/VendorA:name=silverQueue,owner=HttpService Component/VendorA:name=bronzeQueue,owner=HttpService 

In addition to expressing an MBean's identity, key properties provide a way to pass configuration information to an MBean. For example, adding a priority property to our ServiceQueue object names, like this:

 Component/VendorA:name=silverQueue,priority=6,owner=HttpService 

provides a means of setting ServiceQueue 's priority without resorting to .property files. When we discuss MBean creation in Section 5.3.1, we'll explain how an MBean gets access to these configuration properties.

We have been writing object names in canonical form ” that is, as strings with the names of the key properties sorted in lexical order. In practice, the key properties can appear in any order in the string representation.

5.2.3 The ObjectName Class

Instances of the ObjectName class are used to identify MBeans registered with the MBeanServer and to specify a pattern in the context of an MBeanServer query. We'll look at the query service later in this chapter; here we examine the essential methods of the ObjectName class.

There are three ObjectName constructors:

 ObjectName(String name)  ObjectName(String domain, Hashtable keyproperties) ObjectName(String domain, String key, String property) 

The first version takes the string representation of an object name, in canonical form or not, and creates the corresponding ObjectName instance. The last two are variations on a theme: create instance of ObjectName , given a domain string and a set of key properties. The second and third constructors differ only in the way the set of key properties is expressed; in the Hashtable version, a set of N key properties is provided via Hashtable , and in the final version a single key property is passed in as separate strings. Each of the constructors throws the MalformedObjectNameException if any of its parameters are not formatted correctly ”for example, if the domain part contains an illegal character.

The following code illustrates the construction of three different object names:

 ObjectName goldq = new ObjectName(      "Component/VendorA:name=goldQueue,owner=HttpService"); Hashtable sqprops = new Hashtable(); sqprops.put("name", "silverQueue"); sqprops.put("priority", "6"); sqprops.put("owner", "HttpService"); ObjectName silverq = new ObjectName("Component/VendorA", sqprops); ObjectName bronzeq = new ObjectName(     "Component/VendorA", "name", "bronzeQueue"); 

The rest of the ObjectName methods are getters that retrieve ObjectName 's domain and key property attributes in various forms:

 String getDomain()  String getKeyProperty(String key) Hashtable getKeyPropertyList() String getKeyPropertyListString() String getCanonicalName() String getCanonicalKeyPropertyListString() 

Note that object names are immutable. Therefore, adding additional entries to the hash table returned by getKeyPropertyList() has no effect on the object name itself.

Well-structured names can facilitate finding MBeans and grouping MBeans for a management application. We recommend that key properties contain at least one name or id property and a type property that indicates the managed resource type ”for example, httpd , printer , or jvm .

5.2.4 The ObjectInstance Class

The ObjectInstance class maps an MBean's object name to the actual Java class that implements the MBean's management interface. All of the MBean creation mechanisms, as well as registerMBean() and the various flavors of createMBean() that we'll discuss in Section 5.3, return an instance of ObjectInstance . In addition, given an ObjectName instance, the MBeanServer's getObjectInstance() method returns the corresponding instance of ObjectInstance .

Why would a developer using JMX ever be interested in such a mapping? Regardless of which Java class implements a given MBean interface, the attributes and methods exposed by that interface are the only things available to a management application. Given that reality, what difference does the implementing class make? Suppose we have an MBean associated with a particular resource ”say, a router ”and we want to create another one just like it to represent a new router that we've added to our network. The MBeanServer doesn't provide a cloneMBean() method, so we'll have to implement something similar ourselves using methods like createMBean() that the MBeanServer does provide. The problem is that the MBeanServer's createMBean() methods all require a Java class name. That's where ObjectInstance comes in. We can take our existing MBean's ObjectName , turn it into an ObjectInstance via getObjectInstance() , and then extract the required class name from ObjectInstance using ObjectInstance 's getClassName() method as illustrated here:

 public void cloneMBean(MBeanServer mbs,                         ObjectName prototype,                        ObjectName clone) {   ObjectInstance oi = mbs.getObjectInstance(prototype);   String cn = oi.getClassName();   mbs.createMBean(cn, clone); } 

The ObjectInstance class provides two constructors:

 ObjectInstance(ObjectName objname, String clazz)  ObjectInstance(String objname, String clazz) 

In practice they are seldom used because all of the MBeanServer methods take instances of ObjectName as parameters. The accessor methods that the ObjectInstance class supports are

 String getClassName()  ObjectName getObjectName() 

These methods are typically used to retrieve the underlying Java class or object name from an instance of ObjectInstance returned by one of the MBeanServer's create methods.