Using messaging with the Connection API

Overview

The zero.messaging.connection dependency provides a protocol implementation that can be used with the Connection API to send and receive messages using the IBM® Reliable Transport Extension for WebSphere® sMash.

For example, the following code sample first sends a message to a queue and then synchronously reads a message from the queue:

try {

    // Send a message
    Connection.doPOST("myQueue", "This is my message");
    
    // Wait for and read message
    System.out.println(Connection.doGET("myQueue").getResponseBodyAsString());
    
} catch (ConnectionException e) {

    // Process exception
    if (e.getCause() instanceof JMSException) {
        // Caught a messaging exception
    } else {
        // Other exception
    }
    
} catch (IOException e) {

    // Other exception
    
}

In order for the previous code sample to operate correctly the application configuration will need configuration similar to the following. The first stanza describes the myQueue connection destination and maps it to the messaging queue, myQueue, using the broker connection, myBroker. The second stanza describes the configuration that the application should used to connect to the broker.

/config/connection/destinations += {
  "myQueue" : {
    "connection" : {
      "protocol" : "messaging",
      "config" : {
        "connectionConfig" : "myBroker",
        "queue" : "myQueue"
      }
    }
  }
}

/config/connection/messaging/myBroker = {
  "hostname" : "localhost",
  "port" : 9091
}

The remainder of this topic describes the messaging protocol and the operation and parameters it supports in more detail. For more information on using the Connection API, see the zero.core developer's guide.

Protocol summary

Name

messaging

Description

Sends and receives messages to and from messaging destinations.

Resource name

Can contain the target queue name or can be overridden using queue protocol configuration parameter.

Operations

GET - receive message from queue, if one is available.

POST - send message to queue.

Request and response format

GET operation

Request headers

No request headers.

Request body

No request body.

Response headers

The message properties of the received message.

Response body

The javax.jms.Message instance received. If the GET request times out before a message is available, the response body will be null.

POST operation

Request headers

Request headers are included with the message as properties. If a request header has multiple values, the values are set in the order provided and the final value will be the one that is transmitted with the message.

Request body

Response headers

No response headers.

Response body

No response body.

Configuration

The application must include the zero.messaging.connection dependency to use the messaging protocol.

The following protocol configuration parameters can be applied to the connection request or destination using the protocol configuration mechanisms described in the zero.core developer's guide:

connectionConfig

The required connectionConfig parameter identifies the properties that will be used to connect to the messaging broker. The value names a broker connection configuration defined under /config/connection/messaging/ configName. For example, if the value of connectionConfig is set to myBroker then the broker connection configuration will be read from /config/connection/messaging/myBroker:

/config/connection/destinations += {
  "myQueue" : {
    "connection" : {
      "protocol" : "messaging",
      "config" : {
        "connectionConfig" : "myBroker",
        "queue" : "myQueue"
      }
    }
  }
}

/config/connection/messaging/myBroker = {
  "hostname" : "localhost",
  "port" : 9091
}

See Configuring connections to messaging brokers for more information.

storeAndForward

The storeAndForward option is only used for send and POST operations using a broker connection configuration that is not the application's home broker. The messaging protocol always uses direct connection to the target queue for all GET operations and for POST operations to the home broker.

/config/connection/destinations += {
  "myQueue" : {
    "connection" : {
      "protocol" : "messaging",
      "config" : {
        "connectionConfig" : "myBroker",
        "queue" : "myQueue",
        "storeAndForward" : true
      }
    }
  }
}

/config/connection/destinations += {
  "remoteQueue" : {
    "connection" : {
      "protocol" : "messaging",
      "config" : {
        "connectionConfig" : "remoteBroker",
        "queue" : "remoteQueue",
        "storeAndForward" : true
      }
    }
  }
}

/config/messaging/client/homeBroker = "myBroker"

/config/connection/messaging/myBroker = {
  "hostname" : "localhost",
  "port" : 9091
}

/config/connection/messaging/remoteBroker = {
  "hostname" : "localhost",
  "port" : 9092
}

For example, consider the above configuration:

• To POST to remoteQueue, the application will connect to the home broker, myBroker, and place the message on the store-and-forward queue, storeAndForward:remoteBroker/queue/remoteQueue.
• To GET from remoteQueue, the application will connect to the target broker, remoteBroker, and read the message from the target queue, remoteQueue. The storeAndForward setting is ignored for the GET operation.
• To POST to myQueue, the application will connect to the home broker, myBroker, and place the message on the target queue, myQueue. The storeAndForward setting is ignored for queues on the home broker.
• To GET to myQueue, the application will connect to the broker, myBroker, and read the message on the target queue, myQueue.

To use store-and-forward processing, the following conditions must be satisfied:

• The storeAndForward property of the messaging protocol must be set to true.
• The application making the POST request must have a home broker connection configuration. See Configuring connections to messaging brokers for more information about the home broker configuration.
• The home broker must have a suitable bridge connection configuration for the broker named by the connectionConfig property. See Configuring connections to messaging brokers for more information about the bridge connection configuration.

See Store-and-forward processing in multiple messaging broker topologies for more information about store-and-forward processing.

reuseSession

Under normal circumstances, each Connection request using the messaging protocol is carried out using a newly created messaging session. This session is committed for a single message POST or GET operation.

The reuseSession parameter offers an alternative approach that can be used when the Connection operation is being carried out in response to message event from the messaging receiver. If reuseSession is specified, the messaging protocol uses the messaging session created by the messaging receiver. In this case, the session will not be committed for a single POST or GET operation. Instead, the session will be committed by the messaging receiver, after the message event has completed succesfully. For example, reuseSession could be used to send a reply within the messaging transaction in which a message was received.

For more information about the messaging receiver, see Using the messaging kicker and receiver.