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
|
<html>
<head>
<title>Apache Qpid : Getting Started Guide</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 : Getting Started Guide
</span>
</div>
<div class="pagesubheading">
This page last changed on Apr 22, 2008 by <font color="#0050B2">mmccorma</font>.
</div>
<h1><a name="GettingStartedGuide-"></a><font color="#000000">Installing & Using Qpid (Java)</font></h1>
<h2><a name="GettingStartedGuide-Introduction"></a>Introduction</h2>
<p>The information below details how to install and use the main Broker and Client packages.</p>
<p>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.</p>
<p>Related pages to get you going</p>
<ul>
<li><a href="Qpid Troubleshooting Guide.html" title="Qpid Troubleshooting Guide">Troubleshooting Guide</a></li>
<li><a href="How to Use JNDI.html" title="How to Use JNDI">How to Use JNDI</a></li>
<li><a href="URL Formats.html" title="URL Formats">URL Formats for Qpid</a></li>
<li><a href="Example Classes.html" title="Example Classes">Example Classes</a></li>
</ul>
<p>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.</p>
<h3><a name="GettingStartedGuide-Prerequisites"></a>Prerequisites</h3>
<p>The Qpid broker requires Java 5 or later to be available. 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 !</p>
<p>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.</p>
<h2><a name="GettingStartedGuide-Downloading%26InstallingQpid"></a>Downloading & Installing Qpid</h2>
<p>The latest binary and source distributions of Qpid Broker and Client packages are available from the <a href="Download.html" title="Download">downloads page</a>.</p>
<p>If you want to use a newer version than an official release then you should check out the code from the <a href="Source Repository.html" title="Source Repository">Subversion repository</a> and then consult the <a href="Qpid Java Build How To.html" title="Qpid Java Build How To">Build How To</a> page.</p>
<h3><a name="GettingStartedGuide-BrokerInstall"></a>Broker Install</h3>
<p>Unpack the archive into any directory of your choice e.g c:/qpid</p>
<p>Once unpacked, the package will be installed in a directory with a release label (i.e. qpid-1.0-incubating-M2) and the directories underneath should look something like this:</p>
<p><b>/bin</b></p>
<p>Contains various startup utilities:</p>
<p><b>qpid-server</b> 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-1.0-incubating-M2. This enables the startup script to find default config files in the installed etc directory.</p>
<p><b>qpid-run</b> is a script which allows shell commands to be executed which the qpid-server script utilises.</p>
<p><b>qpid-server.bat</b> is a dos script which runs the broker on Windows. See note above about QPID_HOME.</p>
<p>The other scripts in this directory can be safely ignored for now.</p>
<p><b>/lib</b></p>
<p>Contains all the jars used by the broker, mainly in their own subdirectories.</p>
<p>The <b>broker-launch.jar</b> contains a manifest file which puts the requisite jars into the classpath for broker startup.</p>
<p>Other files & jars in here can be safely ignored for now.</p>
<p><b>/etc</b></p>
<p>Contains the config files used by the broker on startup.</p>
<p><b>/client</b></p>
<p>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.</p>
<p><b>/doc</b></p>
<p>Contains javadoc for the broker.</p>
<p>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</p>
<h2><a name="GettingStartedGuide-EnvironmentVariables"></a>Environment Variables</h2>
<h3><a name="GettingStartedGuide-QpidLocations"></a>Qpid Locations</h3>
<p>You should set the following variables:</p>
<p><b>QPID_HOME</b> - specifies where your install of Qpid exists, used for broker lookups of files etc<br/>
<b>QPID_WORK</b> - defines location of all working files created by the broker including log and db (i.e. BDB if used)<br/>
<b>PATH</b> - ensure that the QPID_HOME/bin directory is added to your path so that the server scripts can run</p>
<ol>
<li>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.</li>
<li>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.</li>
<li>Then set your PATH variable appropriately to include the bin dir</li>
</ol>
<h3><a name="GettingStartedGuide-SettingJAVAenvironment"></a>Setting JAVA environment</h3>
<p>You must make the JDK available available by setting the JAVA_HOME environment variable and adding the JAVA_HOME/bin directory to your PATH.</p>
<p>You should use JDK 1.6, or at least a version later than 1.5_15.</p>
<p>For example, if you have installed the JDK in /home/jdk1.6 then:<br/>
JAVA_HOME should be set to /home/jdk1.6<br/>
PATH should include /home/jdk1.6/bin</p>
<p>To check that you have completed this change successfully, simply type</p>
<p>java -version</p>
<p>You should see something like</p>
<p>java version "1.6.0_02"<br/>
Java(TM) SE Runtime Environment (build 1.6.0_02-b06)<br/>
Java HotSpot(TM) Server VM (build 1.6.0_02-b06, mixed mode)</p>
<p>The Qpid scripts set the classpath and other flags required for the broker to run.</p>
<h2><a name="GettingStartedGuide-Configuration"></a>Configuration</h2>
<p>We ship two example configuration files with the Java broker:</p>
<p><b>persistent_confg.xml</b> - when you want to use any persistent messages with the Qpid broker (currently with BDB)<br/>
<b>transient_config.xml</b> - for transient messaging only</p>
<p>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.</p>
<p>Please visit our <a href="3rd Party Libraries.html" title="3rd Party Libraries">3rd Party Libraries</a> page to get more generic information on how to set up your chosen persistence implementation for Qpid.</p>
<h2><a name="GettingStartedGuide-RunningtheQpidBroker"></a>Running the Qpid Broker</h2>
<p>There are scripts provided to run the broker on Windows and on Linux/Unix.</p>
<h3><a name="GettingStartedGuide-RunningtheQpidBrokeronLinux%2FUnix"></a>Running the Qpid Broker on Linux/Unix</h3>
<ul>
<li>Make sure you have set the QPID_HOME variable as specified above, and QPID_WORK if you don't want the default</li>
<li>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</li>
<li>Then run the qpid-server script from the root dir of your install. (The qpid-server script also supports cygwin environments.)</li>
</ul>
<h3><a name="GettingStartedGuide-CommandLineArguments"></a>Command Line Arguments</h3>
<p>You can get a list of all command line arguments by using the -h argument.</p>
<p>The following command line 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>
<h4><a name="GettingStartedGuide-Checkingthebrokerhasstartedup"></a>Checking the broker has started up</h4>
<p>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:<br/>
2006-07-06 09:18:24,264 INFO [main] server.Main (Main.java:181) - Starting Qpid.AMQP broker<br/>
2006-07-06 09:18:24,331 INFO [main] server.Main (Main.java:251) - Qpid.AMQP listening on non-SSL address 0.0.0.0/0.0.0.0:5672</p>
<p>Note that you may have to edit the log4j.xml in the /etc directory to add an appender for the server.Main class to see loggeds output like this on startup.</p>
<h3><a name="GettingStartedGuide-RunningtheQpidBrokeronWindows"></a>Running the Qpid Broker on Windows</h3>
<p>Simply set the QPID_HOME variable and run the .bat script. All other details as identical to running on Linux/Unix.</p>
<p>So for example:<br/>
qpid-server.bat</p>
<h2><a name="GettingStartedGuide-GettingHelp"></a>Getting Help</h2>
<p>You can view our <a href="Qpid Java FAQ.html" title="Qpid Java FAQ">FAQ</a> and <a href="Qpid Troubleshooting Guide.html" title="Qpid Troubleshooting Guide">Troubleshooting Guide</a> for assistance. If you can't find the information that you need there, then email our qpid users list</p>
<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="Getting Started Guide_attachments/set_classpath.bat">set_classpath.bat</a> (application/octet-stream)
<br/>
<img src="icons/bullet_blue.gif" height="8" width="8" alt=""/>
<a href="Getting Started Guide_attachments/set_classpath.sh">set_classpath.sh</a> (application/octet-stream)
<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>
|
