JBoss.orgCommunity Documentation

JMX Tools Reference Guide

Version: 1.0.0.GA

Copyright © 2007, 2009 JBoss, a division of Red Hat

December 2008

PDF version

1. Introduction
1.1. Requirements
1.2. History
1.3. Installation
1.4. Quick Start
2. MBean Explorer
3. MBean Editor
3.1. Notifications Page
4. Connections
4.1. The Default Connection
5. How to ...
5.1. How to Manage Tomcat
5.2. How to manage Eclipse Equinox
5.3. Managing JBoss Instances
6. Extension API
6.1. Why??
6.2. Core Extensions
6.3. UI Extensions

Chapter 1. Introduction

1.1. Requirements
1.2. History
1.3. Installation
1.4. Quick Start

JMX Tools allows to setup multiple JMX connections and provides view for exploring the JMX tree and execute operations directly from Eclipse.

This chapter covers the basics of working with JMX plugin, which is used to manage Java applications through JMX and its RMI Connector.

JMX Tools

Figure 1.1. JMX Tools


Requirements to use JMX Tools are the following:

JBoss Tools' JMX project is a fork of eclipse-jmx, a project by Jeff Mesnil. It was forked with permission.

Here, we are going to explain how to install the JMX plugin into Eclipse.

JMX Tools is one module of the JBoss Tools project. JMX Tools has no dependency on any other part of JBoss Tools, and can be downloaded standalone. Even though the JMX Tools have no dependencies, other plugins, such as AS Tools, do depend on the JMX Tooling and even extend it.

You can find the JBoss Tools plugins over at the download pages. The only package you'll need to get is the JMX Tooling, however the AS Tools would give you a more full experience when using JMX with JBoss Servers. You can find further download and installation instructions on the JBoss Wiki in the InstallingJBossTools section.

To start using the JMX Tools, it's necessary to open MBean Explorer. Go to Window > Show View > Other and then select MBean Explorer and click OK.

The MBean Explorer lists all of the domains, mbeans, attributes, and operations inside a connection. When you double-click on a MBean in the MBean Explorer, it opens a multi-page editor to manage the MBean. The MBean Editor is composed of these pages:

Chapter 2. MBean Explorer

The MBean Explorer displays the MBean features (both attributes and operations) in its hierarchy. Double-clicking on a feature will open a MBean Editor, display the page corresponding to the feature type and select the feature.

MBean Explorer Features

Figure 2.1. MBean Explorer Features


Since it's possible to have many MBean Editors opened at the same time, the MBean Explorer has the Link With Editor button to synchronize selections between the active MBean Editor and the MBean Explorer (and vice versa).

The MBean Explorer has also a filter text that can be used to filter among all the MBeans the few ones, which interest you.

For example, if you are only interested by MBeans related to memory, typing memo will show any node (domain, mbean, attribute, or operation) that matches that text, as well as that node's parents and children. So if an MBean matches, all attributes and operations from that bean will show. If, however, an attribute or operation name (a leaf node) matches, only that node and its parents in the tree will show.

Query Filter

Figure 2.2. Query Filter


The Collapse All button on the MBean Explorer toolbar is used to collapse all the MBeans and display only the domains. It is also possible to double click on a node to expand/collapse it.

Chapter 3. MBean Editor

updated
3.1. Notifications Page
MBean Editor Pages

Figure 3.1. MBean Editor Pages


The MBean Editor is composed of several pages:

  • the Attributes page

  • the Operations page

  • the Notifications page

  • the Info page

The Attributes and Operations pages display a list for either the MBean attributes or operations as well as details for the selection.

It is possible to toggle the layout between the list and the details either vertically (by default) or horizontally with the help of the special icons in the right top corner of the editor.

MBean Editor Horizontal Layout

Figure 3.2. MBean Editor Horizontal Layout


One more page in the MBean Editor is the Notifications page, which gives the possibility to subscribe (resp. unsubscribe) to a MBean to receive its notifications by checking (resp. unchecking) the Subscribe button in the right top corner.

