Search

Appendix B. Client Connection Options

download PDF

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.
Table B.1. Client Connection Options
OptionDefaultDescription
alwaysSessionAsynctrueSpecifies 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.
checkForDuplicatestrueSpecifies if the consumer will check for duplicate messages and make sure that it is not processed twice inadvertently.
clientID Specifies the JMS clientID to use for the connection.
closeTimeout15000Specifies 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.
copyMessageOnSendtrueSpecifies 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.
disableTimeStampsByDefaultfalseSpecifies whether or not timestamps on messages should be disabled or not. Disabling them it adds a small performance boost.
dispatchAsyncfalseSpecifies if the broker dispatches messages to the consumer asynchronously.
nestedMapAndListEnabledtrueEnables/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.
objectMessageSerializationDeferedfalseSpecifies 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.
optimizeAcknowledgefalseSpecifies if messages are acknowledged in batches rather than individually. Enabling this could cause some issues with auto-acknowledgement on reconnection.
optimizeAcknowledgeTimeOut300Specifies the maximum time, in milliseconds, between batch acknowledgements when optimizeAcknowledge is enabled.
optimizedAckScheduledAckInterval0if greater than 0, specifies a time interval upon which all the outstanding acks are delivered when optimized acknowledge is used, so that a long running consumer that doesn't receive any more messages will eventually ack the last few unacked messages.
optimizedMessageDispatchtrueSpecifies if a larger prefetch limit is used for durable topic subscribers.
useAsyncSendfalseSpecifies 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.
useCompressionfalseSpecifies if message bodies are compressed.
useRetroactiveConsumerfalseSpecifies 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.
warnAboutUnstartedConnectionTimeout500Specifies 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.
auditDepth2048Specifies the size of the message window that will be audited for duplicates and out of order messages.
auditMaximumProducerNumber64Specifies the maximum number of producers that will be audited.
alwaysSyncSendfalseSpecifies if a message producer will always use synchronous sends when sending a message.
consumerExpiryCheckEnabled trueSpecifies whether message expiration checking is done in each MessageConsumer prior to dispatching a message. Disabling this can lead to consumption of expired messages.
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.
Table B.2. Blob Message Properties
OptionDescription
bufferSizeSpecifies the size of the buffer used when uploading or downloading blobs.
uploadUrlSpecifies 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.
Table B.3. Connection URI Prefect Limit Options
OptionDescription
queuePrefetchSpecifies the prefect limit for all consumers using queues.
queueBrowserPrefetchSpecifies the prefect limit for all queue browsers.
topicPrefetchSpecifies the prefect limit for non-durable topic consumers.
durableTopicPrefetchSpecifies the prefect limit for durable topic consumers.
allSpecifies 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.
Table B.4. Redelivery Policy Options
OptionDefaultDescription
collisionAvoidanceFactor0.15Specifies the percentage of range of collision avoidance.
maximumRedeliveries6Specifies 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-1Specifies the maximum delivery delay that will be applied if the useExponentialBackOff option is set. -1 specifies that no maximum be applied.
initialRedeliveryDelay1000Specifies the initial redelivery delay in milliseconds.
redeliveryDelay1000Specifies the delivery delay, in milliseconds.
useCollisionAvoidancefalseSpecifies if the redelivery policy uses collision avoidance.
useExponentialBackOfffalseSpecifies if the redelivery time out should be increased exponentially.
backOffMultiplier5Specifies the back-off multiplier.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.