com.sun.jdmk.remote.cascading
Interface CascadingServiceMBean

All Known Implementing Classes:

CascadingService

public interface CascadingServiceMBean

The CascadingServiceMBean is a high level service MBean that makes it possible to remotely configure CascadingAgents. This MBean makes it possible to mount a partial view of a source MBeanServer known by its JMXServiceURL into the target MBeanServer of this CascadingServiceMBean.

The target MBeanServer of a CascadingServiceMBean is usually the MBeanServer in which that CascadingServiceMBean is registered. It is recommended to instantiate at most one CascadingServiceMBean per target MBeanServer. If no ObjectName is specified when registering the CascadingServiceMBean, then the CascadingServiceMBean will supply its own default name: CASCADING_SERVICE_DEFAULT_NAME=new ObjectName("com.sun.jdmk:type=CascadingService").

If the JMX Connection with a source MBeanServer fails, the CascadingServiceMBean will emit a JMXConnectionNotification with the following parameters:

• The type is "com.sun.jdmk.remote.cascading.failed"
• The source is the CascadingServiceMBean.
• The connectionId is the mountPointID that was returned by the the mount method
• The userData is the source JMXConnectionNotification

If the cascading is unmounted (unmount was called) then the CascadingServiceMBean will emit a JMXConnectionNotification with the following parameters:

• The type is "com.sun.jdmk.remote.cascading.stopped"
• The source is the CascadingServiceMBean.
• The connectionId is the mountPointID that was returned by the the mount method

Note: In this implementation, the mount operation does not perform any checks with regards to the coherency of the supplied targetPath. It is under the responsibility of the application to conform to the rules documented in com.sun.jdmk.remote.cascading package documentation, section "The File System Analogy".

Since:

Java DMK 5.1

Field Summary

static String	CASCADING_FAILED_NOTIFICATION The type of the JMXConnectionNotification emitted when a JMXConnectionNotification.FAILED is emitted by the underlying JMX Remote Connection.
static ObjectName	CASCADING_SERVICE_DEFAULT_NAME Default ObjectName of the CascadingServiceMBean MBean.
static String	CASCADING_STOPPED_NOTIFICATION The type of the JMXConnectionNotification emitted when a source MBeanServer is unmounted.

Method Summary

String[]	getMountPointIDs() Returns an array of current mountPointIDs.
boolean	isMounted(String mountPointID) Tell whether the given ID identifies a currently mounted mountPoint.
String	mount(JMXServiceURL sourceURL, Map sourceMap, ObjectName sourcePattern, String targetPath) Mounts a partial view of the source MBeanServer identified by its JMXServiceURL.
boolean	unmount(String mountPointID) Undo the mount operation identified by mountPointID.

Field Detail

CASCADING_SERVICE_DEFAULT_NAME

static final ObjectName CASCADING_SERVICE_DEFAULT_NAME

Default ObjectName of the CascadingServiceMBean MBean.

 CASCADING_SERVICE_DEFAULT_NAME = 
    new ObjectName("com.sun.jdmk:type=CascadingService");
 

CASCADING_FAILED_NOTIFICATION

static final String CASCADING_FAILED_NOTIFICATION

The type of the JMXConnectionNotification emitted when a JMXConnectionNotification.FAILED is emitted by the underlying JMX Remote Connection.

See Also:

Constant Field Values

CASCADING_STOPPED_NOTIFICATION

static final String CASCADING_STOPPED_NOTIFICATION

The type of the JMXConnectionNotification emitted when a source MBeanServer is unmounted.

See Also:

unmount(java.lang.String), Constant Field Values

Method Detail

mount

String mount(JMXServiceURL sourceURL,
             Map sourceMap,
             ObjectName sourcePattern,
             String targetPath)
             throws IOException,
                    InstanceAlreadyExistsException

Mounts a partial view of the source MBeanServer identified by its JMXServiceURL. This method obtains a JMXConnector by calling JMXConnectorFactory.connect(sourceURL,sourceMap). Then it mounts the source MBeanServer thus connected under the provided targetPath into the target MBeanServer of this CascadingServiceMBean. Note that only the source MBeans whose source ObjectName satisfy the provided sourcePattern will be mounted.

Finally, it returns a mountPointID string identifying this mount operation. The calling application is expected to later call unmount with this mountPointID as parameter.

Parameters:

sourceURL - A JMXServiceURL from which a JMXConnector to the source MBeanServer can be obtained.

sourceMap - A Map object that will be passed to the JMXConnectorFactory.connect(JMXServiceURL,Map) method, in order to connect to the source MBeanServer. This parameter can be null.

sourcePattern - An ObjectName pattern that must be satisfied by the ObjectNames of the source MBeans.

The sourcePattern is evaluated in the context of the source MBeanServer. The source pattern is used to perform a partial mount of the source MBeanServer in the target MBeanServer. Only those MBeans that satisfy the pattern will be mounted. The source pattern is thus a filter element. A null sourcePattern is equivalent to the wildcard "*:*".

targetPath - The domain path under which the source MBeans will be mounted in the target MBeanServer.

If this parameter is not null, all source MBean names will be transformed in the target MBeanServer by prefixing their domain name with the string targetPath+"/". An MBean whose name is "D:k1=v1,k2=v2" will thus be mounted as "targetPath/D:k1=v1,k2=v2".

A null targetPath means that MBeans are mounted directly at the root of the hierarchy, that is, as if they were local MBeans. Using a null targetPath is thus highly discouraged, as it could cause name conflicts in the target MBeanServer.

Similarly, MBeans from different sources should not be mounted under the same targetPath. Moreover, an application should not attempt to mount source MBeans under a targetPath that already contain MBeans in the target MBeanServer.

However, this implementation does not enforce these rules: It is the responsibility of the application that uses the CascadingService to ensure the consistency of the mounting strategy - see The File System Analogy.

Note: A zero-length targetPath is treated as a null targetPath.

Returns:

A mountPointID identifying this mount operation. This mountPointID must be later used to call unmount(java.lang.String).

Throws:

NullPointerException - if sourceURL is null. See JMXConnectorFactory.connect.

IOException - if the connector client or the connection to the source MBeanServer cannot be made, or if the underlying CascadingAgent cannot be started because of a communication problem. See JMXConnectorFactory.connect and CascadingAgentMBean.start.

SecurityException - if the connection with the source MBeanServer cannot be made for security reasons. See JMXConnectorFactory.connect.

InstanceAlreadyExistsException - if a name conflict is detected while performing the mount operation. See CascadingAgentMBean.start.

unmount

boolean unmount(String mountPointID)
                throws IOException

Undo the mount operation identified by mountPointID. The specified mountPointID must be a mount point ID obtained from mount.

Parameters:

mountPointID - A mount point ID previously obtained from mount.

Returns:

true if the given mountPointID was found and unmounted by this invocation.

Throws:

IOException - if the connection with the source MBeanServer cannot be closed cleanly, or if the underlying CascadingAgent fails to stop. See JMXConnector.close and CascadingAgentMBean.stop.

isMounted

boolean isMounted(String mountPointID)

Tell whether the given ID identifies a currently mounted mountPoint.

Returns:

true if the given mountPointID was found.

getMountPointIDs

String[] getMountPointIDs()

Returns an array of current mountPointIDs.

Returns:

an array of mountPointIDs currently mounted.