Skip to content
CA API Gateway - 9.3
Documentation powered by DocOps

Manage JMS Destinations

Last update November 17, 2017

This topic describes how the CA API Gateway works with JMS destinations.

Note: If you are configuring Websphere as a JMS Destination, see Connect to a WebSphereJMS Provider instead.

Understanding JMS Destinations

In the CA API Gateway, a JMS destination is either a queue or a topic. One or more JMS destinations must be configured in the Policy Manager before the CA API Gateway can use JMS (Java Message Service) to communicate with service requestors and published services. A JMS destination can be used for receiving messages from requestors (inbound) or for sending messages to a web service or XML application (outbound).  

The CA API Gateway automatically monitors all inbound destinations configured in the Policy Manager. When the CA API Gateway receives a message from an inbound destination, it determines which service the message is destined for and executes the applicable policy.

Policies could contain a Route via HTTP(S) or Route via JMS assertion that specifies message forwarding using either HTTP(S) or JMS, respectively. In the CA API Gateway, there are three possible HTTP(S) and JMS routing scenarios:

JMS-to-JMS Configuration

In a JMS-to-JMS configuration scenario, the CA API Gateway receives messages from a monitored inbound JMS destination (iJMS), and then uses a Route via JMS assertion to transmit the messages to an outbound JMS destination (oJMS):

Requestor < iJMS  > Gateway < oJMS  > Service

Both the iJMS and oJMS destinations can be configured for a variety of reply behavior. This determines how the CA API Gateway will respond. For details, see the [Inbound Options] and [Outbound Options] tabs on the JMS destination Properties dialog.

 JMS-to-HTTP Configuration

In the JMS-to-HTTP configuration scenario, the CA API Gateway receives messages from a monitored inbound JMS destination (iJMS), and then transmits the messages to the service using HTTP:

Requestor <  iJMS > Gateway < HTTP > Service

