JMX Accelerated Howto

This document is available in several formats.

You may be reading this document right now at http://admc.com/blaine/howtos/jmx, or in a distribution somewhere else. I hereby call the document distribution from which you are reading this, your current distro.

http://admc.com/blaine/howtos/jmx hosts the latest versions of all available formats. If you want a different format of the same version of the document you are reading now, then you should try your current distro. If you want the latest version, you should try http://admc.com/blaine/howtos/jmx.

Sometimes, distributions other than http://admc.com/blaine/howtos/jmx do not host all available formats. So, if you can't access the format that you want in your current distro, you have no choice but to use the newest version at http://admc.com/blaine/howtos/jmx.

This is an accelerated Howto for experienced Java programmers to really master, both theoretically and practically, the essential features of JMX, a.k.a. Java Management Extensions. You should already understand Java reflection, and how traditional Java Beans work. If you have dabbled with some facets of JMX, but want a more comprehensive understanding of it, this is for you too.

My goal is to get right to what you want to know and skip all the stuff that would be needed to accommodate a wider audience. I provide you with command-line and graphical Adaptors, and refer you to my publicly accessible JMX Manager where you can work with the objects discussed here.

Buy some used books from my book store, http://librimagni.com .

The primary goal of JMX is to provide easy and flexible availability to a repository of Java objects. The registered objects are Managed MBeans. One class could register a Managed Bean today. Tomorrow, some unrelated Java object could invoke methods of that Managed Bean instance.

Each MBean object needs a unique identifier in the MBeanSever, of course. That identifier is called the MBean Name, and consists of the JMX Domain and key/value pairs. The whole thing is formatted like DomainName:key1=val1,key2=val2. The Java class javax.management.ObjectName represents an MBean Name (as well as a wild-card for MBean Names). The entire combination of the domain plus all keys and values must be unique. (That is equivalent to saying that the entire MBean Name must be unique).

