Page History

{composition-setup}
cloak.toggle.zone = true
{composition-setup}

Here are a list of commonly asked questions and answers. If you have any questions which are not on this list, please email our qpid-user list.

Getting Started

• Can you help me get started with Qpid?
• How do I install the Qpid broker ?

Wiki Markup
{toggle-cloak:id=

...

whatisQpid}

What is Qpid ?

{cloak:id=q1whatisQpid}

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.

...

• High performance header-based routing for messages
• All features required by the JMS 1.1 specification. Qpid passes all tests in the Sun JMS compliance test suite
• Transaction support
• Persistence using the high performance Berkeley DB Java Edition. The persistence layer is also pluggable should an alternative implementation be required. The BDB store is available from the 3rd Party Libraries page
• Pluggable security using SASL. Any Java SASL provider can be used
• Management using JMX and a custom management console built using Eclipse RCP
• Naturally, interoperability with other clients including the Qpid .NET, Python, Ruby and C++ implementations

{cloak}

Wiki Markup
{toggle-cloak:id=

...

q4}

...

How do I run the Qpid broker ?

{cloak:id=q2q4}

Have a look at our Getting Started Guide

{cloak}

Wiki Markup
{toggle-cloak:id=q3}

How do I install the Qpid broker ?

{cloak:id=q3}

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 pagePlease follow the instructions provided on our Getting Started Guide.

{cloak}

Wiki Markup
{toggle-cloak:id=

...

q5}

How

...

can I create a connection using a URL ?

{cloak:id=q4q5}

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.

{cloak}

Wiki Markup
{toggle-cloak:id=q5}

How can I create a connection using a URL ?

{cloak:id=q5}

The format for connection URL in QPID is as follows:

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

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'Don't be alarmed - it's really not that complex !

...

<virtualhosts>
  <default>test</default>
  <virtualhost>
   <name>test</name>
   <test>  
   <queue>
      <name>devqueue</name>
      <devqueue>
        <exchange>amq.direct</exchange>
        <maximumQueueDepth>4235264</maximumQueueDepth>  <!-- 4Mb --->
        <maximumMessageSize>2117632</maximumMessageSize> <!-- 2Mb -->
        <maximumMessageAge>600000</maximumMessageAge>  <!-- 10 mins -->
      </devqueue>
   </queue>
   </test>
  </virtualhost>
</virtualhosts>

Note that the name (in thie example above the name is 'test') 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 also see that we've set the 'test' virtual host to be the default for any connections which do not specify a virtual host (in the <default> tag).

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

{cloak}

Wiki Markup
{toggle-cloak:id=q16}

Where do undeliverable messages end up ?

{cloak:id=q16}

>
        <maximumMessageSize>2117632</maximumMessageSize> <!-- 2Mb -->
        <maximumMessageAge>600000</maximumMessageAge>  <!-- 10 mins -->
      </devqueue>
   </queue>
   </test>
  </virtualhost>
</virtualhosts>

Note that the name (in thie example above the name is 'test') 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 also see that we've set the 'test' virtual host to be the default for any connections which do not specify a virtual host (in the <default> tag).

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

{cloak}

Wiki Markup
{toggle-cloak:id=q16}

Where do undeliverable messages end up ?

{cloak:id=q16}

At present, messages with an invalid routing key will be returned to the sender. If you register an exception listener for your publisher (easiest to do by making your publisher implement the ExceptionListener interface and coding the onException method) you'll see that you end up in onException in this case. You can expect to be catching a subclass of org.apache.qpid.AMQUndeliveredException.

{cloak}

Wiki Markup
{toggle-cloak:id=q17}

Can I configure the name of the Qpid broker log file at runtime ?

{cloak:id=q17}

If you simply start the Qpid broker using the default configuration, then the log file is written to $QPID_WORK/log/qpid.log

This is not ideal if you want to run several instances from one install, or acrhive logs to a shared drive from several hosts.

To make life easier, there are two optional ways to configure the naming convention used for the broker log.

Setting a prefix or suffix

Users should set the following environment variables before running qpid-server:

QPID_LOG_PREFIX - will prefix the log file name with the specified value e.g. if you set this value to be the name of your host (for example) it could look something like host123qpid.log

QPID_LOG_SUFFIX - will suffix the file name with the specified value e.g. if you set this value to be the name of your application (for example) if could look something like qpidMyApp.log

Including the PID

