Developing a Java Management Extensions (JMX) Manager and Connecting to a Remote JMX Agent
Last Updated: January 2008
By
and
,
JMX Engineering Team.
Expected duration: 30 minutes
The NetBeans JMX Wizard Module integrates JMX technology right into your workflow
in the NetBeans IDE. This module allows you to quickly develop management applications,
add management to existing applications, develop manager applications, and
monitor the state of the Virtual Machine.
This tutorial has been updated for the JMX Wizard module version 3.0, available for NetBeans
IDE version 6.0 and higher.
This tutorial requires the JDK 5 or higher version of the Java Platform.
The steps detailed below have been performed with JDK 6.
This tutorial shows you how to perform the following actions:
Start a JMX agent in order to make it accessible from a remote JMX manager.
Create a JMX manager.
Run the manager.
Update the manager to add your own management logic.
To install the JMX plugin, choose Tools > Plugins and download the module from the NetBeans Update Center.
IMPORTANT NOTE: If you are using NetBeans 6.1 or higher, you also need to download and install the JConsole module.
This tutorial requires the JDK 5 or higher version of the Java Platform.
The steps detailed below have been performed with JDK 6.
Resources
Netbeans help contents (Help > Help Contents > JMX). This help is
also available from the Wizards.
Exercise 1: Creating the Management Sample Anagram Project
The goal of this exercise is to create a JMX agent to which the manager application
can connect. The JMX module comes with a JMX agent sample Java project. Instead
of writing a JMX agent from scratch, we will simply create this sample project.
Steps to follow
The JMX module includes a sample application with JMX monitoring built into it.
Choose File > New Project.
In Samples, select the JMX category.
Select the Anagram Game Managed with JMX project.
Click Next, no need to change the already filled in default project name and
location values, keep the Set as Main Project checkbox checked and click
Finish
The goal of this exercise is to start a Java application with the JMX remote
management enabled. Remote management allows client applications (JMX
managers) to connect to the application (JMX agent) and visualize the
management and monitoring information.
Note: Any running application based on JDK 1.5 is a JMX agent for which you
can enable remote management.
Steps to Follow
Be sure to have the JMXAnagramGame project selected and to have set it as
your main project.
Right-click on the JMXAnagramGame project and select Properties.
In the left part of the dialog box which is displayed,
select "Monitoring and Management".
Uncheck the "Attach JConsole to Project" box and
check the "Enable RMI Remote Access" box.
You can provide a port on which the agent waits for incoming JMX requests. In
this tutorial, we just keep the default port (1099). If you provided another
port number, you would have to make the appropriate changes in every part of this
tutorial. Also, in this tutorial, we do not specify a properties file. (For your
own applications, we provide a wizard to help you create a management properties
file.)
Click OK.
Now, run the anagram game by clicking on the
"Run Main Project with Monitoring and Management" button in the toolbar.
It's the button with an icon like this:
This will launch the Angram game, with the JVM listening for RMI access on
local host port 1099. The Anagram Game window will pop up:
You can reduce the Anagrams window, but keep it running. Your JMX agent
is running, waiting for the manger to send management requests.
In this exercise, we will create a Java Application project named JMXAnagramManager.
Steps to Follow
Choose File > New Project (Ctrl-Shift-N).
Choose the project type by selecting category "Java"
and project "Java Application".
Click Next.
Name the new project JMXAnagramManager. Set it as your main project.
Deselect the Create Main Class checkbox. In the next exercise, the JMX Manager
wizard will be used to generate the main runnable class.
Click Finish. The new project is added to the Projects tree. Notice that a
JMX manager project is just like any other Java Application project.
In this exercise, you will learn how to use the JMX Manager wizard to generate
a runnable manager class.
Steps to Follow
Be sure to have selected the JMXAnagramManager project and to have it set
as your main project.
Choose File > New File (Ctrl-N). Then select the JMX Manager template
from the Management category.
Click Next.
Type AnagramsManager as the Class Name. Enter com.toys.anagrams.manager
as the package name. Leave the checkboxes as they are. The wizard will generate
a main method and some MBean discovery code. It will also set this class as
the project's runnable class.
Click Next to select the JMX Agent URL to which to connect.
Click the Edit button to enter the JMX agent URL to which you want to connect.
A dialog box is displayed to help you enter a valid JMX URL. A JMX URL is
composed of a Protocol, a Host, a Port and an URL path.
In the protocol drop-down list, a single element is provided. The list
is writable and you can enter your own protocol. The default protocol RMI
JVM Agent is the RMI protocol used to connect to a JDK JMX agent. The Agent
we previously started is of this nature. Accept the protocol default selection.
The Agent is listening on localhost:1099 so keep the host and port default
values as they are. The URL path is read-only. It is automaticaly updated
with the host and port values. This is the way the URL path is constructed
for a RMI JVM Agent.
Click OK. The JMX Agent URL textfield is updated with the full URL you entered.
The connection to the Agent is not authenticated because we did not provide
any authentication configuration when the agent was launched. Accept the default
selection. Some sample code to enable an authenticated connection will be
generated.
Click Finish. The manager class is opened in the Source Editor.
In this exercise, you will learn how to run the manager and discover the MBeans.
Steps to Follow
In the AnagramsManager.java file,
uncomment the MBean discovery code located in the main method,
so that it should read:
public static void main(String[] args) throws Exception {
//Manager instantiation and connection to the remote agent
AnagramsManager manager = AnagramsManager.getDefault();
// SAMPLE MBEAN NAME DISCOVERY. Uncomment following code:
Set resultSet =
manager.getMBeanServerConnection().queryNames(null, null);
for(Iterator i = resultSet.iterator(); i.hasNext();) {
System.out.println("MBean name: " + i.next());
}
// Close connection
manager.close();
System.out.println("Connection closed.");
}
You may also need to add import clauses for the java.util.Set
and java.util.Iterator classes.
Choose Run > Run Main Project to run the manager which will connect
to the remote agent, display the discovered MBean names in the Output window
and then close the connection:
The project is compiled and the manager is started. The discovered ObejctNames
are displayed in the Output window. You can notice the AnagramsStats
MBean name as well as the Java VM MBeans. All Java VM standard MBeans are
located under the java.lang JMX domain.
Here is what you should see in the NetBeans Output Window of the
JMXAnagramManager run:
In this exercise you will learn how to make a simple JMX request to access
an MBean attribute. We will update the manager class main method in order to
access the NumResolvedAnagrams attribute. This attribute represents
the number of anagrams solved.
Steps to Follow
In the main method, before closing the connection we are going to perform
the following actions:
Access the MBeanServerConnection. The MBeanServerConnection
class allows you to make requests to the remote server.
Create the Anagrams statistics MBean ObjectName. The name is
copied/pasted from the output. An object name is needed when a request
is sent to a remote agent in order to specify the MBean from which to
get the atribute.
Get the attribute NumResolvedAttribute.
Print the attribute value to the output.
To do so, copy and paste the four lines of code below at the end of the
AnagramsManager.java main method, right before the close conection lines:
MBeanServerConnection connection = manager.getMBeanServerConnection();
ObjectName name = new ObjectName("com.toy.anagrams.mbeans:type=AnagramsStats");
Integer num = (Integer) connection.getAttribute(name, "NumSolvedAnagrams");
System.out.println("NumSolvedAnagrams : " + num);
You may need to add an import clause for javax.management.ObjectName
Once you have updated the source code, you can play with the Anagrams game
then run the project again in order to see the updated values.
In the NetBeans Output Window of the JMXAnagramManager run you should now see
at the end, before the connection closed, the added line:
NumSolvedAnagrams : 0
Yes, you are done! Great job!
We hope that this tutorial helped you understand how to develop manager applications
in order to access information exported thanks to JMX.
