WebSphere Message Brokers
File: ae33040_
Writer: John Cooper

Task topic

This build: July 31, 2007 21:29:00

Navigating broker domains using the Configuration Manager Proxy

Before you start

Before starting this step, you must have completed Connecting to a Configuration Manager using the Configuration Manager Proxy.

Each domain object that is controllable from the Configuration Manager is represented as a single object in the Configuration Manager Proxy (CMP) and this includes:
  • Brokers
  • Execution groups
  • Deployed message flows
  • Topics
  • Collectives
  • Subscriptions
  • Publish/Subscribe topology
  • Broker event log

The CMP also handles deployed message sets, although these are handled as attributes of deployed execution groups.

Collectively known as administered objects these objects provide the bulk of the interface to the Configuration Manager, and as such are fundamental to understanding the Configuration Manager Proxy API.

Each administered object is an instance of a Java class that describes the underlying type of object in the Configuration Manager. The possible Java classes follow:
Java class Class function
TopologyProxy Describes the pub/sub topology.
CollectiveProxy Describes pub/sub collectives.
BrokerProxy Describes brokers.
ExecutionGroupProxy Describes execution groups.
MessageFlowProxy Describes message flows that have already been deployed to execution groups; does NOT describe message flows in the Broker Application Development perspective of the toolkit.
TopicProxy Describes topics.
TopicRootProxy Describes the root of the topic hierarchy.
LogProxy Describes the broker’s event log for the current user.
SubscriptionsProxy Describes a subset of the active subscriptions.
ConfigManagerProxy Describes the Configuration Manager itself.
Each administered object describes a single object that is controllable from the Configuration Manager. For example, every broker within a broker domain will have one BrokerProxy instance that represents it within the CMP application, and so on.

Declared in each administered object is a set of public methods that programs can use to enquire and manipulate properties of the underlying Configuration Manager object to which the instance refers. For example, on a BrokerProxy object that refers to broker B1, it is possible to invoke methods that cause the broker to reveal its run-state, or cause it to start all its message flows and so on.

To access an administered object, and make use of its API, it is necessary to first request a handle to it from the object that logically owns it. For example, as brokers logically own execution groups, in order to gain a handle to execution group EG1 running on broker B1 the application needs to ask the BrokerProxy object represented by B1 for a handle to the ExecutionGroupProxy object represented by EG1.

In the ConnectToConfigManager example a handle is gained to the ConfigManagerProxy object. The ConfigManagerProxy is logically the root of the administered object tree, which means that all other objects in the Configuration Manager are directly, or indirectly, accessible from it. The Configuration Manager directly owns the Publish/Subscribe topology and so there is a method that applications can invoke from ConfigManagerProxy in order to gain a handle to the TopologyProxy object. Similarly, the topology logically contains the set of all brokers and so it is possible to call methods on the TopologyProxy object to access the BrokerProxy objects. The complete hierarchy of these access relationships is shown below:
Using the ConnectToConfigManager example as a starting point, the following program traverses the administered object hierarchy to discover the run state of a deployed message flow. Note that the program assumes that message flow MF1 is deployed to EG1 on broker B1, although it is possible to substitute these values in the code for any that are valid in the domain.
import com.ibm.broker.config.proxy.*;

public class GetMessageFlowRunState {

  public static void main(String[] args) {
        
    ConfigManagerProxy cmp = null;
    try {
      ConfigManagerConnectionParameters cmcp =
         new MQConfigManagerConnectionParameters(
           "localhost",
           1414,
           "");
      cmp = ConfigManagerProxy.getInstance(cmcp);   
    } catch (ConfigManagerProxyException cmpex) {
      System.out.println("Error connecting: "+cmpex);
    }
        
    if (cmp != null) {
      System.out.println("Connected to Config Manager!");
      displayMessageFlowRunState(cmp, "B1", "EG1", "MF1");
      cmp.disconnect();
    }      
  }

  private static void displayMessageFlowRunState(
                                 ConfigManagerProxy cmp,
                                 String brokerName,
                                 String egName,
                                 String flowName) {
    try {
      TopologyProxy topology = cmp.getTopology();
            
      if (topology != null) {
        BrokerProxy b = topology.getBrokerByName(brokerName);

        if (b != null) {
          ExecutionGroupProxy eg =
            b.getExecutionGroupByName(egName);

          if (eg != null) {
            MessageFlowProxy mf = 
              eg.getMessageFlowByName(flowName);

            if (mf != null) {
              boolean isRunning = mf.isRunning();
              System.out.print("Flow "+flowName+" on " + 
                egName+" on "+brokerName+" is ");

              if (isRunning) {
                System.out.println("running");
              } else {
                System.out.println("stopped");
              }
            } else {
              System.err.println("No such flow "+flowName);
            }
          } else {
            System.err.println("No such exegrp "+egName+"!");
          }
        } else {
          System.err.println("No such broker "+brokerName);
        }
      } else {
        System.err.println("Topology not available!");
      }
    } catch(ConfigManagerProxyPropertyNotInitializedException
                                                      ex) {
      System.err.println("Comms problem! "+ex);
    }
  }
}
The method that does most of the work is displayMessageFlowRunState(). This method takes the valid ConfigManagerProxy handle gained previously and discovers the run-state of the message flow as follows:
  1. The ConfigManagerProxy instance is used to gain a handle to the TopologyProxy. As there is only ever one topology per Configuration Manager, the getTopology() method does not need qualifying with an identifier.
  2. If a valid topology is returned, the TopologyProxy instance is used to gain a handle to its BrokerProxy object with the name described by the string brokerName.
  3. If a valid broker is returned, the BrokerProxy instance is used to gain a handle to its ExecutionGroupProxy object with the name described by the string egName.
  4. If a valid execution group is returned, the ExecutionGroupProxy instance is used to gain a handle to its MessageFlowProxy object with the name described by the string flowName.
  5. If a valid message flow is returned, the run-state of the MessageFlowProxy object is queried and the result is displayed.
