Download and install the Sun Microsystems Java SDK from http://java.sun.com/j2se and install it according to the supplied instructions. Most of the examples are compiled and run from the command line, so make sure the installation process adds the required commands, located in the bin directory of the Java SDK installation, to your PATH environment variable. You can check that the PATH settings are correct by trying to execute the java command from the command prompt. If the java command is found correctly, you should see the following output on the console window:

C: Examples> java
Usage: java [-options] class [args...]
           (to execute a class)
   or  java -jar [-options] jarfile [args...]
           (to execute a jar file)

If the java command does not work, modify the PATH environment setting to point to the bin directory of the SDK installation. For example,

C: Examples> set PATH=%PATH%;C: Java1.3 bin

Modify the directory path in the previous example to match your Java SDK installation directory. To make the PATH environment setting permanent, go to the Windows Control Panel and modify the System settings.

Those of you wanting to use an Integrated Development Environment (IDE) to run the examples will have to adjust these instructions to your corresponding IDEs. Unix and Linux users should set up the environment settings as documented in their command shells.

Download the JMX Reference Implementation from http://java.sun.com/products/JavaManagement/index.html. Create a new empty directory for the examples in this book, for example C:Examples. Unpack the downloaded package into this directory. Notice that if you are using a tool such as WinZip to unpack the downloaded file, you should ensure that the Use Folder Names option has been checked. After you have unpacked the JMX Reference Implementation package, all the files should appear under the C:Examplesjmx-1 0 1-ri_bin directory.

When compiling and running the examples, you will need the libraries under the C:Examplesjmx-1 0 1-ri_binjmxlib directory—the jmxri.jar and jmxtools.jar files. The jmxri.jar file contains the JMX API classes, and the jmxtools.jar file contains JMX extensions, such as the HTTP Adaptor.

To configure the second JMX implementation used in this book, download the Tivoli JMX implementation from the IBM AlphaWorks Web site at http://www.alphaworks.ibm.com/tech/TMX4J. Again, unzip the package into the C:Examples directory. You should see all the files in the package appear in the C:Examples mx4j directory. The libraries required to compile and run the examples can be found under C:Examples mx4jaselib—the jmxx.jar, jmxc.jar and log.jar files. In addition, JMX extension libraries can be found under the C:Examples mx4jextlib directory.

All the source code in the book can be compiled and run from the directory that you created in the C:Examples directory. If specific classpath settings are required, they are mentioned in the text. Usually all classpath settings are passed to the runtime environment using a classpath switch or a similar mechanism.

All the source code is also packaged in a book.jmx.examples package. This requires you to specify the full package names when running the examples. When compiling the source code, use the -d switch to specify the target directory as the current work directory. This will create a directory structure under the work directory that matches the Java package declaration in the source files. When running the code with java command, this directory structure is expected by the runtime system.

To compile a Java source file, the following command line should be used:

C:Examples> javac –d . –classpath .;jmx-1_0_1-ri_binjmxlibjmxri
.jar;jmx-1_0_1-ri_binjmxlibjmxtools.jar <Java source file>

If the Java source file contains the package declaration book.jmx.examples, a corresponding directory structure is created under the work directory, as indicated by the -d switch.

To run the compiled classes, the full package name must be included. The code should be executed from the same working directory where it was compiled. For example, to run the previous example, the following command line should be executed:

C: Examples> java –classpath .;jmx-1_0_1-ri_bin/jmx/lib/ jmxri.jar;jmx-1_0_1-ri_bin/jmx
/lib/jmxtools.jar book.jmx.examples.MyClassName

The previous two example commands use the Sun JMX Reference Implementation. To switch to the IBM Tivoli JMX implementation, replace the jmxri.jar with the three Jar packages found under tmx4jaselib—jmxx.jar, jmxc.jar and log.jar. Replace the jmxtools.jar with jmxext.dir found in the C:Examples mx4jextlib directory.

C: Examples> javac -d . –classpath .;tmx4j/base/lib/jmxc.jar;tmx4j/base/lib/ jmxx
.jar;tmx4j/ext/lib/jmxext.jar <Java source file>
C: Examples> java –classpath .;tmx4j/base/lib/jmxc.jar;tmx4j/base/lib/ jmxx.jar;tmx4j
/base/lib/log.jar;tmx4j/ext/lib/jmxext.jar book.jmx.examples.Agent

In Part II, “JMX in the J2EE Platform,” you will look at some examples that use the J2EE services with JMX. The examples use the JBoss version 2.4.1 implementation, which is available as Open Source and for free from http://www.jboss.org.

To install JBoss, download the package and unpack it to the directory you have created. If you are following the directory setup shown previously, the directory will be C:Examples. After you have unpacked the JBoss distribution, you will have a directory C:ExamplesJBoss-2.4.1 in your file system. If you change the directory to C:ExamplesJBoss-2.4.1in, you will find the run.bat|sh files that you can execute to start the JBoss server.

In Chapter 10, “JMX Distribution Layer with J2EE Services,” you will build an asynchronous connector that can be used for remote communication between a management application and the MBean server. The message transport for this connector is implemented using Java Message Service (JMS). The JBoss server starts an implementation of JMS—the JBossMQ—automatically when you execute the server start scripts. However, a JMS topic needs to be added and configured for the JBossMQ server. Using the previous file structure, you can find the configuration file jboss.jcml from under the C:ExamplesJBoss-2.4.1confdefault directory. About half way through the configuration file, you can find the JBossMQ configuration shown next:

