Menu Search

3.6. Configuring the JMS Client

The Qpid JMS Client allows several configuration options to customize it's behaviour at different levels of granualarity.

  • JVM level using JVM arguments : Configuration that affects all connections, sessions, consumers and producers created within that JVM.

    Ex. -Dmax_prefetch=1000 property specifies the message credits to use.

  • Connection level using Connection/Broker properties : Affects the respective connection and sessions, consumers and produces created by that connection.

    Ex. amqp://guest:guest@test/test?max_prefetch='1000' &brokerlist='tcp://localhost:5672' property specifies the message credits to use. This overrides any value specified via the JVM argument max_prefetch.

    Please refer to the Section 3.2.2, “Connection URLs” section for a complete list of all properties and how to use them.

  • Destination level using Addressing options : Affects the producer(s) and consumer(s) created using the respective destination.

    Ex. my-queue; {create: always, link:{capacity: 10}}, where capacity option specifies the message credits to use. This overrides any connection level configuration.

    Please refer to the Section 2.4, “Addresses” section for a complete understanding of addressing and it's various options.

Some of these config options are available at all three levels (Ex. max_prefetch), while others are available only at JVM or connection level.

3.6.1. Qpid JVM Arguments

Table 3.6. Config Options For Connection Behaviour

Property NameTypeDefault ValueDescription
qpid.amqp.versionstring0-10

Sets the AMQP version to be used - currently supports one of {0-8,0-9,0-91,0-10}.

The client will begin negotiation at the specified version and only negotiate downwards if the Broker does not support the specified version.

qpid.heartbeatint120 (secs)The heartbeat interval in seconds. Two consective misssed heartbeats will result in the connection timing out.

This can also be set per connection using the Connection URL options.

ignore_setclientIDbooleanfalseIf a client ID is specified in the connection URL it's used or else an ID is generated. If an ID is specified after it's been set Qpid will throw an exception.

Setting this property to 'true' will disable that check and allow you to set a client ID of your choice later on.


Table 3.7. Config Options For Session Behaviour

Property NameTypeDefault ValueDescription
qpid.session.command_limitint65536Limits the # of unacked commands
qpid.session.byte_limitint1048576Limits the # of unacked commands in terms of bytes
qpid.use_legacy_map_messagebooleanfalse

If set will use the old map message encoding. By default the Map messages are encoded using the 0-10 map encoding.

This can also be set per connection using the Connection URL options.

qpid.jms.daemon.dispatcherbooleanfalse

Controls whether the Session dispatcher thread is a daemon thread or not. If this system property is set to true then the Session dispatcher threads will be created as daemon threads. This setting is introduced in version 0.16.


Table 3.8. Config Options For Consumer Behaviour

Property NameTypeDefault ValueDescription
max_prefetchint500Maximum number of pre-fetched messages per consumer.

This can also be defaulted for consumers created on a particular connection using the Connection URL options, or per destination (see the capacity option under link properties in addressing)

qpid.session.max_ack_delaylong1000 (ms)

Timer interval to flush message acks in buffer when using AUTO_ACK and DUPS_OK.

When using the above ack modes, message acks are batched and sent if one of the following conditions are met (which ever happens first).

  • When the ack timer fires.

  • if un_acked_msg_count > max_prefetch/2.

The ack timer can be disabled by setting it to 0.

sync_ackbooleanfalse

If set, each message will be acknowledged synchronously. When using AUTO_ACK mode, you need to set this to "true", in order to get the correct behaviour as described by the JMS spec.

This is set to false by default for performance reasons, therefore by default AUTO_ACK behaves similar to DUPS_OK.

This can also be set per connection using the Connection URL options.


Table 3.9. Config Options For Producer Behaviour

Property NameTypeDefault ValueDescription
sync_publishstring"" (disabled)

If one of {persistent|all} is set then persistent messages or all messages will be sent synchronously.

This can also be set per connection using the Connection URL options.


Table 3.10. Config Options For Threading

Property NameTypeDefault ValueDescription
qpid.thread_factorystringorg.apache.qpid.thread.DefaultThreadFactory

Specifies the thread factory to use.

If using a real time JVM, you need to set the above property to org.apache.qpid.thread.RealtimeThreadFactory.

qpid.rt_thread_priorityint20

Specifies the priority (1-99) for Real time threads created by the real time thread factory.


Table 3.11. Config Options For I/O

Property NameTypeDefault ValueDescription
qpid.transportstringorg.apache.qpid.transport.network.io.IoNetworkTransport

