Messaging System Filter


A messaging system is a loosely coupled, peer-to-peer facility where clients can send messages to, and receive messages from any other client. In a messaging system, a client sends a message to a messaging agent. The recipient of the message can then connect to the same agent and read the message. However, the sender and recipient of the message do not need to be available at the same time to communicate (for example, unlike HTTP). The sender and recipient need only know the name and address of the messaging agent to talk to.

The Java Messaging System (JMS) is an implementation of such a messaging system. It provides an API for creating, sending, receiving, and reading messages. Java-based applications can use it to connect to other messaging system implementations. A JMS provider can deliver messages synchronously or asynchronously, which means that the client can fire and forget messages or wait for a response before resuming processing. Furthermore, the JMS API ensures different levels of reliability in terms of message delivery. For example, it can ensure that the message is delivered once and only once, or at least once.

The API Gateway uses the JMS API to connect to other messaging systems that expose a JMS interface. For example, these include Oracle WebLogic Server, IBM MQSeries, JBoss Messaging, TIBCO EMS, IBM WebSphere Server, and Progress SonicMQ.

[Important] Important

You must add the JMS provider JAR files to the API Gateway classpath for this filter to function correctly. If the provider's implementation is platform-specific, copy the provider JAR files to the INSTALL_DIR/ext/PLATFORM folder, where INSTALL_DIR points to the root of your product installation, and PLATFORM is the platform on which the API Gateway is installed (Win32, Linux.i386, or SunOS.sun4u-32). If the provider implementation is platform-independent, you can place the JAR files in INSTALL_DIR/ext/lib.

Request Settings

The Request tab specifies properties of the request to the messaging system. You can configure the following fields:

JMS Service:

Click the button next to this field, and select an existing JMS service in the tree. To add a JMS Service, right-click the JMS Services tree node, and select Add a JMS Service. Alternatively, you can configure JMS services under the External Connections node in the Policy Studio tree. For more details, see the Messaging System topic.


Enter the name of the JMS queue or topic that you want to drop messages on to.

Delivery Mode:

The API Gateway supports persistent and non-persistent delivery modes:

  • Persistent:

    Instructs the JMS provider to ensure that a message is not lost in transit if the JMS provider fails. A message sent with this delivery mode is logged to persistent storage when it is sent.

  • Non-persistent:

    Does not require the JMS provider to store the message. With this mode, the message may be lost if the JMS provider fails.

Priority Level:

You can use message priority levels to instruct the JMS provider to deliver urgent messages first. The ten levels of priority range from 0 (lowest) to 9 (highest). If you do not specify a priority level, the default level is 4. A JMS provider tries to deliver higher priority messages before lower priority ones but does not have to deliver messages in exact order of priority.

Time to Live:

By default, a message never expires. However, if a message becomes obsolete after a certain period, you may want to set an expiration time (in milliseconds). If the specified time to live value is 0, the message never expires.

Message ID:

Enter an identifier to be used as the unique identifier for the message. By default, the unique identifier is the ID assigned to the message by the API Gateway (${id}). However, you can use a proprietary correlation system, perhaps using MIME message IDs instead of API Gateway message IDs.

Correlation ID:

Enter an identifier for the message that the API Gateway uses to correlate response messages with the corresponding request messages. Usually, if ${id} is specified in the Message ID field above, it is also used here to correlate request messages with their correct response messages.

Message Type:

This drop-down list enables you to specify the type of data to be serialized and sent in the JMS message to the JMS provider. The option selected depends on what part of the message you want to send to the consumer. For example, if you want to send the message body, select the option to format the body according to the rules defined in the SOAP over JMS recommendation. Alternatively, if you wanted to serialize a list of name-value pairs to the JMS message, choose the option to create a MapMessage.

The following list describes the various serialization options available:

  • Use content.body attribute to create a message in the format specified in the SOAP over Java Messaging Service recommendation:

    If this option is selected, messages are formatted according to the SOAP over JMS recommendation. This is the default option because, in most cases, the message body is to be routed to the messaging system. If this option is selected, a javax.jms.BytesMessage is created and a JMS property containing the content type (text/xml) is set on the message.

  • Create a MapMessage from the java.lang.Map in the attribute named below:

    Select this option to create a javax.jms.MapMessage from the API Gateway message attribute named below that consists of name-value pairs.

  • Create a BytesMessage from the attribute named below:

    Select this option to create a javax.jms.BytesMessage from the API Gateway message attribute named below.

  • Create an ObjectMessage from the java.lang.Serializable in the attribute named below:

    Select this option to create a javax.jms.ObjectMessage from the API Gateway message attribute named below.

  • Create a TextMessage from the attribute named below:

    Select this option to create a javax.jms.TextMessage from the message attribute named below.

  • Use the javax.jms.Message stored in the attribute named below:

    If a javax.jms.Message has already been stored in a message attribute, select this option, and enter the name of the attribute in the field below.

