Software AG Products 10.5 | Using API Gateway | API Gateway Administration | General Configuration | Messaging | Creating a JMS Connection Alias
 
Creating a JMS Connection Alias
A JMS connection alias specifies the information that API Gateway needs to establish an active connection between API Gateway and the JMS/AMQP provider. API Gateway uses a JMS connection alias to send messages to and receive messages from the JMS/AMQP provider. 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.
*Each JMS connection alias has an associated transaction type. Within API Gateway, certain functionality must be completed within a non-transacted session. For example, to use API Gateway to send or receive large message streams, you must specify a JMS connection alias whose transaction type is set to NO_TRANSACTION.
*To create a JMS connection alias
1. Expand the menu options icon , in the title bar, and select Administration.
2. Select General > Messaging.
API Gateway displays a list of all the currently defined JNDI provider alias definitions, JMS connection alias definitions and individual SOAP JMS trigger controls.
3. Click Add JMS connection alias under JMS connection alias definitions section.
4. In the General Settings section, provide the following information:
Field
Description
Connection alias name
Name of the connection alias.
This name should be unique as each connection alias represents a connection factory to a specific JMS provider.
Description
A description of the JMS connection alias.
Transaction type
Specifies whether the sessions that use this JMS connection alias are transacted.
Available values are:
*NO_TRASACTION. Indicates that sessions that use this JMS connection alias are not transacted.
*LOCAL_TRASACTION. Indicates that sessions that use this JMS connection alias are part of a local transaction.
*XA_TRASACTION. Indicates 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.
Username
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.
5. In the Connection protocol settings section, provide the following information:
Field
Description
JNDI provider alias name
The alias to the JNDI provider that you want this JMS connection alias to use to look up administered objects.
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)
Specifies whether API Gateway creates administered objects on the JNDI provider if the object is not found when API Gateway looks up the object.
Select the check box if you want API Gateway to create a destination or connection factory when an JNDI lookup for the object fails.
Enable follow the master (Universal Messaging)
Specifies 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.
You can do one of the following:
*Select the Enable follow the master check box to indicate that API Gateway connects to the master realm server in the Universal Messaging cluster when API Gateway uses this JMS connection alias to send or receive messages.
*Clear the Enable follow the master check box to disable the follow the master behaviour for this JMS connection alias when API Gateway uses this JMS connection alias to send or receive messages.
Note:
Enable follow the master option is available to JMS connection aliases that use Universal Messaging as the JMS provider.
Monitor webMethods connection factory
Specifies how API Gateway 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 one of the following available options:
*No. Indicates that API Gateway does not monitor the connection factory. This is the default option.
*Poll for changes (specify interval). Monitors the connection factory by polling the changes at an interval that you specify.
*Poll for changes (interval defined by webMethods Connection Factory). Monitors the connection factory at an interval determined by the refresh interval specified for the webMethods Connection Factory object.
*Register change listener. Monitors the connection factory by registering an event listener.
6. In the Advanced settings section, provide the following information:
Field
Description
Class loader
The name of the class loader that you want to use with this JMS connection alias. API Gateway uses 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, and so on.)
By default, API Gateway uses the server class loader. However, you can specify the class loader for a package instead. 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. API Gateway 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, API Gateway does not write messages to the client side queue for this JMS connection alias.
Drain CSQ in order
Specifies whether API Gateway drains the client side queue by sending the messages to the JMS provider in the same order in which API Gateway placed the messages in the client side queue.
Select the check box if you want API Gateway to send messages from the client side queue in the same order in which API Gateway 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, API Gateway 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, API Gateway sends new messages directly to the JMS provider while it drains the client side queue.
Note:
You can also specify the number of messages API Gateway retrieves from the client side queue for delivery to the JMS provider at one time. By default, API Gateway sends 25 messages at a time.
Create temporary queue
Specifies whether API Gateway 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 API Gateway to create a temporary queue. Clear the check box if you do not want API Gateway 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 API Gateway creates a single dedicated MessageConsumer for receiving synchronous replies delivered to the temporary queue for this JMS connection alias.
When this check box is selected, API Gateway creates a dedicated consumer for receiving replies to requests published using this JMS connection alias.
When this check box is cleared, API Gateway creates a new JMS MessageConsumer for each reply message.
Enable destination management with designer (Broker and Universal Messaging)
Specifies whether users can use Designer to create, list, and modify destinations on the webMethods Broker or 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.
Note:
Software AG recommends that you prevent Designer users from managing destinations in a production environment.
Create new connection per trigger
Specifies whether API Gateway creates a separate connection to the JMS provider for each JMS trigger.
Select the check box if you want API Gateway 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.
7. In the Producer caching section, provide the following information to configure pools for caching of JMS Session and MessageProducer objects:
Field
Description
Caching Mode
Specifies whether to enable caching of JMS Session and MessageProducer objects for this connection alias.
Select one of the following:
*DISABLED. Indicates that API Gateway 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, API Gateway caches a Session object and a MessageProducer object. For a transacted JMS connection alias, API Gateway caches a Session object.
Minimum pool size (unspecified destinations)
The minimum number of entries in the default session pool.
The default is 1.
Maximum pool size (unspecified destinations)
The maximum number of entries in the default session pool.
The default is 30.
Minimum poolsize per destination
The minimum number of entries in each destination-specific pool.
Maximum poolsize per destination
The maximum number of entries in each destination-specific pool.
A value of 0 (or blank) indicates that API Gateway does not create separate pools for any of the destinations associated with the JMS connection alias.
Destination lookup names (semicolon delimited)
A semicolon delimited list of the lookup names for the destinations for which you want API Gateway 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.
Idle timeout (ms)
The number of milliseconds before API Gateway 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 API Gateway uses the system default as defined by the watt.server.jms.producer.pooledSession.timeout parameter.
The default value is 60000 milliseconds.
8. In the Producer retry section, provide the following information to configure automatic retry of pub.jms:send services that use this JMS connection alias to send a message to the JMS provider:
Field
Description
Maximum Retry attempts
The maximum number of times that API Gateway automatically retries a pub.jms:send service that fails because of a transient error.
The default value is 0. A value of 0 indicates that automatic retry is disabled for this JMS connection alias.
Retry interval (ms)
The number of milliseconds that API Gateway 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, API Gateway ignores the producer retry values.
9. In the Enhanced logging section, provide the following information to configure additional logging for the sending or receiving of JMS messages that use this messaging connection alias:
Field
Description
Logging type
Specifies where API Gateway writes log messages when enhanced logging is enabled for the message producers or consumers that use this JMS connection alias to send or receive messages.
You can select one of the following:
*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.
Enable producer message ID tracking
Select to indicate that API Gateway 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.
Enable consumer message ID tracking
Select to indicate that API Gateway writes additional log messages for messaging consumers (triggers) that use this JMS connection alias to receive messages. API Gateway writes additional log message for the JMS triggers listed in Consumer Message ID Tracking: Include Triggers
Producer message ID tracking: include destinations (semicolon delimited)
The destination names for which API Gateway performs additional logging when sending messages to the destination.
Use a semicolon (;) to separate each destination name. Leave this field blank if you want API Gateway to perform enhanced logging for every destination to which this JMS connection alias sends messages.
Consumer message ID tracking: include triggers (semicolon delimited)
The fully qualified name of the JMS triggers for which API Gateway performs additional logging during trigger processing.
Use a semicolon (;) to separate each trigger name. Leave this field blank if you want API Gateway to perform enhanced logging for every JMS trigger that uses this JMS connection alias to receive messages.
10. Click Add.
The JMS connection alias created is listed in a table under JMS connection alias definitions in the Messaging page.