Working with JMS Connection Aliases

A JMS connection alias specifies the information that Integration Server needs to establish an active connection between Integration Server and the JMS provider. Integration Server uses a JMS connection alias to send messages to and receive messages from the JMS provider.

Connecting to webMethods Broker with the Native webMethods API

When you use webMethods Broker as the JMS provider, you can configure a JMS connection alias to use the native webMethods API. The native webMethods API provides a way to connect the Integration Server directly to the webMethods Broker acting as the JMS provider. This eliminates the need for connection factories. Destinations can be created directly on the Broker and do not need to be stored in a JNDI provider. Consequently, you do not need to use a JNDI provider if all JMS connection aliases specify that the connection to webMethods Broker should be made using the native webMethods API.

If you choose to use webMethods Broker but do not want to connect natively (using the native webMethods API), you still need to use a JNDI provider.

Note: webMethods Broker is deprecated. Consequently, the ability to configure JMS connection alias to use the native webMethods API is deprecated as well.

Predefined JMS Connection Aliases

Integration Server includes predefined JMS connection aliases. Integration Server creates the aliases the first time Integration Server starts. If the aliases existed in an Integration Server that was migrated from a previous version, Integration Server keeps the existing aliases. That is, Integration Server does not overwrite the previous alias definition.

Integration Server has the following predefined JMS connection aliases:

JMS Connection Alias	Description
DEFAULT_IS_JMS _CONNECTION	A JMS connection alias that defines a connection to Universal Messaging using the predefined JNDI provider alias DEFAULT_IS_JNDI_PROVIDER. Integration Server configures this JMS connection alias when you launch the Integration Server the first time. This connection alias is disabled by default.
PE_NON TRANSACTIONAL_ ALIAS	A JMS connection alias for the Process Engine that establishes a connection to Universal Messaging using the predefined JNDI provider alias DEFAULT_IS_JNDI_PROVIDER. Integration Server configures this alias when you launch your Integration Server the first time. Note: Integration Server creates this alias even if the Process Engine is not installed.

JMS Connection Alias

Description

DEFAULT_IS_JMS
_CONNECTION

A JMS connection alias that defines a connection to Universal Messaging using the predefined JNDI provider alias DEFAULT_IS_JNDI_PROVIDER.

Integration Server configures this JMS connection alias when you launch the Integration Server the first time.

This connection alias is disabled by default.

PE_NON
TRANSACTIONAL_
ALIAS

A JMS connection alias for the Process Engine that establishes a connection to Universal Messaging using the predefined JNDI provider alias DEFAULT_IS_JNDI_PROVIDER.

Integration Server configures this alias when you launch your Integration Server the first time.

Note: Integration Server creates this alias even if the Process Engine is not installed.

Note: If you migrated to Integration Server 9.10 or later from an earlier version, you might have the EventBus alias which was a pre-defined JMS connection alias in versions prior to 9.10. This EventBus alias is for the EDA Event Bus server and defines a connection to Universal Messaging using the predefined JNDI provider alias DEFAULT_IS_JNDI_PROVIDER.

Creating a JMS Connection Alias

About this task

When you create a JMS connection alias, keep the following points in mind:

You can use JNDI to retrieve administered objects (Connection Factories and Destinations) and then use the Connection Factory to create a connection. If you intend to use a JNDI provider, you need to configure one or more JNDI provider aliases before creating a JMS connection alias.

- or -

You can use the native webMethods API to create the connection directly on the webMethods Broker. Because you can create Destinations at the Broker, you do not need to configure a JNDI provider alias if you intend to use the native webMethods API.

Note that if you elect to use the webMethods Broker but do not want to connect natively, you will need to use a JNDI provider and configure one or more JNDI provider aliases.
Each JMS connection alias has an associated transaction type. Within Integration Server, certain functionality must be completed within a non-transacted session. For example, to use Integration Server to send or receive large message streams, you must specify a JMS connection alias whose transaction type is set to NO_TRANSACTION.
When configuring a JMS connection alias from an on-premise Integration Server to a Universal Messaging server in the cloud, you need to modify the custom_wrapper.conf configuration file to include com.softwareag.um.jndi.cf.url.override=true. Specifically, modify the custom_wrapper.conf file to include:
wrapper.java.additional. n =-Dcom.softwareag.um.jndi.cf.url.override=true

Where n is the next available wrapper.java.additional number.

To create a JMS connection alias

Procedure

Open Integration Server Administrator if it is not already open.
In the Settings menu of the Navigation panel, click Messaging.
Under JMS Configuration, click JMS Settings.
Click Create JMS Connection Alias.

Set the following General Settings for the JMS connection alias:

For this field	Specify
Connection Alias Name	Name of the connection alias. Each connection alias represents a connection factory to a specific JMS provider.
Description	A description of the JMS connection alias.
Transaction Type	Whether sessions that use this JMS connection alias will be transacted.
	Select	To
	NO_TRANSACTION	Indicate that sessions that use this JMS connection alias are not transacted.
	LOCAL_TRANSACTION	Indicate that sessions that use this JMS connection alias are part of a local transaction.
	XA_TRANSACTION	Indicate that sessions that use this JMS connection alias are part of an XA transaction.
