See information about the latest product version
Navigating brokers and broker resources in a CMP application
Explore the status and attributes of the broker that your CMP application is connected to, and discover information about its resources.
Before you start
Before starting this step, you must have completed Connecting to a broker from a CMP application.
- Brokers
- Execution groups
- Deployed message flows
- Administration logs
- Activity logs
- Data capture stores
The CMP also handles deployed message sets; these resources are handled as attributes of deployed execution groups.
Collectively known as administered objects, these objects provide most of the interface to the broker, and are therefore fundamental to an understanding of the CMP.
Java class | Class function |
---|---|
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 WebSphere® Message Broker Toolkit. |
LogProxy | Represents the log of recent administrative activity on the broker, for all users. |
ActivityLogProxy | Represents a log of recent message flow and resource activity. |
DataCaptureProxy | Represents data that is held in a broker data store. Retrieved data is contained in DataCaptureEntry objects. |
The LogProxy object includes messages, created as LogEntry objects, that record recent changes made to the administered objects. These messages include the following information:
- Administration requests; for example, a request to deploy a BAR file
- Results of administration requests
- Changes that have been made to objects; for example, a change to a property value through an administration task
- Changes that have been made to objects as a result of starting a broker at a new fix pack level or version.
The ActivityLogProxy object includes messages, created as ActivityLogEntry objects, that record recent high-level activities involving message flows and their interactions with external resources. For more information about these messages, see Using Activity logs. An Activity log is generated for message flows and for specific resource types.
You can retrieve an ActivityLogProxy object for a message flow from a MessageFlowProxy object. To get an ActivityLogProxy object for a resource type, use the ResourceManagerProxy object. Invoke the method getActivityLog() on the MessageFlowProxy object or the ResourceManagerProxy object. For further information, see Working with Activity logs in a CMP application.
You can use the AdminQueueProxy object to examine what items of work are in progress or are waiting for processing by the broker. The following code shows how you can access the queue:
BrokerConnectionParameters bcp =
new MQBrokerConnectionParameters("localhost", 1414, "QMGR");
BrokerProxy b = BrokerProxy.getInstance(bcp);
AdminQueueProxy l = b.getAdministrationQueue();
A set of public methods is available for each administered object, which applications can use to inquire and manipulate properties of the underlying broker to which the instance refers. To access an administered object through its API, your application must first request a handle to that object from the object that logically owns it.
For example, because brokers logically own execution groups, to gain a handle to execution group EG1 running on broker B1, the application must ask the BrokerProxy object represented by B1 for a handle to the ExecutionGroupProxy object represented by EG1.
On a BrokerProxy object that refers to broker B1, the application can call methods that cause the broker to reveal its run-state, or cause it to start all its message flows. You can write applications to track the changes that are made to the broker objects by reading the messages maintained as LogEntry objects.
In the following example, a handle is requested to the BrokerProxy object. The BrokerProxy is logically the root of the administered object tree, therefore your application can access all other objects in the broker directly, or indirectly.
The broker directly owns the execution groups, therefore applications can call a method on the BrokerProxy object to gain a handle to the ExecutionGroupProxy objects. Similarly, the execution group logically contains the set of all message flows, therefore the application can call methods on the ExecutionGroupProxy object to access the MessageFlowProxy objects.


