3.2. Apache Qpid JNDI Properties for AMQP Messaging

Apache Qpid defines JNDI properties that can be used to specify JMS Connections and Destinations. Here is a typical JNDI properties file:

Example 3.3. JNDI Properties File

  = org.apache.qpid.jndi.PropertiesFileInitialContextFactory

# connectionfactory.[jndiname] = [ConnectionURL]
  = amqp://guest:guest@clientid/test?brokerlist='tcp://localhost:5672'
# destination.[jndiname] = [address_string]
destination.topicExchange = amq.topic

The following sections describe the JNDI properties that Qpid uses.

3.2.1. JNDI Properties for Apache Qpid

Apache Qpid supports the properties shown in the following table:

Table 3.1. JNDI Properties supported by Apache Qpid

Property Purpose

The Connection URL that the connection factory uses to perform connections.


A JMS queue, which is implemented as an amq.direct exchange in Apache Qpid.


A JMS topic, which is implemented as an amq.topic exchange in Apache Qpid.


Can be used for defining all amq destinations, queues, topics and header matching, using an address string. [a]

[a] Binding URLs, which were used in earlier versions of the Qpid Java JMS client, can still be used instead of address strings.

3.2.2. Connection URLs

In JNDI properties, a Connection URL specifies properties for a connection. The format for a Connection URL is:


For instance, the following Connection URL specifies a user name, a password, a client ID, a virtual host ("test"), a broker list with a single broker, and a TCP host with the host name localhost using port 5672:


Apache Qpid supports the following properties in Connection URLs:

Table 3.2. Connection URL Properties

Option Type Description
brokerlist see below The broker to use for this connection. In the current release, precisely one broker must be specified.
maxprefetch -- The maximum number of pre-fetched messages per destination.
sync_publish {'persistent' | 'all'} A sync command is sent after every persistent message to guarantee that it has been received; if the value is 'persistent', this is done only for persistent messages.
sync_ack Boolean A sync command is sent after every acknowledgement to guarantee that it has been received.
use_legacy_map_msg_format Boolean If you are using JMS Map messages and deploying a new client with any JMS client older than 0.8 release, you must set this to true to ensure the older clients can understand the map message encoding.
failover {'roundrobin' | 'failover_exchange'} If roundrobin is selected it will try each broker given in the broker list. If failover_exchange is selected it connects to the initial broker given in the broker URL and will receive membership updates via the failover exchange.

Broker lists are specified using a URL in this format:


For instance, this is a typical broker list:


A broker list can contain more than one broker address; if so, the connection is made to the first broker in the list that is available. In general, it is better to use the failover exchange when using multiple brokers, since it allows applications to fail over if a broker goes down.

Example 3.4. Broker Lists

A broker list can specify properties to be used when connecting to the broker, such as security options. This broker list specifies options for a Kerberos connection using GSSAPI:


This broker list specifies SSL options:


The following broker list options are supported.

Table 3.3. Broker List Options

Option Type Description
heartbeat integer frequency of heartbeat messages (in seconds)
sasl_mechs -- For secure applications, we suggest CRAM-MD5, DIGEST-MD5, or GSSAPI. The ANONYMOUS method is not secure. The PLAIN method is secure only when used together with SSL. For Kerberos, sasl_mechs must be set to GSSAPI, sasl_protocol must be set to the principal for the qpidd broker, e.g. qpidd/, and sasl_server must be set to the host for the SASL server, e.g. sasl.com. SASL External is supported using SSL certification, e.g. ssl='true'&sasl_mechs='EXTERNAL'
sasl_encryption Boolean If sasl_encryption='true', the JMS client attempts to negotiate a security layer with the broker using GSSAPI to encrypt the connection. Note that for this to happen, GSSAPI must be selected as the sasl_mech.
ssl Boolean If ssl='true', the JMS client will encrypt the connection using SSL.
tcp_nodelay Boolean If tcp_nodelay='true', TCP packet batching is disabled.
sasl_protocol -- Used only for Kerberos. sasl_protocol must be set to the principal for the qpidd broker, e.g. qpidd/
sasl_server -- For Kerberos, sasl_mechs must be set to GSSAPI, sasl_server must be set to the host for the SASL server, e.g. sasl.com.
trust_store -- path to Keberos trust store
trust_store_password Kerberos trust store password
key_store path to Kerberos key store
key_store_password -- Kerberos key store password
ssl_verify_hostname Boolean When using SSL you can enable hostname verification by using "ssl_verify_hostname=true" in the broker URL.
ssl_cert_alias If multiple certificates are present in the keystore, the alias will be used to extract the correct certificate.