org.glassfish.admin.amx.core
Interface AMXProxy

All Superinterfaces:

AMX_SPI

All Known Subinterfaces:

AbstractModule, AccessLog, Action, AdminObjectResource, AdminService, AlertService, AlertSubscription, AMXConfigProxy, AmxPref, AnyProperty, AppClientModule, Application, ApplicationConfig, ApplicationRef, ApplicationRefReferent, Applications, ApplicationsBase, AuditModule, AuthRealm, AvailabilityService, BackendPrincipal, BulkAccess, Cluster, ClusteredServer, ClusterRef, ClusterRefConfigReferent, Clusters, Config, ConfigElement, Configs, ConfigTools, ConnectionPool, ConnectorConnectionPool, ConnectorResource, ConnectorRuntimeAPIProvider, ConnectorService, ContainerMonitoring, ContextParam, CustomResource, DasConfig, DiagnosticService, Domain, DomainRoot, EJB, EjbContainer, EjbContainerAvailability, EJBModule, EjbTimerService, Engine, EntityBean, EnvEntry, Event, Ext, Extra, FileCache, FilterConfig, GroupManagementService, HealthChecker, Http, HttpAccessLog, HttpFileCache, HttpListener, HttpService, IiopListener, IiopService, J2EEApplication, J2EEDeployedObject, J2EEDomain, J2EELogicalServer, J2EEManagedObject, J2EEModule, J2EEResource, J2EEServer, JaccProvider, JavaConfig, JavaMailResource, JCAConnectionFactory, JCAManagedConnectionFactory, JCAResource, JdbcConnectionPool, JDBCDataSource, JDBCDriver, JdbcResource, JDBCResource, JmsAvailability, JmsHost, JMSResource, JmsService, JmxConnector, JndiResource, JNDIResource, JTAResource, JVM, KeepAlive, LbConfig, LbConfigs, ListenerConfig, LoadBalancer, LoadBalancers, Logging, LogService, MailResource, ManagementRule, ManagementRules, ManagerProperties, MdbContainer, MessageDrivenBean, MessageSecurityConfig, Module, ModuleLogLevels, ModuleMonitoringLevels, MonitoringRoot, MonitoringService, NamedConfigElement, NetworkConfig, NetworkListener, NetworkListeners, NodeAgent, NodeAgents, Orb, Pathnames, PersistenceManagerFactoryResource, PortUnification, Profiler, PropertiesAccess, Property, Protocol, ProtocolChain, ProtocolChainInstanceHandler, ProtocolFilter, ProtocolFinder, Protocols, ProviderConfig, Query, Realms, Ref, RefReferent, RegistryLocation, RequestPolicy, RequestProcessing, Resource, ResourceAdapter, ResourceAdapter, ResourceAdapterModule, ResourceRef, ResourceRefReferent, Resources, ResponsePolicy, RMI_IIOPResource, RuntimeRoot, Sample, SecurityMap, SecurityService, SelectionKeyHandler, Server, ServerMon, ServerRef, ServerRefReferent, ServerRuntime, Servers, Servlet, SessionBean, SessionConfig, SessionManager, SessionProperties, Singleton, SingletonSessionBean, Ssl, SslContainer, StandaloneServer, StatefulSessionBean, StatelessSessionBean, StoreProperties, SystemApplications, SystemInfo, SystemPropertiesAccess, SystemProperty, SystemStatus, ThreadPool, ThreadPools, Tools, TransactionService, TransformationRule, Transport, Transports, URLResource, VirtualServer, WebContainer, WebContainerAvailability, WebModule, WebServiceEndpoint

All Known Implementing Classes:

AMXProxyHandler

@Taxonomy(stability=UNCOMMITTED)
public interface AMXProxy
extends AMX_SPI

An AMXProxy offers generic access to any AMX-compliant MBean, including the ability to navigate upwards to the Parent MBean, find all children or those of a particular type or name, to get all metadata, atttributes, or to invoke any method.

