Installing & Using Qpid (Java)

Introduction

The information below details how to install and use the main Broker and Client packages.

Essentially, to make use of the Qpid AMQP infrastructure you need to be able to run a broker instance to handle messaging traffic and talk to your client code. Your own application code will make use of the Qpid client package provided to interface with the broker.

Related pages to get you going

• Troubleshooting Guide
• How to Use JNDI
• URL Formats for Qpid
• Example Classes

Minor apologies since these instructions are heavily linux/unix focused. If you have difficulty using our .bat script (see below) please email qpid-users for assistance.

Prerequisites

The Qpid currently broker requires jdk 1.Java 5 or later to be available. See later section for details.For maximum performance Java 6 is recommended. Note that JDK 5 has a bug which may cause problems, so plase use versions later than 1.5.0_15 !

The Java JMS client can be run using Java 1.4, 5 or 6. Note that the 1.4 client libraries come in a separate package.

Downloading & Installing Qpid

The latest build binary and source distributions of Qpid Broker and Client packages are available here:TBCfrom the downloads page.

If you want to use a newer version than an official release then you should check out the code from the Subversion repository and then consult the Build How To page.

Broker Install

Download the broker zip or tar package as appropriate for the platform you are installing on.

Once you have downloaded the package then unpack it into a directory i.e. Unpack the archive into any directory of your choice e.g c:/qpid

Once unpacked, the package will be installed in a directory with a release label (i.e. qpid-broker-0.95) and the directories underneath should look something like this:

...

qpid-server is a bash script which runs the broker on linux/unix. You should set the environment variable QPID_HOME to point at your install path e.g. C:/qpid/qpid-broker-0.95. This enables the startup script to find default config files in the installed etc directory.

...

qpid-server.bat is a dos script which runs the broker on Windows. See note above about QPID_HOME.

create-example-ssl-stores(.sh/.bat) bash shell / dos batch script to create an example SSL keystore and truststore for use by the brokers JMX management connections, which now ship with SSL enabled by default. Either provide your own keystore by modifying the broker configuration, or run the appropriate script from the /etc directory to create example stores to allow initial broker startup. Alternatively you can modify the configuration files in /etc to turn SSL use off.

The other scripts in this directory can be safely ignored for now.

/lib

This directory contains Contains all the jars used by the broker, mainly in their own subdirectories.

The brokerqpid-launchall.jar contains a manifest file which puts the requisite jars into the classpath for broker startup.

Other files & jars in here can be safely ignored for now.

/etc

This contains Contains the config files used by the broker on startup.

/client

This comes with the broker package at the moment and contains the client package. The client can also be downloaded independently. See client section below for details.

/doc

Contains javadoc for the broker.

If running on a unix or linux platform check that the appropriate permissions have been applied to the .sh scripts. If not, then update i.e. chmod 755 *.sh

Client Only Install

Download the qpid-client-<build#>.zip or qpid-client-<build#>.tar.gz package as appropriate for the platform you are installing on.

Once you have downloaded the package then unpack it into a directory i.e. c:/qpid-client

Once unpacked, the package will be installed in a directory with a release label (i.e. qpid-0.9) and then under the client directory should look something like this:

/lib

This dir contains all the jars needed by the client code and the client jars themselves.

/doc

Contains javadoc for the client code.

Environment Variables

Setting JAVA environment

You can continue to use DAM packages etc for Java providing that you have the correct version current in your .softdefs.

Environment Variables

Qpid Locations

You should set the following variables:

QPID_HOME - specifies where your install of Qpid exists, used for broker lookups of files etc
QPID_WORK - defines location of all working files created by the broker including log and db (i.e. BDB if used)
PATH - ensure that the QPID_HOME/bin directory is added to your path so that the server scripts can run

1. First set the QPID_HOME variable to reflect the root of your installation. For example, if you have installed the broker package into a directory <homedir>/broker/qpid-xx then you should set the QPID_HOME variable to <homedir>/broker/qpid-xx.
2. You can also set the QPID_WORK variable in order to control the destination directory for the log dir into which broker logging is generated. For example, if you wish to set the working directory to be <homedir>/working you should set the QPID_WORK directory to be <homedir>/working. Note that the QPID_WORK variable defaults to the current user's home directory if not set.
3. Then set your PATH variable appropriately to include the bin dir

