2.5.5 Cascading

Cascading is the term used to describe a hierarchy of agents, where management requests are passed from a master agent to one of its subagents. A master agent connects to other agents, possibly remotely, through their connector server components, much like a manager connects to an agent. In a set of cascading agents, all MBeans in a subagent are visible as if they are registered in their master agent. The master agent hides the physical location of subagents and provides client applications with a centralized access point.

In Java DMK 5.1, the cascading service is implemented over JMX Remote API connectors. The CascadingServiceMBean makes it possible to mount source MBean servers, that are possibly located in subagents, into a target MBean server, that is located in the master agent, in a manner that is somewhat analogous to a File System mount operation.

2.5.5.1 Object Names and Domain Paths

The Java DMK cascading API introduces the notion of a domain path. An ObjectName is thus decomposed into three parts, as follows.

domain-path/domain-base-name:key-property-list

The domain path is a hierarchical name similar to a File System path name, using the character `/' as a separator.

2.5.5.2 File System Analogy

The CascadingServiceMBean provided in the Java DMK 5.1 makes it possible to mount MBeans from a source MBean server under a target domain path in a target MBean server, in a similar way to a File System mount operation.

Although our API also allows you to implement different cascading schemes, we recommend that applications only implement those schemes that can be compared to a regular File System mount, as follows.

• When calling the CascadingServiceMBean.mount operation, always use a non null targetPath. The target path can be assimilated to a target mount point in the File System analogy.

• Never use a targetPath under which MBeans are already registered in the target MBean server. Using such a target path could cause a naming conflict when mounting the source MBeans to the target MBean server.

• Never give the same targetPath to two different mount operations. Like in the file system analogy, you should not attempt to mount two sources to the same target path.

Our implementation does not enforce those rules, but applications which are concerned with naming consistency and coherency should make sure to respect them. See the package description in the API documentation for the com.sun.jdmk.remote.cascading package for details.

2.5.5.3 CascadingServiceMBean

The cascading service proposed in the com.sun.jdmk.remote.cascading package is based on a simple MBean class, the CascadingServiceMBean.

• The CascadingServiceMBean provides methods that make it possible to mount MBeans from a source MBean server in a target MBean server under a target domain path. Usually the target MBean server is the MBean server in which the CascadingService is registered.

  There should be only one CascadingServiceMBean per target MBean server.

• The CascadingServiceMBean.mount method mounts a partial view of a source MBean server known by its JMXServiceURL in the target MBean server of the CascadingServiceMBean.

• The CascadingServiceMBean.unmount method cancels a previous mount operation. The unmount operation will close the connection that was opened by the mount operation.

The default CascadingService implementation provided in the Java DMK 5.1 relies on proxy-based cascading and implements the mount operation by instantiating a ProxyCascadingAgent behind the scenes. Although the ProxyCascadingAgent offers a public API, you should not use it directly. Applications should use the CascadingServiceMBean instead.

CascadingServiceMBeans are also notification emitters, which emit notifications when mountpoints are unmounted, as a result of a an unmount operation, or because the underlying connection with the source MBean server has been closed or failed.

2.5.5.4 Cascading over Java DMK legacy connectors

There are two possibilities to implement cascading over Java DMK legacy connectors.

• Use the legacy cascading service that was provided in earlier versions of the Java DMK. This legacy cascading service is still provided for reasons of backwards compatibility, but it is now deprecated. This alternative is therefore not recommended.

• Create a JMXServiceURL from which a JMXConnector wrapping a legacy Java DMK ConnectorClient can be obtained from the JMXConnectorFactory. You can then use this JMXServiceURL with the new CascadingServiceMBean API. See the Java Dynamic Management Kit 5.1 Tutorial for more information about wrapping legacy connectors.