JMS Client Configuration

This topic describes the configuration properties for JMS Client connectors.

Categories

The following tables list the JMS client configuration properties as displayed in the NetBeans IDE configuration dialogs. These tables provide a cross-reference to the property descriptions in the following section, which are categorized by consumer and producer, and presented alphabetically.

The sections below describe the JMS client connector properties in detail, and supplement the information given in Configuring JMS Clients.

Consumers

Action

The Action property specifies the action to take following a specified number of unsuccessful attempts to deliver a message. This property specifies whether to move (redirect) or delete the message after the number of retries specified in Delay. See Message Redelivery and Redirection for additional information.

Allowed Values

The allowed values are move, delete, and no final action.

Default Value

The default is no final action, which specifies continued retries until the message is received.

Concurrency

The Concurrency property specifies whether the message consumers use connection consumer or serialized processing. To use concurrent processing for a connection, select the Connection consumer setting. To use serial execution, select the Serial mode setting. This property applies to topic subscribers and queue receivers, and is specified in the Basic properties dialog.

You can configure JMS clients to use connection consumers to improve message throughput through concurrent processing. Connection consumers consume messages that are specified by a destination and an optional message selector. See Message Selector.

To start processing, a connection consumer gets a server session from its pool and loads the session with a message. Server sessions associate a JMS session with a thread. The server session pool is a set of server sessions provided to a connection consumer to process its messages.

The use of connection consumers increases message processing performance by enabling concurrent processing using multiple threads. You can specify the number of message driven beans (MDBs) or server session pool to assign to a JMS Collaboration to process messages concurrently. When you use connection consumer with fully concurrent or protected concurrent FIFO processing, this setting allows the integration server to assign multiple threads to execute the Collaboration on a particular message destination.

For queues, you can also use connection consumers for concurrent processing on multiple CPUs and application servers on a single system. This configuration does affect FIFO processing. For information, refer to Message Processing Order.

You specify the maximum number of threads per server session pool as described in Server Session Pool Size. By default, the maximum number of threads is 5.

The maximum number of messages that a connection consumer can load into a server session at one time is set at 1 and cannot be changed (see Server Session Batch Size).

Default Value

The default JMS client concurrency mode is Serial mode.

Delay

The Delay property specifies the delay(s) to apply following a specified number of unsuccessful attempts to deliver a message. The format is retries:delay, where the number of retries is counted from the original rollback and the delay time is in milliseconds. Progressive delays can be specified by concatenating retry:delay pairs separated by a comma and a space:

retry:delay, retry:delay, …, retry:delay

This property applies to topic subscribers and queue receivers, and is specified in the Redelivery Handling properties dialog. See Message Redelivery and Redirection for additional information.

Allowed Values

The maximum allowed delay is five seconds (5000 ms).

Default Value

By default, no value is specified.

Durable Subscriber Name

The Durable Subscriber Name property, which is specified in the root JMS Client properties dialog, both provides a name for the JMS client and identifies it as being a durable subscriber.

A durable subscription is one that is not dependent upon a client’s connection with a message server. Therefore, it is tolerant of disconnections, whether they are intentional or not. When a durable subscriber is disconnected from the message server, the server stores messages until the subscriber reconnects. It then delivers all accumulated messages that have not expired. This process is also known as store-and-forward messaging.

Once set, the Durable Subscriber Name does not get autogenerated, and can only be changed manually. Copies of the Connectivity Map also retain this name.

Durability

The Durability property specifies whether or not the subscriber to this JMS connection is durable. When a subscriber is nondurable, the client sees messages on a topic only when the subscriber is active. If messages are published when the subscriber is inactive, the messages are lost. This property applies to topic subscribers only, and is specified in the Basic properties dialog.

When a subscriber is durable, messages are not lost even when the subscriber is inactive because the message server retains the messages until they are retrieved by the subscriber or until the messages expire. A durable subscriber registers with the message server as a durable subscriber with the name source_destination, for example, topicA_CollaborationA. When a subscriber becomes inactive, the message server retains the unexpired messages for a subsequent subscriber object with the same identity to resume the subscription. Note that there is a trade-off in performance.

Allowed Values

Durable or Nondurable.

Default Value

By default, JMS client connections are Durable.

Message Selector

The Message selector property specifies message selectors for the JMS client. This property applies to topic subscribers and queue receivers, and is specified in the Basic properties dialog.

To specify a message selector, enter a message selector String according to the JMS specification syntax. For example:

JMSType =’car’ AND color =’blue’

Identifier start characters must be characters for which the Character.isJavaIdentifierStart method returns true according to the JMS specification. If the identifier is invalid, the Java CAPS Monitor might show invalid message property names.

Move/Delete After N Times

The Move/Delete After N Times property specifies the number of retries to allow before redirecting or deleting the message, as specified in Action. The action is taken on the retry number entered for the property value.

This property applies to topic subscribers and queue receivers, and is specified in the Redelivery Handling properties dialog. See Message Redelivery and Redirection for additional information.

Allowed Values

Any number.

Default Value

By default, no value is specified.

Move to Queue/Topic

The Move to Queue/Topic property specifies whether to redirect the message to a queue or a topic, following the number of retries specified in Move/Delete After N Times.

