Page History

...

• Can you help me get started with Qpid?
• How do I install the Qpid broker ?
• Where can I find more information?

Wiki Markup
{toggle-cloak:id=whatisQpid}

What is Qpid ?

...

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:

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@client1/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'

Please see the Connection URL Format documentation.

{cloak}

Wiki Markup
{toggle-cloak:id=q6}

How do I represent a JMS Destination string with QPID ?

{cloak:id=q6}

Queues

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

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

For example: direct://amq.direct/<Destination>/simpleQueue

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

The bindingurlformat is described in more detail on it's own page.

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.

{composition-setup}{composition-setup}

cloak.memory.duration = 0

{cloak:id=hiddentillqpid-3isdone|visible=false}

The topic subscription is formed from a series of words that may only contain the letters A-Z and a-z and digits 0-9.
The words are delimited by dots. Each dot represents a new level.

For example: stocks.nyse.ibm

Wildcards can be used on subscription with the following meaning.

• match a single level
  # match zero or more levels

For example:
With two clients
1 - stocks.*.ibm
2 - stocks.#.ibm

Publishing stocks.nyse.ibm will be received by both clients but stocks.ibm and stocks.world.us.ibm will only be received by client 2.

The topic currently does not support wild cards.

{cloak}

{cloak}

Wiki Markup
{toggle-cloak:id=q7}

How do I connect to the broker using JNDI ?

{cloak:id=q7}

see How to use JNDI

{cloak}

Wiki Markup
{toggle-cloak:id=q8}

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

{cloak:id=q8}

Here is a donated Spring configuration file appContext.zip which shows the config for Qpid side by side with Weblogic. HtH 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 !

{cloak}

Wiki Markup
{toggle-cloak:id=

...

q9}

How do I

...

configure the logging level for Qpid ?

{cloak:id=q6q9}

The system property

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.

{composition-setup}{composition-setup}

cloak.memory.duration = 0

...

amqj.logging.level

can be used to configure the logging level.

For the broker, you can use the environment variable AMQJ_LOGGING_LEVEL which is picked up by the qpid-run script (called by qpid-server to start the broker) at runtime.

For client code that you've written, simply pass in a system property to your command line to set it to the level you'd like i.e.

-Damqj.logging.level=INFO

The log level for the broker defaults to INFO if the env variable is not set, but you may find that your log4j properties affect this. Setting the property noted above should address this.

{cloak}

unmigrated-inline-wiki-markup
{toggle-cloak:id=

...

loggingslf4j}

How can I configure my application to use Qpid client logging?

{cloak:id=loggingslf4j}

If you don't already have a logging implementation in your classpath you should add slf4-log4j12-1.4.0.jar and log4j-1.2.12.jar.

The topic subscription is formed from a series of words that may only contain the letters A-Z and a-z and digits 0-9.
The words are delimited by dots. Each dot represents a new level.

For example: stocks.nyse.ibm

Wildcards can be used on subscription with the following meaning.

• match a single level
  # match zero or more levels

For example:
With two clients
1 - stocks.*.ibm
2 - stocks.#.ibm

Publishing stocks.nyse.ibm will be received by both clients but stocks.ibm and stocks.world.us.ibm will only be received by client 2.

The topic currently does not support wild cards.

{cloak}

Wiki Markup
{toggle-cloak:id=q10}

How can I configure the broker ?

{

...

cloak:id=

...

q10}

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

{cloak:id=q7}

see How to use JNDI

{cloak}

Wiki Markup
{toggle-cloak:id=

...

q11}

...

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

{cloak:id=q8}

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

{cloak}

...

q11}

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

{cloak}

Wiki Markup
{toggle-cloak:id=

...

q12}

...

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

{cloak:id=q9q12}

The system property

amqj.logging.level

can be used to configure the logging level.

For the broker, you can use the environment variable AMQJ_LOGGING_LEVEL which is picked up by the qpid-run script (called by qpid-server to start the broker) at runtime.

For client code that you've written, simply pass in a system property to your command line to set it to the level you'd like i.e.

-Damqj.logging.level=INFO

...

following command line options are available:

{cloak}

Wiki Markup
{toggle-cloak:id=q13}

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

{cloak:id=q13}

You should login as user guest with password guest

{cloak}

Wiki Markup
{toggle-cloak:id=

...

q14}

How

...

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

{cloak:id=q10q14}

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

{cloak}

Wiki Markup
{toggle-cloak:id=q11}

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

