Java Dynamic Management Kit 5.1 Tutorial

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);
	            }
	       }
  }

[...]

When the master agent is stopped, it stops the cascading service by unmounting all the subagents that are currently mounted. This is done by first unregistering the CascadingServiceMBean from its target MBean server, to ensure that nobody can create new mount points while the removal is ongoing. Then, for each currently mounted mount point, the unmount operation is called, so that all proxies for the associated cascaded MBeans are unregistered from the target MBean server. The MBean server delegate in the master agent sends an unregistration notification for each cascaded MBean as it is removed.