com.sun.jdmk.remote.cascading
Class CascadingService

java.lang.Object
  com.sun.jdmk.remote.cascading.CascadingService

All Implemented Interfaces:

CascadingServiceMBean, MBeanRegistration, NotificationBroadcaster, NotificationEmitter

public class CascadingService
extends Object
implements CascadingServiceMBean, NotificationEmitter, MBeanRegistration

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 or is permanently closed, 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
• The userData is either null, or the exception thrown by unmount

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 The File System Analogy

In this implementation, the CascadingService relies on the ProxyCascadingAgent.

Since:

Java DMK 5.1

Field Summary

Fields inherited from interface com.sun.jdmk.remote.cascading.CascadingServiceMBean

CASCADING_FAILED_NOTIFICATION, CASCADING_SERVICE_DEFAULT_NAME, CASCADING_STOPPED_NOTIFICATION

Constructor Summary

CascadingService()
Instantiate a new CascadingService.

CascadingService(MBeanServer targetMBS)
Instantiate a new CascadingService for the specified target MBeanServer.

Method Summary

void	addNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback)
String[]	getMountPointIDs() Returns an array of current mountPointIDs.
MBeanNotificationInfo[]	getNotificationInfo()
MBeanServer	getTargetMBeanServer() The target MBeanServer in which the source MBeans will be mounted under the target path.
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.
void	postDeregister()
void	postRegister(Boolean registrationDone)
void	preDeregister()
ObjectName	preRegister(MBeanServer server, ObjectName name) Allows the MBean to perform any operations it needs before being registered in the MBean server.
void	removeNotificationListener(NotificationListener listener)
void	removeNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback)
boolean	unmount(String mountPointID) Undo the mount operation identified by mountPointID.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CascadingService

public CascadingService()

Instantiate a new CascadingService. The target MBeanServer for this service will be the MBeanServer in which this object is registered.

CascadingService

public CascadingService(MBeanServer targetMBS)

Instantiate a new CascadingService for the specified target MBeanServer. The target MBeanServer for this service will be the specified targetMBS.

Parameters:

targetMBS - The target MBeanServer for this cascading service.

Method Detail

mount

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

Description copied from interface: CascadingServiceMBean

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.

Specified by:

mount in interface CascadingServiceMBean

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 CascadingServiceMBean.unmount(java.lang.String).

Throws:

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.

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

unmount

public final boolean unmount(String mountPointID)
                      throws IOException

Description copied from interface: CascadingServiceMBean

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

Specified by:

unmount in interface CascadingServiceMBean

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

public boolean isMounted(String mountPointID)

Description copied from interface: CascadingServiceMBean

Tell whether the given ID identifies a currently mounted mountPoint.

Specified by:

isMounted in interface CascadingServiceMBean

Returns:

true if the given mountPointID was found.

getMountPointIDs

public String[] getMountPointIDs()

Description copied from interface: CascadingServiceMBean

Returns an array of current mountPointIDs.

Specified by:

getMountPointIDs in interface CascadingServiceMBean

Returns:

an array of mountPointIDs currently mounted.

addNotificationListener

public final void addNotificationListener(NotificationListener listener,
                                          NotificationFilter filter,
                                          Object handback)
                                   throws IllegalArgumentException

Specified by:

addNotificationListener in interface NotificationBroadcaster

Throws:

IllegalArgumentException

removeNotificationListener

public final void removeNotificationListener(NotificationListener listener)
                                      throws ListenerNotFoundException

Specified by:

removeNotificationListener in interface NotificationBroadcaster

Throws:

ListenerNotFoundException

removeNotificationListener

public final void removeNotificationListener(NotificationListener listener,
                                             NotificationFilter filter,
                                             Object handback)
                                      throws ListenerNotFoundException

Specified by:

removeNotificationListener in interface NotificationEmitter

Throws:

ListenerNotFoundException

getNotificationInfo

public MBeanNotificationInfo[] getNotificationInfo()

Specified by:

getNotificationInfo in interface NotificationBroadcaster

getTargetMBeanServer

public final MBeanServer getTargetMBeanServer()

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

Returns:

the target MBeanServer.

preRegister

public ObjectName preRegister(MBeanServer server,
                              ObjectName name)
                       throws Exception

Allows the MBean to perform any operations it needs before being registered in the MBean server. If the target MBeanServer supplied at construction time was null, then server becomes the target MBeanServer.

Specified by:

preRegister in interface MBeanRegistration

Parameters:

server - The MBean server in which the MBean will be registered.

name - The object name of the MBean. If name is null then CascadingServiceMBean.CASCADING_SERVICE_DEFAULT_NAME is returned.

Returns:

The given name, or if null the default name for the CascadingService.

Throws:

IllegalArgumentException - if no target MBeanServer was specified in the constructor and this object is already registered in an MBeanServer.

Exception

See Also:

MBeanRegistration.preRegister(javax.management.MBeanServer, javax.management.ObjectName)

postRegister

public void postRegister(Boolean registrationDone)

Specified by:

postRegister in interface MBeanRegistration

preDeregister

public void preDeregister()
                   throws Exception

Specified by:

preDeregister in interface MBeanRegistration

Throws:

Exception

postDeregister

public void postDeregister()

Specified by:

postDeregister in interface MBeanRegistration