test

Sun Java System Application Server 9.1 Developer's Guide

Chapter 20 Using the Application Server Management Extensions

Sun Java System Application Server uses Application 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 Application 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 Application 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 Application Server package.

com.sun.appserv.management

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

com.sun.appserv.management.sample

The Application Server is based around the concept of administration domains. Each domain consists of one or more managed resources. A managed resource can be an Application 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 Application 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 http://glassfish.dev.java.net/nonav/javaee5/amx/javadoc/com/sun/appserv/management/DomainRoot.html).

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 com.sun.appserv.management.base.Container interface (see http://glassfish.dev.java.net/nonav/javaee5/amx/javadoc/com/sun/appserv/management/base/Container.html). 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 com.sun.appserv.management (see http://glassfish.dev.java.net/nonav/javaee5/amx/javadoc/com/sun/appserv/management/package-summary.html) 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 Application Server domain. There is exactly one domain per DAS. Thus all MBeans accessible through the DAS belong to a single Application Server administrative domain. All MBeans in an Application 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 Application 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 com.sun.appserv.management.base.AMX.GROUP_CONFIGURATION.

Monitoring MBeans

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

The Group Attribute of monitoring MBeans, obtained from getGroup(), has a value of com.sun.appserv.management.base.AMX.GROUP_MONITORING.

Utility MBeans

Utility MBeans provide commonly used services to the Application Server.

The Group Attribute of utility MBeans, obtained from getGroup(), has a value of com.sun.appserv.management.base.AMX.GROUP_UTILITY.

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 com.sun.appserv.management.base.AMX.GROUP_JSR77.

Other MBeans

MBeans that do not fit into one of the above four categories have the value com.sun.appserv.management.base.AMX.GROUP_OTHER. One such example is com.sun.appserv.management.deploy.DeploymentMgr (see http://glassfish.dev.java.net/nonav/javaee5/amx/javadoc/com/sun/appserv/management/deploy/DeploymentMgr.html).

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 javax.management.AttributeChangeNotification (see http://java.sun.com/j2se/1.5.0/docs/api/javax/management/AttributeChangeNotification.html) 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, server.property.myproperty.

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 http://java.sun.com/j2se/1.5.0/docs/api/javax/management/MBeanServerConnection.html) 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 com.sun.appserv.management 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 Application 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 com.sun.appserv.management.helper.Connect class (see http://glassfish.dev.java.net/nonav/javaee5/amx/javadoc/com/sun/appserv/management/helper/Connect.html) 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 http://glassfish.dev.java.net/nonav/javaee5/amx/samples/javadoc/index.html and http://glassfish.dev.java.net/nonav/javaee5/amx/samples/javadoc/amxsamples/Samples.html.

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 com.sun.appserv.management.sample 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
    connect(
        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(
                    AppserverConnectionSource.PROTOCOL_RMI,
                    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 com.sun.appserv.management.client.AppserverConnectionSource 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 com.sun.appserv.management.client.AppserverConnectionSource 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 Application Server

The Samples.startServer method demonstrates how to start an Application 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 Application Server

The Samples.stopServer method demonstrates how to stop an Application 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 SampleMain.properties file, which provides the parameters required by AppserverConnectionSource to connect to the DAS.

    The file SampleMain.properties file should use the following format:

    connect.host=localhost
connect.port=8686
connect.user=admin
connect.password=admin123
connect.truststore=sample-truststore
connect.truststorePassword=changeme
connect.useTLS=true
    Note –

    If you are running the Application 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 Java System Application Server 9.1 Administration Guide.

  3. Scripts are provided in the com.sun.appserv.management.sample package to run the AMX samples.

    Start SampleMain by running the appropriate script for your platform:

    • run-samples.sh 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 ---
    AttributeNames=[...]
    BulkAccessObjectName=amx:j2eeType=X-BulkAccess,name=na
    DomainConfigObjectName=amx:j2eeType=X-DomainConfig,name=na
    MBeanInfoIsInvariant=true
    J2EEDomainObjectName=amx:j2eeType=J2EEDomain,name=amx
    AppserverDomainName=amx
    ObjectName=amx:j2eeType=X-DomainRoot,name=amx
    [...]

    • Enter Command> show-hierarchy

      You see output like this:

          X-DomainRoot=amx
    X-ConfigDottedNames
    X-SystemInfo
    X-QueryMgr
    X-DeploymentMgr
    X-UploadDownloadMgr
    X-BulkAccess
    X-MonitoringDottedNames
    X-JMXMonitorMgr
    X-Sample
    X-DomainConfig
    X-WebModuleConfig=admingui
    X-WebModuleConfig=adminapp
    X-WebModuleConfig=com_sun_web_ui
    X-JDBCResourceConfig=jdbc/__default
    X-JDBCResourceConfig=jdbc/__TimerPool
    X-J2EEApplicationConfig=MEjbApp
    [...]

    • Enter Command> list

      You see output like this:

          --- Top-level ---
    ConfigConfig: [server2-config, default-config, server-config,
    server3-config]
    ServerConfig: [server3, server, server2]
    StandaloneServerConfig: [server3, server, server2]
    ClusteredServerConfig: []
    ClusterConfig: []
    [...]

    • Enter Command> list-properties

      You see output like this:

          Properties for:
    amx:j2eeType=X-JDBCConnectionPoolConfig,name=DerbyPool
    Password=pbPublic
DatabaseName=jdbc:derby://localhost:9092/sun-appserv-samples
    User=pbPublic
    [...]

    • Enter Command> query

      You see output like this:

          --- Queried for j2eeType=X-*ResourceConfig ---
    j2eeType=X-JDBCResourceConfig,name=jdbc/__default
    j2eeType=X-JDBCResourceConfig,name=jdbc/__TimerPool
    [...]

    • 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