It is not necessary to know the names of objects that you intend to manipulate. Each administered object contains methods to return sets of objects that it logically owns. The following example demonstrates this by looking up the names of all brokers within the domain:
import java.util.Enumeration;
import com.ibm.broker.config.proxy.*;

public class DisplayBrokerNames {

  public static void main(String[] args) {
        
    ConfigManagerProxy cmp = null;
    try {
      ConfigManagerConnectionParameters cmcp =
         new MQConfigManagerConnectionParameters(
           "localhost",
           1414,
           "");
      cmp = ConfigManagerProxy.getInstance(cmcp);   
    } catch (ConfigManagerProxyException cmpex) {
      System.out.println("Error connecting: "+cmpex);
    }
        
    if (cmp != null) {
      System.out.println("Connected to Config Manager!");
      displayBrokerNames(cmp);
      cmp.disconnect();
    }
  }

  private static void displayBrokerNames(ConfigManagerProxy cmp)
  {
    try {
      TopologyProxy topology = cmp.getTopology();
            
      if (topology != null) {
        Enumeration allBrokers = topology.getBrokers(null);
        
        while (allBrokers.hasMoreElements()) {
          BrokerProxy thisBroker =
            (BrokerProxy) allBrokers.nextElement();
          System.out.println("Broker "+thisBroker.getName());
        }
      }
    } catch(ConfigManagerProxyPropertyNotInitializedException
                                                      ex) {
        System.err.println("Comms problem! "+ex);
    }
  }
}
The key method is TopologyProxy.getBrokers(Properties). When supplied with a null argument, it returns an Enumeration of all the BrokerProxy objects in the domain. The program uses this method to look at each BrokerProxy in turn and display its name.

The Properties argument of TopologyProxy.getBrokers(Properties) can be used to exactly specify the characteristics of the brokers that are sought. It is possible to do this for nearly all of the methods that return administered objects, and is a powerful way of filtering those objects with which the program needs to work.

Examples of those characteristics that can be used to filter object look ups are the run-state and short description, as well as more obvious properties such as the name and UUID. In order to write logic to achieve this, it is necessary for you to understand how each administered object stores its information.

The properties of each administered object are stored locally inside the object using a hash table, where each property is represented as a {key, value} tuple. Each key is the name of an attribute (for example, name) and each value is the value (for example, BROKER1).

Each key name must be expressed using a constant from the AttributeConstants class (com.ibm.broker.config.proxy). A complete set of keys and possible values for each administered object is described in the Java documentation for the AttributesConstant class, or by using the Show raw property table for this object function in the Configuration Manager Proxy API Exerciser sample program. The latter displays the complete list of {key, value} pairs for each administered object.

The Properties argument supplied to the look up methods is a set of those {key, value} pairs that must exist in each administered object in the returned enumeration. To demonstrate this, consider the following code fragment:
Properties p = new Properties();
        
p.setProperty(AttributeConstants.OBJECT_RUNSTATE_PROPERTY,
              AttributeConstants.OBJECT_RUNSTATE_RUNNING);

Enumeration e = executionGroup.getMessageFlows(p);
Providing that the variable executionGroup is a valid ExecutionGroupProxy object, the returned enumeration only contains running message flows (OBJECT_RUN_STATE_PROPERTY equal to OBJECT_RUNSTATE_RUNNING).
When property filtering is applied to a method that returns a single administered object rather than an enumeration of objects, only the first result is returned (which is non deterministic if more than one match applies). This means that:
Properties p = new Properties();

p.setProperty(AttributeConstants.NAME_PROPERTY,
              "shares");

TopicProxy t = topicProxy.getTopic(p);
is an alternative to:
TopicProxy t = topicProxy.getTopicByName("shares");

If multiple {key, value} pairs are added to a property filter, all properties must be present in the child object in order for an object to match. It is not possible to perform a logical OR, or a logical NOT, on a filter without writing specific application code to do this.

When AdministeredObjects are first instantiated in an application, the CMP asks the Configuration Manager for the current set of properties for that object. This happens asynchronously, which means that the first time a property is requested there may be a pause while the CMP waits for the information to be supplied by the Configuration Manager. If the information does not arrive within a certain time (for example, if the Configuration Manager is not running), a ConfigManagerProxyPropertyNotInitializedException is thrown. The maximum time that the CMP waits is determined by the ConfigManagerProxy.setRetryCharacteristics() method.

Related tasks
Configuring an environment for developing and running Configuration Manager Proxy applications
Connecting to a Configuration Manager using the Configuration Manager Proxy
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:29:00

ae33040_ This topic's URL is: