1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
|
<html>
<head>
<title>Apache Qpid : Qpid Java FAQ</title>
<link rel="stylesheet" href="styles/site.css" type="text/css" />
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
<table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
<tr>
<td valign="top" class="pagebody">
<div class="pageheader">
<span class="pagetitle">
Apache Qpid : Qpid Java FAQ
</span>
</div>
<div class="pagesubheading">
This page last changed on Mar 10, 2008 by <font color="#0050B2">ritchiem</font>.
</div>
<h2><a name="QpidJavaFAQ-WhatisQpid%3F"></a><span id='tgl_content_q1' class='cloakToggle'></span> What is Qpid ?</h2>
<span id='content_q1' class='cloak' style='display: none'>
<p>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.</p>
<p>It currently supports the following features:</p>
<ul>
<li>High performance header-based routing for messages</li>
<li>All features required by the JMS 1.1 specification. Qpid passes all tests in the Sun JMS compliance test suite</li>
<li>Transaction support</li>
<li>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 <a href="3rd Party Libraries.html" title="3rd Party Libraries">3rd Party Libraries</a> page</li>
<li>Pluggable security using SASL. Any Java SASL provider can be used</li>
<li>Management using JMX and a custom management console built using Eclipse RCP</li>
<li>Naturally, interoperability with other clients including the Qpid .NET, Python, Ruby and C++ implementations
</span></li>
</ul>
<h2><a name="QpidJavaFAQ-CanyouhelpmegetstartedwithQpid%3F"></a><span id='tgl_content_q2' class='cloakToggle'></span> Can you help me get started with Qpid?</h2>
<span id='content_q2' class='cloak' style='display: none'>
<p>Have a look at our <a href="Getting Started Guide.html" title="Getting Started Guide">Getting Started Guide</a></p>
</span>
<h2><a name="QpidJavaFAQ-HowdoIinstalltheQpidbroker%3F"></a><span id='tgl_content_q3' class='cloakToggle'></span> How do I install the Qpid broker ?</h2>
<span id='content_q3' class='cloak' style='display: none'>
<p>Please follow the instructions provided on our <a href="Getting Started Guide.html" title="Getting Started Guide">Getting Started Guide</a>.</p>
</span>
<h2><a name="QpidJavaFAQ-HowdoIruntheQpidbroker%3F"></a><span id='tgl_content_q4' class='cloakToggle'></span> How do I run the Qpid broker ?</h2>
<span id='content_q4' class='cloak' style='display: none'>
<p>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.</p>
<p>For the Windows OS, please use qpid-server.bat.</p>
<p>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.</p>
<p>For more information on running the broker please see our <a href="Getting Started.html" title="Getting Started">Getting Started</a> page.</p>
</span>
<h2><a name="QpidJavaFAQ-HowcanIcreateaconnectionusingaURL%3F"></a><span id='tgl_content_q5' class='cloakToggle'></span> How can I create a connection using a URL ?</h2>
<span id='content_q5' class='cloak' style='display: none'>
<p>The format for connection URL in QPID is as follows:</p>
<div class="preformatted"><div class="preformattedContent">
<pre>amqp://[user:pass@][clientid]/virtualhost?brokerlist='[transport://]host[:port][?option='value'[&option='value']];'
[&failover='method[?option='value'[&option='value']]']
[&option='value']"
</pre>
</div></div>
<p>Don't be alarmed - it's really not that complex !</p>
<p>You could use a URL which looks something like this:</p>
<p><tt>amqp://guest:guest@client1/development?brokerlist='tcp://localhost:5672'</tt></p>
<p>Breaking this example down, here's what it all means:</p>
<p>amqp = the protocol we're using</p>
<p>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.</p>
<p>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 [.-_+!=:].</p>
<p>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.</p>
<p>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:</p>
<p>brokerlist='tcp://host1;tcp://host2:5673'</p>
<p>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 !</p>
</span>
<h2><a name="QpidJavaFAQ-HowdoIrepresentaJMSDestinationstringwithQPID%3F"></a><span id='tgl_content_q6' class='cloakToggle'></span> How do I represent a JMS Destination string with QPID ?</h2>
<span id='content_q6' class='cloak' style='display: none'>
<h4><a name="QpidJavaFAQ-Queues"></a>Queues</h4>
<p>A queue can be created in QPID using the following URL format.</p>
<p><tt>direct://amq.direct//<Queue Name></tt></p>
<p>For example: <tt>direct://amq.direct//simpleQueue</tt></p>
<p>Queue names may consist of any mixture of digits, letters, and underscores.</p>
<h4><a name="QpidJavaFAQ-Topics"></a>Topics</h4>
<p>A topic can be created in QPID using the following URL format.</p>
<p><tt>topic://amq.topic/<Topic Subscription>/</tt></p>
<p>The topic subscription may only contain the letters A-Z and a-z and digits 0-9.</p>
<p>cloak.memory.duration = 0</p>
<span id='content_q6_hiddentillqpid-3isdone' class='cloak' style='display: none'>
<p>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.<br/>
The words are delimited by dots. Each dot represents a new level.</p>
<p>For example: <tt>stocks.nyse.ibm</tt></p>
<p>Wildcards can be used on subscription with the following meaning.</p>
<ul>
<li>match a single level<br/>
<tt>#</tt> match zero or more levels</li>
</ul>
<p>For example:<br/>
With two clients<br/>
1 - <tt>stocks.*.ibm</tt><br/>
2 - <tt>stocks.#.ibm</tt></p>
<p>Publishing <tt>stocks.nyse.ibm</tt> will be received by both clients but <tt>stocks.ibm</tt> and <tt>stocks.world.us.ibm</tt> will only be received by client 2.</p>
<p>The topic currently does not support wild cards.</p>
</span>
</span>
<h2><a name="QpidJavaFAQ-HowdoIconnecttothebrokerusingJNDI%3F"></a><span id='tgl_content_q7' class='cloakToggle'></span> How do I connect to the broker using JNDI ?</h2>
<span id='content_q7' class='cloak' style='display: none'>
<p>see <a href="How to use JNDI.html" title="How to Use JNDI">How to use JNDI</a></p>
</span>
<h2><a name="QpidJavaFAQ-I%27musingSpringandWeblogiccanyouhelpmewiththeconfigurationformovingovertoQpid%3F"></a><span id='tgl_content_q8' class='cloakToggle'></span> I'm using Spring and Weblogic - can you help me with the configuration for moving over to Qpid ?</h2>
<span id='content_q8' class='cloak' style='display: none'>
<p>Here is a donated Spring configuration file <a href="http://cwiki.apache.org/confluence/download/attachments/28400/appContext.zip?version=1" title="appContext.zip attached to Qpid Java FAQ">appContext.zip</a> which shows the config for Qpid side by side with Weblogic. HtH !</p>
</span>
<h2><a name="QpidJavaFAQ-HowdoIconfigurethelogginglevelforQpid%3F"></a><span id='tgl_content_q9' class='cloakToggle'></span> How do I configure the logging level for Qpid ?</h2>
<span id='content_q9' class='cloak' style='display: none'>
<p>The system property <div class="preformatted"><div class="preformattedContent">
<pre>amqj.logging.level</pre>
</div></div> can be used to configure the logging level. </p>
<p>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.</p>
<p>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. </p>
<div class="preformatted"><div class="preformattedContent">
<pre>-Damqj.logging.level=INFO
</pre>
</div></div>
<p>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.</p>
</span>
<h2><a name="QpidJavaFAQ-HowcanIconfigurethebroker%3F"></a><span id='tgl_content_q10' class='cloakToggle'></span> How can I configure the broker ?</h2>
<span id='content_q10' class='cloak' style='display: none'>
<p>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></p>
<p>For more detailed information on configuration, please see <a href="Qpid Design - Configuration.html" title="Qpid Design - Configuration">Qpid Design - Configuration</a></p>
</span>
<h2><a name="QpidJavaFAQ-HowcanIchangetheportthebrokerusesatruntime%3F"></a><span id='tgl_content_q11' class='cloakToggle'></span> How can I change the port the broker uses at runtime ?</h2>
<span id='content_q11' class='cloak' style='display: none'>
<p>The broker defaults to use port 5672 at startup.</p>
<p>To change this, use the -p flag at startup i.e. qpid-server -p <port_number_to_use></p>
<p>Use this to get round any issues on your host server with port 5672 being in use/unavailable.</p>
<p>For more detailed information on configuration, please see <a href="Qpid Design - Configuration.html" title="Qpid Design - Configuration">Qpid Design - Configuration</a></p>
</span>
<h2><a name="QpidJavaFAQ-WhatcommandlineoptionscanIpassintotheqpidserverscript%3F"></a><span id='tgl_content_q12' class='cloakToggle'></span> What command line options can I pass into the qpid-server script ?</h2>
<span id='content_q12' class='cloak' style='display: none'>
<p>The following options are available:</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Option </th>
<th class='confluenceTh'> Long Option </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> b </td>
<td class='confluenceTd'> bind </td>
<td class='confluenceTd'> Bind to the specified address overriding any value in the config file </td>
</tr>
<tr>
<td class='confluenceTd'> c </td>
<td class='confluenceTd'> config </td>
<td class='confluenceTd'> Use the given configuration file </td>
</tr>
<tr>
<td class='confluenceTd'> h </td>
<td class='confluenceTd'> help </td>
<td class='confluenceTd'> Prints list of options </td>
</tr>
<tr>
<td class='confluenceTd'> l </td>
<td class='confluenceTd'> logconfig </td>
<td class='confluenceTd'> Use the specified log4j.xml file rather than that in the etc directory </td>
</tr>
<tr>
<td class='confluenceTd'> p </td>
<td class='confluenceTd'> port </td>
<td class='confluenceTd'> Specify port to listen on. Overrides value in config file </td>
</tr>
<tr>
<td class='confluenceTd'> v </td>
<td class='confluenceTd'> version </td>
<td class='confluenceTd'> Print version information and exit </td>
</tr>
<tr>
<td class='confluenceTd'> w </td>
<td class='confluenceTd'> logwatch </td>
<td class='confluenceTd'> Specify interval for checking for logging config changes. Zero means no checking </td>
</tr>
</tbody></table>
<p>For more detailed information on configuration, please see <a href="Qpid Design - Configuration.html" title="Qpid Design - Configuration">Qpid Design - Configuration</a></p>
</span>
<h2><a name="QpidJavaFAQ-HowdoIauthenticatewiththebroker%3FWhatuserid%26passwordshouldIuse%3F"></a><span id='tgl_content_q13' class='cloakToggle'></span> How do I authenticate with the broker ? What user id & password should I use ?</h2>
<span id='content_q13' class='cloak' style='display: none'>
<p>You should login as user guest with password guest</p>
</span>
<h2><a name="QpidJavaFAQ-HowdoIcreatequeuesthatwillalwaysbeinstantiatedatbrokerstartup%3F"></a><span id='tgl_content_q14' class='cloakToggle'></span> How do I create queues that will always be instantiated at broker startup ?</h2>
<span id='content_q14' class='cloak' style='display: none'>
<p>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.</p>
<p>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:</p>
<div class="preformatted"><div class="preformattedContent">
<pre><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>
</pre>
</div></div>
<p>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).</p>
<p>You can amend the config.xml to point at a different virtualhosts.xml file by editing the <virtualhosts/> element.</p>
<p>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:</p>
<p><virtualhosts>/home/myhomedir/virtualhosts.xml</virtualhosts></p>
<p>You can then pass this amended config.xml into the broker at startup using the -c flag i.e.<br/>
qpid-server -c <path>/config.xml</p>
</span>
<h2><a name="QpidJavaFAQ-Wheredoundeliverablemessagesendup%3F"></a><span id='tgl_content_q16' class='cloakToggle'></span> Where do undeliverable messages end up ?</h2>
<span id='content_q16' class='cloak' style='display: none'>
<p>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.</p>
</span>
<h2><a name="QpidJavaFAQ-CanIconfigurethenameoftheQpidbrokerlogfileatruntime%3F"></a><span id='tgl_content_q17' class='cloakToggle'></span> Can I configure the name of the Qpid broker log file at runtime ?</h2>
<span id='content_q17' class='cloak' style='display: none'>
<p>If you simply start the Qpid broker using the default configuration, then the log file is written to $QPID_WORK/log/qpid.log</p>
<p>This is not ideal if you want to run several instances from one install, or acrhive logs to a shared drive from several hosts.</p>
<p>To make life easier, there are two optional ways to configure the naming convention used for the broker log.</p>
<h3><a name="QpidJavaFAQ-Settingaprefixorsuffix"></a>Setting a prefix or suffix</h3>
<p>Users should set the following environment variables before running qpid-server:</p>
<p>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</p>
<p>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</p>
<h3><a name="QpidJavaFAQ-IncludingthePID"></a>Including the PID</h3>
<p>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**</p>
</span>
<h2><a name="QpidJavaFAQ-Myclientapplicationappearstohavehung%3F"></a><span id='tgl_content_q14b' class='cloakToggle'></span> My client application appears to have hung?</h2>
<span id='content_q14b' class='cloak' style='display: none'>
<p>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 <a href="https://issues.apache.org/jira/browse/QPID-429" title="Visit page outside Confluence">QPID-429</a></p>
</span>
<h2><a name="QpidJavaFAQ-HowdoIcontacttheQpidteam%3F"></a><span id='tgl_content_q15' class='cloakToggle'></span> How do I contact the Qpid team ?</h2>
<span id='content_q15' class='cloak' style='display: none'>
<p>For now, subscribe to our developer list (email qpid-dev-subscribe@incubator.apache.com). A users list is currently being set up!</p>
</span>
<br/>
<div class="tabletitle">
<a name="attachments">Attachments:</a>
</div>
<div class="greybox" align="left">
<img src="icons/bullet_blue.gif" height="8" width="8" alt=""/>
<a href="Qpid Java FAQ_attachments/appContext.zip">appContext.zip</a> (application/x-zip-compressed)
<br/>
</div>
</td>
</tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td height="12" background="border/border_bottom.gif"><img src="border/spacer.gif" width="1" height="1" border="0"/></td>
</tr>
<tr>
<td align="center"><font color="grey">Document generated by Confluence on Apr 22, 2008 02:47</font></td>
</tr>
</table>
</body>
</html>
|
