Navigating integration node and integration node resources in a custom integration application

The IBM Integration API also handles deployed message sets; these resources are handled as attributes of deployed integration servers.

Collectively known as administered objects, these objects provide most of the interface to the integration node, and are therefore fundamental to an understanding of the IBM Integration API.

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 an integration node 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. Activity Logs are 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 Viewing Activity Logs by using a custom integration application.

You can use the AdminQueueProxy object to examine what items of work are in progress or are waiting for processing by the integration node. The following code shows how you can access the queue:

BrokerConnectionParameters bcp =
		new IntegrationNodeConnectionParameters("localhost", 4414);
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 integration node 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 integration node logically own integration servers, to gain a handle to integration server EG1 running on integration node 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 integration node B1, the application can call methods that cause the integration node 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 integration node 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 integration node directly, or indirectly.

The integration node directly owns the integration servers, therefore applications can call a method on the BrokerProxy object to gain a handle to the ExecutionGroupProxy objects. Similarly, the integration server logically contains the set of all message flows, therefore the application can call methods on the ExecutionGroupProxy object to access the MessageFlowProxy objects.

The hierarchy of these access relationships is shown in the following diagram.

Each object with an asterisk after its name inherits from the DeployedObjectGroupProxy class, and therefore has further child objects as shown in the following diagram.

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 integration node B1; you can substitute these values in the code for other values that are valid in the integration node.

import com.ibm.broker.config.proxy.*;

public class GetMessageFlowRunState {

  public static void main(String[] args) {
        
    BrokerProxy b = null;
    try {
      BrokerConnectionParameters bcp =
         new IntegrationNodeConnectionParameters(
           "localhost",
           4414);
      b = BrokerProxy.getInstance(bcp);   
    } catch (ConfigManagerProxyException cmpex) {
      System.out.println("Error connecting: "+cmpex);
    }
        
    if (b != null) {
      System.out.println("Connected to integration node!");
      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 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 integration servers within the integration node.

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 IntegrationNodeConnectionParameters(
           "localhost",
           4414);
      b = BrokerProxy.getInstance(bcp);   
    } catch (ConfigManagerProxyException cmpex) {
      System.out.println("Error connecting: "+cmpex);
    }
        
    if (b != null) {
      System.out.println("Connected to integration node!");
      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 integration node. 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 integration servers 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, INODE1).

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 IBM Integration 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);

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 IBM Integration API asks the integration node for the current set of properties for that object. This action happens asynchronously, therefore the first time a property is requested, the IBM Integration API might pause while it waits for the information to be supplied by the integration node. If the information does not arrive within a certain time (for example, if the integration node is not running), a ConfigManagerProxyPropertyNotInitializedException is thrown. Your application can control the maximum time that the IBM Integration API waits by using the BrokerProxy.setRetryCharacteristics() method.