{cloak:id=q11}

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

{cloak}

Wiki Markup
{toggle-cloak:id=q12}

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

{cloak:id=q12}

The following options are available:

...

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 'devqueue' you can ensure that it is created at startup by using an entry something like this:

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

{cloak}

Wiki Markup
{toggle-cloak:id=

...

runtimequeues}

How do I

...

create queues at runtime?

{cloak:id=q13}runtimequeues}

Queues can be dynamically created at runtime by creating a consumer for them. After they have been created and bound (which happens automatically when a JMS Consumer is created) a publisher can send messages to them. You should login as user guest with password guest

{cloak}

Wiki Markup
{toggle-cloak:id=

...

tuning}

How do I

...

tune the broker?

There are a number of tuning options available, please see the How to Tune M3 Java Broker Performance page for more information.

{cloak:id=q14}

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 'devqueue' you can ensure that it is created at startup by using an entry something like this:

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

q16}

{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**

{cloak}

Wiki Markup
{toggle-cloak:id=q14b}

My client application appears to have hung?

{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-429You 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=

...

q15}

...

How do I contact the Qpid team ?

{cloak:id=q16q15}

For general questions, please subscribe to the qpid-users@incubator.apache.org mailing list (archive).

For development questions, please subscribe to the qpid-dev@incubator.apache.org mailing list (archive).

More details on these lists are available on our mailing lists pageAt 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=

...

q18}

...

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

{cloak:id=q17q18}

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

{cloak}

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.

{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=

...

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

{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=

...

qManagementConsoleSecurity}

How do I

...

connect the management console to my broker using security ?

{cloak:id=q15}qManagementConsoleSecurity}

The Management Console Security page will give you the instructions that you should use to set this up.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=

...

qHowToWriteOwnInVMTests}

How

...

do I use an InVM Broker for my own tests?

{cloak:id=q18qHowToWriteOwnInVMTests}

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.

I would take a look at the testPassiveTTL in TimeToLiveTest

The setUp and tearDown methods show how to correctly start up a broker for InVM testing. If you write your tests using a file for the JNDI you can then very easily swap between running your tests InVM and against a real broker.

See our JNDI How to page on how to confgure it

Basically though you just need to set two System Properites:

java.naming.factory.initial = org.apache.qpid.jndi.PropertiesFileInitialContextFactory
java.naming.provider.url = <your JNDI file>

and call getInitialContext() in your code.

You will of course need to have the broker libraries on your class path for this to runIf you're using plain text passwords, then simply update your file and the content is read on every connection.

{cloak}

Wiki Markup
{toggle-cloak:id=

...

MessageStoreContents}

How

...

can I inspect the contents of my MessageStore?

{cloak:id=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.

:id=MessageStoreContents}

There are two possibilities here:

1) The management console can be used to interogate an active broker and browse the contents of a queue.See the JMX Management Console page for further details.

2) The MessageStore Tool can be used to inspect the contents of a persistent message store. Note: this can currently only be used when the broker is offlineThese flags will not be able to tell you if the consuming application has received the message and is able to process it.

{cloak}

Wiki Markup
{toggle-cloak:id=

...

slowtransient}

...

Why are my transient messages being so slow?

{cloak:id=qManagementConsoleSecurity}slowtransient}

You should check that you aren't sending persistent messages, this is the default. If you want to send transient messages you must explicitly set this optionThe Management Console Security page will give you the instructions that you should use to set this up.

{cloak}

Wiki Markup
{toggle-cloak:id=

...

asyncpublish}

Why does my producer fill up the broker with messages?

{cloak:id=slowtransient}

The Java broker does not currently implement producer flow control. Publishes are currently asynchronous, so there is no ability to rate limit this automatically. While this is something which will be addressed in the future, it is currently up to applications to ensure that they do not publish faster than the messages are being consumed for signifcant periods of time

{cloak:id=qHowToWriteOwnInVMTests}

I would take a look at the testPassiveTTL in TimeToLiveTest

The setUp and tearDown methods show how to correctly start up a broker for InVM testing. If you write your tests using a file for the JNDI you can then very easily swap between running your tests InVM and against a real broker.

See our JNDI How to page on how to confgure it

Basically though you just need to set two System Properites:

java.naming.factory.initial = org.apache.qpid.jndi.PropertiesFileInitialContextFactory
java.naming.provider.url = <your JNDI file>

and call getInitialContext() in your code.

You will of course need to have the broker libraries on your class path for this to run.

{cloak}