Various sub-interfaces offer additional functionality, such as explicit methods for getting children of a particular type, creating new children (eg configuration), attribute getter/setter methods, etc. The most notable sub-interface is AMXConfigProxy and its sub-interfaces.

Implementing handler— an AMXProxy is implemented by AMXProxyHandler, but the handler should be considered private: do not use it as it is subject to change.

Sub interfaces— the base AMXProxy interface can and should be extended for specific MBeans, but in most cases it will not be appropriate or convenient for MBean implementors to 'implement' the interface because it is for use by a proxy to the MBean, not the MBean itself. In particular, it makes no sense for an MBean to implement the proxy interface because the proxy interface demands the use of AMXProxy and sub-types, whereas the MBean must return ObjectName.

Method name convention— a convention followed in AMXProxy is that convenience "getter" methods (non-remote methods implemented directly by the proxy itself) do not use the get prefix, in order to distinguish them from the usual getter pattern for real MBean attributes. For example, parent() returns an AMXProxy, but AMX_SPI.getParent() returns the value of the Parent attribute (an ObjectName). The same convention is followed for childrenSet(), etc / AMX_SPI.getChildren().

Not authoritative— proxy interfaces should not be considered authoritative, meaning that an underlying MBean implementation determines what the MBean actually provides, possibly ignoring the proxy interface (this is the case with config MBeans, which derive their metadata from the ConfigBean @Configured interface). Therefore, it is possible for the proxy interface to completely misrepresent the actual MBean functionality, should the interface get out of sync with the actual MBean. Only at runtime would errors between the interface and the MBean would emerge.

Methods in sub-interfaces of AMXProxy— To mininimize issues with tracking implementation changes over time (eg addition or removal of attributes), sub-interfaces of AMXProxy might choose to omit getter/setter methods for attributes, and instead manifest the containment relationships (children), which form the core of usability of navigating the hierarchy. The methods attributeNames() and attributesMap() can be used to generically obtain all available attributes, and of course MetaGetters#mbeanInfo provides extensive metadata.

Auto-mapping of ObjectName— An AMXProxy automatically maps various ObjectName constructs to the equivalent AMXProxy(ies).

For example, an MBean providing an Attribute named Item should declare it as an ObjectName, or for a plurality Items, declaring an ObjectName[]. Any of the following proxy methods (declared in a sub-interface of AMXProxy) will automatically convert the resulting ObjectName(s) into the corresponding AMXProxy or plurality of AMXProxy:

AMXProxy getItem();
AMXProxy[] getItems();
Set<AMXProxy> getItems();
List<AMXProxy> getItems();
Map<String,AMXProxy> getItems();

The same approach is used in the generic child(java.lang.String), childrenSet(), childrenMap(java.lang.String) methods.

Invoking operations generically— Use the invokeOp(java.lang.String) methods to invoke an arbitrary operation by name.

See Also:

Extra, MetaGetters, AMXConfigProxy

Method Summary

<T extends AMXProxy> T	as(Class<T> intf) Return a proxy implementing the specified interface.
Set<String>	attributeNames() Get all available Attributes names, no trip to server needed.
Map<String,Object>	attributesMap() Get a Map keyed by Attribute name of all Attribute values.
Map<String,Object>	attributesMap(Set<String> attrNames) Get a Map keyed by Attribute name of the specified Attribute values.
<T extends AMXProxy> T	child(Class<T> intf) Get a singleton child.
AMXProxy	child(String type) Get a singleton child of the specified type.
<T extends AMXProxy> Map<String,T>	childrenMap(Class<T> intf) Get all children of the same type.
Map<String,AMXProxy>	childrenMap(String type) Get all children of a specified type, keyed by the name as found in the ObjectName.
Map<String,Map<String,AMXProxy>>	childrenMaps() Get Maps keyed by type, with a Map keyed by name.
Set<AMXProxy>	childrenSet() Get all existing children of all types.
Extra	extra() additional capabilities, including direct JMX access
Object	invokeOp(String operationName) Invoke an operation by name, no arguments.
Object	invokeOp(String operationName, Object[] params, String[] signature) Invoke an operation by name, JMX style params and signature.
String	java() Return a Java interface representing this MBean, suitable for display or compilation
String	nameProp() Value of the name property of the ObjectName.
ObjectName	objectName() The ObjectName of this MBean.
AMXProxy	parent() MBean MUST return an ObjectName.
String	parentPath() The value of the PARENT_PATH_KEY property in the ObjectName
String	path() Get this MBean's pathname.
String	type() The value of the TYPE_KEY property in the ObjectName
boolean	valid() A proxy can become invalid if its corresponding MBean is unregistered, the connection is lost, etc.

Methods inherited from interface org.glassfish.admin.amx.core.AMX_SPI

getChildren, getName, getParent

Method Detail

parent

AMXProxy parent()

MBean MUST return an ObjectName. May be null for DomainRoot only.

nameProp

String nameProp()

Value of the name property of the ObjectName. Could differ from getName(), which returns the internal name, which might not be legal in an ObjectName, or could have changed.

parentPath

String parentPath()

The value of the PARENT_PATH_KEY property in the ObjectName

type

String type()

The value of the TYPE_KEY property in the ObjectName

valid

boolean valid()

A proxy can become invalid if its corresponding MBean is unregistered, the connection is lost, etc. If currently marked as valid, a trip to the server is made to verify validity.

Returns:

true if this proxy is valid

childrenSet

Set<AMXProxy> childrenSet()

Get all existing children of all types. Returns null if the MBean is a leaf node (cannot have children) .

childrenMap

Map<String,AMXProxy> childrenMap(String type)

Get all children of a specified type, keyed by the name as found in the ObjectName.

childrenMap

<T extends AMXProxy> Map<String,T> childrenMap(Class<T> intf)

Get all children of the same type. The Map is keyed by the name as found in the ObjectName.

Parameters:

intf - the proxy interface, type is deduced from it

childrenMaps

Map<String,Map<String,AMXProxy>> childrenMaps()

Get Maps keyed by type, with a Map keyed by name.

child

AMXProxy child(String type)

Get a singleton child of the specified type. An exception is thrown if the child is not a singleton. If children do not exist, or there is no such child, then null is returned.

child

<T extends AMXProxy> T child(Class<T> intf)

Get a singleton child. Its type is deduced from the interface using Util#deduceType.

as

<T extends AMXProxy> T as(Class<T> intf)

Return a proxy implementing the specified interface. Clients with access to a sub-interface of AMXProxy can specialized it with this method; the proxy by default will implement only the base AMXProxy interface.

This method is needed when crossing module boundaries where the desired class is not available to the AMXProxyHandler through its own classloader and/or when a generic proxy has been obtained through other means. When sub-interfaces of AMXProxy already return the appropriate type there is no reason or need to use this method.

attributesMap

Map<String,Object> attributesMap()

Get a Map keyed by Attribute name of all Attribute values. Requires a trip to the server.

attributesMap

Map<String,Object> attributesMap(Set<String> attrNames)

Get a Map keyed by Attribute name of the specified Attribute values.

attributeNames

Set<String> attributeNames()

Get all available Attributes names, no trip to server needed. Requires a trip to the server.

path

String path()

Get this MBean's pathname. Its parent path can be obtained by calling path on parent()

objectName

ObjectName objectName()

The ObjectName of this MBean.

java

String java()

Return a Java interface representing this MBean, suitable for display or compilation

extra

Extra extra()

additional capabilities, including direct JMX access

invokeOp

Object invokeOp(String operationName)

Invoke an operation by name, no arguments.

invokeOp

Object invokeOp(String operationName,
                Object[] params,
                String[] signature)

Invoke an operation by name, JMX style params and signature.