Sun Microsystems
Products & Services
 
Support & Training
 
 

Previous Previous     Contents     Index     Next Next
Chapter 14

Cascading Service

The cascading service enables you to access the MBeans of a subagent directly through the MBean server of a master agent. The cascading service has been completely overhauled in Java Dynamic Management Kit (Java DMK) 5.1 to allow it to operate over the connector protocols defined by the Java Management Extensions (JMX) Remote API. The legacy cascading service is now deprecated. The examples of the legacy cascading service have been retained in Chapter 25, Legacy Cascading Agents, for reasons of backwards compatibility. However, when using legacy Java DMK connectors, you should use the new CasdingServiceMBean with wrapped legacy connectors rather than relying on the deprecated legacy cascading agent API.

The service is implemented in a CascadingServiceMBean, which makes it possible to mount source MBean servers (that are possibly located in subagents) into a target MBean server (that is located in a Master Agent) in a manner that is somewhat analogous to a File System mount operation. Several source MBean servers can be mounted in the same target MBean server, provided that different target paths are used. A source MBean server mounted from a subagent can itself be a Master Agent in which source MBean servers from another level of subagents are mounted, and so on and so on, forming a hierarchy of cascading agents.

By connecting to the root of an agent hierarchy, managers can have a single access point to many resources and services. All MBeans in the hierarchy are manageable through the top master agent, and a manager does not need to worry about their physical location. Like the other services, the cascading service is implemented as an MBean that can be managed dynamically. This enables the manager to control the structure of the agent hierarchy, adding and removing subagents as necessary.

In particular, the cascading service MBean can work with any protocol connector, including any custom implementation. Those supplied by the Java DMK give you the choice of using remote method invocation (RMI), or the JMX messaging protocol (JMXMP). The legacy connector protocols implemented by previous versions of Java DMK can also be used, as long as they have been wrapped for use with the JMX Remote API, as described in 9.5 Wrapping Legacy Connectors.

The cascading service also lets you specify a filter for selecting precisely the source MBeans that are cascaded in the target MBean server. This mechanism lets you limit the number of MBeans that are cascaded in the top agent of a large cascading hierarchy. For a general overview of the cascading service, see the Java Dynamic Management Kit 5.1 Getting Started Guide.

The code samples in this topic are from the files in the current/Cascading directory located in the main examplesDir (see Directories and Classpath in the preface).

This chapter contains the following topics:

14.1 CascadingService MBean

You should create a maximum of one CascadingService MBean in any target MBean server. The same CascadingService MBean can be used to mount multiple source MBean servers, that are located in multiple subagents in the Master Agent's target MBean server. The CascadingService creates one ProxyCascadingAgent behind the scenes for every mount operation it performs. The creation of that ProxyCascadingAgent is entirely hidden from the user. The complexity of the ProxyCascadingAgents is thus hidden by the CascadingService MBean. You should not attempt to use CascadingAgents directly, as was the case in earlier versions of Java DMK. Applications should always use the CascadingServiceMBean instead. The CascadingServiceMBean handles connections to the subagents and cascades all of that agent's registered MBeans into the master agent's target MBean server. No other classes are required or need to be generated to represent the MBeans.

The agent whose MBean server contains an active cascading service is called a master agent in relation to the subagent that is cascaded. The MBean server in which the MBeans are cascaded is called the target MBean server. An agent to which the cascading service is connected is called a subagent in relation to its master agent. Its MBean server is named the source MBean server. The source MBean server is the MBean server in which the MBeans actually reside. The CascadingService MBean creates target MBeans in the target MBean server to represent the subagent's source MBeans. For each source MBean, a CascadingProxy is registered behind the scenes in the target MBean server. See 14.2 Cascaded MBeans in the Master Agent for a description of these objects. The operation that makes it possible to cascade a source MBean server located in a subagent to the target MBean server in the Master Agent is called a mount operation, because of its similarity to a file system mount operation.

A master agent can have any number of subagents, each controlled individually by the same CascadingService MBean. Each mount operation is in fact implemented behind the scenes through a different CascadingAgent object created by the CascadingService MBean. The complexity of the CascadingAgent API is however completely abstracted by the CascadingServiceMBean. A subagent can itself contain cascading agents and cascaded MBeans, mounted from another layer of subagents, all of which will appear to be cascaded again in the master agent. This effectively enables cascading hierarchies of arbitrary depth and width.

