Connecting to an integration node from a custom integration application

Connect an application that uses the IBM® Integration API to an integration node, to send requests about its status and its resources.

Before you begin

You must complete the steps in Configuring an environment for developing and running custom integration applications.

About this task

Review the following example application, BrokerRunStateChecker.java, which demonstrates how to use the IBM Integration API classes:

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

public class BrokerRunStateChecker {    
 
    public static void main(String[] args) {          	    	
            // The IP address of where the integration node is running
  	   // and the web administration port number of the integration node.
        displayBrokerRunState("localhost", 4414);   
    }     

	public static void displayBrokerRunState(String hostname, int port) {        

        BrokerProxy b= null;
        try {            
            BrokerConnectionParameters bcp =  
				new IntegrationNodeConnectionParameters(hostname, 4414);
            b = BrokerProxy.getInstance(bcp);           
            String brokerName = b.getName();           
                      
            System.out.println("Integration node '"+brokerName+               
                "' is available!");           
            b.disconnect();        
		} catch (ConfigManagerProxyException ex) {           
            System.out.println("Integration node is NOT available"+               
                " because "+ex);       
        }   
    }
}

This example application connects to a remote integration node.

Review each part of the application that uses the IBM Integration API to understand what is required to connect to an integration node. Use the following steps to assist you in creating your own custom integration applications.

Procedure

Import the com.ibm.broker.config.proxy package, which contains the IBM Integration API Java™ classes.
This action is in the first line of the application:
```
import com.ibm.broker.config.proxy.*; 
```

The first line of code inside the try block of the displayBrokerRunState() method instantiates a BrokerConnectionParameters object. BrokerConnectionParameters is an interface that states that implementing classes are able to provide the parameters to connect to an integration node.

The IntegrationNodeConnectionParameters class implements this interface by defining a set of HTTP connection parameters. The constructor that is used in the program has two required parameters:

The host name of the computer that the integration node is running on.
The web administration port (the default is 4414). For more information about port numbers for an integration node, see Configuring the IBM Integration Bus web user interface.

If you have administration security enabled, use constructors for the user name and password. For example:

BrokerConnectionParameters bcp =  
                          new IntegrationNodeConnectionParameters(hostname, 4414, "user", "password");

For any existing compiled integration (CMP) applications that were created and compiled before IBM Integration Bus Version 10.0, you can apply the user name and password in one of the following ways:

In the Java VM, use the following parameters:
```
-DMQSI_CMP_USERNAME=username -DMQSI_CMP_PASSWORD=password
```
Replace username with the user name, and password with its associated password.
In the system environment, use the following variables:
```
MQSI_CMP_USERNAME, MQSI_CMP_PASSWORD
```
Create or use an existing .broker file and add the XML property userName, and then supply the password in an integration application or command. The following example shows how to connect to an integration node with a .broker file:
```
String filename = "C:\\my.broker";
IntegrationNodeConnectionParameters bcp = new IntegrationNodeConnectionParameters(filename);
```
For more information about how to create a .broker file, see Connecting to an integration node by creating a .broker file.

If your web administration listener is using SSL, specify true in the IntegrationNodeConnectionParameters. For example:

BrokerConnectionParameters bcp =  
                          new IntegrationNodeConnectionParameters(hostname, 4414, "user", "password", true);

This SSL constructor uses the JVM trust store; however, you can supply the location of an alternative trust store by using a .broker file. For more information, see Connecting to an integration node by creating a .broker file.

In this example application, the connection is remote. If you are using a local integration node, and the web administration port is not enabled, use the following code for a local connection (where IBNODE represents the name of the integration node):

b = BrokerProxy.getLocalInstance("IBNODE");

Enter the static getInstance() factory method inside the try block.
When a valid handle to the queue manager is returned, the application requests the name of the integration node by using the b.getName() method, and displays it.

getName(), and other methods that request information from the integration node, cause a block until the information is supplied, or a timeout occurs. Therefore, if the integration node is not running, the application hangs for a period. You can control the timeout period by using the BrokerProxy.setRetryCharacteristics() method. Typically, blocking occurs only when a resource is accessed for the first time within an application.

Define the BrokerConnectionParameters object. You can then connect to the integration node that is defined by the settings for the object.
Finally, enter the disconnect() method. This method frees up resources that are associated with the connection in both the custom integration application and the integration node.

Results

You can create a custom integration application that can connect to an integration node.

When a BrokerProxy handle is first returned from the getInstance() method, the integration node service does not have to be running. It is only when the application uses the handle (by calling the getName() method in this example) that the application can be assured that a two-way connection with the integration node is active.