<!— ========================================================= —>
<!— JBossMQ                                                   —>
<!— ========================================================= —>
<mbean code = "org.jboss.mq.server.JBossMQService"
       name = "JBossMQ:service=Server"/>

<!— The StateManager is used for JMS persistent state data.   —>
<!— For example: what durable subscriptions are active.       —>
<mbean code = "org.jboss.mq.server.StateManager"
       name = "JBossMQ:service=StateManager">
    <attribute name="StateFile">jbossmq-state.xml</attribute>
</mbean>

<!— The PersistenceManager is used to store messages to disk. —>
<mbean code = "org.jboss.mq.pm.rollinglogged.PersistenceManager"
       name = "JBossMQ:service=PersistenceManager">
    <attribute name="DataDirectory">../../db/jbossmq/</attribute>
</mbean>

<!— InvocationLayers are the different transport methods that —>
<!— can be used to access the server.                         —>
<mbean code = "org.jboss.mq.il.jvm.JVMServerILService"
       name = "JBossMQ:service=InvocationLayer,type=JVM">
    <attribute name = "ConnectionFactoryJNDIRef">
        java:/ConnectionFactory
    </attribute>
    <attribute name = "XAConnectionFactoryJNDIRef">
        java:/XAConnectionFactory
    </attribute>
</mbean>

<mbean code = "org.jboss.mq.il.rmi.RMIServerILService"
       name = "JBossMQ:service=InvocationLayer,type=RMI">
    <attribute name = "ConnectionFactoryJNDIRef">
        RMIConnectionFactory
    </attribute>
    <attribute name = "XAConnectionFactoryJNDIRef">
        RMIXAConnectionFactory
    </attribute>
</mbean>

<mbean code = "org.jboss.mq.il.oil.OILServerILService"
       name = "JBossMQ:service=InvocationLayer,type=OIL">
    <attribute name = "ConnectionFactoryJNDIRef">
        ConnectionFactory
    </attribute>
    <attribute name = "XAConnectionFactoryJNDIRef">
        XAConnectionFactory
    </attribute>
</mbean>
<mbean code = "org.jboss.mq.il.uil.UILServerILService"
       name = "JBossMQ:service=InvocationLayer,type=UIL">
    <attribute name = "ConnectionFactoryJNDIRef">
        UILConnectionFactory
    </attribute>
    <attribute name = "XAConnectionFactoryJNDIRef">
        UILXAConnectionFactory
    </attribute>
</mbean>

<!— The following three line create 3 topics named: testTopic,—>
<!— example, and bob                                          —>
<mbean code = "org.jboss.mq.server.TopicManager"
       name = "JBossMQ:service=Topic,name=testTopic"/>
<mbean code = "org.jboss.mq.server.TopicManager"
       name = "JBossMQ:service=Topic,name=example"/>
<mbean code = "org.jboss.mq.server.TopicManager"
       name = "JBossMQ:service=Topic,name=bob"/>

To add a new topic to the JBossMQ server, insert the following lines at the end of the previous listing.

<!— The following three line create 3 topics named: testTopic,—>
<!— example, and bob                                          —>
<mbean code = "org.jboss.mq.server.TopicManager"
       name = "JBossMQ:service=Topic,name=testTopic"/>
<mbean code = "org.jboss.mq.server.TopicManager"
       name = "JBossMQ:service=Topic,name=example"/>
<mbean code = "org.jboss.mq.server.TopicManager"
       name = "JBossMQ:service=Topic,name=bob"/>
<mbean code = "org.jboss.mq.server.TopicManager"
       name = "JBossMQ:service=Topic,name=JMSConnector"/>

Adding the last two lines in jboss.jcml will create the JMSConnector topic at startup.

In Chapter 10, you will build a SOAP connector to invoke and manipulate MBeans from a remote host using the SOAP protocol. The SOAP connector implementation uses the GLUE library available from http://www.themindelectric.com. There is a free binary distribution available for GLUE from the Web site. A registration is required to download the standard edition of the library.

Unpack the 1.2 version of the Standard GLUE library in to the same directory to which you have unpacked the other files. If you are following the naming used in this chapter, the directory is C:Examples. After you have unpacked the GLUE package, you will see a C:Exampleselectricon library your file system and under that a directory a C:Exampleselectriclib directory that contains the Java archive file GLUE-STD.jar that you will use in the SOAP examples.

The examples in Part II of the book use XML on several occasions. All the examples use the JDOM library for the XML read and write operations. You can download the JDOM library from http://www.jdom.org. The examples have been compiled and run using the JDOM Beta 7 release.

Unpack the JDOM package into C:Examples directory. At the time of this writing, the Beta 7 release of JDOM library was the latest stable release. After unpacking, you will find the library under the C:Examplesjdom-b7uild directory. In addition, there are other required XML related libraries under the C:Examplesjdom-b7lib directory, namely the jaxp.jar and crimson.jar libraries.

The SNMP examples in Chapter 9, “Connectors and Protocol Adaptors,” require that both AdventNet JMX implementation and Sun JDMK implementation be installed.

You can download a free evaluation version of the AdventNet JMX implementation from http://www.adventnet.com. Install the software under the C:Examples directory.

Similarly, download the Sun JDMK from http://www.sun.com/software/java-dynamic/ and unpack it under the C:Examples directory.

After you have finished installing all this software, the directory structure of your setup should look similar to the Explorer view shown in Figure A.1.

Figure A.1. Microsoft Windows File Explorer view of the expected file structure for the examples in this book.