Qpid Java FAQ

What is Qpid ?

The java implementation of Qpid is a pure Java message broker that implements the AMQP protocol. Essentially, Qpid is a robust, performant middleware component that can handle your messaging traffic. One of the most attractive aspects of Qpid is its cost - there is no licensing cost  !

It currently supports the following features:

*High performance header-based routing for messages
*Most features required by the JMS 1.1 specification. See our roadmap for details of missing JMS features and when we expect to add them.
*Transaction support
*Persistence using the high performance Berkeley DB Java Edition. The persistence layer is also pluggable should an alternative implementation be required.
*Pluggable security using SASL. Any Java SASL provider should be capable of working with Blaze.
*Management using JMX and MC4J (again see our roadmap for details of this feature and our future plans in this area)
*Clustering for scalability
*.NET API implementation (currently an alpha release; see our roadmap)

Can you help me get started with Qpid?

Have a look at our Getting Started Guide

How do I install the Qpid broker ?

Please follow the instructions provided on our Getting Started Guide.

How do I run the Qpid broker ?

The broker comes with a script for unix/linux/cygwin called qpid-server, which can be found in the bin directory of the installed package. This command can be executed without any paramters and will then use the default configuration file provided on install.

For the Windows OS, please use qpid-server.bat.

There's no need to set your classpath for QPID as the scripts take care of that by adding jar's with classpath defining manifest files to your classpath.

For more information on running the broker please see our Getting Started page.

How can I create a connection using a URL ?

The format for connection URL in QPID is as follows:

amqp://[user:pass@][clientid]/virtualhost?brokerlist='[transport://]host[:port][?option='value'[&option='value']];'
                                         [&failover='method[?option='value'[&option='value']]']
                                         [&option='value']"

Don't be alarmed - it's really not that complex !

You could use a URL which looks something like this:

amqp://guest:guest@localhost/development?brokerlist='tcp://localhost:5672'

Breaking this example down, here's what it all means:

amqp = the protocol we're using

