Java Dynamic Management Kit 5.0 Tutorial

CascadingAgent MBean

You should create one CascadingAgent MBean for every subagent you want to manage through the master agent. Each connects to an agent and mirrors all of that agent's registered MBeans in the master agent's MBean server. No other classes are required or need to be generated in order to represent the MBeans.

The agent whose MBean server contains an active cascading service is called a master agent in relation to the other agent that is mirrored. The agent to which the cascading service is connected is called the subagent in relation to its master agent. We say that it creates mirror MBeans to represent the subagent's MBeans. See Mirror MBeans in the Master Agent for a description of these objects.

A master agent can have any number of subagents, each controlled individually by a different CascadingAgent MBean. A subagent can itself contain cascading agents and mirror MBeans, all of which are mirrored 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, registered with its MBean server, and ready to receive connections.

In our example application, we use the RMI connector client that we will connect to the RMI connector server of the subagent on port 1099 of the local host. In fact, this is the same as the default values when instantiating a cascading agent MBean, but we also want to specify a pattern for selecting the MBeans to mirror. By default, all MBeans of the subagent are mirrored in the master agent; we provide an object name pattern to only select those in the subagent's CascadedDomain.

Example 16–1 Connecting to a Subagent

ObjectName mbeanObjectName = null;
String domain = server.getDefaultDomain();
mbeanObjectName = new ObjectName(domain + ":type=CascadingAgent");

RmiConnectorAddress address = new RmiConnectorAddress(,
CascadingAgent remAgent = new CascadingAgent(
    new ObjectName("CascadedDomain:*"),
ObjectInstance remAgentInstance =
    server.registerMBean(remAgent, mbeanObjectName);

[...] // Output omitted
// Now we explicitly start the cascading agent
// as it is not started automatically
echo("\nStarting the cascading agent...");
server.invoke(mbeanObjectName, "start", null, null);
echo("\tIs ACTIVE = " + server.getAttribute(mbeanObjectName, "Active"));  

Before the subagent's MBeans are mirrored, the CascadingAgent MBean must be registered in the master agent's MBean server, and its mirroring must be started. When you invoke the start operation of the cascading service MBean, it will connect it to its designated subagent and create one mirror MBean to represent each MBean in the subagent. When its Active attribute becomes true, the cascading mechanism is ready to use.

The CascadingAgent MBean exposes two writable attributes:

Neither of these attributes can be modified when the cascading service is active. You must first call the MBean's stop operation: this will remove all of the mirror MBeans for the given subagent and disconnect from the subagent's connector server. You can then modify the address or the class of the connector client. The new values will be used when you start the mirroring again: this lets you change subagents or even change protocols.

When the cascading service is stopped or its MBean is removed from the master agent, all of its mirror MBeans are unregistered. The MBean server delegate in the master agent will send an unregistration notification for each mirror MBean as it is removed.