JMS Destination Properties

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

gateway90

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

For more information about JMS destinations, see Manage JMS Destinations.

If you are configuring Websphere as a JMS Destination, see "Connect to a WebSphere JMS Provider" in the CA API Gateway Administrators Manual
.

To access the properties for an MQ native queue
:

Run the Manage JMS Destinations task.

Select a destination and then click [Properties
]. You can also click [Add
] to create a new queue.

The JMS Destination Properties appear.

Configure each tab within the properties as necessary. Refer to the appropriate section below for a complete description of each tab.

Click [Save
] when done.

Configuring the [Basics] Tab

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

Enter a name for the JMS destination. This name will be 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.

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.

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.

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 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 MQ
over 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 will hold the messages that cannot be processed.

Choose WebLogic JMS
if connecting to a WebLogic JMS server.

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

Please contact CA Support if you require assistance configuring the destination for other JMS providers.

The [Reset
] button allows you to quickly set destination properties for the current provider using the predefined defaults. You will be warned if existing configuration will be overwritten. The [Reset
] button is not available for Generic JMS destinations.

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.

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.

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—i.e., machine.company.com.) 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 to be 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 will not match the connected EMS server host. This option is available only when the Verify server certificate check box is selected. 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. Private keys stored in an internal Hardware Security Module (HSM) on the `API Gateway` cannot be used for client certificate authentication with the TIBCO EMS server, and will not appear in the drop-down list.
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 ]. 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 . 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 will be received by exactly one consumer. If no consumers are available, then the message will be held until a consumer is available. If a consumer receives a message and does not acknowledge it before closing then the message will be redelivered to another consumer. Topic : The destination is a JMS Topic. It will be received by all consumers who have subscribed to this topic. Only subscribers with an active subscription will 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. If the system property com.l7tech.server.transport.jms.detectJmsTypes is set to "true" (default), the `API Gateway` will try to detect the connection type (either Queue or Topic) automatically. For more information, see System Properties.
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 `API Gateway` connect to the MQ Queue Manager using SSL. The `API Gateway` will always use its primary SSL keypair as a client certificate on the MQ connection. Additionally, the `API Gateway` will always perform hostname and server certificate validation using the `API 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.

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 will accept incoming messages from a JMS queue, ensure that the appropriate inbound JMS queue is monitored for the messages. JMS messages will be processed according to the assertions defined in the policy.

Setting	Description
Acknowledgement Behavior	From the drop-down list, select how the `API Gateway` should acknowledge 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" acknowledgement increases the reliability of message processing. If a `API Gateway` fails during the processing of a message, that message will remain in the JMS destination and can be processed by another node. (This assumes that a cluster of nodes has been configured. For more information, see Configure a `API Gateway`Cluster. If you have not configured a failure destination or a backout destination, then messages that consistently fail (for example, a backend service is non-functional) will remain in the queue indefinitely. The `API Gateway` will continually try to process these messages and may get stuck in a loop, unless one of the above destinations are configured. The Protect Against Message Replay assertion should not be used in any policy that will process 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 `API 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 will ignore 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 will override 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 `API 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 `API 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 `API Gateway` built-in service resolution logic. 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 `API 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 isn't 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 `API Gateway` will assume 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 `API 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 will be expected to ensure that messages that could not 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 `API Gateway` to stop listening for messages on this JMS destination. During this stoppage, incoming client requests will accumulate in the destination until the `API Gateway` resumes listening. When listening restarts, the `API Gateway` will process the queued messages and send a response.
Consumer Connections	Enter the number of JMS consumer connections permitted for a particular JMS destination, between 1 and 10000. Default: 1 (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 on 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. For a topic destination type, it is recommended that you choose the "No replies (one way)" option for an outbound topic. This will prevent errors when the Route via JMS assertion is processed. Always use temporary queue : Choose this to have the `API 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 `API 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. 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 `API 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 `API 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.
Session Pooling Setting	Specify the JMS session pooling settings: Session Pool Size : Specify the maximum number of sessions that can be allocated by the session pool (maximum 10000). Enter -1 to indicate no limit. Enter 0 to create a new connection each time the Route via JMS assertion sends a message to the queue. Default: 8 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 (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) 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.

Content feedback and comments

CA API Gateway 9.1

JMS Destination Properties