The list of notifications is refreshed every time a new notification is received:

MBean Editor Notifications Page

Figure 3.3. MBean Editor Notifications Page


Note

It is only possible to subscribe to MBean, which emits notifications (they must be NotificationBroadcaster).

Chapter 4. Connections

4.1. The Default Connection

The MBean Explorer supports several different types of connections. The tooling itself comes only with a default connection type, however other adopters can provide additional connection types that may require additional or non-spec behavior. Connections can be in either the connected state or the disconnected state. Some connection types (such as the default connection type) allow you to control the current state. Other connection types may not.

Similarly, some connection types may be able to be created, and others may not. The default connection type, for example, can be created and deleted by you at will. The AS Tools connection type, which represents a JBoss server, does not allow you this level of control. A JBoss JMX connection is created when a JBoss server is created in the server's view, and deleted when said server is deleted. The JMX connection for this server is in the connected state only when the server is started.

There are two ways to connect to an application with remote management enabled:

The first step is the same for both - to connect to a MBean Server, click on the New Connection icon in the MBean Explorer menu bar.

Then to follow the simple one you just need to specify host, port (and optionally user name and password) and click OK.

The default JMX URL is service:jmx:rmi:///jndi/rmi://localhost:3000/jmxrmi.

In case you need to connect to an application which has not used the "standard" JMX URL (e.g. Eclipse Equinox), you need chose more advance way, where it's necessary to specify explicitly a JMX URL in the Advanced tab of the JMX Connection window.

Note

Only JMX URL based on RMI are supported.

Chapter 5. How to ...

5.1. How to Manage Tomcat
5.2. How to manage Eclipse Equinox
5.3. Managing JBoss Instances

This chapter will give you answers on most popular questions asked by JMX plugin users.

It's possible to manage Tomcat using JMX Tools.

Currently, JMX Tooling is able to connect to Tomcat without authentication or with password-based authentication.

Using SSL for authentication is not supported: you need to make sure that the System property com.sun.management.jmxremote.ssl is set to false.

More information to manage Tomcat can be found in Tomcat management documentation.

Instructions to manage remotely Tomcat are available in Tomcat's monitoring documentation.

You can manage Equinox through the Equinox monitoring framework.

Once you have installed the Equinox monitoring framework and restarted Eclipse:

You now have access to the MBeans exposed by Equinox.

Managing JBoss instances is not supported with the JMX Tools alone. You must also download and install the AS Tools portion of the JBoss Tools distribution. Even after installing the proper tooling, you cannot create a JBoss JMX connection yourself or through the Connection Wizard. The first step is to create a JBoss Server. The full instructions for this can be found in the AS Tools section, however, the short summary is:

Now you can explore MBeans exposed by a JBoss instance.

Chapter 6. Extension API

6.1. Why??
6.2. Core Extensions
6.3. UI Extensions

This chapter will outline how to contribute your own Server type with some default behavior.

You might be asking yourself why you'd need to extend this framework if JMX is a standard. Perhaps you want a connection to be automatically created after some specific action, or perhaps you want your connection wizard to do more than simply set a host and port. JBoss, for example, requires setting some credentials on the client machine, but using JBoss classes to do it. This requires that the connection have access to JBoss jars.

To create your own JMX Connection type, you must use the org.jboss.tools.jmx.core.MBeanServerConnectionProvider extension point. This point takes one child, a connectionProvider with a class that implements org.jboss.tools.jmx.core.IConnectionProvider.

An IConnectionProvider is responsible for creation and deletion of IConnectionWrapper objects. It must also keep a list of listeners that it is expected to inform when a connection is added or removed from its list.

Each IConnectionWrapper is expected to handle running arbitrary JMX runnables or getting a "Root" object representing all JMX nodes. There are some utility methods the IConnectionWrapper can make use of.

There are two extension points currently approved for use in the UI