Apache Qpid

Documentation

Community

Developers

About AMQP

About Apache

Programming in Apache Qpid > Using the Qpid JMS client > Apache Qpid JNDI Properties for AMQP Messaging

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

	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.

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
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.


3.2.2. Connection URLs

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 List of one or more broker addresses.
maxprefetch integer

The maximum number of pre-fetched messages per consumer. If not specified, default value of 500 is used.

Note: You can also set the default per-consumer prefetch value on a client-wide basis by configuring the client using Java system properties.

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 {'singlebroker' | 'roundrobin' | 'failover_exchange' | 'nofailover' | '<class>'}

This option controls failover behaviour. The method singlebroker uses only the first broker in the list, roundrobin will try each broker given in the broker list until a connection is established, failover_exchange connects to the initial broker given in the broker URL and will receive membership updates via the failover exchange. nofailover disables all retry and failover logic. Any other value is interpreted as a classname which must implement the org.apache.qpid.jms.failover.FailoverMethod interface.

The broker list options retries and connectdelay (described below) determine the number of times a connection to a broker will be retried and the the length of time to wait between successive connection attempts before moving on to the next broker in the list. The failover option cyclecount controls the number of times to loop through the list of available brokers before finally giving up.

Defaults to roundrobin if the brokerlist contains multiple brokers, or singlebroker otherwise.


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''

This broker list specifies two brokers using the connectdelay and retries broker options. It also illustrates the failover connection URL property. 


	  amqp://guest:guest@/test?failover='roundrobin?cyclecount='2''
	  &brokerlist='tcp://ip1:5672?retries='5'&connectdelay='2000';tcp://ip2:5672?retries='5'&connectdelay='2000''

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.
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 trust store
trust_store_password Trust store password
key_store path to key store
key_store_password -- key store password
ssl Boolean If ssl='true', the JMS client will encrypt the connection using SSL.
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.
retries integer The number of times to retry connection to each broker in the broker list. Defaults to 1.
connectdelay integer Length of time (in milliseconds) to wait before attempting to reconnect. Defaults to 0.
connecttimeout integer Length of time (in milliseconds) to wait for the socket connection to succeed. A value of 0 represents an infinite timeout, i.e. the connection attempt will block until established or an error occurs. Defaults to 30000.
tcp_nodelay Boolean If tcp_nodelay='true', TCP packet batching is disabled. Defaults to true since Qpid 0.14.

Prev Up Next
Chapter 3. Using the Qpid JMS client Home 3.3. Java JMS Message Properties