Manage JMS Destinations
This topic describes how the gateway works with JMS destinations.
This topic describes how the
CA API Gatewayworks with JMS destinations.
Understanding JMS Destinations
API Gateway, a JMS destination is either a
topic. One or more JMS destinations must be configured in the Policy Manager before the
API Gatewaycan 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).
API Gatewayautomatically monitors all inbound destinations configured in the Policy Manager. When the
API Gatewayreceives 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
API Gateway, there are three possible HTTP(S) and JMS routing scenarios:
In a JMS-to-JMS configuration scenario, the
API Gatewayreceives 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):
> Gateway <
Both the iJMS and oJMS destinations can be configured for a variety of reply behavior. This determines how the
API Gatewaywill respond. For details, see the [
Inbound Options] and [
Outbound Options] tabs on the JMS destination Properties dialog.
In the JMS-to-HTTP configuration scenario, the
API Gatewayreceives messages from a monitored inbound JMS destination (iJMS), and then transmits the messages to the service using HTTP:
Once again, the
API Gatewaymonitors the inbound JMS destination (iJMS) configured in the Policy Manager. When the
API Gatewaypicks 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
API Gatewayresponds to the inbound message based on the inbound JMS destination configuration (for details, see the [
Inbound Options] tab of the JMS Destination Properties.
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.
In the HTTP-to-JMS configuration scenario, the
API Gatewayreceives messages via HTTP, and then transmits the messages to an outbound JMS destination (oJMS):
API Gatewayreceives 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
API Gatewayresponds to the oJMS response based on the outbound JMS destination configuration (for details, see the [
Outbound Options] tab of the JMS Destination Properties). The
API Gatewaythen 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.
Returns the value of the JMS header, where <name> is the header name.
Retrieves a JMS header that has been modified in the policy via the Manage Transport Properties/Headers Assertion. For example:
This is a multivalued context variable that returns the names of all headers that are present.
Retrieves all JMS header names that have been modified in the policy via the Manage Transport Properties/Headers Assertion. For example:
This is a multivalued context variable that returns all the header names and values that are present, in the format
The following are the possible headers:
Retrieves all JMS header name/value pairs that have been in the policy via the Manage Transport Properties/Headers Assertion. For example:
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
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.jmsMessageMaxBytesto a lower value than
Working with JMS Destinations
An inbound destination allows the
API Gatewayto receive messages from a JMS destination, whereas an outbound destination allows the
API Gatewayto 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
API Gatewaywill enable such changes within a few seconds.
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
API Gatewaywill close an outbound JMS connection under any of the following conditions:
- the connection has been idle for too long (controlled byio.jmsConnectionCacheMaxIdleTimecluster property)
- the connection is too old (controlled byio.jmsConnectionCacheMaxAgecluster property)
- there are too many open connections (controlled byio.jmsConnectionCacheMaxSizecluster property)
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:
- Locate thetibemsd.conffile on the EMS server and open it for editing.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
- Add the following parameters:server_heartbeat_client = 5 client_timeout_server_connection = 25The unit is seconds, so the parameters above are 5 and 25 seconds.Ensure thatclient_timeout_server_connectionis at least five times the value ofserver_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:
- In the Policy Manager, select[Tasks] > Transports > Manage JMS Destinationsfrom the Main Menu (on the browser client, from the Manage menu). The Manage JMS Destinations dialog appears.Choose one of the following actions:ActionDescriptionFilter 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:
Sort destination list based on columnBy default, the list of destinations is sorted in ascending order by Name.Add a new JMS destinationClick [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.The same Outbound destination may be defined multiple times, as long as each resolves to a different web service.Clone an existing JMS destinationSelect the destination to clone, then click [Clone]. Edit the destination properties as required. See JMS Destination Properties.Modify an existing JMS destinationSelect the destination to modify, then click [Properties]. Edit the destination properties as necessary. See JMS Destination Properties.Be sure to test your new settings to ensure the connection is valid.Remove a JMS destinationSelect the destination to remove and then click [Remove]. Click [OK]to confirm the deletion.Removing a destination only unregisters it from theAPI Gateway. The destination still exists in the JMS system's management application.
- 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.
- Type a few characters to search on. This text will be matched anywhere within the chosen destination property and is not case sensitive.For more powerful filtering, you can use regular expressions.
- Indicate whether to include only Inbound, Outbound, or Both types of destinations.
- Click [Filter]. The list is filtered to display only those destinations matching the filter criteria.
- Click [Test Settings] to test the connection between theAPI Gatewayand JMS destination. A test is considered successful if theAPI Gatewaycan:
- 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 andAPI Gatewaysettings, and then try again.
- Click [Save] to close the JMS Destination Properties. When adding a destination, the new destination is registered in theAPI Gatewayand 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.
- Click [Close] when done.