Sun GlassFish Enterprise Server v2.1.1 Developer's Guide

Chapter 20 Using the Application Server Management Extensions

Sun GlassFish Enterprise Server uses Enterprise Server Management eXtensions (AMX) for management and monitoring purposes. AMX technology exposes managed resources for remote management as the JavaTM Management eXtensions (JMXTM) API.

The Enterprise Server incorporates the JMX 1.2 Reference Implementation, which was developed by the Java Community Process as Java Specification Request (JSR) 3, and the JMX Remote API 1.0 Reference Implementation , which is JSR 160.

This chapter assumes some familiarity with the JMX technology, but the AMX interfaces can be used for the most part without understanding JMX. For more information about JMX, see the JMX specifications and Reference Implementations.

For information about creating custom MBeans, see Chapter 14, Developing Custom MBeans.

This chapter contains the following topics:

About AMX

AMX is an API that exposes all of the Enterprise Server configuration, monitoring and JSR 77 MBeans as easy-to-use client-side dynamic proxies implementing the AMX interfaces. To understand the design and implementation of the AMX API, you can get started with this white paper.

Complete API documentation for AMX is provided in the Enterprise Server package.

The code samples in this section are taken from the package:

The Enterprise Server is based around the concept of administration domains. Each domain consists of one or more managed resources. A managed resource can be an Enterprise Server instance, a cluster of such instances, or a manageable entity within a server instance. A managed resource is of a particular type, and each resource type exposes a set of attributes and administrative operations that change the resource’s state.

Managed resources are exposed as JMX management beans, or MBeans. While the MBeans can be accessed using standard JMX APIs (for example, MBeanServerConnection), most users find the use of the AMX client-side dynamic proxies much more convenient.

Virtually all components of the Enterprise Server are visible for monitoring and management through AMX. You can use third-party tools to perform all common administrative tasks programmatically, based on the JMX and JMX Remote API standards.

