Developing a Remote Java Management Extensions (JMX) Manager and Connecting
It to a JMX Agent
Jean-Francois Denise (
),
JMX team
Expected duration: 30 minutes
The NetBeans JMX Module integrates JMX technology right into your workflow
in the NetBeans IDE. This module allows you to quickly develop management applications,
add management to exisiting applications, develop manager applications, and
monitor the state of the Virtual Machine. The module is available for NetBeans
IDE version 4.0 and higher. You can install the module by choosing Tools >
Update Center and downloading the module from the NetBeans Update Center.
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.
Prerequisites
This tutorial assumes you have some basic knowledge of, or programming experience
with, the following technologies.
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
Choose File > New Project (Ctrl-Shift-N).
Select the Anagram Game Managed with JMX project type from the Samples >
Management category.
Click Next. The Project Name and Location page is displayed.
Type JMXAnagramGame as the project name.
Click Finish. A new JMXAnagramGame project is created.
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.
Choose Run > Remote Management > Run Main Project with Remote Management.
A dialog box is displayed that lets you configure remote management. You
can provide a port on which the agent waits for incoming JMX requests. In
this tutorial, we will keep the default port (1099). If you provide another
port number, be sure to make the appropriate changes in every part of this
tutorial. 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.)
Deselect the Connect JConsole checkbox.
Click OK. The anagram game is compiled then started. The host and
port on which the agent is listening is displayed in the output console (currently
localhost:1099).
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).
Select the Java Application project type from the General category.
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 port, a host, and a 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
Uncomment the MBean discovery code located in the main method
Choose Run > Run Main Project to run the manager. The manager connects
to the remote agent, displays the discovered MBean names in the Output window
and then closes 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.
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.
ObjectName name = new ObjectName("anagrams.toy.com:type=AnagramsStats");
Get the attribute NumResolvedAttribute.
Integer num = (Integer) connection.getAttribute(name, "NumResolvedAnagrams");
