Package com.sun.appserv.management

Appserver Management Extensions (AMX) package summary.

See:
Description

Interface Summary

DomainRoot

The top-level interface for an appserver domain.

Package com.sun.appserv.management Description

Appserver Management Extensions (AMX) package summary.

Contents

Overview
Naming Conventions
Proxies Versus MBean Interfaces
System Requirements

Overview

AMX is a JMX-based API for managing all aspects of Sun Java System Appserver 9.0. As a programmer, there are two ways to access these APIs:

1. Direct use of JMX eg the method of javax.management.MBeanServerConnection;
2. Use of client-side dynamic proxies, which provide client-side implementations of the AMX APIs.
   

Unless you are writing very generic code, use of the client-side dynamic proxies is recommended. They are convenient and easy to use, and are type-safe as well. For details on the differences, see Proxy versus MBean Interface later on this page.

Unless otherwise noted in the javadoc, all 'public' (as in the java keyword 'public') classes provided as part of the com.sun.appserv.management package and all its subpackages are public interfaces that are expected to remain backward-compatible for all minor releases, with the intent (but not guarantee) of maintaining backward-compatibility between major releases. This statement applies only to 'public' methods and variables of 'public' classes; it does not apply to package-private, protected or private methods or variables.

The AMX model

AMX MBeans (and their corresponding interfaces) can be grouped into four categories:

Configuration MBeans represent configuration as found in domain.xml. They are passive MBeans that exist for the purpose of reading, writing and creating configuration elements in domain.xml. These MBeans all have interface name that end in Config.

Monitoring MBeans expose monitoring data. These MBeans all have interface name that end in Monitor.

JSR 77 MBeans. These MBeans exist as defined by the Java Enterprise Management specification, JSR 77. Some of them also provide ways to get to their corresponding Config or Monitor MBean(s).

Other MBeans include DomainRoot and various utility MBeans such as QueryMgr, BulkAccess and DeploymentMgr. Most of these MBeans have interface name that end in Mgr.

Naming conventions

Various suffixes are used for classes within AMX. These suffixes are used consistently throughout the API to aid in understanding what any particular class is used for. The suffix, combined with the package name together give a strong clue as the functionality of any given interface (MBean). Note that the J2EE Management (JSR 77) interfaces do not use any suffix; these are specified by a standard.

Note that all interfaces representing MBeans are implemented as dynamic proxies to server-side MBeans. The actual MBean interface, as seen in its MBeanInfo, is a subset of this interface, and also differs slightly in certain consistent ways. See Proxy Versus MBean Interface below for further information.

Idiom	Explanation
Abc	A dynamic proxy interface Abc, such as DomainRoot.
AbcMgr	Manager interface for items or activities of type Abc
XyzConfig	Configuration interface for an item of type Xyz
XyzMonitor	Monitoring interface for an item of type Xyz

Examples for naming conventions:

Example	Discussion
HTTPListenerConfig WebModuleConfig	The Config suffix used by all configuration MBeans.
DeploymentMgr JMXMonitorMgr	The Mgr suffix used by most utility MBeans.
ServletMonitor	The Monitor suffix used by all monitoring MBeans.
DomainRoot J2EEDomain, J2EEServer, etc	No common suffix.

Proxy Versus MBean Interface

The AMX interfaces provide a convenient and easy-to-use way of accessing the server-side JMX MBeans. They are found in the following Java packages (or their sub-packages):

com.sun.appserv.management.base
com.sun.appserv.management.config
com.sun.appserv.management.monitor
com.sun.appserv.management.j2ee
com.sun.appserv.management.deploy

The com.sun.appserv.management.client package contains code for initiating connections to the Appserver. There are also a small number of support classes.

When using the AMX interfaces, you need not understand the way they are mapped to the MBeanInfo of an MBean. Such knowledge is necessary only if you are using straight JMX and/or you are doing more advanced things.

An MBean's MBeanInfo is very similar to its AMX interface. However, for routines involving the creation or querying of other interfaces/MBeans, there is a consistent way in which certain operations are mapped from the AMX interface to the equivalent MBean operation:

AMX Interface (proxy) Pattern	MBeanInfo Pattern	Explanation
Set getContaineeJ2EETypes(); Map getMultiContaineeMap(...); Map getContaineeMap(...); AMX getSingletonContainee(...); Set getContaineeSet(...); Set getContaineeSet( ); Set getContaineeSet(...); Set getByNameContaineeSet(...); AMX getContainee(...);	Set getContaineeJ2EETypes(); Map getMultiContaineeObjectNameMap(...); Map getContaineeObjectNameMap(...); ObjectName getSingletonContaineeObjectName(...); Set getContaineeObjectNameSet(...); Set getContaineeObjectNameSet( ); Set getContaineeObjectNameSet(...); Set getByNameContaineeObjectNameSet(...); ObjectName getContaineeObjectName(...);	These methods are from Container. Note that ObjectName either replaces AMX or is inserted into the operation name.
AbcConfig createAbcConfig(...);	ObjectName createAbcConfig(...);	Creation of a new item always returns an appropriate interface for the type of item created when using AMX. When using MBeans, an ObjectName is always returned.
Abc getAbc();	ObjectName getAbcObjectName();	The MBean represented by ObjectName implements the Abc interface with the differences described in this table.

System requirements

The AMX client works against Appserver 8.1 PE or EE or later. However, this document describes the AMX APIs as theyu exist in version 9.0; they are largely compatible. JDK 1.5 is required.

The following jar files are required to use the MBean API (AMX) and must be in the classpath of your client application. They are found in the appserver install at <install_root>/lib.

jar file name	Discussion
appserv-ext.jar	This jar file contains all the interfaces and classes necessary to access AMX; all of which reside within the package com.sun.appserv.management or its subpackages.
javaee.jar	For including the Stats and Statistics interfaces defined by JSR 77.