Once again, the CA API Gateway monitors the inbound JMS destination (iJMS) configured in the Policy Manager. When the CA API Gateway picks up a message from the destination, it routes the message to the service URL specified in the Route via HTTP(S) assertion in the service’s policy. The CA API Gateway responds to the inbound message based on the inbound JMS destination configuration (for details, see the [Inbound Options] tab of the JMS Destination Properties.

Note: When you publish a service, the Policy Manager automatically adds the service URL specified during the publication process as a Route via HTTP(S) assertion in the policy.

HTTP-to-JMS Configuration

In the HTTP-to-JMS configuration scenario, the CA API Gateway receives messages via HTTP, and then transmits the messages to an outbound JMS destination (oJMS):

Requestor <  HTTP > Gateway < oJMS  > Service

The CA API Gateway receives a message over HTTP or HTTP(S), allowing the use of the Require HTTP Basic Credentials and Require SSL or TLS Transport with Client Authentication assertions in the policy. The CA API Gateway responds to the oJMS response based on the outbound JMS destination configuration (for details, see the [Outbound Options] tab of the JMS Destination Properties). The CA API Gateway then routes the reply message back to the requesting HTTP or HTTP(S) requestor, unless the "no replies" option was set.

Context Variables Created by JMS Requests

When the Manage JMS Destination task is run, it populates the context variables with the header information.

Variable

Description

${request.jms.header.<name>}

Returns the value of the JMS header, where <name> is the header name.

${request.jms.header.<name>.modified} Retrieves a JMS header that has been modified in the policy via the Manage Transport Properties/Headers Assertion. For example: ${request.jms.header.JMSType.modified}

${request.jms.headernames} 

This is a multivalued context variable that returns the names of all headers that are present.

${request.jms.headernames.modified}  Retrieves all JMS header names that have been modified in the policy via the Manage Transport Properties/Headers Assertion. For example: ${request.jms.headernames.modified}

${request.jms.allheadervalues} 

This is a multivalued context variable that returns all the header names and values that are present, in the format headername:headervalue.

The following are the possible headers:

JMSDestination
JMSDeliveryMode
JMSExpiration
JMSPriority
JMSMessageID
JMSTimestamp
JMSCorrelationID
JMSReplyTo
JMSType
JMSRedelivered

${request.jms.allheadervalues.modified} Retrieves all JMS header name/value pairs that have been in the policy via the Manage Transport Properties/Headers Assertion. For example: ${request.jms.allheadervalues.modified}

Tip: For a list of the context variables created by a JMS response, see the Route via JMS Assertion.

Resolving Requests in JMS Destinations

Requests received via a JMS destination can either be sent to a specific published service (bypassing the resolution process), or they can undergo the standard resolution rules. You can optionally augment the service resolution using SOAPAction values retrieved from a specified JMS message property.

If SOAPAction message properties are configured on inbound destinations, the combination of SOAPAction values and payload namespace URI(s) should be distinct for every service that is expected to receive requests over JMS. If SOAPAction message attributes are not configured, every service that is expected to receive requests over JMS must have payload namespace URI(s) that are not shared by any other service on the CA API Gateway.

Understanding JMS Message Size

The maximum size of a JMS message is governed by the following two global cluster properties:

  • io.xmlPartMaxBytes: This controls the maximum size of any XML message, including JMS messages. By default, this is 2621440 bytes (2.5MB).
  • io.jmsMessageMaxBytes: This controls the maximum size of JMS messages, including the XML and all MIME parts. By default, this is the same as io.xmlPartMaxBytes (2.5MB).

Normally, these two properties would have the same limit. If you have a need to further restrict the size of JMS messages globally, set io.jmsMessageMaxBytes to a lower value than io.xmlPartMaxBytes.

Working with JMS Destinations

An inbound destination allows the CA API Gateway to receive messages from a JMS destination, whereas an outbound destination allows the CA API Gateway to route messages to a service that is listening on a JMS destination. Destinations must be created in the JMS system's management application before they can be configured in the Policy Manager. A JMS destination can be edited or deleted at any time, and the CA API Gateway will enable such changes within a few seconds.

Note: The configuration of a new destination requires the JNDI directory settings specified during the JMS configuration process. Consult your Administrator for the required values.

Outbound JMS Connection Management

The CA API Gatewaywill close an outbound JMS connection under any of the following conditions:

  • the connection has been idle for too long (controlled by io.jmsConnectionCacheMaxIdleTime cluster property)
  • the connection is too old (controlled by io.jmsConnectionCacheMaxAge cluster property)
  • there are too many open connections (controlled by io.jmsConnectionCacheMaxSize cluster property)

Tip: If many outbound destinations are in use, you can improve performance by reducing the idle time and increasing the cache size.

Template Outbound Destinations

A template outbound destination is a special type of destination that allows certain properties to be omitted when the destination is created, to be filled in later during policy construction:

  • Initial Context Factory class name (JNDI tab)
  • JNDI URL (JNDI tab)
  • JNDI User Name, Password (JNDI tab)
  • Connection Factory Name (Destination tab)
  • Destination Name (Destination tab)
  • Destination User Name, Password (Destination tab)
  • Reply-to queue name (Outbound Options tab)

When you omit any of these properties during the destination definition, the policy author can enter the values during policy design in the Route via JMS assertion. However if any of the above properties are set in the template destination, they cannot be changed when the template is used in the Route via JMS assertion.

Troubleshooting Connection Issues with TIBCO EMS

If you find that your JMS destinations do not reconnect after the TIBCO EMS server is shut down and restarted, do the following:

  1. Locate the tibemsd.conf file on the EMS server and open it for editing.

    Tip: There are two tibemsd.conf files with the same name: one is a sample file, while the functional one resides in the TIBCO home folder, which may differ in each installation. For example, a search for "tibemsd.conf" may bring up these results:

    /opt/tibco/ems/6.1/samples/config/tibemsd.conf
    /root/TIBCO_HOME/tibco/cfgmgmt/ems/data/tibemsd.conf

  2. Add the following parameters:

    server_heartbeat_client = 5
    client_timeout_server_connection = 25

    The unit is seconds, so the parameters above are 5 and 25 seconds.

    Tip: Ensure that client_timeout_server_connection is at least five times the value of server_heartbeat_client.

This should resolve the reconnection issues. For more information about these parameters, refer to the TIBCO Enterprise Messaging Service User Guide.

Running the Manage JMS Destinations Task

To manage JMS destinations:

  1. In the Policy Manager, select [Tasks] > Transports > Manage JMS Destinations from the Main Menu (on the browser client, from the Manage menu).
    The Manage JMS Destinations dialog appears.

    Choose one of the following actions:

    Action

    Description

    Filter list of destinations (optional)

    When there are a large number of JMS destinations, you can filter the list to more easily locate the destination you want:

    1. From the drop-down list, select the destination property to filter on:
      • Name (from [Basics] tab)
      • JNDI URL (from [JNDI] tab)
      • Destination Name (from [Destination] tab)
        These are all in the JMS Destination Properties.
    2. Type a few characters to search on. This text will be matched anywhere within the chosen destination property and is not case sensitive.

      Tip: For more powerful filtering, you can use regular expressions.

    3. Indicate whether to include only Inbound, Outbound, or Both types of destinations.
    4. Click [Filter]. The list is filtered to display only those destinations matching the filter criteria.

    Sort destination list based on column

    By default, the list of destinations is sorted in ascending order by Name.

    Add a new JMS destination

    Click [Add] and then configure the properties for the new destination. See JMS Destination Properties.

    You can also create a new JMS destination by clicking [New Destination] on the JMS Routing Properties dialog.

    Note: The same Outbound destination may be defined multiple times, as long as each resolves to a different web service.

    Clone an existing JMS destination

    Select the destination to clone, then click [Clone]. Edit the destination properties as required. See JMS Destination Properties.

    Modify an existing JMS destination

    Select the destination to modify, then click [Properties]. Edit the destination properties as necessary. See JMS Destination Properties.  

    Note: Be sure to test your new settings to ensure the connection is valid.

    Remove a JMS destination

    Select the destination to remove and then click [Remove]. Click [OK] to confirm the deletion.

    Note: Removing a destination only unregisters it from the CA API Gateway. The destination still exists in the JMS system's management application.

  2. Click [Test Settings] to test the connection between the CA API Gateway and JMS destination. A test is considered successful if the CA API Gateway can:
    • Read from an inbound destination
    • Write to an outbound destination
    • Contact any additional destinations specified in the configuration (for example, a Reply-to queue, Failure queue, Wait-for-reply queue)
      If a connection cannot be established, make a note of the diagnostic information that is displayed, double-check the destination and CA API Gateway settings, and then try again. 
  3. Click [Save] to close the JMS Destination Properties. When adding a destination, the new destination is registered in the CA API Gateway and added to the Known JMS Destinations table in the Manage JMS Destinations dialog.
    The [Save] button is unavailable if there is information missing in any of the tabs.
  4. Click [Close] when done.
Was this helpful?

Please log in to post comments.