TIBCO Enterprise Messaging System Routing Filter

Contents

Overview

TIBCO Enterprise Messaging System™ (EMS) provides a distributed message bus with native support for JMS (Java Messaging Service) and TIBCO Rendezvous, along with other protocols.

In general, TIBCO EMS clients produce messages and send them to the TIBCO EMS Server. Similarly, TIBCO EMS clients can connect to the TIBCO EMS Server and declare an interest in a particular queue or topic on that server. In doing so, it can consume messages that have been produced by another TIBCO EMS client.

The Enterprise Gateway can act as a message producer by sending messages to the TIBCO EMS Server and as a message consumer by listening on a queue or topic at the server. The TIBCO EMS Routing filter can be used as a message producer in this manner.

Connection

The list of all globally configured TIBCO EMS Connections are listed on this tab. You can configure TIBCO EMS Connections on the External Connections tab in the Policy Studio. For more information on configuring TIBCO EMS Connections, see the TIBCO Enterprise Messaging System Connection topic.

Select a previously configured TIBCO EMS Connection from the list. Messages will be sent to this TIBCO EMS Connection and will be dropped on the queue or topic specified on the Request tab.

Request

The Request tab is used to configure properties of the request to the messaging system. The following fields can be configured:

Destination Type:
You must specify whether the name specified in the Queue or Topic Name field below is a "Queue" or "Topic".

Queue or Topic Name:
Enter the name of the queue or topic that you want to drop messages on to.

Delivery Mode:
The Enterprise Gateway supports 3 delivery modes: persistent, non-persistent, and reliable.

  1. Persistent:
    Instructs the TIBCO EMS Server to ensure that a message is not lost in transit if the server fails. A message sent with this delivery mode is logged to persistent storage when it is sent.
  2. Non-persistent:
    Does not require the TIBCO EMS Server to store the message. With this mode, the message may be lost if the server fails.
  3. Reliable:
    When using reliable mode the TIBCO EMS Server never sends an acknowledgement or confirmation receipt back to the producer. This greatly decreases the volume of traffic on the network and can result in improved performance.

Priority Level:
You can use message priority levels to instruct the TIBCO EMS server 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 1. The TIBCO EMS Server will try 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 will become 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 Enterprise Gateway, i.e. ${id}. However, it is possible to use a proprietary correlation system, perhaps using MIME message IDs instead of Oracle message IDs.

Correlation ID:
Enter an identifier for the message that the Enterprise Gateway will use to correlate response messages with the corresponding request messages. Usually, if $id is specified in the Message ID field above, it will also be used here to correlate request messages with their correct response messages.

Message Type:
This dropdown allows you to specify the type of data that is to be serialized and sent in the message to the TIBCO EMS Server. The option selected will depend on what part of the message you want to send to the consumer.

For example, if you want to send the message body you should 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 message, you should 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.
  • Create a MapMessage from the java.lang.Map in the attribute named below:
    Select this option to create a javax.jms.MapMessage from a Oracle message attribute (named below) that consists of name-value pairs.
  • Create a ByteMessage from the attribute named below:
    Select this option to create a javax.jms.ByteMessage from the Oracle message attribute named below.
  • Create an ObjectMessage from the java.lang.Serializable in the attribute named below:
    This option can be selected in order to create a javax.jms.ObjectMessage from the Oracle message attribute named below.
  • Create a TextMessage from the attribute named below:
    A javax.jms.TextMessage can be created from the message attribute named below by selecting this option from the dropdown.

Attribute Name:
Enter the name of the Oracle message attribute that holds the data that is to be serialized to a JMS message and sent over the wire to the TIBCO EMS Server. The type of the attribute named here must correspond to that selected in the Message Type dropdown field above.

Custom Message Properties:
It is possible to set custom properties for messages in addition to the standard JMS header fields. Custom properties may be useful in order to pass additional information to the TIBCO EMS Server. It is possible to use message attributes as property values. For example, it is possible to create a property called "AuthNUser" and set its value to ${authenticated.subject.id}. When this message is routed to the specified queue or topic, other consumers can then filter on this property, e.g. only consume messages where "AuthNUser" equals "admin".

Response

The Response tab is used to configure whether the Enterprise Gateway should use asynchronous or synchronous communication when talking to the messaging system. If the Enterprise Gateway is to use asynchronous communication then select the "No Response" option from the Response dropdown. If synchronous communication is required, you must configure where to read the response from the TIBCO EMS Server.

When synchronous communication is selected, the Enterprise Gateway will wait on a message from a queue/topic from the TIBCO EMS Server. The Enterprise Gateway will set the "JMSReplyTo" property on each message that it sends. The value of the "JMSReplyTo" property will be the queue, temporary queue, topic, or temporary topic that was selected in the Response dropdown. It is up to the application that consumes the message from the queue to send the message back to the destination specified in the "JMSReplyTo" property.

The Enterprise Gateway will set the "JMSCorrelationID" property to the value of the Correlation ID field on the Response tab to correlate requests messages to their corresponding response messages. If the user has selected to use a temporary queue or temporary topic then this will be created when the Enterprise Gateway is started up.

Response:
Select where to read the response message from. The following options are available:

  • No Response:
    Select this option if you do not expect or require a response from the TIBCO EMS Server.
  • Response in Queue Named Below:
    If you want the TIBCO EMS Server to place response messages into a named queue, select this option and enter the name of the queue in the field below.
  • Response in Temporary Queue:
    You can also instruct the TIBCO EMS Server to place response messages on a temporary queue from which the Enterprise Gateway can pick them up.
  • Response in Topic Named Below:
    Select this option to tell the TIBCO EMS Server to place response messages in the topic named in the field below.
  • Response in Temporary Topic:
    If you want to read response messages from a temporary topic, select this option.

Note that when a temporary destination is selected, this destination will be created at start-up of the Enterprise Gateway. Only the Enterprise Gateway will be able to read from the temporary destination however any application can write to it. The Enterprise Gateway will use the value of the "JMSReplyTo" header to indicate the location where it will read responses from.

Reply Topic/Queue Name:
If you have selected a named queue or topic (i.e. not a temporary queue or topic) from the Response field above, its name should be entered here.

Time Out:
The Enterprise Gateway will wait a certain time period for a response to be received before it will time out. If the Enterprise Gateway does time out waiting for a response, this filter will fail. Enter the time out value in milliseconds.