Connection Client ID	The JMS client identifier associated with the connections established by this JMS connection alias. Note: The connection client ID can be specified in the JMS connection alias or in the Connection Factory. If the connection client ID is specified in both places, Integration Server uses the value from the Connection Factory. For more information about the connection client ID, see About the Connection Client ID.
User (optional)	User name needed to acquire a connection from the connection factory. For more information about whether or not the JMS provider requires a user name and password to obtain a connection, refer to the product documentation for the JMS provider.
Password (optional)	Password needed to acquire a connection from the connection factory. For more information about whether or not the JMS provider requires a user name and password to obtain a connection, refer to the product documentation for the JMS provider.

In the Create Connection Using list, select one of the following to indicate how administered objects (connection factories and destinations) will be looked up:
- If you intend to use a JNDI provider, select JNDI Lookup.
- If you intend to use the native webMethods API to create the connection directly on the webMethods Broker, select Native webMethods API.

If you selected JNDI Lookup in the Create Connection Using list, do the following in the remaining fields under Connection Protocol Settings:

For this field	Specify
JNDI Provider Alias Name	The alias to the JNDI provider that you want this JMS connection alias to use to look up administered objects. For information about creating a JNDI provider alias, see Creating a JNDI Provider Alias.
Connection Factory Lookup Name	The lookup name for the connection factory that you want to use to create a connection to the JMS provider specified in this JMS connection alias. If the JMS connection alias connects to Universal Messaging, specify the Universal Messaging connection factory that you created when you set up your environment. If you are using SonicMQ as the JMS provider, specify the lookup name that refers to the serializable Java object file containing the SonicMQ object definitions. Include the .sjo extension as part of the lookup name.
Create Administered Objects On Demand ( Universal Messaging	Whether Integration Server creates administered objects on the JNDI provider if the object is not found when Integration Server looks up the object. Select the check box if you want Integration Server to create a destination or connection factory when an JNDI lookup for the object fails. For more information about creating administered objects on demand, see Creating Administered Objects. To create the administered objects on demand, the JNDI provider must be the Universal Messaging JNDI provider and the JMS provider must be Universal Messaging. Note: Software AG recommends against using this feature in a production environment. That is, leave the Create Administered Objects On Demand check box cleared for an Integration Server running in production.
Enable Follow the Master ( Universal Messaging )	Whether connections created from this JMS connection alias always connect to the master realm server in the Universal Messaging cluster. This setting affects producer and consumer connections created using this JMS connection alias. Do one of the following: Select the Enable Follow the Master check box to indicate that Integration Server always connects to the master realm server in a Universal Messaging cluster when Integration Server uses this JMS connection alias to send or receive messages. Clear the Enable Follow the Master check box to disable the follow the master behavior for this JMS connection alias when Integration Server uses this JMS connection alias to send or receive messages. If your solution uses the round-robin feature for sending JMS messages, disable follow the master for the JMS connection alias. Note: Enable Follow the Master option is available to JMS connection aliases that use Universal Messaging as the JMS provider.
Monitor webMethods Connection Factory	How Integration Server monitors the connection factory object for changes, if at all. This only applies if a JMS connection alias connects to the webMethods Broker using a webMethods Connection Factory object in a JNDI server.
	Select	To
	No	Indicate that Integration Server will not monitor the connection factory. This is the default.
	Poll for changes (specify interval)	Monitor the connection factory by polling for changes at an interval that you specify.
	Poll for changes (interval defined by webMethods Connection Factory)	Monitor the connection factory at an interval determined by the refresh interval specified for the webMethods Connection Factory object. For more information about configuring a cluster connection factory, see Administering webMethods Broker and webMethods Broker Messaging Programmer’s Guide .
	Register change listener	Monitor the connection factory by registering an event listener.
Polling Interval (minutes)	The number of minutes between polling attempts. The polling interval must be a positive integer. The default value is 60 minutes. Note: This field is only available if you selected Poll for changes (specify interval).
Note: For more information, see Monitoring a Connection Factory Object for Changes.

If you selected Native webMethods API in the Create Connection Using list, do the following to configure the connection to the Broker Server that you want to use as the JMS provider for this JMS connection alias:

For this field	Specify
Broker Host	Name (`DNSname`:`port` or `ipaddress`:`port`) of the machine on which the Broker Server resides.
Broker Name	Name of the webMethods Broker as defined on the Broker Server. The default name is Broker #1.
Client Group	The name of the client group to which you want Integration Server to belong when it acts as a JMS client. The client group that you specify must already exist on the Broker Server. The default is IS-JMS.
Broker List	A comma delimited list of Broker Servers on which the connection between the Integration Server (acting as the JMS client) and the Broker (acting as the JMS provider) can exist. This provides connection failover. If a connection failure occurs to the first Broker Server in the list, a connection attempt will be made to the next Broker Server listed. Use the following format for each webMethods Broker: {webMethods Broker Name]@<host>[:port] Note: If a connection to a Broker Server is already configured (via Settings > Messaging > webMethods Messaging Settings), Integration Server populates the fields under Connection Protocol Settings with information about that Broker Server. If that Broker Server functions as the JMS provider, you may not need to edit any information. However, make sure that the Client Group field specifies the client group to which you want Integration Server to belong when it functions as a JMS client.
Keystore	The full path to this Integration Server's keystore file. A keystore file contains the credentials (private key/signed certificate) that an entity needs for SSL authentication. If the Broker Server requires an SSL connection, then the information in this file is used to authenticate the Integration Server client to that Broker Server. The Integration Server's keystore file is stored on the machine on which the Integration Server resides.
Keystore Type	The file type of the Integration Server's keystore file, which can be either PKCS12 or JKS.
Truststore	The full path to this Integration Server client's truststore file. A truststore file contains trusted root certificates for the authorities responsible for signing SSL certificates. For an SSL connection to be made, a valid trusted root for the SSL certificate stored in the keystore must be accessible in a truststore file. The Integration Server's truststore file is stored on the machine on which the Integration Server resides.
Truststore Type	The file type of the Integration Server's truststore file, which is JKS.
Encryption	Specify whether or not to encrypt the connection between the Integration Server and the webMethods Broker.

Under Advanced Settings, specify the following information for the JMS connection alias:

For this field	Specify
Class Loader	The name of the class loader that you want to use with this JMS connection alias. Integration Server will use the specified class loader when performing certain activities with the JMS connection alias (send a message, receive a message, create a connection, create a destination, etc.) By default, Integration Server uses the server class loader. However, you can specify the class loader for a package instead. This may be helpful when working with third party JMS providers. For example, you might place the third party jars needed for each JMS provider in separate packages, specifically, in the `Integration Server_directory` /instances/`instance_name`/packages/`packageName`/code/jars directory. This can help prevent conflicts between the jars required for different JMS providers.
Maximum CSQ Size (messages)	The maximum number of messages that can exist in the client side queue for this JMS connection alias. Integration Server writes messages to the client side queue if the JMS provider is not available when messages are sent. Each JMS connection alias has its own client side queue. Specify -1 if you want the client side queue to be able to contain an unlimited number of messages. That is, specify ‑1 if you do not want to set a maximum limit. If you specify 0, Integration Serverwill not write messages to the client side queue for this JMS connection alias.
Drain CSQ in Order	Whether Integration Server drains the client side queue by sending the messages to the JMS provider in the same order in which Integration Server placed the messages in the client side queue. Select the check box if you want Integration Server to send messages from the client side queue in the same order in which Integration Server originally placed the messages in the client side queue. When the Drain CSQ in Order check box is selected, after the connection to the JMS provider is re-established, Integration Server continues to write new messages to the client side queue until the client side queue is completely drained. If the Drain CSQ in Order check box is not selected, after the connection to the JMS provider is re-established, Integration Server sends new messages directly to the JMS provider while it drains the client side queue. Note: You can also specify the number of messages Integration Server retrieves from the client side queue for delivery to the JMS provider at one time. By default, Integration Server sends 25 messages at a time. For more information about the watt.server.jms.csq.batchProcessingSize property, see Server Configuration Parameters.
Create Temporary Queue	Whether Integration Server creates a temporary queue on the JMS provider to handle request-reply operations that do not specify a replyTo destination. Select the check box if you want Integration Server to create a temporary queue. Clear the check box if you do not want Integration Server to create a temporary queue. You must select the Create Temporary Queue check box if you want to select the Enable Request-Reply Listener for Temporary Queue check box.
Enable Request-Reply Listener for Temporary Queue	Specifies whether or not Integration Server creates a single dedicated MessageConsumer for receiving synchronous replies delivered to the temporary queue for this JMS connection alias. When this check box is cleared, Integration Server creates a new JMS MessageConsumer for each reply message. In many situations, creating one MessageConsumer per response does not impact performance. However, in some situations, such as when many threads invoke pub.jms:sendAndWait concurrently, creating a MessageConsumer for every expected response can impact performance. When this check box is selected, Integration Server creates a dedicated consumer for receiving replies to requests published using this JMS connection alias. For more information about creating a dedicated listener for receiving replies, see Creating a Dedicated Listener for Receiving Replies.
Enable Destination Management with Designer (Broker and Universal Messaging	Whether users can use Designer to create, list, and modify destinations on the webMethods Broker or Universal Messaging when working with JMS triggers. Select the check box if you want Designer users to be able to create, list, and modify destinations using a JMS trigger that uses this JMS connection alias. Software AG recommends that you prevent Designer users from managing destinations in a production environment. For more information about using Designer to manage destinations, see Allowing Destinations to Be Managed through the JMS Connection Alias and Designer.
Create New Connection per Trigger	Whether Integration Server creates a separate connection to the JMS provider for each JMS trigger. Select the check box if you want Integration Server to create a separate connection for each JMS trigger that uses this JMS connection alias. If you want a concurrent JMS trigger that uses this JMS connection alias to use multiple connections to the JMS provider, you must configure the alias to create a separate connection per trigger. For more information, see Allowing Multiple Connections for a JMS Connection Alias.

Under Producer Caching, specify the following to configure pools for caching of JMS Session and MessageProducer objects. For more information about producer caching, see Configuring Producer Caching for Sending JMS Messages.

For this field	Specify
Caching Mode	Whether to enable caching of JMS Session and MessageProducer objects for this connection alias.
	Select...	To...
	DISABLED	Indicate that Integration Server does not cache JMS Session or MessageProducer objects.
	ENABLED PER DESTINATION	Enable caching of JMS Session and MessageProducer objects. For a non-transacted JMS connection alias, Integration Server caches a Session object and a MessageProducer object. For a transacted JMS connection alias, Integration Server caches a Session object.
	Note: Integration Server supports session caching for transacted JMS connection aliases when the JMS provider is Universal Messaging or WebSphere MQ 7.5. For information about Universal Messaging versions supported with this version of Integration Server, see Supported JMS Providers.
Minimum Session Pool Size (unspecified destinations)	The minimum number of entries in the default session pool. The default is 1.
Maximum Session Pool Size (unspecified destinations)	The maximum number of entries in the default session pool. The default is 30.
Minimum Pool Size per Destination	The minimum number of entries in each destination- specific pool.
Maximum Pool Size per Destination	The maximum number of entries in each destination-specific pool. A value of 0 (or blank) indicates that Integration Server does not create separate pools for any of the destinations associated with the JMS connection alias.
Destination Lookup Name List	A semicolon delimited list of the lookup names for the destinations for which you want Integration Server to create separate pools. Note: This field appears only when the JMS connection alias specifies JNDI Lookup for creating the connection to the JMS provider.
Queue List	A semicolon delimited list of the queues for which you want Integration Server to create separate pools. Note: This field only appears when the JMS connection alias specifies Native webMethods API for creating the connection to the webMethods Broker.
Topic List	A semicolon delimited list of the topics for which you want Integration Server to create separate pools. Note: This field only appears when the JMS connection alias specifies Native webMethods API for creating the connection to the webMethods Broker.
Idle Timeout	The number of milliseconds before Integration Server removes an inactive pool entry. The timeout value applies to the default session pool and the destination-specific pools. A value of 0 indicates that pool entries never expire. A value of -1 indicates that Integration Server uses the system default as defined by the watt.server.jms.producer.pooledSession.timeout parameter. This default is 60000 milliseconds

Under Producer Retry, specify the following to configure automatic retry of pub.jms:send services that use this JMS connection alias to send a message to the JMS provider. For more information about automatic retry, see Configuring Automatic Retry when Sending JMS Messages Using the pub.jms:send Service.

For this field	Specify
Max Retry Count	The maximum number of times that Integration Server will automatically retry a pub.jms:send service that fails because of a transient error. A value of 0 indicates that automatic retry is disabled for this JMS connection alias. The default is 0.
Retry Interval (milliseconds)	The number of milliseconds that Integration Server waits between retry attempts. The default is 1000 milliseconds (1 second).

Note: If the JMS connection alias is transacted or uses a connection factory to which the multi-send guaranteed policy is applied, Integration Server ignores the producer retry values.

Under Enhanced Logging, specify the following to configure additional logging for the sending and/or receiving of JMS messages that use this messaging connection alias.

For this field	Specify
Logging Type	Where Integration Server writes log messages when enhanced logging is enabled for the message producers and/or consumers that use this JMS connection alias to send and/or receive messages. SERVER LOG. Write enhanced logging messages to the server log. If you specify the server log as the destination, make sure to increase the logging level for the 0168 Messaging (Enhanced Logging) server log facility to at least Info. MESSAGING AUDIT LOG. Write enhanced logging messages to the messaging audit log. You can select one of the options only. Integration Server cannot write enhanced logging messages to the server log and the messaging audit log.
Enable Producer Message ID Tracking	Select to indicates that Integration Server writes additional log messages when a message producer uses this JMS connection alias to send messages to a destination in Producer Message ID Tracking: Include Destinations.
Producer Message ID Tracking: Include Destinations	The destination names for which Integration Server performs additional logging when sending messages to the destination. Use a semicolon (;) to separate each destination name. Leave this field blank if you want Integration Server to perform enhanced logging for every destination to which this JMS connection alias sends messages.
Enable Consumer Message ID Tracking	Select to indicate that Integration Server writes additional log messages for messaging consumers (triggers) that use this JMS connection alias to receive messages. Integration Server writes additional log message for the JMS triggers listed in Consumer Message ID Tracking: Include Triggers.
Consumer Message ID Tracking: Include Triggers	The fully qualified name of the JMS triggers for which Integration Server performs additional logging during trigger processing. Use a semicolon (;) to separate each trigger name. Leave this field blank if you want Integration Server to perform enhanced logging for every JMS trigger that uses this JMS connection alias to receive messages.

For more information about using enhanced logging for sending and receiving of JMS messages, Using Enhanced Logging for Messaging.

Click Save Changes.
Enable the JMS connection alias.

Allowing Destinations to Be Managed through the JMS Connection Alias and Designer

You can configure the JMS connection alias to enable Designer users to manage destinations and durable subscribers when working with JMS triggers. When the JMS connection alias is configured for managing destinations (i.e., the Enable Destination Management with Designer check box is selected), you can use Designer to create and modify destinations and durable subscribers on webMethods Broker or Software AG Universal Messaging.

Note: The ability to use Designer to manage destinations on Broker or Universal Messaging is a design-time feature. In a production environment, this functionality should be disabled.

To manage destinations on Broker, the following must be true

The JMS connection alias must use Broker as the JMS provider.
Broker must be Broker version 7.1 or higher.
The versions of following three Broker jar files installed on Integration Server must be the 8.0 SP1 or higher versions of the files.
- Software AG_directory /common/lib/wm-brokerclient.jar
- Software AG_directory /common/lib/wm-jmsclient.jar
- Software AG_directory /common/lib/wm-jmsnaming.jar

To manage destinations on Universal Messaging, the following must be true:

The JMS connection alias must use Universal Messaging as the JMS provider.
The Universal Messaging version must be supported with this version of Integration Server. For information about supported versions, see Supported JMS Providers.

For more information about using Designer to modify Destinations on the Broker or Universal Messaging, see webMethods Service Development Help .

Allowing Multiple Connections for a JMS Connection Alias

You can configure a JMS connection alias to instruct Integration Server to create a separate connection to the JMS provider for each JMS trigger that uses the alias. Creating separate connections for individual triggers can improve performance, especially when processing a high volume of messages across many triggers.

By default, an alias creates a single connection to the JMS provider, and each JMS trigger that uses the alias shares the same connection. Integration Server uses this same connection to send JMS messages when executing pub.jms* services that specify the JMS connection alias.

If you select the Create New Connection per Trigger check box when configuring a JMS connection alias, Integration Server creates a new connection to the JMS provider for each JMS trigger that uses the alias. These connections are in addition to the connection that Integration Server uses for sending JMS messages. Therefore, if a JMS connection alias is associated with 3 JMS triggers, there will be a total of 4 connections associated with the alias.

When an alias creates a separate connection for each trigger, you can configure the associated concurrent JMS triggers to obtain multiple connections to the JMS provider, thereby noticeably improving trigger throughput. Keep in mind, however, that each connection used by the trigger requires a dedicated Integration Server thread, regardless of the current throughput.

Note: If you select the Create New Connection per Trigger check box, then the Ignore Locally Published feature on associated JMS triggers will not work. For the trigger to ignore locally published messages, the publisher and subscriber must share the same connection. When the JMS connection alias creates a new connection per trigger, the publisher and subscriber will not share the same connection.

Integration Server supports creating and using multiple connections for a single JMS connection alias with the supported JMS providers. For a list of supported JMS providers, see Supported JMS Providers.

Note: When Integration Server creates multiple connections, Integration Server uses the same client ID for each connection. While the webMethods Broker permits this, some JMS providers do not support the use of multiple connections with the same client ID or require additional configuration to support it. This can be particularly true when working with topics and/or durable subscribers. Review the JMS provider documentation before configuring the JMS connection alias or a JMS trigger to use multiple connections.

To use multiple connections for a single JMS connection alias when using webMethods Broker as the JMS provider, the following must be true:

webMethods Broker must be webMethods Broker version 7.1 or higher.
The versions of following three webMethods Broker jar files installed on Integration Server must be the 8.0 SP1 or higher versions of the files.
- Software AG_directory /common/lib/wm-brokerclient.jar
- Software AG_directory /common/lib/wm-jmsclient.jar
- Software AG_directory /common/lib/wm-jmsnaming.jar

For more information about configuring JMS triggers, see the webMethods Service Development Help in Software AG Designer.

About the Connection Client ID

The connection client ID is the JMS client identifier associated with the connections established by a JMS connection alias. The connection client ID that Integration Server uses for a connection created from a JMS connection alias depends on one or more of the following:

The value of the Connection Client ID field for the JMS connection alias.
The connection client ID specified in the Connection Factory used by the JMS connection alias.
Whether the JMS connection alias is configured to create a new connection for each JMS trigger. That is, whether or not the Create New Connection per Trigger check box is selected.

Using the above information, Integration Server determines the connection client ID as follows:

If only the JMS connection alias specifies the connection client ID, Integration Server uses this value for any connections created from the alias. When connecting to the webMethods Broker natively (the Create Connection Using list is set to Native webMethods API), Integration Server always uses the connection client ID from the JMS connection alias.
If only the Connection Factory specifies the connection client ID, Integration Server uses this value for any connections created from the alias.
If the JMS connection alias and the Connection Factory specify the connection client ID, Integration Server uses the value in the Connection Factory. This is true when working with all JMS providers, including the webMethods Broker.
When the Create New Connection per Trigger check box is not selected, each JMS trigger that uses the JMS connection alias will use the same connection. Each connection will have the same connection client ID.
When the Create New Connection per Trigger check box is selected, each JMS trigger that uses the JMS connection alias will create its own connection to the JMS provider.
- If Integration Server uses the connection client ID in the Connection Factory, each connection for a JMS trigger will have the same connection client ID.
- If Integration Server uses the connection client ID from the JMS connection alias, each connection for a JMS trigger will be unique to the JMS trigger. The connection client ID will consist of the value of the Connection Client ID field in the JMS connection alias plus the fully qualified name of the JMS trigger.

Note: To receive messages in a load balanced manner, each JMS trigger must connect to the webMethods Broker using the same connection client ID. Because the Create New Connection per Trigger option can change the connection client ID, you must be sure that use of this option is consistent across all Integration Servers across the Integration Server group.

Creating a Dedicated Listener for Receiving Replies

Integration Server includes the ability to create a dedicated consumer for receiving replies to a published request. You configure this functionality per JMS messaging connection alias.

When the pub.jms:sendAndWait service executes a synchronous request-reply, Integration Server sends the request message to the JMS provider and waits for a reply. By default Integration Server creates a new JMS MessageConsumer for each reply message. In many situations, creating one MessageConsumer per response does not impact performance. However, in some situations, such as when many threads invoke pub.jms:sendAndWait concurrently, creating a MessageConsumer for every expected response can impact performance.

To address this, Integration Server includes an option named Enable Request-Reply Listener for Temporary Queue that, when selected, creates a single dedicated MessageConsumer for receiving synchronous replies sent by the JMS connection alias. If Integration Server uses a single consumer to retrieve all synchronous replies for requests sent by a particular JMS connection alias, when executing pub.jms:sendAndWait service, Integration Server assigns a unique value to the new wm_tag field used as a property in the JMS message, specificallyJMSMessage/properties/wm_tag. When using pub.jms:reply to reply to a JMS message request for which wm_tag is populated, the replying Integration Server maps the value of wm_tag to JMSMessage/header/JMSCorrelationID field in the reply message.

To use a dedicated consumer to retrieve replies to all requests sent using a particular JMS connection alias, the following must be true:

The JMS connection alias used to send the request must have the following configured:
- The Create Temporary Queue check box must be selected.
- The Enable Request-Reply Listener for Temporary Queue check box must be selected. This is a new option for a JMS connection alias.
The pub.jms:sendAndWait invocation:
- Must be synchronous (the async input parameter must be set to false).
- Must not specify a value for the destinationNameReplyTo input parameter.

Configuring Producer Caching for Sending JMS Messages

When sending a JMS message, Integration Server creates and closes a new JMS Session object and a JMS MessageProducer object for each message. This can introduce overhead for some JMS providers. To improve performance when sending JMS messages, you can configure producer-side pooling. For each JMS connection alias, Integration Server can create the following:

A default session pool containing JMS Session objects. When a default session pool is defined for a JMS connection alias, Integration Server draws from a pool of open JMS Sessions for sending a JMS message instead of opening and closing a JMS Session for each JMS message. Integration Server uses the default session pool only when sending a message to a destination that does not have its own pool. When using the default session pool, Integration Server creates a new MessageProducer each time it sends a JMS message.
Destination-specific pools for sending JMS messages to specific destinations. Integration Server creates a pool for each specified destination. The composition of a destination-specific pool varies depending on the transaction type of the JMS connection alias.
- For a non-transacted JMS connection alias, an entry in a destination-specific pool consists of a Session object and a MessageProducer object. When sending a JMS message to one of the specified destinations, Integration Server uses a Session object and MessageProducer object from the pool instead of creating and closing a Session object and MessageProducer object for each JMS message.
- For a transacted JMS connection alias, an entry in a destination-specific pool contains a Session object. When sending a JMS message to one of the specified destinations, Integration Server uses a Session object from the pool instead of creating and closing a Session object for each JMS message. Integration Server creates a new MessageProducer each time it sends a JMS message.
  Note: Integration Server supports session caching for transacted JMS connection aliases when the JMS provider is Universal Messaging or WebSphere MQ 7.5. For information about Universal Messaging versions supported with this version of Integration Server, see Supported JMS Providers.

You can specify the minimum and maximum sizes for the default session pool and all destination pools. Additionally, you can identify the destinations for which Integration Server creates specific pools. If the JMS connection alias specifies the use of a connection factory object to connect to the JMS provider, you specify a single list of destinations. If the JMS connection alias specifies the Native webMethods API for connecting to the webMethods Broker, you must specify separate lists for the queues and topics for which you want Integration Server to create destination pools.

Consider the following examples that explain how Integration Server creates session and destination pools based on the information specified for transacted and non-transacted connection aliases:

Example of creating session and destination pools for a non-transacted JMS connection alias

Suppose that a non-transacted JMS connection alias named "myAlias" connects to the webMethods Broker using the Native webMethods API and the fields are set as described in the following table.:

Field	Value
Minimum Pool Size	1
Maximum Pool Size	10
Minimum Pool Size per Destination	1
Maximum Pool Size per Destination	5
Queue List	myQueue1; myQueue2
Topic List	myTopic
Idle Timeout	70000

Using the above information, Integration Server creates a default session pool with a minimum size of 1 and a maximum size of 10. This pool contains JMS Session objects only. Integration Server uses an entry from the pool when sending a message to destination that does not have its own pool.

Integration Server also creates three destination pools: one each for the queues myQueue1 and myQueue2, and one for the topic myTopic. Each of these pools has a maximum size of 5 pool entries. Messages sent to the destinations myQueue1, myQueue2, or myTopic will use an entry (a Session object and MessageProducer object) from the pool created for the destination. Messages sent to other destinations will use a Session from the default session pool.

An entry in the default or destination-specific pools expires after the entry has been inactive for over 70000 milliseconds (70 seconds).

Example of creating session and destination pools for a transacted JMS connection alias

Suppose that a transacted JMS connection alias named "myAlias1" connects to WebSphere MQ 7.5 using JNDI and the fields are set as described in the following table:

Field	Value
Minimum Pool Size	1
Maximum Pool Size	15
Minimum Pool Size per Destination	1
Maximum Pool Size per Destination	10
Destination Lookup Name List	myQueue1; myQueue2; myTopic1
Idle Timeout	80000

Using the above information, Integration Server creates a default session pool with a minimum size of 1 and a maximum size of 15. This pool contains JMS Session objects only. Integration Server uses an entry from the pool when sending a message to destination that does not have its own pool.

Integration Server also creates three destination pools: one each for the queues myQueue1 and myQueue2, and one for the topic myTopic1. Each of these pools has a maximum size of 10 pool entries. Messages sent to the destinations myQueue1, myQueue2, or myTopic1 will use an entry (a Session object) from the pool created for the destination. Messages sent to other destinations will use a Session from the default session pool.

An entry in the default or destination-specific pools expires after the entry has been inactive for over 80000 milliseconds (80 seconds).

Configuring Automatic Retry when Sending JMS Messages Using the pub.jms:send Service

You can configure a JMS connection alias so that Integration Server automatically retries a pub.jms:send service that uses the JMS connection alias if the service fails because of a transient error. To configure automatic retry for instances of the pub.jms:send service that use a particular JMS connection alias to send messages to the JMS provider, you specify the following for the alias:

Maximum number of retry attempts. The Max Retry Count field determines the maximum number of times that Integration Server will retry a particular pub.jms:send service. A Max Retry Count of 0 indicates that automatic retry is disabled for the JMS connection alias.
Interval between retry attempts. The Retry Interval field determines the number of milliseconds that Integration Server waits between retry attempts. The default interval is 1000 milliseconds (1 second).

The JMS connection alias must also meet the following criteria for a pub.jms:send service that uses the alias to be retried after a transient error:

The JMS connection alias must be enabled.
The JMS connection alias must have a transaction type of NO_TRANSACTION. Integration Server will not retry a pub.jms:send service that is executed as part of a transaction.
If the JMS connection alias specifies the Broker as the JMS provider, the JMS connection alias must not use a cluster connection factory to which the multisend guaranteed policy is applied.

The following table describes the retry process that Integration Server uses when the the JMS connection alias is configured for retry and the pub.jms:send service fails because of a transient error.

Stage	Description
1	Execution of the pub.jms:send service fails because of a transient error.
2	Integration Server waits the length of the retry interval. Note: If Integration Server begins to shut down while waiting to retry, Integration Server interrupts the waiting period and retries the service. Note: If the JMS connection alias becomes disabled while Integration Server waits to retry, Integration Server interrupts the retry process. Depending on whether the client side queue is enabled for the JMS connection alias, either writes the JMS message to the client side queue or throws the original exception that caused the pub.jms:send service to fail. For more information, see the description for stage 5, which follows.
3	Integration Server re-executes the pub.jms:send service.
4	If the pub.jms:send service fails again because of a transient error Integration Server repeats steps 2 and 3 until one of the following occurs: The pub.jms:send service executes successfully. Retry failure occurs because the maximum number of retry attempts have been made.
5	If retry failure occurs, Integration Server will do one of the following depending on whether or not the JMS connection alias uses a client side queue: If the client side queue is in use, Integration Server writes the message created by the pub.jms:send service to the client side queue. If the client side queue is not in use, Integration Server throws the original exception thrown by the JMS provider. Note: A client side queue is in use if the JMS connection alias has a Maximum CSQ Size value greater than 0 (zero) and the `useCSQ` input parameter is set to true for the pub.jms:send service.

About Retrying the pub.jms:send Service when Software AG Universal Messaging Is the JMS Provider

When the JMS connection alias is configured to retry the pub.jms:send service upon transient error and Universal Messaging is the JMS provider, Integration Server may make some changes to the local instance of the Universal Messaging connection factory to prevent or at least delay an exception from being thrown by Integration Server. Integration Server makes changes so that if Integration Server loses its connection to the Universal Messaging cluster, Integration Server does not throw an exception right away. Instead, Universal Messaging suppresses the exception for a period of time. During this time, Universal Messaging attempts to restore the cluster quorum. Concurrently, Integration Server attempts to re-establish a connection to Universal Messaging. During this delay, Integration Server is not notified of the exception and the JMS connection alias will not be stopped. However, JMS triggers that use the JMS connection alias will not receive any messages. Additionally, any pub.jms:send services that were in the midst of using the JMS connection alias to send a message will be retried based on the retry interval and retry count set for the JMS connection alias. If Universal Messaging cannot restore a cluster quorum, Integration Server throws the exception. At this point, any JMS trigger that uses the JMS connection alias will be stopped and any services that send JMS messages using the JMS connection alias will throw exceptions immediately. Integration Server then attempts to reconnect to Universal Messaging.

Integration Server makes changes to the Universal Messaging connection factory if the connection factory has a MaxReconAttempts property set to -1. (A value of -1 is the default and suggests that the MaxReconAttempts value has not been changed on Universal Messaging.) Integration Server makes the following changes to the local instance of the Universal Messaging connection factory:

Sets ConxExceptionOnFailure to true.
Sets MaxReconAttempts to 35.
Sets ReconnectInterval to 2000 milliseconds.

Integration Server makes changes to the local instance of the Universal Messaging connection factory only. The ConnectionFactory will not be changed on the JNDI provider, which means that other clients that use the ConnectionFactory will not be impacted.

To prevent Integration Server from making changes to the local instance of the Universal Messaging connection factory, use the Universal Messaging Enterprise Manager to set the MaxReconAttempts property to a value greater than -1.

Editing a JMS Connection Alias

About this task

After you create a JMS connection alias, you might need to modify properties of the alias you created or a default alias. For example, you might want to reduce the amount of memory that the client side queue can occupy by decreasing the maximum number of messages that can be placed in the client side queue. You can edit any properties of a JMS connection alias with the exception of the alias name.

Keep the following information in mind when editing a JMS connection alias:

You must disable a JMS connection alias before you can edit it.
Because Integration Server uses the connection client ID as the first part of the durable subscriber name, changing the connection client ID results in the creation of durable subscribers for triggers that use the alias. The durable subscribers that use the old connection client ID as part of the name are not automatically removed from Universal Messaging. Old durable subscribers might contain messages and continue to receive messages.

To edit a JMS connection alias

Procedure

Open Integration Server Administrator if it is not already open.
In the Settings menu of the Navigation panel, click Messaging.
Under JMS Configuration, click JMS Settings.
In the JMS Connection Alias Definitions list, select the JMS connection alias that you want to edit. Integration Server Administrator displays details about the connection alias.
Click Edit JMS Connection Alias.
Edit the properties of the connection alias. For more information about the fields, see Creating a JNDI Provider Alias. Note that the Connection Alias Name field cannot be modified.
Click Save Changes.

Enabling and Disabling a JMS Connection Alias

About this task

When a JMS connection alias is enabled, Integration Server can use the alias to obtain connections, send messages, and receive messages on behalf of services and JMS triggers. When a connection alias is disabled, Integration Server suspends all JMS triggers that use the alias. Additionally, any services that use a disabled JMS connection alias to send or receive messages will end in error.

To enable or disable a JMS connection alias

Procedure

Open Integration Server Administrator if it is not already open.
In the Settings menu of the Navigation panel, click Messaging.
Under JMS Configuration, click JMS Settings.
In the JMS Connection Alias Definitions list, do one of the following in the Enabled column:
- Click No if the alias is disabled and you want to enable it.
  
  If Integration Server cannot enable the alias, it displays a message under the alias indicating why Integration Server cannot enable the alias.
- Click Yes if the alias is enabled and you want to disable it.

Deleting a JMS Connection Alias

About this task

Before you delete a JMS connection alias, make sure of the following:

The JMS connection alias is disabled.
No services or JMS triggers rely on the JMS connection alias. If a JMS trigger uses a JMS connection alias, Integration Server will prevent the JMS connection alias from being deleted.

To delete a JMS connection alias

Procedure

Open Integration Server Administrator if it is not already open.
In the Settings menu of the Navigation panel, click Messaging.
Under JMS Configuration, click JMS Settings.
In the JMS Connection Alias Definitions list, disable the alias if it is not already disabled.
Locate the alias you want to delete and click in the Delete column. Integration Server displays a dialog box that prompts you to verify your action. Click OK to verify that you want to delete the JMS connection alias.

Specifying a Connection Monitoring Period

Integration Server periodically checks the state of an active connection to the JMS provider. You can configure how frequently Integration Server checks the connection status using the watt.server.jms.connection.monitorPeriod property. The default is 45 seconds.

If the connection between Integration Server and the JMS provider fails, Integration Server attempts to re-establish the connection automatically after a 20 second delay. You can configure how long Integration Server waits between attempts to re-establish the connection by changing the value of the watt.server.jms.connection.retryPeriod property

For more information about server configuration parameters, see Server Configuration Parameters.

Specifying a Retry Interval for Failed Connections

When a connection between Integration Server and the JMS provider fails, Integration Server attempts to re-establish the connection automatically after a 20 second delay. You can configure how long Integration Server waits between attempts to re-establish the connection by changing the value of the watt.server.jms.connection.retryPeriod property. For more information about this property, see watt.server..

Specifying a Keep-Alive Interval

Integration Server periodically pings the JMS provider to keep the connection between the Integration Server and the JMS provider active. The ping acts as a keep-alive request. By default, Integration Server pings the JMS provider every 300 seconds. You can configure how frequently Integration Server pings the JMS provider by changing the value of the watt.server.jms.connection.pingPeriod property. For more information about this property, see watt.server..