The AMX API consists of a set of interfaces. The interfaces are implemented by client-side dynamic proxies, each of which is associated with a server-side MBean in the Domain Administration Server (DAS). AMX provides routines to obtain proxies for MBeans, starting with the DomainRoot interface (see

Note –

The term AMX interface in the context of this document should be understood as synonymous with a client-side dynamic proxy implementing that interface.

You can navigate generically through the MBean hierarchy using the interface (see When using AMX, the interfaces defined are implemented by client-side dynamic proxies, but they also implicitly define the MBeanInfo that is made available by the MBean or MBeans corresponding to it. Certain operations defined in the interface might have a different return type or a slightly different name when accessed through the MBean directly. This results from the fact that direct access to JMX requires the use of ObjectName, whereas the AMX interfaces use strongly typed proxies implementing the interface(s).

AMX MBeans

All AMX MBeans are represented as interfaces in a subpackage of (see and are implemented by dynamic proxies on the client-side. Note that client-side means any client, wherever it resides. AMX may be used within the server itself such as in a custom MBean. While you can access AMX MBeans directly through standard JMX APIs, most users find the use of AMX interface (proxy) classes to be most convenient.

An AMX MBean belongs to an Enterprise Server domain. There is exactly one domain per DAS. Thus all MBeans accessible through the DAS belong to a single Enterprise Server administrative domain. All MBeans in an Enterprise Server administrative domain, and hence within the DAS, belong to the JMX domain amx. All AMX MBeans can be reached by navigating through the DomainRoot.

Note –

Any MBeans that do not have the JMX domain amx are not part of AMX, and are neither documented nor supported for use by clients.

AMX defines different types of MBean, namely, configuration MBeans, monitoring MBeans, utility MBeans and Java EE management JSR 77 MBeans. These MBeans are logically related in the following ways:

Configuration MBeans

Configuration information for a given Enterprise Server domain is stored in a central repository that is shared by all instances in that domain. The central repository can only be written to by the DAS. However, configuration information in the central repository is made available to administration clients through AMX MBeans.

The configuration MBeans are those that modify the underlying domain.xml or related files. Collectively, they form a model representing the configuration and deployment repository and the operations that can be performed on them.

The Group Attribute of configuration MBeans, obtained from getGroup(), has a value of

Monitoring MBeans

Monitoring MBeans provide transient monitoring information about all the vital components of the Enterprise Server.

The Group Attribute of monitoring MBeans, obtained from getGroup(), has a value of

Utility MBeans

Utility MBeans provide commonly used services to the Enterprise Server.

The Group Attribute of utility MBeans, obtained from getGroup(), has a value of

Java EE Management MBeans

The Java EE management MBeans implement, and in some cases extend, the management hierarchy as defined by JSR 77, which specifies the management model for the whole Java EE platform.

The AMX JSR 77 MBeans offer access to configuration and monitoring MBeans using the getMonitoringPeer() and getConfigPeer() methods.

The Group Attribute of Java EE management MBeans, obtained from getGroup(), has a value of

Other MBeans

MBeans that do not fit into one of the above four categories have the value One such example is (see

MBean Notifications

All AMX MBeans that emit Notifications place a java.util.Map within the UserData field of a standard JMX Notification, which can be obtained using Notification.getUserData(). Within the map are one or more items, which vary according to the Notification type. Each Notification type, and the data available within the Notification, is defined in the Javadoc of the MBean (AMX interface) that emits it.

Note that certain standard Notifications, such as (see do not and cannot follow this behavior.

Access to MBean Attributes

An AMX MBean Attribute is accessible in three ways:

All dotted names that are accessible through the command line interface are available as Attributes within a single MBean. This includes properties, which are provided as Attributes beginning with the prefix property., for example,

Note –

Certain attributes that ought to be of a specific type, such as int, are declared as java.lang.String. This is because the value of the attribute may be a template of a form such as ${HTTP_LISTENER_PORT}.

Dynamic Client Proxies

Dynamic Client Proxies are an important part of the AMX API, and enhance ease-of-use for the programmer.

JMX MBeans can be used directly by an MBeanServerConnection (see to the server. However, client proxies greatly simplify access to Attributes and operations on MBeans, offering get/set methods and type-safe invocation of operations. Compiling against the AMX interfaces means that compile-time checking is performed, as opposed to server-side runtime checking, when invoked generically through MBeanServerConnection.

See the API documentation for the package and its sub-packages for more information about using proxies. The API documentation explains the use of AMX with proxies. If you are using JMX directly (for example, by usingMBeanServerConnection), the return type, argument types, and method names might vary as needed for the difference between a strongly-typed proxy interface and generic MBeanServerConnection/ObjectName interface.

Connecting to the Domain Administration Server

As stated in Configuration MBeans, the AMX API allows client applications to connect to Enterprise Server instances using the DAS. All AMX connections are established to the DAS only: AMX does not support direct connections to individual server instances. This makes it simple to interact with all servers, clusters, and so on, with a single connection.

Sample code for connecting to the DAS is shown in Connecting to the DAS. The class (see is also available.

Examining AMX Code Samples

An overview of the AMX API and code samples that demonstrate various uses of the AMX API can be found at and

The sample implementation is based around the SampleMain class. The principal uses of AMX demonstrated by SampleMain are the following:

All of these actions are performed by commands that you give to SampleMain. Although these commands are executed by SampleMain, they are defined as methods of the class Samples, which is also found in the package.

The SampleMain Class

The SampleMain class creates a connection to a DAS, and creates an interactive loop in which you can run the various commands defined in Samples that demonstrate different uses of AMX.

Connecting to the DAS

The connection to the DAS is shown in the following code.

public static AppserverConnectionSource
        final String host,
        final int port,
        final String user,
        final String password,
        final TLSParams tlsParams )
        throws IOException
            final String info = "host=" + host + ", port=" + port +
                ", user=" + user + ", password=" + password +
                ", tls=" + (tlsParams != null);

            SampleUtil.println( "Connecting...:" + info );

            final AppserverConnectionSource conn    =
                new AppserverConnectionSource(
                    host, port, user, password, tlsParams, null);

            conn.getJMXConnector( false );

            SampleUtil.println( "Connected: " + info );

            return( conn );

A connection to the DAS is obtained using an instance of the class. For the connection to be established, you must know the name of the host and port number on which the DAS is running, and have the correct user name, password and TLS parameters.

After the connection to the DAS is established, DomainRoot is obtained as follows:

DomainRoot domainRoot = appserverConnectionSource.getDomainRoot();

This DomainRoot instance is a client-side dynamic proxy to the MBean amx:j2eeType=X-DomainRoot,name=amx.

See the API documentation for for further details about connecting to the DAS using the AppserverConnectionSource class.

However, if you prefer to work with standard JMX, instead of getting DomainRoot, you can get the MBeanServerConnection or JMXConnector, as shown:

MBeanServerConnection conn =
appserverConnectionSource.getMBeanServerConnection( false );
JMXConnector jmxConn =
appserverConnectionSource.getJMXConnector( false );

Starting an Enterprise Server

The Samples.startServer method demonstrates how to start an Enterprise Server.

In this sample AMX implementation, all the tasks are performed by the command start-server when you run SampleMain. See the startServer method to see how this command is implemented. Click the method name to see the source code.

Deploying an Archive

The Samples.uploadArchive() and deploy methods demonstrate how to upload and deploy a Java EE archive file.

Displaying the AMX MBean Hierarchy

The Samples.displayHierarchy method demonstrates how to display the AMX MBean hierarchy.

Setting Monitoring States

The Samples.setMonitoring method demonstrates how to set monitoring states.

Accessing AMX MBeans

The Samples.handleList method demonstrates how to access many (but not all) configuration elements.

Accessing and Displaying the Attributes of an AMX MBean

The Samples.displayAllAttributes method demonstrates how to access and display the attributes of an AMX MBean.

Listing AMX MBean Properties

The Samples.displayAllProperties method demonstrates how to list AMX MBean properties.

Performing Queries

The Samples.demoQuery method demonstrates how to perform queries.

The demoQuery() method uses other methods that are defined by Samples, namely displayWild(), and displayJ2EEType().

Monitoring Attribute Changes

The Samples.demoJMXMonitor method demonstrates how to monitor attribute changes.

Undeploying Modules

The Samples.undeploy method demonstrates how to undeploy a module.

Stopping an Enterprise Server

The Samples.stopServer method demonstrates how to stop an Enterprise Server. The stopServer method simply calls the Samples.getJ2EEServer method on a given server instance, and then calls J2EEServer.stop.

Running the AMX Samples

The following section lists the steps to run the AMX samples.

ProcedureTo Run the AMX Sample

  1. Ensure that the JAR file appserv-ext.jar has been added to your classpath. Some examples also require that j2ee.jar be present.

  2. Define a file, which provides the parameters required by AppserverConnectionSource to connect to the DAS.

    The file file should use the following format:

    Note –

    If you are running the Enterprise Server enterprise profile, TLS must be used (provided it has not been turned off). The useTLS property must therefore be set to useTLS=true. For information about profiles, see Usage Profiles in Sun GlassFish Enterprise Server v2.1.1 Administration Guide.

  3. Scripts are provided in the package to run the AMX samples.

    Start SampleMain by running the appropriate script for your platform:

    • on UNIX or Linux platforms

    • run-samples.bat on Microsoft Windows platforms

  4. After SampleMain is running, you can interact with it by typing the commands examined above:

    • Enter Command> start-server serverName

    • Enter Command> list-attributes

      You see output like this:

          --- Attributes for X-DomainRoot=amx ---
    • Enter Command> show-hierarchy

      You see output like this:

    • Enter Command> list

      You see output like this:

          --- Top-level ---
          ConfigConfig: [server2-config, default-config, server-config,
          ServerConfig: [server3, server, server2]
          StandaloneServerConfig: [server3, server, server2]
          ClusteredServerConfig: []
          ClusterConfig: []
    • Enter Command> list-properties

      You see output like this:

          Properties for:
    • Enter Command> query

      You see output like this:

          --- Queried for j2eeType=X-*ResourceConfig ---
    • And so on for the other commands:

      Enter Command> demo-jmx-monitor

      Enter Command> set-monitoring monitoringLevel (one of HIGH, LOW or OFF)

      Enter Command> stop-server serverName

      Enter Command> quit