Using messaging with the Connection API

This topic describes the messaging protocol implementation, which allows an application to send and receive messages to and from messaging destinations using the Connection API.

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.

The messaging protocol is similar to the one provided by the "Protocol extension for JMS" (zero.connection.jms) for interoperation with an external Java™ Message Service (JMS) providers. Many of the concepts and capabilities are shared between the two protocols.

Example usage

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 zero.config file needs configuration similar to the following:

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

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

The first stanza describes the myQueue connection destination and maps it to the messaging queue, myQueue, using the broker connection, myBroker. For more information about configuring connection destinations, see the Developer's Guide topics about the connection infrastructure included in the zero.core module. The second stanza describes the configuration that the application must use to connect to the broker. For more information about configuring a connection to a messaging broker, see Configuring connections to messaging brokers

The remainder of this topic describes the messaging protocol and the operation and parameters it supports in more detail. For more information about using the Connection API, see the Developer's Guide topics about the connection infrastructure included in the zero.core module.

Request and response format

This section details the headers and body types for the requests and responses of the supported operations.

GET operation

The GET operation receives a message from a messaging queue, if one is available.

Request headers

No request headers.

Request body

No request body.

Response headers

The response headers of the GET operation contain the message properties of the received message, including the JMSMessageID value and JMSCorrelationID string, if present.

Response body

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

The zero.messaging.connection dependency automatically includes zero.connection.jms, which contains a type handler that enables the application to access the contents of the response body without explicitly using the javax.jms.* APIs. For more information about working with javax.jms.Message objects in the global context and with the Connection API, see the Developer's Guide topics about the protocol extension for JMS.

POST operation

The POST operation sends a message to a messaging queue.

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 is the one that is transmitted with the message.

Message properties beginning with the string "JMSX" are reserved for use by the provider and might not be included in the transmitted message.

Request body

Request body type Comments
javax.jms.Message Sent to destination after message properties are updated.
String or Reader Contents sent to destination contained in a javax.jms.TextMessage
byte[] or InputStream Contents sent to destination contained in a javax.jms.BytesMessage
Serializable Contents sent to destination contained in a javax.jms.ObjectMessage
Other types Converted to String using toString() and processed as above.

If an instance of javax.jms.Message is presented to the POST operation it is modified before transmission.

Response headers

The response headers of the POST operation contain the the JMSMessageID value and JMSCorrelationID string, if present, of the message that has been sent.

Response body

No response body.

Configuration

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

The zero.messaging.connection, zero.messaging.kicker and zero.messaging.receiver modules contain classes that are incompatible with the IBM WebSphere MQ classes for JMS, which are supplied with WebSphere MQ Version 7.0. To avoid compatiblity problems, a WebSphere sMash application that connects to both a messaging broker and a WebSphere MQ Version 7.0 queue manager must use the WebSphere MQ classes for JMS from the MQC6: WebSphere MQ V6.0 Clients SupportPac™.

The following protocol configuration parameters can be applied to the connection request or destination using the protocol configuration mechanisms described in the Developer's Guide topics about the connection infrastructure included in the zero.core module:

Parameter Operation Description Default
connectionConfig Any Broker connection configuration name. (Maximum 20 characters) Required.
queue Any Name of messaging queue for this operation. (Maximum 79 characters) Request target resource name.
userid Any User ID for authentication with the messaging broker. None set.
password Any Authentication password. (XOR strings are supported) None set.
timeout GET Message receive timeout, in milliseconds. 0 (wait indefinitely)
messageSelector GET JMS message selector expression for the MessageConsumer, for example JMSCorrelationID='ID:0123456789'. If supplied, only messages with headers that match the selector are received. Headers that do not match the selector are left on the queue. No message selector set.
priority POST Message priority, in the range 0 (low) to 9 (high), inclusive. Higher priority messages are normally delivered before lower priority messages. 4
storeAndForward POST true to use store-and-forward logic to send message using the home broker. false to connect directly to target broker. false
reuseSession Any true to use messaging receiver's session and transaction context when processing a message event. false to perform operation under independent session. false

connectionConfig

The required connectionConfig parameter identifies the properties to 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 is 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 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.

Consider the following example configuration:

/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
}

Using the this configuration, the application behaves as follows:

  • To POST to remoteQueue, the application connects to the home broker, myBroker, and places the message on the store-and-forward queue, storeAndForward:remoteBroker/queue/remoteQueue.
  • To GET from remoteQueue, the application connects to the target broker, remoteBroker, and reads the message from the target queue, remoteQueue. The storeAndForward setting is ignored for the GET operation.
  • To POST to myQueue, the application connects to the home broker, myBroker, and places the message on the target queue, myQueue. The storeAndForward setting is ignored for queues on the home broker.
  • To GET to myQueue, the application connects to the broker, myBroker, and reads 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 Considerations for store-and-forward scenarios 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 is not committed for a single POST or GET operation. Instead, the session is 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.

The reuseSession option can only be used when connecting to the home broker. To use reuseSession to send a message to a remote queue in response to a message receiver message event, you must also use store-and-forward processing.

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

Version 1.1.26825