This property applies to topic subscribers and queue receivers, and is specified in the Redelivery Handling properties dialog. See Message Redelivery and Redirection for additional information.

Allowed Values

The allowed values are queue, topic, and auto, which specifies the same kind of message destination as the message producer.

Default Value

By default, the destination is specified as auto.

Move to Destination Name

The Move to Destination Name property specifies a queue or topic name to which the message is to be redirected. The special character $ specifies the original destination name.

This property applies to topic subscribers and queue receivers, and is specified in the Redelivery Handling properties dialog. See Message Redelivery and Redirection for additional information.

Allowed Values

Any string.

Default Value

By default, no value is specified.

Server Session Batch Size

The Server session batch size property specifies the maximum number of messages that a connection consumer can load into a server session at one time. This property applies to topic subscribers and queue receivers, and is specified in the Advanced properties dialog. By default, this property is set to 1 and cannot be changed.

Server Session Pool Size

The Server session pool size property specifies the maximum number of threads per ServerSessionPool to be used for concurrent processing. This property applies to topic subscribers and queue receivers, and is specified in the Advanced properties dialog.

This property is used in conjunction with the connection consumer setting of the Concurrency property, as described in Concurrency). You can specify the number of message driven beans (MDBs) or server session pool to assign to a JMS Collaboration to process messages concurrently. When you use connection consumer with fully concurrent or protected concurrent FIFO processing, this connection consumer configuration allows the integration server to assign multiple threads to execute the Collaboration on a particular message destination.

For an overview about message processing, refer to Message Processing Order.

Allowed Values

An integer of 1 or larger, depending on the capability of the system, indicating the number of threads.

Default Value

By default, the maximum number of threads per server session pool is 5.

Producers

Delivery Mode

The Delivery mode property specifies whether the messages for this JMS connection are persistent or non-persistent. This property applies to topic publishers and queue senders, and is specified in the Basic properties dialog.

Non-persistent delivery mode is the most efficient delivery mode, because it does not require messages to be saved to permanent storage. Per JMS specification, the message destination delivers non-persistent messages with an at-most-once guarantee. The message is only delivered once, even if it is lost. This mode involves a trade-off between performance and reliability. Non-persistence offers better performance but if a message server fails, messages may be lost due to a power outage.

When messages are persistent, the message server places the message in permanent storage to ensure the message is not lost in transit if the message server fails. Persistent messages are delivered once, and only once.

For the JMS IQ Manager, persistent messages are stored in the message server database files.

Default Value

The default delivery mode is Persistent.

Idle Timeout

The Idle timeout property specifies the amount of time, in seconds, to wait before returning a connection to the pool. This property applies to topic publishers and queue senders, and is specified in the Basic properties dialog.

Default Value

The default timeout is 30 seconds.

Maximum Pool Size

The Maximum pool size property specifies the maximum number of connections to be made to the message server. This property applies to topic publishers and queue senders, and is specified in the Basic properties dialog.

Default Value

The default size is 32.

Maximum Wait Time

The Maximum wait time property specifies the maximum amount of time, in milliseconds, to wait for acquiring a connection before throwing an exception. This property applies to topic publishers and queue senders, and is specified in the Basic properties dialog.

Default Value

The default time is 30000 milliseconds.

Priority

The Priority property specifies the message priority level for the JMS client. The message priority level that you specify causes all messages produced by this client to have that same priority level. For example, if you set the priority level to 2, all messages sent by that client have message priority level 2. This property applies to topic publishers and queue senders, and is specified in the Basic properties dialog.

You can also specify message priorities in Collaborations with the JMS OTD with the setPriority method. Collaboration message priorities override JMS client message priorities. For more information, refer to Configuring JMS Clients.

Allowed Values

An integer between 0 and 9, where 0 through 4 is normal priority and 5 through 9 is expedited priority.

Default Value

The default delivery mode is 4.

Steady Pool Size

The Steady pool size property specifies the minimum, and initial, number of connections maintained in the pool. This property applies to topic publishers and queue senders, and is specified in the Basic properties dialog.

Default Value

The default is 4 connections.

Transaction Mode

The Transaction mode property specifies the transaction mode used for message producers. For consumers, this mode is always XA. This property applies to topic publishers and queue senders, and is specified in the Basic properties dialog.

The Transaction mode property specifies whether messages for this JMS client use one of the following transaction modes:

• Transacted Mode

  When you set the transaction mode to Transacted, the Java Collaboration Definition uses a new, separate transacted JMS session to send and receive messages. The message is committed automatically, and cannot be rolled back (even by raising an exception).

• XA Mode

  When the transaction mode is set to XA, the JMS session becomes part of the existing transaction, and is processed according to the XA two-phase commit protocol. In the first phase, the resource manager sends a query to commit to the receivers and waits for the receivers to respond with a confirmation. In the second phase, the resource manager receives confirmation from all receivers, and commits the message to all receivers. This setting prevents message loss and duplicate messages, even when a system unexpectedly shuts down.

Allowed Values

Transacted or XA.

Default Value

The default transaction mode is XA.

Documentation on distributed transaction processing using XA is available at no charge from The Open Group at http://www.opengroup.org (search on “XA”).