guest:guest@localhost = username:password@clientid where the clientid is the name of your server (used under the covers but don't worry about this for now). Always use the guest:guest combination at the moment.

development = the name of the virtualhost, where the virtualhost is a path which acts as a namespace. You can effectively use any value here so long as you're consistent throughout. The virtualhost must start with a slash "/" and continue with names separated by slashes. A name consists of any combination of at least one of [A-Za-z0-9] plus zero or more of [.-_+!=:].

brokerlist = this is the host address and port for the broker you want to connect to. The connection factory will assume tcp if you don't specify a transport protocol. The port also defaults to 5672. Naturally you have to put at least one broker in this list.

This example is not using failover so only provides one host for the broker. If you do wish to connect using failover you can provide two (or more) brokers in the format:

brokerlist='tcp://host1;tcp://host2:5673'

The default failover setup will automatically retry each broker once after a failed connection. If the brokerlist contains more than one server then these servers are tried in a round robin. Details on how to modifiy this behaviour will follow soon !

How do I represent a JMS Destination string with QPID ?

Queues

A queue can be created in QPID using the following URL format.

direct://amq.direct//<Queue Name>

For example: direct://amq.direct//simpleQueue

Queue names may consist of any mixture of digits, letters, and underscores.

Topics

A topic can be created in QPID using the following URL format.

topic://amq.topic/<Topic Subscription>/

The topic subscription may only contain the letters A-Z and a-z and digits 0-9.

The topic currently does not support wild cards.

How do I connect to the broker using JNDI ?

Qpid will work with any JNDI provider capable of storing Java objects. We have a task to add our own initial context factory, but until that's available ....

First you must select a JNDI provider to use. If you aren't already using an application server (i.e. Tomcat ?) which provides JNDI support you could consider using either:

• Apache's Directory which provides an LDAP JNDI implementation

• OR the SUN JNDI SPI for the FileSystem which can be downloaded from http://java.sun.com/products/jndi/downloads/index.html

• Click : Download JNDI 1.2.1 & More button
• Download: File System Service Provider, 1.2 Beta 3
• and then add the two jars in the lib dir to your class path.

There are two steps to using JNDI objects.

• Bind : Which stores a reference to a JMS Object in the provider.
• Lookup : Which tries to retrieve the reference and create the JMS Object.

There are two objects that would normally be stored in JNDI.

• A ConnectionFactory
• A Destination (Queue or Topic)

Binding

Then you need to setup the values that the JNDI provider will used to bind your references, something like this:

Hashtable env = new Hashtable(11);
  env.put(Context.INITIAL_CONTEXT_FACTORY,"com.sun.jndi.fscontext.RefFSContextFactory");
  env.put(Context.PROVIDER_URL,LOCAL_FILE_PATH_FOR_STORING_BINDS_PATH_MUST_EXIST);

These values are then used to create a context to bind your references.

try
{
    Context ctx = new InitialContext(env);

    // Create the object to be bound in this case a ConnectionFactory
    ConnectionFactory factory = null;

    try
    {
        factory = new AMQConnectionFactory(CONNECTION_URL);
        try
        {
            ctx.bind(binding, factory);
        }
        catch (NamingException e)
        {
            //Handle problems with binding. Such as the binding already exists.
        }
    }
    catch (URLSyntaxException amqe)
    {
        //Handle any exception with creating ConnnectionFactory
    }
}
catch (NamingException e)
{
    //Handle problem creating the Context.
}

To bind a queue instead simply create a AMQQueue object and use that in the binding call.

AMQQueue  queue = new AMQQueue(QUEUE_URL);
ctx.bind(binding, queue);

Lookup

You can then get a queue connection factory from the JNDI context.

ConnectionFactory factory;
try
{
    factory= (ConnectionFactory)ctx.lookup(binding);
}
catch (NamingException e)
{
    //Handle problems with lookup. Such as binding does not exist.
}

Note that you need not cast the bound object back to an AMQConnectionFactory so all your current JMS apps that use JNDI can start using Qpid straight away.

I'm using Spring and Weblogic - can you help me with the configuration for moving over to Qpid ?

Here is a donated Spring configuration file appContext.zip which shows the config for Qpid side by side with Weblogic. HtH !

How can I configure the broker ?

The broker configuration is contained in the <installed-dir>/etc/config.xml file. You can copy and edit this file and then specify your own configuration file as a parameter to the startup script using the -c flag i.e. qpid-server -c <your_config_file's_path>

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

How can I change the port the broker uses at runtime ?

The broker defaults to use port 5672 at startup.

To change this, use the -p flag at startup i.e. qpid-server -p <port_number_to_use>

Use this to get round any issues on your host server with port 5672 being in use/unavailable.

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

What command line options can I pass into the qpid-server script ?

The following options are available:

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

How do I authenticate with the broker ? What user id & password should I use ?

You should login as user guest with password guest

How do I create queues that will always be instantiated at broker startup ?

You can configure queues which will be created at broker startup by tailoring a copy of the virtualhosts.xml file provided in the installed qpid-version/etc directory.

So, if you're using a queue called 'MY_QUEUE' you can ensure that it is created at startup by using an entry something like this:

<virtualhosts>
<virtualhost>
<path>/temp</path>
<bind>direct://amq.direct//MY_QUEUE</bind>
</virtualhost>
</virtualhosts>

Note that the path element should match the virtualhost that you're using to create connections to the broker. This is effectively a namespace used to prevent queue name clashes etc.

You can amend the config.xml to point at a different virtualhosts.xml file by editing the <virtualhosts/> element.

So, for example, you could tell the broker to use a file in your home directory by creating a new config.xml file with the following entry:

<virtualhosts>/home/myhomedir/virtualhosts.xml</virtualhosts>

You can then pass this amended config.xml into the broker at startup using the -c flag i.e.
qpid-server -c <path>/config.xml

How do I contact the Qpid team ?

tbc