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

JMS Destination Properties

Last update August 30, 2018

When creating or viewing details about JMS destinations, the JMS Destination Properties appear. The properties are organized across these tabs:

To access the properties for an MQ native queue:

  1. Run the Manage JMS Destinations task.
  2. Select a destination and then click [Properties]. You can also click [Add] to create a new queue.
    The JMS Destination Properties appear.
  3. Configure each tab within the properties as necessary. Refer to the appropriate section below for a complete description of each tab.
  4. Click [Save] when done.

Configuring the [Basics] Tab

The [Basics] tab is used to set the destination direction and provider type.  

  1. Enter a name for the JMS destination. This name is displayed in the policy window. It can be the same as the Destination Name in the [Destination] tab or it can be a descriptive label to help users more easily identity the destination. This name is required.
  2. Specify the Direction of the destination being configured:
    • Select Outbound to configure an outbound destination.
    • Select the This destination is a template check box to configure a template outbound destination that allows certain details to be entered later, using the  Route via JMS Assertion . For more information, see "Template Outbound Destinations" in Manage JMS Destinations.
    • Select [Inbound] to configure an inbound destination.

      Note: Selecting a direction is possible only when adding or modifying a destination using the Manage JMS Destinations task. When creating a new destination from the Route via JMS Assertion, the outbound option is always used.

  3. Select the JMS provider type from the drop-down list.
    • Choose Generic JMS to connect to a JMS provider not listed.
      The "Generic JMS" option can be used to configure the JMS destination to work with other JMS providers that are not listed in the drop-down list.
      For example, to connect to webMethods Broker: enter the following Context Factory class name in the [JNDI] tab: com.webmethods.jms.naming.WmJmsNamingCtxFactory
    • Choose TIBCO EMS if connecting to a TIBCO Enterprise Message Service (EMS) server.
    • Choose WebSphere MQover LDAP if connecting to an IBM WebSphere MQ server using the LDAP protocol. If you are configuring an MQSeries destination with a backout destination configured, this destination holds the messages that cannot be processed.

    • Choose WebLogic JMS if connecting to a WebLogic JMS server.

      Note: When connecting to a WebLogic JMS provider, set the io.jmsConnectionCacheMaxSize cluster property to "0" (zero) and also set the system property com.l7tech.server.transport.jms.detectJmsTypes to true on each node in a cluster. Restart the Gateway for the new setting to take effect.

    The [Reset] button resets the destination properties for the current provider using the predefined defaults. You are warned if existing configuration will be overwritten. The [Reset] button is not available for Generic JMS destinations.
  4. Optionally choose a security zone. To remove this entity from a security zone (security role permitting), choose "No security zone". For more information about security zones, see Understanding Security Zones.

    Note: This control is hidden if either: (a) no security zones have been defined, or (b) you do not have Read access to any security zone (regardless of whether you have Read access to entities inside the zones).

Configuring the [JNDI] Tab

The [JNDI] tab is used to configure the JNDI connection properties. Note that the settings described below may not be available for all provider types.

Reducing the JNDI Timeout

Some best practices tips for improving performance by reducing the JNDI timeout period:

  • Define the weblogic.jndi.connectTimeout property. Refer to the "Additional Properties" section in the table below for details.
  • Increase the size of the Session Pool in the [Outbound Options] tab.
  • Reduce the Max Wait setting in the "Session Pooling" section of the [Outbound Options] tab if necessary.

Setting

Description

Initial Context Factory class name

Enter the name of the initial context class.

For outbound template destinations, you may leave this field blank to be filled in later using the Route via JMS Assertion .

Examples:

WebSphere MQ: com.sun.jndi.ldap.LdapCtxFactory

TIBCO EMS: com.tibco.tibjms.naming.TibjmsInitialContextFactory

WebLogic JMS: weblogic.jndi.WLInitialContextFactory

WebSphere: com.ibm.websphere.naming.WsnInitialContextFactory

JNDI URL