Two master agents can also connect to the same subagent. This is similar to the situation where two managers connect to the same agent and can access the same MBean. If the implementation of a management solution permits such a condition, it is the designer's responsibility to handle any synchronization issues in the MBean.

The connection between two agents resembles the connection between a manager and an agent. The cascading service MBean relies on a connector client, and the subagent must have the corresponding connector server. The subagent's connector server must already be instantiated, be registered with its MBean server, and be ready to receive connections. The CascadingServiceMBean mount operation accepts a JMXServiceURL and a Map from which it obtains a JMXConnector from the JMXConnectorFactory. The mount operation will create the connection, and the unmount operation will close it.

Example 14-1 Mounting MBeans from a Subagent

[...]

private void mountSubagents(JMXServiceURL[] agentURLs) {
		 mountPoints = new String[agentURLs.length];
	    for (int i=0;i<agentURLs.length;i++) {
	         try {
               final String mountPointID =
		               cascadingService.mount(agentURLs[i],null,
                                         new ObjectName("ExportDomain:*"),
                                         "subagents/agent"+(i+1));

				     mountPoints[i] = mountPointID;
     		     echo(mountPointID);
	          } catch (Exception x) {
		           echo("\t!!! Could not mount subagent#"+(i+1)+" at " + 
		                agentURLs[i] + "\n\tError is: " + x);
		           x.printStackTrace();
		           echo("\nEXITING...\n");
		           System.exit(1);
	          }
	    }
}

	[...]

In Example 14-1, source MBean servers located in subagents are mounted using a defined JMXServiceURL, to cascade remote MBeans from the domain ExportedDomain. By default, all MBeans of the subagent are cascaded in the master agent, but in this example we provide an object name pattern so as only to select those in ExportedDomain. Example 14-1 is taken from the example class MasterAgent, in the directory examplesDir/current/Cascading. To emulate file system mount operations, a different target path for each mounted subagent is used. In this example, we use subagents/agent#x, where #x starts at 1, x is incremented for each subagent, and preserves the order of the JMX Service URLs that are given as input.


Note - You should use a different target path for every mount operation. The Java DMK cascading service implementation does not enforce this rule, but applications that are concerned with naming coherency should not break it.


Example 14-2 Creating the Cascading Service

[...]

    private void createCascadingService() {

        printline();
        echo("Creating the CascadingService" +
             " MBean within the MBeanServer:");
        try {
	            CascadingService service  = new CascadingService();
             ObjectInstance   cascadingInstance =
                  server.registerMBean(service, null);
             echo("\tCLASS NAME  = " + cascadingInstance.getClassName());
             echo("\tOBJECT NAME = " + cascadingInstance.getObjectName());
	             cascadingService = service;
          } catch (Exception e) {
             echo("\t!!! Could not create the " +
                  CascadingService.class.getName() + " MBean !!!");
             e.printStackTrace();
             echo("\nEXITING...\n");
             System.exit(1);
          }
    }

[...]

As shown in Example 14-2, before the subagent's source MBean servers can be mounted, the CascadingService MBean must be created and registered in, or tied to, the master agent's target MBean server. The CascadingService MBean in this example is registered in the master agent's target MBean server with a null object name, so that it is registered with its default ObjectName, that is defined in the CascadingServiceMBean interface.

Example 14-3 Unmounting MBeans from a Subagent

[...]

private void unmountAll() {
      printline();

	      echo("Unregistering CascadingServiceMBean");
       try {
	          server.unregisterMBean(CascadingServiceMBean.
				                        CASCADING_SERVICE_DEFAULT_NAME);
	      } catch (Exception x) {
	          echo("\t!!! Could not unregister " + CascadingServiceMBean.
		            CASCADING_SERVICE_DEFAULT_NAME + "\n\tError is: " + x);
	          x.printStackTrace();
	          echo("\nEXITING...\n");
	          System.exit(1);
       } 

	       echo("Unmounting all mount points");

       final String mounts[] = cascadingService.getMountPointIDs();
	       for (int i=0;i<mounts.length;i++) {
	            try {
		              if (cascadingService.unmount(mounts[i]))
		                  echo("unmounted "+mounts[i]);
	            } catch (Exception x) {
		              echo("\t!!! Could not unmount " + mounts[i] +
		                   "\n\tError is: " + x);
		              x.printStackTrace();
		              echo("\nEXITING...\n");
		              System.exit(1);
	            }
	       }
  }

[...]

Previous Previous     Contents     Index     Next Next