Attribute Name:

Enter the name of the API Gateway message attribute that holds the data that is to be serialized to a JMS message and sent over the wire to the JMS provider. The type of the attribute named here must correspond to that selected in the Message Type drop-down field above.

Use Shared JMS Session:

By default, each running instance of a Messaging System filter creates its own session (using its own thread) with the JMS provider. You can select this option to force all running instances of this filter to share the same JMS session (using a common shared thread) to the JMS provider. Reusing a shared session across multiple filter instances in this manner may result in performance degradation as each connection to the provider using the session blocks until the response (if any) is received.

Custom Message Properties:

You can set custom properties for messages in addition to those provided by the header fields. Custom properties may be required to provide compatibility with other messaging systems. You can use message attribute selectors as property values. For example, you can create a property called AuthNUser, and set its value to ${}. Other applications can then filter on this property (for example, only consume messages where AuthNUser equals admin). To add a new property, click Add, and enter a name and value in the fields provided on the Properties dialog.

Use the following policy to change JMS request message:

This setting enables you to customize the JMS message before it is published to a JMS queue or topic. Click the browse button on the right, and select a configured policy in the dialog. The selected policy is then invoked before the JMS request is sent to the queuing system.

When the selected policy is invoked, the JMS request message is available on the white board in the jms.outbound.message message attribute. You can therefore call JMS API methods to manipulate the JMS request further. For example, you could configure a policy containing a Scripting Language filter that runs a script such as the following against the JMS message:

function invoke(msg) {
 var jmsMsg = msg.get("jms.outbound.message");
 jmsMsg.setIntProperty("My_JMS_Report", 123);
 return true;

Response Settings

The Response tab specifies whether the API Gateway uses asynchronous or synchronous communication when talking to the messaging system. For example, if you want the API Gateway to use asynchronous communication, you can select the Do not set response option. If synchronous communication is required, you can select to read the response from a temporary queue or from a named queue or topic.

You can also specify whether the API Gateway waits on a response message from a queue or topic from the messaging system. The API Gateway sets the JMSReplyTo property on each message that it sends. The value of the JMSReplyTo property is the temporary queue, queue, or topic selected in this dialog. It is the responsibility of the application that consumes the message from the queue (JMS Consumer) to send the message back to the destination specified in JMSReplyTo.

The API Gateway sets the JMSCorrelationID property to the value of the Correlation ID field on the Request tab to correlate requests messages to their corresponding response messages. If you select to use a temporary queue or temporary topic, this is created when the API Gateway starts up.

Wait for response:

Select whether the API Gateway waits to receive a response:

  • No wait:

    The API Gateway does not wait to receive a response.

  • Wait with timeout (ms):

    The API Gateway waits a specific time period to receive a response before it times out. If the API Gateway times out waiting for a response, the Messaging System filter fails. Enter the timeout value in milliseconds. The default value of 0 means there is no timeout, and the API Gateway waits for a response indefinitely.

Set where response is to be sent:

Select where the response message is to be placed using one of the following options:

  • Do not set response:

    Select this option if you do not expect or do not care about receiving a response from the JMS provider.

  • Use temporary queue:

    Select this option to instruct the JMS provider to place the response message on a temporary queue. In this case, the temporary queue is created when the API Gateway starts up. Only the API Gateway can read from the temporary queue, but any application can write to it. The API Gateway uses the value of the JMSReplyTo header to indicate the location where reads responses from.

  • Use named queue or topic:

    If you want the JMS provider to place response messages on a named queue or topic, select this option, and enter the name of the queue or topic in the text box.

Selector for response:

The expression entered specifies the messages that the consumer is interested in receiving. By using a selector, the task of filtering the messages is performed by the JMS provider instead of by the consumer. The selector is a string that specifies an expression whose syntax is based on the SQL92 conditional expression syntax. The API Gateway instance only receives messages whose headers and properties match the selector.

[Important] Important

The JMS Consumer automatically returns the results of the invoked policy to the JMS destination specified in the JMSReplyTo header of the request. This means that you do not need to send a reply using the Messaging System filter.

If the incoming JMS message contains a JMSReplyTo header (a queue or topic that expects a response), when the policy invoked by the JMS Consumer completes, the API Gateway sends a message to the JMSReplyTo source using the reverse of the mechanism that it used to read from the queue. For example, if the consumer reads the JMS message and populates an attribute with a value inferred from the message type to Java (for example, from TextMessage to String), when the policy completes, the consumer looks up this attribute, and infers the JMS response message type based on the object type stored in the message.