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.

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 overriden 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.

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.

The zero.messaging.connection dependency includes (via zero.connection.jms) a type handler which can be used to access the contents of the response body without explicitly using the javax.jms.* API in the application code. See the zero.connection.jms developer's guide for more information about working with javax.jms.Message objects in the global context and with the Connection API.

`POST` operation

Request headers

Request headers will be included in the sent message as message properties.

Message properties beginning with the string "JMSX" are reserved for use by the provider and may 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 as `javax.jms.TextMessage`
`byte[]` or `InputStream`	Contents sent to destination as `javax.jms.BytesMessage`
`Serializable`	Contents sent to destination as `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 PUT operation it will be modified before transmission.

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:

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)
`priority`	`POST`	Message priority, in the range `0` (low) to `9` (high), inclusive. High priority messages will tend to be delivered before low priority messages.	`4`
`storeAndForward`	`POST`	`true` to use store-and-forward logic in home broker to send message. `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 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 the zero.messaging.broker developer's guide 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.

The reuseSession option may only be used when connecting to the broker, for which the session was originally connected. For example, if you wish 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.

Using messaging with the Connection API

Overview

Protocol summary

Request and response format

GET operation

Request headers

Request body

Response headers

Response body

POST operation

Request headers

Request body

Response headers

Response body

Configuration

connectionConfig

storeAndForward

reuseSession

Using messaging with the `Connection` API

`GET` operation

`POST` operation

`connectionConfig`

`storeAndForward`

`reuseSession`