Apache Qpid

183 Pages·2010·0.59 MB·English

Apache Qpid
Open Source AMQP Messaging
Apache Qpid: Open Source AMQP Messaging
Copyright © 2010 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions
and limitations under the License.
Table of Contents
I. Basics ............................................................................................................................ 1
1. Apache Qpid: Open Source AMQP Messaging ............................................................. 3
AMQP Messaging Brokers ................................................................................... 3
AMQP Client APIs: C++, Java, JMS, Ruby, Python, and C# ...................................... 3
Operating Systems and Platforms: ......................................................................... 3
2. AMQP (Advanced Message Queueing Protocol ............................................................ 5
Download the AMQP Specifications ...................................................................... 5
3. Getting Started ....................................................................................................... 7
4. Download Apache Qpid ........................................................................................... 9
Production Releases ............................................................................................ 9
0.5 Release ........................................................................................................ 9
Multiple Component Packages ...................................................................... 9
Single Component Package .......................................................................... 9
QpidComponents.org ......................................................................................... 10
Contributed C++ Packages ................................................................................. 11
Pre-built Linux Packages ............................................................................ 11
Windows Installer ..................................................................................... 11
Source Code Repository ..................................................................................... 11
II. AMQP Messaging Broker (Implemented in C++) ............................................................... 12
5. Running the AMQP Messaging Broker .................................................................... 13
Running a Qpid C++ Broker ............................................................................ 13
Building the C++ Broker and Client Libraries .............................................. 13
Running the C++ Broker .......................................................................... 13
Most common questions getting qpidd running ............................................. 13
Authentication ........................................................................................ 14
Slightly more complex configuration .......................................................... 15
Loading extra modules ............................................................................ 16
Cheat Sheet for configuring Queue Options ......................................................... 17
Configuring Queue Options ...................................................................... 17
Cheat Sheet for configuring Exchange Options ..................................................... 19
Configuring Exchange Options .................................................................. 19
Using Broker Federation .................................................................................. 21
Introduction ........................................................................................... 21
What Is Broker Federation? ...................................................................... 21
The qpid-route Utility .............................................................................. 21
Example Scenarios .................................................................................. 27
Advanced Topics .................................................................................... 29
SSL .............................................................................................................. 29
SSL How to .......................................................................................... 29
LVQ ............................................................................................................ 31
Understanding LVQ ................................................................................ 31
LVQ semantics: ..................................................................................... 31
LVQ_NO_BROWSE semantics: ................................................................ 32
Example source ...................................................................................... 33
queue state replication ..................................................................................... 36
Asynchronous Replication of Queue State ................................................... 36
Starting a cluster ............................................................................................ 40
Running a Qpidd cluster .......................................................................... 40
ACL ............................................................................................................. 42
v2 ACL file format for brokers ................................................................. 42
Design Documentation ............................................................................. 45
iii
Apache Qpid
v2 ACL User Guide ................................................................................ 46
6. Managing the AMQP Messaging Broker .................................................................. 48
Managing the C++ Broker ................................................................................ 48
Using qpid-config ................................................................................... 48
Using qpid-route ..................................................................................... 50
Using qpid-tool ...................................................................................... 51
Using qpid-printevents ............................................................................. 55
QMan - Qpid Management bridge ..................................................................... 55
QMan : Qpid Management Bridge ............................................................. 55
Qpid Management Framework .......................................................................... 56
What Is QMF ........................................................................................ 56
Getting Started with QMF ........................................................................ 57
QMF Concepts ....................................................................................... 57
The QMF Protocol .................................................................................. 61
How to Write a QMF Console .................................................................. 61
How to Write a QMF Agent ..................................................................... 61
Management Design notes ................................................................................ 61
Status of This Document .......................................................................... 61
Introduction ........................................................................................... 62
Links .................................................................................................... 62
Management Requirements ....................................................................... 62
Definition of Terms ................................................................................ 63
Operational Scenarios: Basic vs. Extended ................................................... 63
Architectural Framework .......................................................................... 63
The Management Exchange ...................................................................... 64
The Protocol .......................................................................................... 65
QMF Python Console Tutorial .......................................................................... 79
Prerequisite - Install Qpid Messaging ......................................................... 79
Synchronous Console Operations ............................................................... 79
Asynchronous Console Operations ............................................................. 84
Discovering what Kinds of Objects are Available .......................................... 88
III. AMQP Messaging Broker (Implemented in Java) .............................................................. 89
7. General User Guides .............................................................................................. 90
Java Broker Feature Guide ............................................................................... 90
The Qpid pure Java broker currently supports the following features: ................ 90
Qpid Java FAQ .............................................................................................. 90
Purpose ................................................................................................... 90
Java Environment Variables ............................................................................ 100
Setting Qpid Environment Variables ......................................................... 100
Qpid Troubleshooting Guide ........................................................................... 100
I'm getting a java.lang.UnsupportedClassVersionError when I try to start the
broker. What does this mean ? .................................................................. 100
I'm having a problem binding to the required host:port at broker startup ? ......... 101
I'm having problems with my classpath. How can I ensure that my classpath is
ok ? ..................................................................................................... 101
I can't get the broker to start. How can I diagnose the problem ? ..................... 101
When I try to send messages to a queue I'm getting a error as the queue does not
exist. What can I do ? ............................................................................. 101
8. How Tos ............................................................................................................ 102
Add New Users ............................................................................................ 102
Available Password file formats ............................................................... 102
Dynamic changes to password files. ......................................................... 103
How password files and PrincipalDatabases relate to authentication
mechanisms .......................................................................................... 104
iv
Apache Qpid
Configure ACLs ........................................................................................... 104
Configure ACLs ................................................................................... 104
Configure Java Qpid to use a SSL connection. .................................................... 104
Using SSL connection with Qpid Java. ...................................................... 104
Setup .................................................................................................. 104
Performing the connection. ..................................................................... 105
Configure Log4j CompositeRolling Appender .................................................... 105
How to configure the CompositeRolling log4j Appender ............................... 105
Configure the Broker via config.xml ................................................................. 107
Broker config.xml Overview ................................................................... 107
Qpid Version ....................................................................................... 107
Configure the Virtual Hosts via virtualhosts.xml ................................................. 107
virtualhosts.xml Overview ...................................................................... 107
Debug using log4j ......................................................................................... 109
Debugging with log4j configurations ........................................................ 109
How to Tune M3 Java Broker Performance ....................................................... 113
Problem Statement ................................................................................ 113
Successful Tuning Options ..................................................................... 113
Next Steps ........................................................................................... 114
Qpid Java Build How To ............................................................................... 114
Build Instructions - General .................................................................... 114
Build Instructions - Trunk ...................................................................... 115
Use Priority Queues ...................................................................................... 118
General Information .............................................................................. 118
Defining Priority Queues ........................................................................ 118
Client configuration/messaging model for priority queues ............................. 119
9. Qpid JMX Management Console ........................................................................... 120
Qpid JMX Management Console ..................................................................... 120
Overview ............................................................................................. 120
10. Management Tools ............................................................................................. 135
MessageStore Tool ........................................................................................ 135
MessageStore Tool ................................................................................ 135
Qpid Java Broker Management CLI ................................................................. 136
How to build Apache Qpid CLI ............................................................... 136
IV. AMQP Messaging Clients Clients ................................................................................. 138
11. AMQP Java JMS Messaging Client ...................................................................... 140
General User Guides ........................................................................................ 140
System Properties ................................................................................. 140
Connection URL Format ........................................................................ 143
Binding URL Format ............................................................................. 145
AMQP Java JMS Examples ............................................................................. 147
12. AMQP C++ Messaging Client ............................................................................. 148
User Guides ................................................................................................. 148
Examples ..................................................................................................... 148
13. AMQP .NET Messaging Client ........................................................................... 149
User Guides ................................................................................................. 149
Apache Qpid: Open Source AMQP Messaging - .NET User Guide .................. 149
Excel AddIn ......................................................................................... 164
WCF .................................................................................................. 166
Examples ..................................................................................................... 167
14. AMQP Python Messaging Client ......................................................................... 168
User Guides ................................................................................................. 168
Examples ..................................................................................................... 168
PythonBrokerTest ......................................................................................... 168
v
Apache Qpid
Python Broker System Test Suite ............................................................. 168
15. AMQP Ruby Messaging Client ........................................................................... 169
Examples ..................................................................................................... 169
V. Appendices ................................................................................................................ 170
16. AMQP compatibility ......................................................................................... 172
AMQP Compatibility of Qpid releases: ............................................................. 172
Interop table by AMQP specification version ..................................................... 173
17. Qpid Interoperability Documentation .................................................................... 174
Qpid Interoperability Documentation ................................................................ 174
SASL .................................................................................................. 174
vi
List of Tables
4.1. ................................................................................................................................. 9
4.2. Broker ........................................................................................................................ 9
4.3. Client ......................................................................................................................... 9
4.4. C++ broker management .............................................................................................. 10
4.5. Java broker management .............................................................................................. 10
5.1. ............................................................................................................................... 27
5.2. ............................................................................................................................... 42
5.3. ............................................................................................................................... 45
5.4. ............................................................................................................................... 46
6.1. ............................................................................................................................... 56
6.2. ............................................................................................................................... 56
6.3. ............................................................................................................................... 59
6.4. ............................................................................................................................... 60
6.5. ............................................................................................................................... 60
6.6. ............................................................................................................................... 63
6.7. ............................................................................................................................... 69
6.8. ............................................................................................................................... 72
6.9. ............................................................................................................................... 72
6.10. .............................................................................................................................. 72
6.11. .............................................................................................................................. 73
6.12. .............................................................................................................................. 73
6.13. .............................................................................................................................. 74
6.14. .............................................................................................................................. 74
6.15. .............................................................................................................................. 75
6.16. .............................................................................................................................. 76
6.17. .............................................................................................................................. 77
6.18. .............................................................................................................................. 84
7.1. Command Line Options .............................................................................................. 94
8.1. .............................................................................................................................. 104
8.2. .............................................................................................................................. 114
8.3. .............................................................................................................................. 115
8.4. .............................................................................................................................. 115
8.5. .............................................................................................................................. 115
11.1. ............................................................................................................................ 144
11.2. ............................................................................................................................ 144
11.3. ............................................................................................................................ 144
11.4. ............................................................................................................................ 145
11.5. Options .................................................................................................................. 145
11.6. ............................................................................................................................ 146
16.1. ............................................................................................................................ 172
16.2. ............................................................................................................................ 173
17.1. ............................................................................................................................ 174
17.2. ............................................................................................................................ 175
vii
List of Examples
11.1. Queues .................................................................................................................. 146
11.2. Topics ................................................................................................................... 146
viii
Part I. Basics
Table of Contents
1. Apache Qpid: Open Source AMQP Messaging ..................................................................... 3
AMQP Messaging Brokers ........................................................................................... 3
AMQP Client APIs: C++, Java, JMS, Ruby, Python, and C# .............................................. 3
Operating Systems and Platforms: ................................................................................. 3
2. AMQP (Advanced Message Queueing Protocol .................................................................... 5
Download the AMQP Specifications .............................................................................. 5
3. Getting Started ............................................................................................................... 7
4. Download Apache Qpid ................................................................................................... 9
Production Releases .................................................................................................... 9
0.5 Release ................................................................................................................ 9
Multiple Component Packages .............................................................................. 9
Single Component Package .................................................................................. 9
QpidComponents.org ................................................................................................. 10
Contributed C++ Packages ......................................................................................... 11
Pre-built Linux Packages .................................................................................... 11
Windows Installer ............................................................................................. 11
Source Code Repository ............................................................................................. 11
2