Setting JAVA environment

You must make the JDK available Otherwise, you must make JDK 1.5 available by setting the JAVA_HOME environment variable and adding the JAVA_HOME/bin directory it to your PATH variable.

You should use JDK 1.6, or at least a version later than 1.5_15.

For example, if you have installed the JDK in /home/jdk1.5 6 then:
JAVA_HOME should be set to /home/jdk1.56
PATH should include /home/jdk1.56/bin

To check that you have completed this change successfully, simply type

...

You should see something like

java version "1.56.0_0702"
Java(TM) 2 SE Runtime Environment , Standard Edition (build 1.56.0_0702-b03b06)
Java HotSpot(TM) Client Server VM (build 1.56.0_0702-b03b06, mixed mode, sharing)

The Qpid scripts provided will setup set the classpath and other flags required for the broker to run.

Configuration

We ship two example configuration files with the Java broker:

persistent_config.xml - when you want to use any persistent messages with the Qpid broker (currently with BDB)
transient_config.xml - for transient messaging only

You can simply use one of these config files to get started, using the -c option to specify to the qpid-server script. See details next in the next section for more info on command line options.

Please visit our 3rd Party Libraries page to get more generic information on how to set up your chosen persistence implementation for Qpid.

Running the Qpid Broker

There are scripts provided to run the broker on Windows and on Linux/Unix.

Running the Qpid Broker on Linux/Unix

...

• Make sure you have set the QPID_HOME variable

...

<homedir>/broker/qpid-xx then you should set the QPID_HOME variable to <homedir>/broker/qpid-xx.

Then run the qpid-server script from the root dir of your install.

...

• as specified above, and QPID_WORK if you don't want the default
• Make sure you have provided an SSL keystore for the JMX management connections, or disabled the SSL usage, as detailed above in the 'broker install' section.
• One of the config files (persistent_config.xml or transient_config.xml) supplied in the etc directory one level below your root dir probably doesn't need modification and

...

• should be passed in using -c and the path to your config file
• Then run the qpid-server script from the root dir of your install. (The qpid-server script also supports cygwin environments.)

Command Line Arguments

startup script.

You can get a list of all command line arguments by using the -h argument.
In particular, -p overrides the port specified in the config file and -b overrides the bind interface (default is wildcard).

The qpid-server script also supports cygwin environments.

The following command line options are available:

For more detailed information on configuration, please see Qpid Design - Configuration

Checking the broker has started up

You can check that the broker has started up successfully by viewing the output it sends to stdout and looking for the start up port info:

2009-07-15 14:04:49,411 WARN [main] management.JMXManagedObjectRegistry (JMXManagedObjectRegistry.java:187) - Starting JMX ConnectorServer on port '8999' (+9099) with SSL
2009-07-15 14:04:49,842 INFO [main] server.Main (Main.java:279) - Starting Qpid Broker 0.5 build: xxxxxxx
2009-07-15 14:04:49,910 INFO [main] server.Main (Main.java:387) - Qpid.AMQP listening on non-SSL address Wiki MarkupYou can check that the broker has started up successfully by viewing the output it sends to stdout and looking for the start up port info: 2006-07-06 09:18:24,264 INFO&nbsp; \[main\] server.Main (Main.java:181) - Starting Qpid.AMQP broker 2006-07-06 09:18:24,331 INFO&nbsp; \[main\] server.Main (Main.java:251) - Qpid.AMQP listening on non-SSL address 0.0.0.0/0.0.0.0:5672

Running the

...

Qpid Broker on Windows

Simply set the QPID_HOME variable and run the .bat script. All other details as identical to running on Linux/Unix.

So for example:
qpid-server.bat

Getting Help

You can view our FAQ and Troubleshooting Guide for assistance. If you can't find the information that you need there, then email our qpid users list