Once you implement an MBean by any of the methods in the Instrumentation chapter of this doc, then you can use a JMX Client to work with them as MBeans (I'm only describing how to use them as MBeans. There is nothing to prevent you from accessing the classes directly instead of through JMX-- but this Howto is about JMX). A JMX Client can instantiate, interrogate, register, retrieve and invoke methods on MBeans. If a JMX Client program has an interface for non-JMX clients, then you can use a non JMX program, like a web browser or the command line, to work with MBeans via the JMX Client (JMX Clients that perform this function are called Adaptors. The first thing we do in the Instrumentation chapter is start up an Adaptor). There are additional, non-essential features useful in specific problem domains. I list these in the JMX Features chapter.

When you implement any kind of MBean, you (usually) have to tell the JMX system which methods to expose-- because you don't generally want to expose all of them. (The exception to this is with constructors, as I explain next). I call this publishing. If you publish method X.y() , then method X.y() will be available to JMX Clients who get access to MBeans for the class X. JMX divides published methods are divided into three groups.

According to the JMX Spec, and common sense, you pretty much never want to change the JMX Interface of MBeans dynamically. JMX always sets up the original interface of an MBean class dynamically (even though with Standard MBeans this is hidden from you). To dynamically change the exposed MBean Interface, you would need to make very complex registration, tracking and notification strategies so that the JVM knows which version of the published methods to use for which MBean instances. A true nighmare. In practice, the coding needed just for one-time dynamic MBean interface setup is extremely complex, and you are hereby advised to try to avoid doing that work (some strategies are recommended below). The main point is, it does not makes sense to modify an MBean's published interface dynamically.

The main division of MBeans is between Standard and Dynamic. Both Standard and Dynamic MBeans dynamically publish their JMX interfaces. With Dynamic MBeans, you code the methods to publish your methods. With Standard MBeans, the JMX libraries use reflection on your class to publish the methods for you. Dynamic MBeans provide for runtime modification of the JMX interface-- just what Sun recommends against.

For the class to expose, you use a naming convention for the methods to expose, then put the signature of those methods into a new interface (the MBean Interface) which follows a naming convention. (I.e., the MBean Interface interface name is not MBean, but follows a naming convention). JMX uses reflection to publish the exposed methods at the right time. This is all done very similarly to how traditional Java Beans work.

Unfortunately, Sun decided to not support publishing descriptions for Standard MBeans and their exposed methods.

Dynamic MBeans can publish a description for each exposed method. IMO, this is the best feature that there is to JMX. Your end users can use a generic interface to browse existing MBeans which themselves tell the user how to use them.

I've had problems with is() method behavior with Sun's JMX implementation. They work as advertised with MS4J.

Jmx has lots of prohibitions and warnings against overloading. Anybody can code up a class where the base name alpha is used for a getter, setter, is, and multiple other methods, like

That's fine as long as you don't want to publish them with JMX. To publish with JMX, for each base name (alpha in this case), you are allowed only

Some of these rules are enforced and some are not. To minimize changes of obsolescence, follow all of these rules.

Read the Required Software chapter if you haven't already.

If you are just learning to create MBeans, then you will need an Agent server to test them with. Download admcjmx-adaptors.jar from http://admc.com/dist/admcjmx-adaptors.jar. This has my generic JMX Adaptors, including the command-line Adaptor that we're going to use now.

from a Bourne-compatible shell.

Enter the command "list" to see a list of the MBean names for all the registered MBeans. (I talk about MBean name queries in the JMX Client Implementation chapter. Since you haven't registered any MBeans yet, all of the MBeans listed are part of the Jmx Implementation itself or the Adaptor. Leave this Adaptor running and use another window to get another shell in the same directory. (We're going to code up some MBean classes in the other window, then use this window to load and inspect them).

Standard MBeans publish all of their public constructors automatically. You publish attribute and operation methods by putting them into your MBean Interface file. JMX Clients that look at your MBean class will see the same public constructors whether they use normal Java introspection or use JMX interrogation facilities for an existing MBean instance. JMX Clients can instantiate instances of your MBean using any of its public constructors. (The reasons behind these constructor idiosyncracies are explained in the Introduction to MBeans chapter).

Download TrivialStd.java or cut and paste this to a file named TrivialStd.java in the same directory.

public class TrivialStd implements TrivialStdMBean {
    public String speak() {
        return "Hello world";
    }
}

This is your target implementation class. Note that I coded no constructor so Java will create a no-arg public constructor for me by default. Like I said, JMX will automatically publish all public constructor, and this includes the default one.

Download TrivialStdMBean.java or cut and paste this to a file named TrivialStd.java in the same directory.

public interface TrivialStdMBean {
    public String speak();
}

This is your MBean Interface.

In your second terminal window, run

    javac Trivial*.java
            

Back in your JmxStreamAdaptor session, enter the following. (Don't type # or what follows on each line-- those are comments).

    instantiate TrivialStd dom:k=v  # Creates MBean of given class and name
    list dom:*                      # List MBean names with domain "dom"
    dump dom:k=v                    # Displays MBean of given name
    invoke dom:k=v speak              # Invokes given operation of given MBean
            

The descriptions that the Adaptor shows (for anything-- class, attributes, operations, constructors) are just dummy values. Standard MBeans do not support descriptions, so no JMX Client can obtain descriptions for them.

Here's what your output should look like.

Created MBeanServer with ID: 6cd7d5:fa884d34b0:-8000:onella.icfconsulting.com:1
Available commands (you can re-execute but not edit previous commands):
    classConstructors CLASS_NAME   (lists them)
    constructors MBEAN_NAME        (lists JMX published cons)
    dump MBEAN_NAME                (displays details of MBean)
    list [MBEAN_NAME_WILDCARD]     (lists MBean names)
    history                        (displays command history)
    invoke MBEAN_NAME OP [argType1, argType2...]
    instantiate CLASS_NAME MBEAN_NAME [argType1, argtype2...]
    attribute MBEAN_NAME ATT_NAME NEW_VALUE
    -                              (re-execute previous command)
    -X                             (re-execute Xth previous command)
    spool [/SPOOL/FILE.txt]        (no file turns off spooling)
EOD (like Ctrl-D/Z) to exit.

> instantiate TrivialStd dom:k=v
> list dom:*
{
    dom:k=v
}
> dump dom:k=v
DESCRIPTION: Manageable Bean

JMX-Declared CONSTRUCTORS:
Constructor exposed for management
    ()

ATTRIBUTES:
OPERATIONS:
java.lang.String: speak [Operation exposed for management]
    ()
> invoke dom:k=v speak
Hello world
> 
            

Now that you're not shaking in fear any more, make a subdirectory named "tst" and download this more substantial Standard MBean to that directory. tst/SampleStd.java and tst/SampleStdMBean.java. While more substantial than the previous MBean, it's still pretty simple. Do study the code and see how specific selected attributes and operations are published. Compile the classes into the tst subdirectory, then use your JmxStreamAdaptor to instantiate a few instances, invoke setters and operations, and dump the target MBean to see the results. You will definitley need a scrollbar on your window to see the dump. (You can also use the "spool" command to send output to a file).

Use the "classConstructors" and "constructors" commands of the Adaptor. Notice that you can only run "constructors" on an existing MBean instance whereas you can run classConstructors on any class, MBean or not, instantiated or not. Even though the constructor descriptions are dummy values, notice that you can only see the descriptions with the "constructors" command.

Notice that to instantiate an MBean, you only need to know the class name and arguments-- nothing JMX-specific. That solves the chicken-egg problem, but it means that you can't make use of any JMX publishing information (including descriptions, which will become useful once we move on to Dynamic MBeans) until after you instantiate an MBean.

Up to this point, we have used the command-line adaptor. I wanted to use the simplest adaptor possible in order to avoid a problem of Sun's JMX tutorial. When first being introduced to MBeans, we want to spend our time learning about JMX and MBeans, not learning how to operate a specific management tool. The command-line tool is perfect for working with little MBeans like TrivialStd.

However, at this point you should have a firm grasp on what MBeans are and what you can do with them. A graphical management tool makes it much easier to view MBeans with many constructors/attributes/operations, like SampleStdMBean. If you want to switch to a graphical tool, you can use my demo site at http://admc.com:8111/, or run your own instance. On my site you can instantiate and use any of the test.* classes discussed here. To start up your own instance, just run

    java com.admc.jmx.JmxHtmlAdaptor 1289
            

instead of

    java com.admc.jmx.JmxStreamAdaptor
            

This will run a http service on port 1289 of IPADDR_ANY. Run java com.admc.jmx.JmxHtmlAdaptor -h if you're interested in using other settings (like TLS). You then use a browser to go to http://localhost:1289/ (or whatever port you specified.

The home page consists of an entry field for narrowing down the MBean list (it defaults to listing all MBeans in the repository); a list of MBean names; and a button to display the public constructors for the MBean class name that you enter.

HTML-over-HTTP Adaptor's MBean Listing page.

If you click on an MBean Name, that MBean will be displayed for you. The adaptor can handle Strings and primitives, plus it can read (but not input) Collections of these types. If a constructor, operator or getter has an argument of a type outside of this, then you can only view that item. The constructors on the MBean dump page are the JMX-published constructors. If you use them, you will create an additional MBean instance with the MBean Name that you supply.

HTML-over-HTTP Adaptor's MBean Dump page.

If you Display Constructors from the main page, you will be able to create new MBeans. Since this function just uses Java reflection, you can list the public constructors for any Java class in the classpath, but instantiation will fail if you try to construct a class that is not an MBean.

You can use Dynamic MBeans with any Adaptor the same way that you work with your Standard MBean. The only difference you will see is that the Adaptor will show meaningful description for Dynamic MBean classes and methods. (But see the next paragraph regarding constructor descriptions).

As explained in the Introduction to MBeans chapter, JMX Clients have access to all of the public constructors of your target MBean class. JMX Clients can use normal Java reflection to find all of the public constructors. However, if JMX Clients use JMX facilities to look at your constructors, they will only see the ones that you tell JMX about (to do this manually, you define entries in the MBeanInfo structure returned by one of your methods-- but hopefully you won't do it manually). This can only be done by the JMX Client if it already has an instance of your MBean. To make sure that all JMX Clients get a consistent view of your MBean, you should tell JMX about all of your public constructors. (This wasn't a consideration for Standard MBeans since they auto-publish their constructors). In addition, JMX Clients can only see descriptions of constructors if they interrogate the constructors using an existing MBean instance and if you have told JMX about this constructor, as described above.

To create a Dynamic MBean, you start with the target class that you want to expose, and implement the DynamicMBean interface according to the API (for javax.management.DynamicMBean). This is neither easy nor enjoyable.

The Dynamic MBean design is bad, unnecessarily complex, and inherently difficult to maintain. You have to implement a bunch of methods which all return static information (unless you want to sabotage your application by changing the MBean interface at runtime). You have to assemble complex, nested structures containing redundant information.

If you have Sun's RI, then study Sun's example at JMX_HOME /examples/DynamicMBean/SimpleDynamic.java. To appreciate the extraordinary complexity and mess, search through there for "state" (do a case insensitive search). SimpleDynamic has a simple MBean Attribute (= getter/setter) for "state". Of course you must implement the get and set methods, but take a look at how much additional coding you need to write and maintain to expose these methods as an MBean Attribute.

If you are going to be coding Dynamic, Open or Model MBeans manually, you need to learn how to use the following classes (as well as many member classes used within these).

You have to assemble a MBeanInfo object for Model MBeans, just like for Dynamic MBeans, but there are some major differences. You don't touch the target (non-JMX) class to be exposed. You make a new JMX Client class (or use an existing one) to instantiate a ModelMBean (normally as implemented by RequiredModelMBean) which you use to expose any methods available to you (in this or other classes).

    mBeanInfo = ...
    RequiredModelMBean mb = new RequiredModelMBean(mBeanInfo);
    mb.setManagedResource(targetObject, "targetReferenceString");

See JMX_HOME examples/ModelMBean/ModelAgent.java for an example.

Just follow the commented example of tst/SampleADM.java.

If, for any reason at all, you want to expose methods of an existing class, but don't want to modify that class itself, make an MBean wrapper for it. Maybe you want to isolate the JMX portions, or maybe you don't have the source code for the target class, or maybe you want to expose a Java "interface" instead of a real Java "class".

If you don't need description capabilities, then you can make a Standard MBean which is a subclass of the original class. (When I say target class, I mean the original class that you want to expose). Say Oclass is the target class, then you could make Mclass, a subclass of Oclass, for your Standard MBean class. Mclass would have the MBean interface MclassMBean.

For a DynamicMBean wrapper, I highly recommend that you use AbstractDynamicMBean instead of doing it manually. Just follow the commented example of tst/SampleWrapper.java.

Notice that you have to code your MBean constructors. Pay attention to the comments.

It isn't that difficult to take an existing (or new) class that is a subclass of something else and make it into a DynamicMBean without losing the convenience of AbstractDynamicMBean.

Your modify your target class to implement the DynamicMBean interface, but the DynamicMBean methods will just delegate to calls to a nested AbstractDynamicMBean object that you will code.

The first part, implementing DynamicMBean, is trivial if you name your nested AbstractDynamicMBean object "delegate". Just modify your class declarationline to "implement AbstractDynamicMBean", and copy this boilerplate into your class: ADMDelegation.txt.

Then you need to code up your AbstractDynamicMBean delegate object and take care a few other details. Study the example closely. tst/DelegatedADM.java.