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
java.naming.factory.initial = org.apache.qpid.jndi.PropertiesFileInitialContextFactory # connectionfactory.[jndiname] = [ConnectionURL] connectionfactory.qpidConnectionfactory = 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.
Apache Qpid supports the properties shown in the following table:
Table 3.1. JNDI Properties supported by Apache Qpid
| Property | Purpose |
|---|---|
| connectionfactory.<jndiname> |
The Connection URL that the connection factory uses to perform connections. |
| queue.<jndiname> |
A JMS queue, which is implemented as an amq.direct exchange in Apache Qpid. |
| topic.<jndiname> |
A JMS topic, which is implemented as an amq.topic exchange in Apache Qpid. |
| destination.<jndiname> |
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. | |
In JNDI properties, a Connection URL specifies properties for a connection. The format for a Connection URL is:
amqp://[<user>:<pass>@][<clientid>]<virtualhost>[?<option>='<value>'[&<option>='<value>']]
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:
amqp://username:password@clientid/test?brokerlist='tcp://localhost: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:
brokerlist=<transport>://<host>[:<port>](?<param>=<value>)?(&<param>=<value>)*
For instance, this is a typical broker list:
brokerlist='tcp://localhost:5672'
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:
amqp://guest:guest@test/test?sync_ack='true'
&brokerlist='tcp://ip1:5672?sasl_mechs='GSSAPI'
This broker list specifies SSL options:
amqp://guest:guest@test/test?sync_ack='true' &brokerlist='tcp://ip1:5672?ssl='true'&ssl_cert_alias='cert1'
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. |