The transport implementation to be used.

A user could specify an alternative transport mechanism that implements the interface org.apache.qpid.transport.network.OutgoingNetworkTransport.

qpid.sync_op_timeoutlong60000

The length of time (in milliseconds) to wait for a synchronous operation to complete.

For compatibility with older clients, the synonym amqj.default_syncwrite_timeout is supported.

qpid.tcp_nodelaybooleantrue

Sets the TCP_NODELAY property of the underlying socket. The default was changed to true as of Qpid 0.14.

This can also be set per connection using the Connection URL options.

For compatibility with older clients, the synonym amqj.tcp_nodelay is supported.

qpid.send_buffer_sizeinteger65535

Sets the SO_SNDBUF property of the underlying socket. Added in Qpid 0.16.

For compatibility with older clients, the synonym amqj.sendBufferSize is supported.

qpid.receive_buffer_sizeinteger65535

Sets the SO_RCVBUF property of the underlying socket. Added in Qpid 0.16.

For compatibility with older clients, the synonym amqj.receiveBufferSize is supported.

qpid.failover_method_timeoutlong60000

During failover, this is the timeout for each attempt to try to re-establish the connection. If a reconnection attempt exceeds the timeout, the entire failover process is aborted.

It is only applicable for AMQP 0-8/0-9/0-9-1 clients.


Table 3.12. Config Options For Security

Property NameTypeDefault ValueDescription
qpid.sasl_mechsstringPLAIN

The SASL mechanism to be used. More than one could be specified as a comma separated list.

We currently support the following mechanisms {PLAIN | GSSAPI | EXTERNAL}.

This can also be set per connection using the Connection URL options.

qpid.sasl_protocolstringAMQP

When using GSSAPI as the SASL mechanism, sasl_protocol must be set to the principal for the qpidd broker, e.g. qpidd.

This can also be set per connection using the Connection URL options.

qpid.sasl_server_namestringlocalhost

When using GSSAPI as the SASL mechanism, sasl_server must be set to the host for the SASL server, e.g. example.com.

This can also be set per connection using the Connection URL options.


Table 3.13. Config Options For Security - Standard JVM properties needed when using GSSAPI as the SASL mechanism.[a]

Property NameTypeDefault ValueDescription
javax.security.auth.useSubjectCredsOnlybooleantrue

If set to 'false', forces the SASL GASSPI client to obtain the kerberos credentials explicitly instead of obtaining from the "subject" that owns the current thread.

java.security.auth.login.configstring 

Specifies the jass configuration file.

Ex-Djava.security.auth.login.config=myjas.conf

Here is the sample myjas.conf JASS configuration file:


		com.sun.security.jgss.initiate {
		com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true;
		};

		

[a] Please refer to the Java security documentation for a complete understanding of the above properties.


Table 3.14. Config Options For Security - Using SSL for securing connections or using EXTERNAL as the SASL mechanism.

Property NameTypeDefault ValueDescription
qpid.ssl_timeoutlong60000

Timeout value used by the Java SSL engine when waiting on operations.

qpid.ssl.KeyManagerFactory.algorithmstring-

The key manager factory algorithm name. If not set, defaults to the value returned from the Java runtime call KeyManagerFactory.getDefaultAlgorithm()

For compatibility with older clients, the synonym qpid.ssl.keyStoreCertType is supported.

qpid.ssl.TrustManagerFactory.algorithmstring-

The trust manager factory algorithm name. If not set, defaults to the value returned from the Java runtime call TrustManagerFactory.getDefaultAlgorithm()

For compatibility with older clients, the synonym qpid.ssl.trustStoreCertType is supported.


Table 3.15. Config Options For Security - Standard JVM properties needed when Using SSL for securing connections or using EXTERNAL as the SASL mechanism.[a]

Property NameTypeDefault ValueDescription
javax.net.ssl.keyStorestringjvm default

Specifies the key store path.

This can also be set per connection using the Connection URL options.

javax.net.ssl.keyStorePasswordstringjvm default

Specifies the key store password.

This can also be set per connection using the Connection URL options.

javax.net.ssl.trustStorestringjvm default

Specifies the trust store path.

This can also be set per connection using the Connection URL options.

javax.net.ssl.trustStorePasswordstringjvm default

Specifies the trust store password.

This can also be set per connection using the Connection URL options.

[a] Qpid allows you to have per connection key and trust stores if required. If specified per connection, the JVM arguments are ignored.