7.1 Naming

I l @ ve RuBoard

JMX provides a great deal of flexibility in how you can name your MBeans. With only a few exceptions imposed by the specification, the sky is the limit. However, with this flexibility comes a potential hazard : collisions between names. You should make every effort to give your MBeans unique names . There are two components of an MBean object name: the domain name and the key property list. In this section, we will look at how to use these two components of the object name to mitigate the risk of MBean naming collisions.

In this section, the term "object name" is used to refer to the string representation of the ObjectName instance required to register an MBean with the MBean server.

7.1.1 Name MBean Domains Just Like Packages

The domain name is part of the object name of an MBean and serves as a namespace mechanism for MBeans. The JMX specification imposes a few limitations on how you can name the domain of an MBean. For instance, you can't use wildcard characters (? and *) or a comma, colon , or equals sign. You also cannot use the JMImplementation string as a domain name because it is reserved for the particular JMX implementation you're using.

Other than that, there are no further restrictions on naming the domain of your MBeans. But as I said, with this freedom comes a potential problem: object name collisions. If the domain name you choose for your MBean is the same as an object name that is already registered, the MBean server will not allow you to register your MBean!

It's necessary, therefore, to take great care when choosing a naming idiom because you want to ensure that your MBeans can coexist with MBeans named by other developers from your team, company, and even the industry. As a developer, I understand the tendency to create new idioms to solve naming problems. For example, I could use my application's name as the domain name for all of my MBeans. However, this could lead to problems when integrating with other applications. Imagine if you have a great deal of investment in a particular domain naming idiom, only to find out that none of your MBeans can be registered as a result of collisions with MBeans from another vendor!

Java uses packages as its namespace mechanism, separating a parent package from its immediate child by a period ("dot"), its child by a dot, and so on. Because the domain name serves as a namespace mechanism for MBeans, it seems reasonable, then, to use the same idiom. The generally accepted idiom for naming packages is:

 org-type.org-name.application-name[.subsystem-name] 

Use this same idiom for naming domains. Here are a few examples:

 org.apache.xerces com.alltel.framework.logging com.acme.accounting.payable 

Of course, there is no guarantee that all developers will follow this idiom, but naming domains like packages significantly reduces the likelihood of object name collisions.

7.1.2 Use the Key Property List to Help Avoid Collisions

The domain name is only part of what makes up the object name of an MBean. The key property list, which makes up the rest, is an unordered set of key/value pairs. The specification imposes no explicit restrictions on how you can assign key properties, other than requiring that there be at least one key property, and that all are in the following format:

 property1=value1[,propertyN=valueN] 

The specification makes it clear that the key property list enables uniqueness among MBean names within a given domain (and within a given MBean server instance). It is logical, then, to establish some guidelines for naming key properties. For the purposes of this example, assume that we are talking about MBeans within the same domain. Here are some recommendations.

First, define a key property called name and use that property to establish uniqueness within a given domain. The value of this property should be the same as the Java class (unqualified) of the MBean. For example, suppose you have a payroll system with a queue resource for processing vendor payments called VendorQueue within the com.acme.accounting.payable domain. You could define a key property called name that would take the form:

 name=VendorQueue 

The resulting object name would be:

 com.acme.accounting.payable:name=VendorQueue 

If you want to register multiple instances of the same MBean class in the same domain, define a key property called instanceId that contains a unique identifier that is determined at runtime.

One approach is to use the string representation of the MBean instance's hash code as the value of the key property:

 VendorQueue v = new VendorQueue(  ); String domain = "com.acme.accounting.payable"; String keyPropertyList = "name=VendorQueue,instanceId=" +     Integer.toString(v.hashCode(  )); 

However, this approach won't work if you don't have access to the MBean object reference. Here are some other approaches to take:

• Use the system time just prior to registering the MBean (via a call to System.currentTimeMillis( ) ) as the instanceId . Even for two MBeans whose creation/registration are relatively close within a given code path , it is unlikely that the second call to System.currentTimeMillis( ) will yield the same value due to the amount of processing required by the MBean server to act as an MBean registry.

• Use a sequence number obtained from a facility you provide as instanceId . This facility could be as simple as a singleton object that provides access to an int value that is increased each time an access method is called.

• If you know at development time the number of MBeans of a particular class that will be registered, and if they are all registered by the same agent, an agent-dependent sequence number can be applied when each MBean is registered.

The approach you choose for distinguishing between instances of the same MBean class depends on your application needs. The point is that no two MBeans registered within the same MBean server can have the same combination of domain name and key property list.

I l @ ve RuBoard