Issuing synchronous callout requests from a Java dependent region

IMS provides support for synchronous callout functionality from Java™ message processing (JMP) or Java batch processing (JBP) applications through an IMS implementation of the Java Message Service (JMS).

To use the JMP and JBP support for synchronous callout, the JMS API (jms.jar) file must be on your classpath. The JMS API is included in the Java SDK. Alternatively, you can order IMS Enterprise Suite V3.2, which includes the JMS API.

The IMS implementation of JMS is limited to supporting the Point-to-Point (PTP) messaging domain only. In addition, support is only provided for non-transacted QueueSession objects with Session.AUTO_ACKNOWLEDGE mode.

If the JMP or JBP application attempts to call any JMS method not supported by IMS or pass any unsupported argument to JMS method calls, a JMSException exception is thrown.

To send a message using the JMP and JBP support for synchronous callout and synchronously receive a response:

  1. Create a com.ibm.ims.jms.IMSQueueConnectionFactory object.
  2. Create a JMS QueueConnection instance by calling the createQueueConnection method on the IMSQueueConnectionFactory object.
  3. Create a JMS QueueSession instance by calling the createQueueSession method on the QueueConnection instance.
    In the method call, you must set the input parameter values to false and Session.AUTO_ACKNOWLEDGE to specify that the generated QueueSession instance is non-transacted and runs in AUTO_ACKNOWLEDGE mode.
  4. Create a queue identity by calling the createQueue method on the QueueSession instance.
    In the method call, you must set the input parameter value to the OTMA descriptor name for the synchronous callout operation.
  5. Create a JMS QueueRequestor instance and pass in the QueueSession instance from step 3 and the Queue instance from step 4 as input parameters to the QueueRequestor constructor method.
  6. Create a TextMessage instance by calling the createTextMessage method on the QueueSession instance from step 3.
    Set the string containing the message data.
  7. To send the message and retrieve a response, call the request method on the QueueRequestor object from step 5.
    In the method call, pass in the TextMessage instance from step 6. You need to cast the return value from the request method call to a TextMessage instance. If the call is successful, the return value is the response to the synchronous callout request.
The following code shows how to write a simple JMP or JBP application that sends a message to an external application and synchronously receive a response message. In the example, an IMSQueueConnectionFactory instance is created with a timeout value of 10 seconds and with 128 KB of space allocated to hold response messages.
import javax.jms.JMSException;
import javax.jms.Queue;
import javax.jms.QueueConnection;
import javax.jms.QueueRequestor;
import javax.jms.QueueSession;
import javax.jms.Session ;
import javax.jms.TextMessage;
import com.ibm.ims.jms.IMSQueueConnectionFactory;

public class IMS_Sample
{
    public static void main(String argv[])
    {
        IMSQueueConnectionFactory jmsConnectionFactory 
           = new IMSQueueConnectionFactory();
        QueueConnection jmsConnection = null;
        QueueSession jmsQueueSession = null;
        Queue jmsQueue = null;
        QueueRequestor jmsQueueRequestor = null;
        
        try {
            jmsConnectionFactory.setTimeout(1000); 
                          // set the timeout to 10 seconds
            jmsConnectionFactory.setResponseAreaLength(128000); 
                          // allocate 128k to hold the response message
            jmsConnection = jmsConnectionFactory.createQueueConnection();
            jmsQueueSession 
            = jmsConnection.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);
						// set session to be non-transacted and in AUTO_ACKNOWLEDGE mode
            jmsQueue = jmsQueueSession.createQueue("OTMDEST1"); 
						// pass in the OTMA descriptor name
            
            jmsQueueRequestor 
               = new QueueRequestor(jmsQueueSession, jmsQueue);
            TextMessage sendMsg = jmsQueueSession.createTextMessage();
            sendMsg.setText("MyMessage");
            System.out.println("Sending message: "+sendMsg.getText());
            TextMessage replyMsg 
               = (TextMessage)jmsQueueRequestor.request(sendMsg);
            
            System.out.println("\nReceived message: "+replyMsg.getText());
        } catch (JMSException e) {
            e.printStackTrace();
        }
    }
}