Enter the address of the JNDI (Java Naming and Directory Interface) server, followed by a port number (if required).

For outbound template destinations, you may leave this field blank to be filled in later using the Route via JMS Assertion .

Examples:

WebSphere MQ: ldap://servername.company.com/dc=companydomain,dc=com

TIBCO EMS: tibjmsnaming://machinename:7222 (Important: Enter only the machine name, not the full host nameā€”for example, machine.company.com

Problems connecting to JNDI URL?

Ensure that all Gateway nodes in the cluster can access the port specified in the JNDI URL. Any firewall issues preventing access can cause unexpected timeouts. Also check if rate limiting has been applied to a port.

Credentials are required to connect to JNDI

If login information is required, select this check box and then enter the User Name and Password.

For outbound template destinations, you may select the check box and leave the credential fields blank. These are filled in later using the Route via JMS Assertion.

Use SSL

(only available for Provider Type 'TIBCO EMS'')

Select this check box if you want to use an SSL connection for the JMS destination.

  • For Provider Type TIBCO EMS, additional SSL settings become available once the Use SSL check box is selected.

The following options are available once this check box is selected for Provider Type TIBCO EMS:

  • Use SSL for authentication only: Select this check box to use SSL only when authenticating. Clear this check box to use SSL for all communication (for both authentication and subsequent messages).
  • Verify server certificate (using trusted certificate store): Select this check box to verify the server certificate. Clear this check box to not verify the server certificate.
  • Verify that common name in server certificate matches connected host name: Select this check box to verify the server certificate with the host name. Clear this check box if you know that the common name in the server certificate does not match the connected EMS server host.

This option is available only when the Verify server certificate check box is selected.

Tip: Normally you should verify the certificate name with the host name. You may disable this option for testing purposes, when a temporary non-production certificate is installed on the EMS server.

  • Supply digital certificate for client authentication: Select this check box if you are supplying a certificate and private key for client authentication. This is required if the EMS server is configured with "ssl_require_client_cert = enabled".  From the drop-down list, select the digital certificate to be used.

Note: Private keys stored in an internal Hardware Security Module (HSM) on the Gateway cannot be used for client certificate authentication with the TIBCO EMS server.

Additional Properties

Optionally define additional properties required by the JNDI connection. Note: Please consult with your administrator or CA Support to determine the need for additional properties.

  • To add an additional property, click [Add] and then enter the Name and Value.
  • To modify a property in the list, select the row and then click [Edit]. Edit the Value as required.
  • To remove a property from the list, select the row and then click [Remove].

Performance Tip: Faster Connection Timeouts

Add a property named weblogic.jndi.connectTimeout with a low value. This allows JNDI connection failures to time out more quickly and reduces the number of blocking threads. This leads to a performance improvement.

When not specified, the internal value is 180,000 ms. Try setting values from 1000 to 10000. Note: There are three retries, so this value is multiplied internally by 3 for the total timeout.

Configuring the [Destination] Tab

The [Destination] tab is used to configure the JMS destination details.

Setting

Description

Destination Type

From the drop-down list, select the destination type:

  • Queue: The destination is a JMS Queue, where the message is received by exactly one consumer. If no consumers are available, then the message is held until a consumer is available. If a consumer receives a message and does not acknowledge it before closing, then the message is redelivered to another consumer.
  • Topic: The destination is a JMS Topic. It is received by all consumers who have subscribed to this topic. Only subscribers with an active subscription get a copy of the message.

Connection Factory Name

Enter the JNDI Connection Factory reference name.

For outbound template destinations, you may leave this field blank to be filled in later using the Route via JMS assertion.

The Connection Factory Name should be displayed if WebSphere has been correctly configured as a JMS destination.

Tip: If the system property com.l7tech.server.transport.jms.detectJmsTypes is set to "true" (default), the Gateway tries to detect the connection type (either Queue or Topic) automatically.

Destination Name

Enter the destination reference name.

For outbound template destinations, you may leave this field blank to be filled in later using the Route via JMS Assertion .

Credentials are required to connect to this Destination

If this JMS destination requires login information, select this check box and then enter the User Name and Password.

For outbound template destinations, you may select the check box and leave the credential fields blank to be filled in later using the  Route via JMS Assertion .

Use SSL

(only available for Provider Types = 'TIBCO EMS' and 'WebSphere')

When the Provider Type is TIBCO EMS:

  • See "Use SSL" for details.

When the Provider Type is WebSphere MQ over LDAP:

  • Select this check box to have the Gateway connect to the MQ Queue Manager using SSL. The Gateway always uses its primary SSL keypair as a client certificate on the MQ connection. Additionally, the Gateway always performs hostname and server certificate validation using the Gateway standard trusted certificate store.

Clear this check box if you are certain that the MQ Queue Manager does not require SSL.

  • Use Client Authentication: When connecting using SSL, select this check box to present a certificate to the server during the SSL handshake, if one is requested. Clear this check box to never present a certificate, even if one is requested. Note that access may be denied in this case.
  • Keystore: From the drop-down list, select the keystore from which to retrieve the certificate.

The [Use SSL] check box assumes that the MQ Queue Manager has been correctly configured to use SSL.

Configuring the [Inbound Options] Tab

The [Inbound Options] tab is used to configure details for inbound JMS destinations.

Note: Inbound JMS destinations are used by published JMS services and do not require an assertion. The JMS service publication process is the same as the publication process for a regular service. If you are publishing a service that accepts incoming messages from a JMS queue, ensure that the appropriate inbound JMS queue is monitored for the messages. JMS messages are processed according to the assertions defined in the policy.

Setting

Description

Acknowledgement Behavior

From the drop-down list, select how the Gateway acknowledges incoming JMS messages:

  • On Take: Automatically acknowledge each message as it is read from the destination.
  • On Completion: Delay acknowledging the incoming message until the services policy execution completes.

Using "On Completion" acknowledgment increases the reliability of message processing. If a Gateway fails during the processing of a message, that message remains in the JMS destination and can be processed by another node. (This assumes that a cluster of nodes has been configured.)

Note: If you have not configured a failure destination or a backout destination, then messages that consistently fail (for example, a back-end service is non-functional) remain in the queue indefinitely. The Gateway continually tries to process these messages and may get stuck in a loop, unless one of the above destinations are configured.

Note: The Protect Against Message Replay Assertion should not be used in any policy that processes messages from JMS destinations that are configured with the "On completion" acknowledgment mode without a specified failure destination.

  

Inbound Reply Behavior

Select a JMS reply behavior for the inbound destination:

  • Automatic: Choose this option to have the Gateway send response messages on the destination named in the corresponding request message's JMSReplyTo attribute. If the attribute is not present, no response messages will be sent.
  • Do not send replies: Choose this option to never send replies to requests received on this inbound destination. This ignores any JMSReplyTo attribute in inbound messages.  
  • Send reply to specified queue: Choose this option to send all replies to requests received on this inbound destination to the specified queue. This overrides any JMSReplyTo attribute in inbound messages. Enter the name of the queue in the adjacent box.

Request/Response Correlation

The inbound Request/Response correlation behavior can be specified if either the "Automatic" or "Send reply to specified queue" option was selected:

  • Copy CorrelationID from Request to Response: Choose this option to have the Gateway copy the JMSCorrelationID value from the inbound request message to the JMSCorrelationID attribute on the outbound response.
  • Set Response CorrelationID from Request's MessageID: Choose this option to have the Gateway copy the MessageID from the inbound request message to the JMSCorrelationID attribute on the outbound response.

Service Resolution

Select how the service should be resolved:

  • Associate destination with published service (bypass resolution)
    • Select this check box to associate the inbound JMS destination with a published service. This overrides the built-in service resolution logic of the Gateway. This is useful if you need to publish the same WSDL multiple times and have the same target namespace, yet still be consumed through JMS. Choose the service from the Service name drop-down list.
    • Clear this check box to have the Gateway determine the applicable policy for each message. This is done based on message-level inspection. For example, a SOAP payload will be resolved against a set of published services and associated WSDL documents to find a match.
  • Get SOAPAction values from the specified JMS message property for service resolution: Select this check box to use a specific JMS message property as the "SOAPAction" for service resolution purposes. Enter the name of the property to use.
  • Specify content type: Select this check box to specify the Content-Type to be associated with the inbound destination. Choose from one of the following:
    • Select the Content-Type to use from the Use Content Type drop-down list. If the Content-Type you need is not listed, type it directly into the drop-down list.
    • Select Get Content Type from JMS Property and then specify a JMS message property to retrieve from.

If a Content-Type is not specified, the Gateway assumes type "text/xml".

Send failed requests to the specified queue

Select this check box to route the message to a special queue if the service policy does not successfully complete.

The messages sent to the failure queue are not due to a Gateway failure, but rather from other causes such as routing failure, message content, etc.  

If this check box is not selected, then the JMS provider configuration must ensure that messages that cannot be processed do not remain in the queue indefinitely.

This option is available only when Acknowledgement Behavior is set to "On Completion".

Failure queue name

If sending requests to a failure queue, enter the name of the queue (topics are not supported) that will receive messages that were not successfully processed.

Stop listening on this destination

Select this check box to instruct the Gateway to stop listening for messages on this JMS destination. During this stoppage, incoming client requests accumulate in the destination until the Gateway resumes listening. When listening restarts, the Gateway processes the queued messages and sends a response.  

Consumer Connections

Enter the number of JMS consumer connections that are permitted for a particular JMS destination, between 1 and 10000. Default: 1

Notes: (1) This setting only applies to JMS Queues, not to JMS Topics. (2) The default can be changed using the io.jmsConsumerConnections cluster property. (3) Consumer connections stay open until the "Stop listening on this destination" check box is selected.

Override maximum message size


Select this check box to override the permitted maximum size of the routing message. Clear this check box to use the value set in the io.xmlPartMaxBytes cluster property.

  • Restrict messages to: Enter the maximum permitted size of the response message, in bytes. You may reference context variables.
  • Allow unlimited message size (not recommended): Select this option to allow response messages of unlimited size. This is not recommended and should be used only under the direction of CA Support.

Configuring the [Outbound Options] Tab

The [Outbound Options] tab is used to configure details for outbound JMS destinations. For more information about using an outbound destination in a service with JMS routing, see Route via JMS Assertion.

Setting

Description

Outbound Reply Behavior

Specify a JMS reply behavior for the outbound destination.

Tip: For a topic destination type, it is recommended that you choose the "No replies (one way)" option for an outbound topic. This prevents errors when the  Route via JMS Assertion is processed.

  • Always use temporary queue: Choose this to have the Gateway create a temporary queue, set it as the JMSReplyTo attribute on outbound requests, then listen on that temporary queue for a response.

  • No replies (one way): Choose this to have the Gateway send the request and then return immediately without waiting for a reply. The response to the requestor will be empty, unless some other assertion fills it in.

    Tip: Opting for no replies may increase performance slightly, but the Gateway must still wait for the JMS server to send an acknowledge, which can be slow on many JMS servers. Since JMS in general and commercial queuing systems from many vendors are considered reliable messaging systems, most commit the message to disk before sending the acknowledge. This incurs additional latency and reduces the overall throughput.

  • Wait for reply on specified queue: Choose this to have the Gateway look up the specified queue, set it as the JMSReplyTo attribute on the outbound request, and then wait on that queue for the response. Enter the name of the queue in the adjacent box.

For outbound template destinations, you may leave this field blank to be filled in later using the Route via JMS Assertion .

Request/Response Correlation

If waiting for a reply on a specific destination, select a Request/Response Correlation option:

  • Generate New CorrelationID for Request: Choose this to have the Gateway generate a unique ID, set it as the JMSCorrelationID attribute on the outbound request, and then select only messages with the matching JMSCorrelationID value from the response destination.
  • Expect Receiver to Copy Request MessageID to Response CorrelationID: Choose this to send the request message as-is, then select only messages with the JMSCorrelationID attribute matching the outbound request's MessageID attribute from the response destination.

Outbound Message Format

Select the desired output Content-Type:

  • Automatic: Requests arriving over JMS as TextMessage will be forwarded as TextMessage, otherwise it will be forwarded as BytesMessage. This setting is the default.
  • BytesMessage: Always forward requests as BytesMessage, regardless of incoming format.
  • TextMessage: Always forward requests as TextMessage, regardless of incoming format.
Pool Settings

Specify which type of pool settings to use for this connection:

  • Session Pooling: This option uses a single JMS connection per destination. You can adjust the number of sessions for this connection. This option replicates the functionality available in the Gateway before v9.3. Tip: For better performance, use the "Connection Pooling" option instead.
  • Connection Pooling: This option lets you create more than one connection per destination. This allows multiple thread pools to send JMS messages, which increases overall throughput and improves performance. Tip: With Connection Pooling, every connection has a single session only. It is not possible to also enable Session Pooling.

Pooling Settings:
Session Pooling
.

  • Session Pool Size: The maximum number of sessions that can be allocated by the session pool (maximum 10000). Enter any negative value to indicate no limit (not recommended). Enter 0 to create a new connection each time the Route via JMS Assertion sends a message to the queue. Default: (from the io.jmsSessionPoolSize cluster property)
  • Max Session Idle: Specify the maximum number of sessions that can sit idle in the session pool (maximum 10000). Enter -1 to indicate no limit. Default: 8 (from the io.jmsSessionMaxIdle cluster property)

    Tips: (1) When this setting is too low on a heavily loaded system, you may see sessions (producers) being destroyed and new sessions being created almost immediately. (2) For best performance, set both "Session Pool Size" and "Max Session Idle" to the same value and use a value similar to the request concurrency (specified by the io.httpCoreConcurrency cluster property). 

  • Max Wait: Specify the maximum period of time to wait for an idle session when the pool is exhausted (maximum 999999999).
    Default: 5000 milliseconds (from the io.jmsSessionMaxWait cluster property)

    Tip: If you are using the "No replies (one way)" option for outbound JMS destinations, reduce the Max Wait setting. This helps improve performance if you have a slow JMS server.

Pooling Settings:
Connection Pooling
  • Connection Pool Size: The maximum pool size for the JMS connection (maximum 10000). Default: 1 (from the io.jmsConnectionPoolSize cluster property)

    Tip: For best performance, set the connection pool size to between 100 and 200.

  • Min Connection Idle: The minimum number of idle JMS connections that must stay in the pool. Default: 0 (from the io.jmsConnectionMinIdle cluster property)

    Tip: (1) This value should be no higher than the Connection Pool Size. Too high a value could impact the Gateway memory, while too low a setting (for example, "0") could affect performance. (2) The default "0" for this setting is meant to preserve compatibility with the previous (before v9.3) versions of the Gateway. Be sure to change this value if you are using Connection Pooling. 

  • Max Wait: The maximum time the Gateway waits to acquire a JMS connection. Default: 5000 milliseconds (from the io.jmsConnectionMaxWait cluster property)
Override System Defaults

Select this check box to enter your own values into the pooling fields. Clear this check box to use the values from the corresponding cluster properties.

Tip: When the check box is deselected, the Gateway reverts to using the values from the relevant cluster properties. These values appear in the fields the next time you open the JMS Destination Properties dialog box, but they will take effect the moment you click OK.

Was this helpful?

Please log in to post comments.

  1. conny Postma
    2019-05-23 03:13

    can we add the following: Format used for Connection Factory name and Destination Name needs to have 'dynamic'Topics/ Connection Factory must be given for inbound queues(when using Failure queue)