The following application traverses the administered object hierarchy to discover the run-state of a deployed message flow. The application assumes that message flow MF1 is deployed to EG1 on broker B1; you can substitute these values in the code for other values that are valid in the broker.
import com.ibm.broker.config.proxy.*;
public class GetMessageFlowRunState {
public static void main(String[] args) {
BrokerProxy b = null;
try {
BrokerConnectionParameters bcp =
new MQBrokerConnectionParameters(
"localhost",
1414,
"");
b = BrokerProxy.getInstance(bcp);
} catch (ConfigManagerProxyException cmpex) {
System.out.println("Error connecting: "+cmpex);
}
if (b != null) {
System.out.println("Connected to broker!");
displayMessageFlowRunState(b, "EG1", "MF1");
b.disconnect();
}
}
private static void displayMessageFlowRunState(
BrokerProxy b,
String egName,
String flowName) {
try {
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 "+b.getName()+" 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+"!");
}
} catch(ConfigManagerProxyPropertyNotInitializedException
ex) {
System.err.println("Comms problem! "+ex);
}
}
}
- The BrokerProxy instance is used to gain a handle to the ExecutionGroupProxy object with the name described by the string egName
- If a valid execution group is returned, the ExecutionGroupProxy instance is used to gain a handle to the MessageFlowProxy object with the name described by the string flowName.
- If a valid message flow is returned, the run-state of the MessageFlowProxy object is queried, and the result is displayed.
The application does not have to know the names of objects that it can manipulate. Each administered object contains methods to return sets of objects that it logically owns. The following example demonstrates this technique by looking up the names of all execution groups within the broker.
import java.util.Enumeration;
import com.ibm.broker.config.proxy.*;
public class DisplayExecutionGroupNames {
public static void main(String[] args) {
BrokerProxy b = null;
try {
BrokerConnectionParameters bcp =
new MQBrokerConnectionParameters(
"localhost",
1414,
"");
b = BrokerProxy.getInstance(bcp);
} catch (ConfigManagerProxyException cmpex) {
System.out.println("Error connecting: "+cmpex);
}
if (b != null) {
System.out.println("Connected to broker!");
displayExecutionGroupNames(b);
b.disconnect();
}
}
private static void displayExecutionGroupNames(BrokerProxy b)
{
try {
Enumeration<ExecutionGroupProxy> allEGs = b.getExecutionGroups(null);
while (allEGs.hasMoreElements()) {
ExecutionGroupProxy thisEG =
allEGs.nextElement();
System.out.println("Found EG: "+thisEG.getName());
}
} catch(ConfigManagerProxyPropertyNotInitializedException
ex) {
System.err.println("Comms problem! "+ex);
}
}
}
The key method is BrokerProxy.getExecutionGroups(Properties). When supplied with a null argument, this method returns an enumeration of all the ExecutionGroupProxy objects in the broker. The application uses this method to look at each ExecutionGroupProxy in turn, and display its name.
The Properties argument of the method BrokerProxy.getExecutionGroups(Properties) can be used to exactly specify the characteristics of the execution groups that are sought. The application can use this argument for nearly all the methods that return administered objects, and is a powerful way of filtering those objects with which the application needs to work.
Examples of the characteristics that can be used to filter object lookups are the run-state and short description, as well as more obvious properties such as the name and UUID. To write logic to achieve filtered lookups, you must understand how each administered object stores its information.
The properties of each administered object are stored locally inside the object by 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 by 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 CMP API Exerciser sample application. The latter displays the complete list of {key, value} pairs for each administered object.
The Properties argument that is supplied to the lookup methods is a set of those {key, value} pairs that must exist in each administered object in the returned enumeration. Consider the following code fragment:
Properties p = new Properties();
p.setProperty(AttributeConstants.OBJECT_RUNSTATE_PROPERTY,
AttributeConstants.OBJECT_RUNSTATE_RUNNING);
Enumeration<MessageFlowProxy> mf = executionGroup.getMessageFlows(p);
Providing that the variable executionGroup is a valid ExecutionGroupProxy object, the returned enumeration contains only active message flows (that is, OBJECT_RUN_STATE_PROPERTY equal to OBJECT_RUNSTATE_RUNNING).
Properties p = new Properties();
p.setProperty(AttributeConstants.NAME_PROPERTY,
"EG1");
ExecutionGroupProxy eg1 = brokerProxy.getExecutionGroup(p);
is
an alternative to the following statement:ExecutionGroupProxy eg1 = brokerProxy.getTopicByName("EG1");
If multiple {key, value} pairs are added to a property filter, all properties must be present in the child object for an object to match. If you want a method to perform a logical OR, or a logical NOT, on a filter, you must write specific application code for this purpose.
When AdministeredObjects are first instantiated in an application, the CMP API asks the broker for the current set of properties for that object. This action happens asynchronously, therefore the first time a property is requested, the CMP API might pause while it waits for the information to be supplied by the broker. If the information does not arrive within a certain time (for example, if the broker is not running), a ConfigManagerProxyPropertyNotInitializedException is thrown. Your application can control the maximum time that the CMP API waits by using the BrokerProxy.setRetryCharacteristics() method.