Appendix B. Client Connection Options
Overview
When creating a connection to a broker, a client can use the connection URI to configure a number of the connection properties. The properties are added to the connection URI as matrix parameters on the URI as shown in Example B.1, “Client Connection Options Syntax”.
Example B.1. Client Connection Options Syntax
URI?jms.option?jms.option...
Important
All of the client connection options are prefixed with
jms.
Options
Table B.1, “Client Connection Options” shows the client connection options.
| Option | Default | Description |
|---|---|---|
alwaysSessionAsync | true | Specifies if a separate thread is used for dispatching messages for each Session in the Connection. However, a separate thread is always used if there is more than one session, or the session isn't in auto acknowledge or dups ok mode. |
clientID | Specifies the JMS clientID to use for the connection. | |
closeTimeout | 15000 | Specifies the timeout, in milliseconds, before a connection close is considered complete. Normally a close() on a connection waits for confirmation from the broker; this allows that operation to timeout and save the client from hanging if there is no broker. |
copyMessageOnSend | true | Specifies if a JMS message should be copied to a new JMS Message object as part of the send() method in JMS. This is enabled by default to be compliant with the JMS specification. Disabling this can give you a performance, however you must not mutate JMS messages after they are sent. |
disableTimeStampsByDefault | false | Specifies whether or not timestamps on messages should be disabled or not. Disabling them it adds a small performance boost. |
dispatchAsync | false | Specifies if the broker dispatches messages to the consumer asynchronously. |
nestedMapAndListEnabled | true | Enables/disables whether or not structured message properties and MapMessages are supported so that Message properties and MapMessage entries can contain nested Map and List objects. |
objectMessageSerializationDefered | false | Specifies that the serialization of objects when they are set on an ObjectMessage is deferred. The object may subsequently get serialized if the message needs to be sent over a socket or stored to disk. |
optimizeAcknowledge | false | Specifies if messages are acknowledged in batches rather than individually. Enabling this could cause some issues with auto-acknowledgement on reconnection. |
optimizeAcknowledgeTimeOut | 300 | Specifies the maximum time, in milliseconds, between batch acknowledgements when optimizeAcknowledge is enabled. |
optimizedMessageDispatch | true | Specifies if a larger prefetch limit is used for durable topic subscribers. |
useAsyncSend | false | Specifies in sends are performed asynchronously. Asynchronous sends provide a significant performance boost. The tradeoff is that the send() method will return immediately whether the message has been sent or not which could lead to message loss. |
useCompression | false | Specifies if message bodies are compressed. |
useRetroactiveConsumer | false | Specifies whether or not retroactive consumers are enabled. Retroactive consumers allow non-durable topic subscribers to receive messages that were published before the non-durable subscriber started. |
warnAboutUnstartedConnectionTimeout | 500 | Specifies the timeout, in milliseconds, from connection creation to when a warning is generated if the connection is not properly started and a message is received by a consumer. -1 disables the warnings. |
auditDepth | 2048 | Specifies the size of the message window that will be audited for duplicates and out of order messages. |
auditMaximumProducerNumber | 64 | Specifies the maximum number of producers that will be audited. |
alwaysSyncSend | false | Specifies if a message producer will always use synchronous sends when sending a message. |
blobTransferPolicy.* | Used to configure how the client handles blob messages. See the section called “Blob handling”. | |
prefetchPolicy.* | Used to configure the prefect limits. See the section called “Prefetch limits”. | |
redeliveryPolicy.* | Used to configure the redelivery policy. See the section called “Redelivery policy”. |
Blob handling
Blob messages allow the broker to use an out of band transport to pass large files between clients. Table B.2, “Blob Message Properties” describes the connection URI options used to configure how a client handles blob messages.
Important
All of the prefetch options are prefixed with
jms.blobTransferPolicy.
| Option | Description |
|---|---|
bufferSize | Specifies the size of the buffer used when uploading or downloading blobs. |
uploadUrl | Specifies the URL to which blob messages are stored for transfer. This value overrides the upload URI configured by the broker. |
Prefetch limits
The prefetch limits control how many messages can be dispatched to a consumer and waiting to be acknowledged. Table B.3, “Connection URI Prefect Limit Options” describes the options used to configure the prefetch limits of consumers using a connection.
Important
All of the prefetch options are prefixed with
jms.prefetchPolicy.
| Option | Description |
|---|---|
queuePrefetch | Specifies the prefect limit for all consumers using queues. |
queueBrowserPrefetch | Specifies the prefect limit for all queue browsers. |
topicPrefetch | Specifies the prefect limit for non-durable topic consumers. |
durableTopicPrefetch | Specifies the prefect limit for durable topic consumers. |
all | Specifies the prefect limit for all types of message consumers. |
Redelivery policy
The redelivery policy controls the redelivery of messages in the event of connectivity issues. Table B.4, “Redelivery Policy Options” describes the options used to configure the redelivery policy of consumers using a connection.
Important
All of the prefetch options are prefixed with
jms.redeliveryPolicy.
| Option | Default | Description |
|---|---|---|
collisionAvoidanceFactor | 0.15 | Specifies the percentage of range of collision avoidance. |
maximumRedeliveries | 6 | Specifies the maximum number of times a message will be redelivered before it is considered a poisoned pill and returned to the broker so it can go to a dead letter queue. -1 specifies an infinite number of redeliveries. |
maximumRedeliveryDelay | -1 | Specifies the maximum delivery delay that will be applied if the useExponentialBackOff option is set. -1 specifies that no maximum be applied. |
initialRedeliveryDelay | 1000 | Specifies the initial redelivery delay in milliseconds. |
redeliveryDelay | 1000 | Specifies the delivery delay, in milliseconds, if initialRedeliveryDelay is 0. |
useCollisionAvoidance | false | Specifies if the redelivery policy uses collision avoidance. |
useExponentialBackOff | false | Specifies if the redelivery time out should be increased exponentially. |
backOffMultiplier | 5 | Specifies the back-off multiplier. |