Setting either of these variables to the special value PID will introduce the process id of the java process into the file name as a prefix or suffix as specified**At present, messages with an invalid routing key will be returned to the sender. If you register an exception listener for your publisher (easiest to do by making your publisher implement the ExceptionListener interface and coding the onException method) you'll see that you end up in onException in this case. You can expect to be catching a subclass of org.apache.qpid.AMQUndeliveredException.

{cloak}

Wiki Markup
{toggle-cloak:id=

...

q14b}

My client application appears to have hung?

{cloak:id=q17q14b}

If you simply start the Qpid broker using the default configuration, then the log file is written to $QPID_WORK/log/qpid.log

This is not ideal if you want to run several instances from one install, or acrhive logs to a shared drive from several hosts.

To make life easier, there are two optional ways to configure the naming convention used for the broker log.

Setting a prefix or suffix

Users should set the following environment variables before running qpid-server:

QPID_LOG_PREFIX - will prefix the log file name with the specified value e.g. if you set this value to be the name of your host (for example) it could look something like host123qpid.log

QPID_LOG_SUFFIX - will suffix the file name with the specified value e.g. if you set this value to be the name of your application (for example) if could look something like qpidMyApp.log

Including the PID

The client code currently has various timeouts scattered throughout the code. These can cause your client to appear like it has hung when it is actually waiting for the timeout ot compelete. One example is when the broker becomes non-responsive, the client code has a hard coded 2 minute timeout that it will wait when closing a connection. These timeouts need to be consolidated and exposed. see QPID-429

{cloak}

Wiki Markup
{toggle-cloak:id=q15}

How do I contact the Qpid team ?

{cloak:id=q15}

For now, subscribe to our developer list (email qpid-dev-subscribe@incubator.apache.com). A users list is currently being set up!Setting either of these variables to the special value PID will introduce the process id of the java process into the file name as a prefix or suffix as specified**

{cloak}

Wiki Markup
{toggle-cloak:id=

...

q18}

How can I change a user's password while the broker is up ?

{cloak:id=q14b}

The client code currently has various timeouts scattered throughout the code. These can cause your client to appear like it has hung when it is actually waiting for the timeout ot compelete. One example is when the broker becomes non-responsive, the client code has a hard coded 2 minute timeout that it will wait when closing a connection. These timeouts need to be consolidated and exposed. see QPID-429

{cloak}

Wiki Markup
{toggle-cloak:id=q15}

How do I contact the Qpid team ?

{cloak:id=q15}

=q18}

You can do this via the management console if you're using the base64password file (rather than plain text). To do this simply log in to the management console as an admin user (you need to have created an admin account in the jmxremote.access file first) and then select the 'Manage Users' pane. There is a 'Change Password' tab which you can then use. Alternatively, update the base64password file and use the management console to reload the file, in the 'Manage Users' pane. In both cases, this will take effect when the user next logs in i.e. will not cause them to be disconnected if they are already connected.

For more information on the Management Console please see our Qpid Management Console User Guide.

If you're using plain text passwords, then simply update your file and the content is read on every connection.For now, subscribe to our developer list (email qpid-dev-subscribe@incubator.apache.com). A users list is currently being set up!

{cloak}

Wiki Markup
{toggle-cloak:id=

...

qKnowConsumerExisistToSendMessage}

How

...

do I know if there is a consumer for a message I am going to send?

{cloak:id=q18}

You can do this via the management console if you're using the base64password file (rather than plain text). To do this simply log in to the management console as an admin user (you need to have created an admin account in the jmxremote.access file first) and then select the 'Manage Users' pane. There is a 'Change Password' tab which you can then use. Alternatively, update the base64password file and use the management console to reload the file, in the 'Manage Users' pane. In both cases, this will take effect when the user next logs in i.e. will not cause them to be disconnected if they are already connected.

For more information on the Management Console please see our Qpid Management Console User Guide.

qKnowConsumerExisistToSendMessage}

Knowing that there is a consumer for a message is quite tricky. That said using the qpid.jms.Session#createProducer with immediate and mandatory set to true will get you part of the way there.

If you are publishing to a well known queue then immediate will let you know if there is any consumer able to pre-fetch that message at the time you send it. If not it will be returned to you on your connection listener.

If you are sending to a queue that the consumer creates then the mandatory flag will let you know if they have not yet created that queue.

These flags will not be able to tell you if the consuming application has received the message and is able to process itIf you're using plain text passwords, then simply update your file and the content is read on every connection.

{cloak}