diff options
Diffstat (limited to 'qpid/doc')
72 files changed, 27671 insertions, 0 deletions
diff --git a/qpid/doc/book/.gitignore b/qpid/doc/book/.gitignore new file mode 100644 index 0000000000..21f1f20096 --- /dev/null +++ b/qpid/doc/book/.gitignore @@ -0,0 +1,21 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you 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. +# + +/build +/out diff --git a/qpid/doc/book/Makefile b/qpid/doc/book/Makefile new file mode 100644 index 0000000000..6e97a0c5cc --- /dev/null +++ b/qpid/doc/book/Makefile @@ -0,0 +1,38 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you 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. +# + +DIRS = src/cpp-broker src/programming + + +.PHONY: all $(DIRS) + +all: $(DIRS) + +clean: + rm -rf build + +html: TARGET = html +html: all + +pdf: TARGET = pdf +pdf: all + +$(DIRS): + $(MAKE) -C $@ $(TARGET) OUTPUTDIR=../../build/ + diff --git a/qpid/doc/book/src/Makefile.inc b/qpid/doc/book/src/Makefile.inc new file mode 100644 index 0000000000..4de5733740 --- /dev/null +++ b/qpid/doc/book/src/Makefile.inc @@ -0,0 +1,63 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you 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. +# + +BOOK=$(wildcard *Book.xml Programming-In-Apache-Qpid.xml ) +XML=$(wildcard *.xml) $(wildcard ../common/*.xml) +IMAGES=$(wildcard images/*.png) +CSS=$(wilcard ../common/css/*.css) + +OUTPUTDIR=output +OUTPUT= $(BOOK:%.xml=$(OUTPUTDIR)/%/) + +all: html pdf + +pdf: $(OUTPUT)/pdf $(BOOK:%.xml=$(OUTPUT)/pdf/%.pdf) + +html: $(OUTPUT)/html $(BOOK:%.xml=$(OUTPUT)/html/index.html) + +$(OUTPUT)/html/images: $(IMAGES) + -mkdir -p $(OUTPUT)/html/images + -cp images/*.png $(OUTPUT)/html/images/ + +$(OUTPUT)/html/css: $(CSS) + -mkdir -p $(OUTPUT)/html/css + -cp ../common/css/*.css $(OUTPUT)/html/css + +$(OUTPUT)/html: + -mkdir -p $(OUTPUT)/html + +$(OUTPUT)/pdf: + -mkdir -p $(OUTPUT)/pdf + +$(OUTPUT)/html/index.html: $(BOOK) $(OUTPUT)/html/css $(OUTPUT)/html/images $(XML) + xsltproc -o $(OUTPUT)/html/ --xinclude --stringparam chunk.section.depth 1 --stringparam section.autolabel 1 --stringparam callout.graphics 0 --stringparam callout.unicode 0 --stringparam section.label.includes.component.label 1 --stringparam use.id.as.filename 1 --stringparam html.stylesheet css/style.css --stringparam section.autolabel.max.depth 3 --stringparam toc.section.depth 2 --stringparam chunker.output.encoding UTF-8 --stringparam css.decoration 0 ../../xsl/html-custom.xsl $< + +%.fo: %.xml + xsltproc --xinclude --stringparam section.autolabel 1 --stringparam callout.graphics 0 --stringparam callout.unicode 0 --stringparam section.label.includes.component.label 1 http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl $< > $@ + + +%.pdf: %.fo + fop $< $@ + +$(OUTPUT)/pdf/%.pdf: %.pdf + @mv $< $@ + +clean: + -rm -rf $(OUTPUT) *.fo + diff --git a/qpid/doc/book/src/common/css/style.css b/qpid/doc/book/src/common/css/style.css new file mode 100644 index 0000000000..c681596592 --- /dev/null +++ b/qpid/doc/book/src/common/css/style.css @@ -0,0 +1,279 @@ +/* + * + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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. + * + */ +ul { + list-style-type:square; +} + +th { + font-weight: bold; +} + +.navfooter td { + font-size:10pt; +} + +.navheader td { + font-size:10pt; +} + +body { + margin:0; + background:#FFFFFF; + font-family:"Verdana", sans-serif; + font-size:10pt; +} + +.container { + width:950px; + margin:0 auto; +} + +body a { + color:#000000; +} + + +div.book { + margin-left:10pt; + margin-right:10pt; +} + +div.preface { + margin-left:10pt; + margin-right:10pt; +} + +div.chapter { + margin-left:10pt; + margin-right:10pt; +} + +div.section { + margin-left:10pt; + margin-right:10pt; +} + +div.titlepage { + margin-left:-10pt; + margin-right:-10pt; +} + +.calloutlist td { + font-size:10pt; +} + +.table-contents table { + border-spacing: 0px; +} + +.table-contents td { + font-size:10pt; + padding-left:6px; + padding-right:6px; +} + +div.breadcrumbs { + font-size:9pt; + margin-right:10pt; + padding-bottom:16px; +} + +.chapter h2.title { + font-size:20pt; + color:#0c3b82; +} + +.chapter .section h2.title { + font-size:18pt; + color:#0c3b82; +} + +.section h2.title { + font-size:16pt; + color:#0c3b82; +} + +.section h3.title { + font-size:14pt; + color:#0c3b82; +} + +.section h4.title { + font-size:12pt; + color:#0c3b82; +} + +.section h5.title { + font-size:12pt; + color:#0c3b82; +} + +.section h6.title { + font-size:12pt; + color:#0c3b82; +} + +.toc a { + font-size:9pt; +} + +.header { + height:100px; + width:950px; + background:url(http://qpid.apache.org/images/header.png) +} + +.logo { + text-align:center; + font-weight:600; + padding:0 0 0 0; + font-size:14px; + font-family:"Verdana", cursive; +} + +.logo a { + color:#000000; + text-decoration:none; +} + +.main_text_area { + margin-left:200px; +} + +.main_text_area_top { + height:14px; + font-size:1px; +} + +.main_text_area_bottom { + display:none; +/* height:14px; + margin-bottom:4px;*/ +} + +.main_text_area_body { + padding:5px 24px; +} + +.main_text_area_body p { + text-align:justify; +} + +.main_text_area br { + line-height:10px; +} + +.main_text_area h1 { + font-size:28px; + font-weight:600; + margin:0 0 24px 0; + color:#0c3b82; + font-family:"Verdana", Times, serif; +} + +.main_text_area h2 { + font-size:24px; + font-weight:600; + margin:24px 0 8px 0; + color:#0c3b82; + font-family:"Verdana",Times, serif; +} + +.main_text_area ol, .main_text_area ul { + padding:0; + margin:10px 0; + margin-left:20px; +} + +.main_text_area li { +/* margin-left:40px; */ +} + +.main_text_area, .menu_box { + font-size:13px; + line-height:17px; + color:#000000; +} + +.main_text_area { + font-size:14px; +} + +.main_text_area a { + color:#000000; +} + +.main_text_area a:hover { + color:#000000; +} + +.menu_box { + width:196px; + float:left; + margin-left:4px; +} + +.menu_box_top { + background:url(http://qpid.apache.org/images/menu_top.png) no-repeat; + height:14px; + font-size:1px; +} + +.menu_box_body { + background:url(http://qpid.apache.org/images/menu_body.png) repeat-y; + padding:5px 24px 5px 24px; +} + +.menu_box_bottom { + background:url(http://qpid.apache.org/images/menu_bottom.png) no-repeat; + height:14px; + font-size:1px; + margin-bottom:1px; +} + +.menu_box h3 { + font-size:20px; + font-weight:500; + margin:0 0 8px 0; + color:#0c3b82; + font-family:"Verdana",Times, serif; +} + +.menu_box ul { + margin:12px; + padding:0px; +} + +.menu_box li { + list-style:square; +} + +.menu_box a { + color:#000000; + text-decoration:none; +} + +.menu_box a:hover { + color:#000000; + text-decoration:underline; +} + + diff --git a/qpid/doc/book/src/cpp-broker/.gitignore b/qpid/doc/book/src/cpp-broker/.gitignore new file mode 100644 index 0000000000..6d31bdba7f --- /dev/null +++ b/qpid/doc/book/src/cpp-broker/.gitignore @@ -0,0 +1,20 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you 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. +# + +/output diff --git a/qpid/doc/book/src/cpp-broker/AMQP-Compatibility.xml b/qpid/doc/book/src/cpp-broker/AMQP-Compatibility.xml new file mode 100644 index 0000000000..e5aa98cf96 --- /dev/null +++ b/qpid/doc/book/src/cpp-broker/AMQP-Compatibility.xml @@ -0,0 +1,713 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section id="AMQP-Compatibility"> + <title> + AMQP compatibility + </title> + <para> + Qpid provides the most complete and compatible implementation + of AMQP. And is the most aggressive in implementing the latest + version of the specification. + </para> + <para> + There are two brokers: + </para> + + <itemizedlist> + <listitem><para>C++ with support for AMQP 0-10</para></listitem> + <listitem><para>Java with support for AMQP 0-8 and 0-9 (0-10 planned)</para></listitem> + </itemizedlist> + <para> + There are client libraries for C++, Java (JMS), .Net (written in + C#), python and ruby. + </para> + <itemizedlist> + <listitem><para>All clients support 0-10 and interoperate with the C++ + broker. + </para></listitem> + </itemizedlist> + <itemizedlist> + <listitem><para>The JMS client supports 0-8, 0-9 and 0-10 and interoperates + with both brokers. + </para></listitem> + </itemizedlist> + <itemizedlist> + <listitem><para>The python and ruby clients will also support all versions, + but the API is dynamically driven by the specification used and + so differs between versions. To work with the Java broker you + must use 0-8 or 0-9, to work with the C++ broker you must use + 0-10. + </para></listitem> + </itemizedlist> + <itemizedlist> + <listitem><para>There are two separate C# clients, one for 0-8 that + interoperates with the Java broker, one for 0-10 that + inteoperates with the C++ broker. + </para></listitem> + </itemizedlist> + <para> + QMF Management is supported in Ruby, Python, C++, and via QMan + for Java JMX & WS-DM. + </para> + <section role="h3" id="AMQPcompatibility-AMQPCompatibilityofQpidreleases-3A"> + <title> + AMQP + Compatibility of Qpid releases: + </title> + <para> + Qpid implements the AMQP Specification, and as the specification + has progressed Qpid is keeping up with the updates. This means + that different Qpid versions support different versions of AMQP. + Here is a simple guide on what use. + </para> + <para> + Here is a matrix that describes the different versions supported + by each release. The status symbols are interpreted as follows: + </para> + + <variablelist> + <varlistentry> + <term>Y</term> + <listitem><para>supported</para></listitem> + </varlistentry> + <varlistentry> + <term>N</term> + <listitem><para>unsupported</para></listitem> + </varlistentry> + <varlistentry> + <term>IP</term> + <listitem><para>in progress</para></listitem> + </varlistentry> + <varlistentry> + <term>P</term> + <listitem><para>planned</para></listitem> + </varlistentry> + </variablelist> + + <table> + <title>AMQP Version Support by Qpid Release</title> + <tgroup cols="6"> + <tbody> + <row> + <entry> + Component + </entry> + <entry> + Spec + </entry> + <entry> + + </entry> + <entry> + + </entry> + <entry> + + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + + </entry> + <entry> + + </entry> + <entry> + M2.1 + </entry> + <entry> + M3 + </entry> + <entry> + M4 + </entry> + <entry> + 0.5 + </entry> + </row> + <row> + <entry> + java client + </entry> + <entry> + 0-10 + </entry> + <entry> + + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + </row> + <row> + <entry> + + </entry> + <entry> + 0-9 + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + </row> + <row> + <entry> + + </entry> + <entry> + 0-8 + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + </row> + <row> + <entry> + java broker + </entry> + <entry> + 0-10 + </entry> + <entry> + + </entry> + <entry> + + </entry> + <entry> + + </entry> + <entry> + P + </entry> + </row> + <row> + <entry> + + </entry> + <entry> + 0-9 + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + </row> + <row> + <entry> + + </entry> + <entry> + 0-8 + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + </row> + <row> + <entry> + c++ client/broker + </entry> + <entry> + 0-10 + </entry> + <entry> + + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + </row> + <row> + <entry> + + </entry> + <entry> + 0-9 + </entry> + <entry> + Y + </entry> + <entry> + + </entry> + <entry> + + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + python client + </entry> + <entry> + 0-10 + </entry> + <entry> + + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + </row> + <row> + <entry> + + </entry> + <entry> + 0-9 + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + </row> + <row> + <entry> + + </entry> + <entry> + 0-8 + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + </row> + <row> + <entry> + ruby client + </entry> + <entry> + 0-10 + </entry> + <entry> + + </entry> + <entry> + + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + </row> + <row> + <entry> + + </entry> + <entry> + 0-8 + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + </row> + <row> + <entry> + C# client + </entry> + <entry> + 0-10 + </entry> + <entry> + + </entry> + <entry> + + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + </row> + <row> + <entry> + + </entry> + <entry> + 0-8 + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + </row> + </tbody> + </tgroup> + </table> + <!--h3--> + </section> + + <section role="h3" id="AMQPcompatibility-InteroptablebyAMQPspecificationversion"> + <title> + Interop + table by AMQP specification version + </title> + <para> + Above table represented in another format. + </para> + <table> + <title>AMQP Version Support - alternate format</title> + <tgroup cols="5"> + <tbody> + <row> + <entry> + + </entry> + <entry> + release + </entry> + <entry> + 0-8 + </entry> + <entry> + 0-9 + </entry> + <entry> + 0-10 + </entry> + </row> + <row> + <entry> + java client + </entry> + <entry> + M3 M4 0.5 + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + </row> + <row> + <entry> + java client + </entry> + <entry> + M2.1 + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + N + </entry> + </row> + <row> + <entry> + java broker + </entry> + <entry> + M3 M4 0.5 + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + N + </entry> + </row> + <row> + <entry> + java broker + </entry> + <entry> + trunk + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + P + </entry> + </row> + <row> + <entry> + java broker + </entry> + <entry> + M2.1 + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + N + </entry> + </row> + <row> + <entry> + c++ client/broker + </entry> + <entry> + M3 M4 0.5 + </entry> + <entry> + N + </entry> + <entry> + N + </entry> + <entry> + Y + </entry> + </row> + <row> + <entry> + c++ client/broker + </entry> + <entry> + M2.1 + </entry> + <entry> + N + </entry> + <entry> + Y + </entry> + <entry> + N + </entry> + </row> + <row> + <entry> + python client + </entry> + <entry> + M3 M4 0.5 + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + </row> + <row> + <entry> + python client + </entry> + <entry> + M2.1 + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + N + </entry> + </row> + <row> + <entry> + ruby client + </entry> + <entry> + M3 M4 0.5 + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + N + </entry> + </row> + <row> + <entry> + ruby client + </entry> + <entry> + trunk + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + P + </entry> + </row> + <row> + <entry> + C# client + </entry> + <entry> + M3 M4 0.5 + </entry> + <entry> + Y + </entry> + <entry> + N + </entry> + <entry> + N + </entry> + </row> + <row> + <entry> + C# client + </entry> + <entry> + trunk + </entry> + <entry> + Y + </entry> + <entry> + N + </entry> + <entry> + Y + </entry> + </row> + </tbody> + </tgroup> + </table> + <!--h3--> + </section> + +</section> diff --git a/qpid/doc/book/src/cpp-broker/AMQP-Messaging-Broker-CPP-Book.xml b/qpid/doc/book/src/cpp-broker/AMQP-Messaging-Broker-CPP-Book.xml new file mode 100644 index 0000000000..6122b12e18 --- /dev/null +++ b/qpid/doc/book/src/cpp-broker/AMQP-Messaging-Broker-CPP-Book.xml @@ -0,0 +1,74 @@ +<?xml version="1.0"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<book xmlns:xi="http://www.w3.org/2001/XInclude"> + <title>AMQP Messaging Broker (Implemented in C++)</title> + <preface> + <title>Introduction</title> + + <para>Qpid provides two AMQP messaging brokers:</para> + + <itemizedlist> + <listitem><para>Implemented in C++ - high performance, low latency, and RDMA support.</para></listitem> + <listitem><para>Implemented in Java - Fully JMS compliant, runs on any Java platform.</para></listitem> + </itemizedlist> + + <para>Both AMQP messaging brokers support clients in multiple + languages, as long as the messaging client and the messaging + broker use the same version of AMQP. See <link + linkend="AMQP-Compatibility">AMQP Compatibility</link> to see + which messaging clients work with each broker.</para> + + <para>This manual contains information specific to the broker that is implemented in C++.</para> + </preface> + +<chapter> + <title> + Running the AMQP Messaging Broker + </title> + + <xi:include href="Running-CPP-Broker.xml"/> + <xi:include href="Cheat-Sheet-for-configuring-Queue-Options.xml"/> + <xi:include href="Cheat-Sheet-for-configuring-Exchange-Options.xml"/> + <xi:include href="Using-Broker-Federation.xml"/> + <xi:include href="Security.xml"/> + <xi:include href="LVQ.xml"/> + <xi:include href="queue-state-replication.xml"/> + <xi:include href="producer-flow-control.xml"/> + <xi:include href="AMQP-Compatibility.xml"/> + <xi:include href="Qpid-Interoperability-Documentation.xml"/> + <xi:include href="Using-message-groups.xml"/> + <xi:include href="Active-Passive-Cluster.xml"/> + <xi:include href="HA-Queue-Replication.xml"/> +</chapter> + + +<chapter id="chapter-Managing-CPP-Broker"> + <title> + Managing the AMQP Messaging Broker + </title> + + <xi:include href="Managing-CPP-Broker.xml"/> + <xi:include href="Qpid-Management-Framework.xml"/> + <xi:include href="QMF-Python-Console-Tutorial.xml"/> +</chapter> +</book> diff --git a/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml b/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml new file mode 100644 index 0000000000..461b75d320 --- /dev/null +++ b/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml @@ -0,0 +1,1229 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you 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 +h"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. + +--> + +<section id="chapter-ha"> + <title>Active-Passive Messaging Clusters</title> + + <section id="ha-overview"> + <title>Overview</title> + <para> + + The High Availability (HA) module provides + <firstterm>active-passive</firstterm>, <firstterm>hot-standby</firstterm> + messaging clusters to provide fault tolerant message delivery. + </para> + <para> + In an active-passive cluster only one broker, known as the + <firstterm>primary</firstterm>, is active and serving clients at a time. The other + brokers are standing by as <firstterm>backups</firstterm>. Changes on the primary + are replicated to all the backups so they are always up-to-date or "hot". Backup + brokers reject client connection attempts, to enforce the requirement that clients + only connect to the primary. + </para> + <para> + If the primary fails, one of the backups is promoted to take over as the new + primary. Clients fail-over to the new primary automatically. If there are multiple + backups, the other backups also fail-over to become backups of the new primary. + </para> + <para> + This approach relies on an external <firstterm>cluster resource manager</firstterm> + to detect failures, choose the new primary and handle network partitions. <ulink + url="https://fedorahosted.org/cluster/wiki/RGManager">rgmanager</ulink> is supported + initially, but others may be supported in the future. + </para> + <section id="ha-at-least-once"> + <title>Avoiding message loss</title> + <para> + In order to avoid message loss, the primary broker <emphasis>delays + acknowledgement</emphasis> of messages received from clients until the + message has been replicated and acknowledged by all of the back-up + brokers, or has been consumed from the primary queue. + </para> + <para> + This ensures that all acknowledged messages are safe: they have either + been consumed or backed up to all backup brokers. Messages that are + consumed <emphasis>before</emphasis> they are replicated do not need to + be replicated. This reduces the work load when replicating a queue with + active consumers. + </para> + <para> + Clients keep <emphasis>unacknowledged</emphasis> messages in a buffer + <footnote> + <para> + You can control the maximum number of messages in the buffer by setting the + client's <literal>capacity</literal>. For details of how to set the capacity + in client code see "Using the Qpid Messaging API" in + <citetitle>Programming in Apache Qpid</citetitle>. + </para> + </footnote> + until they are acknowledged by the primary. If the primary fails, clients will + fail-over to the new primary and <emphasis>re-send</emphasis> all their + unacknowledged messages. + <footnote> + <para> + Clients must use "at-least-once" reliability to enable re-send of unacknowledged + messages. This is the default behaviour, no options need be set to enable it. For + details of client addressing options see "Using the Qpid Messaging API" + in <citetitle>Programming in Apache Qpid</citetitle>. + </para> + </footnote> + </para> + <para> + If the primary crashes, all the <emphasis>acknowledged</emphasis> + messages will be available on the backup that takes over as the new + primary. The <emphasis>unacknowledged</emphasis> messages will be + re-sent by the clients. Thus no messages are lost. + </para> + <para> + Note that this means it is possible for messages to be + <emphasis>duplicated</emphasis>. In the event of a failure it is possible for a + message to received by the backup that becomes the new primary + <emphasis>and</emphasis> re-sent by the client. The application must take steps + to identify and eliminate duplicates. + </para> + <para> + When a new primary is promoted after a fail-over it is initially in + "recovering" mode. In this mode, it delays acknowledgement of messages + on behalf of all the backups that were connected to the previous + primary. This protects those messages against a failure of the new + primary until the backups have a chance to connect and catch up. + </para> + <para> + Not all messages need to be replicated to the back-up brokers. If a + message is consumed and acknowledged by a regular client before it has + been replicated to a backup, then it doesn't need to be replicated. + </para> + <variablelist id="ha-broker-states"> + <title>HA Broker States</title> + <varlistentry> + <term>Stand-alone</term> + <listitem> + <para> + Broker is not part of a HA cluster. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Joining</term> + <listitem> + <para> + Newly started broker, not yet connected to any existing primary. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Catch-up</term> + <listitem> + <para> + A backup broker that is connected to the primary and downloading + existing state (queues, messages etc.) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Ready</term> + <listitem> + <para> + A backup broker that is fully caught-up and ready to take over as + primary. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Recovering</term> + <listitem> + <para> + Newly-promoted primary, waiting for backups to connect and catch up. + Clients can connect but they are stalled until the primary is active. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Active</term> + <listitem> + <para> + The active primary broker with all backups connected and caught-up. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="limitations"> + <title>Limitations</title> + <para> + There are a some known limitations in the current implementation. These + will be fixed in future versions. + </para> + <itemizedlist> + <listitem> + <para> + Transactional changes to queue state are not replicated atomically. If + the primary crashes during a transaction, it is possible that the + backup could contain only part of the changes introduced by a + transaction. + </para> + </listitem> + <listitem> + <para> + Configuration changes (creating or deleting queues, exchanges and + bindings) are replicated asynchronously. Management tools used to + make changes will consider the change complete when it is complete + on the primary, it may not yet be replicated to all the backups. + </para> + </listitem> + <listitem> + <para> + Federation links <emphasis>to</emphasis> the primary will fail over + correctly. Federated links <emphasis>from</emphasis> the primary + will be lost in fail over, they will not be re-connected to the new + primary. It is possible to work around this by replacing the + <literal>qpidd-primary</literal> start up script with a script that + re-creates federation links when the primary is promoted. + </para> + </listitem> + </itemizedlist> + </section> + </section> + + <section id="ha-virtual-ip"> + <title>Virtual IP Addresses</title> + <para> + Some resource managers (including <command>rgmanager</command>) support + <firstterm>virtual IP addresses</firstterm>. A virtual IP address is an IP + address that can be relocated to any of the nodes in a cluster. The + resource manager associates this address with the primary node in the + cluster, and relocates it to the new primary when there is a failure. This + simplifies configuration as you can publish a single IP address rather + than a list. + </para> + <para> + A virtual IP address can be used by clients to connect to the primary. The + following sections will explain how to configure virtual IP addresses for + clients or brokers. + </para> + </section> + + <section id="ha-broker-config"> + <title>Configuring the Brokers</title> + <para> + The broker must load the <filename>ha</filename> module, it is loaded by + default. The following broker options are available for the HA module. + </para> + <note> + <para> + Broker management is required for HA to operate, it is enabled by + default. The option <literal>mgmt-enable</literal> must not be set to + "no" + </para> + </note> + <note> + <para> + Incorrect security settings are a common cause of problems when + getting started, see <xref linkend="ha-security"/>. + </para> + </note> + <table frame="all" id="ha-broker-options"> + <title>Broker Options for High Availability Messaging Cluster</title> + <tgroup align="left" cols="2" colsep="1" rowsep="1"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <thead> + <row> + <entry align="center" nameend="c2" namest="c1"> + Options for High Availability Messaging Cluster + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <literal>ha-cluster <replaceable>yes|no</replaceable></literal> + </entry> + <entry> + Set to "yes" to have the broker join a cluster. + </entry> + </row> + <row> + <entry> + <literal>ha-queue-replication <replaceable>yes|no</replaceable></literal> + </entry> + <entry> + Enable replication of specific queues without joining a cluster, see <xref linkend="ha-queue-replication"/>. + </entry> + </row> + <row> + <entry> + <literal>ha-brokers-url <replaceable>URL</replaceable></literal> + </entry> + <entry> + <para> + The URL + <footnote id="ha-url-grammar"> + <para> + The full format of the URL is given by this grammar: + <programlisting> +url = ["amqp:"][ user ["/" password] "@" ] addr ("," addr)* +addr = tcp_addr / rmda_addr / ssl_addr / ... +tcp_addr = ["tcp:"] host [":" port] +rdma_addr = "rdma:" host [":" port] +ssl_addr = "ssl:" host [":" port]' + </programlisting> + </para> + </footnote> + used by cluster brokers to connect to each other. The URL should + contain a comma separated list of the broker addresses, rather than a + virtual IP address. + </para> + </entry> + </row> + <row> + <entry><literal>ha-public-url <replaceable>URL</replaceable></literal> </entry> + <entry> + <para> + This option is only needed for backwards compatibility if you + have been using the <literal>amq.failover</literal> exchange. + This exchange is now obsolete, it is recommended to use a + virtual IP address instead. + </para> + <para> + If set, this URL is advertised by the + <literal>amq.failover</literal> exchange and overrides the + broker option <literal>known-hosts-url</literal> + </para> + </entry> + </row> + <row> + <entry><literal>ha-replicate </literal><replaceable>VALUE</replaceable></entry> + <entry> + <para> + Specifies whether queues and exchanges are replicated by default. + <replaceable>VALUE</replaceable> is one of: <literal>none</literal>, + <literal>configuration</literal>, <literal>all</literal>. + For details see <xref linkend="ha-replicate-values"/>. + </para> + </entry> + </row> + <row> + <entry> + <para><literal>ha-username <replaceable>USER</replaceable></literal></para> + <para><literal>ha-password <replaceable>PASS</replaceable></literal></para> + <para><literal>ha-mechanism <replaceable>MECHANISM</replaceable></literal></para> + </entry> + <entry> + Authentication settings used by HA brokers to connect to each other, + see <xref linkend="ha-security"/> + </entry> + </row> + <row> + <entry><literal>ha-backup-timeout<replaceable>SECONDS</replaceable></literal> + <footnote id="ha-seconds-spec"> + <para> + Values specified as <replaceable>SECONDS</replaceable> can be a + fraction of a second, e.g. "0.1" for a tenth of a second. + They can also have an explicit unit, + e.g. 10s (seconds), 10ms (milliseconds), 10us (microseconds), 10ns (nanoseconds) + </para> + </footnote> + </entry> + <entry> + <para> + Maximum time that a recovering primary will wait for an expected + backup to connect and become ready. + </para> + </entry> + </row> + <row> + <entry> + <literal>link-maintenance-interval <replaceable>SECONDS</replaceable></literal> + <footnoteref linkend="ha-seconds-spec"/> + </entry> + <entry> + <para> + HA uses federation links to connect from backup to primary. + Backup brokers check the link to the primary on this interval + and re-connect if need be. Default 2 seconds. Set lower for + faster failover, e.g. 0.1 seconds. Setting too low will result + in excessive link-checking on the backups. + </para> + </entry> + </row> + <row> + <entry> + <literal>link-heartbeat-interval <replaceable>SECONDS</replaceable></literal> + <footnoteref linkend="ha-seconds-spec"/> + </entry> + <entry> + <para> + HA uses federation links to connect from backup to primary. + If no heart-beat is received for twice this interval the primary will consider that + backup dead (e.g. if backup is hung or partitioned.) + This interval is also used to time-out for broker status checks, + it may take up to this interval for rgmanager to detect a hung or partitioned broker. + Clients sending messages may be held up during this time. + Default 120 seconds: you will probably want to set this to a lower value e.g. 10. + If set too low rgmanager may consider a slow broker to have failed and kill it. + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + <para> + To configure a HA cluster you must set at least <literal>ha-cluster</literal> and + <literal>ha-brokers-url</literal>. + </para> + </section> + + <section id="ha-rm"> + <title>The Cluster Resource Manager</title> + <para> + Broker fail-over is managed by a <firstterm>cluster resource + manager</firstterm>. An integration with <ulink + url="https://fedorahosted.org/cluster/wiki/RGManager">rgmanager</ulink> is + provided, but it is possible to integrate with other resource managers. + </para> + <para> + The resource manager is responsible for starting the <command>qpidd</command> broker + on each node in the cluster. The resource manager then <firstterm>promotes</firstterm> + one of the brokers to be the primary. The other brokers connect to the primary as + backups, using the URL provided in the <literal>ha-brokers-url</literal> configuration + option. + </para> + <para> + Once connected, the backup brokers synchronize their state with the + primary. When a backup is synchronized, or "hot", it is ready to take + over if the primary fails. Backup brokers continually receive updates + from the primary in order to stay synchronized. + </para> + <para> + If the primary fails, backup brokers go into fail-over mode. The resource + manager must detect the failure and promote one of the backups to be the + new primary. The other backups connect to the new primary and synchronize + their state with it. + </para> + <para> + The resource manager is also responsible for protecting the cluster from + <firstterm>split-brain</firstterm> conditions resulting from a network partition. A + network partition divide a cluster into two sub-groups which cannot see each other. + Usually a <firstterm>quorum</firstterm> voting algorithm is used that disables nodes + in the inquorate sub-group. + </para> + </section> + + <section id="ha-rm-config"> + <title>Configuring with <command>rgmanager</command> as resource manager</title> + <para> + This section assumes that you are already familiar with setting up and configuring + clustered services using <command>cman</command> and + <command>rgmanager</command>. It will show you how to configure an active-passive, + hot-standby <command>qpidd</command> HA cluster with <command>rgmanager</command>. + </para> + <note> + <para> + Once all components are installed it is important to take the following step: + <programlisting> +chkconfig rgmanager on +chkconfig cman on +chkconfig qpidd <emphasis>off</emphasis> + </programlisting> + </para> + <para> + The qpidd service must be <emphasis>off</emphasis> in + <literal>chkconfig</literal> because <literal>rgmanager</literal> will + start and stop <literal>qpidd</literal>. If the normal system init + process also attempts to start and stop qpidd it can cause rgmanager to + lose track of qpidd processes. The symptom when this happens is that + <literal>clustat</literal> shows a <literal>qpidd</literal> service to + be stopped when in fact there is a <literal>qpidd</literal> process + running. The <literal>qpidd</literal> log will show errors like this: + <programlisting> +critical Unexpected error: Daemon startup failed: Cannot lock /var/lib/qpidd/lock: Resource temporarily unavailable + </programlisting> + </para> + </note> + <para> + You must provide a <literal>cluster.conf</literal> file to configure + <command>cman</command> and <command>rgmanager</command>. Here is + an example <literal>cluster.conf</literal> file for a cluster of 3 nodes named + node1, node2 and node3. We will go through the configuration step-by-step. + </para> + <programlisting> + <![CDATA[ +<?xml version="1.0"?> +<!-- +This is an example of a cluster.conf file to run qpidd HA under rgmanager. +This example assumes a 3 node cluster, with nodes named node1, node2 and node3. + +NOTE: fencing is not shown, you must configure fencing appropriately for your cluster. +--> + +<cluster name="qpid-test" config_version="18"> + <!-- The cluster has 3 nodes. Each has a unique nodeid and one vote + for quorum. --> + <clusternodes> + <clusternode name="node1.example.com" nodeid="1"/> + <clusternode name="node2.example.com" nodeid="2"/> + <clusternode name="node3.example.com" nodeid="3"/> + </clusternodes> + + <!-- Resouce Manager configuration. --> + + status_poll_interval is the interval in seconds that the resource manager checks the status + of managed services. This affects how quickly the manager will detect failed services. + --> + <rm status_poll_interval="1"> + <!-- + There is a failoverdomain for each node containing just that node. + This lets us stipulate that the qpidd service should always run on each node. + --> + <failoverdomains> + <failoverdomain name="node1-domain" restricted="1"> + <failoverdomainnode name="node1.example.com"/> + </failoverdomain> + <failoverdomain name="node2-domain" restricted="1"> + <failoverdomainnode name="node2.example.com"/> + </failoverdomain> + <failoverdomain name="node3-domain" restricted="1"> + <failoverdomainnode name="node3.example.com"/> + </failoverdomain> + </failoverdomains> + + <resources> + <!-- This script starts a qpidd broker acting as a backup. --> + <script file="/etc/init.d/qpidd" name="qpidd"/> + + <!-- This script promotes the qpidd broker on this node to primary. --> + <script file="/etc/init.d/qpidd-primary" name="qpidd-primary"/> + + <!-- + This is a virtual IP address for client traffic. + monitor_link="yes" means monitor the health of the NIC used for the VIP. + sleeptime="0" means don't delay when failing over the VIP to a new address. + --> + <ip address="20.0.20.200" monitor_link="yes" sleeptime="0"/> + </resources> + + <!-- There is a qpidd service on each node, it should be restarted if it fails. --> + <service name="node1-qpidd-service" domain="node1-domain" recovery="restart"> + <script ref="qpidd"/> + </service> + <service name="node2-qpidd-service" domain="node2-domain" recovery="restart"> + <script ref="qpidd"/> + </service> + <service name="node3-qpidd-service" domain="node3-domain" recovery="restart"> + <script ref="qpidd"/> + </service> + + <!-- There should always be a single qpidd-primary service, it can run on any node. --> + <service name="qpidd-primary-service" autostart="1" exclusive="0" recovery="relocate"> + <script ref="qpidd-primary"/> + <!-- The primary has the IP addresses for brokers and clients to connect. --> + <ip ref="20.0.20.200"/> + </service> + </rm> +</cluster> + ]]> + </programlisting> + + <para> + There is a <literal>failoverdomain</literal> for each node containing just that + one node. This lets us stipulate that the qpidd service should always run on all + nodes. + </para> + <para> + The <literal>resources</literal> section defines the <command>qpidd</command> + script used to start the <command>qpidd</command> service. It also defines the + <command>qpid-primary</command> script which does not + actually start a new service, rather it promotes the existing + <command>qpidd</command> broker to primary status. + </para> + <para> + The <literal>resources</literal> section also defines a virtual IP + address for clients: <literal>20.0.20.200</literal>. + </para> + <para> + <filename>qpidd.conf</filename> should contain these lines: + </para> + <programlisting> +ha-cluster=yes +ha-brokers-url=20.0.20.1,20.0.20.2,20.0.20.3 + </programlisting> + <para> + The brokers connect to each other directly via the addresses + listed in <command>ha-brokers-url</command>. Note the client and broker + addresses are on separate sub-nets, this is recommended but not required. + </para> + <para> + The <literal>service</literal> section defines 3 <literal>qpidd</literal> + services, one for each node. Each service is in a restricted fail-over + domain containing just that node, and has the <literal>restart</literal> + recovery policy. The effect of this is that rgmanager will run + <command>qpidd</command> on each node, restarting if it fails. + </para> + <para> + There is a single <literal>qpidd-primary-service</literal> using the + <command>qpidd-primary</command> script which is not restricted to a + domain and has the <literal>relocate</literal> recovery policy. This means + rgmanager will start <command>qpidd-primary</command> on one of the nodes + when the cluster starts and will relocate it to another node if the + original node fails. Running the <literal>qpidd-primary</literal> script + does not start a new broker process, it promotes the existing broker to + become the primary. + </para> + + <section id="ha-rm-shutdown-node"> + <title>Shutting down qpidd on a HA node</title> + <para> + As explained above both the per-node <literal>qpidd</literal> service + and the re-locatable <literal>qpidd-primary</literal> service are + implemented by the same <literal>qpidd</literal> daemon. + </para> + <para> + As a result, stopping the <literal>qpidd</literal> service will not stop + a <literal>qpidd</literal> daemon that is acting as primary, and + stopping the <literal>qpidd-primary</literal> service will not stop a + <literal>qpidd</literal> process that is acting as backup. + </para> + <para> + To shut down a node that is acting as primary you need to shut down the + <literal>qpidd</literal> service <emphasis>and</emphasis> relocate the + primary: + </para> + <para> + <programlisting> +clusvcadm -d somenode-qpidd-service +clusvcadm -r qpidd-primary-service + </programlisting> + </para> + <para> + This will shut down the <literal>qpidd</literal> daemon on that node and + prevent the primary service service from relocating back to the node + because the qpidd service is no longer running there. + </para> + </section> + </section> + + <section id="ha-broker-admin"> + <title>Broker Administration Tools</title> + <para> + Normally, clients are not allowed to connect to a backup broker. However + management tools are allowed to connect to a backup brokers. If you use + these tools you <emphasis>must not</emphasis> add or remove messages from + replicated queues, nor create or delete replicated queues or exchanges as + this will disrupt the replication process and may cause message loss. + </para> + <para> + <command>qpid-ha</command> allows you to view and change HA configuration settings. + </para> + <para> + The tools <command>qpid-config</command>, <command>qpid-route</command> and + <command>qpid-stat</command> will connect to a backup if you pass the flag <command>ha-admin</command> on the + command line. + </para> + </section> + + <section id="ha-replicate-values"> + <title>Controlling replication of queues and exchanges</title> + <para> + By default, queues and exchanges are not replicated automatically. You can change + the default behaviour by setting the <literal>ha-replicate</literal> configuration + option. It has one of the following values: + <itemizedlist> + <listitem> + <para> + <firstterm>all</firstterm>: Replicate everything automatically: queues, + exchanges, bindings and messages. + </para> + </listitem> + <listitem> + <para> + <firstterm>configuration</firstterm>: Replicate the existence of queues, + exchange and bindings but don't replicate messages. + </para> + </listitem> + <listitem> + <para> + <firstterm>none</firstterm>: Don't replicate anything, this is the default. + </para> + </listitem> + </itemizedlist> + </para> + <para> + You can over-ride the default for a particular queue or exchange by passing the + argument <literal>qpid.replicate</literal> when creating the queue or exchange. It + takes the same values as <literal>ha-replicate</literal> + </para> + <para> + Bindings are automatically replicated if the queue and exchange being bound both + have replication <literal>all</literal> or <literal>configuration</literal>, they + are not replicated otherwise. + </para> + <para> + You can create replicated queues and exchanges with the + <command>qpid-config</command> management tool like this: + </para> + <programlisting> +qpid-config add queue myqueue --replicate all + </programlisting> + <para> + To create replicated queues and exchanges via the client API, add a + <literal>node</literal> entry to the address like this: + </para> + <programlisting> +"myqueue;{create:always,node:{x-declare:{arguments:{'qpid.replicate':all}}}}" + </programlisting> + <para> + There are some built-in exchanges created automatically by the broker, these + exchanges are never replicated. The built-in exchanges are the default (nameless) + exchange, the AMQP standard exchanges (<literal>amq.direct, amq.topic, amq.fanout</literal> and + <literal>amq.match</literal>) and the management exchanges (<literal>qpid.management, qmf.default.direct</literal> and + <literal>qmf.default.topic</literal>) + </para> + <para> + Note that if you bind a replicated queue to one of these exchanges, the + binding will <emphasis>not</emphasis> be replicated, so the queue will not + have the binding after a fail-over. + </para> + </section> + + <section id="ha-failover"> + <title>Client Connection and Fail-over</title> + <para> + Clients can only connect to the primary broker. Backup brokers reject any + connection attempt by a client. Clients rejected by a backup broker will + automatically fail-over until they connect to the primary. + </para> + <para> + Clients are configured with the URL for the cluster (details below for + each type of client). There are two possibilities + <itemizedlist> + <listitem> + <para> + The URL contains multiple addresses, one for each broker in the cluster. + </para> + </listitem> + <listitem> + <para> + The URL contains a single <firstterm>virtual IP address</firstterm> + that is assigned to the primary broker by the resource manager. + This is the recommended configuration. + </para> + </listitem> + </itemizedlist> + In the first case, clients will repeatedly re-try each address in the URL + until they successfully connect to the primary. In the second case the + resource manager will assign the virtual IP address to the primary broker, + so clients only need to re-try on a single address. + </para> + <para> + When the primary broker fails, clients re-try all known cluster addresses + until they connect to the new primary. The client re-sends any messages + that were previously sent but not acknowledged by the broker at the time + of the failure. Similarly messages that have been sent by the broker, but + not acknowledged by the client, are re-queued. + </para> + <para> + TCP can be slow to detect connection failures. A client can configure a + connection to use a <firstterm>heartbeat</firstterm> to detect connection + failure, and can specify a time interval for the heartbeat. If heartbeats + are in use, failures will be detected no later than twice the heartbeat + interval. The following sections explain how to enable heartbeat in each + client. + </para> + <para> + Note: the following sections explain how to configure clients with + multiple dresses, but if you are using a virtual IP address you only need + to configure that one address for clients, you don't need to list all the + addresses. + </para> + <para> + Suppose your cluster has 3 nodes: <literal>node1</literal>, + <literal>node2</literal> and <literal>node3</literal> all using the + default AMQP port, and you are not using a virtual IP address. To connect + a client you need to specify the address(es) and set the + <literal>reconnect</literal> property to <literal>true</literal>. The + following sub-sections show how to connect each type of client. + </para> + <section id="ha-clients"> + <title>C++ clients</title> + <para> + With the C++ client, you specify multiple cluster addresses in a single URL + <footnote> + <para> + The full grammar for the URL is: + </para> + <programlisting> +url = ["amqp:"][ user ["/" password] "@" ] addr ("," addr)* +addr = tcp_addr / rmda_addr / ssl_addr / ... +tcp_addr = ["tcp:"] host [":" port] +rdma_addr = "rdma:" host [":" port] +ssl_addr = "ssl:" host [":" port]' + </programlisting> + </footnote> + You also need to specify the connection option + <literal>reconnect</literal> to be true. For example: + </para> + <programlisting> +qpid::messaging::Connection c("node1,node2,node3","{reconnect:true}"); + </programlisting> + <para> + Heartbeats are disabled by default. You can enable them by specifying a + heartbeat interval (in seconds) for the connection via the + <literal>heartbeat</literal> option. For example: + </para> + <programlisting> +qpid::messaging::Connection c("node1,node2,node3","{reconnect:true,heartbeat:10}"); + </programlisting> + </section> + <section id="ha-python-client"> + <title>Python clients</title> + <para> + With the python client, you specify <literal>reconnect=True</literal> + and a list of <replaceable>host:port</replaceable> addresses as + <literal>reconnect_urls</literal> when calling + <literal>Connection.establish</literal> or + <literal>Connection.open</literal> + </para> + <programlisting> +connection = qpid.messaging.Connection.establish("node1", reconnect=True, reconnect_urls=["node1", "node2", "node3"]) + </programlisting> + <para> + Heartbeats are disabled by default. You can + enable them by specifying a heartbeat interval (in seconds) for the + connection via the 'heartbeat' option. For example: + </para> + <programlisting> +connection = qpid.messaging.Connection.establish("node1", reconnect=True, reconnect_urls=["node1", "node2", "node3"], heartbeat=10) + </programlisting> + </section> + <section id="ha-jms-client"> + <title>Java JMS Clients</title> + <para> + In Java JMS clients, client fail-over is handled automatically if it is + enabled in the connection. You can configure a connection to use + fail-over using the <command>failover</command> property: + </para> + + <screen> + connectionfactory.qpidConnectionfactory = amqp://guest:guest@clientid/test?brokerlist='tcp://localhost:5672'&failover='failover_exchange' + </screen> + <para> + This property can take three values: + </para> + <variablelist> + <title>Fail-over Modes</title> + <varlistentry> + <term>failover_exchange</term> + <listitem> + <para> + If the connection fails, fail over to any other broker in the cluster. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term>roundrobin</term> + <listitem> + <para> + If the connection fails, fail over to one of the brokers specified in the <command>brokerlist</command>. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term>singlebroker</term> + <listitem> + <para> + Fail-over is not supported; the connection is to a single broker only. + </para> + + </listitem> + + </varlistentry> + + </variablelist> + <para> + In a Connection URL, heartbeat is set using the <command>heartbeat</command> property, which is an integer corresponding to the heartbeat period in seconds. For instance, the following line from a JNDI properties file sets the heartbeat time out to 3 seconds: + </para> + + <screen> + connectionfactory.qpidConnectionfactory = amqp://guest:guest@clientid/test?brokerlist='tcp://localhost:5672'&heartbeat='3' + </screen> + </section> + </section> + + <section id="ha-security"> + <title>Security and Access Control.</title> + <para> + This section outlines the HA specific aspects of security configuration. + Please see <xref linkend="chap-Messaging_User_Guide-Security"/> for + more details on enabling authentication and setting up Access Control Lists. + </para> + <note> + <para> + Unless you disable authentication with <literal>auth=no</literal> in + your configuration, you <emphasis>must</emphasis> set the options below + and you <emphasis>must</emphasis> have an ACL file with at least the + entry described below. + </para> + <para> + Backups will be <emphasis>unable to connect to the primary</emphasis> if + the security configuration is incorrect. See also <xref + linkend="ha-troubleshoot-security"/> + </para> + </note> + <para> + When authentication is enabled you must set the credentials used by HA + brokers with following options: + </para> + <table frame="all" id="ha-security-options"> + <title>HA Security Options</title> + <tgroup align="left" cols="2" colsep="1" rowsep="1"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <thead> + <row> + <entry align="center" nameend="c2" namest="c1"> + HA Security Options + </entry> + </row> + </thead> + <tbody> + <row> + <entry><para><literal>ha-username</literal> <replaceable>USER</replaceable></para></entry> + <entry><para>User name for HA brokers. Note this must <emphasis>not</emphasis> include the <literal>@QPID</literal> suffix.</para></entry> + </row> + <row> + <entry><para><literal>ha-password</literal> <replaceable>PASS</replaceable></para></entry> + <entry><para>Password for HA brokers.</para></entry> + </row> + <row> + <entry><para><literal>ha-mechanism</literal> <replaceable>MECHANISM</replaceable></para></entry> + <entry> + <para> + Mechanism for HA brokers. Any mechanism you enable for + broker-to-broker communication can also be used by a client, so + do not use ha-mechanism=ANONYMOUS in a secure environment. + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + <para> + This identity is used to authorize federation links from backup to + primary. It is also used to authorize actions on the backup to replicate + primary state, for example creating queues and exchanges. + </para> + <para> + When authorization is enabled you must have an Access Control List with the + following rule to allow HA replication to function. Suppose + <literal>ha-username</literal>=<replaceable>USER</replaceable> + </para> + <programlisting> +acl allow <replaceable>USER</replaceable>@QPID all all + </programlisting> + </section> + + <section id="ha-other-rm"> + <title>Integrating with other Cluster Resource Managers</title> + <para> + To integrate with a different resource manager you must configure it to: + <itemizedlist> + <listitem><para>Start a qpidd process on each node of the cluster.</para></listitem> + <listitem><para>Restart qpidd if it crashes.</para></listitem> + <listitem><para>Promote exactly one of the brokers to primary.</para></listitem> + <listitem><para>Detect a failure and promote a new primary.</para></listitem> + </itemizedlist> + </para> + <para> + The <command>qpid-ha</command> command allows you to check if a broker is + primary, and to promote a backup to primary. + </para> + <para> + To test if a broker is the primary: + </para> + <programlisting>qpid-ha -b <replaceable>broker-address</replaceable> status --expect=primary</programlisting> + <para> + This will return 0 if the broker at <replaceable>broker-address</replaceable> is the primary, + non-0 otherwise. + </para> + <para> + To promote a broker to primary: + <programlisting>qpid-ha --cluster-manager -b <replaceable>broker-address</replaceable> promote</programlisting> + </para> + <para> + Note that <literal>promote</literal> is considered a "cluster manager + only" command. Incorrect use of <literal>promote</literal> outside of the + cluster manager could create a cluster with multiple primaries. Such a + cluster will malfunction and lose data. "Cluster manager only" commands + are not accessible in <command>qpid-ha</command> without the + <literal>--cluster-manager</literal> option. + </para> + <para> + To list the full set of commands use: + </para> + <programlisting> +qpid-ha --cluster-manager --help + </programlisting> + </section> + + <section id ="ha-store"> + <title>Using a message store in a cluster</title> + <para> + If you use a persistent store for your messages then each broker in a + cluster will have its own store. If the entire cluster fails and is + restarted, the *first* broker that becomes primary will recover from its + store. All the other brokers will clear their stores and get an update + from the primary to ensure consistency. + </para> + </section> + + <section id="ha-troubleshoot"> + <title>Troubleshooting a cluster</title> + <para> + This section applies to clusters that are using rgmanager as the + cluster manager. + </para> + <section id="ha-troubleshoot-no-primary"> + <title>No primary broker</title> + <para> + When you initially start a HA cluster, all brokers are in + <literal>joining</literal> mode. The brokers do not automatically select + a primary, they rely on the cluster manager <literal>rgmanager</literal> + to do so. If <literal>rgmanager</literal> is not running or is not + configured correctly, brokers will remain in the + <literal>joining</literal> state. See <xref linkend="ha-rm-config"/> + </para> + </section> + <section id="ha-troubleshoot-security"> + <title>Authentication and ACL failures</title> + <para> + If a broker is unable to establish a connection to another broker in the + cluster due to authentication or ACL problems the logs may contain + errors like the following: + <programlisting> +info SASL: Authentication failed: SASL(-13): user not found: Password verification failed + </programlisting> + <programlisting> +warning Client closed connection with 320: User anonymous@QPID federation connection denied. Systems with authentication enabled must specify ACL create link rules. + </programlisting> + <programlisting> +warning Client closed connection with 320: ACL denied anonymous@QPID creating a federation link. + </programlisting> + </para> + <para> + Set the HA security configuration and ACL file as described in <xref + linkend="ha-security"/>. Once the cluster is running and the primary is + promoted , run: + <programlisting>qpid-ha status --all</programlisting> + to make sure that the brokers are running as one cluster. + </para> + </section> + <section id="ha-troubleshoot-slow-recovery"> + <title>Slow recovery times</title> + <para> + The following configuration settings affect recovery time. The + values shown are examples that give fast recovery on a lightly + loaded system. You should run tests to determine if the values are + appropriate for your system and load conditions. + </para> + <section id="ha-troubleshoot-cluster.conf"> + <title>cluster.conf:</title> + <programlisting> +<rm status_poll_interval=1> + </programlisting> + <para> + status_poll_interval is the interval in seconds that the + resource manager checks the status of managed services. This + affects how quickly the manager will detect failed services. + </para> + <programlisting> +<ip address="20.0.20.200" monitor_link="yes" sleeptime="0"/> + </programlisting> + <para> + This is a virtual IP address for client traffic. + monitor_link="yes" means monitor the health of the network interface + used for the VIP. sleeptime="0" means don't delay when + failing over the VIP to a new address. + </para> + </section> + <section id="ha-troubleshoot-qpidd.conf"> + <title>qpidd.conf</title> + <programlisting> +link-maintenance-interval=0.1 + </programlisting> + <para> + Interval for backup brokers to check the link to the primary + re-connect if need be. Default 2 seconds. Can be set lower for + faster fail-over. Setting too low will result in excessive + link-checking activity on the broker. + </para> + <programlisting> +link-heartbeat-interval=5 + </programlisting> + <para> + Heartbeat interval for federation links. The HA cluster uses + federation links between the primary and each backup. The + primary can take up to twice the heartbeat interval to detect a + failed backup. When a sender sends a message the primary waits + for all backups to acknowledge before acknowledging to the + sender. A disconnected backup may cause the primary to block + senders until it is detected via heartbeat. + </para> + <para> + This interval is also used as the timeout for broker status + checks by rgmanager. It may take up to this interval for + rgmanager to detect a hung broker. + </para> + <para> + The default of 120 seconds is very high, you will probably want + to set this to a lower value. If set too low, under network + congestion or heavy load, a slow-to-respond broker may be + re-started by rgmanager. + </para> + </section> + </section> + <section id="ha-troubleshoot-total-cluster-failure"> + <title>Total cluster failure</title> + <para> + Note: for definition of broker states <firstterm>joining</firstterm>, + <firstterm>catch-up</firstterm>, <firstterm>ready</firstterm>, + <firstterm>recovering</firstterm> and <firstterm>active</firstterm> see + <xref linkend="ha-broker-states"/> + </para> + <para> + The cluster can only guarantee availability as long as there is at + least one active primary broker or ready backup broker left alive. + If all the brokers fail simultaneously, the cluster will fail and + non-persistent data will be lost. + </para> + <para> + While there is an active primary broker, clients can get service. + If the active primary fails, one of the "ready" backup + brokers will take over, recover and become active. Note a backup + can only be promoted to primary if it is in the "ready" + state (with the exception of the first primary in a new cluster + where all brokers are in the "joining" state) + </para> + <para> + Given a stable cluster of N brokers with one active primary and + N-1 ready backups, the system can sustain up to N-1 failures in + rapid succession. The surviving broker will be promoted to active + and continue to give service. + </para> + <para> + However at this point the system <emphasis>cannot</emphasis> + sustain a failure of the surviving broker until at least one of + the other brokers recovers, catches up and becomes a ready backup. + If the surviving broker fails before that the cluster will fail in + one of two modes (depending on the exact timing of failures) + </para> + <section id="ha-troubleshoot-the-cluster-hangs"> + <title>1. The cluster hangs</title> + <para> + All brokers are in joining or catch-up mode. rgmanager tries to + promote a new primary but cannot find any candidates and so + gives up. clustat will show that the qpidd services are running + but the the qpidd-primary service has stopped, something like + this: + </para> + <programlisting> +Service Name Owner (Last) State +------- ---- ----- ------ ----- +service:mrg33-qpidd-service 20.0.10.33 started +service:mrg34-qpidd-service 20.0.10.34 started +service:mrg35-qpidd-service 20.0.10.35 started +service:qpidd-primary-service (20.0.10.33) stopped + </programlisting> + <para> + Eventually all brokers become stuck in "joining" mode, + as shown by: <literal>qpid-ha status --all</literal> + </para> + <para> + At this point you need to restart the cluster in one of the + following ways: + <orderedlist> + <listitem><para> + Restart the entire cluster: + In <literal>luci:<replaceable>your-cluster</replaceable>:Nodes</literal> + click reboot to restart the entire cluster + </para></listitem> + <listitem><para> + Stop and restart the cluster with + <literal>ccs --stopall; ccs --startall</literal> + </para></listitem> + <listitem><para> + Restart just the Qpid services:In <literal>luci:<replaceable>your-cluster</replaceable>:Service Groups</literal> + <orderedlist> + <listitem><para>Select all the qpidd (not qpidd-primary) services, click restart</para></listitem> + <listitem><para>Select the qpidd-primary service, click restart</para></listitem> + </orderedlist> + </para></listitem> + <listitem><para> + Stop the <literal>qpidd-primary</literal> and + <literal>qpidd</literal> services with <literal>clusvcadm</literal>, + then restart (qpidd-primary last) + </para></listitem> + </orderedlist> + </para> + </section> + <section id="ha-troubleshoot-the-cluster-reboots"> + <title>2. The cluster reboots</title> + <para> + A new primary is promoted and the cluster is functional but all + non-persistent data from before the failure is lost. + </para> + </section> + </section> + <section id="ha-troubleshoot-fencing-and-network-partitions"> + <title>Fencing and network partitions</title> + <para> + A network partition is a a network failure that divides the + cluster into two or more sub-clusters, where each broker can + communicate with brokers in its own sub-cluster but not with + brokers in other sub-clusters. This condition is also referred to + as a "split brain". + </para> + <para> + Nodes in one sub-cluster can't tell whether nodes in other + sub-clusters are dead or are still running but disconnected. We + cannot allow each sub-cluster to independently declare its own + qpidd primary and start serving clients, as the cluster will + become inconsistent. We must ensure only one sub-cluster continues + to provide service. + </para> + <para> + A <emphasis>quorum</emphasis> determines which sub-cluster + continues to operate, and <emphasis>power fencing</emphasis> + ensures that nodes in non-quorate sub-clusters cannot attempt to + provide service inconsistently. For more information see: + </para> + <para> + https://access.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/6/html-single/High_Availability_Add-On_Overview/index.html, + chapter 2. Quorum and 4. Fencing. + </para> + </section> + </section> +</section> diff --git a/qpid/doc/book/src/cpp-broker/Cheat-Sheet-for-configuring-Exchange-Options.xml b/qpid/doc/book/src/cpp-broker/Cheat-Sheet-for-configuring-Exchange-Options.xml new file mode 100644 index 0000000000..fccdae1b9a --- /dev/null +++ b/qpid/doc/book/src/cpp-broker/Cheat-Sheet-for-configuring-Exchange-Options.xml @@ -0,0 +1,144 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section> + <title> + Cheat Sheet for configuring Exchange Options + </title> + + <section role="h2" id="CheatSheetforconfiguringExchangeOptions-ConfiguringExchangeOptions"> + <title> + Configuring Exchange Options + </title> + <para> + The C++ Broker M4 or later supports the following additional + Exchange options in addition to the standard AMQP define options + </para><itemizedlist> + <listitem><para>Exchange Level Message sequencing + </para></listitem> + <listitem><para>Initial Value Exchange + </para></listitem> + </itemizedlist><para> + Note that these features can be used on any exchange type, that + has been declared with the options set. + </para><para> + It also supports an additional option to the bind operation on a + direct exchange + </para><itemizedlist> + <listitem><para>Exclusive binding for key + </para></listitem> + </itemizedlist> + + <section role="h3" id="CheatSheetforconfiguringExchangeOptions-ExchangeLevelMessagesequencing"><title> + Exchange Level Message sequencing + </title> + <para> + This feature can be used to place a sequence number into each + message's headers, based on the order they pass through an + exchange. The sequencing starts at 0 and then wraps in an AMQP + int64 type. + </para><para> + The field name used is "qpid.msg_sequence" + </para><para> + To use this feature an exchange needs to be declared specifying + this option in the declare + </para> + <programlisting> +.... + FieldTable args; + args.setInt("qpid.msg_sequence",1); + +... + // now declare the exchange + session.exchangeDeclare(arg::exchange="direct", arg::arguments=args); +</programlisting> + <para> + Then each message passing through that exchange will be numbers + in the application headers. + </para> + <programlisting> + unit64_t seqNo; + //after message transfer + seqNo = message.getHeaders().getAsInt64("qpid.msg_sequence"); +</programlisting> + <!--h3--></section> + <section role="h3" id="CheatSheetforconfiguringExchangeOptions-InitialValueExchange"><title> + Initial + Value Exchange + </title> + <para> + This feature caches a last message sent to an exchange. When a + new binding is created onto the exchange it will then attempt to + route this cached messaged to the queue, based on the binding. + This allows for topics or the creation of configurations where a + new consumer can receive the last message sent to the broker, + with matching routing. + </para><para> + To use this feature an exchange needs to be declared specifying + this option in the declare + </para> + <programlisting> +.... + FieldTable args; + args.setInt("qpid.ive",1); + +... + // now declare the exchange + session.exchangeDeclare(arg::exchange="direct", arg::arguments=args); +</programlisting> + <para> + now use the exchange in the same way you would use any other + exchange. + </para> + <!--h3--></section> + + <section role="h3" id="CheatSheetforconfiguringExchangeOptions-Exclusivebindingforkey"><title> + Exclusive + binding for key + </title> + <para> + Direct exchanges in qpidd support a qpid.exclusive-binding option + on the bind operation that causes the binding specified to be the + only one for the given key. I.e. if there is already a binding at + this exchange with this key it will be atomically updated to bind + the new queue. This means that the binding can be changed + concurrently with an incoming stream of messages and each message + will be routed to exactly one queue. + </para> + <programlisting> +.... + FieldTable args; + args.setInt("qpid.exclusive-binding",1); + + //the following will cause the only binding from amq.direct with 'my-key' + //to be the one to 'my-queue'; if there were any previous bindings for that + //key they will be removed. This is atomic w.r.t message routing through the + //exchange. + session.exchangeBind(arg::exchange="amq.direct", arg::queue="my-queue", + arg::bindingKey="my-key", arg::arguments=args); + +... +</programlisting> +<!--h3--></section> +<!--h2--></section> +</section> diff --git a/qpid/doc/book/src/cpp-broker/Cheat-Sheet-for-configuring-Queue-Options.xml b/qpid/doc/book/src/cpp-broker/Cheat-Sheet-for-configuring-Queue-Options.xml new file mode 100644 index 0000000000..125372e463 --- /dev/null +++ b/qpid/doc/book/src/cpp-broker/Cheat-Sheet-for-configuring-Queue-Options.xml @@ -0,0 +1,198 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section><title> + Cheat Sheet for configuring Queue Options + </title> + + <section role="h2" id="CheatSheetforconfiguringQueueOptions-ConfiguringQueueOptions"><title> + Configuring + Queue Options + </title> + + <para> + The C++ Broker M4 or later supports the following additional + Queue constraints. + </para> + <itemizedlist> + <listitem><para> + <xref linkend="CheatSheetforconfiguringQueueOptions-ConfiguringQueueOptions"/> + </para></listitem> + <listitem><para> + <itemizedlist> + <listitem><para> + <xref linkend="CheatSheetforconfiguringQueueOptions-ApplyingQueueSizingConstraints"/> + </para></listitem> + <listitem><para> + <xref linkend="CheatSheetforconfiguringQueueOptions-ChangingtheQueueorderingBehaviors-28FIFO-2FLVQ-29"/> + </para></listitem> + <listitem><para> + <xref linkend="CheatSheetforconfiguringQueueOptions-Settingadditionalbehaviors"/> + </para></listitem> + <listitem><para> + <itemizedlist> + <listitem><para> + <xref linkend="CheatSheetforconfiguringQueueOptions-Queueeventgeneration"/> + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <xref linkend="CheatSheetforconfiguringQueueOptions-OtherClients"/> + </para></listitem> + </itemizedlist> + </para></listitem> + </itemizedlist> + + <para> + The 0.10 C++ Broker supports the following additional Queue configuration options: + </para> + <itemizedlist> + <listitem><para> + <xref linkend="producer-flow-control"/> + </para></listitem> + </itemizedlist> + + <section role="h3" id="CheatSheetforconfiguringQueueOptions-ApplyingQueueSizingConstraints"><title> + Applying Queue Sizing Constraints + </title> + + <para> + This allows to specify how to size a queue and what to do when + the sizing constraints have been reached. The queue size can be + limited by the number messages (message depth) or byte depth on + the queue. + </para><para> + Once the Queue meets/ exceeds these constraints the follow + policies can be applied + </para><itemizedlist> + <listitem><para>REJECT - Reject the published message + </para></listitem> + <listitem><para>FLOW_TO_DISK - Flow the messages to disk, to preserve memory + </para></listitem> + <listitem><para>RING - start overwriting messages in a ring based on sizing. + If head meets tail, advance head + </para></listitem> + <listitem><para>RING_STRICT - start overwriting messages in a ring based on + sizing. If head meets tail, AND the consumer has the tail message + acquired it will reject + </para></listitem> + </itemizedlist><para> + Examples: + </para><para> + Create a queue an auto delete queue that will support 100 000 + bytes, and then REJECT + </para> + <programlisting> +#include "qpid/client/QueueOptions.h" + + QueueOptions qo; + qo.setSizePolicy(REJECT,100000,0); + + session.queueDeclare(arg::queue=queue, arg::autoDelete=true, arg::arguments=qo); +</programlisting> + <para> + Create a queue that will support 1000 messages into a RING buffer + </para> + <programlisting> +#include "qpid/client/QueueOptions.h" + + QueueOptions qo; + qo.setSizePolicy(RING,0,1000); + + session.queueDeclare(arg::queue=queue, arg::arguments=qo); +</programlisting> + <!--h3--></section> + <section role="h3" id="CheatSheetforconfiguringQueueOptions-ChangingtheQueueorderingBehaviors-28FIFO-2FLVQ-29"><title> + Changing the Queue ordering Behaviors (FIFO/LVQ) + </title> + <para> + The default ordering in a queue in Qpid is FIFO. However + additional ordering semantics can be used namely LVQ (Last Value + Queue). Last Value Queue is define as follows. + </para><para> + If I publish symbols RHT, IBM, JAVA, MSFT, and then publish RHT + before the consumer is able to consume RHT, that message will be + over written in the queue and the consumer will receive the last + published value for RHT. + </para><para> + Example: + </para> + <programlisting> +#include "qpid/client/QueueOptions.h" + + QueueOptions qo; + qo.setOrdering(LVQ); + + session.queueDeclare(arg::queue=queue, arg::arguments=qo); + + ..... + string key; + qo.getLVQKey(key); + + .... + for each message, set the into application headers before transfer + message.getHeaders().setString(key,"RHT"); + +</programlisting> + <para> + Notes: + </para><itemizedlist> + <listitem><para>Messages that are dequeued and the re-queued will have the + following exceptions. a.) if a new message has been queued with + the same key, the re-queue from the consumer, will combine these + two messages. b.) If an update happens for a message of the same + key, after the re-queue, it will not update the re-queued + message. This is done to protect a client from being able to + adversely manipulate the queue. + </para></listitem> + <listitem><para>Acquire: When a message is acquired from the queue, no matter + it's position, it will behave the same as a dequeue + </para></listitem> + <listitem><para>LVQ does not support durable messages. If the queue or + messages are declared durable on an LVQ, the durability will be + ignored. + </para></listitem> + </itemizedlist><para> + A fully worked <xref linkend="LVQ-Example"/> can be found here + </para> + <!--h3--></section> + <section role="h3" id="CheatSheetforconfiguringQueueOptions-Settingadditionalbehaviors"><title> + Setting additional behaviors + </title> + <!--h3--></section> + <section role="h3" id="CheatSheetforconfiguringQueueOptions-OtherClients"><title> + Other + Clients + </title> + <para> + Note that these options can be set from any client. QueueOptions + just correctly formats the arguments passed to the QueueDeclare() + method. + </para> + + <!--h3--></section> + + <!--h2--></section> + + +</section> diff --git a/qpid/doc/book/src/cpp-broker/HA-Queue-Replication.xml b/qpid/doc/book/src/cpp-broker/HA-Queue-Replication.xml new file mode 100644 index 0000000000..81b55a3914 --- /dev/null +++ b/qpid/doc/book/src/cpp-broker/HA-Queue-Replication.xml @@ -0,0 +1,126 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you 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. + +--> + +<section id="ha-queue-replication"> + <title>Replicating Queues with the HA module</title> + <para> + As well as support for an active-passive cluster, the + HA module allows you to replicate individual queues, + even if the brokers are not in a cluster. The <firstterm>original</firstterm> + queue is used as normal. The <firstterm>replica</firstterm> queue is + updated automatically as messages are added to or removed from the original + queue. + </para> + <warning> + <para> + It is not safe to modify the replica queue + other than via the automatic updates from the original. Adding or removing + messages on the replica queue will make replication inconsistent and may + cause message loss. + The HA module does <emphasis>not</emphasis> enforce + restricted access to the replica queue (as it does in the case of a cluster) + so it is up to the application to ensure the replica is not used until it has + been disconnected from the original. + </para> + </warning> + <section> + <title>Replicating queues</title> + <para> + To create a replica queue, the HA module must be + loaded on both the original and replica brokers (it is loaded by default.) + You also need to set the configuration option: + <programlisting> + ha-queue-replication=yes + </programlisting> + to enable this feature on a stand-alone broker. It is automatically + enabled for brokers that are part of a cluster. + </para> + <para> + Suppose that <command>myqueue</command> is a queue on + <command>node1</command> and we want to create a replica of + <command>myqueue</command> on <command>node2</command> (where both brokers + are using the default AMQP port.) This is accomplished by the command: + <programlisting> + qpid-config --broker=node2 add queue --start-replica node1 myqueue + </programlisting> + If <command>myqueue</command> already exists on the replica + broker you can start replication from the original queue like this: + <programlisting> + qpid-ha replicate -b node2 node1 myqueue + </programlisting> + </para> + </section> + <section> + <title>Replicating queues between clusters</title> + <para> + You can replicate queues between two standalone brokers, between a + standalone broker and a cluster, or between two clusters (see <xref + linkend="chapter-ha"/>.) For failover in a cluster there are two cases to + consider. + </para> + <orderedlist> + <listitem> + <para> + When the <emphasis>original</emphasis> queue is on the active node + of a cluster, failover is automatic. If the active node + fails, the replication link will automatically reconnect and the + replica will continue to be updated from the new primary. + </para> + </listitem> + <listitem> + <para> + When the <emphasis>replica</emphasis> queue is on the active node of a + cluster, there is no automatic failover. However you can use the + following workaround. + </para> + </listitem> + </orderedlist> + <section> + <title>Work around for fail-over of replica queue in a cluster</title> + <para> + When a primary broker fails the cluster resource manager calls a script + to promote a backup broker to be the new primary. By default this script + is <filename>/etc/init.d/qpidd-primary</filename> but you can modify + that in your <filename>cluster.conf</filename> file (see <xref + linkend="ha-rm-config"/>.) + </para> + <para> + You can modify this script (on each host in your cluster) by adding + commands to create your replica queues just before the broker is + promoted, as indicated in the following exceprt from the script: + <programlisting> +start() { + service qpidd start + echo -n $"Promoting qpid daemon to cluster primary: " + ################################ + #### Add your commands here #### + ################################ + $QPID_HA -b localhost:$QPID_PORT promote + [ "$?" -eq 0 ] && success || failure +} + </programlisting> + Your commands will be run, and your replicas created, whenever + the system fails over to a new primary. + </para> + </section> + </section> +</section> diff --git a/qpid/doc/book/src/cpp-broker/LVQ.xml b/qpid/doc/book/src/cpp-broker/LVQ.xml new file mode 100644 index 0000000000..b57c6268be --- /dev/null +++ b/qpid/doc/book/src/cpp-broker/LVQ.xml @@ -0,0 +1,181 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section> + <title>LVQ - Last Value Queue</title> + + <section role="h2" id="LVQ-UnderstandingLVQ"> + <title>Understanding LVQ</title> + <para> + A Last Value Queue is configured with the name of a message header that + is used as a key. The queue behaves as a normal FIFO queue with the + exception that when a message is enqueued, any other message in the + queue with the same value in the key header is removed and discarded. + Thus, for any given key value, the queue holds only the most recent + message. + </para> + <para> + The following example illustrates the operation of a Last Value Queue. + The example shows an empty queue with no consumers and a sequence of + produced messages. The numbers represent the key for each message. + </para> + <programlisting> + <empty queue> + 1 => + 1 + 2 => + 1 2 + 3 => + 1 2 3 + 4 => + 1 2 3 4 + 2 => + 1 3 4 2 + 1 => + 3 4 2 1 + </programlisting> + <para> + Note that the first four messages are enqueued normally in FIFO order. + The fifth message has key '2' and is also enqueued on the tail of the + queue. However the message already in the queue with the same key is + discarded. + <note> + <para> + If the set of keys used in the messages in a LVQ is constrained, the + number of messages in the queue shall not exceed the number of + distinct keys in use. + </para> + </note> + </para> + <section role="h3" id="LVQ-UnderstandingLVQ-UseCases"> + <title>Common Use-Cases</title> + <itemizedlist> + <listitem> + <para> + LVQ with zero or one consuming subscriptions - In this case, if + the consumer drops momentarily or is slower than the producer(s), + it will only receive current information relative to the message + keys. + </para> + </listitem> + <listitem> + <para> + LVQ with zero or more browsing subscriptions - A browsing consumer + can subscribe to the LVQ and get an immediate dump of all of the + "current" messages and track updates thereafter. Any number of + independent browsers can subscribe to the same LVQ with the same + effect. Since messages are never consumed, they only disappear + when replaced with a newer message with the same key or when their + TTL expires. + </para> + </listitem> + </itemizedlist> + </section> + </section> + + <section role="h2" id="LVQ-Creating"> + <title>Creating a Last Value Queue</title> + <section role="h3" id="LVQ-Creating-Address"> + <title>Using Addressing Syntax</title> + <para> + A LVQ may be created using directives in the API's address syntax. + The important argument is "qpid.last_value_queue_key". The following + Python example shows how a producer of stock price updates can create + a LVQ to hold the latest stock prices for each ticker symbol. The + message header used to hold the ticker symbol is called "ticker". + </para> + <programlisting> + conn = Connection(url) + conn.open() + sess = conn.session() + tx = sess.sender("prices;{create:always, node:{type:queue, x-declare:{arguments:{'qpid.last_value_queue_key':'ticker'}}}}") + </programlisting> + </section> + <section role="h3" id="LVQ-Creating-Tool"> + <title>Using qpid-config</title> + <para> + The same LVQ as shown in the previous example can be created using the + qpid-config utility: + </para> + <programlisting> + $ qpid-config add queue prices --lvq-key ticker + </programlisting> + </section> + </section> + + <section role="h2" id="LVQ-Example"> + <title>LVQ Example</title> + + <section role="h3" id="LVQ-Example-Sender"> + <title>LVQ Sender</title> + <programlisting> + from qpid.messaging import Connection, Message + + def send(sender, key, message): + message.properties["ticker"] = key + sender.send(message) + + conn = Connection("localhost") + conn.open() + sess = conn.session() + tx = sess.sender("prices;{create:always, node:{type:queue,x-declare:{arguments:{'qpid.last_value_queue_key':ticker}}}}") + + msg = Message("Content") + send(tx, "key1", msg); + send(tx, "key2", msg); + send(tx, "key3", msg); + send(tx, "key4", msg); + send(tx, "key2", msg); + send(tx, "key1", msg); + + conn.close() + </programlisting> + </section> + + <section role="h3" id="LVQ-Example-Receiver"> + <title>LVQ Browsing Receiver</title> + <programlisting> + from qpid.messaging import Connection, Message + + conn = Connection("localhost") + conn.open() + sess = conn.session() + rx = sess.receiver("prices;{mode:browse}") + + while True: + msg = rx.fetch() + sess.acknowledge() + print msg + </programlisting> + </section> + </section> + + <section role="h2" id="LVQ-Deprecated"> + <title>Deprecated LVQ Modes</title> + <para> + There are two legacy modes (still implemented as of Qpid 0.14) + controlled by the qpid.last_value_queue and + qpid.last_value_queue_no_browse argument values. These modes are + deprecated and should not be used. + </para> + </section> +</section> diff --git a/qpid/doc/book/src/cpp-broker/Makefile b/qpid/doc/book/src/cpp-broker/Makefile new file mode 100644 index 0000000000..0266a0f54d --- /dev/null +++ b/qpid/doc/book/src/cpp-broker/Makefile @@ -0,0 +1,20 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you 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. +# + +include ../Makefile.inc diff --git a/qpid/doc/book/src/cpp-broker/Managing-CPP-Broker.xml b/qpid/doc/book/src/cpp-broker/Managing-CPP-Broker.xml new file mode 100644 index 0000000000..ab72bf286b --- /dev/null +++ b/qpid/doc/book/src/cpp-broker/Managing-CPP-Broker.xml @@ -0,0 +1,480 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section id="section-Managing-CPP-Broker"> + <title> Managing the C++ Broker </title> + <para> + There are quite a few ways to interact with the C++ broker. The + command line tools + include: + </para><itemizedlist> + <listitem><para>qpid-route - used to configure federation (a set of federated + brokers) + </para></listitem> + <listitem><para>qpid-config - used to configure queues, exchanges, bindings + and list them etc + </para></listitem> + <listitem><para>qpid-tool - used to view management information/statistics + and call any management actions on the broker + </para></listitem> + <listitem><para>qpid-printevents - used to receive and print QMF events + </para></listitem> + <listitem><para>qpid-ha - used to interact with the High Availability module + </para></listitem> + </itemizedlist> + + <section role="h3" id="MgmtC-2B-2B-Usingqpidconfig"><title> + Using qpid-config + </title> + <para> + This utility can be used to create queues exchanges and bindings, + both durable and transient. Always check for latest options by + running --help command. + </para> + <programlisting> +$ qpid-config --help +Usage: qpid-config [OPTIONS] + qpid-config [OPTIONS] exchanges [filter-string] + qpid-config [OPTIONS] queues [filter-string] + qpid-config [OPTIONS] add exchange <type> <name> [AddExchangeOptions] + qpid-config [OPTIONS] del exchange <name> + qpid-config [OPTIONS] add queue <name> [AddQueueOptions] + qpid-config [OPTIONS] del queue <name> + qpid-config [OPTIONS] bind <exchange-name> <queue-name> [binding-key] + qpid-config [OPTIONS] unbind <exchange-name> <queue-name> [binding-key] + +Options: + -b [ --bindings ] Show bindings in queue or exchange list + -a [ --broker-addr ] Address (localhost) Address of qpidd broker + broker-addr is in the form: [username/password@] hostname | ip-address [:<port>] + ex: localhost, 10.1.1.7:10000, broker-host:10000, guest/guest@localhost + +Add Queue Options: + --durable Queue is durable + --file-count N (8) Number of files in queue's persistence journal + --file-size N (24) File size in pages (64Kib/page) + --max-queue-size N Maximum in-memory queue size as bytes + --max-queue-count N Maximum in-memory queue size as a number of messages + --limit-policy [none | reject | flow-to-disk | ring | ring-strict] + Action taken when queue limit is reached: + none (default) - Use broker's default policy + reject - Reject enqueued messages + flow-to-disk - Page messages to disk + ring - Replace oldest unacquired message with new + ring-strict - Replace oldest message, reject if oldest is acquired + --order [fifo | lvq | lvq-no-browse] + Set queue ordering policy: + fifo (default) - First in, first out + lvq - Last Value Queue ordering, allows queue browsing + lvq-no-browse - Last Value Queue ordering, browsing clients may lose data + +Add Exchange Options: + --durable Exchange is durable + --sequence Exchange will insert a 'qpid.msg_sequence' field in the message header + with a value that increments for each message forwarded. + --ive Exchange will behave as an 'initial-value-exchange', keeping a reference + to the last message forwarded and enqueuing that message to newly bound + queues. +</programlisting> + <para> + Get the summary page + </para> + <programlisting> +$ qpid-config +Total Exchanges: 6 + topic: 2 + headers: 1 + fanout: 1 + direct: 2 + Total Queues: 7 + durable: 0 + non-durable: 7 +</programlisting> + <para> + List the queues + </para> + <programlisting> +$ qpid-config queues +Queue Name Attributes +================================================================= +pub_start +pub_done +sub_ready +sub_done +perftest0 --durable +reply-dhcp-100-18-254.bos.redhat.com.20713 auto-del excl +topic-dhcp-100-18-254.bos.redhat.com.20713 auto-del excl + +</programlisting> + <para> + List the exchanges with bindings + </para> + <programlisting> +$ ./qpid-config -b exchanges +Exchange '' (direct) + bind pub_start => pub_start + bind pub_done => pub_done + bind sub_ready => sub_ready + bind sub_done => sub_done + bind perftest0 => perftest0 + bind mgmt-3206ff16-fb29-4a30-82ea-e76f50dd7d15 => mgmt-3206ff16-fb29-4a30-82ea-e76f50dd7d15 + bind repl-3206ff16-fb29-4a30-82ea-e76f50dd7d15 => repl-3206ff16-fb29-4a30-82ea-e76f50dd7d15 +Exchange 'amq.direct' (direct) + bind repl-3206ff16-fb29-4a30-82ea-e76f50dd7d15 => repl-3206ff16-fb29-4a30-82ea-e76f50dd7d15 + bind repl-df06c7a6-4ce7-426a-9f66-da91a2a6a837 => repl-df06c7a6-4ce7-426a-9f66-da91a2a6a837 + bind repl-c55915c2-2fda-43ee-9410-b1c1cbb3e4ae => repl-c55915c2-2fda-43ee-9410-b1c1cbb3e4ae +Exchange 'amq.topic' (topic) +Exchange 'amq.fanout' (fanout) +Exchange 'amq.match' (headers) +Exchange 'qpid.management' (topic) + bind mgmt.# => mgmt-3206ff16-fb29-4a30-82ea-e76f50dd7d15 +</programlisting> +<!--h3--></section> + + <section role="h3" id="MgmtC-2B-2B-Usingqpidroute"><title> + Using qpid-route + </title> + <para> + This utility is to create federated networks of brokers, This + allows you for forward messages between brokers in a network. + Messages can be routed statically (using "qpid-route route add") + where the bindings that control message forwarding are supplied + in the route. Message routing can also be dynamic (using + "qpid-route dynamic add") where the messages are automatically + forwarded to clients based on their bindings to the local broker. + </para> + <programlisting> +$ qpid-route +Usage: qpid-route [OPTIONS] dynamic add <dest-broker> <src-broker> <exchange> [tag] [exclude-list] + qpid-route [OPTIONS] dynamic del <dest-broker> <src-broker> <exchange> + + qpid-route [OPTIONS] route add <dest-broker> <src-broker> <exchange> <routing-key> [tag] [exclude-list] + qpid-route [OPTIONS] route del <dest-broker> <src-broker> <exchange> <routing-key> + qpid-route [OPTIONS] queue add <dest-broker> <src-broker> <exchange> <queue> + qpid-route [OPTIONS] queue del <dest-broker> <src-broker> <exchange> <queue> + qpid-route [OPTIONS] route list [<dest-broker>] + qpid-route [OPTIONS] route flush [<dest-broker>] + qpid-route [OPTIONS] route map [<broker>] + + qpid-route [OPTIONS] link add <dest-broker> <src-broker> + qpid-route [OPTIONS] link del <dest-broker> <src-broker> + qpid-route [OPTIONS] link list [<dest-broker>] + +Options: + -v [ --verbose ] Verbose output + -q [ --quiet ] Quiet output, don't print duplicate warnings + -d [ --durable ] Added configuration shall be durable + -e [ --del-empty-link ] Delete link after deleting last route on the link + -s [ --src-local ] Make connection to source broker (push route) + -t <transport> [ --transport <transport>] + Specify transport to use for links, defaults to tcp + + dest-broker and src-broker are in the form: [username/password@] hostname | ip-address [:<port>] + ex: localhost, 10.1.1.7:10000, broker-host:10000, guest/guest@localhost +</programlisting> + <para> + A few examples: + </para> + <programlisting> +qpid-route dynamic add host1 host2 fed.topic +qpid-route dynamic add host2 host1 fed.topic + +qpid-route -v route add host1 host2 hub1.topic hub2.topic.stock.buy +qpid-route -v route add host1 host2 hub1.topic hub2.topic.stock.sell +qpid-route -v route add host1 host2 hub1.topic 'hub2.topic.stock.#' +qpid-route -v route add host1 host2 hub1.topic 'hub2.#' +qpid-route -v route add host1 host2 hub1.topic 'hub2.topic.#' +qpid-route -v route add host1 host2 hub1.topic 'hub2.global.#' +</programlisting> + <para> + The link map feature can be used to display the entire federated + network configuration by supplying a single broker as an entry + point: + </para> + <programlisting> +$ qpid-route route map localhost:10001 + +Finding Linked Brokers: + localhost:10001... Ok + localhost:10002... Ok + localhost:10003... Ok + localhost:10004... Ok + localhost:10005... Ok + localhost:10006... Ok + localhost:10007... Ok + localhost:10008... Ok + +Dynamic Routes: + + Exchange fed.topic: + localhost:10002 <=> localhost:10001 + localhost:10003 <=> localhost:10002 + localhost:10004 <=> localhost:10002 + localhost:10005 <=> localhost:10002 + localhost:10006 <=> localhost:10005 + localhost:10007 <=> localhost:10006 + localhost:10008 <=> localhost:10006 + + Exchange fed.direct: + localhost:10002 => localhost:10001 + localhost:10004 => localhost:10003 + localhost:10003 => localhost:10002 + localhost:10001 => localhost:10004 + +Static Routes: + + localhost:10003(ex=amq.direct) <= localhost:10005(ex=amq.direct) key=rkey + localhost:10003(ex=amq.direct) <= localhost:10005(ex=amq.direct) key=rkey2 +</programlisting> +<!--h3--></section> + + <section role="h3" id="MgmtC-2B-2B-Usingqpidtool"><title> + Using qpid-tool + </title> + <para> + This utility provided a telnet style interface to be able to + view, list all stats and action + all the methods. Simple capture below. Best to just play with it + and mail the list if you have + questions or want features added. + </para> + <programlisting> +qpid: +qpid: help +Management Tool for QPID +Commands: + list - Print summary of existing objects by class + list <className> - Print list of objects of the specified class + list <className> all - Print contents of all objects of specified class + list <className> active - Print contents of all non-deleted objects of specified class + list <list-of-IDs> - Print contents of one or more objects (infer className) + list <className> <list-of-IDs> - Print contents of one or more objects + list is space-separated, ranges may be specified (i.e. 1004-1010) + call <ID> <methodName> <args> - Invoke a method on an object + schema - Print summary of object classes seen on the target + schema <className> - Print details of an object class + set time-format short - Select short timestamp format (default) + set time-format long - Select long timestamp format + quit or ^D - Exit the program +qpid: list +Management Object Types: + ObjectType Active Deleted + ================================ + qpid.binding 21 0 + qpid.broker 1 0 + qpid.client 1 0 + qpid.exchange 6 0 + qpid.queue 13 0 + qpid.session 4 0 + qpid.system 1 0 + qpid.vhost 1 0 +qpid: list qpid.system +Objects of type qpid.system + ID Created Destroyed Index + ================================== + 1000 21:00:02 - host +qpid: list 1000 +Object of type qpid.system: (last sample time: 21:26:02) + Type Element 1000 + ======================================================= + config sysId host + config osName Linux + config nodeName localhost.localdomain + config release 2.6.24.4-64.fc8 + config version #1 SMP Sat Mar 29 09:15:49 EDT 2008 + config machine x86_64 +qpid: schema queue +Schema for class 'qpid.queue': + Element Type Unit Access Notes Description + =================================================================================================================== + vhostRef reference ReadCreate index + name short-string ReadCreate index + durable boolean ReadCreate + autoDelete boolean ReadCreate + exclusive boolean ReadCreate + arguments field-table ReadOnly Arguments supplied in queue.declare + storeRef reference ReadOnly Reference to persistent queue (if durable) + msgTotalEnqueues uint64 message Total messages enqueued + msgTotalDequeues uint64 message Total messages dequeued + msgTxnEnqueues uint64 message Transactional messages enqueued + msgTxnDequeues uint64 message Transactional messages dequeued + msgPersistEnqueues uint64 message Persistent messages enqueued + msgPersistDequeues uint64 message Persistent messages dequeued + msgDepth uint32 message Current size of queue in messages + msgDepthHigh uint32 message Current size of queue in messages (High) + msgDepthLow uint32 message Current size of queue in messages (Low) + byteTotalEnqueues uint64 octet Total messages enqueued + byteTotalDequeues uint64 octet Total messages dequeued + byteTxnEnqueues uint64 octet Transactional messages enqueued + byteTxnDequeues uint64 octet Transactional messages dequeued + bytePersistEnqueues uint64 octet Persistent messages enqueued + bytePersistDequeues uint64 octet Persistent messages dequeued + byteDepth uint32 octet Current size of queue in bytes + byteDepthHigh uint32 octet Current size of queue in bytes (High) + byteDepthLow uint32 octet Current size of queue in bytes (Low) + enqueueTxnStarts uint64 transaction Total enqueue transactions started + enqueueTxnCommits uint64 transaction Total enqueue transactions committed + enqueueTxnRejects uint64 transaction Total enqueue transactions rejected + enqueueTxnCount uint32 transaction Current pending enqueue transactions + enqueueTxnCountHigh uint32 transaction Current pending enqueue transactions (High) + enqueueTxnCountLow uint32 transaction Current pending enqueue transactions (Low) + dequeueTxnStarts uint64 transaction Total dequeue transactions started + dequeueTxnCommits uint64 transaction Total dequeue transactions committed + dequeueTxnRejects uint64 transaction Total dequeue transactions rejected + dequeueTxnCount uint32 transaction Current pending dequeue transactions + dequeueTxnCountHigh uint32 transaction Current pending dequeue transactions (High) + dequeueTxnCountLow uint32 transaction Current pending dequeue transactions (Low) + consumers uint32 consumer Current consumers on queue + consumersHigh uint32 consumer Current consumers on queue (High) + consumersLow uint32 consumer Current consumers on queue (Low) + bindings uint32 binding Current bindings + bindingsHigh uint32 binding Current bindings (High) + bindingsLow uint32 binding Current bindings (Low) + unackedMessages uint32 message Messages consumed but not yet acked + unackedMessagesHigh uint32 message Messages consumed but not yet acked (High) + unackedMessagesLow uint32 message Messages consumed but not yet acked (Low) + messageLatencySamples delta-time nanosecond Broker latency through this queue (Samples) + messageLatencyMin delta-time nanosecond Broker latency through this queue (Min) + messageLatencyMax delta-time nanosecond Broker latency through this queue (Max) + messageLatencyAverage delta-time nanosecond Broker latency through this queue (Average) +Method 'purge' Discard all messages on queue +qpid: list queue +Objects of type qpid.queue + ID Created Destroyed Index + =========================================================================== + 1012 21:08:13 - 1002.pub_start + 1014 21:08:13 - 1002.pub_done + 1016 21:08:13 - 1002.sub_ready + 1018 21:08:13 - 1002.sub_done + 1020 21:08:13 - 1002.perftest0 + 1038 21:09:08 - 1002.mgmt-3206ff16-fb29-4a30-82ea-e76f50dd7d15 + 1040 21:09:08 - 1002.repl-3206ff16-fb29-4a30-82ea-e76f50dd7d15 + 1046 21:09:32 - 1002.mgmt-df06c7a6-4ce7-426a-9f66-da91a2a6a837 + 1048 21:09:32 - 1002.repl-df06c7a6-4ce7-426a-9f66-da91a2a6a837 + 1054 21:10:01 - 1002.mgmt-c55915c2-2fda-43ee-9410-b1c1cbb3e4ae + 1056 21:10:01 - 1002.repl-c55915c2-2fda-43ee-9410-b1c1cbb3e4ae + 1063 21:26:00 - 1002.mgmt-8d621997-6356-48c3-acab-76a37081d0f3 + 1065 21:26:00 - 1002.repl-8d621997-6356-48c3-acab-76a37081d0f3 +qpid: list 1020 +Object of type qpid.queue: (last sample time: 21:26:02) + Type Element 1020 + ========================================================================== + config vhostRef 1002 + config name perftest0 + config durable False + config autoDelete False + config exclusive False + config arguments {'qpid.max_size': 0, 'qpid.max_count': 0} + config storeRef NULL + inst msgTotalEnqueues 500000 messages + inst msgTotalDequeues 500000 + inst msgTxnEnqueues 0 + inst msgTxnDequeues 0 + inst msgPersistEnqueues 0 + inst msgPersistDequeues 0 + inst msgDepth 0 + inst msgDepthHigh 0 + inst msgDepthLow 0 + inst byteTotalEnqueues 512000000 octets + inst byteTotalDequeues 512000000 + inst byteTxnEnqueues 0 + inst byteTxnDequeues 0 + inst bytePersistEnqueues 0 + inst bytePersistDequeues 0 + inst byteDepth 0 + inst byteDepthHigh 0 + inst byteDepthLow 0 + inst enqueueTxnStarts 0 transactions + inst enqueueTxnCommits 0 + inst enqueueTxnRejects 0 + inst enqueueTxnCount 0 + inst enqueueTxnCountHigh 0 + inst enqueueTxnCountLow 0 + inst dequeueTxnStarts 0 + inst dequeueTxnCommits 0 + inst dequeueTxnRejects 0 + inst dequeueTxnCount 0 + inst dequeueTxnCountHigh 0 + inst dequeueTxnCountLow 0 + inst consumers 0 consumers + inst consumersHigh 0 + inst consumersLow 0 + inst bindings 1 binding + inst bindingsHigh 1 + inst bindingsLow 1 + inst unackedMessages 0 messages + inst unackedMessagesHigh 0 + inst unackedMessagesLow 0 + inst messageLatencySamples 0 + inst messageLatencyMin 0 + inst messageLatencyMax 0 + inst messageLatencyAverage 0 +qpid: +</programlisting> +<!--h3--></section> + + <section role="h3" id="MgmtC-2B-2B-Usingqpidprintevents"><title> + Using + qpid-printevents + </title> + <para> + This utility connects to one or more brokers and collects events, + printing out a line per event. + </para> + <programlisting> +$ qpid-printevents --help +Usage: qpid-printevents [options] [broker-addr]... + +Collect and print events from one or more Qpid message brokers. If no broker- +addr is supplied, qpid-printevents will connect to 'localhost:5672'. broker- +addr is of the form: [username/password@] hostname | ip-address [:<port>] ex: +localhost, 10.1.1.7:10000, broker-host:10000, guest/guest@localhost + +Options: + -h, --help show this help message and exit +</programlisting> + <para> + You get the idea... have fun! + </para> +<!--h3--></section> +<section> + <title>Using qpid-ha</title> + <para>This utility lets you monitor and control the activity of the clustering behavior provided by the HA module. + </para> + <programlisting> + <![CDATA[ +qpid-ha --help +usage: qpid-ha <command> [<arguments>] + +Commands are: + + ready Test if a backup broker is ready. + query Print HA configuration settings. + set Set HA configuration settings. + promote Promote broker from backup to primary. + replicate Set up replication from <queue> on <remote-broker> to <queue> on the current broker. + +For help with a command type: qpid-ha <command> --help +]]> + </programlisting> +</section> +</section> diff --git a/qpid/doc/book/src/cpp-broker/QMF-Python-Console-Tutorial.xml b/qpid/doc/book/src/cpp-broker/QMF-Python-Console-Tutorial.xml new file mode 100644 index 0000000000..2cb802671b --- /dev/null +++ b/qpid/doc/book/src/cpp-broker/QMF-Python-Console-Tutorial.xml @@ -0,0 +1,894 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section><title> + QMF Python Console Tutorial + </title> + <itemizedlist> + <listitem><para> + <xref linkend="QMFPythonConsoleTutorial-PrerequisiteInstallQpidMessaging"/> + </para></listitem> + <listitem><para> + <xref linkend="QMFPythonConsoleTutorial-SynchronousConsoleOperations"/> + </para></listitem> + <listitem><para> + <itemizedlist> + <listitem><para> + <xref linkend="QMFPythonConsoleTutorial-CreatingaQMFConsoleSessionandAttachingtoaBroker"/> + </para></listitem> + <listitem><para> + <xref linkend="QMFPythonConsoleTutorial-AccessingManagedObjects"/> + </para></listitem> + <listitem><para> + <itemizedlist> + <listitem><para> + <xref linkend="QMFPythonConsoleTutorial-ViewingPropertiesandStatisticsofanObject"/> + </para></listitem> + <listitem><para> + <xref linkend="QMFPythonConsoleTutorial-InvokingMethodsonanObject"/> + </para></listitem> + </itemizedlist> + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <xref linkend="QMFPythonConsoleTutorial-AsynchronousConsoleOperations"/> + </para></listitem> + <listitem><para> + <itemizedlist> + <listitem><para> + <xref linkend="QMFPythonConsoleTutorial-CreatingaConsoleClasstoReceiveAsynchronousData"/> + </para></listitem> + <listitem><para> + <xref linkend="QMFPythonConsoleTutorial-ReceivingEvents"/> + </para></listitem> + <listitem><para> + <xref linkend="QMFPythonConsoleTutorial-ReceivingObjects"/> + </para></listitem> + <listitem><para> + <xref linkend="QMFPythonConsoleTutorial-AsynchronousMethodCallsandMethodTimeouts"/> + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <xref linkend="QMFPythonConsoleTutorial-DiscoveringwhatKindsofObjectsareAvailable"/> + </para></listitem> + </itemizedlist> + <section role="h1" id="QMFPythonConsoleTutorial-PrerequisiteInstallQpidMessaging"><title> + Prerequisite + - Install Qpid Messaging + </title> + + <para> + QMF uses AMQP Messaging (QPid) as its means of communication. To + use QMF, Qpid messaging must be installed somewhere in the + network. Qpid can be downloaded as source from Apache, is + packaged with a number of Linux distributions, and can be + purchased from commercial vendors that use Qpid. Please see + <ulink url="http://qpid.apache.org">http://qpid.apache.org</ulink>for + information as to where to get Qpid Messaging. + </para><para> + Qpid Messaging includes a message broker (qpidd) which typically + runs as a daemon on a system. It also includes client bindings in + various programming languages. The Python-language client library + includes the QMF console libraries needed for this tutorial. + </para><para> + Please note that Qpid Messaging has two broker implementations. + One is implemented in C++ and the other in Java. At press time, + QMF is supported only by the C++ broker. + </para><para> + If the goal is to get the tutorial examples up and running as + quickly as possible, all of the Qpid components can be installed + on a single system (even a laptop). For more realistic + deployments, the broker can be deployed on a server and the + client/QMF libraries installed on other systems. + </para> +<!--h1--></section> + + <section role="h1" id="QMFPythonConsoleTutorial-SynchronousConsoleOperations"><title> + Synchronous + Console Operations + </title> + + <para> + The Python console API for QMF can be used in a synchronous + style, an asynchronous style, or a combination of both. + Synchronous operations are conceptually simple and are well + suited for user-interactive tasks. All operations are performed + in the context of a Python function call. If communication over + the message bus is required to complete an operation, the + function call blocks and waits for the expected result (or + timeout failure) before returning control to the caller. + </para><section role="h2" id="QMFPythonConsoleTutorial-CreatingaQMFConsoleSessionandAttachingtoaBroker"><title> + Creating a QMF Console Session and Attaching to a Broker + </title> + + <para> + For the purposes of this tutorial, code examples will be shown as + they are entered in an interactive python session. + </para> + <programlisting> +$ python +Python 2.5.2 (r252:60911, Sep 30 2008, 15:41:38) +[GCC 4.3.2 20080917 (Red Hat 4.3.2-4)] on linux2 +Type "help", "copyright", "credits" or "license" for more information. +>>> +</programlisting> + <para> + We will begin by importing the required libraries. If the Python + client is properly installed, these libraries will be found + normally by the Python interpreter. + </para> + <programlisting> +>>> from qmf.console import Session +</programlisting> + <para> + We must now create a <emphasis>Session</emphasis> object to manage this QMF + console session. + </para> + <programlisting> +>>> sess = Session() +</programlisting> + <para> + If no arguments are supplied to the creation of <emphasis>Session</emphasis>, + it defaults to synchronous-only operation. It also defaults to + user-management of connections. More on this in a moment. + </para><para> + We will now establish a connection to the messaging broker. If + the broker daemon is running on the local host, simply use the + following: + </para> + <programlisting> +>>> broker = sess.addBroker() +</programlisting> + <para> + If the messaging broker is on a remote host, supply the URL to + the broker in the <emphasis>addBroker</emphasis> function call. Here's how to + connect to a local broker using the URL. + </para> + <programlisting> +>>> broker = sess.addBroker("amqp://localhost") +</programlisting> + <para> + The call to <emphasis>addBroker</emphasis> is synchronous and will return + only after the connection has been successfully established or + has failed. If a failure occurs, <emphasis>addBroker</emphasis> will raise an + exception that can be handled by the console script. + </para> + <programlisting> +>>> try: +... broker = sess.addBroker("amqp://localhost:1000") +... except: +... print "Connection Failed" +... +Connection Failed +>>> +</programlisting> + <para> + This operation fails because there is no Qpid Messaging broker + listening on port 1000 (the default port for qpidd is 5672). + </para><para> + If preferred, the QMF session can manage the connection for you. + In this case, <emphasis>addBroker</emphasis> returns immediately and the + session attempts to establish the connection in the background. + This will be covered in detail in the section on asynchronous + operations. + </para> +<!--h2--></section> + + <section role="h2" id="QMFPythonConsoleTutorial-AccessingManagedObjects"><title> + Accessing + Managed Objects + </title> + + <para> + The Python console API provides access to remotely managed + objects via a <emphasis>proxy</emphasis> model. The API gives the client an + object that serves as a proxy representing the "real" object + being managed on the agent application. Operations performed on + the proxy result in the same operations on the real object. + </para><para> + The following examples assume prior knowledge of the kinds of + objects that are actually available to be managed. There is a + section later in this tutorial that describes how to discover + what is manageable on the QMF bus. + </para><para> + Proxy objects are obtained by calling the + <emphasis>Session.getObjects</emphasis> function. + </para><para> + To illustrate, we'll get a list of objects representing queues in + the message broker itself. + </para> + <programlisting> +>>> queues = sess.getObjects(_class="queue", _package="org.apache.qpid.broker") +</programlisting> + <para> + <emphasis>queues</emphasis> is an array of proxy objects representing real + queues on the message broker. A proxy object can be printed to + display a description of the object. + </para> + <programlisting> +>>> for q in queues: +... print q +... +org.apache.qpid.broker:queue[0-1537-1-0-58] 0-0-1-0-1152921504606846979:reply-localhost.localdomain.32004 +org.apache.qpid.broker:queue[0-1537-1-0-61] 0-0-1-0-1152921504606846979:topic-localhost.localdomain.32004 +>>> +</programlisting> + <section role="h3" id="QMFPythonConsoleTutorial-ViewingPropertiesandStatisticsofanObject"><title> + Viewing Properties and Statistics of an Object + </title> + + <para> + Let us now focus our attention on one of the queue objects. + </para> + <programlisting> +>>> queue = queues[0] +</programlisting> + <para> + The attributes of an object are partitioned into + <emphasis>properties</emphasis> and <emphasis>statistics</emphasis>. Though the + distinction is somewhat arbitrary, <emphasis>properties</emphasis> tend to + be fairly static and may also be large and <emphasis>statistics</emphasis> + tend to change rapidly and are relatively small (counters, etc.). + </para><para> + There are two ways to view the properties of an object. An array + of properties can be obtained using the <emphasis>getProperties</emphasis> + function: + </para> + <programlisting> +>>> props = queue.getProperties() +>>> for prop in props: +... print prop +... +(vhostRef, 0-0-1-0-1152921504606846979) +(name, u'reply-localhost.localdomain.32004') +(durable, False) +(autoDelete, True) +(exclusive, True) +(arguments, {}) +>>> +</programlisting> + <para> + The <emphasis>getProperties</emphasis> function returns an array of tuples. + Each tuple consists of the property descriptor and the property + value. + </para><para> + A more convenient way to access properties is by using the + attribute of the proxy object directly: + </para> + <programlisting> +>>> queue.autoDelete +True +>>> queue.name +u'reply-localhost.localdomain.32004' +>>> +</programlisting> + <para> + Statistics are accessed in the same way: + </para> + <programlisting> +>>> stats = queue.getStatistics() +>>> for stat in stats: +... print stat +... +(msgTotalEnqueues, 53) +(msgTotalDequeues, 53) +(msgTxnEnqueues, 0) +(msgTxnDequeues, 0) +(msgPersistEnqueues, 0) +(msgPersistDequeues, 0) +(msgDepth, 0) +(byteDepth, 0) +(byteTotalEnqueues, 19116) +(byteTotalDequeues, 19116) +(byteTxnEnqueues, 0) +(byteTxnDequeues, 0) +(bytePersistEnqueues, 0) +(bytePersistDequeues, 0) +(consumerCount, 1) +(consumerCountHigh, 1) +(consumerCountLow, 1) +(bindingCount, 2) +(bindingCountHigh, 2) +(bindingCountLow, 2) +(unackedMessages, 0) +(unackedMessagesHigh, 0) +(unackedMessagesLow, 0) +(messageLatencySamples, 0) +(messageLatencyMin, 0) +(messageLatencyMax, 0) +(messageLatencyAverage, 0) +>>> +</programlisting> + <para> + or alternatively: + </para> + <programlisting> +>>> queue.byteTotalEnqueues +19116 +>>> +</programlisting> + <para> + The proxy objects do not automatically track changes that occur + on the real objects. For example, if the real queue enqueues more + bytes, viewing the <emphasis>byteTotalEnqueues</emphasis> statistic will show + the same number as it did the first time. To get updated data on + a proxy object, use the <emphasis>update</emphasis> function call: + </para> + <programlisting> +>>> queue.update() +>>> queue.byteTotalEnqueues +19783 +>>> +</programlisting> + + <note><title>Be Advised</title> + <para> + The <emphasis>update</emphasis> method was added after the M4 release + of Qpid/Qmf. It may not be available in your + distribution. + </para> + </note> +<!--h3--></section> + + <section role="h3" id="QMFPythonConsoleTutorial-InvokingMethodsonanObject"><title> + Invoking + Methods on an Object + </title> + + <para> + Up to this point, we have used the QMF Console API to find + managed objects and view their attributes, a read-only activity. + The next topic to illustrate is how to invoke a method on a + managed object. Methods allow consoles to control the managed + agents by either triggering a one-time action or by changing the + values of attributes in an object. + </para><para> + First, we'll cover some background information about methods. A + <emphasis>QMF object class</emphasis> (of which a <emphasis>QMF object</emphasis> is an + instance), may have zero or more methods. To obtain a list of + methods available for an object, use the <emphasis>getMethods</emphasis> + function. + </para> + <programlisting> +>>> methodList = queue.getMethods() +</programlisting> + <para> + <emphasis>getMethods</emphasis> returns an array of method descriptors (of + type qmf.console.SchemaMethod). To get a summary of a method, you + can simply print it. The _<emphasis>repr</emphasis>_ function returns a + string that looks like a function prototype. + </para> + <programlisting> +>>> print methodList +[purge(request)] +>>> +</programlisting> + <para> + For the purposes of illustration, we'll use a more interesting + method available on the <emphasis>broker</emphasis> object which represents + the connected Qpid message broker. + </para> + <programlisting> +>>> br = sess.getObjects(_class="broker", _package="org.apache.qpid.broker")[0] +>>> mlist = br.getMethods() +>>> for m in mlist: +... print m +... +echo(sequence, body) +connect(host, port, durable, authMechanism, username, password, transport) +queueMoveMessages(srcQueue, destQueue, qty) +>>> +</programlisting> + <para> + We have just learned that the <emphasis>broker</emphasis> object has three + methods: <emphasis>echo</emphasis>, <emphasis>connect</emphasis>, and + <emphasis>queueMoveMessages</emphasis>. We'll use the <emphasis>echo</emphasis> method to + "ping" the broker. + </para> + <programlisting> +>>> result = br.echo(1, "Message Body") +>>> print result +OK (0) - {'body': u'Message Body', 'sequence': 1} +>>> print result.status +0 +>>> print result.text +OK +>>> print result.outArgs +{'body': u'Message Body', 'sequence': 1} +>>> +</programlisting> + <para> + In the above example, we have invoked the <emphasis>echo</emphasis> method on + the instance of the broker designated by the proxy "br" with a + sequence argument of 1 and a body argument of "Message Body". The + result indicates success and contains the output arguments (in + this case copies of the input arguments). + </para><para> + To be more precise... Calling <emphasis>echo</emphasis> on the proxy causes + the input arguments to be marshalled and sent to the remote agent + where the method is executed. Once the method execution + completes, the output arguments are marshalled and sent back to + the console to be stored in the method result. + </para><para> + You are probably wondering how you are supposed to know what + types the arguments are and which arguments are input, which are + output, or which are both. This will be addressed later in the + "Discovering what Kinds of Objects are Available" section. + </para> +<!--h3--></section> +<!--h2--></section> +<!--h1--></section> + + <section role="h1" id="QMFPythonConsoleTutorial-AsynchronousConsoleOperations"><title> + Asynchronous + Console Operations + </title> + + <para> + QMF is built on top of a middleware messaging layer (Qpid + Messaging). Because of this, QMF can use some communication + patterns that are difficult to implement using network transports + like UDP, TCP, or SSL. One of these patterns is called the + <emphasis>Publication and Subscription</emphasis> pattern (pub-sub for + short). In the pub-sub pattern, data sources <emphasis>publish</emphasis> + information without a particular destination in mind. Data sinks + (destinations) <emphasis>subscribe</emphasis> using a set of criteria that + describes what kind of data they are interested in receiving. + Data published by a source may be received by zero, one, or many + subscribers. + </para><para> + QMF uses the pub-sub pattern to distribute events, object + creation and deletion, and changes to properties and statistics. + A console application using the QMF Console API can receive these + asynchronous and unsolicited events and updates. This is useful + for applications that store and analyze events and/or statistics. + It is also useful for applications that react to certain events + or conditions. + </para><para> + Note that console applications may always use the synchronous + mechanisms. + </para> + + <section role="h2" id="QMFPythonConsoleTutorial-CreatingaConsoleClasstoReceiveAsynchronousData"><title> + Creating a Console Class to Receive Asynchronous Data + </title> + + <para> + Asynchronous API operation occurs when the console application + supplies a <emphasis>Console</emphasis> object to the session manager. The + <emphasis>Console</emphasis> object (which overrides the + <emphasis>qmf.console.Console</emphasis> class) handles all asynchronously + arriving data. The <emphasis>Console</emphasis> class has the following + methods. Any number of these methods may be overridden by the + console application. Any method that is not overridden defaults + to a null handler which takes no action when invoked. + </para><table><title>QMF Python Console Class Methods</title><tgroup cols="3"> + <tbody> + <row> + <entry> + Method + </entry> + <entry> + Arguments + </entry> + <entry> + Invoked when... + </entry> + </row> + <row> + <entry> + brokerConnected + </entry> + <entry> + broker + </entry> + <entry> + a connection to a broker is established + </entry> + </row> + <row> + <entry> + brokerDisconnected + </entry> + <entry> + broker + </entry> + <entry> + a connection to a broker is lost + </entry> + </row> + <row> + <entry> + newPackage + </entry> + <entry> + name + </entry> + <entry> + a new package is seen on the QMF bus + </entry> + </row> + <row> + <entry> + newClass + </entry> + <entry> + kind, classKey + </entry> + <entry> + a new class (event or object) is seen on the QMF bus + </entry> + </row> + <row> + <entry> + newAgent + </entry> + <entry> + agent + </entry> + <entry> + a new agent appears on the QMF bus + </entry> + </row> + <row> + <entry> + delAgent + </entry> + <entry> + agent + </entry> + <entry> + an agent disconnects from the QMF bus + </entry> + </row> + <row> + <entry> + objectProps + </entry> + <entry> + broker, object + </entry> + <entry> + the properties of an object are published + </entry> + </row> + <row> + <entry> + objectStats + </entry> + <entry> + broker, object + </entry> + <entry> + the statistics of an object are published + </entry> + </row> + <row> + <entry> + event + </entry> + <entry> + broker, event + </entry> + <entry> + an event is published + </entry> + </row> + <row> + <entry> + heartbeat + </entry> + <entry> + agent, timestamp + </entry> + <entry> + a heartbeat is published by an agent + </entry> + </row> + <row> + <entry> + brokerInfo + </entry> + <entry> + broker + </entry> + <entry> + information about a connected broker is available to be + queried + </entry> + </row> + <row> + <entry> + methodResponse + </entry> + <entry> + broker, seq, response + </entry> + <entry> + the result of an asynchronous method call is received + </entry> + </row> + </tbody> + </tgroup></table><para> + Supplied with the API is a class called <emphasis>DebugConsole</emphasis>. + This is a test <emphasis>Console</emphasis> instance that overrides all of + the methods such that arriving asynchronous data is printed to + the screen. This can be used to see all of the arriving + asynchronous data. + </para> + <!--h2--></section> + + <section role="h2" id="QMFPythonConsoleTutorial-ReceivingEvents"><title> + Receiving + Events + </title> + + <para> + We'll start the example from the beginning to illustrate the + reception and handling of events. In this example, we will create + a <emphasis>Console</emphasis> class that handles broker-connect, + broker-disconnect, and event messages. We will also allow the + session manager to manage the broker connection for us. + </para><para> + Begin by importing the necessary classes: + </para> + <programlisting> +>>> from qmf.console import Session, Console +</programlisting> + <para> + Now, create a subclass of <emphasis>Console</emphasis> that handles the three + message types: + </para> + <programlisting> +>>> class EventConsole(Console): +... def brokerConnected(self, broker): +... print "brokerConnected:", broker +... def brokerDisconnected(self, broker): +... print "brokerDisconnected:", broker +... def event(self, broker, event): +... print "event:", event +... +>>> +</programlisting> + <para> + Make an instance of the new class: + </para> + <programlisting> +>>> myConsole = EventConsole() +</programlisting> + <para> + Create a <emphasis>Session</emphasis> class using the console instance. In + addition, we shall request that the session manager do the + connection management for us. Notice also that we are requesting + that the session manager not receive objects or heartbeats. Since + this example is concerned only with events, we can optimize the + use of the messaging bus by telling the session manager not to + subscribe for object updates or heartbeats. + </para> + <programlisting> +>>> sess = Session(myConsole, manageConnections=True, rcvObjects=False, rcvHeartbeats=False) +>>> broker = sess.addBroker() +>>> +</programlisting> + <para> + Once the broker is added, we will begin to receive asynchronous + events (assuming there is a functioning broker available to + connect to). + </para> + <programlisting> +brokerConnected: Broker connected at: localhost:5672 +event: Thu Jan 29 19:53:19 2009 INFO org.apache.qpid.broker:bind broker=localhost:5672 ... +</programlisting> +<!--h2--></section> + + <section role="h2" id="QMFPythonConsoleTutorial-ReceivingObjects"><title> + Receiving + Objects + </title> + + <para> + To illustrate asynchronous handling of objects, a small console + program is supplied. The entire program is shown below for + convenience. We will then go through it part-by-part to explain + its design. + </para><para> + This console program receives object updates and displays a set + of statistics as they change. It focuses on broker queue objects. + </para> + <programlisting> +# Import needed classes +from qmf.console import Session, Console +from time import sleep + +# Declare a dictionary to map object-ids to queue names +queueMap = {} + +# Customize the Console class to receive object updates. +class MyConsole(Console): + + # Handle property updates + def objectProps(self, broker, record): + + # Verify that we have received a queue object. Exit otherwise. + classKey = record.getClassKey() + if classKey.getClassName() != "queue": + return + + # If this object has not been seen before, create a new mapping from objectID to name + oid = record.getObjectId() + if oid not in queueMap: + queueMap[oid] = record.name + + # Handle statistic updates + def objectStats(self, broker, record): + + # Ignore updates for objects that are not in the map + oid = record.getObjectId() + if oid not in queueMap: + return + + # Print the queue name and some statistics + print "%s: enqueues=%d dequeues=%d" % (queueMap[oid], record.msgTotalEnqueues, record.msgTotalDequeues) + + # if the delete-time is non-zero, this object has been deleted. Remove it from the map. + if record.getTimestamps()[2] > 0: + queueMap.pop(oid) + +# Create an instance of the QMF session manager. Set userBindings to True to allow +# this program to choose which objects classes it is interested in. +sess = Session(MyConsole(), manageConnections=True, rcvEvents=False, userBindings=True) + +# Register to receive updates for broker:queue objects. +sess.bindClass("org.apache.qpid.broker", "queue") +broker = sess.addBroker() + +# Suspend processing while the asynchronous operations proceed. +try: + while True: + sleep(1) +except: + pass + +# Disconnect the broker before exiting. +sess.delBroker(broker) +</programlisting> + <para> + Before going through the code in detail, it is important to + understand the differences between synchronous object access and + asynchronous object access. When objects are obtained + synchronously (using the <emphasis>getObjects</emphasis> function), the + resulting proxy contains all of the object's attributes, both + properties and statistics. When object data is published + asynchronously, the properties and statistics are sent separately + and only when the session first connects or when the content + changes. + </para><para> + The script wishes to print the queue name with the updated + statistics, but the queue name is only present with the + properties. For this reason, the program needs to keep some state + to correlate property updates with their corresponding statistic + updates. This can be done using the <emphasis>ObjectId</emphasis> that + uniquely identifies the object. + </para> + <programlisting> + # If this object has not been seen before, create a new mapping from objectID to name + oid = record.getObjectId() + if oid not in queueMap: + queueMap[oid] = record.name +</programlisting> + <para> + The above code fragment gets the object ID from the proxy and + checks to see if it is in the map (i.e. has been seen before). If + it is not in the map, a new map entry is inserted mapping the + object ID to the queue's name. + </para> + <programlisting> + # if the delete-time is non-zero, this object has been deleted. Remove it from the map. + if record.getTimestamps()[2] > 0: + queueMap.pop(oid) +</programlisting> + <para> + This code fragment detects the deletion of a managed object. + After reporting the statistics, it checks the timestamps of the + proxy. <emphasis>getTimestamps</emphasis> returns a list of timestamps in the + order: + </para><itemizedlist> + <listitem><para> + <emphasis>Current</emphasis> - The timestamp of the sending of this update. + </para></listitem> + <listitem><para> + <emphasis>Create</emphasis> - The time of the object's creation + </para></listitem> + <listitem><para> + <emphasis>Delete</emphasis> - The time of the object's deletion (or zero if + not deleted) + </para></listitem> + </itemizedlist><para> + This code structure is useful for getting information about + very-short-lived objects. It is possible that an object will be + created, used, and deleted within an update interval. In this + case, the property update will arrive first, followed by the + statistic update. Both will indicate that the object has been + deleted but a full accounting of the object's existence and final + state is reported. + </para> + <programlisting> +# Create an instance of the QMF session manager. Set userBindings to True to allow +# this program to choose which objects classes it is interested in. +sess = Session(MyConsole(), manageConnections=True, rcvEvents=False, userBindings=True) + +# Register to receive updates for broker:queue objects. +sess.bindClass("org.apache.qpid.broker", "queue") +</programlisting> + <para> + The above code is illustrative of the way a console application + can tune its use of the QMF bus. Note that <emphasis>rcvEvents</emphasis> is + set to False. This prevents the reception of events. Note also + the use of <emphasis>userBindings=True</emphasis> and the call to + <emphasis>sess.bindClass</emphasis>. If <emphasis>userBindings</emphasis> is set to False + (its default), the session will receive object updates for all + classes of object. In the case above, the application is only + interested in broker:queue objects and reduces its bus bandwidth + usage by requesting updates to only that class. + <emphasis>bindClass</emphasis> may be called as many times as desired to add + classes to the list of subscribed classes. + </para> +<!--h2--></section> + + <section role="h2" id="QMFPythonConsoleTutorial-AsynchronousMethodCallsandMethodTimeouts"><title> + Asynchronous Method Calls and Method Timeouts + </title> + + <para> + Method calls can also be invoked asynchronously. This is useful + if a large number of calls needs to be made in a short time + because the console application will not need to wait for the + complete round-trip delay for each call. + </para><para> + Method calls are synchronous by default. They can be made + asynchronous by adding the keyword-argument _<emphasis>async=True</emphasis> + to the method call. + </para><para> + In a synchronous method call, the return value is the method + result. When a method is called asynchronously, the return value + is a sequence number that can be used to correlate the eventual + result to the request. This sequence number is passed as an + argument to the <emphasis>methodResponse</emphasis> function in the + <emphasis>Console</emphasis> interface. + </para><para> + It is important to realize that the <emphasis>methodResponse</emphasis> + function may be invoked before the asynchronous call returns. + Make sure your code is written to handle this possibility. + </para> + <!--h2--></section> + <!--h1--></section> + + <section role="h1" id="QMFPythonConsoleTutorial-DiscoveringwhatKindsofObjectsareAvailable"><title> + Discovering what Kinds of Objects are Available + </title> + <para/> + <!--h1--></section> + + +</section> diff --git a/qpid/doc/book/src/cpp-broker/Qpid-Interoperability-Documentation.xml b/qpid/doc/book/src/cpp-broker/Qpid-Interoperability-Documentation.xml new file mode 100644 index 0000000000..74546693df --- /dev/null +++ b/qpid/doc/book/src/cpp-broker/Qpid-Interoperability-Documentation.xml @@ -0,0 +1,377 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section role="h2" id="QpidInteroperabilityDocumentation-QpidInteroperabilityDocumentation"> + <title>Qpid Interoperability Documentation</title> + + <para> + This page documents the various interoperable features of the + Qpid clients. + </para> + <section role="h3" id="QpidInteroperabilityDocumentation-SASL"><title> + SASL + </title> + + <para> + + </para> + <section role="h4" id="QpidInteroperabilityDocumentation-StandardMechanisms"><title> + Standard + Mechanisms + </title> + + <para> + <ulink url="http://en.wikipedia.org/wiki/Simple_Authentication_and_Security_Layer#SASL_mechanisms"/> + </para><para> + This table list the various SASL mechanisms that each component + supports. The version listed shows when this + functionality was added to the product. + </para><table><title>SASL Mechanism Support</title><tgroup cols="7"> + <tbody> + <row> + <entry> + Component + </entry> + <entry> + ANONYMOUS + </entry> + <entry> + CRAM-MD5 + </entry> + <entry> + DIGEST-MD5 + </entry> + <entry> + EXTERNAL + </entry> + <entry> + GSSAPI/Kerberos + </entry> + <entry> + PLAIN + </entry> + </row> + <row> + <entry> + C++ Broker + </entry> + <entry> + M3[<xref linkend="QpidInteroperabilityDocumentation-1"/>] + </entry> + <entry> + M3[<xref linkend="QpidInteroperabilityDocumentation-1"/>,<xref linkend="QpidInteroperabilityDocumentation-2"/>] + </entry> + <entry> + + </entry> + <entry> + + </entry> + <entry> + M3[<xref linkend="QpidInteroperabilityDocumentation-1"/>,<xref linkend="QpidInteroperabilityDocumentation-2"/>] + </entry> + <entry> + M1 + </entry> + </row> + <row> + <entry> + C++ Client + </entry> + <entry> + M3[<xref linkend="QpidInteroperabilityDocumentation-1"/>] + </entry> + <entry> + + </entry> + <entry> + + </entry> + <entry> + + </entry> + <entry> + + </entry> + <entry> + M1 + </entry> + </row> + <row> + <entry> + Java Broker + </entry> + <entry> + + </entry> + <entry> + M1 + </entry> + <entry> + + </entry> + <entry> + + </entry> + <entry> + + </entry> + <entry> + M1 + </entry> + </row> + <row> + <entry> + Java Client + </entry> + <entry> + + </entry> + <entry> + M1 + </entry> + <entry> + + </entry> + <entry> + + </entry> + <entry> + + </entry> + <entry> + M1 + </entry> + </row> + <row> + <entry> + .Net Client + </entry> + <entry> + M2 + </entry> + <entry> + M2 + </entry> + <entry> + M2 + </entry> + <entry> + M2 + </entry> + <entry> + + </entry> + <entry> + M2 + </entry> + </row> + <row> + <entry> + Python Client + </entry> + <entry> + + </entry> + <entry> + + </entry> + <entry> + + </entry> + <entry> + + </entry> + <entry> + + </entry> + <entry> + ? + </entry> + </row> + <row> + <entry> + Ruby Client + </entry> + <entry> + + </entry> + <entry> + + </entry> + <entry> + + </entry> + <entry> + + </entry> + <entry> + + </entry> + <entry> + ? + </entry> + </row> + </tbody> + </tgroup></table> + + <para id="QpidInteroperabilityDocumentation-1"> + 1: Support for these will be in M3 (currently available on + trunk). + </para> + + <para id="QpidInteroperabilityDocumentation-2">2: C++ Broker uses <ulink url="http://freshmeat.net/projects/cyrussasl/">Cyrus SASL</ulink> which + supports CRAM-MD5 and GSSAPI but these have not been tested yet + </para> +<!--h4--></section> + + <section role="h4" id="QpidInteroperabilityDocumentation-CustomMechanisms"><title> + Custom + Mechanisms + </title> + + <para> + There have been some custom mechanisms added to our + implementations. + </para><table><title>SASL Custom Mechanisms</title><tgroup cols="3"> + <tbody> + <row> + <entry> + Component + </entry> + <entry> + AMQPLAIN + </entry> + <entry> + CRAM-MD5-HASHED + </entry> + </row> + <row> + <entry> + C++ Broker + </entry> + <entry> + + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + C++ Client + </entry> + <entry> + + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + Java Broker + </entry> + <entry> + M1 + </entry> + <entry> + M2 + </entry> + </row> + <row> + <entry> + Java Client + </entry> + <entry> + M1 + </entry> + <entry> + M2 + </entry> + </row> + <row> + <entry> + .Net Client + </entry> + <entry> + + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + Python Client + </entry> + <entry> + M2 + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + Ruby Client + </entry> + <entry> + M2 + </entry> + <entry> + + </entry> + </row> + </tbody> + </tgroup></table> + + <section><title>AMQPLAIN</title> + <para/> + </section> + + <section><title>CRAM-MD5-HASHED</title> + <para> + The Java SASL implementations require that you have the password + of the user to validate the incoming request. This then means + that the user's password must be stored on disk. For this to be + secure either the broker must encrypt the password file or the + need for the password being stored must be removed. + </para><para> + The CRAM-MD5-HASHED SASL plugin removes the need for the plain + text password to be stored on disk. The mechanism defers all + functionality to the build in CRAM-MD5 module the only change is + on the client side where it generates the hash of the password + and uses that value as the password. This means that the Java + Broker only need store the password hash on the file system. + While a one way hash is not very secure compared to other forms + of encryption in environments where the having the password in + plain text is unacceptable this will provide and additional layer + to protect the password. In particular this offers some + protection where the same password may be shared amongst many + systems. It offers no real extra protection against attacks on + the broker (the secret is now the hash rather than the password). + </para> + </section> +<!--h4--></section> +<!--h3--></section> +<!--h2--></section> diff --git a/qpid/doc/book/src/cpp-broker/Qpid-Management-Framework.xml b/qpid/doc/book/src/cpp-broker/Qpid-Management-Framework.xml new file mode 100644 index 0000000000..89bfe9d95e --- /dev/null +++ b/qpid/doc/book/src/cpp-broker/Qpid-Management-Framework.xml @@ -0,0 +1,944 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section><title> + Qpid Management Framework + </title> + <itemizedlist> + <listitem><para> + <xref linkend="QpidManagementFramework-WhatIsQMF"/> + </para></listitem> + <listitem><para> + <xref linkend="QpidManagementFramework-GettingStartedwithQMF"/> + </para></listitem> + <listitem><para> + <xref linkend="QpidManagementFramework-QMFConcepts"/> + </para></listitem> + <listitem><para> + <itemizedlist> + <listitem><para> + <xref linkend="QpidManagementFramework-Console-2CAgent-2CandBroker"/> + </para></listitem> + <listitem><para> + <xref linkend="QpidManagementFramework-Schema"/> + </para></listitem> + <listitem><para> + <xref linkend="QpidManagementFramework-ClassKeysandClassVersioning"/> + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <xref linkend="QpidManagementFramework-TheQMFProtocol"/> + </para></listitem> + <listitem><para> + <xref linkend="QpidManagementFramework-HowtoWriteaQMFConsole"/> + </para></listitem> + <listitem><para> + <xref linkend="QpidManagementFramework-HowtoWriteaQMFAgent"/> + </para></listitem> + </itemizedlist> + + <para> + Please visit the <xref linkend="qpid_QMFv2-Project-Page"/> for information + about the future of QMF. + </para> + <section role="h1" id="QpidManagementFramework-WhatIsQMF"><title> + What Is QMF + </title> + + <para> + QMF (Qpid Management Framework) is a general-purpose management + bus built on Qpid Messaging. It takes advantage of the + scalability, security, and rich capabilities of Qpid to provide + flexible and easy-to-use manageability to a large set of + applications. + </para> + <!--h1--></section> + + <section role="h1" id="QpidManagementFramework-GettingStartedwithQMF"><title> + Getting + Started with QMF + </title> + + <para> + QMF is used through two primary APIs. The <emphasis>console</emphasis> API is + used for console applications that wish to access and manipulate + manageable components through QMF. The <emphasis>agent</emphasis> API is used + for application that wish to be managed through QMF. + </para><para> + The fastest way to get started with QMF is to work through the + "How To" tutorials for consoles and agents. For a deeper + understanding of what is happening in the tutorials, it is + recommended that you look at the <emphasis>Qmf Concepts</emphasis> section. + </para> + <!--h1--></section> + + <section role="h1" id="QpidManagementFramework-QMFConcepts"><title> + QMF Concepts + </title> + + <para> + This section introduces important concepts underlying QMF. + </para> + + + <section role="h2" id="QpidManagementFramework-Console-2CAgent-2CandBroker"><title> + Console, + Agent, and Broker + </title> + + <para> + The major architectural components of QMF are the Console, the + Agent, and the Broker. Console components are the "managing" + components of QMF and agent components are the "managed" parts. + The broker is a central (possibly distributed, clustered and + fault-tolerant) component that manages name spaces and caches + schema information. + </para><para> + A console application may be a command-line utility, a + three-tiered web-based GUI, a collection and storage device, a + specialized application that monitors and reacts to events and + conditions, or anything else somebody wishes to develop that uses + QMF management data. + </para><para> + An agent application is any application that has been enhanced to + allow itself to be managed via QMF. + </para> + <programlisting> + +-------------+ +---------+ +---------------+ +-------------------+ + | CLI utility | | Web app | | Audit storage | | Event correlation | + +-------------+ +---------+ +---------------+ +-------------------+ + ^ ^ ^ ^ | + | | | | | + v v v v v + +---------------------------------------------------------------------------------+ + | Qpid Messaging Bus (with QMF Broker capability) | + +---------------------------------------------------------------------------------+ + ^ ^ ^ + | | | + v v v + +----------------+ +----------------+ +----------------+ + | Manageable app | | Manageable app | | Manageable app | + +----------------+ +----------------+ +----------------+ +</programlisting> + <para> + In the above diagram, the <emphasis>Manageable apps</emphasis> are agents, + the <emphasis>CLI utility</emphasis>, <emphasis>Web app</emphasis>, and <emphasis>Audit + storage</emphasis> are consoles, and <emphasis>Event correlation</emphasis> is both + a console and an agent because it can create events based on the + aggregation of what it sees. + </para> +<!--h2--></section> + + <section role="h2" id="QpidManagementFramework-Schema"><title> + Schema + </title> + + <para> + A <emphasis>schema</emphasis> describes the structure of management data. + Each <emphasis>agent</emphasis> provides a schema that describes its + management model including the object classes, methods, events, + etc. that it provides. In the current QMF distribution, the + agent's schema is codified in an XML document. In the near + future, there will also be ways to programatically create QMF + schemata. + </para><section role="h3" id="QpidManagementFramework-Package"><title> + Package + </title> + + <para> + Each agent that exports a schema identifies itself using a + <emphasis>package</emphasis> name. The package provides a unique namespace + for the classes in the agent's schema that prevent collisions + with identically named classes in other agents' schemata. + </para><para> + Package names are in "reverse domain name" form with levels of + hierarchy separated by periods. For example, the Qpid messaging + broker uses package "org.apache.qpid.broker" and the Access + Control List plugin for the broker uses package + "org.apache.qpid.acl". In general, the package name should be the + reverse of the internet domain name assigned to the organization + that owns the agent software followed by identifiers to uniquely + identify the agent. + </para><para> + The XML document for a package's schema uses an enclosing + <schema> tag. For example: + </para> + <programlisting> +<schema package="org.apache.qpid.broker"> + +</schema> +</programlisting> +<!--h3--></section> + + <section role="h3" id="QpidManagementFramework-ObjectClasses"><title> + Object + Classes + </title> + + <para> + <emphasis>Object classes</emphasis> define types for manageable objects. The + agent may create and destroy objects which are instances of + object classes in the schema. An object class is defined in the + XML document using the <class> tag. An object class is + composed of properties, statistics, and methods. + </para> + <programlisting> + <class name="Exchange"> + <property name="vhostRef" type="objId" references="Vhost" access="RC" index="y" parentRef="y"/> + <property name="name" type="sstr" access="RC" index="y"/> + <property name="type" type="sstr" access="RO"/> + <property name="durable" type="bool" access="RC"/> + <property name="arguments" type="map" access="RO" desc="Arguments supplied in exchange.declare"/> + + <statistic name="producerCount" type="hilo32" desc="Current producers on exchange"/> + <statistic name="bindingCount" type="hilo32" desc="Current bindings"/> + <statistic name="msgReceives" type="count64" desc="Total messages received"/> + <statistic name="msgDrops" type="count64" desc="Total messages dropped (no matching key)"/> + <statistic name="msgRoutes" type="count64" desc="Total routed messages"/> + <statistic name="byteReceives" type="count64" desc="Total bytes received"/> + <statistic name="byteDrops" type="count64" desc="Total bytes dropped (no matching key)"/> + <statistic name="byteRoutes" type="count64" desc="Total routed bytes"/> + </class> +</programlisting> +<!--h3--></section> + + + <section role="h3" id="QpidManagementFramework-PropertiesandStatistics"><title> + Properties + and Statistics + </title> + + <para> + <property> and <statistic> tags must be placed within + <schema> and </schema> tags. + </para><para> + Properties, statistics, and methods are the building blocks of an + object class. Properties and statistics are both object + attributes, though they are treated differently. If an object + attribute is defining, seldom or never changes, or is large in + size, it should be defined as a <emphasis>property</emphasis>. If an + attribute is rapidly changing or is used to instrument the object + (counters, etc.), it should be defined as a <emphasis>statistic</emphasis>. + </para><para> + The XML syntax for <property> and <statistic> have + the following XML-attributes: + </para><table><title>XML Attributes for QMF Properties and Statistics</title><tgroup cols="4"> + <tbody> + <row> + <entry> + Attribute + </entry> + <entry> + <property> + </entry> + <entry> + <statistic> + </entry> + <entry> + Meaning + </entry> + </row> + <row> + <entry> + name + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + The name of the attribute + </entry> + </row> + <row> + <entry> + type + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + The data type of the attribute + </entry> + </row> + <row> + <entry> + unit + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + Optional unit name - use the singular (i.e. MByte) + </entry> + </row> + <row> + <entry> + desc + </entry> + <entry> + Y + </entry> + <entry> + Y + </entry> + <entry> + Description to annotate the attribute + </entry> + </row> + <row> + <entry> + references + </entry> + <entry> + Y + </entry> + <entry> + + </entry> + <entry> + If the type is "objId", names the referenced class + </entry> + </row> + <row> + <entry> + access + </entry> + <entry> + Y + </entry> + <entry> + + </entry> + <entry> + Access rights (RC, RW, RO) + </entry> + </row> + <row> + <entry> + index + </entry> + <entry> + Y + </entry> + <entry> + + </entry> + <entry> + "y" if this property is used to uniquely identify the + object. There may be more than one index property in a + class + </entry> + </row> + <row> + <entry> + parentRef + </entry> + <entry> + Y + </entry> + <entry> + + </entry> + <entry> + "y" if this property references an object in which this + object is in a child-parent relationship. + </entry> + </row> + <row> + <entry> + optional + </entry> + <entry> + Y + </entry> + <entry> + + </entry> + <entry> + "y" if this property is optional (i.e. may be + NULL/not-present) + </entry> + </row> + <row> + <entry> + min + </entry> + <entry> + Y + </entry> + <entry> + + </entry> + <entry> + Minimum value of a numeric attribute + </entry> + </row> + <row> + <entry> + max + </entry> + <entry> + Y + </entry> + <entry> + + </entry> + <entry> + Maximum value of a numeric attribute + </entry> + </row> + <row> + <entry> + maxLen + </entry> + <entry> + Y + </entry> + <entry> + + </entry> + <entry> + Maximum length of a string attribute + </entry> + </row> + </tbody> + </tgroup></table> +<!--h3--></section> + + + <section role="h3" id="QpidManagementFramework-Methods"><title> + Methods + </title> + + <para> + <method> tags must be placed within <schema> and + </schema> tags. + </para><para> + A <emphasis>method</emphasis> is an invokable function to be performed on + instances of the object class (i.e. a Remote Procedure Call). A + <method> tag has a name, an optional description, and + encloses zero or more arguments. Method arguments are defined by + the <arg> tag and have a name, a type, a direction, and an + optional description. The argument direction can be "I", "O", or + "IO" indicating input, output, and input/output respectively. An + example: + </para> + <programlisting> + <method name="echo" desc="Request a response to test the path to the management broker"> + <arg name="sequence" dir="IO" type="uint32"/> + <arg name="body" dir="IO" type="lstr"/> + </method> +</programlisting> +<!--h3--></section> + + <section role="h3" id="QpidManagementFramework-EventClasses"><title> + Event Classes + </title> + <para/> + <!--h3--></section> + + <section role="h3" id="QpidManagementFramework-DataTypes"><title> + Data Types + </title> + + <para> + Object attributes, method arguments, and event arguments have + data types. The data types are based on the rich data typing + system provided by the AMQP messaging protocol. The following + table describes the data types available for QMF: + </para><table><title>QMF Datatypes</title><tgroup cols="2"> + <tbody> + <row> + <entry> + QMF Type + </entry> + <entry> + Description + </entry> + </row> + <row> + <entry> + REF + </entry> + <entry> + QMF Object ID - Used to reference another QMF object. + </entry> + </row> + <row> + <entry> + U8 + </entry> + <entry> + 8-bit unsigned integer + </entry> + </row> + <row> + <entry> + U16 + </entry> + <entry> + 16-bit unsigned integer + </entry> + </row> + <row> + <entry> + U32 + </entry> + <entry> + 32-bit unsigned integer + </entry> + </row> + <row> + <entry> + U64 + </entry> + <entry> + 64-bit unsigned integer + </entry> + </row> + <row> + <entry> + S8 + </entry> + <entry> + 8-bit signed integer + </entry> + </row> + <row> + <entry> + S16 + </entry> + <entry> + 16-bit signed integer + </entry> + </row> + <row> + <entry> + S32 + </entry> + <entry> + 32-bit signed integer + </entry> + </row> + <row> + <entry> + S64 + </entry> + <entry> + 64-bit signed integer + </entry> + </row> + <row> + <entry> + BOOL + </entry> + <entry> + Boolean - True or False + </entry> + </row> + <row> + <entry> + SSTR + </entry> + <entry> + Short String - String of up to 255 bytes + </entry> + </row> + <row> + <entry> + LSTR + </entry> + <entry> + Long String - String of up to 65535 bytes + </entry> + </row> + <row> + <entry> + ABSTIME + </entry> + <entry> + Absolute time since the epoch in nanoseconds (64-bits) + </entry> + </row> + <row> + <entry> + DELTATIME + </entry> + <entry> + Delta time in nanoseconds (64-bits) + </entry> + </row> + <row> + <entry> + FLOAT + </entry> + <entry> + Single precision floating point number + </entry> + </row> + <row> + <entry> + DOUBLE + </entry> + <entry> + Double precision floating point number + </entry> + </row> + <row> + <entry> + UUID + </entry> + <entry> + UUID - 128 bits + </entry> + </row> + <row> + <entry> + FTABLE + </entry> + <entry> + Field-table - std::map in C++, dictionary in Python + </entry> + </row> + </tbody> + </tgroup></table><para> + In the XML schema definition, types go by different names and + there are a number of special cases. This is because the XML + schema is used in code-generation for the agent API. It provides + options that control what kind of accessors are generated for + attributes of different types. The following table enumerates the + types available in the XML format, which QMF types they map to, + and other special handling that occurs. + </para><table><title>XML Schema Mapping for QMF Types</title><tgroup cols="4"> + <tbody> + <row> + <entry> + XML Type + </entry> + <entry> + QMF Type + </entry> + <entry> + Accessor Style + </entry> + <entry> + Special Characteristics + </entry> + </row> + <row> + <entry> + objId + </entry> + <entry> + REF + </entry> + <entry> + Direct (get, set) + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + uint8,16,32,64 + </entry> + <entry> + U8,16,32,64 + </entry> + <entry> + Direct (get, set) + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + int8,16,32,64 + </entry> + <entry> + S8,16,32,64 + </entry> + <entry> + Direct (get, set) + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + bool + </entry> + <entry> + BOOL + </entry> + <entry> + Direct (get, set) + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + sstr + </entry> + <entry> + SSTR + </entry> + <entry> + Direct (get, set) + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + lstr + </entry> + <entry> + LSTR + </entry> + <entry> + Direct (get, set) + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + absTime + </entry> + <entry> + ABSTIME + </entry> + <entry> + Direct (get, set) + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + deltaTime + </entry> + <entry> + DELTATIME + </entry> + <entry> + Direct (get, set) + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + float + </entry> + <entry> + FLOAT + </entry> + <entry> + Direct (get, set) + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + double + </entry> + <entry> + DOUBLE + </entry> + <entry> + Direct (get, set) + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + uuid + </entry> + <entry> + UUID + </entry> + <entry> + Direct (get, set) + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + map + </entry> + <entry> + FTABLE + </entry> + <entry> + Direct (get, set) + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + hilo8,16,32,64 + </entry> + <entry> + U8,16,32,64 + </entry> + <entry> + Counter (inc, dec) + </entry> + <entry> + Generates value, valueMin, valueMax + </entry> + </row> + <row> + <entry> + count8,16,32,64 + </entry> + <entry> + U8,16,32,64 + </entry> + <entry> + Counter (inc, dec) + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + mma32,64 + </entry> + <entry> + U32,64 + </entry> + <entry> + Direct + </entry> + <entry> + Generates valueMin, valueMax, valueAverage, valueSamples + </entry> + </row> + <row> + <entry> + mmaTime + </entry> + <entry> + DELTATIME + </entry> + <entry> + Direct + </entry> + <entry> + Generates valueMin, valueMax, valueAverage, valueSamples + </entry> + </row> + </tbody> + </tgroup></table> + + <note><title>Important</title> + <para> + When writing a schema using the XML format, types used in + <property> or <arg> must be types that have + <emphasis>Direct</emphasis> accessor style. Any type may be used in + <statistic> tags. + </para> + </note> + +<!--h3--></section> +<!--h2--></section> + + <section role="h2" id="QpidManagementFramework-ClassKeysandClassVersioning"><title> + Class + Keys and Class Versioning + </title> + + <para/> + +<!--h2--></section> + + <!--h1--></section> + + <section role="h1" id="QpidManagementFramework-TheQMFProtocol"><title> + The QMF + Protocol + </title> + + <para> + The QMF protocol defines the message formats and communication + patterns used by the different QMF components to communicate with + one another. + </para><para> + A description of the current version of the QMF protocol can be + found at <xref linkend="qpid_QMF-Protocol"/>. + </para><para> + A proposal for an updated protocol based on map-messages is in + progress and can be found at <xref linkend="qpid_QMF-Map-Message-Protocol"/>. + </para> +<!--h1--></section> + + <section role="h1" id="QpidManagementFramework-HowtoWriteaQMFConsole"><title> + How + to Write a QMF Console + </title> + + <para> + Please see the <xref linkend="qpid_QMF-Python-Console-Tutorial"/> for information about using the console API with + Python. + </para> +<!--h1--></section> + + <section role="h1" id="QpidManagementFramework-HowtoWriteaQMFAgent"><title> + How to + Write a QMF Agent + </title> + <para/> + <!--h1--></section> + + +</section> diff --git a/qpid/doc/book/src/cpp-broker/Running-CPP-Broker.xml b/qpid/doc/book/src/cpp-broker/Running-CPP-Broker.xml new file mode 100644 index 0000000000..7f76cbc354 --- /dev/null +++ b/qpid/doc/book/src/cpp-broker/Running-CPP-Broker.xml @@ -0,0 +1,846 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section id="section-Running-a-Qpid-CPP-Broker"> + <title> + Running a Qpid C++ Broker + </title> + + <section role="h2" id="RASC-BuildingtheCppBrokerandClientLibraries"><title> + Building the + C++ Broker and Client Libraries + </title> + <para> + The root directory for the C++ distribution is named + qpidc-0.4. The README file in that directory gives + instructions for building the broker and client libraries. In + most cases you will do the following: + </para> + <programlisting> +[qpidc-0.4]$ ./configure +[qpidc-0.4]$ make +</programlisting> + <!--h2--></section> + <section role="h2" id="RASC-RunningtheCppBroker"><title> + Running the C++ Broker + </title> + <para> + Once you have built the broker and client libraries, you can + start the broker from the command line: + </para> + <programlisting> +[qpidc-0.4]$ src/qpidd +</programlisting> + <para> + Use the --daemon option to run the broker as a daemon + process: + </para> + <programlisting> +[qpidc-0.4]$ src/qpidd --daemon +</programlisting> + <para> + You can stop a running daemon with the --quit option: + </para> + <programlisting> +[qpidc-0.4]$ src/qpidd --quit +</programlisting> + <para> + You can see all available options with the --help option + </para> + <programlisting> +[qpidc-0.4]$ src/qpidd --help +</programlisting> + <!--h2--></section> + <section role="h2" id="RASC-Mostcommonquestionsgettingqpiddrunning"><title> + Most + common questions getting qpidd running + </title> + <section role="h3" id="RASC-Errorwhenstartingbroker-3A-22nodatadirectory-22"><title> + Error + when starting broker: "no data directory" + </title> + <para> + The C++ Broker requires you to set a data directory or specify + --no-data-dir (see help for more details). The data + directory is used for the journal, so it is important when + reliability counts. Make sure your process has write permission + to the data directory. + </para><para> + The default location is + </para> + <programlisting> +/lib/var/qpidd +</programlisting> + <para> + An alternate location can be set with --data-dir + </para> + <!--h3--></section> + <section role="h3" id="RASC-Errorwhenstartingbroker-3A-22thatprocessislocked-22"><title> + Error + when starting broker: "that process is locked" + </title> + <para> + Note that when qpidd starts it creates a lock file is data + directory are being used. If you have a un-controlled exit, + please mail + the trace from the core to the dev@qpid.apache.org mailing list. + To clear the lock run + </para> + <programlisting> +./qpidd -q +</programlisting> + <para> + It should also be noted that multiple brokers can be run on the + same host. To do so set alternate data directories for each qpidd + instance. + </para> + <!--h3--></section> + <section role="h3" id="RASC-Usingaconfigurationfile"><title> + Using a configuration + file + </title> + <para> + Each option that can be specified on the command line can also be + specified in a configuration file. To see available options, use + --help on the command line: + </para> + <programlisting> +./qpidd --help +</programlisting> + <para> + A configuration file uses name/value pairs, one on each line. To + convert a command line option to a configuration file entry: + </para><para> + a.) remove the '--' from the beginning of the option. + b.) place a '=' between the option and the value (use + <emphasis>yes</emphasis> or <emphasis>true</emphasis> to enable options that take no + value when specified on the command line). + c.) place one option per line. + </para><para> + For instance, the --daemon option takes no value, the + --log-to-syslog option takes the values yes or + no. The following configuration file sets these two + options: + </para> + <programlisting> +daemon=yes +log-to-syslog=yes +</programlisting> + <!--h3--></section> + <section role="h3" id="RASC-CanIuseanyLanguageclientwiththeCppBroker-3F"><title> + Can I use + any Language client with the C++ Broker? + </title> + <para> + Yes, all the clients work with the C++ broker; it is written in + C+<emphasis>, but uses the AMQP wire protocol. Any broker can be used + with any client that uses the same AMQP version. When running the + C</emphasis>+ broker, it is highly recommended to run AMQP 0-10. + </para><para> + Note that JMS also works with the C++ broker. + </para> + <!--h3--></section> + <!--h2--></section> + <section role="h2" id="RASC-Authentication"><title> + Authentication + </title> + <section role="h3" id="RASC-Linux"><title> + Linux + </title> + <para> + The PLAIN authentication is done on a username+password, which is + stored in the sasldb_path file. Usernames and passwords can be + added to the file using the command: + </para> + <programlisting> +saslpasswd2 -f /var/lib/qpidd/qpidd.sasldb -u <REALM> <USER> +</programlisting> + <para> + The REALM is important and should be the same as the + --auth-realm + option to the broker. This lets the broker properly find the user + in + the sasldb file. + </para><para> + Existing user accounts may be listed with: + </para> + <programlisting> +sasldblistusers2 -f /var/lib/qpidd/qpidd.sasldb +</programlisting> + <para> + NOTE: The sasldb file must be readable by the user running the + qpidd daemon, and should be readable only by that user. + </para> + <!--h3--></section> + <section role="h3" id="RASC-Windows"><title> + Windows + </title> + <para> + On Windows, the users are authenticated against the local + machine. You should add the appropriate users using the standard + Windows tools (Control Panel->User Accounts). To run many of + the examples, you will need to create a user "guest" with + password "guest". + </para><para> + If you cannot or do not want to create new users, you can run + without authentication by specifying the no-auth option to the + broker. + </para> + <!--h3--></section> + <!--h2--></section> + + <section role="h2" id="RASC-Slightlymorecomplexconfiguration"><title> + Slightly more + complex configuration + </title> + <para> + The easiest way to get a full listing of the broker's options are + to use the --help command, run it locally for the latest set of + options. These options can then be set in the conf file for + convenience (see above) + </para> + <programlisting> +./qpidd --help + +Usage: qpidd OPTIONS +Options: + -h [ --help ] Displays the help message + -v [ --version ] Displays version information + --config FILE (/etc/qpidd.conf) Reads configuration from FILE + +Module options: + --module-dir DIR (/usr/lib/qpidd) Load all .so modules in this directory + --load-module FILE Specifies additional module(s) to be loaded + --no-module-dir Don't load modules from module directory + +Broker Options: + --data-dir DIR (/var/lib/qpidd) Directory to contain persistent data generated by the broker + --no-data-dir Don't use a data directory. No persistent + configuration will be loaded or stored + -p [ --port ] PORT (5672) Tells the broker to listen on PORT + --worker-threads N (3) Sets the broker thread pool size + --max-connections N (500) Sets the maximum allowed connections + --connection-backlog N (10) Sets the connection backlog limit for the + server socket + --staging-threshold N (5000000) Stages messages over N bytes to disk + -m [ --mgmt-enable ] yes|no (1) Enable Management + --mgmt-pub-interval SECONDS (10) Management Publish Interval + --ack N (0) Send session.ack/solicit-ack at least every + N frames. 0 disables voluntary ack/solitict + -ack + +Daemon options: + -d [ --daemon ] Run as a daemon. + -w [ --wait ] SECONDS (10) Sets the maximum wait time to initialize the + daemon. If the daemon fails to initialize, prints + an error and returns 1 + -c [ --check ] Prints the daemon's process ID to stdout and + returns 0 if the daemon is running, otherwise + returns 1 + -q [ --quit ] Tells the daemon to shut down +Logging options: + -t [ --trace ] Enables all logging + --log-enable RULE (notice+) Enables logging for selected levels and components. + RULE is in the form 'LEVEL[+-][:PATTERN]' + LEVEL is one of: + trace debug info notice warning error critical + PATTERN is a logging category name, or a namespace-qualified + function name or name fragment. + Logging category names are: + Security Broker Management Protocol System HA Messaging Store + Network Test Client Model Unspecified + + For example: + '--log-enable warning+' + logs all warning, error and critical messages. + + '--log-enable trace+:Broker' + logs all category 'Broker' messages. + + '--log-enable debug:framing' + logs debug messages from all functions with 'framing' in + the namespace or function name. + + This option can be used multiple times + + --log-disable RULE Disables logging for selected levels and components. + RULE is in the form 'LEVEL[+-][:PATTERN]' + LEVEL is one of: + trace debug info notice warning error critical + PATTERN is a logging category name, or a namespace-qualified + function name or name fragment. + Logging category names are: + Security Broker Management Protocol System HA Messaging Store + Network Test Client Model Unspecified + + For example: + '--log-disable warning-' + disables logging all warning, notice, info, debug, and + trace messages. + + '--log-disable trace:Broker' + disables all category 'Broker' trace messages. + + '--log-disable debug-:qmf::' + disables logging debug and trace messages from all functions + with 'qmf::' in the namespace. + + This option can be used multiple times + + --log-time yes|no (1) Include time in log messages + --log-level yes|no (1) Include severity level in log messages + --log-source yes|no (0) Include source file:line in log + messages + --log-thread yes|no (0) Include thread ID in log messages + --log-function yes|no (0) Include function signature in log + messages + --log-hires-timestamp yes|no (0) Use hi-resolution timestamps in log + messages + --log-category yes|no (1) Include category in log messages + --log-prefix STRING Prefix to prepend to all log messages + +Logging sink options: + --log-to-stderr yes|no (1) Send logging output to stderr + --log-to-stdout yes|no (0) Send logging output to stdout + --log-to-file FILE Send log output to FILE. + --log-to-syslog yes|no (0) Send logging output to syslog; + customize using --syslog-name and + --syslog-facility + --syslog-name NAME (qpidd) Name to use in syslog messages + --syslog-facility LOG_XXX (LOG_DAEMON) + Facility to use in syslog messages + +</programlisting> + <!--h2--></section> + <section role="h2" id="RASC-Loadingextramodules"><title> + Loading extra modules + </title> + <para> + By default the broker will load all the modules in the module + directory, however it will NOT display options for modules that + are not loaded. So to see the options for extra modules loaded + you need to load the module and then add the help command like + this: + </para> + <programlisting> +./qpidd --load-module libbdbstore.so --help +Usage: qpidd OPTIONS +Options: + -h [ --help ] Displays the help message + -v [ --version ] Displays version information + --config FILE (/etc/qpidd.conf) Reads configuration from FILE + + + / .... non module options would be here ... / + + +Store Options: + --store-directory DIR Store directory location for persistence (overrides + --data-dir) + --store-async yes|no (1) Use async persistence storage - if store supports + it, enables AIO O_DIRECT. + --store-force yes|no (0) Force changing modes of store, will delete all + existing data if mode is changed. Be SURE you want + to do this! + --num-jfiles N (8) Number of files in persistence journal + --jfile-size-pgs N (24) Size of each journal file in multiples of read + pages (1 read page = 64kiB) +</programlisting> +<!--h2--></section> +<section role="h2" id="RASC-message-timestamps"> + <title>Timestamping Received Messages</title> + <para> + The AMQP 0-10 specification defines a <emphasis>timestamp</emphasis> message delivery + property. The timestamp delivery property is a <emphasis>datetime</emphasis> value + that is written to each message that arrives at the broker. See the description of + "message.delivery-properties" in the "Command Classes" section of the AMQP 0-10 + specification for more detail. + </para> + <para> + See the <emphasis>Programming in Apache Qpid</emphasis> documentation for + information regarding how clients may access the timestamp value in received + messages. + </para> + <para> + By default, this timestamping feature is disabled. To enable timestamping, use the + <emphasis>enable-timestamp</emphasis> broker configuration option. Setting the + enable-timestamp option to 'yes' will enable message timestamping: + </para> + <programlisting> +./qpidd --enable-timestamp yes + </programlisting> + <para> + Message timestamping can also be enabled (and disabled) without restarting the broker. + The QMF Broker management object defines two methods for accessing the timestamp + configuration: + </para> + <table> + <title>QMF Management - Broker Methods for Managing the Timestamp Configuration</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Method</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>getTimestampConfig</entry> + <entry>Get the message timestamping configuration. Returns True if received messages are timestamped.</entry> + </row> + <row> + <entry>setTimestampConfig</entry> + <entry>Set the message timestamping configuration. Set True to enable timestamping received messages, False to disable timestamping.</entry> + </row> + </tbody> + </tgroup> + </table> + <example> + <title>Enabling Message Timestamping via QMF - Python</title> + <para> + The following code fragment uses these QMF method calls to enable message timestamping. + </para> + <programlisting lang="python"> +# get the state of the timestamp configuration +broker = self.qmf.getObjects(_class="broker")[0] +rc = broker.getTimestampConfig() +self.assertEqual(rc.status, 0) +self.assertEqual(rc.text, "OK") +print("The timestamp setting is %s" % str(rc.receive)) + +# try to enable it +rc = broker.setTimestampConfig(True) +self.assertEqual(rc.status, 0) +self.assertEqual(rc.text, "OK") + </programlisting> + </example> +<!--h2--></section> +<section role="h2" id="RASC-logging-options"> + <title>Logging Options</title> + <para> + The C++ Broker provides a rich set of logging options. To use logging effectively + a user must select a useful set of options to expose the log messages of interest. + This section introduces the logging options and how they are used in practice. + </para> + <section role="h3" id="RASC-LogConcepts"> + <title>Logging Concepts</title> + + <section role="h4" id="RASC-LogConcept-level"> + <title>Log Level</title> + <para> + The C++ Broker has a traditional set of log severity levels. The log levels + range from low frequency and high importance critical level + to high frequency and low importance trace level. + </para> + <table> + <title>C++ Broker Log Severity Levels</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Name</entry> + <entry>Level</entry> + </row> + </thead> + <tbody> + <row><entry>critical</entry><entry>high</entry></row> + <row><entry>error</entry> <entry></entry> </row> + <row><entry>warning</entry> <entry></entry> </row> + <row><entry>notice</entry> <entry></entry> </row> + <row><entry>info</entry> <entry></entry> </row> + <row><entry>debug</entry> <entry></entry> </row> + <row><entry>trace</entry> <entry>low</entry> </row> + </tbody> + </tgroup> + </table> + <!--h4--></section> + + <section role="h4" id="RASC-LogConcept-category"> + <title>Log Category</title> + <para> + The C++ Broker groups log messages into categories. The log category + name may then be used to enable and disable groups of related messages + at varying log levels. + </para> + <table> + <title>C++ Broker Log Categories</title> + <tgroup cols="1"> + <thead> + <row> + <entry>Name</entry> + </row> + </thead> + <tbody> + <row><entry>Security</entry></row> + <row><entry>Broker</entry></row> + <row><entry>Management</entry></row> + <row><entry>Protocol</entry></row> + <row><entry>System</entry></row> + <row><entry>HA</entry></row> + <row><entry>Messaging</entry></row> + <row><entry>Store</entry></row> + <row><entry>Network</entry></row> + <row><entry>Test</entry></row> + <row><entry>Client</entry></row> + <row><entry>Model</entry></row> + <row><entry>Unspecified</entry></row> + </tbody> + </tgroup> + </table> + <para> + Generally speaking the log categories are groupings of messages from files + related by + thier placement in the source code directory structure. The + <emphasis>Model</emphasis> category is an exception. Debug log entries + identified by the Model category expose the creation, deletion, and usage + statistics for managed objects in the broker. Log messages in the Model + category are emitted by source files scattered throughout the source tree. + </para> + <!--h4--></section> + + <section role="h4" id="RASC-LogConcept-StatementAttributes"> + <title>Log Statement Attributes</title> + <para> + Every log statement in the C++ Broker has fixed attributes that may be + used in enabling or disabling log messages. + </para> + <table> + <title>C++ Broker Log Statement Attributes</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>Level</entry> + <entry>Severity level</entry> + </row> + <row> + <entry>Category</entry> + <entry>Category</entry> + </row> + <row> + <entry>Function</entry> + <entry>Namespace-qualified source function name</entry> + </row> + </tbody> + </tgroup> + </table> + + <!--h4--></section> + + <!--h3--></section> + <section role="h3" id="RASC-LogRules-EnableDisable"> + <title>Enabling and Disabling Log Messages</title> + <para> + The Qpid C++ Broker has hundreds of log message statements in the source + code. Under typical conditions + most of the messages are deselected and never emitted as actual logs. + However, under some circumstances debug and trace messages must be enabled + to analyze broker behavior. This section discusses how the broker enables + and disables log messages. + </para> + <para> + At startup the broker processes command line and option file '--log-enable RULE' and + '--log-disable RULE' options using the following rule format: + </para> + <programlisting> + LEVEL[+-][:PATTERN} + </programlisting> + <table> + <title>C++ Broker Log Enable/Disable RULE Format</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>LEVEL</entry> + <entry>Severity level</entry> + </row> + <row> + <entry>[+-]</entry> + <entry> + Option level modifiers. <emphasis>'+'</emphasis> indicates + <emphasis>this level and above</emphasis>. + <emphasis>'-'</emphasis> indicates <emphasis>this level and below</emphasis>. + </entry> + </row> + <row> + <entry>[:PATTERN]</entry> + <entry> + If PATTERN matches a Category name then the log option applies only + to log messages with the named category. Otherwise, the pattern is stored + as a function name match string. + </entry> + </row> + </tbody> + </tgroup> + </table> + <para> + As the options are procesed the results are aggregated into two pairs of tables. + </para> + <table> + <title>C++ Broker Log Enable/Disable Settings Tables</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>Function Table</entry> + <entry> + A set of vectors of accumulated function name patterns. + There is a separate vector of name patterns for each log level. + </entry> + </row> + <row> + <entry>Category Table</entry> + <entry> + A simple two dimensional array of boolean values indexed by + [Level][Category] indicating + if all log statements are enabled for the Level and Category pair. + </entry> + </row> + </tbody> + </tgroup> + </table> + <para> + --log-enable statements and --log-disable statements are aggregated into dedicated + Function and Category tables. With this scheme multiple conflicting log enable and + disable commands may be processed in any order yet produce consistent patterns + of enabled broker log statements. + </para> + <!--h3--></section> + + <section role="h3" id="RASC-LogRules-RuleMatching"> + <title>Determining if a Log Statement is Enabled</title> + <para> + Function Table Lookups are simple string pattern matches where the searchable + text is the domain-name qualified function name from the log statement and the + search pattern is the set of Function Table entries for a given log level. + </para> + <para> + Category Table Lookups are boolean array queries where the Level and Category + indexes are from the log statement. + </para> + <para> + Each log statment sends its Level, Category, and FunctionName to the + Logger for evaluation. As a result the log statement is either visible or hidden. + </para> + <table> + <title>C++ Broker Log Statement Visibility Determination</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Test</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>Disabled Function</entry> + <entry> + If the statement matches a Disabled Function pattern then the + statement is hidden. + </entry> + </row> + <row> + <entry>Disabled Category</entry> + <entry> + If the Disabled Category table for this [Level][Category] is true then the + statement is hidden. + </entry> + </row> + <row> + <entry>Enabled Function</entry> + <entry> + If the statement matches a Enabled Function pattern then the + statement is visible. + </entry> + </row> + <row> + <entry>Enabled Category</entry> + <entry> + If the Enabled Category table for this [Level][Category] is true then the + statement is visible. + </entry> + </row> + <row> + <entry>Unreferenced</entry> + <entry> + Log statements that are unreferenced by specific enable rules are by + default hidden. + </entry> + </row> + </tbody> + </tgroup> + </table> + <!--h3--></section> + + <section role="h3" id="RASC-LogRules-Reenabling"> + <title>Changing Log Enable/Disable Settings at Run Time</title> + <para> + The C++ Broker provides QMF management methods that allow users to query and to set + the log enable and disable settings while the broker is running. + </para> + <table> + <title>QMF Management - Broker Methods for Managing the Log Enable/Disable Settings</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Method</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>getLogLevel</entry> + <entry>Get the log enable/disable settings.</entry> + </row> + <row> + <entry>setLogLevel</entry> + <entry>Set the log enable/disable settings.</entry> + </row> + </tbody> + </tgroup> + </table> + <para> + The management methods use a RULE format similar to the option RULE format: + </para> + <programlisting> + [!]LEVEL[+-][:PATTERN] + </programlisting> + <para> + The difference is the leading exclamation point that identifies disable rules. + </para> + <example> + <title> + Querying Log Settings via qpid-ctrl utility + </title> + <para> + At start up a C++ Broker may have the following options: + </para> + <programlisting> + --log-enable debug+ + --log-enable trace+:Protocol + --log-disable info-:Management + </programlisting> + <para> + The following command: + </para> + <programlisting> + qpid-ctrl getLogLevel + </programlisting> + <para> + will return the following result: + </para> + <programlisting> + level=debug+,trace+:Protocol,!info-:Management + </programlisting> + </example> + <example> + <title> + Setting Log Settings via qpid-ctrl utility + </title> + <para> + New broker log options may be set at any time using qpid-ctrl + </para> + <programlisting> + qpid-ctrl setLogLevel level='debug+:Broker !debug-:broker::Broker::ManagementMethod' + </programlisting> + </example> + <!--h3--></section> + + <section role="h3" id="RASC-LogRules-Explorer"> + <title>Discovering Log Sources</title> + <para> + A common condition for a user is being swamped by log messages that are not + interesting for some debug situation. Conversely, a particular log entry + may be of interest all the time but enabling all log levels just to see a + single log entry is too much. How can a user find and specify a pattern + to single out logs of interest? + </para> + <para> + The easiest way to hide messages it to disable logs at log level and + category combinations. This may not always work since using only these + coarse controls the log messages of interest may also be hidden. + To discover a more precise filter to specify the messages you want + to show or to hide you may temporarily enable the + <emphasis>"--log-function=yes"</emphasis> option. + The following log entries show a typical log message without and + with the log function names enabled: + </para> + <programlisting> + 2013-05-01 11:16:01 [Broker] notice Broker running + 2013-05-01 11:16:54 [Broker] notice qpid::broker::Broker::run: Broker running + </programlisting> + <para> + This log entry is emitted by function <emphasis>qpid::broker::Broker::run</emphasis> + and this is the function name pattern to be used in specific log enable and + disable rules. + For example, this log entry could be disabled with any of the following: + </para> + <programlisting> + --log-disable notice [1] + --log-disable notice:qpid:: [2] + --log-disable notice:Broker [3] + --log-disable notice-:Broker::run [4] + --log-disable notice:qpid::broker::Broker::run [5] + </programlisting> + <itemizedlist> + <listitem> + [1] Disables all messages at notice level. + </listitem> + <listitem> + [2] Disables all messages at notice level in qpid:: name space. This is + very broad and disables many log messages. + </listitem> + <listitem> + [3] Disables the category <emphasis>[Broker]</emphasis> and is not specific + to the function. Category names supercede function name fragments in + log option processing + </listitem> + <listitem> + [4] Disables the function. + </listitem> + <listitem> + [5] Disables the function. + </listitem> + </itemizedlist> + <para> + Remember that the log filter matching PATTERN strings are matched against the + domain-name qualified function names associated with the log statement + and not against the log message text itself. That is, in the previous example + log filters cannot be set on the log text <emphasis>Broker running</emphasis> + </para> + <!--h3--></section> +<!--h2--></section> +</section> diff --git a/qpid/doc/book/src/cpp-broker/Security.xml b/qpid/doc/book/src/cpp-broker/Security.xml new file mode 100644 index 0000000000..8f42e6abdf --- /dev/null +++ b/qpid/doc/book/src/cpp-broker/Security.xml @@ -0,0 +1,2516 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> +<section id="chap-Messaging_User_Guide-Security"> + <title>Security</title> + <para> + This chapter describes how authentication, rule-based authorization, encryption, and digital signing can be accomplished using Qpid. Authentication is the process of verifying the identity of a user; in Qpid, this is done using the SASL framework. Rule-based authorization is a mechanism for specifying the actions that each user is allowed to perform; in Qpid, this is done using an Access Control List (ACL) that is part of the Qpid broker. Encryption is used to ensure that data is not transferred in a plain-text format that could be intercepted and read. Digital signatures provide proof that a given message was sent by a known sender. Encryption and signing are done using SSL (they can also be done using SASL, but SSL provides stronger encryption). + </para> + <section id="sect-Messaging_User_Guide-Security-User_Authentication"> + <title>User Authentication</title> + <para> + AMQP uses Simple Authentication and Security Layer (SASL) to authenticate client connections to the broker. SASL is a framework that supports a variety of authentication methods. For secure applications, we suggest <command>CRAM-MD5</command>, <command>DIGEST-MD5</command>, or <command>GSSAPI</command>. The <command>ANONYMOUS</command> method is not secure. The <command>PLAIN</command> method is secure only when used together with SSL. + </para> + <para> + Both the Qpid broker and Qpid clients use the <ulink url="http://cyrusimap.web.cmu.edu/">Cyrus SASL library</ulink>, a full-featured authentication framework, which offers many configuration options. This section shows how to configure users for authentication with SASL, which is sufficient when using <command>SASL PLAIN</command>. If you are not using SSL, you should configure SASL to use <command>CRAM-MD5</command>, <command>DIGEST-MD5</command>, or <command>GSSAPI</command> (which provides Kerberos authentication). For information on configuring these and other options in SASL, see the Cyrus SASL documentation<!-- at <filename>/usr/share/doc/cyrus-sasl-lib-2.1.22/index.html</filename> for &RHEL5; or <filename>/usr/share/doc/cyrus-sasl-2.1.19/index.html</filename> for &RHEL4;-->. + </para> + <important> + <title>Important</title> + <para> + The <command>SASL PLAIN</command> method sends passwords in cleartext, and is vulnerable to man-in-the-middle attacks unless SSL (Secure Socket Layer) is also used (see <xref linkend="sect-Messaging_User_Guide-Security-Encryption_using_SSL" />). + </para> + <para> + If you are not using SSL, we recommend that you disable <command>PLAIN</command> authentication in the broker. + </para> + + </important> + <para> + The Qpid broker uses the <command>auth yes|no</command> option to determine whether to use SASL authentication. Turn on authentication by setting <command>auth</command> to <command>yes</command> in <filename>/etc/qpidd.conf</filename>: + </para> + +<programlisting> +# /etc/qpidd.conf +# +# Set auth to 'yes' or 'no' + +auth=yes +</programlisting> + <section id="sect-Messaging_User_Guide-User_Authentication-Configuring_SASL"> + <title>Configuring SASL</title> + <para> + On Linux systems, the SASL configuration file is generally found in <filename>/etc/sasl2/qpidd.conf</filename> <!-- for &RHEL5; and-->or <filename>/usr/lib/sasl2/qpidd.conf</filename><!-- for &RHEL4;-->. + </para> + <para> + The SASL database contains user names and passwords for SASL. In SASL, a user may be associated with a <firstterm>realm</firstterm>. The Qpid broker authenticates users in the <command>QPID</command> realm by default, but it can be set to a different realm using the <command>realm</command> option: + </para> + +<programlisting> +# /etc/qpidd.conf +# +# Set the SASL realm using 'realm=' + +auth=yes +realm=QPID +</programlisting> + <para> + The SASL database is installed at <filename>/var/lib/qpidd/qpidd.sasldb</filename>; initially, it has one user named <command>guest</command> in the <command>QPID</command> realm, and the password for this user is <command>guest</command>. + </para> + <note> + <title>Note</title> + <para> + The user database is readable only by the <systemitem class="username">qpidd</systemitem> user. When run as a daemon, Qpid always runs as the <systemitem class="username">qpidd</systemitem> user. If you start the broker from a user other than the <systemitem class="username">qpidd</systemitem> user, you will need to either reconfigure SASL or turn authentication off. + </para> + + </note> + <important> + <title>Important</title> + <para> + The SASL database stores user names and passwords in plain text. If it is compromised so are all of the passwords that it stores. This is the reason that the <systemitem class="username">qpidd</systemitem> user is the only user that can read the database. If you modify permissions, be careful not to expose the SASL database. + </para> + + </important> + <para> + Add new users to the database by using the <command>saslpasswd2</command> command, which specifies a realm and a user ID. A user ID takes the form <command><replaceable>user-id</replaceable>@<replaceable>domain</replaceable>.</command>. + </para> + +<screen># saslpasswd2 -f /var/lib/qpidd/qpidd.sasldb -u <replaceable>realm</replaceable> <replaceable>new_user_name</replaceable></screen> + <para> + To list the users in the SASL database, use <command>sasldblistusers2</command>: + </para> + +<screen># sasldblistusers2 -f /var/lib/qpidd/qpidd.sasldb +</screen> + <para> + If you are using <command>PLAIN</command> authentication, users who are in the database can now connect with their user name and password. This is secure only if you are using SSL. If you are using a more secure form of authentication, please consult your SASL documentation for information on configuring the options you need. + </para> + + </section> + + <section id="sect-Messaging_User_Guide-User_Authentication-Kerberos"> + <title>Kerberos</title> + <para> + Both the Qpid broker and Qpid users are 'principals' of the Kerberos server, which means that they are both clients of the Kerberos authentication services. + </para> + <para> + To use Kerberos, both the Qpid broker and each Qpid user must be authenticated on the Kerberos server: + </para> + <procedure> + <step> + <para> + Install the Kerberos workstation software and Cyrus SASL GSSAPI on each machine that runs a qpidd broker or a qpidd messaging client: + </para> + +<screen>$ sudo yum install cyrus-sasl-gssapi krb5-workstation</screen> + + </step> + <step> + <para> + Make sure that the Qpid broker is registered in the Kerberos database. + </para> + <para> + Traditionally, a Kerberos principal is divided into three parts: the primary, the instance, and the realm. A typical Kerberos V5 has the format <literal>primary/instance@REALM</literal>. For a Qpid broker, the primary is <literal>qpidd</literal>, the instance is the fully qualified domain name, which you can obtain using <command>hostname --fqdn</command>, and the REALM is the Kerberos domain realm. By default, this realm is <literal>QPID</literal>, but a different realm can be specified in qpid.conf, e.g.: +<screen>realm=EXAMPLE.COM</screen> + + </para> + <para> + For instance, if the fully qualified domain name is <literal>dublduck.example.com</literal> and the Kerberos domain realm is <literal>EXAMPLE.COM</literal>, then the principal name is <literal>qpidd/dublduck.example.com@EXAMPLE.COM</literal>. + </para> + <para> + The following script creates a principal for qpidd: + </para> + +<programlisting> +FDQN=`hostname --fqdn` +REALM="EXAMPLE.COM" +kadmin -r $REALM -q "addprinc -randkey -clearpolicy qpidd/$FQDN" +</programlisting> + <para> + Now create a Kerberos keytab file for the Qpid broker. The Qpid broker must have read access to the keytab file. The following script creates a keytab file and allows the broker read access: + </para> + +<programlisting> +QPIDD_GROUP="qpidd" +kadmin -r $REALM -q "ktadd -k /etc/qpidd.keytab qpidd/$FQDN@$REALM" +chmod g+r /etc/qpidd.keytab +chgrp $QPIDD_GROUP /etc/qpidd.keytab +</programlisting> + <para> + The default location for the keytab file is <filename>/etc/krb5.keytab</filename>. If a different keytab file is used, the KRB5_KTNAME environment variable must contain the name of the file, e.g.: + </para> + +<programlisting> +export KRB5_KTNAME=/etc/qpidd.keytab +</programlisting> + <para> + If this is correctly configured, you can now enable kerberos support on the Qpid broker by setting the <varname>auth</varname> and <varname>realm</varname> options in <filename>/etc/qpidd.conf</filename>: + </para> + +<programlisting> +# /etc/qpidd.conf +auth=yes +realm=EXAMPLE.COM +</programlisting> + <para> + Restart the broker to activate these settings. + </para> + + </step> + <step> + <para> + Make sure that each Qpid user is registered in the Kerberos database, and that Kerberos is correctly configured on the client machine. The Qpid user is the account from which a Qpid messaging client is run. If it is correctly configured, the following command should succeed: + </para> + +<screen>$ kinit user@REALM.COM</screen> + + </step> + + </procedure> + + <para> + Java JMS clients require a few additional steps. + </para> + <procedure> + <step> + <para> + The Java JVM must be run with the following arguments: + </para> + <variablelist> + <varlistentry> + <term>-Djavax.security.auth.useSubjectCredsOnly=false</term> + <listitem> + <para> + Forces the SASL GASSPI client to obtain the kerberos credentials explicitly instead of obtaining from the "subject" that owns the current thread. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term>-Djava.security.auth.login.config=myjas.conf</term> + <listitem> + <para> + Specifies the jass configuration file. Here is a sample JASS configuration file: + </para> + +<programlisting> +com.sun.security.jgss.initiate { + com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true; +}; +</programlisting> + + </listitem> + + </varlistentry> + <varlistentry> + <term>-Dsun.security.krb5.debug=true</term> + <listitem> + <para> + Enables detailed debug info for troubleshooting + </para> + + </listitem> + + </varlistentry> + + </variablelist> + + </step> + <step> + <para> + The client's Connection URL must specify the following Kerberos-specific broker properties: + </para> + <itemizedlist> + <listitem> + <para> + <varname>sasl_mechs</varname> must be set to <literal>GSSAPI</literal>. + </para> + + </listitem> + <listitem> + <para> + <varname>sasl_protocol</varname> must be set to the principal for the qpidd broker, e.g. <literal>qpidd</literal>/ + </para> + + </listitem> + <listitem> + <para> + <varname>sasl_server</varname> must be set to the host for the SASL server, e.g. <literal>sasl.com</literal>. + </para> + + </listitem> + + </itemizedlist> + <para> + Here is a sample connection URL for a Kerberos connection: + </para> + +<screen>amqp://guest@clientid/testpath?brokerlist='tcp://localhost:5672?sasl_mechs='GSSAPI'&sasl_protocol='qpidd'&sasl_server='<server-host-name>''</screen> + + </step> + + </procedure> +<!-- + <para> + Please refer to the following documentation for more detail on using Kerberos: + </para> + <variablelist> + <varlistentry> + <term>RHEL5</term> + <listitem> + <para> + <ulink url="http://www.redhat.com/docs/manuals/enterprise/RHEL-5-manual/Deployment_Guide-en-US/ch-kerberos.html"> Red Hat Enterprise Linux 5: Deployment Guide </ulink> + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term>RHEL4</term> + <listitem> + <para> + <ulink url="http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/ref-guide/ch-kerberos.html"> Red Hat Enterprise Linux 4: Reference Guide </ulink> + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term>Java</term> + <listitem> + <para> + <ulink url="http://java.sun.com/j2se/1.5.0/docs/guide/security/jgss/tutorials/index.html"> Introduction to JAAS and Java GSS-API Tutorials </ulink> + </para> + + </listitem> + + </varlistentry> + + </variablelist> + --> + + </section> + + + </section> + + <!-- ################################################### --> <section id="sect-Messaging_User_Guide-Security-Authorization"> + <title>Authorization</title> + <para> + In Qpid, Authorization specifies which actions can be performed by each authenticated user using an Access Control List (ACL). + </para> + <para> + Use the <command>--acl-file</command> command to load the access control list. The filename should have a <filename>.acl</filename> extension: + </para> + +<screen> + $ qpidd --acl-file <replaceable>./aclfilename.acl</replaceable></screen> + <para> + Each line in an ACL file grants or denies specific rights to a user. If the last line in an ACL file is <literal>acl deny all all</literal>, the ACL uses <firstterm>deny mode</firstterm>, and only those rights that are explicitly allowed are granted: + </para> + +<programlisting> + acl allow rajith@QPID all all + acl deny all all +</programlisting> + <para> + On this server, <literal>rajith@QPID</literal> can perform any action, but nobody else can. Deny mode is the default, so the previous example is equivalent to the following ACL file: + </para> + +<programlisting> + acl allow rajith@QPID all all +</programlisting> + <para> + Alternatively the ACL file may use <firstterm>allow mode</firstterm> by placing: + </para> +<programlisting> + acl allow all all +</programlisting> + <para> + as the final line in the ACL file. In <emphasis>allow mode</emphasis> all actions by all users are allowed unless otherwise denied by specific ACL rules. + The ACL rule which selects <emphasis>deny mode</emphasis> or <emphasis>allow mode</emphasis> must be the last line in the ACL rule file. + </para> + <para> + ACL syntax allows fine-grained access rights for specific actions: + </para> + +<programlisting> + acl allow carlt@QPID create exchange name=carl.* + acl allow fred@QPID create all + acl allow all consume queue + acl allow all bind exchange + acl deny all all +</programlisting> + <para> + An ACL file can define user groups, and assign permissions to them: + </para> + +<programlisting> + group admin ted@QPID martin@QPID + acl allow admin create all + acl deny all all +</programlisting> + <para> + An ACL file can define per user connection and queue quotas: + </para> + +<programlisting> + group admin ted@QPID martin@QPID + group blacklist usera@qpid userb@qpid + quota connections 10 admin + quota connections 5 all + quota connections 0 blacklist + quota queues 50 admin + quota queues 5 all + quota queues 1 test@qpid +</programlisting> + + <para> + Performance Note: Most ACL queries are performed infrequently. The overhead associated with + ACL passing an allow or deny decision on the creation of a queue is negligible + compared to actually creating and using the queue. One notable exception is the <command>publish exchange</command> + query. ACL files with no <emphasis>publish exchange</emphasis> rules are noted and the broker short circuits the logic + associated with the per-messsage <emphasis>publish exchange</emphasis> ACL query. + However, if an ACL file has any <emphasis>publish exchange</emphasis> rules + then the broker is required to perform a <emphasis>publish exchange</emphasis> query for each message published. + Users with performance critical applications are encouraged to structure exchanges, queues, and bindings so that + the <emphasis>publish exchange</emphasis> ACL rules are unnecessary. + </para> + + <!-- ######## --> <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntax"> + <title>ACL Syntax</title> + <para> + ACL rules follow this syntax: +<programlisting><![CDATA[ +aclline = ( comment | aclspec | groupspec | quotaspec ) + +comment = "#" [ STRING ] + +aclspec = "acl" permission ( groupname | name | "all" ) + ( action | "all" ) [ ( object | "all ) [ ( property "=" STRING )* ] ] + +groupspec = "group" groupname ( name )* [ "\" ] + +groupcontinuation = ( name )* [ "\" ] + +quotaspec = "quota" ( "connections" | "queues" ) NUMBER ( groupname | name | "all" )* + +name = ( ALPHANUMERIC | "-" | "_" | "." | "@" | "/" ) [ ( ALPHANUMERIC | "-" | "_" | "." | "@" | "/" )* ] + +groupname = ( ALPHANUMERIC | "-" | "_" ) [ ( ALPHANUMERIC | "-" | "_" )* ] + +permission = "allow" | "allow-log" | "deny" | "deny-log" + +action = "consume" | "publish" | "create" | "access" | + "bind" | "unbind" | "delete" | "purge" | + "update" + +object = "queue" | "exchange" | "broker" | "link" | + "method" | "query" | "connection" + +property = "name" | "durable" | "routingkey" | "autodelete" | + "exclusive" | "type" | "alternate" | "queuename" | + "exchangename" | "schemapackage" | "schemaclass" | + "policytype" | "paging" | + "queuemaxsizelowerlimit" | "queuemaxsizeupperlimit" | + "queuemaxcountlowerlimit" | "queuemaxcountupperlimit" | + "filemaxsizelowerlimit" | "filemaxsizeupperlimit" | + "filemaxcountlowerlimit" | "filemaxcountupperlimit" | + "pageslowerlimit" | "pagesupperlimit" | + "pagefactorlowerlimit" | "pagefactorupperlimit" +]]></programlisting> + + ACL rules can also include a single object name (or the keyword <parameter>all</parameter>) and one or more property name value pairs in the form <command>property=value</command> + </para> + <para> + The following tables show the possible values for <command>permission</command>, <command>action</command>, <command>object</command>, and <command>property</command> in an ACL rules file. + </para> + <table id="tabl-Messaging_User_Guide-ACL_Syntax-ACL_Rules_permission"> + <title>ACL Rules: permission</title> + <tgroup cols="2"> + <tbody> + <row> + <entry> + <command>allow</command> + </entry> + <entry> + <para> + Allow the action <!-- ### rule => the action --> + </para> + </entry> + </row> + <row> + <entry> + <command>allow-log</command> + </entry> + <entry> + <para> + Allow the action and log the action in the event log + </para> + </entry> + </row> + <row> + <entry> + <command>deny</command> + </entry> + <entry> + <para> + Deny the action + </para> + </entry> + </row> + <row> + <entry> + <command>deny-log</command> + </entry> + <entry> + <para> + Deny the action and log the action in the event log + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + <!-- Actions --> <table id="tabl-Messaging_User_Guide-ACL_Syntax-ACL_Rulesaction"> + <title>ACL Rules: action</title> + <tgroup cols="2"> + <tbody> + <row> + <entry> + <command>access</command> + </entry> + <entry> + <para> + Accessing or reading an object + </para> + </entry> + </row> + <row> + <entry> + <command>bind</command> + </entry> + <entry> + <para> + Associating a queue to an exchange with a routing key. + </para> + </entry> + </row> + <row> + <entry> + <command>consume</command> + </entry> + <entry> + <para> + Using an object + </para> + </entry> + </row> + <row> + <entry> + <command>create</command> + </entry> + <entry> + <para> + Creating an object. + </para> + </entry> + </row> + <row> + <entry> + <command>delete</command> + </entry> + <entry> + <para> + Deleting an object. + </para> + </entry> + </row> + <row> + <entry> + <command>move</command> + </entry> + <entry> + <para> + Moving messages between queues. + </para> + </entry> + </row> + <row> + <entry> + <command>publish</command> + </entry> + <entry> + <para> + Authenticating an incoming message. + </para> + </entry> + </row> + <row> + <entry> + <command>purge</command> + </entry> + <entry> + <para> + Purging a queue. + </para> + </entry> + </row> + <row> + <entry> + <command>redirect</command> + </entry> + <entry> + <para> + Redirecting messages between queues + </para> + </entry> + </row> + <row> + <entry> + <command>reroute</command> + </entry> + <entry> + <para> + Rerouting messages from a queue to an exchange + </para> + </entry> + </row> + <row> + <entry> + <command>unbind</command> + </entry> + <entry> + <para> + Disassociating a queue from an exchange with a routing key. + </para> + </entry> + </row> + <row> + <entry> + <command>update</command> + </entry> + <entry> + <para> + Changing a broker configuration setting. + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + <!-- object types --> <table id="tabl-Messaging_User_Guide-ACL_Syntax-ACL_Rulesobject"> + <title>ACL Rules:object</title> + <tgroup cols="2"> + <tbody> + <row> + <entry> + <command>broker</command> + </entry> + <entry> + <para> + </para> + </entry> + </row> + <row> + <entry> + <command>connection</command> + </entry> + <entry> + <para> + Incoming TCP/IP connection + </para> + </entry> + </row> + <row> + <entry> + <command>exchange</command> + </entry> + <entry> + <para> + </para> + </entry> + </row> + <row> + <entry> + <command>link</command> + </entry> + <entry> + <para> + A federation or inter-broker link + </para> + </entry> + </row> + <row> + <entry> + <command>method</command> + </entry> + <entry> + <para> + Management method + </para> + </entry> + </row> + <row> + <entry> + <command>query</command> + </entry> + <entry> + <para> + Management query of an object or class + </para> + </entry> + </row> + <row> + <entry> + <command>queue</command> + </entry> + <entry> + <para> + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + <!-- + <para> + Wild cards can be used on properties that are a string. The following rule properties are supported: --> + <table id="tabl-Messaging_User_Guide-ACL_Syntax-ACL_Rulesproperty"> + <title>ACL Rules: property</title> + <tgroup cols="4"> + <thead> + <row> + <entry>Property</entry> + <entry>Type</entry> + <entry>Description</entry> + <entry>Usage</entry> + </row> + </thead> + <tbody> + <row> + <entry> <command>name</command> </entry> + <entry>String</entry> + <entry>Rule refers to objects with this name. When 'name' is blank or absent then the rule + applies to all objects of the given type.</entry> + <entry></entry> + </row> + <row> + <entry> <command>alternate</command> </entry> + <entry>String</entry> + <entry>Name of an alternate exchange</entry> + <entry>CREATE QUEUE, CREATE EXCHANGE, ACCESS QUEUE, ACCESS EXCHANGE, DELETE QUEUE, DELETE EXCHANGE</entry> + </row> + <row> + <entry> <command>autodelete</command> </entry> + <entry>Boolean</entry> + <entry>Indicates whether or not the object gets deleted when the connection that created it is closed</entry> + <entry>CREATE QUEUE, CREATE EXCHANGE, ACCESS QUEUE, ACCESS EXCHANGE, DELETE QUEUE</entry> + </row> + <row> + <entry> <command>durable</command> </entry> + <entry>Boolean</entry> + <entry>Rule applies to durable objects</entry> + <entry>CREATE QUEUE, CREATE EXCHANGE, ACCESS QUEUE, ACCESS EXCHANGE, DELETE QUEUE, DELETE EXCHANGE</entry> + </row> + <row> + <entry> <command>exchangename</command> </entry> + <entry>String</entry> + <entry>Name of the exchange to which queue's entries are routed</entry> + <entry>REROUTE QUEUE</entry> + </row> + <row> + <entry> <command>filemaxcountlowerlimit</command> </entry> + <entry>Integer</entry> + <entry>Minimum value for file.max_count (files)</entry> + <entry>CREATE QUEUE</entry> + </row> + <row> + <entry> <command>filemaxcountupperlimit</command> </entry> + <entry>Integer</entry> + <entry>Maximum value for file.max_count (files)</entry> + <entry>CREATE QUEUE</entry> + </row> + <row> + <entry> <command>filemaxsizelowerlimit</command> </entry> + <entry>Integer</entry> + <entry>Minimum value for file.max_size (64kb pages)</entry> + <entry>CREATE QUEUE</entry> + </row> + <row> + <entry> <command>filemaxsizeupperlimit</command> </entry> + <entry>Integer</entry> + <entry>Maximum value for file.max_size (64kb pages)</entry> + <entry>CREATE QUEUE</entry> + </row> + <row> + <entry> <command>host</command> </entry> + <entry>String</entry> + <entry>Target TCP/IP host or host range for create connection rules</entry> + <entry>CREATE CONNECTION</entry> + </row> + <row> + <entry> <command>exclusive</command> </entry> + <entry>Boolean</entry> + <entry>Indicates the presence of an <parameter>exclusive</parameter> flag</entry> + <entry>CREATE QUEUE, ACCESS QUEUE, DELETE QUEUE</entry> + </row> + <row> + <entry> <command>pagefactorlowerlimit</command> </entry> + <entry>Integer</entry> + <entry>Minimum value for size of a page in paged queue</entry> + <entry>CREATE QUEUE</entry> + </row> + <row> + <entry> <command>pagefactorupperlimit</command> </entry> + <entry>Integer</entry> + <entry>Maximum value for size of a page in paged queue</entry> + <entry>CREATE QUEUE</entry> + </row> + <row> + <entry> <command>pageslowerlimit</command> </entry> + <entry>Integer</entry> + <entry>Minimum value for number of paged queue pages in memory</entry> + <entry>CREATE QUEUE</entry> + </row> + <row> + <entry> <command>pagesupperlimit</command> </entry> + <entry>Integer</entry> + <entry>Maximum value for number of paged queue pages in memory</entry> + <entry>CREATE QUEUE</entry> + </row> + <row> + <entry> <command>paging</command> </entry> + <entry>Boolean</entry> + <entry>Indicates if the queue is a paging queue</entry> + <entry>CREATE QUEUE</entry> + </row> + <row> + <entry> <command>policytype</command> </entry> + <entry>String</entry> + <entry>"ring", "self-destruct", "reject"</entry> + <entry>CREATE QUEUE, ACCESS QUEUE, DELETE QUEUE</entry> + </row> + <row> + <entry> <command>queuename</command> </entry> + <entry>String</entry> + <entry>Name of the target queue</entry> + <entry>ACCESS EXCHANGE, BIND EXCHANGE, MOVE QUEUE, UNBIND EXCHANGE</entry> + </row> + <row> + <entry> <command>queuemaxsizelowerlimit</command> </entry> + <entry>Integer</entry> + <entry>Minimum value for queue.max_size (memory bytes)</entry> + <entry>CREATE QUEUE, ACCESS QUEUE</entry> + </row> + <row> + <entry> <command>queuemaxsizeupperlimit</command> </entry> + <entry>Integer</entry> + <entry>Maximum value for queue.max_size (memory bytes)</entry> + <entry>CREATE QUEUE, ACCESS QUEUE</entry> + </row> + <row> + <entry> <command>queuemaxcountlowerlimit</command> </entry> + <entry>Integer</entry> + <entry>Minimum value for queue.max_count (messages)</entry> + <entry>CREATE QUEUE, ACCESS QUEUE</entry> + </row> + <row> + <entry> <command>queuemaxcountupperlimit</command> </entry> + <entry>Integer</entry> + <entry>Maximum value for queue.max_count (messages)</entry> + <entry>CREATE QUEUE, ACCESS QUEUE</entry> + </row> + <row> + <entry> <command>routingkey</command> </entry> + <entry>String</entry> + <entry>Specifies routing key</entry> + <entry>BIND EXCHANGE, UNBIND EXCHANGE, ACCESS EXCHANGE, PUBLISH EXCHANGE</entry> + </row> + <row> + <entry> <command>schemaclass</command> </entry> + <entry>String</entry> + <entry>QMF schema class name</entry> + <entry>ACCESS METHOD, ACCESS QUERY</entry> + </row> + <row> + <entry> <command>schemapackage</command> </entry> + <entry>String</entry> + <entry>QMF schema package name</entry> + <entry>ACCESS METHOD</entry> + </row> + <row> + <entry> <command>type</command> </entry> + <entry>String</entry> + <entry>Type of exchange, such as topic, fanout, or xml</entry> + <entry>CREATE EXCHANGE, ACCESS EXCHANGE, DELETE EXCHANGE</entry> + </row> + </tbody> + </tgroup> + </table> + + <section id="sect-Messaging_User_Guide-Authorization-ACL_ActionObjectPropertyTuples"> + <title>ACL Action-Object-Property Combinations</title> + <para> + Not every ACL action is applicable to every ACL object. Furthermore, not every property may be + specified for every action-object pair. The following table lists the broker events + that trigger ACL lookups. Then for each event it lists the action, object, and properties + allowed in the lookup. + </para> + <para> + User-specified ACL rules constrain property sets to those that match one or more of + the action and object pairs. For example these rules are allowed: + </para> +<programlisting> + acl allow all access exchange + acl allow all access exchange name=abc + acl allow all access exchange name=abc durable=true +</programlisting> + <para> + These rules could possibly match one or more of the broker lookups. However, this rule + is not allowed: + </para> +<programlisting> + acl allow all access exchange queuename=queue1 durable=true +</programlisting> + <para> + Properties <emphasis>queuename</emphasis> and <emphasis>durable</emphasis> + are not in the list of allowed properties for any 'access exchange' lookup. + This rule would never match a broker lookup query and would never contribute to an + allow or deny decision. + </para> + <para> + For more information about matching ACL rules please refer to + <link linkend="sect-Messaging_User_Guide-Authorization-ACL_Rule_Matching"> + ACL Rule Matching + </link> + </para> + + <table id="tabl-Messaging_User_Guide-ACL_Syntax-ACL_ActionObject_properties"> + <title>Broker Lookup Events With Allowed Action, Object, and Properties</title> + <tgroup cols="4"> + <thead> + <row> + <entry>Lookup Event</entry> + <entry>Action</entry> + <entry>Object</entry> + <entry>Properties</entry> + </row> + </thead> + <tbody> + <row> + <entry>User querying message timestamp setting </entry> + <entry>access</entry> + <entry>broker</entry> + <entry></entry> + </row> + <row> + <entry>AMQP 0-10 protocol received 'query' </entry> + <entry>access</entry> + <entry>exchange</entry> + <entry>name </entry> + </row> + <row> + <entry>AMQP 0-10 query binding </entry> + <entry>access</entry> + <entry>exchange</entry> + <entry>name queuename routingkey </entry> + </row> + <row> + <entry>AMQP 0-10 exchange declare </entry> + <entry>access</entry> + <entry>exchange</entry> + <entry>name type alternate durable autodelete </entry> + </row> + <row> + <entry>AMQP 1.0 exchange access </entry> + <entry>access</entry> + <entry>exchange</entry> + <entry>name type durable </entry> + </row> + <row> + <entry>AMQP 1.0 node resolution </entry> + <entry>access</entry> + <entry>exchange</entry> + <entry>name </entry> + </row> + <row> + <entry>Management method request </entry> + <entry>access</entry> + <entry>method</entry> + <entry>name schemapackage schemaclass </entry> + </row> + <row> + <entry>Management agent method request </entry> + <entry>access</entry> + <entry>method</entry> + <entry>name schemapackage schemaclass </entry> + </row> + <row> + <entry>Management agent query </entry> + <entry>access</entry> + <entry>query</entry> + <entry>name schemaclass </entry> + </row> + <row> + <entry>QMF 'query queue' method </entry> + <entry>access</entry> + <entry>queue</entry> + <entry>name </entry> + </row> + <row> + <entry>AMQP 0-10 query </entry> + <entry>access</entry> + <entry>queue</entry> + <entry>name </entry> + </row> + <row> + <entry>AMQP 0-10 queue declare </entry> + <entry>access</entry> + <entry>queue</entry> + <entry>name alternate durable exclusive autodelete policytype queuemaxcountlowerlimit queuemaxcountupperlimit queuemaxsizelowerlimit queuemaxsizeupperlimit </entry> + </row> + <row> + <entry>AMQP 1.0 queue access </entry> + <entry>access</entry> + <entry>queue</entry> + <entry>name alternate durable exclusive autodelete policytype queuemaxcountlowerlimit queuemaxcountupperlimit queuemaxsizelowerlimit queuemaxsizeupperlimit </entry> + </row> + <row> + <entry>AMQP 1.0 node resolution </entry> + <entry>access</entry> + <entry>queue</entry> + <entry>name </entry> + </row> + <row> + <entry>AMQP 0-10 or QMF bind request </entry> + <entry>bind</entry> + <entry>exchange</entry> + <entry>name queuename routingkey </entry> + </row> + <row> + <entry>AMQP 1.0 new outgoing link from exchange</entry> + <entry>bind</entry> + <entry>exchange</entry> + <entry>name queuename routingkey </entry> + </row> + <row> + <entry>AMQP 0-10 subscribe request </entry> + <entry>consume</entry> + <entry>queue</entry> + <entry>name </entry> + </row> + <row> + <entry>AMQP 1.0 new outgoing link from queue </entry> + <entry>consume</entry> + <entry>queue</entry> + <entry>name </entry> + </row> + <row> + <entry>TCP/IP connection creation </entry> + <entry>create</entry> + <entry>connection</entry> + <entry>host </entry> + </row> + <row> + <entry>Create exchange </entry> + <entry>create</entry> + <entry>exchange</entry> + <entry>name type alternate durable autodelete </entry> + </row> + <row> + <entry>Interbroker link creation </entry> + <entry>create</entry> + <entry>link</entry> + <entry></entry> + </row> + <row> + <entry>Interbroker link creation </entry> + <entry>create</entry> + <entry>link</entry> + <entry></entry> + </row> + <row> + <entry>Create queue </entry> + <entry>create</entry> + <entry>queue</entry> + <entry>name alternate durable exclusive autodelete policytype paging pageslowerlimit pagesupperlimit pagefactorlowerlimit pagefactorupperlimit queuemaxcountlowerlimit queuemaxcountupperlimit queuemaxsizelowerlimit queuemaxsizeupperlimit filemaxcountlowerlimit filemaxcountupperlimit filemaxsizelowerlimit filemaxsizeupperlimit </entry> + </row> + <row> + <entry>Delete exchange </entry> + <entry>delete</entry> + <entry>exchange</entry> + <entry>name type alternate durable </entry> + </row> + <row> + <entry>Delete queue </entry> + <entry>delete</entry> + <entry>queue</entry> + <entry>name alternate durable exclusive autodelete policytype </entry> + </row> + <row> + <entry>Management 'move queue' request </entry> + <entry>move</entry> + <entry>queue</entry> + <entry>name queuename </entry> + </row> + <row> + <entry>AMQP 0-10 received message processing </entry> + <entry>publish</entry> + <entry>exchange</entry> + <entry>name routingkey </entry> + </row> + <row> + <entry>AMQP 1.0 establish sender link to queue </entry> + <entry>publish</entry> + <entry>exchange</entry> + <entry>routingkey </entry> + </row> + <row> + <entry>AMQP 1.0 received message processing </entry> + <entry>publish</entry> + <entry>exchange</entry> + <entry>name routingkey </entry> + </row> + <row> + <entry>Management 'purge queue' request </entry> + <entry>purge</entry> + <entry>queue</entry> + <entry>name </entry> + </row> + <row> + <entry>Management 'purge queue' request </entry> + <entry>purge</entry> + <entry>queue</entry> + <entry>name </entry> + </row> + <row> + <entry>Management 'redirect queue' request </entry> + <entry>redirect</entry> + <entry>queue</entry> + <entry>name queuename </entry> + </row> + <row> + <entry>Management 'reroute queue' request </entry> + <entry>reroute</entry> + <entry>queue</entry> + <entry>name exchangename </entry> + </row> + <row> + <entry>Management 'unbind exchange' request </entry> + <entry>unbind</entry> + <entry>exchange</entry> + <entry>name queuename routingkey </entry> + </row> + <row> + <entry>User modifying message timestamp setting</entry> + <entry>update</entry> + <entry>broker</entry> + <entry></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + </section> + + <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions"> + <title>ACL Syntactic Conventions</title> + <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-comments"> + <title>Comments</title> + <para> + <itemizedlist> + <listitem> + <para> + A line starting with the <command>#</command> character is considered a comment and is ignored. + </para> + </listitem> + <listitem> + <para> + Embedded comments and trailing comments are not allowed. The <command>#</command> is commonly found in routing keys and other AMQP literals which occur naturally in ACL rule specifications. + </para> + </listitem> + </itemizedlist> + </para> + </section> + <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-whitespace"> + <title>White Space</title> + <itemizedlist> + <listitem> + <para> + Empty lines and lines that contain only whitespace (' ', '\f', '\n', '\r', '\t', '\v') are ignored. + </para> + </listitem> + <listitem> + <para> + Additional whitespace between and after tokens is allowed. + </para> + </listitem> + <listitem> + <para> + Group and Acl definitions must start with <command>group</command> and <command>acl</command> respectively and with no preceding whitespace. + </para> + </listitem> + </itemizedlist> + </section> + <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-characterset"> + <title>Character Set</title> + <itemizedlist> + <listitem> + <para> + ACL files use 7-bit ASCII characters only + </para> + </listitem> + <listitem> + <para> + Group names may contain only + <itemizedlist> + <listitem><command>[a-z]</command></listitem> + <listitem><command>[A-Z]</command></listitem> + <listitem><command>[0-9]</command></listitem> + <listitem><command>'-'</command> hyphen</listitem> + <listitem><command>'_'</command> underscore</listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + Individual user names may contain only + <itemizedlist> + <listitem><command>[a-z]</command></listitem> + <listitem><command>[A-Z]</command></listitem> + <listitem><command>[0-9]</command></listitem> + <listitem><command>'-'</command> hyphen</listitem> + <listitem><command>'_'</command> underscore</listitem> + <listitem><command>'.'</command> period</listitem> + <listitem><command>'@'</command> ampersand</listitem> + <listitem><command>'/'</command> slash</listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + </section> + <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-casesensitivity"> + <title>Case Sensitivity</title> + <itemizedlist> + <listitem> + <para> + All tokens are case sensitive. <parameter>name1</parameter> is not the same as <parameter>Name1</parameter> and <parameter>create</parameter> is not the same as <parameter>CREATE</parameter>. + </para> + </listitem> + </itemizedlist> + </section> + <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-linecontinuation"> + <title>Line Continuation</title> + <itemizedlist> + <listitem> + <para> + Group lists can be extended to the following line by terminating the line with the <command>'\'</command> character. No other ACL file lines may be continued. + </para> + </listitem> + <listitem> + <para> + Group specification lines may be continued only after the group name or any of the user names included in the group. See example below. + </para> + </listitem> + <listitem> + <para> + Lines consisting solely of a <command>'\'</command> character are not permitted. + </para> + </listitem> + <listitem> + <para> + The <command>'\'</command> continuation character is recognized only if it is the last character in the line. Any characters after the <command>'\'</command> are not permitted. + </para> + </listitem> + </itemizedlist> +<programlisting><![CDATA[ + # + # Examples of extending group lists using a trailing '\' character + # + group group1 name1 name2 \ + name3 name4 \ + name5 + + group group2 \ + group1 \ + name6 + # + # The following are illegal: + # + # '\' must be after group name + # + group \ + group3 name7 name8 + # + # No empty extension line + # + group group4 name9 \ + \ + name10 +]]></programlisting> + + </section> + <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-linelength"> + <title>Line Length</title> + <itemizedlist> + <listitem> + <para> + ACL file lines are limited to 1024 characters. + </para> + </listitem> + </itemizedlist> + </section> + + + <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-keywords"> + <title>ACL File Keywords</title> + ACL reserves several words for convenience and for context sensitive substitution. + + <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-keywords-all"> + <title>The <command>all</command> Keyword</title> + The keyword <command>all</command> is reserved. It may be used in ACL rules to match all individuals and groups, all actions, or all objects. + <itemizedlist> + <listitem>acl allow all create queue</listitem> + <listitem>acl allow bob@QPID all queue</listitem> + <listitem>acl allow bob@QPID create all</listitem> + </itemizedlist> + </section> + + <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-keywords-userdomain"> + <title>User Name and Domain Name Keywords</title> + <para> + In the C++ Broker 0.20 a simple set of user name and domain name substitution variable keyword tokens is defined. This provides administrators with an easy way to describe private or shared resources. + </para> + <para> + Symbol substitution is allowed in the ACL file anywhere that text is supplied for a property value. + </para> + <para> + In the following table an authenticated user named bob.user@QPID.COM has his substitution keywords expanded. + + <table id="tabl-Messaging_User_Guide-ACL_Syntax-ACL_UsernameSubstitution"> + <title>ACL User Name and Domain Name Substitution Keywords</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Keyword</entry> + <entry>Expansion</entry> + </row> + </thead> + <tbody> + <row> + <entry> <command>${userdomain}</command> </entry> + <entry>bob_user_QPID_COM</entry> + </row> + <row> + <entry> <command>${user}</command> </entry> + <entry>bob_user</entry> + </row> + <row> + <entry> <command>${domain}</command> </entry> + <entry>QPID_COM</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + + <para> + <itemizedlist> + <listitem> + The original user name has the period “.” and ampersand “@” characters translated into underscore “_”. This allows substitution to work when the substitution keyword is used in a routingkey in the Acl file. + </listitem> + <listitem> + The Acl processing matches ${userdomain} before matching either ${user} or ${domain}. Rules that specify the combination ${user}_${domain} will never match. + </listitem> + </itemizedlist> + </para> + +<programlisting><![CDATA[ + # Example: + # + # Administrators can set up Acl rule files that allow every user to create a + # private exchange, a private queue, and a private binding between them. + # In this example the users are also allowed to create private backup exchanges, + # queues and bindings. This effectively provides limits to user's exchange, + # queue, and binding creation and guarantees that each user gets exclusive + # access to these resources. + # + # + # Create primary queue and exchange: + # + acl allow all create queue name=$\{user}-work alternate=$\{user}-work2 + acl deny all create queue name=$\{user}-work alternate=* + acl allow all create queue name=$\{user}-work + acl allow all create exchange name=$\{user}-work alternate=$\{user}-work2 + acl deny all create exchange name=$\{user}-work alternate=* + acl allow all create exchange name=$\{user}-work + # + # Create backup queue and exchange + # + acl deny all create queue name=$\{user}-work2 alternate=* + acl allow all create queue name=$\{user}-work2 + acl deny all create exchange name=$\{user}-work2 alternate=* + acl allow all create exchange name=$\{user}-work2 + # + # Bind/unbind primary exchange + # + acl allow all bind exchange name=$\{user}-work routingkey=$\{user} queuename=$\{user}-work + acl allow all unbind exchange name=$\{user}-work routingkey=$\{user} queuename=$\{user}-work + # + # Bind/unbind backup exchange + # + acl allow all bind exchange name=$\{user}-work2 routingkey=$\{user} queuename=$\{user}-work2 + acl allow all unbind exchange name=$\{user}-work2 routingkey=$\{user} queuename=$\{user}-work2 + # + # Access primary exchange + # + acl allow all access exchange name=$\{user}-work routingkey=$\{user} queuename=$\{user}-work + # + # Access backup exchange + # + acl allow all access exchange name=$\{user}-work2 routingkey=$\{user} queuename=$\{user}-work2 + # + # Publish primary exchange + # + acl allow all publish exchange name=$\{user}-work routingkey=$\{user} + # + # Publish backup exchange + # + acl allow all publish exchange name=$\{user}-work2 routingkey=$\{user} + # + # deny mode + # + acl deny all all +]]></programlisting> + </section> + + </section> + + <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntatic_Conventions-wildcards"> + <title>Wildcards</title> + ACL privides two types of wildcard matching to provide flexibility in writing rules. + + <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntatic_Conventions-wildcards-asterisk"> + <title>Property Value Wildcard</title> + <para> + Text specifying a property value may end with a single trailing <command>*</command> character. + This is a simple wildcard match indicating that strings which match up to that point are matches for the ACL property rule. + An ACL rule such as + </para> + <para> + <programlisting> acl allow bob@QPID create queue name=bob*</programlisting> + </para> + <para> + allow user bob@QPID to create queues named bob1, bob2, bobQueue3, and so on. + </para> + </section> + + <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntatic_Conventions-wildcards-topickey"> + <title>Topic Routing Key Wildcard</title> + <para> + In the C++ Broker 0.20 the logic governing the ACL Match has changed for each ACL rule that contains a routingkey property. + The routingkey property is matched according to Topic Exchange match logic the broker uses when it distributes messages published to a topic exchange. + </para> + <para> + Routing keys are hierarchical where each level is separated by a period: + <itemizedlist> + <listitem>weather.usa</listitem> + <listitem>weather.europe.germany</listitem> + <listitem>weather.europe.germany.berlin</listitem> + <listitem>company.engineering.repository</listitem> + </itemizedlist> + </para> + <para> + Within the routing key hierarchy two wildcard characters are defined. + <itemizedlist> + <listitem><command>*</command> matches one field</listitem> + <listitem><command>#</command> matches zero or more fields</listitem> + </itemizedlist> + </para> + <para> + Suppose an ACL rule file is: + </para> + <para> + <programlisting> + acl allow-log uHash1@COMPANY publish exchange name=X routingkey=a.#.b + acl deny all all + </programlisting> + </para> + <para> + When user uHash1@COMPANY attempts to publish to exchange X the ACL will return these results: + + <table id="tabl-Messaging_User_Guide-ACL_Syntax-ACL_TopicExchangeMatch"> + <title>Topic Exchange Wildcard Match Examples</title> + <tgroup cols="2"> + <thead> + <row> + <entry>routingkey in publish to exchange X</entry> + <entry>result</entry> + </row> + </thead> + <tbody> + <row> + <entry> <command>a.b</command> </entry> + <entry>allow-log</entry> + </row> + <row> + <entry> <command>a.x.b</command> </entry> + <entry>allow-log</entry> + </row> + <row> + <entry> <command>a.x.y.zz.b</command> </entry> + <entry>allow-log</entry> + </row> + <row> + <entry> <command>a.b.</command> </entry> + <entry>deny</entry> + </row> + <row> + <entry> <command>q.x.b</command> </entry> + <entry>deny</entry> + </row> + </tbody> + </tgroup> + </table> + + </para> + </section> + + </section> + + + + </section> + + <section id="sect-Messaging_User_Guide-Authorization-ACL_Rule_Matching"> + <title>ACL Rule Matching</title> + <para> + The minimum matching criteria for ACL rules are: + <itemizedlist> + <listitem>An actor (individually named or group member)</listitem> + <listitem>An action</listitem> + <listitem>An object</listitem> + </itemizedlist> + </para> + <para> + If a rule does not match the minimum criteria then that rule does not control the ACL allow or deny decision. + </para> + <para> + ACL rules optionally specify object names and property name=value pairs. If an ACL rule specifies an object name or property values than all of them must match to cause the rule to match. + </para> + <para> + The following illustration shows how ACL rules are processed to find matching rules. +<programlisting><![CDATA[ + # Example of rule matching + # + # Using this ACL file content: + + (1) acl deny bob create exchange name=test durable=true passive=true + (2) acl deny bob create exchange name=myEx type=direct + (3) acl allow all all + + # + # Lookup 1. id:bob action:create objectType:exchange name=test + # {durable=false passive=false type=direct alternate=} + # + # ACL Match Processing: + # 1. Rule 1 passes minimum criteria with user bob, action create, + # and object exchange. + # 2. Rule 1 matches name=test. + # 3. Rule 1 does not match the rule's durable=true with the requested + # lookup of durable=false. + # 4. Rule 1 does not control the decision and processing continues + # to Rule 2. + # 5. Rule 2 passes minimum criteria with user bob, action create, + # and object exchange. + # 6. Rule 2 does not match the rule's name=myEx with the requested + # lookup of name=test. + # 7. Rule 2 does not control the decision and processing continues + # to Rule 3. + # 8. Rule 3 matches everything and the decision is 'allow'. + # + # Lookup 2. id:bob action:create objectType:exchange name=myEx + # {durable=true passive=true type=direct alternate=} + # + # ACL Match Processing: + # 1. Rule 1 passes minimum criteria with user bob, action create, + # and object exchange. + # 2. Rule 1 does not match the rule's name=test with the requested + # lookup of name=myEx. + # 3. Rule 1 does not control the decision and processing continues + # to Rule 2. + # 4. Rule 2 passes minimum criteria with user bob, action create, + # and object exchange. + # 5. Rule 2 matches name=myEx. + # 6. Rule 2 matches the rule's type=direct with the requested + # lookup of type=direct. + # 7. Rule 2 is the matching rule and the decision is 'deny'. + # +]]></programlisting> + </para> + <para> + Referring to <link linkend="tabl-Messaging_User_Guide-ACL_Syntax-ACL_ActionObject_properties">ACL Properties Allowed for each Action and Object table</link> observe that some Action/Object pairs have different sets of allowed properties. For example different broker ACL lookups for <emphasis>access exchange</emphasis> have different property subsets. + </para> + +<programlisting> + [1] access exchange name + [2] access exchange name type alternate durable autodelete + [3] access exchange name queuename routingkey + [4] access exchange name type durable +</programlisting> + + <para> + If an ACL rule specifies the <emphasis>autodelete</emphasis> property then it can possibly match only the second case above. It can never match cases 1, 3, and 4 because the broker calls to ACL will not present the autodelete property for matching. To get proper matching the ACL rule must have only the properties of the intended lookup case. + </para> + +<programlisting> + acl allow bob access exchange alternate=other ! may match pattern 2 only + acl allow bob access exchange queuename=other ! may match pattern 3 only + acl allow bob access exchange durable=true ! may match patterns 2 and 4 only + acl deny bob access exchange ! may match all patterns +</programlisting> + + </section> + + <section id="sect-Messaging_User_Guide-Authorization-Specifying_ACL_Permissions"> + <title>Specifying ACL Permissions</title> + <para> + Now that we have seen the ACL syntax, we will provide representative examples and guidelines for ACL files. + </para> + <para> + Most ACL files begin by defining groups: + </para> + +<programlisting> + group admin ted@QPID martin@QPID + group user-consume martin@QPID ted@QPID + group group2 kim@QPID user-consume rob@QPID + group publisher group2 \ + tom@QPID andrew@QPID debbie@QPID +</programlisting> + <para> + Rules in an ACL file grant or deny specific permissions to users or groups: + </para> + +<programlisting> + acl allow carlt@QPID create exchange name=carl.* + acl allow rob@QPID create queue + acl allow guest@QPID bind exchange name=amq.topic routingkey=stocks.rht.# + acl allow user-consume create queue name=tmp.* + + acl allow publisher publish all durable=false + acl allow publisher create queue name=RequestQueue + acl allow consumer consume queue durable=true + acl allow fred@QPID create all + acl allow bob@QPID all queue + acl allow admin all + acl allow all consume queue + acl allow all bind exchange + acl deny all all +</programlisting> + <para> + In the previous example, the last line, <literal>acl deny all all</literal>, denies all authorizations that have not been specifically granted. This is the default, but it is useful to include it explicitly on the last line for the sake of clarity. If you want to grant all rights by default, you can specify <literal>acl allow all all</literal> in the last line. + </para> + <para> + ACL allows specification of conflicting rules. Be sure to specify the most specific rules first followed by more general rules. Here is an example: + </para> + <para> +<programlisting> + group users alice@QPID bob@QPID charlie@QPID + acl deny charlie@QPID create queue + acl allow users create queue + acl deny all all +</programlisting> + </para> + <para> + In this example users alice and bob would be able to create queues due to their membership in the users group. However, user charlie is denied from creating a queue despite his membership in the users group because a deny rule for him is stated before the allow rule for the users group. + </para> + <para> + Do not allow <parameter>guest</parameter> to access and log QMF management methods that could cause security breaches: + </para> + +<programlisting> + group allUsers guest@QPID + ... + acl deny-log allUsers create link + acl deny-log allUsers access method name=connect + acl deny-log allUsers access method name=echo + acl allow all all +</programlisting> + + </section> + <section id="sect-Messaging_User_Guide-Authorization-Auditing_ACL_Settings"> + <title>Auditing ACL Settings</title> + <para> + The 0.30 C++ Broker ACL module provides a comprehensive set of run-time and debug logging checks. + The following example ACL file is used to illustrate working with the ACL module debugging features. + </para> +<programlisting> + group x a@QPID b@QPID b2@QPID b3@QPID + acl allow all delete broker + acl allow all create queue name=abc + acl allow all create queue exchangename=xyz + acl allow all create connection host=1.1.1.1 + acl allow all access exchange alternate=abc queuename=xyz + acl allow all access exchange queuename=xyz + acl allow all access exchange alternate=abc + acl allow a@qpid all all exchangename=123 + acl allow b@qpid all all + acl allow all all +</programlisting> + <para> + When this file is loaded it will show the following (truncated, formatted) Info-level log. + </para> +<programlisting> + notice ACL: Read file "/home/chug/acl/svn-acl.acl" + warning ACL rule ignored: Broker never checks for rules with + action: 'delete' and object: 'broker' + warning ACL rule ignored: Broker checks for rules with + action: 'create' and object: 'queue' + but will never match with property set: { exchangename=xyz } + warning ACL rule ignored: Broker checks for rules with + action: 'access' and object: 'exchange' + but will never match with property set: { alternate=abc queuename=xyz } + info ACL Plugin loaded +</programlisting> + <para> + Three of the rules are invalid. The first invalid rule is rejected because there are no rules + that specify 'delete broker' regardless of the properties. The other two rules are rejected + because the property sets in the ACL rule don't match any broker lookups. + </para> + <para> + The ACL module only issues a warning about these rules and continues to operate. Users upgrading + from previous versions should be concerned that these rules never had any effect and should fix + the rules to have the property sets needed to allow or deny the intended broker events. + </para> + <para> + The next illustration shows the Debug-level log. Debug log level includes information about + constructing the rule tables, expanding groups and keywords, connection and queue quotas, and + connection black and white lists. + </para> +<programlisting> + notice ACL: Read file "/home/chug/acl/svn-acl.acl" + debug ACL: Group list: 1 groups found: + debug ACL: "x": a@QPID b2@QPID b3@QPID b@QPID + debug ACL: name list: 7 names found: + debug ACL: * a@QPID a@qpid b2@QPID b3@QPID b@QPID b@qpid + debug ACL: Rule list: 10 ACL rules found: + debug ACL: 1 allow [*] delete broker + warning ACL rule ignored: Broker never checks for rules with + action: 'delete' and object: 'broker' + debug ACL: 2 allow [*] create queue name=abc + debug ACL: 3 allow [*] create queue exchangename=xyz + warning ACL rule ignored: Broker checks for rules with + action: 'create' and object: 'queue' + but will never match with property set: { exchangename=xyz } + debug ACL: 4 allow [*] create connection host=1.1.1.1 + debug ACL: 5 allow [*] access exchange alternate=abc queuename=xyz + warning ACL rule ignored: Broker checks for rules with + action: 'access' and object: 'exchange' + but will never match with property set: { alternate=abc queuename=xyz } + debug ACL: 6 allow [*] access exchange queuename=xyz + debug ACL: 7 allow [*] access exchange alternate=abc + debug ACL: 8 allow [a@qpid] * * exchangename=123 + debug ACL: 9 allow [b@qpid] * * + debug ACL: 10 allow [*] * + debug ACL: connections quota: 0 rules found: + debug ACL: queues quota: 0 rules found: + debug ACL: Load Rules + debug ACL: Processing 10 allow [*] * + debug ACL: FoundMode allow + debug ACL: Processing 9 allow [b@qpid] * * + debug ACL: Adding actions {access,bind,consume,create,delete,move,publish,purge, + redirect,reroute,unbind,update} + to objects {broker,connection,exchange,link,method,query,queue} + with props { } + for users {b@qpid} + debug ACL: Processing 8 allow [a@qpid] * * exchangename=123 + debug ACL: Adding actions {access,bind,consume,create,delete,move,publish,purge, + redirect,reroute,unbind,update} + to objects {broker,connection,exchange,link,method,query,queue} + with props { exchangename=123 } + for users {a@qpid} + debug ACL: Processing 7 allow [*] access exchange alternate=abc + debug ACL: Adding actions {access} + to objects {exchange} + with props { alternate=abc } + for users {*,a@QPID,a@qpid,b2@QPID,b3@QPID,b@QPID,b@qpid} + debug ACL: Processing 6 allow [*] access exchange queuename=xyz + debug ACL: Adding actions {access} + to objects {exchange} + with props { queuename=xyz } + for users {*,a@QPID,a@qpid,b2@QPID,b3@QPID,b@QPID,b@qpid} + debug ACL: Processing 5 allow [*] access exchange alternate=abc queuename=xyz + debug ACL: Processing 4 allow [*] create connection host=1.1.1.1 + debug ACL: Processing 3 allow [*] create queue exchangename=xyz + debug ACL: Processing 2 allow [*] create queue name=abc + debug ACL: Adding actions {create} + to objects {queue} + with props { name=abc } + for users {*,a@QPID,a@qpid,b2@QPID,b3@QPID,b@QPID,b@qpid} + debug ACL: Processing 1 allow [*] delete broker + debug ACL: global Connection Rule list : 1 rules found : + debug ACL: 1 [ruleMode = allow {(1.1.1.1,1.1.1.1)} + debug ACL: User Connection Rule lists : 0 user lists found : + debug ACL: Transfer ACL is Enabled! + info ACL Plugin loaded +</programlisting> + <para> + The previous illustration is interesting because it shows the settings as the <emphasis>all</emphasis> keywords are + being expanded. However, that does not show the information about what is actually going into the ACL lookup tables. + </para> + <para> + The next two illustrations show additional information provided by Trace-level logs for ACL startup. + The first shows a dump of the broker's internal + action/object/properties table. This table is authoratative. + </para> +<programlisting> + trace ACL: Definitions of action, object, (allowed properties) lookups + trace ACL: Lookup 1: "User querying message timestamp setting " + access broker () + trace ACL: Lookup 2: "AMQP 0-10 protocol received 'query' " + access exchange (name) + trace ACL: Lookup 3: "AMQP 0-10 query binding " + access exchange (name,routingkey,queuename) + trace ACL: Lookup 4: "AMQP 0-10 exchange declare " + access exchange (name,durable,autodelete,type,alternate) + trace ACL: Lookup 5: "AMQP 1.0 exchange access " + access exchange (name,durable,type) + trace ACL: Lookup 6: "AMQP 1.0 node resolution " + access exchange (name) + trace ACL: Lookup 7: "Management method request " + access method (name,schemapackage,schemaclass) + trace ACL: Lookup 8: "Management agent method request " + access method (name,schemapackage,schemaclass) + trace ACL: Lookup 9: "Management agent query " + access query (name,schemaclass) + trace ACL: Lookup 10: "QMF 'query queue' method " + access queue (name) + trace ACL: Lookup 11: "AMQP 0-10 query " + access queue (name) + trace ACL: Lookup 12: "AMQP 0-10 queue declare " + access queue (name,durable,autodelete,exclusive,alternate, + policytype,queuemaxsizelowerlimit,queuemaxsizeupperlimit, + queuemaxcountlowerlimit,queuemaxcountupperlimit) + trace ACL: Lookup 13: "AMQP 1.0 queue access " + access queue (name,durable,autodelete,exclusive,alternate, + policytype,queuemaxsizelowerlimit,queuemaxsizeupperlimit, + queuemaxcountlowerlimit,queuemaxcountupperlimit) + trace ACL: Lookup 14: "AMQP 1.0 node resolution " + access queue (name) + trace ACL: Lookup 15: "AMQP 0-10 or QMF bind request " + bind exchange (name,routingkey,queuename) + trace ACL: Lookup 16: "AMQP 1.0 new outgoing link from exchange " + bind exchange (name,routingkey,queuename) + trace ACL: Lookup 17: "AMQP 0-10 subscribe request " + consume queue (name) + trace ACL: Lookup 18: "AMQP 1.0 new outgoing link from queue " + consume queue (name) + trace ACL: Lookup 19: "TCP/IP connection creation " + create connection (host) + trace ACL: Lookup 20: "Create exchange " + create exchange (name,durable,autodelete,type,alternate) + trace ACL: Lookup 21: "Interbroker link creation " + create link () + trace ACL: Lookup 22: "Interbroker link creation " + create link () + trace ACL: Lookup 23: "Create queue " + create queue (name,durable,autodelete,exclusive, + alternate,policytype,paging, + queuemaxsizelowerlimit,queuemaxsizeupperlimit, + queuemaxcountlowerlimit,queuemaxcountupperlimit, + filemaxsizelowerlimit,filemaxsizeupperlimit, + filemaxcountlowerlimit,filemaxcountupperlimit, + pageslowerlimit,pagesupperlimit, + pagefactorlowerlimit,pagefactorupperlimit) + trace ACL: Lookup 24: "Delete exchange " + delete exchange (name,durable,type,alternate) + trace ACL: Lookup 25: "Delete queue " + delete queue (name,durable,autodelete,exclusive, + alternate,policytype) + trace ACL: Lookup 26: "Management 'move queue' request " + move queue (name,queuename) + trace ACL: Lookup 27: "AMQP 0-10 received message processing " + publish exchange (name,routingkey) + trace ACL: Lookup 28: "AMQP 1.0 establish sender link to queue " + publish exchange (routingkey) + trace ACL: Lookup 29: "AMQP 1.0 received message processing " + publish exchange (name,routingkey) + trace ACL: Lookup 30: "Management 'purge queue' request " + purge queue (name) + trace ACL: Lookup 31: "Management 'purge queue' request " + purge queue (name) + trace ACL: Lookup 32: "Management 'redirect queue' request " + redirect queue (name,queuename) + trace ACL: Lookup 33: "Management 'reroute queue' request " + reroute queue (name,exchangename) + trace ACL: Lookup 34: "Management 'unbind exchange' request " + unbind exchange (name,routingkey,queuename) + trace ACL: Lookup 35: "User modifying message timestamp setting " + update broker () +</programlisting> + <para> + The final illustration shows a dump of every rule for every user in the ACL database. + It includes the user name, action, object, original ACL rule number, allow or deny status, + and a cross reference indicating which Lookup Events the rule could possibly satisfy. + </para> + <para> + Note that rules identified by <emphasis>User: *</emphasis> are the rules in effect + for users otherwise unnamed in the ACL file. + </para> + +<programlisting> + trace ACL: Decision rule cross reference + trace ACL: User: b@qpid access broker + Rule: [rule 9 ruleMode = allow props{ }] + may match Lookups : (1) + trace ACL: User: * access exchange + Rule: [rule 6 ruleMode = allow props{ queuename=xyz }] + may match Lookups : (3) + trace ACL: User: * access exchange + Rule: [rule 7 ruleMode = allow props{ alternate=abc }] + may match Lookups : (4) + trace ACL: User: a@QPID access exchange + Rule: [rule 6 ruleMode = allow props{ queuename=xyz }] + may match Lookups : (3) + trace ACL: User: a@QPID access exchange + Rule: [rule 7 ruleMode = allow props{ alternate=abc }] + may match Lookups : (4) + trace ACL: User: a@qpid access exchange + Rule: [rule 6 ruleMode = allow props{ queuename=xyz }] + may match Lookups : (3) + trace ACL: User: a@qpid access exchange + Rule: [rule 7 ruleMode = allow props{ alternate=abc }] + may match Lookups : (4) + trace ACL: User: b2@QPID access exchange + Rule: [rule 6 ruleMode = allow props{ queuename=xyz }] + may match Lookups : (3) + trace ACL: User: b2@QPID access exchange + Rule: [rule 7 ruleMode = allow props{ alternate=abc }] + may match Lookups : (4) + trace ACL: User: b3@QPID access exchange + Rule: [rule 6 ruleMode = allow props{ queuename=xyz }] + may match Lookups : (3) + trace ACL: User: b3@QPID access exchange + Rule: [rule 7 ruleMode = allow props{ alternate=abc }] + may match Lookups : (4) + trace ACL: User: b@QPID access exchange + Rule: [rule 6 ruleMode = allow props{ queuename=xyz }] + may match Lookups : (3) + trace ACL: User: b@QPID access exchange + Rule: [rule 7 ruleMode = allow props{ alternate=abc }] + may match Lookups : (4) + trace ACL: User: b@qpid access exchange + Rule: [rule 6 ruleMode = allow props{ queuename=xyz }] + may match Lookups : (3) + trace ACL: User: b@qpid access exchange + Rule: [rule 7 ruleMode = allow props{ alternate=abc }] + may match Lookups : (4) + trace ACL: User: b@qpid access exchange + Rule: [rule 9 ruleMode = allow props{ }] + may match Lookups : (2,3,4,5,6) + trace ACL: User: b@qpid access method + Rule: [rule 9 ruleMode = allow props{ }] + may match Lookups : (7,8) + trace ACL: User: b@qpid access query + Rule: [rule 9 ruleMode = allow props{ }] + may match Lookups : (9) + trace ACL: User: b@qpid access queue + Rule: [rule 9 ruleMode = allow props{ }] + may match Lookups : (10,11,12,13,14) + trace ACL: User: b@qpid bind exchange + Rule: [rule 9 ruleMode = allow props{ }] + may match Lookups : (15,16) + trace ACL: User: b@qpid consume queue + Rule: [rule 9 ruleMode = allow props{ }] + may match Lookups : (17,18) + trace ACL: User: b@qpid create connection + Rule: [rule 9 ruleMode = allow props{ }] + may match Lookups : (19) + trace ACL: User: b@qpid create exchange + Rule: [rule 9 ruleMode = allow props{ }] + may match Lookups : (20) + trace ACL: User: b@qpid create link + Rule: [rule 9 ruleMode = allow props{ }] + may match Lookups : (21,22) + trace ACL: User: * create queue + Rule: [rule 2 ruleMode = allow props{ name=abc }] + may match Lookups : (23) + trace ACL: User: a@QPID create queue + Rule: [rule 2 ruleMode = allow props{ name=abc }] + may match Lookups : (23) + trace ACL: User: a@qpid create queue + Rule: [rule 2 ruleMode = allow props{ name=abc }] + may match Lookups : (23) + trace ACL: User: b2@QPID create queue + Rule: [rule 2 ruleMode = allow props{ name=abc }] + may match Lookups : (23) + trace ACL: User: b3@QPID create queue + Rule: [rule 2 ruleMode = allow props{ name=abc }] + may match Lookups : (23) + trace ACL: User: b@QPID create queue + Rule: [rule 2 ruleMode = allow props{ name=abc }] + may match Lookups : (23) + trace ACL: User: b@qpid create queue + Rule: [rule 2 ruleMode = allow props{ name=abc }] + may match Lookups : (23) + trace ACL: User: b@qpid create queue + Rule: [rule 9 ruleMode = allow props{ }] + may match Lookups : (23) + trace ACL: User: b@qpid delete exchange + Rule: [rule 9 ruleMode = allow props{ }] + may match Lookups : (24) + trace ACL: User: b@qpid delete queue + Rule: [rule 9 ruleMode = allow props{ }] + may match Lookups : (25) + trace ACL: User: b@qpid move queue + Rule: [rule 9 ruleMode = allow props{ }] + may match Lookups : (26) + trace ACL: User: b@qpid publish exchange + Rule: [rule 9 ruleMode = allow props{ }] + may match Lookups : (27,28,29) + trace ACL: User: b@qpid purge queue + Rule: [rule 9 ruleMode = allow props{ }] + may match Lookups : (30,31) + trace ACL: User: b@qpid redirect queue + Rule: [rule 9 ruleMode = allow props{ }] + may match Lookups : (32) + trace ACL: User: a@qpid reroute queue + Rule: [rule 8 ruleMode = allow props{ exchangename=123 }] + may match Lookups : (33) + trace ACL: User: b@qpid reroute queue + Rule: [rule 9 ruleMode = allow props{ }] + may match Lookups : (33) + trace ACL: User: b@qpid unbind exchange + Rule: [rule 9 ruleMode = allow props{ }] + may match Lookups : (34) + trace ACL: User: b@qpid update broker + Rule: [rule 9 ruleMode = allow props{ }] + may match Lookups : (35) +</programlisting> + + </section> + </section> + + <section id="sect-Messaging_User_Guide-Authorization-Specifying_ACL_Quotas"> + <title>User Connection and Queue Quotas</title> + <para> + The ACL module enforces various quotas and thereby limits user activity. + </para> + + <section id="sect-Messaging_User_Guide-Authorization-Specifying_ACL_Connection_Limits"> + <title>Connection Count Limits</title> + <para> + The ACL module creates broker command line switches that set limits on the number of concurrent connections allowed per user or per client host address. These settings are not specified in the ACL file. + </para> + <para> + <programlisting> + --max-connections N + --connection-limit-per-user N + --connection-limit-per-ip N + </programlisting> + </para> + <para> + <command>--max-connections</command> specifies an upper limit for all user connections. + </para> + <para> + <command>--connection-limit-per-user</command> specifies an upper limit for each user based on the authenticated user name. This limit is enforced regardless of the client IP address from which the connection originates. + </para> + <para> + <command>--connection-limit-per-ip</command> specifies an upper limit for connections for all users based on the originating client IP address. This limit is enforced regardless of the user credentials presented with the connection. + <itemizedlist> + <listitem> + Note that addresses using different transports are counted separately even though the originating host is actually the same physical machine. In the setting illustrated above a host would allow N_IP connections from [::1] IPv6 transport localhost and another N_IP connections from [127.0.0.1] IPv4 transport localhost. + </listitem> + <listitem> + The connection-limit-per-ip and connection-limit-per-user counts are active simultaneously. From a given client system users may be denied access to the broker by either connection limit. + </listitem> + </itemizedlist> + </para> + <para> + The 0.22 C++ Broker ACL module accepts fine grained per-user connection limits through quota rules in the ACL file. + </para> + <para> + <programlisting> + quota connections 10 admins userX@QPID + </programlisting> + </para> + <para> + <itemizedlist> + <listitem> + User <literal>all</literal> receives the value passed by the command line switch <literal>--connection-limit-per-user</literal>. + </listitem> + <listitem> + Values specified in the ACL rule for user <literal>all</literal> overwrite the value specified on the command line if any. + </listitem> + <listitem> + Connection quotas values are determined by first searching for the authenticated user name. If that user name is not specified then the value for user <literal>all</literal> + is used. If user <literal>all</literal> is not specified then the connection is denied. + </listitem> + <listitem> + The connection quota values range from 0..65530 inclusive. A value of zero disables connections from that user. + </listitem> + <listitem> + A user's quota may be specified many times in the ACL rule file. Only the last value specified is retained and enforced. + </listitem> + <listitem> + Per-user connection quotas are disabled when two conditions are true: 1) No --connection-limit-per-user command line switch and 2) No <literal>quota connections</literal> + rules in the ACL file. Per-user connections are always counted even if connection quotas are not enforced. This supports ACL file reloading that may subsequently + enable per-user connection quotas. + </listitem> + <listitem> + An ACL file reload may lower a user's connection quota value to a number lower than the user's current connection count. In that case the active connections + remain unaffected. New connections are denied until that user closes enough of his connections so that his count falls below the configured limit. + </listitem> + </itemizedlist> + </para> + </section> + + <section id="sect-Messaging_User_Guide-Authorization-Specifying_ACL_Connection_Host_Limits"> + <title>Connection Limits by Host Name</title> + <para> + The 0.30 C++ Broker ACL module adds the ability to create allow and deny lists of the TCP/IP hosts from which users may connect. The rule accepts these forms: + </para> + <para> + <programlisting> + acl allow user create connection host=host1 + acl allow user create connection host=host1,host2 + acl deny user create connection host=all + </programlisting> + </para> + <para> + Using the form <command>host=host1</command> specifies a single host. With a single host the name may resolve to multiple TCP/IP addresses. For example <emphasis>localhost</emphasis> resolves to both <emphasis>127.0.0.1</emphasis> and <emphasis>::1</emphasis> and possibly many other addresses. A connection from any of the addresses associated with this host matches the rule and the connection is allowed or denied accordingly. + </para> + <para> + Using the form <command>host=host1,host2</command> specifies a range of TCP/IP addresses. With a host range each host must resolve to a single TCP/IP address and the second address must be numerically larger than the first. A connection from any host where host >= host1 and host <= host2 match the rule and the connection is allowed or denied accordingly. + </para> + <para> + Using the form <command>host=all</command> specifies all TCP/IP addresses. A connection from any host matches the rule and the connection is allowed or denied accordingly. + </para> + <para> + Connection denial is only applied to incoming TCP/IP connections. Other socket types are not subjected to nor denied by range checks. + </para> + <para> + Connection creation rules are divided into three categories: + </para> + <procedure> + <step> + <para> + User = all, host != all + </para> + <para> + These define global rules and are applied before any specific user rules. + These rules may be used to reject connections before any AMPQ protocol is run and before + any user names have been negotiated. + </para> + </step> + <step> + <para> + User != all, host = any legal host or 'all' + </para> + <para> + These define user rules. These rules are applied after the global rules and + after the AMQP protocol has negotiated user identities. + </para> + </step> + <step> + <para> + User = all, host = all + </para> + <para> + This rule defines what to do if no other rule matches. The default value is "ALLOW". + Only one rule of this type may be defined. + </para> + </step> + </procedure> + + <para> + The following example illustrates how this feature can be used. + </para> + <para> + <programlisting> + group admins alice bob chuck + group Company1 c1_usera c1_userb + group Company2 c2_userx c2_usery c2_userz + acl allow admins create connection host=localhost + acl allow admins create connection host=10.0.0.0,10.255.255.255 + acl allow admins create connection host=192.168.0.0,192.168.255.255 + acl allow admins create connection host=[fc00::],[fc00::ff] + acl allow Company1 create connection host=company1.com + acl deny Company1 create connection host=all + acl allow Company2 create connection host=company2.com + acl deny Company2 create connection host=all + </programlisting> + </para> + <para> + In this example admins may connect from localhost or from any system on the 10.0.0.0/24, 192.168.0.0/16, and fc00::/7 subnets. Company1 users may connect only from company1.com and Company2 users may connect only from company2.com. + However, this example has a flaw. Although the admins group has specific hosts + from which it is allowed to make connections it is not blocked from connecting + from anywhere. The Company1 and Company2 groups are blocked appropriately. + This ACL file may be rewritten as follows: + </para> + <para> + <programlisting> + group admins alice bob chuck + group Company1 c1_usera c1_userb + group Company2 c2_userx c2_usery c2_userz + acl allow admins create connection host=localhost + acl allow admins create connection host=10.0.0.0,10.255.255.255 + acl allow admins create connection host=192.168.0.0,192.168.255.255 + acl allow admins create connection host=[fc00::],[fc00::ff] + acl allow Company1 create connection host=company1.com + acl allow Company2 create connection host=company2.com + acl deny all create connection host=all + </programlisting> + </para> + <para> + Now admins are blocked from connecting from anywhere but their allowed + hosts. + </para> + + </section> + + <section id="sect-Messaging_User_Guide-Authorization-Specifying_ACL_Queue_Limits"> + <title>Queue Limits</title> + <para> + The ACL module creates a broker command line switch that set limits on the number of queues each user is allowed to create. This settings is not specified in the ACL file. + </para> + <para> + <programlisting> + --max-queues-per-user N + </programlisting> + </para> + <para> + The queue limit is set for all users on the broker. + </para> + <para> + The 0.22 C++ Broker ACL module accepts fine grained per-user queue limits through quota rules in the ACL file. + </para> + <para> + <programlisting> + quota queues 10 admins userX@QPID + </programlisting> + </para> + <para> + <itemizedlist> + <listitem> + User <literal>all</literal> receives the value passed by the command line switch <literal>--max-queues-per-user</literal>. + </listitem> + <listitem> + Values specified in the ACL rule for user <literal>all</literal> overwrite the value specified on the command line if any. + </listitem> + <listitem> + Queue quotas values are determined by first searching for the authenticated user name. If that user name is not specified then the value for user <literal>all</literal> + is used. If user <literal>all</literal> is not specified then the queue creation is denied. + </listitem> + <listitem> + The queue quota values range from 0..65530 inclusive. A value of zero disables queue creation by that user. + </listitem> + <listitem> + A user's quota may be specified many times in the ACL rule file. Only the last value specified is retained and enforced. + </listitem> + <listitem> + Per-user queue quotas are disabled when two conditions are true: 1) No --queue-limit-per-user command line switch and 2) No <literal>quota queues</literal> + rules in the ACL file. Per-user queue creations are always counted even if queue quotas are not enforced. This supports ACL file reloading that may subsequently + enable per-user queue quotas. + </listitem> + <listitem> + An ACL file reload may lower a user's queue quota value to a number lower than the user's current queue count. In that case the active queues + remain unaffected. New queues are denied until that user closes enough of his queues so that his count falls below the configured limit. + </listitem> + </itemizedlist> + </para> + </section> + + </section> + + <!-- ########################### --> <section id="sect-Messaging_User_Guide-Security-Encryption_using_SSL"> + <title>Encryption using SSL</title> + <para> + Encryption and certificate management for <command>qpidd</command> is provided by Mozilla's Network Security Services Library (NSS). + </para> + <orderedlist id="orde-Messaging_User_Guide-Encryption_using_SSL-Enabling_SSL_for_the_RHM_broker"> + <title>Enabling SSL for the Qpid broker</title> + <listitem> + <para> + You will need a certificate that has been signed by a Certification Authority (CA). This certificate will also need to be trusted by your client. If you require client authentication in addition to server authentication, the client's certificate will also need to be signed by a CA and trusted by the broker. + </para> + <para> + In the broker, SSL is provided through the <command>ssl.so</command> module. This module is installed and loaded by default in Qpid. To enable the module, you need to specify the location of the database containing the certificate and key to use. This is done using the <command>ssl-cert-db</command> option. + </para> + <para> + The certificate database is created and managed by the Mozilla Network Security Services (NSS) <command>certutil</command> tool. Information on this utility can be found on the <ulink url="http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html">Mozilla website</ulink>, including tutorials on setting up and testing SSL connections. The certificate database will generally be password protected. The safest way to specify the password is to place it in a protected file, use the password file when creating the database, and specify the password file with the <command>ssl-cert-password-file</command> option when starting the broker. + </para> + <para> + The following script shows how to create a certificate database using certutil: + </para> + <!-- TODO: improve description --> +<programlisting> +mkdir ${CERT_DIR} +certutil -N -d ${CERT_DIR} -f ${CERT_PW_FILE} +certutil -S -d ${CERT_DIR} -n ${NICKNAME} -s "CN=${NICKNAME}" -t "CT,," -x -f ${CERT_PW_FILE} -z /usr/bin/certutil +</programlisting> + <para> + When starting the broker, set <command>ssl-cert-password-file</command> to the value of <command>${CERT_PW_FILE}</command>, set <command>ssl-cert-db</command> to the value of <command>${CERT_DIR}</command>, and set <command>ssl-cert-name</command> to the value of <command>${NICKNAME}</command>. + </para> + + </listitem> + <!-- SSL options --> <listitem> + <para> + The following SSL options can be used when starting the broker: + <variablelist> + <varlistentry> + <term><command>--ssl-use-export-policy</command></term> + <listitem> + <para> + Use NSS export policy + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term><command>--ssl-cert-password-file <replaceable>PATH</replaceable></command></term> + <listitem> + <para> + Required. Plain-text file containing password to use for accessing certificate database. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term><command>--ssl-cert-db <replaceable>PATH</replaceable></command></term> + <listitem> + <para> + Required. Path to directory containing certificate database. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term><command>--ssl-cert-name <replaceable>NAME</replaceable></command></term> + <listitem> + <para> + Name of the certificate to use. Default is <literal>localhost.localdomain</literal>. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term><command>--ssl-port <replaceable>NUMBER</replaceable></command></term> + <listitem> + <para> + Port on which to listen for SSL connections. If no port is specified, port 5671 is used. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term><command>--ssl-require-client-authentication</command></term> + <listitem> + <para> + Require SSL client authentication (i.e. verification of a client certificate) during the SSL handshake. This occurs before SASL authentication, and is independent of SASL. + </para> + <para> + This option enables the <literal>EXTERNAL</literal> SASL mechanism for SSL connections. If the client chooses the <literal>EXTERNAL</literal> mechanism, the client's identity is taken from the validated SSL certificate, using the <literal>CN</literal>literal>, and appending any <literal>DC</literal>literal>s to create the domain. For instance, if the certificate contains the properties <literal>CN=bob</literal>, <literal>DC=acme</literal>, <literal>DC=com</literal>, the client's identity is <literal>bob@acme.com</literal>. + </para> + <para> + If the client chooses a different SASL mechanism, the identity take from the client certificate will be replaced by that negotiated during the SASL handshake. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term><command>--ssl-sasl-no-dict</command></term> + <listitem> + <para> + Do not accept SASL mechanisms that can be compromised by dictionary attacks. This prevents a weaker mechanism being selected instead of <literal>EXTERNAL</literal>, which is not vulnerable to dictionary attacks. + </para> + + </listitem> + + </varlistentry> + + </variablelist> + Also relevant is the <command>--require-encryption</command> broker option. This will cause <command>qpidd</command> to only accept encrypted connections. + </para> + + </listitem> + + </orderedlist> + <!-- --> <variablelist id="vari-Messaging_User_Guide-Encryption_using_SSL-Enabling_SSL_in_Clients"> + <title>Enabling SSL in Clients</title> + <varlistentry> + <term>C++ clients:</term> + <listitem> + <para> + <orderedlist> + <listitem> + <para> + In C++ clients, SSL is implemented in the <command>sslconnector.so</command> module. This module is installed and loaded by default in Qpid. + </para> + <para> + The following options can be specified for C++ clients using environment variables: + </para> + <table frame="all" id="tabl-Messaging_User_Guide-Enabling_SSL_in_Clients-SSL_Client_Environment_Variables_for_C_clients"> + <title>SSL Client Environment Variables for C++ clients</title> + <tgroup align="left" cols="2" colsep="1" rowsep="1"> + <colspec colname="c1"></colspec> + <colspec colname="c2"></colspec> + <thead> + <row> + <entry align="center" nameend="c2" namest="c1"> + SSL Client Options for C++ clients + </entry> + + </row> + + </thead> + <tbody> + <row> + <entry> + <command>QPID_SSL_USE_EXPORT_POLICY</command> + </entry> + <entry> + Use NSS export policy + </entry> + + </row> + <row> + <entry> + <command>QPID_SSL_CERT_PASSWORD_FILE <replaceable>PATH</replaceable></command> + </entry> + <entry> + File containing password to use for accessing certificate database + </entry> + + </row> + <row> + <entry> + <command>QPID_SSL_CERT_DB <replaceable>PATH</replaceable></command> + </entry> + <entry> + Path to directory containing certificate database + </entry> + + </row> + <row> + <entry> + <command>QPID_SSL_CERT_NAME <replaceable>NAME</replaceable></command> + </entry> + <entry> + Name of the certificate to use. When SSL client authentication is enabled, a certificate name should normally be provided. + </entry> + + </row> + + </tbody> + + </tgroup> + + </table> + <!-- ######## --> + </listitem> + <listitem> + <para> + When using SSL connections, clients must specify the location of the certificate database, a directory that contains the client's certificate and the public key of the Certificate Authority. This can be done by setting the environment variable <command>QPID_SSL_CERT_DB</command> to the full pathname of the directory. If a connection uses SSL client authentication, the client's password is also needed—the password should be placed in a protected file, and the <command>QPID_SSL_CERT_PASSWORD_FILE</command> variable should be set to the location of the file containing this password. + </para> + + </listitem> + <listitem> + <para> + To open an SSL enabled connection in the Qpid Messaging API, set the <parameter>protocol</parameter> connection option to <parameter>ssl</parameter>. + </para> + + </listitem> + + </orderedlist> + + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term>Java clients:</term> + <listitem> + <para> + <orderedlist> + <listitem> + <para> + For both server and client authentication, import the trusted CA to your trust store and keystore and generate keys for them. Create a certificate request using the generated keys and then create a certificate using the request. You can then import the signed certificate into your keystore. Pass the following arguments to the Java JVM when starting your client: +<programlisting> +-Djavax.net.ssl.keyStore=/home/bob/ssl_test/keystore.jks +-Djavax.net.ssl.keyStorePassword=password +-Djavax.net.ssl.trustStore=/home/bob/ssl_test/certstore.jks +-Djavax.net.ssl.trustStorePassword=password +</programlisting> + + </para> + + </listitem> + <listitem> + <para> + For server side authentication only, import the trusted CA to your trust store and pass the following arguments to the Java JVM when starting your client: +<programlisting> +-Djavax.net.ssl.trustStore=/home/bob/ssl_test/certstore.jks +-Djavax.net.ssl.trustStorePassword=password +</programlisting> + + </para> + + </listitem> + <listitem> + <para> + Java clients must use the SSL option in the connection URL to enable SSL encryption, e.g. + </para> + +<programlisting>amqp://username:password@clientid/test?brokerlist='tcp://localhost:5672?ssl='true'' +</programlisting> + + </listitem> + <listitem> + <para> + If you need to debug problems in an SSL connection, enable Java's SSL debugging by passing the argument <literal>-Djavax.net.debug=ssl</literal> to the Java JVM when starting your client. + </para> + + </listitem> + + </orderedlist> + + </para> + + </listitem> + + </varlistentry> + + </variablelist> + + </section> + + +</section> diff --git a/qpid/doc/book/src/cpp-broker/Using-Broker-Federation.xml b/qpid/doc/book/src/cpp-broker/Using-Broker-Federation.xml new file mode 100644 index 0000000000..614c168704 --- /dev/null +++ b/qpid/doc/book/src/cpp-broker/Using-Broker-Federation.xml @@ -0,0 +1,715 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you 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. + +--> + +<section id="chap-Messaging_User_Guide-Broker_Federation"> + <title>Broker Federation</title> + <para> + <firstterm>Broker Federation</firstterm> allows messaging networks to be defined by creating <firstterm>message routes</firstterm>, in which messages in one broker (the <firstterm>source broker</firstterm>) are automatically routed to another broker (the <firstterm>destination broker</firstterm>). These routes may be defined between exchanges in the two brokers (the <firstterm>source exchange</firstterm> and the <firstterm>destination exchange</firstterm>), or from a queue in the source broker (the <firstterm>source queue</firstterm>) to an exchange in the destination broker. Message routes are unidirectional; when bidirectional flow is needed, one route is created in each direction. Routes can be durable or transient. A durable route survives broker restarts, restoring a route as soon as both the source broker and the destination are available. If the connection to a destination is lost, messages associated with a durable route continue to accumulate on the source, so they can be retrieved when the connection is reestablished. + </para> + <para> + Broker Federation can be used to build large messaging networks, with many brokers, one route at a time. If network connectivity permits, an entire distributed messaging network can be configured from a single location. The rules used for routing can be changed dynamically as servers change, responsibilities change, at different times of day, or to reflect other changing conditions. + </para> + <para> + Broker Federation is useful in a wide variety of scenarios. Some of these have to do with functional organization; for instance, brokers may be organized by geography, service type, or priority. Here are some use cases for federation: + <itemizedlist> + <listitem> + <para> + Geography: Customer requests may be routed to a processing location close to the customer. + </para> + + </listitem> + <listitem> + <para> + Service Type: High value customers may be routed to more responsive servers. + </para> + + </listitem> + <listitem> + <para> + Load balancing: Routing among brokers may be changed dynamically to account for changes in actual or anticipated load. + </para> + + </listitem> + <listitem> + <para> + High Availability: Routing may be changed to a new broker if an existing broker becomes unavailable. + </para> + + </listitem> + <listitem> + <para> + WAN Connectivity: Federated routes may connect disparate locations across a wide area network, while clients connect to brokers on their own local area network. Each broker can provide persistent queues that can hold messages even if there are gaps in WAN connectivity. + </para> + + </listitem> + <listitem> + <para> + Functional Organization: The flow of messages among software subsystems can be configured to mirror the logical structure of a distributed application. + </para> + + </listitem> + <listitem> + <para> + Replicated Exchanges: High-function exchanges like the XML exchange can be replicated to scale performance. + </para> + + </listitem> + <listitem> + <para> + Interdepartmental Workflow: The flow of messages among brokers can be configured to mirror interdepartmental workflow at an organization. + </para> + + </listitem> + + </itemizedlist> + + </para> + <section id="sect-Messaging_User_Guide-Broker_Federation-Message_Routes"> + <title>Message Routes</title> + <para> + Broker Federation is done by creating message routes. The destination for a route is always an exchange on the destination broker. By default, a message route is created by configuring the destination broker, which then contacts the source broker to subscribe to the source queue. This is called a <firstterm>pull route</firstterm>. It is also possible to create a route by configuring the source broker, which then contacts the destination broker in order to send messages. This is called a <firstterm>push route</firstterm>, and is particularly useful when the destination broker may not be available at the time the messaging route is configured, or when a large number of routes are created with the same destination exchange. + </para> + <para> + The source for a route can be either an exchange or a queue on the source broker. If a route is between two exchanges, the routing criteria can be given explicitly, or the bindings of the destination exchange can be used to determine the routing criteria. To support this functionality, there are three kinds of message routes: queue routes, exchange routes, and dynamic exchange routes. + </para> + <section id="sect-Messaging_User_Guide-Message_Routes-Queue_Routes"> + <title>Queue Routes</title> + <para> + <firstterm>Queue Routes</firstterm> route all messages from a source queue to a destination exchange. If message acknowledgement is enabled, messages are removed from the queue when they have been received by the destination exchange; if message acknowledgement is off, messages are removed from the queue when sent. + </para> + + </section> + + <section id="sect-Messaging_User_Guide-Message_Routes-Exchange_Routes"> + <title>Exchange Routes</title> + <para> + <firstterm>Exchange routes</firstterm> route messages from a source exchange to a destination exchange, using a binding key (which is optional for a fanout exchange). + </para> + <para> + Internally, creating an exchange route creates a private queue (auto-delete, exclusive) on the source broker to hold messages that are to be routed to the destination broker, binds this private queue to the source broker exchange, and subscribes the destination broker to the queue. + </para> + + </section> + + <section id="sect-Messaging_User_Guide-Message_Routes-Dynamic_Exchange_Routes"> + <title>Dynamic Exchange Routes</title> + <para> + Dynamic exchange routes allow a client to create bindings to an exchange on one broker, and receive messages that satisfy the conditions of these bindings not only from the exchange to which the client created the binding, but also from other exchanges that are connected to it using dynamic exchange routes. If the client modifies the bindings for a given exchange, they are also modified for dynamic exchange routes associated with that exchange. + </para> + <para> + <firstterm>Dynamic exchange routes</firstterm> apply all the bindings of a destination exchange to a source exchange, so that any message that would match one of these bindings is routed to the destination exchange. If bindings are added or removed from the destination exchange, these changes are reflected in the dynamic exchange route -- when the destination broker creates a binding with a given binding key, this is reflected in the route, and when the destination broker drops a binding with a binding key, the route no longer incurs the overhead of transferring messages that match the binding key among brokers. If two exchanges have dynamic exchange routes to each other, then all bindings in each exchange are reflected in the dynamic exchange route of the other. In a dynamic exchange route, the source and destination exchanges must have the same exchange type, and they must have the same name; for instance, if the source exchange is a direct exchange, the destination exchange must also be a direct exchange, and the names must match. + </para> + <para> + Internally, dynamic exchange routes are implemented in the same way as exchange routes, except that the bindings used to implement dynamic exchange routes are modified if the bindings in the destination exchange change. + </para> + <para> + A dynamic exchange route is always a pull route. It can never be a push route. + </para> + + </section> + + + </section> + + <section id="sect-Messaging_User_Guide-Broker_Federation-Federation_Topologies"> + <title>Federation Topologies</title> + <para> + A federated network is generally a tree, star, or line, using bidirectional links (implemented as a pair of unidirectional links) between any two brokers. A ring topology is also possible, if only unidirectional links are used. + </para> + <para> + Every message transfer takes time. For better performance, you should minimize the number of brokers between the message origin and final destination. In most cases, tree or star topologies do this best. + </para> + <para> + For any pair of nodes A,B in a federated network, there should be only one path from A to B. If there is more than one path, message loops can cause duplicate message transmission and flood the federated network. The topologies discussed above do not have message loops. A ring topology with bidirectional links is one example of a topology that does cause this problem, because a given broker can receive the same message from two different brokers. Mesh topologies can also cause this problem. + </para> + + </section> + + <section id="sect-Messaging_User_Guide-Broker_Federation-Federation_among_High_Availability_Message_Clusters"> + <title>Federation among High Availability Message Clusters</title> + <para> + Federation is generally used together with High Availability Message Clusters, using clusters to provide high availability on each LAN, and federation to route messages among the clusters. Because message state is replicated within a cluster, it makes little sense to define message routes between brokers in the same cluster. + </para> + <para> + To create a message route between two clusters, simply create a route between any one broker in the first cluster and any one broker in the second cluster. Each broker in a given cluster can use message routes defined for another broker in the same cluster. If the broker for which a message route is defined should fail, another broker in the same cluster can restore the message route. + </para> + + </section> + + <section id="sect-Messaging_User_Guide-Broker_Federation-The_qpid_route_Utility"> + <title>The qpid-route Utility</title> + <para> + <command>qpid-route</command> is a command line utility used to configure federated networks of brokers and to view the status and topology of networks. It can be used to configure routes among any brokers that <command>qpid-route</command> can connect to. + </para> + <para> + The syntax of <command>qpid-route</command> is as follows: + </para> + + <screen> + qpid-route [OPTIONS] dynamic add <dest-broker> <src-broker> <exchange> + qpid-route [OPTIONS] dynamic del <dest-broker> <src-broker> <exchange> + + qpid-route [OPTIONS] route add <dest-broker> <src-broker> <exchange> <routing-key> + qpid-route [OPTIONS] route del <dest-broker> <src-broker> <exchange> <routing-key> + + qpid-route [OPTIONS] queue add <dest-broker> <src-broker> <dest-exchange> <src-queue> + qpid-route [OPTIONS] queue del <dest-broker> <src-broker> <dest-exchange> <src-queue> + + qpid-route [OPTIONS] list [<broker>] + qpid-route [OPTIONS] flush [<broker>] + qpid-route [OPTIONS] map [<broker>] + + <!-- qpid-route [OPTIONS] add connection <dest-broker> <src-broker> + qpid-route [OPTIONS] del connection <dest-broker> <src-broker> --> + qpid-route [OPTIONS] list connections [<broker>] + </screen> + <para> + The syntax for <command>broker</command>, <command>dest-broker</command>, and <command>src-broker</command> is as follows: + </para> + + <screen> + [username/password@] hostname | ip-address [:<port>] + </screen> + <para> + The following are all valid examples of the above syntax: <command>localhost</command>, <command>10.1.1.7:10000</command>, <command>broker-host:10000</command>, <command>guest/guest@localhost</command>. + </para> + <para> + These are the options for <command>qpid-route</command>: + </para> + <table frame="all" id="tabl-Messaging_User_Guide-The_qpid_route_Utility-qpid_route_options"> + <title><command>qpid-route</command> options</title> + <tgroup align="left" cols="2" colsep="1" rowsep="1"> + <colspec colname="c1"></colspec> + <colspec colname="c2"></colspec> + <!-- <thead> + <row> + <entry align="center" nameend="c2" namest="c1"> + Options for using <command>qpid-route</command> to Manage Federation + </entry> + </row> + </thead> + --> <tbody> + <row> + <entry> + <command>-v</command> + </entry> + <entry> + Verbose output. + </entry> + + </row> + <row> + <entry> + <command>-q</command> + </entry> + <entry> + Quiet output, will not print duplicate warnings. + </entry> + + </row> + <row> + <entry> + <command>-d</command> + </entry> + <entry> + Make the route durable. + </entry> + + </row> + <!-- + <row> + <entry> + <command>-e</command> + </entry> + <entry> + Delete link after deleting the last route on the link. + </entry> + </row> --> <row> + <entry> + <command> --timeout N</command> + </entry> + <entry> + Maximum time to wait when qpid-route connects to a broker, in seconds. Default is 10 seconds. + </entry> + + </row> + <row> + <entry> + <command>--ack N</command> + </entry> + <entry> + Acknowledge transfers of routed messages in batches of N. Default is 0 (no acknowledgements). Setting to 1 or greater enables acknowledgements; when using acknowledgements, values of N greater than 1 can significnantly improve performance, especially if there is significant network latency between the two brokers. + </entry> + + </row> + <row> + <entry> + <command>-s [ --src-local ]</command> + </entry> + <entry> + Configure the route in the source broker (create a push route). + </entry> + + </row> + <row> + <entry> + <command>-t <transport> [ --transport <transport>]</command> + </entry> + <entry> + Transport protocol to be used for the route. + <itemizedlist> + <listitem> + <para> + tcp (default) + </para> + + </listitem> + <listitem> + <para> + ssl + </para> + + </listitem> + <listitem> + <para> + rdma + </para> + + </listitem> + + </itemizedlist> + + </entry> + + </row> + + </tbody> + + </tgroup> + + </table> + <section id="sect-Messaging_User_Guide-The_qpid_route_Utility-Creating_and_Deleting_Queue_Routes"> + <title>Creating and Deleting Queue Routes</title> + <para> + The syntax for creating and deleting queue routes is as follows: + </para> + + <screen> + qpid-route [OPTIONS] queue add <dest-broker> <src-broker> <dest-exchange> <src-queue> + qpid-route [OPTIONS] queue del <dest-broker> <src-broker> <dest-exchange> <src-queue> + </screen> + <para> + For instance, the following creates a queue route that routes all messages from the queue named <command>public</command> on the source broker <command>localhost:10002</command> to the <command>amq.fanout</command> exchange on the destination broker <command>localhost:10001</command>: + </para> + + <screen> + $ qpid-route queue add localhost:10001 localhost:10002 amq.fanout public + </screen> + <para> + If the <command>-d</command> option is specified, this queue route is persistent, and will be restored if one or both of the brokers is restarted: + </para> + + <screen> + $ qpid-route -d queue add localhost:10001 localhost:10002 amq.fanout public + </screen> + <para> + The <command>del</command> command takes the same arguments as the <command>add</command> command. The following command deletes the queue route described above: + </para> + + <screen> + $ qpid-route queue del localhost:10001 localhost:10002 amq.fanout public + </screen> + + </section> + + <section id="sect-Messaging_User_Guide-The_qpid_route_Utility-Creating_and_Deleting_Exchange_Routes"> + <title>Creating and Deleting Exchange Routes</title> + <para> + The syntax for creating and deleting exchange routes is as follows: + </para> + + <screen> + qpid-route [OPTIONS] route add <dest-broker> <src-broker> <exchange> <routing-key> + qpid-route [OPTIONS] route del <dest-broker> <src-broker> <exchange> <routing-key> + qpid-route [OPTIONS] flush [<broker>] + </screen> + <para> + For instance, the following creates an exchange route that routes messages that match the binding key <command>global.#</command> from the <command>amq.topic</command> exchange on the source broker <command>localhost:10002</command> to the <command>amq.topic</command> exchange on the destination broker <command>localhost:10001</command>: + </para> + + <screen> + $ qpid-route route add localhost:10001 localhost:10002 amq.topic global.# + </screen> + <para> + In many applications, messages published to the destination exchange should also be routed to the source exchange. This is accomplished by creating a second exchange route, reversing the roles of the two exchanges: + </para> + + <screen> + $ qpid-route route add localhost:10002 localhost:10001 amq.topic global.# + </screen> + <para> + If the <command>-d</command> option is specified, the exchange route is persistent, and will be restored if one or both of the brokers is restarted: + </para> + + <screen> + $ qpid-route -d route add localhost:10001 localhost:10002 amq.fanout public + </screen> + <para> + The <command>del</command> command takes the same arguments as the <command>add</command> command. The following command deletes the first exchange route described above: + </para> + + <screen> + $ qpid-route route del localhost:10001 localhost:10002 amq.topic global.# + </screen> + + </section> + + <section id="sect-Messaging_User_Guide-The_qpid_route_Utility-Deleting_all_routes_for_a_broker"> + <title>Deleting all routes for a broker</title> + <para> + Use the <command>flush</command> command to delete all routes for a given broker: + </para> + + <screen> + qpid-route [OPTIONS] flush [<broker>] + </screen> + <para> + For instance, the following command deletes all routes for the broker <command>localhost:10001</command>: + </para> + + <screen> + $ qpid-route flush localhost:10001 + </screen> + + </section> + + <section id="sect-Messaging_User_Guide-The_qpid_route_Utility-Creating_and_Deleting_Dynamic_Exchange_Routes"> + <title>Creating and Deleting Dynamic Exchange Routes</title> + <para> + The syntax for creating and deleting dynamic exchange routes is as follows: + </para> + + <screen> + qpid-route [OPTIONS] dynamic add <dest-broker> <src-broker> <exchange> + qpid-route [OPTIONS] dynamic del <dest-broker> <src-broker> <exchange> + </screen> + <para> + In the following examples, we will route messages from a topic exchange. We will create a new topic exchange and federate it so that we are not affected by other all clients that use the built-in <command>amq.topic</command> exchange. The following commands create a new topic exchange on each of two brokers: + </para> + + <screen> + $ qpid-config -a localhost:10003 add exchange topic fed.topic + $ qpid-config -a localhost:10004 add exchange topic fed.topic + </screen> + <para> + Now let's create a dynamic exchange route that routes messages from the <command>fed.topic</command> exchange on the source broker <command>localhost:10004</command> to the <command>fed.topic</command> exchange on the destination broker <command>localhost:10003</command> if they match any binding on the destination broker's <command>fed.topic</command> exchange: + </para> + + <screen> + $ qpid-route dynamic add localhost:10003 localhost:10004 fed.topic + </screen> + <para> + Internally, this creates a private autodelete queue on the source broker, and binds that queue to the <command>fed.topic</command> exchange on the source broker, using each binding associated with the <command>fed.topic</command> exchange on the destination broker. + </para> + <para> + In many applications, messages published to the destination exchange should also be routed to the source exchange. This is accomplished by creating a second dynamic exchange route, reversing the roles of the two exchanges: + </para> + + <screen> + $ qpid-route dynamic add localhost:10004 localhost:10003 fed.topic + </screen> + <para> + If the <command>-d</command> option is specified, the exchange route is persistent, and will be restored if one or both of the brokers is restarted: + </para> + + <screen> + $ qpid-route -d dynamic add localhost:10004 localhost:10003 fed.topic + </screen> + <para> + When an exchange route is durable, the private queue used to store messages for the route on the source exchange is also durable. If the connection between the brokers is lost, messages for the destination exchange continue to accumulate until it can be restored. + </para> + <para> + The <command>del</command> command takes the same arguments as the <command>add</command> command. The following command deletes the first exchange route described above: + </para> + + <screen> + $ qpid-route dynamic del localhost:10004 localhost:10003 fed.topic + </screen> + <para> + Internally, this deletes the bindings on the source exchange for the the private queues associated with the message route. + </para> + + </section> + + <section id="sect-Messaging_User_Guide-The_qpid_route_Utility-Viewing_Routes"> + <title>Viewing Routes</title> + <para> + The <command>route list</command> command shows the routes associated with an individual broker. For instance, suppose we have created the following two routes: + </para> + + <screen> + $ qpid-route dynamic add localhost:10003 localhost:10004 fed.topic + $ qpid-route dynamic add localhost:10004 localhost:10003 fed.topic + </screen> + <para> + We can now use <command>route list</command> to show all routes for the broker <command>localhost:10003</command>: + </para> + + <screen> + $ qpid-route route list localhost:10003 + localhost:10003 localhost:10004 fed.topic <dynamic> + </screen> + <para> + Note that this shows only one of the two routes we created, the route for which <command>localhost:10003</command> is a destination. If we want to see the route for which <command>localhost:10004</command> is a destination, we need to do another route list: + </para> + + <screen> + $ qpid-route route list localhost:10004 + localhost:10004 localhost:10003 fed.topic <dynamic> + </screen> + <para> + The <command>route map</command> command shows all routes associated with a broker, and recursively displays all routes for brokers involved in federation relationships with the given broker. For instance, here is the output for the two brokers configured above: + </para> + + <screen> + $ qpid-route route map localhost:10003 + + Finding Linked Brokers: + localhost:10003... Ok + localhost:10004... Ok + + Dynamic Routes: + + Exchange fed.topic: + localhost:10004 <=> localhost:10003 + + Static Routes: + none found + </screen> + <para> + Note that the two dynamic exchange links are displayed as though they were one bidirectional link. The <command>route map</command> command is particularly helpful for larger, more complex networks. Let's configure a somewhat more complex network with 16 dynamic exchange routes: + </para> + + <screen> + qpid-route dynamic add localhost:10001 localhost:10002 fed.topic + qpid-route dynamic add localhost:10002 localhost:10001 fed.topic + + qpid-route dynamic add localhost:10003 localhost:10002 fed.topic + qpid-route dynamic add localhost:10002 localhost:10003 fed.topic + + qpid-route dynamic add localhost:10004 localhost:10002 fed.topic + qpid-route dynamic add localhost:10002 localhost:10004 fed.topic + + qpid-route dynamic add localhost:10002 localhost:10005 fed.topic + qpid-route dynamic add localhost:10005 localhost:10002 fed.topic + + qpid-route dynamic add localhost:10005 localhost:10006 fed.topic + qpid-route dynamic add localhost:10006 localhost:10005 fed.topic + + qpid-route dynamic add localhost:10006 localhost:10007 fed.topic + qpid-route dynamic add localhost:10007 localhost:10006 fed.topic + + qpid-route dynamic add localhost:10006 localhost:10008 fed.topic + qpid-route dynamic add localhost:10008 localhost:10006 fed.topic + </screen> + <para> + Now we can use <command>route map</command> starting with any one broker, and see the entire network: + </para> + + <screen> + $ ./qpid-route route map localhost:10001 + + Finding Linked Brokers: + localhost:10001... Ok + localhost:10002... Ok + localhost:10003... Ok + localhost:10004... Ok + localhost:10005... Ok + localhost:10006... Ok + localhost:10007... Ok + localhost:10008... Ok + + Dynamic Routes: + + Exchange fed.topic: + localhost:10002 <=> localhost:10001 + localhost:10003 <=> localhost:10002 + localhost:10004 <=> localhost:10002 + localhost:10005 <=> localhost:10002 + localhost:10006 <=> localhost:10005 + localhost:10007 <=> localhost:10006 + localhost:10008 <=> localhost:10006 + + Static Routes: + none found + </screen> + + </section> + + <section id="sect-Messaging_User_Guide-The_qpid_route_Utility-Resilient_Connections"> + <title>Resilient Connections</title> + <para> + When a broker route is created, or when a durable broker route is restored after broker restart, a connection is created between the source broker and the destination broker. The connections used between brokers are called <firstterm>resilient connections</firstterm>; if the connection fails due to a communication error, it attempts to reconnect. The retry interval begins at 2 seconds and, as more attempts are made, grows to 64 seconds, and continues to retry every 64 seconds thereafter. If the connection fails due to an authentication problem, it will not continue to retry. + </para> + <para> + The command <command>list connections</command> can be used to show the resilient connections for a broker: + </para> + + <screen> + $ qpid-route list connections localhost:10001 + + Host Port Transport Durable State Last Error + ============================================================================= + localhost 10002 tcp N Operational + localhost 10003 tcp N Operational + localhost 10009 tcp N Waiting Connection refused + </screen> + <para> + In the above output, <command>Last Error</command> contains the string representation of the last connection error received for the connection. <command>State</command> represents the state of the connection, and may be one of the following values: + </para> + <table id="tabl-Messaging_User_Guide-Resilient_Connections-State_values_in_qpid_route_list_connections"> + <title>State values in <command>$ qpid-route list connections</command></title> + <tgroup align="left" cols="2" colsep="1" rowsep="1"> + <tbody> + <row> + <entry> + Waiting + </entry> + <entry> + Waiting before attempting to reconnect. + </entry> + + </row> + <row> + <entry> + Connecting + </entry> + <entry> + Attempting to establish the connection. + </entry> + + </row> + <row> + <entry> + Operational + </entry> + <entry> + The connection has been established and can be used. + </entry> + + </row> + <row> + <entry> + Failed + </entry> + <entry> + The connection failed and will not retry (usually because authentication failed). + </entry> + + </row> + <row> + <entry> + Closed + </entry> + <entry> + The connection has been closed and will soon be deleted. + </entry> + + </row> + <row> + <entry> + Passive + </entry> + <entry> + If a cluster is federated to another cluster, only one of the nodes has an actual connection to remote node. Other nodes in the cluster have a passive connection. + </entry> + + </row> + + </tbody> + + </tgroup> + + </table> + + </section> + + </section> + + <section id="federation-broker-options"> + <title>Broker options affecting federation</title> + <para> + The following broker options affect federation: + <table frame="all" id="federation-broker-options-table"> + <title>Broker Options for Federation</title> + <tgroup align="left" cols="2" colsep="1" rowsep="1"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <thead> + <row> + <entry align="center" nameend="c2" namest="c1"> + Options for Federation + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <literal>federation-tag <replaceable>NAME</replaceable></literal> + </entry> + <entry> + A unique name to identify this broker in federation network. + If not specified, the broker will generate a unique identifier. + </entry> + </row> + <row> + <entry> + <literal>link-maintenance-interval <replaceable>SECONDS</replaceable></literal> + <footnoteref linkend="ha-seconds-spec"/> + </entry> + <entry> + <para> + Interval to check if links need to be re-connected. Default 2 + seconds. Can be a sub-second interval for faster failover, + e.g. 0.1 seconds. + </para> + </entry> + </row> + <row> + <entry> + <literal>link-heartbeat-interval <replaceable>SECONDS</replaceable></literal> + <footnoteref linkend="ha-seconds-spec"/> + </entry> + <entry> + <para> + Heart-beat interval for federation links. If no heart-beat is + received for twice the interval the link is considered dead. + Default 120 seconds. + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </section> +</section> diff --git a/qpid/doc/book/src/cpp-broker/Using-message-groups.xml b/qpid/doc/book/src/cpp-broker/Using-message-groups.xml new file mode 100644 index 0000000000..9b904d9f18 --- /dev/null +++ b/qpid/doc/book/src/cpp-broker/Using-message-groups.xml @@ -0,0 +1,295 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section id="Using-message-groups"> + <title> + Using Message Groups + </title> + + <section role="h2" id="usingmessagegroups-Overview"> + <title> + Overview + </title> + <para> + The broker allows messaging applications to classify a set of related messages as + belonging to a group. This allows a message producer to indicate to the consumer + that a group of messages should be considered a single logical operation with + respect to the application. + </para> + <para> + The broker can use this group identification to enforce policies controlling how + messages from a given group can be distributed to consumers. For instance, the + broker can be configured to guarantee all the messages from a particular group are + processed in order across multiple consumers. + </para> + <para> + For example, assume we have a shopping application that manages items in a virtual + shopping cart. A user may add an item to their shopping cart, then change their + mind and remove it. If the application sends an <emphasis>add</emphasis> message to the broker, + immediately followed by a <emphasis>remove</emphasis> message, they will be queued in the proper + order - <emphasis>add</emphasis>, followed by <emphasis>remove</emphasis>. + </para> + <para> + However, if there are multiple consumers, it is possible that once a consumer + acquires the <emphasis>add</emphasis> message, a different consumer may acquire the + <emphasis>remove</emphasis> message. This allows both messages to be processed in parallel, + which could result in a "race" where the <emphasis>remove</emphasis> operation is incorrectly + performed before the <emphasis>add</emphasis> operation. + </para> + </section> + <!--h2--> + <section role="h2" id="usingmessagegroups-GroupingMessages"> + <title> + Grouping Messages + </title> + <para> + In order to group messages, the application would designate a particular + message header as containing a message's <emphasis>group identifier</emphasis>. The group + identifier stored in that header field would be a string value set by the message + producer. Messages from the same group would have the same group identifier + value. The key that identifies the header must also be known to the message + consumers. This allows the consumers to determine a message's assigned group. + </para> + <para> + The header that is used to hold the group identifier, as well as the values used + as group identifiers, are totally under control of the application. + </para> + </section> + <section role="h2" id="usingmessagegroups-BrokerRole"> + <title> + The Role of the Broker + </title> + <para> + The broker will apply the following processing on each grouped message: + <itemizedlist> + <listitem>Enqueue a received message on the destination queue.</listitem> + <listitem>Determine the message's group by examining the message's group identifier header.</listitem> + <listitem>Enforce <emphasis>consumption ordering</emphasis> among messages belonging to the same group.</listitem> + </itemizedlist> + <emphasis>Consumption ordering</emphasis> means that the broker will not allow outstanding + unacknowledged messages to <emphasis>more than one consumer for a given group</emphasis>. + </para> + <para> + This means that only one consumer can be processing messages from a particular + group at a given time. When the consumer acknowledges all of its acquired + messages, then the broker <emphasis>may</emphasis> pass the next pending message + from that group to a different consumer. + </para> + <para> + Specifically, for any given group the broker allows only the first N messages in + the group to be delivered to a consumer. The value of N would be determined by + the selected consumer's configured prefetch capacity. The broker blocks access by + any other consumer to any remaining undelivered messages in that group. Once the + receiving consumer has: + <itemizedlist> + <listitem>acknowledged,</listitem> + <listitem>released, or</listitem> + <listitem>rejected</listitem> + </itemizedlist> + all the delivered messages, the broker allows the next messages in the group to be + delivered. The next messages <emphasis>may</emphasis> be delivered to a different + consumer. + </para> + <para> + Note well that distinct message groups would not block each other from delivery. + For example, assume a queue contains messages from two different message groups - + say group "A" and group "B" - and they are enqueued such that "A"'s messages are + in front of "B". If the first message of group "A" is in the process of being + consumed by a client, then the remaining "A" messages are blocked, but the + messages of the "B" group are available for consumption by other consumers - even + though it is "behind" group "A" in the queue. + </para> + </section> + <section role="h2" id="usingmessagegroups-ConsumerGuide"> + <title> + Well Behaved Consumers + </title> + <para> + The broker can only enforce policy when delivering messages. To guarantee that + strict message ordering is preserved, the consuming application must adhere to the + following rules: + <itemizedlist> + <listitem>completely process the data in a received message before accepting + that message</listitem> + <listitem>acknowledge (or reject) messages in the same order as they are + received</listitem> + <listitem>avoid releasing messages (see below)</listitem> + </itemizedlist> + The term <emphasis>processed</emphasis> means that the consumer has finished + updating all application state affected by the message that has been received. + See section 2.6.2. Transfer of Responsibility, of the AMQP-0.10 specification for + more detail. + </para> + <note> + <title>Be Advised</title> + <para> + If a consumer does not adhere to the above rules, it may affect the ordering of + grouped messages even when the broker is enforcing consumption order. This can + be done by selectively acknowledging and releasing messages from the same group. + </para> + <para> + Assume a consumer has received two messages from group "A", "A-1" and "A-2", in + that order. If the consumer releases "A-1" then acknowledges "A-2", "A-1" will + be put back onto the queue and "A-2" will be removed from the queue. This + allows another consumer to acquire and process "A-1" <emphasis>after</emphasis> + "A-2" has been processed. + </para> + <para> + Under some application-defined circumstances, this may be acceptable behavior. + However, if order must be preserved, the client should either release + <emphasis>all</emphasis> currently held messages, or discard the target message + using reject. + </para> + </note> + </section> + <!--h2--> + <section role="h2" id="usingmessagegroups-BrokerConfig"> + <title> + Broker Configuration + </title> + <para> + In order for the broker to determine a message's group, the key for the header + that contains the group identifier must be provided to the broker via + configuration. This is done on a per-queue basis, when the queue is first + configured. + </para> + <para> + This means that message group classification is determined by the message's destination + queue. + </para> + <para> + Specifically, the queue "holds" the header key that is used to find the message's + group identifier. All messages arriving at the queue are expected to use the same + header key for holding the identifer. Once the message is enqueued, the broker + looks up the group identifier in the message's header, and classifies the message + by its group. + </para> + <para> + Message group support can be enabled on a queue using the + <command>qpid-config</command> command line tool. The following options should be + provided when adding a new queue: + <table> + <title>qpid-config options for creating message group queues</title> + <tgroup cols="2"> + <thead> + <colspec colnum="1" colwidth="1*"/> + <colspec colnum="2" colwidth="3*"/> + <row> + <entry>Option</entry><entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>--group-header=<replaceable>header-name</replaceable></entry> + <entry>Enable message group support for this queue. Specify name of application header that holds the group identifier.</entry> + </row> + <row> + <entry>--shared-groups</entry> + <entry>Enforce ordered message group consumption across multiple consumers.</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <para> + Message group support may also be specified in the + <command>queue.declare</command> method via the <command>arguments</command> + parameter map, or using the messaging address syntax. The following keys must be + provided in the arguments map to enable message group support on a queue: + </para> + <table> + <title>Queue Declare/Address Syntax Message Group Configuration Arguments</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Key</entry> + <entry>Value</entry> + </row> + </thead> + <tbody> + <row> + <entry>qpid.group_header_key</entry> + <entry>string - key for message header that holds the group identifier value</entry> + </row> + <row> + <entry>qpid.shared_msg_group</entry> + <entry>1 - enforce ordering across multiple consumers</entry> + </row> + </tbody> + </tgroup> + </table> + <para> + It is important to note that there is no need to provide the actual group + identifer values that will be used. The broker learns this values as messages are + recieved. Also, there is no practical limit - aside from resource limitations - + to the number of different groups that the broker can track at run time. + </para> + <note> + <title>Restrictions</title> + <para> + Message grouping is not supported on LVQ or Priority queues. + </para> + </note> + <example> + <title>Creating a message group queue via qpid-config</title> + <para> + This example uses the qpid-config tool to create a message group queue called + "MyMsgQueue". The message header that contains the group identifier will use + the key "GROUP_KEY". + </para> + <programlisting> +qpid-config add queue MyMsgQueue --group-header="GROUP_KEY" --shared-groups + </programlisting> + </example> + <example> + <title>Creating a message group queue using address syntax (C++)</title> + <para> + This example uses the messaging address syntax to create a message group queue + with the same configuration as the previous example. + </para> + <programlisting> +sender = session.createSender("MyMsgQueue;" + " {create:always, delete:receiver," + " node: {x-declare: {arguments:" + " {'qpid.group_header_key':'GROUP_KEY'," + " 'qpid.shared_msg_group':1}}}}") + </programlisting> + </example> + <section role="h3" id="usingmessagegroups-DefaultGroup"> + <title> + Default Group + </title> + <para> + Should a message without a group identifier arrive at a queue configured for message grouping, the broker assigns the message to the default group. Therefore, all such "unidentified" messages are considered by the broker as part of the same group. The name of the default group is <command>"qpid.no-group"</command>. This default can be overridden by suppling a different value to the broker configuration item <command>"default-message-group"</command>: + <example> + <title>Overriding the default message group identifier for the broker</title> + <programlisting> +qpidd --default-msg-group "EMPTY-GROUP" + </programlisting> + </example> + </para> + </section> + </section> + </section> + + + diff --git a/qpid/doc/book/src/cpp-broker/producer-flow-control.xml b/qpid/doc/book/src/cpp-broker/producer-flow-control.xml new file mode 100644 index 0000000000..fd44f51e81 --- /dev/null +++ b/qpid/doc/book/src/cpp-broker/producer-flow-control.xml @@ -0,0 +1,351 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section id="producer-flow-control"> + <title> + Producer Flow Control + </title> + + <section role="h2" id="producerflowcontrol-Overview"> + <title> + Overview + </title> + <para> + As of release 0.10, the C++ broker supports the use of flow control to + throttle back message producers that are at risk of overflowing a + destination queue. + </para> + + <para> + Each queue in the C++ broker has two threshold values associated with it: + </para> + + <para> + Flow Stop Threshold: this is the level of queue resource + utilization above which flow control will be enabled. Once this + threshold is crossed, the queue is considered in danger of overflow. + </para> + + <para> + Flow Resume Threshold - this is the level of queue resource utilization + below which flow control will be disabled. Once this threshold is + crossed, the queue is no longer considered in danger of overflow. + </para> + + <para> + In the above description, queue resource utilization may be + defined as the total count of messages currently enqueued, or the total + sum of all message content in bytes. + </para> + + <para> + The value for a queue's Flow Stop Threshold must be greater than or + equal to the value of the queue's Flow Resume Threshold. + </para> + + <section role="h3" id="producerflowcontrol-QueueThresholdsExample"> + <title> + Example + </title> + + <para> + Let's consider a queue with a maximum limit set on the total number of + messages that may be enqueued to that queue. Assume this maximum + message limit is 1000 messages. Assume also that the user configures a + Flow Stop Threshold of 900 messages, and a Flow Resume Threshold of 500 + messages. Then the following holds: + </para> + + <para> + The queue's initial flow control state is "OFF". + </para> + + <para> + While the total number of enqueued messages is less than or equal to + 900, the queue's flow control state remains "OFF". + </para> + + <para> + When the total number of enqueued messages is greater than 900, the + queue's flow control state transitions to "ON". + </para> + + <para> + When the queue's flow control state is "ON", it remains "ON" until the + total number of enqueued messages is less than 500. At that point, the queue's + flow control state transitions to "OFF". + </para> + + <para> + A similar example using total enqueued content bytes as the threshold + units are permitted. + </para> + </section> + + <para> + Thresholds may be set using both total message counts and total byte + counts. In this case, the following rules apply: + </para> + + <para> + 1) Flow control is "ON" when either stop threshold value is crossed. + </para> + <para> + 2) Flow control remains "ON" until both resume thresholds are satisfied. + </para> + + <section role="h3" id="producerflowcontro-MultiThresholdExample"> + <title> + Example + </title> + + <para> + Let's consider a queue with a maximum size limit of 10K bytes, and 5000 + messages. A user may assign a Flow Stop Threshold based on a total + message count of 4000 messages. They may also assigne a Flow Stop + Threshold of 8K bytes. The queue's flow control state transitions to + "ON" if either threshold is crossed: (total-msgs greater-than 4000 OR total-bytes + greater-than 8K). + </para> + + <para> + Assume the user has assigned Flow Resume threshold's of 3000 messages and + 6K bytes. Then the queue's flow control will remain active until both + thresholds are satified: (total-msg less-than 3000 AND total-bytes less-than 6K). + </para> + </section> + + <para> + The Broker enforces flow control by delaying the completion of the + Message.Transfer command that causes a message to be delivered to a queue + with active flow control. The completion of the Message.Transfer command + is held off until flow control state transitions to "OFF" for all queues + that are a destination for that command. + </para> + + <para> + A message producing client is permitted to have a finite number of + commands pending completion. When the total number of these outstanding + commands reaches the limit, the client must not issue further commands + until one or more of the outstanding commands have completed. This + window of outstanding commands is considered the sender's "capacity". + This allows any given producer to have a "capacity's" worth of messages + blocked due to flow control before the sender must stop sending further + messages. + </para> + + <para> + This capacity window must be considered when determining a suitable + flow stop threshold for a given queue, as a producer may send its + capacity worth of messages _after_ a queue has reached the flow stop + threshold. Therefore, a flow stop threshould should be set such that + the queue can accomodate more messages without overflowing. + </para> + + <para> + For example, assume two clients, C1 and C2, are producing messages to + one particular destination queue. Assume client C1 has a configured + capacity of 50 messages, and client C2's capacity is 15 messages. In + this example, assume C1 and C2 are the only clients queuing messages to + a given queue. If this queue has a Flow Stop Threshold of 100 + messages, then, worst-case, the queue may receive up to 165 messages + before clients C1 and C2 are blocked from sending further messages. + This is due to the fact that the queue will enable flow control on + receipt of its 101'st message - preventing the completion of the + Message.Transfer command that carried the 101'st message. However, C1 + and C2 are allowed to have a total of 65 (50 for C1 and 15 for C2) + messages pending completion of Message.Transfer before they will stop + producing messages. Thus, up to 65 messages may be enqueued beyond the + flow stop threshold before the producers will be blocked. + </para> + </section> + + <section role="h2" id="producerflowcontrol-UserInterface"> + <title> + User Interface + </title> + + <para> + By default, the C++ broker assigns a queue's flow stop and flow resume + thresholds when the queue is created. The C++ broker also allows the + user to manually specify the flow control thresholds on a per queue + basis. + </para> + + <para> + However, queues that have been configured with a Limit Policy of type + RING or RING-STRICT do NOT have queue flow thresholds enabled by + default. The nature of a RING queue defines its behavior when its + capacity is reach: replace the oldest message. + </para> + + <para> + The flow control state of a queue can be determined by the "flowState" + boolean in the queue's QMF management object. The queue's management + object also contains a counter that increments each time flow control + becomes active for the queue. + </para> + + <para> + The broker applies a threshold ratio to compute a queue's default flow + control configuration. These thresholds are expressed as a percentage + of a queue's maximum capacity. There is one value for determining the + stop threshold, and another for determining the resume threshold. The + user may configure these percentages using the following broker + configuration options: + </para> + + <programlisting> + --default-flow-stop-threshold ("Queue capacity level at which flow control is activated.") + --default-flow-resume-threshold ("Queue capacity level at which flow control is de-activated.") + </programlisting> + + <para> + For example: + </para> + + <programlisting> + qpidd --default-flow-stop-threshold=90 --default-flow-resume-threshold=75 + </programlisting> + + <para> + Sets the default flow stop threshold to 90% of a queue's maximum + capacity and the flow resume threshold to 75% of the maximum capacity. + If a queue is created with a default-queue-limit of 10000 bytes, then + the default flow stop threshold would be 90% of 10000 = 9000 bytes and + the flow resume threshold would be 75% of 10000 = 7500. The same + computation is performed should a queue be created with a maximum size + expressed as a message count instead of a byte count. + </para> + + <para> + If not overridden by the user, the value of the + default-flow-stop-threshold is 80% and the value of the + default-flow-resume-threshold is 70%. + </para> + + <para> + The user may disable default queue flow control broker-wide by + specifying the value 0 for both of these configuration options. Note + that flow control may still be applied manually on a per-queue basis in + this case. + </para> + + <para> + The user may manually set the flow thresholds when creating a queue. + The following options may be provided when adding a queue using the + <command>qpid-config</command> command line tool: + </para> + + <programlisting> + --flow-stop-size=<replaceable>N</replaceable> Sets the queue's flow stop threshold to <replaceable>N</replaceable> total bytes. + --flow-resume-size=<replaceable>N</replaceable> Sets the queue's flow resume threshold to <replaceable>N</replaceable> total bytes. + --flow-stop-count=<replaceable>N</replaceable> Sets the queue's flow stop threshold to <replaceable>N</replaceable> total messages. + --flow-resume-count=<replaceable>N</replaceable> Sets the queue's flow resume threshold to <replaceable>N</replaceable> total messages. + </programlisting> + + <para> + Flow thresholds may also be specified in the + <command>queue.declare</command> method, via the + <command>arguments</command> parameter map. The following keys can be + provided in the arguments map for setting flow thresholds: + </para> + + <table> + <title>Queue Declare Method Flow Control Arguments</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Key</entry> + <entry>Value</entry> + </row> + </thead> + <tbody> + <row> + <entry>qpid.flow_stop_size</entry> + <entry>integer - queue's flow stop threshold value in bytes</entry> + </row> + <row> + <entry>qpid.flow_resume_size</entry> + <entry>integer - queue's flow resume threshold value in bytes</entry> + </row> + <row> + <entry>qpid.flow_stop_count</entry> + <entry>integer - queue's flow stop threshold value as a message count</entry> + </row> + <row> + <entry>qpid.flow_resume_count</entry> + <entry>integer - queue's flow resume threshold value as a message count</entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + The user may disable flow control on a per queue basis by setting + the flow-stop-size and flow-stop-count to zero for the queue. + </para> + + <para> + The current state of flow control for a given queue can be + determined by the "flowStopped" statistic. This statistic is + available in the queue's QMF management object. The value of + flowStopped is True when the queue's capacity has exceeded the + flow stop threshold. The value of flowStopped is False when the + queue is no longer blocking due to flow control. + </para> + + <para> + A queue will also track the number of times flow control has been + activated. The "flowStoppedCount" statistic is incremented each time + the queue's capacity exceeds a flow stop threshold. This statistic can + be used to monitor the activity of flow control for any given queue + over time. + </para> + + <table> + <title>Flow Control Statistics available in Queue's QMF Class</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Statistic Name</entry> + <entry>Type</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>flowStopped</entry> + <entry>Boolean</entry> + <entry>If true, producers are blocked by flow control.</entry> + </row> + <row> + <entry>flowStoppedCount</entry> + <entry>count32</entry> + <entry>Number of times flow control was activated for this queue</entry> + </row> + </tbody> + </tgroup> + </table> + </section> + <!--h2--> + </section> diff --git a/qpid/doc/book/src/cpp-broker/queue-state-replication.xml b/qpid/doc/book/src/cpp-broker/queue-state-replication.xml new file mode 100644 index 0000000000..3ffac805eb --- /dev/null +++ b/qpid/doc/book/src/cpp-broker/queue-state-replication.xml @@ -0,0 +1,333 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section id="queue-state-replication"> + <title> + Queue State Replication + </title> + + <section role="h2" id="queuestatereplication-AsynchronousReplicationofQueueState"> + <title> + Asynchronous + Replication of Queue State + </title> + + <section role="h3" id="queuestatereplication-Overview"> + <title> + Overview + </title> + <para> + There is support in qpidd for selective asynchronous replication + of queue state. This is achieved by: + </para> + <para> + (a) enabling event generation for the queues in question + </para> + <para> + (b) loading a plugin on the 'source' broker to encode those + events as messages on a replication queue (this plugin is + called + replicating_listener.so) + </para> + <para> + (c) loading a custom exchange plugin on the 'backup' broker (this + plugin is called replication_exchange.so) + </para> + <para> + (d) creating an instance of the replication exchange type on the + backup broker + </para> + <para> + (e) establishing a federation bridge between the replication + queue on the source broker and the replication exchange on the + backup broker + </para> + <para> + The bridge established between the source and backup brokers for + replication (step (e) above) should have acknowledgements turned + on (this may be done through the --ack N option to qpid-route). + This ensures that replication events are not lost if the bridge + fails. + </para> + <para> + The replication protocol will also eliminate duplicates to ensure + reliably replicated state. Note though that only one bridge per + replication exchange is supported. If clients try to publish to + the replication exchange or if more than a the single required + bridge from the replication queue on the source broker is + created, replication will be corrupted. (Access control may be + used to restrict access and help prevent this). + </para> + <para> + The replicating event listener plugin (step (b) above) has the + following options: + </para> + <programlisting> +Queue Replication Options: + --replication-queue QUEUE Queue on which events for + other queues are recorded + --replication-listener-name NAME (replicator) name by which to register the + replicating event listener + --create-replication-queue if set, the replication will + be created if it does not + exist + </programlisting> + <para> + The name of the queue is required. It can either point to a + durable queue whose definition has been previously recorded, or + the --create-replication-queue option can be specified in which + case the queue will be created a simple non-durable queue if it + does not already exist. + </para> + <!--h3--> + </section> + + <section role="h3" id="queuestatereplication-UsewithClustering"> + <title> + Use with + Clustering + </title> + <para> + The source and/or backup brokers may also be clustered brokers. + In this case the federated bridge will be re-established between + replicas should either of the originally connected nodes fail. + There are however the following limitations at present: + </para> + <itemizedlist> + <listitem> + <para>The backup site does not process membership updates after it + establishes the first connection. In order for newly added + members on a source cluster to be eligible as failover targets, + the bridge must be recreated after those members have been added + to the source cluster. + </para> + </listitem> + </itemizedlist> + <itemizedlist> + <listitem> + <para>New members added to a backup cluster will not receive + information about currently established bridges. Therefore in + order to allow the bridge to be re-established from these members + in the event of failure of older nodes, the bridge must be + recreated after the new members have joined. + </para> + </listitem> + </itemizedlist> + <itemizedlist> + <listitem> + <para>Only a single URL can be passed to create the initial link + from backup site to the primary site. this means that at the time + of creating the initial connection the initial node in the + primary site to which the connection is made needs to be running. + Once connected the backup site will receive a membership update + of all the nodes in the primary site, and if the initial + connection node in the primary fails, the link will be + re-established on the next node that was started (time) on the + primary site. + </para> + </listitem> + </itemizedlist> + <para> + Due to the acknowledged transfer of events over the bridge (see + note above) manual recreation of the bridge and automatic + re-establishment of te bridge after connection failure (including + failover where either or both ends are clustered brokers) will + not result in event loss. + </para> + <!--h3--> + </section> + + <section role="h3" id="queuestatereplication-OperationsonBackupQueues"> + <title> + Operations + on Backup Queues + </title> + <para> + When replicating the state of a queue to a backup broker it is + important to recognise that any other operations performed + directly on the backup queue may break the replication. + </para> + <para> + If the backup queue is to be an active (i.e. accessed by clients + while replication is on) only enqueues should be selected + for + replication. In this mode, any message enqueued on the source + brokers copy of the queue will also be enqueued on the backup + brokers copy. However not attempt will be made to remove messages + from the backup queue in response to removal of messages from the + source queue. + </para> + <!--h3--> + </section> + + <section role="h3" id="queuestatereplication-SelectingQueuesforReplication"> + <title> + Selecting + Queues for Replication + </title> + <para> + Queues are selected for replication by specifying the types of + events they should generate (it is from these events that the + replicating plugin constructs messages which are then pulled and + processed by the backup site). This is done through options + passed to the initial queue-declare command that creates the + queue and may be done either through qpid-config or similar + tools, or by the application. + </para> + <para> + With qpid-config, the --generate-queue-events options is used: + </para> + <programlisting> + --generate-queue-events N + If set to 1, every enqueue will generate an event that can be processed by + registered listeners (e.g. for replication). If set to 2, events will be + generated for enqueues and dequeues + </programlisting> + <para> + From an application, the arguments field of the queue-declare + AMQP command is used to convey this information. An entry should + be added to the map with key 'qpid.queue_event_generation' and an + integer value of 1 (to replicate only enqueue events) or 2 (to + replicate both enqueue and dequeue events). + </para> + <para> + Applications written using the c++ client API may fine the + qpid::client::QueueOptions class convenient. This has a + enableQueueEvents() method on it that can be used to set the + option (the instance of QueueOptions is then passed as the value + of the arguments field in the queue-declare command. The boolean + option to that method should be set to true if only enequeue + events should be replicated; by default it is false meaning that + both enqueues and dequeues will be replicated. E.g. + </para> + <programlisting> + QueueOptions options; + options.enableQueueEvents(false); + session.queueDeclare(arg::queue="my-queue", arg::arguments=options); + </programlisting> + <!--h3--> + </section> + + <section role="h3" id="queuestatereplication-Example"> + <title> + Example + </title> + <para> + Lets assume we will run the primary broker on host1 and the + backup on host2, have installed qpidd on both and have the + replicating_listener and replication_exchange plugins in qpidd's + module directory(*1). + </para> + <para> + On host1 we start the source broker and specifcy that a queue + called 'replication' should be used for storing the events until + consumed by the backup. We also request that this queue be + created (as transient) if not already specified: + </para> + <programlisting> + qpidd --replication-queue replication-queue --create-replication-queue true --log-enable info+ + </programlisting> + <para> + On host2 we start up the backup broker ensuring that the + replication exchange module is loaded: + </para> + <programlisting> + qpidd + </programlisting> + <para> + We can then create the instance of that replication exchange that + we will use to process the events: + </para> + <programlisting> + qpid-config -a host2 add exchange replication replication-exchange + </programlisting> + <para> + If this fails with the message "Exchange type not implemented: + replication", it means the replication exchange module was + not + loaded. Check that the module is installed on your system and if + necessary provide the full path to the library. + </para> + <para> + We then connect the replication queue on the source broker with + the replication exchange on the backup broker using the + qpid-route command: + </para> + <programlisting> + qpid-route --ack 50 queue add host2 host1 replication-exchange replication-queue +</programlisting> + <para> + The example above configures the bridge to acknowledge messages + in batches of 50. + </para> + <para> + Now create two queues (on both source and backup brokers), one + replicating both enqueues and dequeues (queue-a) and the + other + replicating only dequeues (queue-b): + </para> + <programlisting> + qpid-config -a host1 add queue queue-a --generate-queue-events 2 + qpid-config -a host1 add queue queue-b --generate-queue-events 1 + + qpid-config -a host2 add queue queue-a + qpid-config -a host2 add queue queue-b + </programlisting> + <para> + We are now ready to use the queues and see the replication. + </para> + <para> + Any message enqueued on queue-a will be replicated to the backup + broker. When the message is acknowledged by a client connected to + host1 (and thus dequeued), that message will be removed from the + copy of the queue on host2. The state of queue-a on host2 will + thus mirror that of the equivalent queue on host1, albeit with a + small lag. (Note + however that we must not have clients connected to host2 publish + to-or consume from- queue-a or the state will fail to replicate + correctly due to conflicts). + </para> + <para> + Any message enqueued on queue-b on host1 will also be enqueued on + the equivalent queue on host2. However the acknowledgement and + consequent dequeuing of messages from queue-b on host1 will have + no effect on the state of queue-b on host2. + </para> + <para> + (*1) If not the paths in the above may need to be modified. E.g. + if using modules built from a qpid svn checkout, the following + would be added to the command line used to start qpidd on host1: + </para> + <programlisting> + --load-module <path-to-qpid-dir>/src/.libs/replicating_listener.so + </programlisting> + <para> + and the following for the equivalent command line on host2: + </para> + <programlisting> + --load-module <path-to-qpid-dir>/src/.libs/replication_exchange.so + </programlisting> + <!--h3--> + </section> + <!--h2--> + </section> +</section> diff --git a/qpid/doc/book/src/images/qpid-logo.png b/qpid/doc/book/src/images/qpid-logo.png Binary files differnew file mode 100644 index 0000000000..5f4ccc3081 --- /dev/null +++ b/qpid/doc/book/src/images/qpid-logo.png diff --git a/qpid/doc/book/src/old/ACL.xml b/qpid/doc/book/src/old/ACL.xml new file mode 100644 index 0000000000..ceb7cecb23 --- /dev/null +++ b/qpid/doc/book/src/old/ACL.xml @@ -0,0 +1,800 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section id="qpid_ACL"> + <title> + ACL + </title> + + <section role="h2" id="ACL-v2ACLfileformatforbrokers"> + <title> + v2 ACL file format for brokers + </title> + <para> + This new ACL implementation has been designed for implementation + and interoperability on all Qpid brokers. It is currently + supported in the following brokers: + </para> + + <table><title>ACL Support in Qpid Broker Versions</title> + <tgroup cols="2"> + <thead> + <row> + <entry> + Broker + </entry> + <entry> + Version + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + C++ + </entry> + <entry> + M4 onward + </entry> + </row> + <row> + <entry> + Java + </entry> + <entry> + M5 anticipated + </entry> + </row> + </tbody> + </tgroup></table> + + <para> + Contents + </para> + <itemizedlist> + <listitem><para> + <xref linkend="ACL-v2ACLfileformatforbrokers"/> + </para></listitem> + <listitem><para> + <itemizedlist> + <listitem><para> + <xref linkend="ACL-Specification"/> + </para></listitem> + <listitem><para> + <xref linkend="ACL-Validation"/> + </para></listitem> + <listitem><para> + <xref linkend="ACL-Examplefile-3A"/> + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <xref linkend="ACL-DesignDocumentation"/> + </para></listitem> + <listitem><para> + <itemizedlist> + <listitem><para> + <xref linkend="ACL-MappingofACLtrapstoactionandtype"/> + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <xref linkend="ACL-v2ACLUserGuide"/> + </para></listitem> + <listitem><para> + <itemizedlist> + <listitem><para> + <xref linkend="ACL-WritingGood-2FFastACL"/> + </para></listitem> + <listitem><para> + <xref linkend="ACL-GettingACLtoLog"/> + </para></listitem> + <listitem><para> + <xref linkend="ACL-UserId-2FdomainsrunningwithCbroker"/> + </para></listitem> + </itemizedlist> + </para></listitem> + </itemizedlist> + <para> + + </para><section role="h3" id="ACL-Specification"><title> + Specification + </title> + <para> + Notes on file formats + </para><itemizedlist> + <listitem><para>A line starting with the character '#' will be considered a + comment, and are ignored. + </para></listitem> + <listitem><para>Since the '#' char (and others that are commonly used for + comments) are commonly found in routing keys and other AMQP + literals, it is simpler (for now) to hold off on allowing + trailing comments (ie comments in which everything following a + '#' is considered a comment). This could be reviewed later once + the rest of the format is finalized. + </para></listitem> + <listitem><para>Empty lines ("") and lines that contain only whitespace (any + combination of ' ', '\f', '\n', '\r', '\t', '\v') are ignored. + </para></listitem> + <listitem><para>All tokens are case sensitive. "name1" != "Name1" and + "create" != "CREATE". + </para></listitem> + <listitem><para>Group lists may be extended to the following line by + terminating the line with the '\' character. However, this may + only occur after the group name or any of the names following the + group name. Empty extension lines (ie just a '\' character) are + not permitted. + + <programlisting> +# Examples of extending group lists using a trailing '\' character + +group group1 name1 name2 \ + name3 name4 \ + name5 + +group group2 \ + group1 \ + name6 + +# The following are illegal: + +# '\' must be after group name +group \ + group3 name7 name8 + +# No empty extension lines +group group4 name9 \ + \ + name10 +</programlisting> + + </para></listitem> + <listitem><para>Additional whitespace (ie more than one whitespace char) + between and after tokens is ignored. However group and acl + definitions must start with "group" or "acl" respectively and + with no preceding whitespace. + </para></listitem> + <listitem><para>All acl rules are limited to a single line. + </para></listitem> + <listitem><para>Rules are interpreted from the top of the file down until the + name match is obtained; at which point processing stops. + </para></listitem> + <listitem><para>The keyword "all" is reserved, and matches all individuals, + groups and actions. It may be used in place of a group or + individual name and/or an action - eg "acl allow all all", "acl + deny all all" or "acl deny user1 all". + </para></listitem> + <listitem><para>The last line of the file (whether present or not) will be + assumed to be "acl deny all all". If present in the file, any + lines below this one are ignored. + </para></listitem> + <listitem><para>Names and group names may contain only a-z, A-Z, 0-9, + '-','_'. + </para></listitem> + <listitem><para>Rules must be preceded by any group definitions they may use; + any name not previously defined as a group will be assumed to be + that of an individual. + </para></listitem> + <listitem><para>ACL rules must have the following tokens in order on a single + line: + <itemizedlist> + <listitem><para>The string literal "acl"; + </para></listitem> + <listitem><para>The permission; + </para></listitem> + <listitem><para>The name of a single group or individual or the keyword + "all"; + </para></listitem> + <listitem><para>The name of an action or the keyword "all"; + </para></listitem> + <listitem><para>Optionally, a single object name or the keyword "all"; + </para></listitem> + <listitem><para>If the object is present, then optionally one or more + property name-value pair(s) (in the form property=value). + </para></listitem> + </itemizedlist> + </para></listitem> + </itemizedlist> + <programlisting> +user = username[@domain[/realm]] +user-list = user1 user2 user3 ... +group-name-list = group1 group2 group3 ... + +group <group-name> = [user-list] [group-name-list] + + +permission = [allow|allow-log|deny|deny-log] +action = [consume|publish|create|access|bind|unbind|delete|purge|update] +object = [virtualhost|queue|exchange|broker|link|route|method] +property = [name|durable|owner|routingkey|passive|autodelete|exclusive|type|alternate|queuename|schemapackage|schemaclass] + +acl permission {<group-name>|<user-name>|"all"} {action|"all"} [object|"all"] [property=<property-value>] +</programlisting> +<!--h3--></section> + <section role="h3" id="ACL-Validation"><title> + Validation + </title> + <para> + The new ACL file format needs to perform validation on the acl + rules. The validation should be performed depending on the set + value: + </para><para> + strict-acl-validation=none + The default setting should be 'warn' + </para><para> + On validation of this acl the following checks would be expected: + </para> + <programlisting> +acl allow client publish routingkey=exampleQueue exchange=amq.direct +</programlisting> + <orderedlist> + <listitem><para>The If the user 'client' cannot be found, if the + authentication mechanism cannot be queried then a 'user' value + should be added to the file. + </para></listitem> + <listitem><para>There is an exchange called 'amq.direct' + </para></listitem> + <listitem><para>There is a queue bound to 'exampleQueue' on 'amq.direct' + </para></listitem> + </orderedlist><para> + Each of these checks that fail will result in a log statement + being generated. + </para><para> + In the case of a fatal logging the full file will be validated + before the broker shuts down. + </para> +<!--h3--></section> + + + <section role="h3" id="ACL-Examplefile-3A"><title> + Example file: + </title> + + <programlisting> + +# Some groups +group admin ted@QPID martin@QPID +group user-consume martin@QPID ted@QPID +group group2 kim@QPID user-consume rob@QPID +group publisher group2 \ + tom@QPID andrew@QPID debbie@QPID + +# Some rules +acl allow carlt@QPID create exchange name=carl.* +acl deny rob@QPID create queue +acl allow guest@QPID bind exchange name=amq.topic routingkey=stocks.ibm.# owner=self +acl allow user-consume create queue name=tmp.* + +acl allow publisher publish all durable=false +acl allow publisher create queue name=RequestQueue +acl allow consumer consume queue durable=true +acl allow fred@QPID create all +acl allow bob@QPID all queue +acl allow admin all +acl deny kim@QPID all +acl allow all consume queue owner=self +acl allow all bind exchange owner=self + +# Last (default) rule +acl deny all all +</programlisting> + +<!--h3--></section> + <!--h2--></section> + + + <section role="h2" id="ACL-DesignDocumentation"><title> + Design Documentation + </title> + <section role="h3" id="ACL-MappingofACLtrapstoactionandtype"><title> + Mapping of ACL + traps to action and type + </title> + <para> + The C++ broker maps the ACL traps in the follow way for AMQP + 0-10: + The Java broker currently only performs ACLs on the AMQP + connection not on management functions: + </para> + + <table> + <title>Mapping ACL Traps</title> + <tgroup cols="5"> + <thead> + <row> + <entry> + Object + </entry> + <entry> + Action + </entry> + <entry> + Properties + </entry> + <entry> + Trap C++ + </entry> + <entry> + Trap Java + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + Exchange + </entry> + <entry> + Create + </entry> + <entry> + name type alternate passive durable + </entry> + <entry> + ExchangeHandlerImpl::declare + </entry> + <entry> + ExchangeDeclareHandler + </entry> + </row> + <row> + <entry> + Exchange + </entry> + <entry> + Delete + </entry> + <entry> + name + </entry> + <entry> + ExchangeHandlerImpl::delete + </entry> + <entry> + ExchangeDeleteHandler + </entry> + </row> + <row> + <entry> + Exchange + </entry> + <entry> + Access + </entry> + <entry> + name + </entry> + <entry> + ExchangeHandlerImpl::query + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + Exchange + </entry> + <entry> + Bind + </entry> + <entry> + name routingkey queuename owner + </entry> + <entry> + ExchangeHandlerImpl::bind + </entry> + <entry> + QueueBindHandler + </entry> + </row> + <row> + <entry> + Exchange + </entry> + <entry> + Unbind + </entry> + <entry> + name routingkey + </entry> + <entry> + ExchangeHandlerImpl::unbind + </entry> + <entry> + ExchangeUnbindHandler + </entry> + </row> + <row> + <entry> + Exchange + </entry> + <entry> + Access + </entry> + <entry> + name queuename routingkey + </entry> + <entry> + ExchangeHandlerImpl::bound + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + Exchange + </entry> + <entry> + Publish + </entry> + <entry> + name routingKey + </entry> + <entry> + SemanticState::route + </entry> + <entry> + BasicPublishMethodHandler + </entry> + </row> + <row> + <entry> + Queue + </entry> + <entry> + Access + </entry> + <entry> + name + </entry> + <entry> + QueueHandlerImpl::query + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + Queue + </entry> + <entry> + Create + </entry> + <entry> + name alternate passive durable exclusive autodelete + </entry> + <entry> + QueueHandlerImpl::declare + </entry> + <entry> + QueueDeclareHandler + </entry> + </row> + <row> + <entry> + Queue + </entry> + <entry> + Purge + </entry> + <entry> + name + </entry> + <entry> + QueueHandlerImpl::purge + </entry> + <entry> + QueuePurgeHandler + </entry> + </row> + <row> + <entry> + Queue + </entry> + <entry> + Purge + </entry> + <entry> + name + </entry> + <entry> + Management::Queue::purge + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + Queue + </entry> + <entry> + Delete + </entry> + <entry> + name + </entry> + <entry> + QueueHandlerImpl::delete + </entry> + <entry> + QueueDeleteHandler + </entry> + </row> + <row> + <entry> + Queue + </entry> + <entry> + Consume + </entry> + <entry> + name (possibly add in future?) + </entry> + <entry> + MessageHandlerImpl::subscribe + </entry> + <entry> + BasicConsumeMethodHandler + BasicGetMethodHandler + </entry> + </row> + <row> + <entry> + <Object> + </entry> + <entry> + Update + </entry> + <entry> + + </entry> + <entry> + ManagementProperty::set + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + <Object> + </entry> + <entry> + Access + </entry> + <entry> + + </entry> + <entry> + ManagementProperty::read + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + Link + </entry> + <entry> + Create + </entry> + <entry> + + </entry> + <entry> + Management::connect + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + Route + </entry> + <entry> + Create + </entry> + <entry> + + </entry> + <entry> + Management:: -createFederationRoute- + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + Route + </entry> + <entry> + Delete + </entry> + <entry> + + </entry> + <entry> + Management:: -deleteFederationRoute- + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + Virtualhost + </entry> + <entry> + Access + </entry> + <entry> + name + </entry> + <entry> + TBD + </entry> + <entry> + ConnectionOpenMethodHandler + </entry> + </row> + </tbody> + </tgroup></table><para> + Management actions that are not explicitly given a name property + it will default the name property to management method name, if + the action is 'W' Action will be 'Update', if 'R' Action will be + 'Access'. + </para><para> + for example, if the mgnt method 'joinCluster' was not mapped in + schema it will be mapped in ACL file as follows + </para> + + <table> + <title>Mapping Management Actions to ACL</title> + <tgroup cols="3"> + <thead> + <row> + <entry> + Object + </entry> + <entry> + Action + </entry> + <entry> + Property + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + Broker + </entry> + <entry> + Update + </entry> + <entry> + name=joinCluster + </entry> + </row> + </tbody> + </tgroup></table> + + <!--h3--></section> + <!--h2--></section> + + + <section role="h2" id="ACL-v2ACLUserGuide"><title> + v2 ACL User Guide + </title> + <section role="h3" id="ACL-WritingGood-2FFastACL"><title> + Writing Good/Fast ACL + </title> + <para> + The file gets read top down and rule get passed based on the + first match. In the following example the first rule is a dead + rule. I.e. the second rule is wider than the first rule. DON'T do + this, it will force extra analysis, worst case if the parser does + not kill the dead rule you might get a false deny. + </para> + <programlisting> +allow peter@QPID create queue name=tmp <-- dead rule!! +allow peter@QPID create queue +deny all all +</programlisting> + <para> + By default files end with + </para> + <programlisting> +deny all all +</programlisting> + <para> + the mode of the ACL engine can be swapped to be allow based by + putting the following at the end of the file + </para> + <programlisting> +allow all all +</programlisting> + <para> + Note that 'allow' based file will be a LOT faster for message + transfer. This is because the AMQP specification does not allow + for creating subscribes on publish, so the ACL is executed on + every message transfer. Also, ACL's rules using less properties + on publish will in general be faster. + </para> + <!--h3--></section> + + <section role="h3" id="ACL-GettingACLtoLog"><title> + Getting ACL to Log + </title> + <para> + In order to get log messages from ACL actions use allow-log and + deny-log for example + </para> + <programlisting> +allow-log john@QPID all all +deny-log guest@QPID all all +</programlisting> + <!--h3--></section> + + <section role="h3" id="ACL-UserId-2FdomainsrunningwithCbroker"><title> + User Id / + domains running with C++ broker + </title> + <para> + The user-id used for ACL is taken from the connection user-id. + Thus in order to use ACL the broker authentication has to be + setup. i.e. (if --auth no is used in combination with ACL the + broker will deny everything) + </para><para> + The user id in the ACL file is of the form + <user-id>@<domain> The Domain is configured via the + SASL configuration for the broker, and the domain/realm for qpidd + is set using --realm and default to 'QPID'. + </para><para> + To load the ACL module use, load the acl module cmd line or via + the config file + </para> + <programlisting> +./src/qpidd --load-module src/.libs/acl.so +</programlisting> + <para> + The ACL plugin provides the following option '--acl-file'. If do + ACL file is supplied the broker will not enforce ACL. If an ACL + file name is supplied, and the file does not exist or is invalid + the broker will not start. + </para> + <programlisting> +ACL Options: + --acl-file FILE The policy file to load from, loaded from data dir +</programlisting> + + <!--h3--></section> + <!--h2--></section> + +</section> diff --git a/qpid/doc/book/src/old/AMQP-.NET-Messaging-Client.xml b/qpid/doc/book/src/old/AMQP-.NET-Messaging-Client.xml new file mode 100644 index 0000000000..1d4001942b --- /dev/null +++ b/qpid/doc/book/src/old/AMQP-.NET-Messaging-Client.xml @@ -0,0 +1,108 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<chapter> + <title> + AMQP .NET Messaging Client + </title> + <para> + Currently the .NET code base provides two client libraries that + are compatible respectively with AMQP 0.8 and 0.10. The 0.8 client + is located in <filename>qpid\dotnet</filename> and the 0.10 client + in: <filename>qpid\dotnet\client-010</filename>. + </para> + <para> + You will need an AMQP broker to fully use those client libraries. + Use M4 or later C++ broker for AMQP 0.10 or Java broker for AMQP + 0.8/0.9. + </para> + <section role="h3" id="AMQP.NETMessagingClient-UserGuides"> + <title> + User Guides + </title> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="NET-User-Guide.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Excel-AddIn.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="WCF.xml"/> + </section> + + <section role="h3" id="AMQP.NETMessagingClient-Examples"> + <title> + Examples + </title> + <itemizedlist> + <listitem> + <para> + <ulink url="http://svn.apache.org/viewvc/qpid/trunk/qpid/dotnet/client-010/examples/"/> + </para> + </listitem> + </itemizedlist> + <!--h3--> + </section> + +<!-- + + <section role="h3" id="AMQP.NETMessagingClient-DeveloperGuidelines"> + <title> + Developer Guidelines + </title> + <itemizedlist> + <listitem> + <para> + <xref linkend="qpid_Developer-Pages"/> + </para> + </listitem> + <listitem> + <para>Coding Standards </para> + </listitem> + <listitem> + <para>How Tos + <itemizedlist> + <listitem> + <para> + <xref linkend="qpid_Build-.NET-Client"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="qpid_Releasing"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="qpid_Run-tests"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="qpid_Setup-.Net-Client-on-Windows"/> + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + </section> + --> + + +</chapter> diff --git a/qpid/doc/book/src/old/AMQP-C++-Messaging-Client.xml b/qpid/doc/book/src/old/AMQP-C++-Messaging-Client.xml new file mode 100644 index 0000000000..73a2cd6c0b --- /dev/null +++ b/qpid/doc/book/src/old/AMQP-C++-Messaging-Client.xml @@ -0,0 +1,61 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<chapter > + <title> + AMQP C++ Messaging Client + </title> + <section role="h3" id="AMQPCPPMessagingClient-UserGuides"> + <title> + User Guides + </title> + <itemizedlist> + <listitem> + <para> + <ulink url="http://qpid.apache.org/docs/api/cpp/html/index.html">C++ Client API (AMQP 0-10)</ulink> + </para> + </listitem> + </itemizedlist> + <!--h3--> + </section> + + <section role="h3" id="AMQPCPPMessagingClient-Examples"> + <title> + Examples + </title> + <itemizedlist> + <listitem> + <para> + <ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/cpp/examples/">AMQP C++ Client Examples </ulink> + </para> + </listitem> + <listitem> + <para> + <ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/cpp/examples/README.txt">Running the AMQP C++ Client Examples </ulink> + </para> + </listitem> + </itemizedlist> + <!--h3--> + </section> + + +</chapter> diff --git a/qpid/doc/book/src/old/AMQP-Java-JMS-Messaging-Client.xml b/qpid/doc/book/src/old/AMQP-Java-JMS-Messaging-Client.xml new file mode 100644 index 0000000000..8c14d67e14 --- /dev/null +++ b/qpid/doc/book/src/old/AMQP-Java-JMS-Messaging-Client.xml @@ -0,0 +1,94 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<chapter> + + <title> + AMQP Java JMS Messaging Client + </title> + + <para>The Java Client supported by Qpid implements the <ulink + url="http://java.sun.com/products/jms/docs.html">Java JMS 1.1 + Specification</ulink>. </para> + + + <section role="h3" + id="AMQPJavaJMSMessagingClient-GeneralUserGuides"> + <title>General User Guides</title> + + +<!-- +Does not seem to exist! + + <listitem><para>AMQP Java JMS Client Feature Guide + </para></listitem> + +http://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=qpid&title=JMS-Client-Feature-Guide&linkCreation=true&fromPageId=4589057 +--> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="System-Properties.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Connection-URL-Format.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Binding-URL-Format.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-JMS-Selector-Syntax.xml"/> + +<!-- + <listitem><para>How to Use JNDI to configure the AMQP Java JMS Client + </para></listitem> + <listitem><para>Using the AMQP Java JMS Client with RT Java + </para></listitem> + <listitem><para>AMQP Java JMS Client Tuning Guide + </para></listitem> +--> + +<!--h3--></section> + + <section role="h3" id="AMQPJavaJMSMessagingClient-AMQPJavaJMSExamples"> + + <title>AMQP Java JMS Examples </title> + + <itemizedlist> + <listitem><para> + <ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/java/client/example/">Examples Directory</ulink> + </para></listitem> + + <listitem><para> + <ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/java/client/example/src/main/java/runSample.sh">Script for running examples</ulink> + </para></listitem> + <listitem><para> + <ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/java/client/example/src/main/java/org/apache/qpid/example/jmsexample/direct/">Direct Example</ulink> + </para></listitem> + <listitem><para> + <ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/java/client/example/src/main/java/org/apache/qpid/example/jmsexample/fanout/">Fanout Example</ulink> + </para></listitem> + <listitem><para> + <ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/java/client/example/src/main/java/org/apache/qpid/example/jmsexample/pubsub">Pub-Sub Example</ulink> + </para></listitem> + <listitem><para> + <ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/java/client/example/src/main/java/org/apache/qpid/example/jmsexample/requestResponse/">Request/Response Example</ulink> + </para></listitem> + <listitem><para> + <ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/java/client/example/src/main/java/org/apache/qpid/example/jmsexample/transacted/">Transacted Example</ulink></para></listitem> + </itemizedlist> + +<!--h3--></section> + +</chapter> diff --git a/qpid/doc/book/src/old/AMQP-Messaging-Broker-CPP.xml b/qpid/doc/book/src/old/AMQP-Messaging-Broker-CPP.xml new file mode 100644 index 0000000000..b4e0deb13d --- /dev/null +++ b/qpid/doc/book/src/old/AMQP-Messaging-Broker-CPP.xml @@ -0,0 +1,70 @@ +<?xml version="1.0"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<part> + <title>AMQP Messaging Broker (Implemented in C++)</title> + <partintro> + <para>Qpid provides two AMQP messaging brokers:</para> + + <itemizedlist> + <listitem><para>Implemented in C++ - high performance, low latency, and RDMA support.</para></listitem> + <listitem><para>Implemented in Java - Fully JMS compliant, runs on any Java platform.</para></listitem> + </itemizedlist> + + <para>Both AMQP messaging brokers support clients in multiple languages, as long as the messaging client and the messaging broker use the same version of AMQP. See <link linkend="AMQP-Compatibility"/> to see which messaging clients work with each broker.</para> + + <para>This section contains information specific to the broker that is implemented in C++.</para> + </partintro> + +<chapter> + <title> + Running the AMQP Messaging Broker + </title> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Running-CPP-Broker.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Cheat-Sheet-for-configuring-Queue-Options.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Cheat-Sheet-for-configuring-Exchange-Options.xml"/> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Using-Broker-Federation.xml"/> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="SSL.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="LVQ.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="queue-state-replication.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Active-Active-Cluster.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ACL.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="producer-flow-control.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Using-message-groups.xml"/> +</chapter> + + +<chapter id="chapter-Managing-CPP-Broker"> + <title> + Managing the AMQP Messaging Broker + </title> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Managing-CPP-Broker.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="QMan-Qpid-Management-bridge.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Qpid-Management-Framework.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Management-Design-notes.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="QMF-Python-Console-Tutorial.xml"/> +</chapter> +</part> diff --git a/qpid/doc/book/src/old/AMQP-Python-Messaging-Client.xml b/qpid/doc/book/src/old/AMQP-Python-Messaging-Client.xml new file mode 100644 index 0000000000..15baf214ec --- /dev/null +++ b/qpid/doc/book/src/old/AMQP-Python-Messaging-Client.xml @@ -0,0 +1,62 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<chapter> + <title> + AMQP Python Messaging Client + </title> + <section role="h3" id="AMQPPythonMessagingClient-UserGuides"> + <title> + User Guides + </title> + <itemizedlist> + <listitem> + <para> + <ulink url="http://qpid.apache.org/docs/api/python/html/index.html">Python Client API Guide</ulink> + </para> + </listitem> + </itemizedlist> + <!--h3--> + </section> + + <section role="h3" id="AMQPPythonMessagingClient-Examples"> + <title> + Examples + </title> + <itemizedlist> + <listitem> + <para> + <ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/python/examples/">AMQP Python Client Examples </ulink> + </para> + </listitem> + <listitem> + <para> + <ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/python/examples/README">Running the AMQP Python Client Examples </ulink> + </para> + </listitem> + </itemizedlist> + <!--h3--> + </section> + + <xi:include href="PythonBrokerTest.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + +</chapter> diff --git a/qpid/doc/book/src/old/AMQP-Ruby-Messaging-Client.xml b/qpid/doc/book/src/old/AMQP-Ruby-Messaging-Client.xml new file mode 100644 index 0000000000..45318c0beb --- /dev/null +++ b/qpid/doc/book/src/old/AMQP-Ruby-Messaging-Client.xml @@ -0,0 +1,40 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<chapter> + <title> + AMQP Ruby Messaging Client + </title> + <para> + The Ruby Messaging Client currently has little documentation and + few examples. + </para> + <section role="h3" id="AMQPRubyMessagingClient-Examples"> + <title> + Examples + </title> + <para> + <ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/ruby/examples">AMQP Ruby Messaging Client Examples</ulink> + </para> + <!--h3--> + </section> +</chapter> diff --git a/qpid/doc/book/src/old/AMQP.xml b/qpid/doc/book/src/old/AMQP.xml new file mode 100644 index 0000000000..1a609649bb --- /dev/null +++ b/qpid/doc/book/src/old/AMQP.xml @@ -0,0 +1,98 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<chapter> + +<title>AMQP (Advanced Message Queueing Protocol</title> + + +<para>AMQP <ulink url="http://www.amqp.org/" >Advanced +Message Queuing Protocol</ulink> is an open standard designed to +support reliable, high-performance messaging over the Internet. +AMQP can be used for any distributed or business application, and +supports common messaging paradigms like point-to-point, fanout, +publish-subscribe, and request-response.</para> +<para>Apache Qpid implements AMQP, including transaction management, +queuing, clustering, federation, security, management and +multi-platform support.</para> +<para>Apache Qpid implements the latest AMQP specification, providing +transaction management, queuing, distribution, security, +management, clustering, federation and heterogeneous multi-platform +support and a lot more.</para> +<para>Apache Qpid is highly optimized, and <ulink url= +"amqp-compatibility.html">aims to be 100% AMQP Compliant</ulink>.</para> + +<section> +<title>Download the AMQP Specifications</title> + +<itemizedlist> +<title>AMQP version 0-10</title> +<listitem><para><ulink url="https://jira.amqp.org/confluence/download/attachments/720900/amqp.0-10.pdf?version=1" +>AMQP 0-10 Specification (PDF)</ulink></para></listitem> +<listitem><para><ulink url="https://jira.amqp.org/confluence/download/attachments/720900/amqp.0-10.xml?version=1" +>AMQP 0-10 Protocol Definition XML</ulink></para></listitem> +<listitem><para><ulink url="https://jira.amqp.org/confluence/download/attachments/720900/amqp.0-10.dfd?version=1" +>AMQP 0-10 Protocol Definition DTD</ulink></para></listitem> +</itemizedlist> + + +<itemizedlist> +<title>AMQP version 0-9-1</title> +<listitem><para><ulink url= +"https://jira.amqp.org/confluence/download/attachments/720900/amqp0-9-1.pdf?version=1" +>AMQP 0-9-1 Specification (PDF)</ulink></para></listitem> +<listitem><para><ulink url= +"https://jira.amqp.org/confluence/download/attachments/720900/amqp0-9-1.xml?version=1" +>AMQP 0-9-1 Protocol Documentation (PDF)</ulink></para></listitem> +<listitem><para><ulink url= +"https://jira.amqp.org/confluence/download/attachments/720900/amqp0-9-1.dtd?version=1" +>AMQP 0-9-1 Protocol Definitions (XML)</ulink></para></listitem> +</itemizedlist> + + +<itemizedlist> +<title>AMQP version 0-9</title> +<listitem><para><ulink url= +"https://jira.amqp.org/confluence/download/attachments/720900/amqp0-9.pdf?version=1" +>AMQP 0-9 Specification (PDF)</ulink></para></listitem> +<listitem><para><ulink url= +"https://jira.amqp.org/confluence/download/attachments/720900/amqp0-9.xml?version=1" +>AMQP 0-9 Protocol Documentation (PDF)</ulink></para></listitem> +<listitem><para><ulink url= +"https://jira.amqp.org/confluence/download/attachments/720900/amqp0-9.dtd?version=1" +>AMQP 0-9 Protocol Definitions (XML)</ulink></para></listitem> +</itemizedlist> + + +<itemizedlist> +<title>AMQP version 0-8</title> +<listitem><para><ulink url= +"https://jira.amqp.org/confluence/download/attachments/720900/amqp0-8.pdf?version=1" +>AMQP 0-8 Specification (PDF)</ulink></para></listitem> +<listitem><para><ulink url="https://jira.amqp.org/confluence/download/attachments/720900/amqp0-8.dtd?version=1" +>AMQP 0-8 Protocol Documentation (PDF)</ulink></para></listitem> +<listitem><para><ulink url="https://jira.amqp.org/confluence/download/attachments/720900/amqp0-8.xml?version=1" +>AMQP 0-8 Protocol Definitions (XML)</ulink></para></listitem> +</itemizedlist> +</section> + +</chapter> diff --git a/qpid/doc/book/src/old/Binding-URL-Format.xml b/qpid/doc/book/src/old/Binding-URL-Format.xml new file mode 100644 index 0000000000..3d938b740a --- /dev/null +++ b/qpid/doc/book/src/old/Binding-URL-Format.xml @@ -0,0 +1,174 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section id="BindingURLFormat"> + <title> + Binding URL Format + </title> + <programlisting> +<Exchange Class>://<Exchange Name>/[<Destination>]/[<Queue>][?<option>='<value>'[&<option>='<value>']] +</programlisting> + <para> + This URL format is used for two purposes in the code base. The + broker uses this in the XML configuration file to create and bind + queues at broker startup. It is also used by the client as a + destination. + </para><para> + This format was used because it allows an explicit description of + exchange and queue relationship. + </para><para> + The Exchange Class is not normally required for client connection + as clients only publish to a named exchange however if exchanges + are being dynamically instantiated it will be required. The class + is required for the server to instantiate an exchange. + </para><para> + There are a number of options that are currently defined: + </para><table><title>Binding URL Options</title><tgroup cols="3"> + <tbody> + <row> + <entry> + Option + </entry> + <entry> + type + </entry> + <entry> + Description + </entry> + </row> + <row> + <entry> + exclusive + </entry> + <entry> + boolean + </entry> + <entry> + Is this an exclusive connection + </entry> + </row> + <row> + <entry> + autodelete + </entry> + <entry> + boolean + </entry> + <entry> + Should this queue be deleted on client disconnection + </entry> + </row> + <row> + <entry> + durable + </entry> + <entry> + boolean + </entry> + <entry> + Create a durable queue + </entry> + </row> + <row> + <entry> + clientid + </entry> + <entry> + string + </entry> + <entry> + Use the following client id + </entry> + </row> + <row> + <entry> + subscription + </entry> + <entry> + boolean + </entry> + <entry> + Create a subscription to this destination + </entry> + </row> + <row> + <entry> + routingkey + </entry> + <entry> + string + </entry> + <entry> + Use this value as the routing key + </entry> + </row> + </tbody> + </tgroup></table><para> + Using these options in conjunction with the Binding URL format + should allow future expansion as new and custom exchange types + are created. + </para><para> + The URL format requires <emphasis>that at least one</emphasis> Queue or + routingkey option be present on the URL. + </para><para> + The routingkey would be used to encode a topic as shown in the + examples section below. + </para> + + <section role="h4" id="BindingURLFormat-Examples"> + <title> + Examples + </title> + +<example> +<title> Queues</title> + <para> + A queue can be created in QPID using the following URL format. + </para><para> + direct://amq.direct//<Queue Name> + </para><para> + For example: direct://amq.direct//simpleQueue + </para><para> + Queue names may consist of any mixture of digits, letters, and + underscores. + </para> +</example> +<example> +<title>Topics</title> + <para> + A topic can be created in QPID using the following URL format. + </para><para> + topic://amq.topic/<Topic Subscription>/ + </para><para> + The topic subscription may only contain the letters A-Z and a-z + and digits 0-9. + </para> + <programlisting> +direct://amq.direct/SimpleQueue +direct://amq.direct/UnusuallyBoundQueue?routingkey='/queue' +topic://amq.topic?routingkey='stocks.#' +topic://amq.topic?routingkey='stocks.nyse.ibm' +</programlisting> +</example> +<!--h4--></section> +</section> diff --git a/qpid/doc/book/src/old/Book-Info.xml b/qpid/doc/book/src/old/Book-Info.xml new file mode 100644 index 0000000000..2e02fbe8ea --- /dev/null +++ b/qpid/doc/book/src/old/Book-Info.xml @@ -0,0 +1,68 @@ +<?xml version='1.0' encoding='utf-8' ?> + +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<bookinfo id="book-Messaging_Installation_Guide-Messaging_Installation_Guide"> + <title>Apache Qpid</title> + <subtitle>Open Source AMQP Messaging</subtitle> + <edition>1</edition> + <pubsnumber>0</pubsnumber> + <productname>Apache Qpid</productname> + <productnumber>6</productnumber> + <corpauthor> + <inlinemediaobject> + <imageobject> + <imagedata fileref="Common_Content/images/qpid-logo.png" format="PNG" /> + </imageobject> + </inlinemediaobject> + </corpauthor> + + <copyright> + <year>2010</year> + <holder>The Apache Software Foundation</holder> + </copyright> + + <legalnotice> + <para>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</para> + + <para><filename>http://www.apache.org/licenses/LICENSE-2.0</filename></para> + + <para>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. + </para> + + + </legalnotice> + +</bookinfo> + + diff --git a/qpid/doc/book/src/old/Book.xml b/qpid/doc/book/src/old/Book.xml new file mode 100644 index 0000000000..ee69532152 --- /dev/null +++ b/qpid/doc/book/src/old/Book.xml @@ -0,0 +1,93 @@ +<?xml version='1.0' encoding='utf-8' ?> + +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<book> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Book-Info.xml"/> + <part> + <title>Basics</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Introduction.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Getting-Started.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Download.xml"/> + </part> + +<!-- + The broker sections define their own <part/> elements, with <partintro/> text. +--> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Messaging-Broker-CPP.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Messaging-Broker-Java.xml"/> + + <part> + <title>AMQP Messaging Clients Clients</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Java-JMS-Messaging-Client.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-C++-Messaging-Client.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-.NET-Messaging-Client.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Python-Messaging-Client.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Ruby-Messaging-Client.xml"/> + + </part> + <part> + <title>Appendices</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Compatibility.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Qpid-Interoperability-Documentation.xml"/> +<!-- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="FAQ.xml"/> --> + </part> +</book> + +<!-- +Documentation +Getting Started + + * Download + * Getting Started + +AMQP (Advanced Message Queueing Protocol) + + * Toward a Commodity Enterprise Middleware + * AMQP (Advanced Message Queueing Protocol) + +Qpid AMQP Brokers + + * AMQP Messaging Broker (implemented in C++) + * AMQP Messaging Broker (implemented in Java) + +Qpid AMQP Clients + + * AMQP Java JMS Messaging Client + * AMQP C++ Messaging Client + * AMQP .NET Messaging Client + * AMQP Python Messaging Client + * AMQP Ruby Messaging Client + +Interoperability + + * AMQP Compatibility + * SASL Interoperability + +FAQ + + * Frequently Asked Questions +--> diff --git a/qpid/doc/book/src/old/Broker-CPP.xml b/qpid/doc/book/src/old/Broker-CPP.xml new file mode 100644 index 0000000000..99584be23d --- /dev/null +++ b/qpid/doc/book/src/old/Broker-CPP.xml @@ -0,0 +1,40 @@ +<!-- + - + - Licensed to the Apache Software Foundation (ASF) under one + - or more contributor license agreements. See the NOTICE file + - distributed with this work for additional information + - regarding copyright ownership. The ASF licenses this file + - to you 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. + - + --> +h1. Running the AMQP Messaging Broker + +* [Running an AMQP 0-10 C++ broker | RASC] +* [Configuring Queue Options|Cheat Sheet for configuring Queue Options] +* [Configuring Exchange Options|Cheat Sheet for configuring Exchange Options] +* [Using Broker Federation] +* [How to use SSL | SSL] +* [Understanding Last Value Queues (LVQ) |LVQ] +* [Queue State Replication|queue state replication] +* [Getting Started] +* [Starting a cluster] +* [Understanding Access Control Lists|Qpid ACLs] + +h2. Management + +* [Managing| MgmtC++] the C++ Broker +* [QMan - Qpid Management bridge] +* [Qpid Management Framework] +* [Qpid Management Framework (QMF) Protocol|management design notes] +* [Manage anything with Qpid - QMF Python Console Tutorial|QMF Python Console Tutorial] diff --git a/qpid/doc/book/src/old/Broker-Java.xml b/qpid/doc/book/src/old/Broker-Java.xml new file mode 100644 index 0000000000..f8ce89b185 --- /dev/null +++ b/qpid/doc/book/src/old/Broker-Java.xml @@ -0,0 +1,45 @@ +<!-- + - + - Licensed to the Apache Software Foundation (ASF) under one + - or more contributor license agreements. See the NOTICE file + - distributed with this work for additional information + - regarding copyright ownership. The ASF licenses this file + - to you 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. + - + --> +h3. General User Guides + +* [Feature Guide| Java Broker Feature Guide] +* [FAQ|Qpid Java FAQ] +* [Getting Started Guide] +* [Broker Environment Variables|Java Environment Variables] +* [Troubleshooting Guide|Qpid Troubleshooting Guide] + +h3. How Tos +* [Add New Users] +* [Configure ACLs] +* [Configure Java Qpid to use a SSL connection.] +* [Configure Log4j CompositeRolling Appender] +* [Configure the Broker via config.xml] +* [Configure the Virtual Hosts via virtualhosts.xml] +* [Debug using log4j] +* [How to Tune M3 Java Broker Performance] +* [Qpid Java Build How To] +* [Use Priority Queues] + +h3. Management Tools +* [Qpid JMX Management Console] +* [MessageStore Tool] +* [Qpid Java Broker Management CLI] +* [Management Design notes] diff --git a/qpid/doc/book/src/old/Clients.xml b/qpid/doc/book/src/old/Clients.xml new file mode 100644 index 0000000000..3dc2d38e86 --- /dev/null +++ b/qpid/doc/book/src/old/Clients.xml @@ -0,0 +1,25 @@ +<!-- + - + - Licensed to the Apache Software Foundation (ASF) under one + - or more contributor license agreements. See the NOTICE file + - distributed with this work for additional information + - regarding copyright ownership. The ASF licenses this file + - to you 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. + - + --> +[AMQP Java JMS Messaging Client] +[AMQP C++ Messaging Client] +[AMQP .NET Messaging Client] +[AMQP Python Messaging Client] +[AMQP Ruby Messaging Client] diff --git a/qpid/doc/book/src/old/Connection-URL-Format.xml b/qpid/doc/book/src/old/Connection-URL-Format.xml new file mode 100644 index 0000000000..cb772487cd --- /dev/null +++ b/qpid/doc/book/src/old/Connection-URL-Format.xml @@ -0,0 +1,387 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section id="Connection-URL-Format"> + <title> + Connection URL Format + </title> + + <section role="h4" id="ConnectionURLFormat-Format"> + <title> + Format + </title> + <programlisting> +amqp://[<user>:<pass>@][<clientid>]<virtualhost>[?<option>='<value>'[&<option>='<value>']] + </programlisting> + <para> + The connection url defines the values that are common across + the cluster of brokers. The virtual host is second in the list + as the AMQP specification demands that it start with a '/' + otherwise it be more readable to be swapped with + clientid. There is currently only one required option and that + is the <emphasis>brokerlist</emphasis> option. In addition the + following options are recognised. </para> +<!--h4--></section> + + + <section role="h4" id="ConnectionURLFormat-WorkedExample"> + + <title> Worked Example </title> + + + + <para> You could use a URL which looks something like this: + </para> + +<programlisting> +amqp://guest:guest@client1/development?brokerlist='tcp://localhost:5672' +</programlisting> + + <para> Breaking this example down, here's what it all + means: </para> + + <itemizedlist> + <listitem><para> amqp = the protocol we're using + </para></listitem> + + <listitem><para> 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.</para></listitem> + + <listitem><para> 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 [.-_+!=:]. </para></listitem> + + <listitem><para>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. </para></listitem> + + </itemizedlist> + + <para> 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: </para> + + <para> + brokerlist='tcp://host1&tcp://host2:5673' </para> + + <para>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 ! </para> + + <!--h4--> + </section> + + <section role="h4" + id="ConnectionURLFormat-Options"> + + <title> Options</title> + + <table> + <title>Connection URL Options</title> + <tgroup cols="3"> + <tbody> + <row> + <entry> + Option + </entry> + <entry> + Default + </entry> + <entry> + Description + </entry> + </row> + <row> + <entry> + brokerlist + </entry> + <entry> + see below + </entry> + <entry> + The list of brokers to use for this connection + </entry> + </row> + <row> + <entry> + failover + </entry> + <entry> + see below + </entry> + <entry> + The type of failover method to use with the broker list. + </entry> + </row> + <row> + <entry> + maxprefetch + </entry> + <entry> + 5000 + </entry> + <entry> + The maximum number of messages to prefetch from the broker. + </entry> + </row> + </tbody> + </tgroup></table> +<!--h4--></section> + +<section role="h4" id="ConnectionURLFormat-Brokerlistoption"> + <title> Brokerlist option </title> + <programlisting> +brokerlist='<broker url>[;<broker url>]' +</programlisting> + <para> + The broker list defines the various brokers that can be used for + this connection. A minimum of one broker url is required + additional URLs are semi-colon(';') delimited. + </para> +<!--h4--></section> + +<section role="h4" id="ConnectionURLFormat-BrokerURLformat"> + +<title> Broker URL format </title> + + <programlisting> +<transport>://<host>[:<port>][?<option>='<value>'[&<option>='<value>']] +</programlisting> + <para> + There are currently quite a few default values that can be + assumed. This was done so that the current client examples would + not have to be re-written. The result is if there is no + transport, 'tcp' is assumed and the default AMQP port of 5672 is + used if no port is specified. + </para><table><title>Broker URL- Transport</title> + <tgroup cols="1"> + <tbody> + <row> + <entry> + Transport + </entry> + </row> + <row> + <entry> + tcp + </entry> + </row> + <row> + <entry> + vm + </entry> + </row> + </tbody> + </tgroup></table><para> + Currently only 'tcp' and 'vm' transports are supported. Each + broker can take have additional options that are specific to that + broker. The following are currently implemented options. To add + support for further transports the + ''client.transportTransportConnection'' class needs updating + along with the parsing to handle the transport. + </para> + <table><title>Broker URL - Connection Options</title> + <tgroup cols="3"> + <tbody> + <row> + <entry> + Option + </entry> + <entry> + Default + </entry> + <entry> + Description + </entry> + </row> + <row> + <entry> + retries + </entry> + <entry> + 1 + </entry> + <entry> + The number of times to retry connection to this Broker + </entry> + </row> + <row> + <entry> + ssl + </entry> + <entry> + false + </entry> + <entry> + Use ssl on the connection + </entry> + </row> + <row> + <entry> + connecttimeout + </entry> + <entry> + 30000 + </entry> + <entry> + How long in (milliseconds) to wait for the connection to + succeed + </entry> + </row> + <row> + <entry> + connectdelay + </entry> + <entry> + none + </entry> + <entry> + How long in (milliseconds) to wait before attempting to + reconnect + </entry> + </row> + </tbody> + </tgroup></table> +<!--h4--></section> + + <section role="h4" id="ConnectionURLFormat-Brokerlistfailoveroption"> + + <title> Brokerlist failover option </title> + <programlisting> +failover='<method>[?<options>]' +</programlisting> + <para> + This option controls how failover occurs when presented with a + list of brokers. There are only two methods currently implemented + but interface qpid.jms.failover.FailoverMethod can be + used for defining further methods. + </para><para> + Currently implemented failover methods. + </para><table><title>Broker List - Failover Options</title><tgroup cols="2"> + <tbody> + <row> + <entry> + Method + </entry> + <entry> + Description + </entry> + </row> + <row> + <entry> + singlebroker + </entry> + <entry> + This will only use the first broker in the list. + </entry> + </row> + <row> + <entry> + roundrobin + </entry> + <entry> + This method tries each broker in turn. + </entry> + </row> + <row> + <entry> + nofailover + </entry> + <entry> + [New in 0.5] This method disables all retry and failover + logic. + </entry> + </row> + </tbody> + </tgroup></table><para> + The current defaults are naturally to use the 'singlebroker' when + only one broker is present and the 'roundrobin' method with + multiple brokers. The '''method''' value in the URL may also be + any valid class on the classpath that implements the + FailoverMethod interface. + </para><para> + The 'nofailover' method is useful if you are using a 3rd party + tool such as Mule that has its own reconnection strategy that you + wish to use. + </para> + + <table> + <title>Broker List - Failover Options</title> + <tgroup cols="3"> + <tbody> + <row> + <entry> + Option + </entry> + <entry> + Default + </entry> + <entry> + Description + </entry> + </row> + <row> + <entry> + cyclecount + </entry> + <entry> + 1 + </entry> + <entry> + The number of times to loop through the list of available + brokers before failure. + </entry> + </row> + </tbody> + </tgroup></table><para> + <emphasis>Note:</emphasis> Default was changed from 0 to 1 in Release 0.5 + </para> +<!--h4--></section> + + <section role="h3" id="ConnectionURLFormat-SampleURLs"> + + <title> + Sample URLs + </title> + <programlisting> +amqp:///test?brokerlist='localhost' +amqp:///test?brokerlist='tcp://anotherhost:5684?retries='10'' +amqp://guest:guest@/test?brokerlist='vm://:1;vm://:2'&failover='roundrobin' +amqp://guest:guest@/test?brokerlist='vm://:1;vm://:2'&failover='roundrobin?cyclecount='20'' +amqp://guest:guest@client/test?brokerlist='tcp://localhost;tcp://redundant-server:5673?ssl='true''&failover='roundrobin' +amqp://guest:guest@/test?brokerlist='vm://:1'&failover='nofailover' +</programlisting> + +<!--h3--></section> +</section> diff --git a/qpid/doc/book/src/old/Download.xml b/qpid/doc/book/src/old/Download.xml new file mode 100644 index 0000000000..7bc08143ac --- /dev/null +++ b/qpid/doc/book/src/old/Download.xml @@ -0,0 +1,174 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<chapter id="chapter-Download"> + +<title>Download Apache Qpid</title> + +<para/> + + +<section><title>Production Releases</title> + +<para>These releases are well tested and appropriate for production use. 0.5 is the latest release of Qpid.</para> + +<para>Qpid supports the latest version of AMQP 0-10, and some components also the AMQP 0-8 and 0-9, earlier versions. The Java Broker and Client provide protocol negotiation. Other versions can be found at <ulink url="http://www.apache.org/dist/qpid/">http://www.apache.org/dist/qpid/</ulink></para> + +<para>For details on cross component compatibility among releases, see: <ulink url="### FIX ME ###">AMQP Release Compatibility for Qpid|AMQP compatibility</ulink></para> + +<para>If you have any questions about these releases, please mail the user list (<ulink url="mailto:users@qpid.apache.org">users@qpid.apache.org</ulink>).</para> + +</section> + +<section><title>0.5 Release</title> + +<section><title>Multiple Component Packages</title> + +<table frame="all"> +<title/> +<tgroup cols='4' align='left' colsep='1' rowsep='1'> +<thead><row><entry> Component </entry><entry> Download </entry><entry> AMQP 0-10 </entry><entry> AMQP 0-8/0-9 </entry></row></thead> +<tbody> +<row><entry> Full release & keys </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/">http://www.apache.org/dist/qpid/0.5/</ulink> </entry><entry> Y </entry><entry> Y </entry></row> +<row><entry> C++ broker & client </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/qpid-cpp-0.5.tar.gz">http://www.apache.org/dist/qpid/0.5/qpid-cpp-0.5.tar.gz</ulink> </entry><entry> Y </entry><entry> </entry></row> +<row><entry> Java broker, client & tools </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/qpid-java-0.5.tar.gz">http://www.apache.org/dist/qpid/0.5/qpid-java-0.5.tar.gz</ulink> </entry><entry> client </entry><entry> Y </entry></row> +</tbody> +</tgroup> +</table> +</section> + +<section><title>Single Component Package</title> + + +<table> +<title>Broker</title> +<tgroup cols="4" align='left' colsep='1' rowsep='1'> +<thead><row><entry> Language </entry><entry> Download </entry><entry> AMQP 0-10 </entry><entry> AMQP 0-8/0-9 </entry></row></thead> +<tbody> +<row><entry> Java </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/qpid-java-broker-0.5.tar.gz">http://www.apache.org/dist/qpid/0.5/qpid-java-broker-0.5.tar.gz</ulink> </entry><entry> </entry><entry> Y </entry></row> +</tbody> +</tgroup> +</table> + + +<table> +<title>Client</title> +<tgroup cols="4" align='left' colsep='1' rowsep='1'> +<thead><row><entry> Language </entry><entry> Download </entry><entry> AMQP 0-10 </entry><entry> AMQP 0-8/0-9 </entry></row></thead> +<tbody> +<row><entry> C# (.NET, WCF, Excel) 0-10 client (C++ Broker Compatible) </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/qpid-dotnet-0-10-0.5.zip">http://www.apache.org/dist/qpid/0.5/qpid-dotnet-0-10-0.5.zip</ulink> </entry><entry> Y </entry><entry> </entry></row> +<row><entry> C# (.NET) 0-8 client (Java Broker Compatible) </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/qpid-dotnet-0-8-0.5.zip">http://www.apache.org/dist/qpid/0.5/qpid-dotnet-0-8-0.5.zip</ulink> </entry><entry> </entry><entry> Y </entry></row> +<row><entry> Java </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/qpid-java-client-0.5.tar.gz">http://www.apache.org/dist/qpid/0.5/qpid-java-client-0.5.tar.gz</ulink> </entry><entry> Y </entry><entry> Y </entry></row> +<row><entry> Python </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/qpid-python-0.5.tar.gz">http://www.apache.org/dist/qpid/0.5/qpid-python-0.5.tar.gz</ulink> </entry><entry> Y </entry><entry> Y </entry></row> +<row><entry> Ruby </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/qpid-ruby-0.5.tar.gz">http://www.apache.org/dist/qpid/0.5/qpid-ruby-0.5.tar.gz</ulink> </entry><entry> Y </entry><entry> Y </entry></row> +</tbody> +</tgroup> +</table> + + +<table> +<title>C++ broker management</title> +<tgroup cols="3" align='left' colsep='1' rowsep='1'> +<thead><row><entry> Component </entry><entry> Download </entry><entry> AMQP 0-10 </entry></row></thead> +<tbody> +<row><entry> cmd line (packaged with python) </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/qpid-python-0.5.tar.gz">http://www.apache.org/dist/qpid/0.5/qpid-python-0.5.tar.gz</ulink> </entry><entry> Y </entry></row> +<row><entry> QMan JMX bridge, WS-DM </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/qpid-management-client-0.5.tar.gz">http://www.apache.org/dist/qpid/0.5/qpid-management-client-0.5.tar.gz</ulink> </entry><entry> Y </entry></row> +</tbody> +</tgroup> +</table> + + +<table> +<title>Java broker management</title> +<tgroup cols="2" align='left' colsep='1' rowsep='1'> +<thead><row><entry> Component </entry><entry> Download </entry></row></thead> +<tbody> +<row><entry> Eclipse RCP client </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/qpid-management-eclipse-plugin-0.5-linux-gtk-x86.tar.gz">Linux x86</ulink> +<ulink url="http://www.apache.org/dist/qpid/0.5/qpid-management-eclipse-plugin-0.5-linux-gtk-x86_64.tar.gz">Linux x86_64</ulink> +<ulink url="http://www.apache.org/dist/qpid/0.5/qpid-management-eclipse-plugin-0.5-macosx.zip">Mac OS X</ulink> +<ulink url="http://www.apache.org/dist/qpid/0.5/qpid-management-eclipse-plugin-0.5-win32-win32-x86.zip">Windows x86</ulink> +</entry></row> +<row><entry> Command line interface </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/qpid-management-tools-qpid-cli-0.5.tar.gz">http://www.apache.org/dist/qpid/0.5/qpid-management-tools-qpid-cli-0.5.tar.gz</ulink> </entry></row> +</tbody> +</tgroup> +</table> +</section> +</section> + + +<section id="qpid_3rd-Party-Libraries"><title>QpidComponents.org</title> + +<para><ulink url="http://QpidComponents.org">http://QpidComponents.org</ulink> provides further components for Apache Qpid, including both persistence and management tools. These components are open source, but are not developed as part of the Apache Qpid project due to licensing or other restrictions.</para> + +</section> + + +<section><title>Contributed C++ Packages</title> + +<section><title>Pre-built Linux Packages</title> + +<section><title>Fedora 8, 9, 10</title> + +<para>On Fedora, Qpid can be installed using yum. Because Java RPMs are not yet available in Fedora repos, the Java client is not in these distributions.</para> + +<para>To install the server:</para> +<programlisting> +# yum install qpidd +</programlisting> +<para>To install C++ and Python clients:</para> +<programlisting> +# yum install qpidc-devel +</programlisting> +<programlisting> +# yum install amqp python-qpid +</programlisting> +<para>To install documentation:</para> +<programlisting> +# yum install rhm-docs +</programlisting> +<para>To install persistence using an external store module:</para> +<programlisting> +# yum install rhm +</programlisting> +</section> +</section> + + +<section><title>Windows Installer</title> + +<para>The Windows installer is available from <ulink url="http://www.apache.org/dist/qpid/0.5-windows/qpidc-0.5.msi">http://www.apache.org/dist/qpid/0.5-windows/qpidc-0.5.msi</ulink>. It is built from the 0.5 C++ broker and client source distribution listed above. It has been tested for Windows XP SP2 and above.</para> + +<para>The Windows executables require the Visual C++ 2008 SP1 run-time components. If the Visual C++ 2008 SP1 runtime is not available, the Qpid broker will not execute. If you intend to run the broker and Visual C++ 2008 is not installed, you must install the Visual C++ 2008 SP1 Redistributable. Please see <ulink url="http://www.microsoft.com/downloads/details.aspx?familyid=A5C84275-3B97-4AB7-A40D-3802B2AF5FC2&displaylang=en">http://www.microsoft.com/downloads/details.aspx?familyid=A5C84275-3B97-4AB7-A40D-3802B2AF5FC2&displaylang=en</ulink> for download and installation instructions.</para> + +<para>If you intend to develop Qpid client applications using this kit, you should install <ulink url="http://www.boostpro.com/download/boost_1_35_0_setup.exe">Boost version 1.35</ulink> (please be sure to select VC9 support when installing) in addition to Visual Studio 2008 SP1.</para> + +</section> +</section> + +<section><title>Source Code Repository</title> + +<para>The latest version of the code is always available in the <ulink url="Source Repository">Source Repository</ulink>. +</para> +</section> + + +</chapter> diff --git a/qpid/doc/book/src/old/Excel-AddIn.xml b/qpid/doc/book/src/old/Excel-AddIn.xml new file mode 100644 index 0000000000..e38f620bd8 --- /dev/null +++ b/qpid/doc/book/src/old/Excel-AddIn.xml @@ -0,0 +1,169 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> +<section> + <title> + Excel AddIn + </title> + <section role="h1" id="ExcelAddIn-ExcelAddIn"> + <title> + Excel AddIn + </title> + <para> + Qpid .net comes with Excel AddIns that are located in: + </para> + <para> + <filename><project-root>\qpid\dotnet\client-010\addins</filename> + </para> + + <para> + There are currently three projects: + </para> + <variablelist> + <varlistentry> + <term>ExcelAddIn</term> + <listitem> + <para>An RTD excel Addin</para> + </listitem> + </varlistentry> + <varlistentry> + <term>ExcelAddInProducer + </term> + <listitem> + <para>A sample client to demonstrate the RTD AddIn</para> + </listitem> + </varlistentry> + <varlistentry> + <term>ExcelAddInMessageProcessor + </term> + <listitem> + <para>A sample message processor for the RTD AddIn</para> + </listitem> + </varlistentry> + </variablelist> + + <section role="h2" id="ExcelAddIn-QpidRDTAddIn"> + <title> + Qpid RDT AddIn + </title> + <section role="h3" id="ExcelAddIn-DeployingtheRTDAddIn"> + <title> + Deploying the RTD + AddIn + </title> + <para> + Excel provides a function called RTD (real-time data) that lets + you specify a COM server via its ProgId here "Qpid" so that you + can push qpid messages into Excel. + </para> + <para> + The provided RTD AddIn consumes messages from one queue and + process them through a provided message processor. + </para> + <para> + For using the Qpid RTD follows those steps: + </para> + + <procedure> + <step><para> + Copy the configuration Excel.exe.config into <filename>Drive\Program Files\Microsoft Office\Office12</filename>. + </para></step> + <step><para> + Edit <filename>Excel.exe.xml</filename> and set the targeted Qpid broker host, port + number, username and password. + </para></step> + <step> <para> + Select the cell or cell range to contain the RTD information + </para></step> + <step><para> + Enter the following formula <command>=rtd("Qpid",,"myQueue")</command>. Where + MyQueue is the queue from which you wish to receive messages from. + </para></step> + </procedure> + <para> + Note: The Qpid RTD is a COM-AddIn that must be registered with + Excel. This is done automatically when compiling the Addin with + visual studio. + </para> + <!--h3--> + </section> + + + <section role="h3" id="ExcelAddIn-Definingamessageprocessor"> + <title> + Defining a message processor + </title> + + <para> + The default behavior of the RDT AddIn is to display the message + payload. This could be altered by specifying your own message + processor. + A Message processor is a class that implements the API + <command>ExcelAddIn.MessageProcessor</command>. For example, the provided processor + in <filename>client-010\addins\ExcelAddInMessageProcessor</filename> displays the + message body and the the header price when specified. + </para> + <para> + To use you own message processor follows those steps: + </para> + <procedure> + <step><para>Write your own message processor that extends ExcelAddIn.MessageProcessor</para></step> + <step><para>Edit Excel.exe.config and uncomment the entries:</para> + <programlisting> +<add key="ProcessorAssembly" +value="<path>\qpid\dotnet\client-010\addins\ExcelAddInMessageProcessor\bin\Debug\ExcelAddInMessageProcessor.dll"/> + </programlisting> + <programlisting> + <add key="ProcessorClass" + value="ExcelAddInMessageProcessor.Processor"/> + </programlisting> + <itemizedlist> + <listitem> + <para>ProcessorAssembly is the path on the Assembly that contains + your processor class + </para> + </listitem> + <listitem> + <para>ProcessorClass is your processor class name + </para> + </listitem> + </itemizedlist> + </step> + <step><para>run excel and define a rtd function</para></step> + </procedure> + <para> + Note: the provided ExcelAddInProducer can be used for + testing the provided message processor. As messages are + sent to queue1 the following rtd function should be used + <command>=rtd("Qpid",,"queue1")</command>. + </para> + + <!--h3--> + </section> + + <!--h2--> + </section> + + <!--h1--> + </section> + +</section> diff --git a/qpid/doc/book/src/old/FAQ.xml b/qpid/doc/book/src/old/FAQ.xml new file mode 100644 index 0000000000..5647f18f69 --- /dev/null +++ b/qpid/doc/book/src/old/FAQ.xml @@ -0,0 +1,524 @@ +<!-- + - + - Licensed to the Apache Software Foundation (ASF) under one + - or more contributor license agreements. See the NOTICE file + - distributed with this work for additional information + - regarding copyright ownership. The ASF licenses this file + - to you 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. + - + --> +{toc} + + +*This page is a collection of FAQ and How to-s for Qpid. If you have a question, post it to the users list and we will place the answer here to build out our FAQ/ How to.* + +h1. FAQ + +h2. About AMQP + +h3. What is AMQP? + +AMQP is a wire-level protocol and model for high performance enterprise messaging. + +[From the AMQP website:|http://www.amqp.org] + + AMQP is an Open Standard for Messaging Middleware. + + By complying to the AMQP standard, middleware products written for different platforms and in different languages can send messages to one another. AMQP addresses the problem of transporting value-bearing messages across and between organizations in a timely manner. + + AMQP enables complete interoperability for messaging middleware; both the networking protocol and the semantics of broker services are defined in AMQP. + +h3. Where did AMQP come from + +AMQP was born out from Frustration by John O'Hara at JPMC. He started a project internally to create commodity messaging that was easy to use. Carl Trieloff from Red Hat had started a project to build messaging for both users and for use in infrastructure, while looking around spoke to John about his work. Out of these discussion was born the AMQP working Group with 6 initial members, under an agreement that it will be eternally be licensed for everyone to use. + +Since then the Working Group has had many join, and has been making solid progress working on revisions of the specification. [For more details see.|http://jira.amqp.org/confluence/display/AMQP/About+AMQP] + +h3. Why use AMQP? + +AMQP is has been designed to be able to handle the hardest workloads, scale to the largest systems, but also deal with reduction of change and maintenance costs by doing a refresh on many aged practices. The specification is also not language specific allowing the freedom from language and platform lock in, without compromise on user experience, security, scalability and consistently excellent performance. + +[Text mostly taken from|http://jira.amqp.org/confluence/display/AMQP/About+AMQP] + +h2. Qpid & AMQP + + +h3. Is Qpid AMQP Compliant? + +Yes, Apache Qpid implements the latest AMQP specifications, providing transaction management, queuing, distribution, security, management, clustering, federation and heterogeneous multi-platform support and a lot more. And Apache Qpid is extremely fast. [Apache Qpid aims to be 100% AMQP Compliant|AMQP compatibility]. + +h3. What Client support does Qpid have? + +Apache Qpid provides AMQP Client APIs for the following languages: +* C+\+ +* C# .NET, using WCF +* Ruby +* Python +* Java JMS, fully conformant with Java CTS1.1 + +If you need another client, join the lists and ask or feel free to contribute one. + +h3. What messaging topologies are supported by AMQP and Qpid? + +AMQP provides the ability to do Point-to-Point, Peer-to-Peer, Pub-Sub, and Eventing. This allows many patterns to be craeted: + ++*Point-to-point*+ + +This is one of the simplest use-cases. AMQP allows for this in a few ways. + a.) A client can create a named queue allowing the producer to publish the message to the direct exchange with the key mapping the queue name. This will route the message to that queue. + b.) The above pattern can be extended by specifying a reply-to address in the published messages allowing for the consumer to reply the producer without knowing who it was send from prior to receiving the message. + ++*One-to-many*+ + +There are a few patterns that can be used. + + a.) AMQP provides a 'fanout' exchange which will send a message to all the queues that have been bound to it. Different domains or topics are created with the 'fanout' exchange by declaring different named fan-out exchanges. + + b.) A 'topic' or 'headers' exchange can also be used. in this case the pattern match is used to send the message to all the bound queues. It can be thought of as a filter allowing you to create just about any One-to-many routing patterns. + ++*Pub-Sub*+ + +Topic can be created with the 'topic' or other 'direct' exchange to allow consumer to bind to into the steams of data they care about. This pattern combined with the use of reply-to and Alternate-routing is the staple of what most people use messaging for today. + ++*FAST Reliable Messaging*+ + +AMQP 0-10 allows for fully reliable transfers between any two peers. This means that you can publish or subscribe to the broker fully reliable without requiring the need for transactions. This can all be done in async mode with the C++ broker allowing for high throughput while running entirely reliable. + ++*Transactional*+ + +AMQP supports two types of transactions in AMQP 0-10, TX and DTX. This allows for local (1PC), and 2PC transaction and the ability to coordinate with a TM (Transaction Manager). The Java broker supports TX, the C++ broker support TX, DTX, XA, JTA for fully ACID transactions. This allows you to commit a single unit of work with may contain enqueues & dequeues either locally on the broker, or in coordination with other transactional resource like RDBMS. + ++*Transient message delivery*+ + +By default messages are transient. Transient message can be sent to queues that are durable. They will not be safe stored or recovered, and will perform as any other transient message - fast! + ++*Durable message delivery*+ + +There is a header on each message where the message properties are specified, one of these is durability. Messages that are marked as durable and published to a durable queue will be safe stored. Durable messages will survive restart of the broker or cluster. + ++*Federation (Hub-spoke, Trees, graphs)*+ + +As AMQP 0-10 is symmetric for peer-to-peer communication all the building block are in place for creating networks of brokers. The C++ broker allows you to link the brokers together using 'qpid-route' and then create routes between the brokers either statically or with dynamic routes. + +This allows for a message to be published to one broker and consumed from another broker in the federated broker network. This feature is great to create data-center, or project isolation, but allow cross communication. It also allows networks to be created to scaled. [For more details see|Using Broker Federation] + ++*And many others, including custom pattern*+ + ++*Message Reply, Rings, Initial Value Caches, Last Value Messaging*+ + +All the above cases can be constructed using the AMQP and features of Qpid. For example reply can be constructed using message browsing and setting TTL on the messages. The C++ broker also support ring queues, last value queues, initial value caches on exchanges. With a bit of throught many additional patterns can be constructed. + +*+Store-and-forward+* + +Store-and-forward can be achieved by publishing to well know durable queues, that are not marked with auto delete. Consumers will be able to 'came back' to consume then at any time, even after restarts. + +h3. What AMQP and other exchanges does Qpid support? + +Both brokers support: + * Direct Exchange + * Topic Exchange + * Fanout Exchange + * Headers Exchange + +In additional the C++ broker support + * XML Exchange - Query routing + * Custom exchange via plug-in. + +Custom exchanges allow you to provide your own custom routing logic and algorithms via a plug-in. If you build an interesting exchange, please feel free to contribute it back to the Qpid project. + +h2. Security + +h3. What encryption does Qpid support? + + * Qpid support SSL/TSL as per the AMQP specification. + * In addition the C++ broker supports Kerberos encryption of messages independent on which transport is used. Support in not yet included in all clients for this but is in process. + +h3. What authentication does Qpid support? + +SASL Authentication is supported. All Clients support PLAIN, and Kerberos support if being added to all the clients. The C++ broker support Kerberbos authentication. + +h3. What authorization does Qpid support? + +Full ACL is supported in the brokers. [For details on configuring ACL see|Qpid ACLs]. + +ACL supports realms and allows for granular permission to be set on all the broker actions including management on an user or group basis. + +h3. How to setup Kerberos with the Java client + +You could force the java client to use kerberos auth by specifying it in the connection URL as follows. +{code} +amqp://guest:guest@clientid/testpath?brokerlist='tcp://localhost:5672?'&sasl_mechs='GSSAPI' +{code} + +You would then need to pass in the following jvm arguments +{code} +-Djavax.security.auth.useSubjectCrehttp://code.google.com/p/confluence-el/dsOnly=false +# (This will force the SASL GASSPI client to obtain the kerberos credentials explicitly instead of obtaining from the "subject" that owns the currents thread) +-Djava.security.auth.login.config=myjas.conf (this specifies the jass config file) +-Dsun.security.krb5.debug=true (to enable detailed debug info for troubleshooting) +{code} + +Before running the java client you would need to do kinit and grab a kerberos ticket. Alternative you could set useTicketCache=false and when the client loads, it will prompt you for the user/pass and will obtain the ticket +(You would also need to setup your kerberos environment properly -refer to doc links below). + +Sample JASS Config file +{code} +com.sun.security.jgss.initiate { + com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true; +}; +{code} + + +h2. Semantics of Exclusive + +h3. I want to be able to have an exclusive consumer, but when it dies I want another to be able to pick up the queue and then block others, can this be done? + +Yes, Declare you queue exclusive. this will prevent anyone else from connecting to the queue. If the consumer dies the next consumer can attach to the queue by redeclaring it using the exclusive flag. Make sure not to set auto delete. Any consumer trying to declare, while a consumer is attached to the queue will receive an exception. + +h3. When will the queue become free for a re-declare + +Once the session that held the consumer is closed. + + +h2. Performance + +h3. Does Qpid Perform (Latency/Throughput)? + +Yes, The Qpid C++ broker has been achieved great benchmark results in published papers by those that redistribute it. [Red Hat MRG|http://www.redhat.com/mrg] product build on Qpid has shown 760,000msg/sec ingress on an 8 way box or 6,000,000msg/sec OPRA messages. + +Latencies have been recored as low as 180-250us (.18ms-.3ms) for TCP round trip and 60-80us for RDMA round trip using the C++ broker. + +h3. How do I measure throughput? + +There is a great resource supplied in the C++ broker test directory called perftest. If allows you to create load on a broker for all the exchanges, multiple queues, multiple connection, coordinate multiple publishing and consuming processes, beachmark transactions and much much more such as acquire mode, txn size, message size. + +For all the options +{code} +./perftest --help +{code} + +h3. How do I measure latency? + +There is a great resource supplied in the C++ broker test directory called latencytest. It is a loopback test that produces messages by count or at a rate, time stamps them and then consumes them back and record the latency. It supports many of the Qpid options, including the ability to vary things like frame-size. + +Latencies to expect round trip: + * 1G TCP ~ .3ms -.5ms + * 10G TCP - .18ms - .22ms + * RDMA transport - 40us - 80us + +Don't forget to set tune the machine and set --tcp-nodelay on both the C++ broker & client. + +For all the options +{code} +./latencytest --help +{code} + +h3. How do I measure performance with Java clients? + +In Java we provide a utility called QpidBench. It allows you to test the performance of the native AMQP API in Java for 0-10 and the JMS API against both brokers. + +h3. Can I run my Java client with JAVA-RT? + +Yes, recently a thread abstraction layer has been added to the Java client allowing it to be used with both the SUN and IBM RT JVMs. This increases the determinism of latency when using the Java client. + +h3. Does Qpid support flow control? + +yes, AMQP 0-10 allows for flow control on the consumer and producer. + +h3. How do I configure producer side flow control + +from qpidd --help + +set the following in the config file on via cmd line options. +{code} + --max-session-rate MESSAGES/S (0) Sets the maximum message rate per session (0=unlimited) +{code} + +h2. Management + +h3. What Management does Qpid support + +The Java broker supports JMX and provides an Eclipse plug-in and command line tool to manage via JMX. The C++ broker has far more extensive management support via QMF which will be added to the Java broker in a future release. + +The C++ Broker supports a layered management protocol over AMQP called QMF. This allows for the management of resource either in the broker or connected to the broker via the AMQP fabric. This management includes statistics, control, eventing, and reporting/updating properties. + +h3. How do I manage a broker? + +A set of tools are provided to manage the C++ broker, they include + * qpid-tool - telnet type tool to access data, view schema, issue command an and QMF resource + * qpid-config - tool to configure queues, exchanges, etc. all the details on the AMQP model + * qpid-route - tool to configure broker federation + * qpid-events - utility that will print to cmd line or syslog event from a broker like, userconnected, user crested/deleted a queue. + * qpid-stats - utility that will print out queue statistics to the cmd line or syslog like rate and message depth. + +Then you can also access all thsi information via JMX or WS-DM (work in progress) using QMan. + +h3. What logging tracing and events does Qpid support? + +Qpid support the ability to output events from any the broker or any managed object via QMF, or to do a variety of logging from the broker & clients. for tracing options run qpidd --help. + +Multiple levels of of logging are supported in the C++ broker from debug, warning, error, info, etc -- all of which can be filtered. + +h3. Can I get to all the management data from a client? + +yes, All the management data is just AMQP messages on specially named queues. An API is provided for working with the management data called QMFC + +h3. What is QMF + +QMF is the layered Management protocol used to manage the C++ broker. For details on teh protocol see the Development pages. + +QMF allows you to manage any resource and provides the following infrsstructure: + * Properties + * Statistics + * Commands + * Events + * Schema for resources and versioning + * tools for creating agents and consuming QMF data. + +h3. What are QMF Agents, and what do they do for me? + +An Agent is any client (producer or consumer) that generates a QMF schema and registers itself to be management by QMF. + +A great use case of this is a consumer that is processing order from a queue can reference itself to that queue and for example provide a schema for the number or successful orders process and a method to suspend processing. Now it becomes possible to use qpid-tool to connect to the broker, see which order processors are on queue via the reference and the via the stats of the order processor client. It is also possible to issue a command to the client via qpid-tool to suspend processing. ACL in the broker can be applied to all these actions if desired. + +h3. What is QMFC and what does it do for mr? + +QMFC is the API used to consume QMF data, event and issue commands to QMF agents from an AMQP client. + +h3. What is QMan + +Qman is a tool that dynamically reads the QMF Schema information and creates JMX objects that consumed by any JMX console or application server to manage Qpid. QMan is also adding support for WS-DM management of QMF resources. + + +h2. Clustering, Federation and Disaster Recovery + +h3. Does Qpid provide Fault Tolerance for the cluster? + +The C++ broker has plug-ins for Active-Active clustering which keep all the nodes of the cluster in sync. This means that any action that is performed on one of the brokers on the cluster is performed on all of them at the same time. New nodes can be added to the cluster at any time, and removed at any time with no consequences, exept for the extra multi-cast load created for the sync on joining. + +h3. What does the cluster guarantee? + +Everything! All configuration, all messages and all actions are replicated in a cluster. This means that two consumers can be connected to different nodes in the cluster and they will behave EXACTLY the same as if they where on a single broker. + +h3. Do clients get notified members joining or leaving the cluster? + +yes, All clients are updated with the addresses of node add/removed as supported by the AMQP 0-10 specification. This means that the client can dynamically track the nodes in the cluster and reconnect as required. + +h3. Can I specify more than one host to connect initially to the cluster to avoid single point of failure? + +yes, the AMQP address is multi-honed and more than one IP address can be specified at the initial connection. The client will then iterate through the host until it makes a successful connection. This feature can also be used in none clustered brokers. + +h3. How does Clustering work? + +When C++ brokers are configured into a cluster, the nodes communicate with each other over a mulitcast protocol called AIS, an open Telco multicast protocol that provides all the quorum and group services. + +Every action that is performed on any node of the cluster is then sequenced via totem and then performed on each node of the cluster in sync. As the cluster backbone is multicast, a separate network can be used for cluster communication and there is little impact adding additional nodes to the cluster with-in reason. + +h3. What is Federation? + +Federation provides the ability to create networks of brokers that communicate with each other in all types of typologies. This allows a producer to publish messages to one broker and someone to consume the messages from another broke somewhere on the broker federated network. + +[For more details see|Using Broker Federation] + +h3. Disater recover features are in process, Q&A will be added once they are complete. + +h2. Heartbeats + +Heartbeat can be configured to allow clients to detect when a broker has failed and connect to another broker or cluster member.Heartbeats are sent by the broker at a client specified, per-connection frequency. If the client does not receive a heartbeat or any other traffic for two heartbeat intervals, the connection will be made to fail. + +h3. What would happen when there is a no heartbeat within a predefined interval? + +If there is no traffic for two heartbeat intervals, the client will fail the connection. The application will see the exact same response as when the connection is killed. + +h3. What happens if the broker is unable to send heartbeat? + +As above, if there is no other traffic the client will eventually kill the connection. + +h3. Does the client retry? + +You can control the heartbeat interval on the client through the heartbeat member of ConnectionSettings (it is measured in seconds). Some of the options on policies do vary for different clients. + +h3. Failover taking too long... + +First check to make sure a heartbeat has been specified in the connection properties for the connection. + +Then make sure that the interfaces on each broker are reachable from the host you run my clients, else it will take a long time for the socket to timeout until it gets to one that can be reached. + +Make sure the list of URL's on the cient are the ones you want tht client to try + +Make sure that the broker is only exporting URL's that the client can connect to, use the --cluster-url option on the broker to specify this. + +h2. Threading + +h3. Could someone provide a brief description of the worker thread duties in the current Qpid release? + +The broker uses IO threads for all the work it does. This means that when work is signalled via an event (socket, RDMA, timer) an IO thread is scheduled and it runs until it completes the work and then returns back to the IO thread pool. This allows the CPUs to be utilized efficiently. The general rule is that we allocate 1 thread per core +1. So on a 8 way machine you see worker-threads default to 9. On a 4 way it will be 5. Sometimes it if work changing the default allocation if: + +a.) you run on high core count machine >8 to a lower number +b.) if you taskset, then set to the cores allocated +1 + +h3. Why was the number X chosen as the default number of worker threads? + +Qpidd defaults to cores + 1 + +h3. What happens in parallel? + +Concurrency in the broker is at the session level. So yes. If you want more concurrency, create another session on the same connection. + +h3. How are worker threads allocated to individual client sessions if there are more clients than threads in the pool? + +They are not allocated to a specific client + +h2. Persistence + +h3. Does Qpid support persistence (durability)? + +Yes, there are third-party (non-Apache) modules for both C++ and Java. Historically, BDB has been used to provide persistence for both C++ and Java. However, this has created a licensing conflict with Apache, and thus the store modules are maintained off-site. + +The Java broker includes a fully Apache licensed persistent store that uses Derby DB. + +The terms _durable_ and _persistent_ are used interchangeably in this FAQ. + +h3. Where do I get the 3rd party persistence store modules? + +The 3rd party persistence store modules may be obtained through anonymous subversion at the following locations: + +C++: http://anonsvn.jboss.org/repos/rhmessaging/store/trunk/cpp +Java: http://anonsvn.jboss.org/repos/rhmessaging/store/trunk/java/bdbstore + +For further details see [3rd Party Libraries] + +h3. How do I build the persistence store module from subversion checkouts? + ++*C\+\+*+ +The README file contains detailed instructions, but here is a summary: + # Make sure that both the db4-devel and libaio-devel packages are installed prior to building. + # Make sure that qpid is built and you know the location of the qpid directory (ie the top-level directory containing the python and cpp sub-directories). + # In the store directory, run: +{code} +./bootstrap +./configure --with-qpid-checkout=/abs/path/to/qpid/dir +make +{code} +# When built, the store library *msgstore.so* will be located in the *lib/.libs* directory. + ++*Java*+ +TODO + +h3. How do I use the persistence store module? + ++*C\+\+*+ + # Start the broker making sure that the store module is loaded, ie +{code} +qpidd --load-module=/path/to/msgstore.so --data-dir=/path/to/store-files ... +{code} + # Make sure that queues that will handle persistent messages are set durable. +{note:title=Note: Existing non-persistent queues cannot be made persistent} +If a queue has been declared without persistence, doing so again with persistence enabled while the old queue still exists in the broker will be ignored. Make sure that when a queue is declared persistent, there is no non-persistent queue of the same name in existence. +{note} + # For each message sent to a durable queue, make sure that it is set durable. + ++*Java*+ +TODO + +h3. How do I configure the persistence store? + ++*C\+\+*+ + +The broker loads help information from each module. To see the help options for the store, load the store module and specify help: +{code} +qpidd --load-module /abs/path/to/store/lib/.libs/msgstore.so --help +{code} + +Note that a set of journal files will be created for each queue declared and marked persistent. Each persistent queue has its own private journal. These are stored in the data directory by default (ie it uses the broker's *\-\-data\-dir* setting) or can be overridden with the *\-\-store\-dir* option. Note that if the broker is started with the *\-\-no\-data\-dir* option, then no store default exists, and the *\-\-store\-dir* option MUST be specified. + +The store file details - or "store geometry" - can be set with command-line options. These include the size and number of files that make up the journal for each queue. The *\-\-num\-jfiles* options sets the number of files to use (between 4 and 64) and the *\-\-jfile\-size\-pgs* sets the size of the file in 64kiB blocks. + +The size of the pages in the write page cache is set with the *\-\-wcache\-page-size* option, and sets a size in KiB. (Legal values are powers of 2, ie: 1, 2, 4, 8, 16, 32, 64, 128). Typically small page sizes give improved latency (especially for small messages), but are bad for message throughput, while large page sizes improve throughput but may cause some messages to have higher latencies. + ++*Java*+ ++Derby Store+ +For details of configuring the Derby Store see [here|Derby Store Plugin] + ++3rd Party Stores+ + +For details of using the 3rd party persistent modules see [here|3rd Party Libraries] + + +h3. \[C++ store\] What is a RHM_IORES_ENQCAPTHRESH error? + +The journal ran out of space (ENQueue CAPacity THRESHold). The journal is a circular file buffer of fixed capacity set by the journal file size and number of files. When an attempt to write a record causes the journal to exceed an approx. 80% threshold, then the enqueue is rejected with this error code. Dequeues (a written record of a consumed message) may continue, however, as these free up space in the journal. Once space has been freed up, enqueues may continue as normal. + +This error may be caused by: +# The journal is too small for the size and number of messages being stored. The journal must be made large enough to hold all of the messages you expect to be on the queue at any one moment (a worst-case scenario). Make the journal capacity larger through the use of the *\-\-num\-jfiles* and *\-\-jfile\-size\-pgs* parameters. +{info:title=Rule of thumb for sizing the journal} +Make the journal twice the size of all the messages you need to store at any one moment in time. +{info} +# Messages are not being dequeued (consumed) as expected. Since the store is a circular file buffer, if one un-dequeued (not consumed) message remains, it can eventually "block" the storage of new messages as the buffer gets overwritten. + +h3. \[C++ store\] What is the TPL? What are the \-\-tpl\-\* options for? +The TPL stands for *Transaction Prepared List*. The store creates a single instance of a store for storing transaction boundaries called the Transaction Prepared List. Because the TPL is frequently flushed and has very different usage patterns to a normal store, it has been provided with its own set of configuration parameters: +* *\-\-tpl\-num\-jfiles:* The number of files in the TPL journal +* *\-\-tpl\-jfile\-size-pgs:* The file size in 64kiB blocks of the TPL journal. +* *\-\-tpl\-wcache\-page-size:* The size of the write cache in the TPL in KiB, which is typically set a lot smaller than the average message store. + +h1. How To + +h2. C++ + +h3. How to use RDMA with Qpid + +The RDMA plugin uses native OFED1.3 and puts AMQP directly onto the DMA. When using the RDMA plug-in for Qpid note the following +* IP over IB or Fibre needs to be setup for the initial negociation +* You need to make sure you have enough memory to pin for DMA use ulimit \-l something large +* you might need to edit /etc/security/limits.conf first then log in again + +Once you have it up and running, use latencytest to make sure it is working. You should see latencies between 50 and 80us round trip. + +h3. Message TTL, auto expire + +I need to be able to set time for a message that I send to be removed from the queue if it is not read by my subscriber. For example: I enqueue a message and I want it to be automatically dequeued after a certain amount of time has passed.Is there a feature like this in qpid? + +yes, the TTL can be set in the message headers and the messages get dequeued if TTL expires + +E.g. from c++: +{code} +Message m("Hello World!"); + m.getDeliveryProperties().setTtl(500); +{code} +Sets a 500 millisecond timeout. + +h3. How to install the qpid-tools for c++ broker? + +I see +{code} +[commands]$ ./qpid-queue-stats + Traceback (most recent call last): + File "./qpid-queue-stats", line 29, in + from qmf.console import Session, Console + ImportError: No module named qmf.console +{code} + +This problem occurs because the PYTHONPATH environment variable does not include the location of the qpid python files. If you are running from the SVN checkout, add <path>/qpid/python to PYTHONPATH (where <path> is the location of your SVN tree). If you are installing from source, make sure you configure with the same prefix where Python is installed. This is most likely: + +{code} +# configure --prefix=/usr +# make +# make install +{code} +If you are running from vendor RPMs, this should work automatically. + + +h2. Java +{children:page=Qpid Java How To} diff --git a/qpid/doc/book/src/old/Getting-Started.xml b/qpid/doc/book/src/old/Getting-Started.xml new file mode 100644 index 0000000000..216a52170e --- /dev/null +++ b/qpid/doc/book/src/old/Getting-Started.xml @@ -0,0 +1,90 @@ +<chapter id="Getting-Started"> + +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> +<title>Getting Started</title> +<para>To get started with Apache Qpid, follow the steps below.</para> + +<orderedlist> +<listitem><para>Download Apache Qpid.</para></listitem> +<listitem> + <para>Start a broker. </para> + <itemizedlist> + <listitem><para><xref linkend="chapter-Running-a-Qpid-Java-Broker"/></para></listitem> + <listitem><para><xref linkend="section-Running-a-Qpid-CPP-Broker"/></para></listitem> + <listitem><para><xref linkend="chapter-Managing-CPP-Broker"/>(AMQP 0-10, works with the Qpid C++ broker)</para></listitem> + </itemizedlist> +</listitem> +<listitem> + <para>Run an example program from the downloaded software, or from the following URLs (these are svn URLs, which you can use to browse the examples or check them out):</para> + <itemizedlist> + <listitem><para>C++ (AMQP 0-10):</para> + <itemizedlist> + <listitem><para>Examples:</para><para><ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/cpp/examples/">https://svn.apache.org/repos/asf/qpid/trunk/qpid/cpp/examples/</ulink></para></listitem> + <listitem><para>Running the C++ Examples:</para><para><ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/cpp/examples/README.txt">https://svn.apache.org/repos/asf/qpid/trunk/qpid/cpp/examples/README.txt</ulink></para></listitem> + </itemizedlist> +</listitem> +<listitem> + <para>Java JMS (AMQP 0-10):</para> + <itemizedlist> + <listitem><para>Examples:</para><para><ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/java/client/example/">https://svn.apache.org/repos/asf/qpid/trunk/qpid/java/client/example/</ulink></para></listitem> + <listitem><para>Script for Running the Java JMS Examples </para><para><ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/java/client/example/src/main/java/runSample.sh">https://svn.apache.org/repos/asf/qpid/trunk/qpid/java/client/example/src/main/java/runSample.sh</ulink></para></listitem> + </itemizedlist> +</listitem> +<listitem> + <para>Python (AMQP 0-10):</para> + <itemizedlist> + <listitem><para>Examples:</para><para><ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/python/examples/">https://svn.apache.org/repos/asf/qpid/trunk/qpid/python/examples/</ulink></para></listitem> + <listitem><para>Running the Python Examples</para><para><ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/python/examples/README">https://svn.apache.org/repos/asf/qpid/trunk/qpid/python/examples/README</ulink></para></listitem> + </itemizedlist> +</listitem> +<listitem> + <para>Ruby (AMQP 0-10):</para> + <itemizedlist> + <listitem><para>Examples: </para><para><ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/ruby/examples/">https://svn.apache.org/repos/asf/qpid/trunk/qpid/ruby/examples/</ulink></para></listitem> + </itemizedlist> +</listitem> +<listitem> + <para>.NET (AMQP 0-10):</para> + <itemizedlist> + <listitem><para>Examples:</para><para><ulink url="http://svn.apache.org/viewvc/qpid/trunk/qpid/dotnet/client-010/examples/">http://svn.apache.org/viewvc/qpid/trunk/qpid/dotnet/client-010/examples/</ulink></para></listitem> + <listitem><para><xref linkend="NETUserGuide-Tutorial"/></para></listitem> + </itemizedlist> +</listitem> +</itemizedlist> +</listitem> +<listitem> + <para>Read the API Guides and Documentation</para> + <itemizedlist> + <listitem><para>C++ Client API (AMQP 0-10)</para><para><ulink url="http://qpid.apache.org/docs/api/cpp/html/index.html"></ulink></para></listitem> + <listitem><para><xref linkend="How-to-Use-JNDI"/></para></listitem> + <listitem><para>Python Client API (AMQP 0-10)</para><para><ulink url="http://qpid.apache.org/docs/api/python/html/index.html">http://qpid.apache.org/docs/api/python/html/index.html</ulink></para></listitem> + </itemizedlist> +</listitem> +<listitem> + <para>Get your Questions Answered</para> + <itemizedlist> + <listitem><para>Read the <xref linkend="FAQ"/></para></listitem> + <listitem><para>Ask a question on the user list</para><para>mailto:users-subscribe@qpid.apache.org</para></listitem> + </itemizedlist> +</listitem> +</orderedlist> +</chapter> diff --git a/qpid/doc/book/src/old/How-to-Use-JNDI.xml b/qpid/doc/book/src/old/How-to-Use-JNDI.xml new file mode 100644 index 0000000000..0d6315c2a3 --- /dev/null +++ b/qpid/doc/book/src/old/How-to-Use-JNDI.xml @@ -0,0 +1,175 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<chapter id="How-to-Use-JNDI"> + <title> + How to Use JNDI + </title> + <section role="h2" id="HowtoUseJNDI-HowtousethePropertiesFileInitialContextFactory"> + <title> + How to use the PropertiesFileInitialContextFactory + </title> + + <para> + This ContextFactory uses a java properties formatted file to + setup initial values. + </para> + <section role="h3" id="HowtoUseJNDI-JNDIPropertysetup"> + <title> + JNDI Property setup + </title> + <para> + By setting the JNDI Initial Context Factory and URL as + below it is possible to load any File from the locally + mounted file system to use for JNDI purposes. The format + of the file is described in the next section. + </para> + <programlisting> +java.naming.factory.initial = org.apache.qpid.jndi.PropertiesFileInitialContextFactory +java.naming.provider.url = <path to JNDI File> +</programlisting> + <para> + By simply setting these two system properties you can jump + straight to the InitialContext creation in your code. + </para> + </section> + <section role="h3" id="HowtoUseJNDI-Examplepropertiesfile"> + <title> + Example properties file </title> + <para> + This is the example properties file. + </para> + <programlisting> +# register some connection factories +# connectionfactory.[jndiname] = [ConnectionURL] +connectionfactory.local = amqp://guest:guest@clientid/testpath?brokerlist='vm://:1' + +# register some queues in JNDI using the form +# queue.[jndiName] = [physicalName] +queue.MyQueue = example.MyQueue + +# register some topics in JNDI using the form +# topic.[jndiName] = [physicalName] +topic.ibmStocks = stocks.nyse.ibm + +# Register an AMQP destination in JNDI +# NOTE: Qpid currently only supports direct,topics and headers +# destination.[jniName] = [BindingURL] +destination.direct = direct://amq.direct//directQueue +</programlisting> + <para> + The property file allows a number of queues to be defined that + can then be discovered via JNDI. There are four properties used + by the PFICFactory. + <emphasis>connectionfactory.<jndiname></emphasis> this is the <xref linkend="Connection-URL-Format"/> that the connection + factory will use to perform connections. + <emphasis>queue.<jndiname></emphasis> this defines a jms queue or in + amqp a amq.direct exchange + <emphasis>topic.<jndiname></emphasis> this defines a jms topic or in + amqp a amq.topic exchange + <emphasis>destination.<jndiname></emphasis> this takes a <xref linkend="BindingURLFormat"/> + and so can be used for defining all amq destinations, queues, + topics and header matching. + </para><para> + In all of these properties the <emphasis><jndiname></emphasis> is the + string value that would be given when performing a lookup. + </para><para> + <emphasis>NOTE</emphasis>: This does not create the queue on the broker. You + should ensure that you have created the queue before publishing + to it. Queues can be declared in the virtualhosts.xml file so + that they are created on broker startup, or created dynamically + by consuming clients. Topics and other destinations that use + temporary queues cannot be created in this way, so a consumer + must be created first before publishing messages with mandatory + routing. + </para> + </section> + <section role="h3" id="HowtoUseJNDI-Examplelookupcode"> + <title> + Example lookup code + </title><!--h3--> + + <para> + The <emphasis>bindingValue</emphasis> is the String that would be placed in + <emphasis><jndiname></emphasis> above. + </para> + + <example> + <title>Simple JNDI lookup using files</title> + <programlisting> +//Ensure you have your system properties set +final String INITIAL_CONTEXT_FACTORY = "org.apache.qpid.jndi.PropertiesFileInitialContextFactory"; + +System.setProperty(Context.INITIAL_CONTEXT_FACTORY, INITIAL_CONTEXT_FACTORY); +System.setProperty(Context.PROVIDER_URL, _JNDIFile); + +// Create the initial context +Context ctx = new InitialContext(); + +// Perform the binds +object = ctx.lookup(bindingValue); + +// Close the context when we're done +ctx.close(); +</programlisting> +</example> + +<example> +<title>Simple JNDI lookup using properties</title> + + <programlisting> + +final String INITIAL_CONTEXT_FACTORY = "org.apache.qpid.jndi.PropertiesFileInitialContextFactory"; + +final String CONNECTION_JNDI_NAME = "local"; +final String CONNECTION_NAME = "amqp://guest:guest@clientid/testpath?brokerlist='vm://:1'"; + +final String QUEUE_JNDI_NAME = "queue"; +final String QUEUE_NAME = "example.MyQueue"; + +// Set the properties ... +Properties properties = new Properties(); +properties.put(Context.INITIAL_CONTEXT_FACTORY, INITIAL_CONTEXT_FACTORY); +properties.put("connectionfactory."+CONNECTION_JNDI_NAME , CONNECTION_NAME); +properties.put("queue."+QUEUE_JNDI_NAME , QUEUE_NAME); + +// Create the initial context +Context ctx = new InitialContext(properties); + +// Perform the lookups +ConnectionFactory factory = (ConnectionFactory)ctx.lookup(CONNECTION_JNDI_NAME); +Queue queue = (Queue)ctx.lookup(QUEUE_JNDI_NAME); + +// Close the context when we're done +ctx.close(); +</programlisting> +</example> + </section> + + <section> + <title>Using Qpid with Other JNDI Providers</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Using-Qpid-with-other-JNDI-Providers.xml"/> + </section> +<!--h2--> + </section> + +</chapter> diff --git a/qpid/doc/book/src/old/InfoPlugin.xml b/qpid/doc/book/src/old/InfoPlugin.xml new file mode 100644 index 0000000000..aebcd08c02 --- /dev/null +++ b/qpid/doc/book/src/old/InfoPlugin.xml @@ -0,0 +1,261 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section xmlns="http://docbook.org/ns/docbook" version="5.0"> +<title> +OSGI Info Plugin +</title> + <para> The Info OSGI Plugin was developed as a mean of monitoring the qpid broker startup/shutdown + times along with selected JVM and OS details. It was written as a OSGI plugin so it can be + used as needed. </para> + + +<section> + <title>How it works</title> + <para> Assuming the plugin is deployed, upon the Activator invocation (which happens when OSGI + loads the bundles), the plugin looks for its configuration file. If the file cannot be + found, the plugin does not perform any operation and will silently exit. If the + configuration is found, it is loaded and parsed. A predefined set of data is collected and + messages are generated as per the configuration templates (see below for details).</para> + <para> Further, the messages are sent using one of the supported protocols (currently http + post and soap) to the configured destination. The same scenario takes place on the plugin + unload phase which usually takes place upon broker shutdown. </para> +</section> + +<section> + <title>Data Gathering</title> + <para> +The info plugin collects a pre-defined set of data, and generates a message according to a template +defined in each section of the ini file. Data can be of 2 categories: +<orderedlist numeration="loweralpha" spacing="normal"> + <listitem> + <para>JVM specific</para> + </listitem> + <listitem> + <para>application specific</para> + </listitem> + </orderedlist> + </para> + <para> +Each data has a variable name associated which can be used for the message generation template. +The convention chosen for template is: @[variable (in uppercase)] (eg @IP, @PORT) (see configuration section +for message examples). +</para> +<para> +The following application specific info are gathered (variable names in round brackets): + + <orderedlist numeration="arabic" spacing="normal"> + <listitem> + <para>The JMX Port the application is listening to (jmxport)</para> + </listitem> + <listitem> + <para>The Port(s) the broker is listening to, comma delimited (port)</para> + </listitem> + <listitem> + <para>The Broker Version (version)</para> + </listitem> + <listitem> + <para>The key store path (KeystorePath)</para> + </listitem> + <listitem> + <para>The Plugin Directory (PluginDirectory)</para> + </listitem> + <listitem> + <para>The QPID work directory (QpidWork)</para> + </listitem> + <listitem> + <para>The JMX Principal Database (JMXPrincipalDatabase)</para> + </listitem> +</orderedlist> +</para> + <para> +The following JVM specific info are collected (variable names in round brackets): + + <orderedlist numeration="arabic" spacing="normal"> + <listitem> + <para>Hostname (hostname)</para> + </listitem> + <listitem> + <para>IP address of the current machine (ip)</para> + </listitem> + <listitem> + <para>Number of CPU cores (CPUCores)</para> + </listitem> + <listitem> + <para>Maximum memory (Maximum_Memory)</para> + </listitem> + <listitem> + <para>Free Memory (Free_Memory)</para> + </listitem> + <listitem> + <para>Java Class Path (java.class.path)</para> + </listitem> + <listitem> + <para>Jave Home (java.home)</para> + </listitem> + <listitem> + <para>Java VM Name (java.vm.name)</para> + </listitem> + <listitem> + <para>Java VM Vendor (java.vm.vendor)</para> + </listitem> + <listitem> + <para>Java VM Version (java.vm.version)</para> + </listitem> + <listitem> + <para>Java Class Version (java.class.version)</para> + </listitem> + <listitem> + <para>Java Runtime Version (java.runtime.version)</para> + </listitem> + <listitem> + <para>OS Architecture (os.arch)</para> + </listitem> + <listitem> + <para>Sun Architecture Data Model (sun.arch.data.model)</para> + </listitem> + <listitem> + <para>User home directory (user.home)</para> + </listitem> + <listitem> + <para>User Name (user.name)</para> + </listitem> + <listitem> + <para>User Time Zone (user.timezone)</para> + </listitem> + </orderedlist> +</para> +</section> + + +<section> + <title>Plugin Configuration</title> +<para> +The plugin configuration file is currently hardcoded to be: $QPID_HOME/etc/qpidinfo.ini +We plan to provide a mean to change the configuration by using system property (eg -DInfoPluginConfig) but +currently this is not available. +</para> +<para> +As it might be useful to send more than 1 message, eventually to different destinations, +we chose an ini file layout for the plugin configuration that consists of a global section +and set of individual sections, one for each message to be sent. +</para> + <para> + The configuration file has a global section composed of any key-value pairs placed before the start + of an ini-type section (eg [section]). The role of the global section is to provide a set of values + that would be inferred in each subsequent section. Any section from the config file can override any + global variable by specifying the respective key-value pair inside. + </para> + <para> The key protocol is mandatory, the plugin will not work if protocol=soap or protocol=http is + not specified. For soap, we expect the following keys to be present: <itemizedlist> + <listitem> + <para>soap.hostname</para> + </listitem> + <listitem> + <para>soap.port</para> + </listitem> + <listitem> + <para>soap.path</para> + </listitem> + <listitem> + <para>soap.envelope</para> + </listitem> + </itemizedlist> For http the following keys have to be present: <itemizedlist> + <listitem> + <para>http.url</para> + </listitem> + <listitem> + <para>http.envelope</para> + </listitem> + </itemizedlist> The names are self-explanatory, please see the example below. The protocol + key cannot be overwritten in the sections and it has to be chosen initially. </para> + </section> + +<section><title>Example Configuration</title> + <para> +For soap messages, we will abbreviate the XML header by omitting the namespaces in the config, +in order to be more readable. A minimal correct XML for the soap envelope would be + <programlisting> + <![CDATA[ + <?xml version=\"1.0\"?> + <soap:Envelope + xmlns:soap=\"http://www.w3.org/2001/12/soap-envelope\" + soap:encodingStyle=\"http://www.w3.org/2001/12/soap-encoding\"> + ...some content... + </soap:Envelope> + ]]> + </programlisting> + + NB. On the ini file, there can be no text wrapping for any entry (as above), the whole text should come into + a single line, irrespective of how long it is. + + </para> + +<programlisting> +<![CDATA[ +## Ini file using SOAP +protocol=soap +soap.hostname=host1 +soap.port=8080 + +[Message1] +soap.path=/axis2/services/QpidInfo +soap.action=qpidevent +soap.envelope=<?xml version=\"1.0\"?><soap:Envelope>@ACTION-@VERSION</soap:Envelope> + +[Message2] +soap.hostname=host2 +soap.port=9090 +soap.path=/axis1/services/Info +soap.envelope=<?xml version=\"1.0\"?><soap:Envelope">@ACTION-@VERSION from @IP:@PORT</soap:Envelope> + +## End of File +]]> +</programlisting> + +<para> +and another example, this time using http: + +<programlisting> +<![CDATA[ +protocol=http +http.url=http://mywebserver:8080/postServlet + +[Message1] +http.envelope=Event from qpid broker at: @IP, running qpid version: @VERSION + +[Message2] +http.url=http://myotherwebserver:9090/postServlet1 +http.envelope=Event for qpid broker @VERSION from @IP:@PORT running java @JAVA.VM.VERSION +]]> +</programlisting> + </para> + <para> + The ini file is supporting comments starting with # or ; anywhere in the file. + The global section is considered to be the first set of lines from the ini file before the first [Section] encountered. + </para> + </section> + +</section> + + + diff --git a/qpid/doc/book/src/old/Introduction.xml b/qpid/doc/book/src/old/Introduction.xml new file mode 100644 index 0000000000..8f92c207cf --- /dev/null +++ b/qpid/doc/book/src/old/Introduction.xml @@ -0,0 +1,106 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<chapter> + +<title>Apache Qpid: Open Source AMQP Messaging</title> + +<para>Enterprise Messaging systems let programs communicate by exchanging messages, much as people communicate by exchanging email. Unlike email, enterprise messaging systems provide guaranteed delivery, speed, security, and freedom from spam. Until recently, there was no open standard for Enterprise Messaging systems, so programmers either wrote their own, or used expensive proprietary systems.</para> + +<para>AMQP Advanced Message Queuing Protocol is the first open standard for Enterprise Messaging. It is designed to support messaging for just about any distributed or business application. Routing can be configured flexibly, easily supporting common messaging paradigms like point-to-point, fanout, publish-subscribe, and request-response.</para> + +<para>Apache Qpid implements the latest AMQP specification, providing transaction management, queuing, distribution, security, management, clustering, federation and heterogeneous multi-platform support and a lot more. And Apache Qpid is extremely fast. Apache Qpid <ulink url="### FIX ME ###">aims to be 100% AMQP Compliant</ulink>.</para> + +<section> +<title>AMQP Messaging Brokers</title> + +<para>Qpid provides two AMQP messaging brokers:</para> + +<itemizedlist> + <listitem><para>Implemented in C++ - high performance, low latency, and RDMA support.</para></listitem> + <listitem><para>Implemented in Java - Fully JMS compliant, runs on any Java platform.</para></listitem> +</itemizedlist> + +<para>Both AMQP messaging brokers support clients in multiple languages, as long as the messaging client and the messaging broker use the same version of AMQP. See <ulink url="### FIX ME ###">Download</ulink> to see which messaging clients work with each broker.</para> + +</section> + +<section> +<title>AMQP Client APIs: C++, Java, JMS, Ruby, Python, and C#</title> + +<para>Qpid provides AMQP Client APIs for the following languages:</para> + +<itemizedlist> + <listitem><para>C++</para></listitem> + <listitem><para>Java, fully conformant with JMS 1.1</para></listitem> + <listitem><para>C# .NET, 0-10 using WCF</para></listitem> + <listitem><para>Ruby</para></listitem> + <listitem><para>Python</para></listitem> +</itemizedlist> + +</section> + +<section> +<title>Operating Systems and Platforms:</title> + +<para>The Qpid C++ broker runs on the following operating systems:</para> + +<itemizedlist> + <listitem><para>Linux systems</para></listitem> + <listitem><para>Windows</para></listitem> + <listitem><para>Solaris (coming soon)</para></listitem> +</itemizedlist> + +<para>The Qpid Java broker runs on:</para> + +<itemizedlist> + <listitem><para>Any Java platform</para></listitem> +</itemizedlist> + +<para>Qpid clients can be run on the following operating systems and platforms:</para> + +<itemizedlist> + <listitem><para>Java:</para> + <itemizedlist> + <listitem><para>any platform, production proven on Windows, Linux, Solaris</para></listitem> + </itemizedlist> + </listitem> + + + <listitem><para>C++:</para> + <itemizedlist> + <listitem><para>Linux</para></listitem> + <listitem><para>Windows</para></listitem> + <listitem><para>Solaris (coming soon)</para></listitem> + </itemizedlist> + </listitem> + + <listitem><para>C#</para> + <itemizedlist> + <listitem><para>.NET</para></listitem> + </itemizedlist> + </listitem> + +</itemizedlist> + +</section> +</chapter> diff --git a/qpid/doc/book/src/old/Java-Broker-StatusLogMessages.xml b/qpid/doc/book/src/old/Java-Broker-StatusLogMessages.xml new file mode 100644 index 0000000000..98f876e532 --- /dev/null +++ b/qpid/doc/book/src/old/Java-Broker-StatusLogMessages.xml @@ -0,0 +1,294 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> +<?oxygen RNGSchema="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" type="xml"?> +<book xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"> + <info> + <title>Operational Logging</title> + <author> + <orgname>Apache Software Foundation</orgname> + </author> + </info> + <chapter> + <title>Status Log Messages</title> + <para>This file was derivied from LogMessages used within the Java Broker and originally defined on: + <tag xlink:href="http://cwiki.apache.org/confluence/display/qpid/Status+Update+Design#StatusUpdateDesign-InitialStatusMessages">Apache Wiki</tag></para> + <sect1> + <title>Technical Notes:</title> + <para>The status log messages file is a standard Java Properties file so white space is respected at the end of + the lines. This file could be processed in a number of ways:</para> + <para> + <orderedlist> + <listitem> + <para>ResourceBundle</para> + <para>This file is loaded as a ResourceBundle. The en_US addition to the + file is the localisation. Additional localisations can be provided and + will automatically be selected based on the <locale> value in the + config.xml. The default locale is en_US.</para> + </listitem> + <listitem> + <para>MessageFormat</para> + <para> Each entry is prepared with the Java Core MessageFormat methods. + Therefore most functionality you can do via MessageFormat can be done + here: </para> + <para><tag xlink:href="http://java.sun.com/javase/6/docs/api/java/text/MessageFormat.html">Java API for MessageFormat</tag></para> + <para>The caveat here is that only default String and number FormatTypes can + be used. This is due to the processing described in 3 below. If support + for date, time or choice is required then the GenerateLogMessages class + should be updated to provide support.</para> + </listitem> + <listitem> + <para>GenerateLogMessage/Velocity Macro</para> + <para>This is the only processing that this file goes through</para> + <orderedlist> + <listitem> + <para>Class Generation:</para> + <para>The GenerateLogMessage processes this file and uses the + velocity Macro to create classes with static methods to perform + the logging and give us compile time validation. </para> + </listitem> + <listitem> + <para>Property Processing</para> + <para>During the class generation the message properties ({x}) are + identified and used to create the method signature.</para> + </listitem> + <listitem> + <para>Option Processing</para> + <para>The Classes perform final formatting of the messages at + runtime based on optional parameters that are defined within the + message. Optional parameters are enclosed in square brackets + e.g. [optional].</para> + </listitem> + </orderedlist> + </listitem> + </orderedlist> + </para> + <para><emphasis role="bold">Format Note:</emphasis></para> + <para> As mentioned earlier white space in this file is very important. One thing in + particular to note is the way MessageFormat performs its replacements. The + replacement text will totally replace the {xxx} section so there will be no addition + of white space or removal e.g. </para> + <programlisting><![CDATA[MSG = Text----{0}----]]> + </programlisting> + <para> When given parameter 'Hello' result in text: </para> + <programlisting><![CDATA[Text----Hello----]]> + </programlisting> + <para>For simple arguments this is expected however when using Style formats then it can + be a little unexpected. In particular a common pattern is used for number + replacements : {0,number,}. This is used in the Broker to display an Integer simply + as the Integer with no formatting. e.g new Integer(1234567) becomes the String + "1234567" which is can be contrasted with the pattern without a style format field : + {0,number} which becomes string "1,234,567".</para> + <para>What you may not expect is that {0,number, } would produce the String " 1234567" + note that the space after the ',' here has resulted in a space in front of the + number in the output.</para> + <para>More details on the SubformatPattern can be found on the API link above. To + provide fixed log messages as required by the Technical Specification:</para> + <para><tag xlink:href="http://cwiki.apache.org/confluence/display/qpid/Operational+Logging+-+Status+Update+-+Technical+SpecificationOperationalLogging-StatusUpdate-TechnicalSpecification-Howtoprovidefixedlogmessages">Operational Logging Tech Specification</tag></para> + <para>This file is processed by Velocity to create a number of classes that contain + static methods that provide LogMessages in the code to provide compile time + validation.</para> + <para>For details of what processing is done see GenerateLogMessages. </para> + <para>What a localiser or developer need know is the following: </para> + <para>The Property structure is important as it defines how the class and methods will + be built.</para> + </sect1> + <sect1> + <title>Class Generation</title> + <para> Each class of messages will be split in to their own <Class>Messages.java. + Each logmessage file contains only one class of messages the <Class> name is + derived from the name of the logmessages file e.g. <Class>_logmessages.properties. + </para> + </sect1> + <sect1> + <title>Property Format</title> + <para>The property format MUST adhere to the follow format to make it easier to use the + logging API as a developer but also so that operations staff can easily locate log + messages in the output.</para> + <para>The property file should contain entries in the following format:</para> + <programlisting><![CDATA[<Log Identifier,developer focused>=<Log Identifier,Operate focus>:<Log Message>]]> + </programlisting> + + <para>eg:</para> + <programlisting><![CDATA[SHUTTING_DOWN = BRK-1003 : Shutting down : {0} port {1,number,}]]> + </programlisting> + + <para>Note: the developer focused identifier will become a method name so only a valid + method name should be used. Currently only '-' are converted to '_'.</para> + <para>That said properties generate the logging code at build time so any error can be + easily identified.</para> + <para>The three character identifier show above in BRK-1003 should ideally be unique. + This is the only requirement, limiting to 3 characters is not required.</para> + <para>The current broker contains the following mappings:</para> + <para> + <table> + <title>Status Messages Mapping</title> + <tgroup cols="2"> + <colspec colname="c1" colnum="1" colwidth="118.29pt"/> + <colspec colname="c2" colnum="2" colwidth="135.18pt"/> + <thead> + <row> + <entry>Class</entry> + <entry> Type</entry> + </row> + </thead> + <tbody> + <row> + <entry>Broker</entry> + <entry>BRK</entry> + </row> + <row> + <entry>Management Console</entry> + <entry>MNG</entry> + </row> + <row> + <entry>VirtualHost</entry> + <entry>VHT</entry> + </row> + <row> + <entry>MessageStore</entry> + <entry>MST</entry> + </row> + <row> + <entry>ConfigStore</entry> + <entry>CFG</entry> + </row> + <row> + <entry>TransactionLog</entry> + <entry>TXN</entry> + </row> + <row> + <entry>Connection</entry> + <entry>CON</entry> + </row> + <row> + <entry>Channel</entry> + <entry>CHN</entry> + </row> + <row> + <entry>Queue</entry> + <entry>QUE</entry> + </row> + <row> + <entry>Exchange</entry> + <entry>EXH</entry> + </row> + <row> + <entry>Binding</entry> + <entry>BND</entry> + </row> + <row> + <entry>Subscription</entry> + <entry>SUB</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </sect1> + <sect1> + <title>Property Processing</title> + <para> + Each property is then processed by the GenerateLogMessages class to identify + the number and type of parameters, {x} entries. Parameters are defaulted to + String types but the use of FormatType number (e.g.{0,number}) will result + in a Number type being used. These parameters are then used to build the + method parameter list. e.g: + </para> + + <para>Property:</para> + <programlisting><![CDATA[SHUTTING_DOWN = BRK-1003 : Shutting down : {0} port {1,number,}]]></programlisting> + <para>becomes Method:</para> + <programlisting><![CDATA[public static LogMessage SHUTTING_DOWN(String param1, Number param2)]]> + </programlisting> + + <para> + This improves our compile time validation of log message content and + ensures that change in the message format does not accidentally cause + erroneous messages.</para> + </sect1> + <sect1> + <title>Option Processing</title> + <para> + Options are identified in the log message as being surrounded by square + brackets ([ ]). These optional values can themselves contain parameters + however nesting of options is not permitted. Identification is performed on + first matching so given the message: + </para> + <programlisting><![CDATA[Msg = Log Message [option1] [option2] ]]></programlisting> + <para> + Two options will be identified and enabled to select text 'option1' and + 'option2'. + </para> + <para> + The nesting of a options is not supported and will provide + unexpected results. e.g. Using Message: + </para> + <programlisting><![CDATA[Msg = Log Message [option1 [sub-option2]] ]]></programlisting> + <para> + The options will be 'option1 [sub-option2' and 'sub-option2'. The first + option includes the second option as the nesting is not detected. + </para> + <para> + The detected options are presented in the method signature as boolean options + numerically identified by their position in the message. e.g. + Property: + </para> + <programlisting><![CDATA[ CON-1001 = Open : Client ID {0} [: Protocol Version : {1}] ]]></programlisting> + <para>becomes Method:</para> + <programlisting><![CDATA[ public static LogMessage CON_1001(String param1, String param2, boolean opt1) ]]></programlisting> + <para> + The value of 'opt1' will show/hide the option in the message. Note that + 'param2' is still required however a null value can be used if the optional + section is not desired. + </para> + <para> + Again here the importance of white space needs to be highlighted. + Looking at the QUE-1001 message as an example. The first thought on how this + would look would be as follows: + </para> + <programlisting><![CDATA[ QUE-1001 = Create : Owner: {0} [AutoDelete] [Durable] [Transient] [Priority: {1,number,}] ]]></programlisting> + <para> + Each option is correctly defined so the text that is defined will appear when + selected. e.g. 'AutoDelete'. However, what may not be immediately apparent is + the white space. Using the above definition of QUE-1001 if we were to print + the message with only the Priority option displayed it would appear as this: + </para> + <programlisting><![CDATA[ "Create : Owner: guest Priority: 1" ]]></programlisting> + <para> + Note the spaces here in between gues and Priority are present because only the text between the brackets + has been removed. + </para> + <para> + Each option needs to include white space to correctly format the message. So + the correct definition of QUE-1001 is as follows: + </para> + <programlisting><![CDATA[ QUE-1001 = Create : Owner: {0}[ AutoDelete][ Durable][ Transient][ Priority: {1,number,}] ]]></programlisting> + <para> + Note that white space is included with each option and there is no extra + white space between the options. As a result the output with just Priority + enabled is as follows: + </para> + <programlisting><![CDATA[ "Create : Owner: guest Priority: 1" ]]></programlisting> + </sect1> + </chapter> +</book> diff --git a/qpid/doc/book/src/old/Java-JMS-Selector-Syntax.xml b/qpid/doc/book/src/old/Java-JMS-Selector-Syntax.xml new file mode 100644 index 0000000000..870e277b66 --- /dev/null +++ b/qpid/doc/book/src/old/Java-JMS-Selector-Syntax.xml @@ -0,0 +1,96 @@ +<!-- + - + - Licensed to the Apache Software Foundation (ASF) under one + - or more contributor license agreements. See the NOTICE file + - distributed with this work for additional information + - regarding copyright ownership. The ASF licenses this file + - to you 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. + - + --> +<section> + <title>Java JMS Selector Syntax</title> + <para>The AMQP Java JMS Messaging Client supports the following syntax for JMS selectors.</para> + +<programlisting><![CDATA[ +Comments: + + LINE_COMMENT: "--" (~["\n","\r"])* EOL + EOL: "\n"|"\r"|"\r\n" + BLOCK_COMMENT: "/*" (~["*"])* "*" ("*" | (~["*","/"] (~["*"])* "*"))* "/" + +Reserved Words (case insensitive): + + NOT: "NOT" + AND: "AND" + OR: "OR" + BETWEEN: "BETWEEN" + LIKE: "LIKE" + ESCAPE: "ESCAPE" + IN: "IN" + IS: "IS" + TRUE: "TRUE" + FALSE: "FALSE" + NULL: "NULL" + +Literals (case insensitive): + + DECIMAL_LITERAL: ["1"-"9"] (["0"-"9"])* (["l","L"])? + HEX_LITERAL: "0" ["x","X"] (["0"-"9","a"-"f","A"-"F"])+ + OCTAL_LITERAL: "0" (["0"-"7"])* + FLOATING_POINT_LITERAL: ( (["0"-"9"])+ "." (["0"-"9"])* (<EXPONENT>)? // matches: 5.5 or 5. or 5.5E10 or 5.E10 + | "." (["0"-"9"])+ (<EXPONENT>)? // matches: .5 or .5E10 + | (["0"-"9"])+ <EXPONENT> ) // matches: 5E10 + EXPONENT: "E" (["+","-"])? (["0"-"9"])+ + STRING_LITERAL: "'" ( ("''") | ~["'"] )* "'" + +Identifiers (case insensitive): + + ID : ["a"-"z", "_", "$"] (["a"-"z","0"-"9","_", "$"])* + QUOTED_ID : "\"" ( ("\"\"") | ~["\""] )* "\"" + +Grammar: + + JmsSelector := orExpression + orExpression := ( andExpression ( <OR> andExpression )* ) + andExpression := ( equalityExpression ( <AND> equalityExpression )* ) + equalityExpression := ( comparisonExpression ( "=" comparisonExpression + | "<>" comparisonExpression + | <IS> <NULL> + | <IS> <NOT> <NULL> )* ) + comparisonExpression := ( addExpression ( ">" addExpression + | ">=" addExpression + | "<" addExpression + | "<=" addExpression + | <LIKE> stringLitteral ( <ESCAPE> stringLitteral )? + | <NOT> <LIKE> <STRING_LITERAL> ( <ESCAPE> <STRING_LITERAL> )? + | <BETWEEN> addExpression <AND> addExpression + | <NOT> <BETWEEN> addExpression <AND> addExpression + | <IN> "(" <STRING_LITERAL> ( "," <STRING_LITERAL> )* ")" + | <NOT> <IN> "(" <STRING_LITERAL> ( "," <STRING_LITERAL> )* ")" )* ) + addExpression := multExpr ( ( "+" multExpr | "-" multExpr ) )* + multExpr := unaryExpr ( "*" unaryExpr | "/" unaryExpr | "%" unaryExpr )* + unaryExpr := ( "+" unaryExpr | "-" unaryExpr | <NOT> unaryExpr | primaryExpr ) + primaryExpr := ( literal | variable | "(" orExpression ")" ) + literal := ( <STRING_LITERAL> + | <DECIMAL_LITERAL> + | <HEX_LITERAL> + | <OCTAL_LITERAL> + | <FLOATING_POINT_LITERAL> + | <TRUE> + | <FALSE> + | <NULL> ) + variable := ( <ID> | <QUOTED_ID> ) +]]></programlisting> + +</section> diff --git a/qpid/doc/book/src/old/Management-Design-notes.xml b/qpid/doc/book/src/old/Management-Design-notes.xml new file mode 100644 index 0000000000..76f0dac926 --- /dev/null +++ b/qpid/doc/book/src/old/Management-Design-notes.xml @@ -0,0 +1,2136 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section><title> + Management Design notes + </title><section role="h2" id="ManagementDesignnotes-StatusofThisDocument"><title> + Status + of This Document + </title> + + <para> + This document does not track any current development activity. It + is the specification of the management framework implemented in + the M3 release of the C++ broker and will be left here for user + and developer reference. + </para><para> + Development continues on the Qpid Management Framework (QMF) for + M4. If you are using M3, this is the document you need. If you + are using the SVN trunk, please refer to <xref linkend="qpid_Qpid-Management-Framework"/> for + up-to-date information. + </para> + <!--h2--></section> + + <section role="h2" id="ManagementDesignnotes-Introduction"><title> + Introduction + </title> + + <para> + This document describes the management features that are used in + the QPID C++ broker as of the M3 milestone. These features do not + appear in earlier milestones nor are they implemented in the Java + broker. + </para><para> + This specification is <emphasis>not</emphasis> a standard and is not endorsed + by the AMQP working group. When such a standard is adopted, the + QPID implementation will be brought into compliance with that + standard. + </para> + <!--h2--></section> + + <section role="h2" id="ManagementDesignnotes-Links"><title> + Links + </title> + + <itemizedlist> + <listitem><para>The schema is checked into <xref linkend="qpid_management-schema.xml"/>. + </para></listitem> + </itemizedlist><section role="h3" id="ManagementDesignnotes-DesignnoteforgettinginfoinandoutviaJMX"><title> + Design + note for getting info in and out via JMX + </title> + + <para> + <xref linkend="qpid_JMX-Gateway"/> + </para> + <!--h3--></section> + + <!--h2--></section> + + <section role="h2" id="ManagementDesignnotes-ManagementRequirements"><title> + Management + Requirements + </title> + + <itemizedlist> + <listitem><para>Must operate from a formally defined management schema. + </para></listitem> + <listitem><para>Must natively use the AMQP protocol and its type system. + </para></listitem> + <listitem><para>Must support the following operations + <itemizedlist> + <listitem><para>SET operation on configurable (persistent) aspects of + objects + </para></listitem> + <listitem><para>GET operation on all aspects of objects + </para></listitem> + <listitem><para>METHOD invocation on schema-defined object-specific + methods + </para></listitem> + <listitem><para>Distribution of unsolicited periodic updates of + instrumentation data + <itemizedlist> + <listitem><para>Data updates shall carry an accurate sample timestamp + for rate calculation + </para></listitem> + <listitem><para>Updates shall carry object create/delete timestamps. + </para></listitem> + <listitem><para>Transient objects shall be fully accounted for via + updates. Note that short-lived transient objects may come + and go within a single update interval. All of the + information pertaining to such an object must be captured + and transmitted. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para>Distribution of unsolicited event and/or alert + indications (schema defined) + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para>Role-based access control at object, operation, and method + granularity + </para></listitem> + <listitem><para>End-to-end encryption and signing of management content + </para></listitem> + <listitem><para>Schema must be self-describing so the management client need + not have prior knowledge of the management model of the system + under management. + </para></listitem> + <listitem><para>Must be extensible to support the management of objects + beyond the QPID component set. This allows AMQP to be used as a + general-purpose management protocol. + </para></listitem> + </itemizedlist> + <!--h2--></section> + + <section role="h2" id="ManagementDesignnotes-DefinitionofTerms"><title> + Definition + of Terms + </title> + + <table><title/><tgroup cols="2"> + <tbody> + <row> + <entry> + class + </entry> + <entry> + A type definition for a manageable object. + </entry> + </row> + <row> + <entry> + package + </entry> + <entry> + A grouping of class definitions that are related to a + single software component. The package concept is used to + extend the management schema beyond just the QPID software + components. + </entry> + </row> + <row> + <entry> + object + </entry> + <entry> + Also "manageable object". An instantiation of a class. An + object represents a physical or logical component in the + core function of the system under management. + </entry> + </row> + <row> + <entry> + property + </entry> + <entry> + A typed member of a class which represents a configurable + attribute of the class. In general, properties don't change + frequently or may not change at all. + </entry> + </row> + <row> + <entry> + statistic + </entry> + <entry> + A typed member of a class which represents an + instrumentation attribute of the class. Statistics are + always read-only in nature and tend to change rapidly. + </entry> + </row> + <row> + <entry> + method + </entry> + <entry> + A member of a class which represents a callable procedure + on an object of the class. Methods may have an arbitrary + set of typed arguments and may supply a return code. + Methods typically have side effects on the associated + object. + </entry> + </row> + <row> + <entry> + event + </entry> + <entry> + A member of a class which represents the occurence of an + event of interest within the system under management. + </entry> + </row> + <row> + <entry> + management broker + </entry> + <entry> + A software component built into the messaging broker that + handles management traffic and distributes management data. + </entry> + </row> + <row> + <entry> + management agent + </entry> + <entry> + A software component that is separate from the messaging + broker, connected to the management broker via an AMQP + connection, which allows any software component to be + managed remotely by QPID. + </entry> + </row> + </tbody> + </tgroup></table> + <!--h2--></section> + + + <section role="h2" id="ManagementDesignnotes-OperationalScenarios-3ABasicvs.Extended"><title> + Operational + Scenarios: Basic vs. Extended + </title> + + <para> + The extensibility requirement introduces complexity to the + management protocol that is unnecessary and undesirable for the + user/developer that wishes only to manage QPID message brokers. + For this reason, the protocol is partitioned into two parts: The + <emphasis>basic protocol</emphasis>, which contains only the capability to + manage a single broker; and the <emphasis>extended protocol</emphasis>, which + provides the hooks for managing an extended set of components. A + management console can be implemented using only the basic + protocol if the extended capabilities are not needed. + </para> +<!--h2--></section> + + + <section role="h2" id="ManagementDesignnotes-ArchitecturalFramework"><title> + Architectural + Framework + </title> + + <para> + <xref linkend="qpid_qmf_architecture"/> + </para> + <!--h2--></section> + + <section role="h2" id="ManagementDesignnotes-TheManagementExchange"><title> + The + Management Exchange + </title> + + <para> + The management exchange (called "qpid.management" currently) is a + special type of exchange used for remote management access to the + Qpid broker. The management exchange is an extension of the + standard "Topic" exchange. It behaves like a topic exchange with + the following exceptions: + </para><orderedlist> + <listitem><para>When a queue is successfully bound to the exchange, a method + is invoked on the broker's management agent to notify it of the + presence of a new remote managment client. + </para></listitem> + <listitem><para>When messages arrive at the exchange for routing, the + exchange examines the message's routing key and if the key + represents a management command or method, it routes it directly + to the management agent rather than routing it to queues using + the topic algorithm. + The management exchange is used by the management agent to + distribute unsolicited management data. Such data is classified + by the routing key allowing management clients to register for + only the data they need. + </para></listitem> + </orderedlist><section role="h3" id="ManagementDesignnotes-RoutingKeyStructure"><title> + Routing + Key Structure + </title> + + <para> + As noted above, the structure of the binding and routing keys + used on the management exchange is important to the function of + the management architecture. The routing key of a management + message determines: + </para><orderedlist> + <listitem><para>The type of message (i.e. operation request or unsolicited + update). + </para></listitem> + <listitem><para>The class of the object that the message pertains to. + </para></listitem> + <listitem><para>The specific operation or update type. + </para></listitem> + <listitem><para>The namespace in which the class belongs. This allows for + plug-in expansion of the management schema for manageable objects + that are outside of the broker itself. + </para></listitem> + </orderedlist><para> + Placing this information in the routing key provides the ability + to enforce access control at class, operation, and method + granularity. It also separates the command structure from the + content of the management message (i.e. element values) allowing + the content to be encrypted and signed end-to-end while still + allowing access control at the message-transport level. This + means that special access control code need not be written for + the management agent. + There are two general types of routing/binding key: + </para><itemizedlist> + <listitem><para> + <emphasis>Command</emphasis> messages use the key: + agent.<bank#> or broker + </para></listitem> + <listitem><para> + <emphasis>Unsolicited</emphasis> keys have the structure: + mgmt.<agent>.<type>.<package>.<class>.<severity> + where + <itemizedlist> + <listitem><para> + <agent> is the uuid of the originating + management agent, + </para></listitem> + <listitem><para> + <type> is one of "schema", "prop", "stat", + or "event", + </para></listitem> + <listitem><para> + <package> is the namespace in which the + <class> name is valid, and + </para></listitem> + <listitem><para> + <class> is the name of the class as defined + in the schema. + </para></listitem> + <listitem><para> + <severity> is relevant for events only. It + is one of "critical", "error", "warning", or "info". + </para></listitem> + </itemizedlist> + </para></listitem> + </itemizedlist><para> + In both cases, the content of the message (i.e. method arguments, + element values, etc.) is carried in the body segment of the + message. + </para><para> + The <package> namespace allows this management + framework to be extended with the addition of other software + packages. + </para> + <!--h3--></section> + <!--h2--></section> + + <section role="h2" id="ManagementDesignnotes-TheProtocol"><title> + The Protocol + </title> + + <section role="h3" id="ManagementDesignnotes-ProtocolHeader"><title> + Protocol + Header + </title> + + <para> + The body segments of management messages are composed of + sequences of binary-encoded data fields, in a manner consistent + with the 0-10 version of the AMQP specification. + </para><para> + All management messages begin with a message header: + </para> + <programlisting> + octet 0 1 2 3 4 5 6 7 + +---------+---------+---------+---------+---------+---------+---------+---------+ + | 'A' | 'M' | '1' | op-code | sequence | + +---------+---------+---------+---------+---------+---------+---------+---------+ +</programlisting> + <para> + The first three octets contain the protocol <emphasis>magic number</emphasis> + "AM1" which is used to identify the type and version of the + message. + </para><para> + The <emphasis>opcode</emphasis> field identifies the operation represented by + the message + </para> + <!--h3--></section> + + <section role="h3" id="ManagementDesignnotes-ProtocolExchangePatterns"><title> + Protocol + Exchange Patterns + </title> + + <para> + The following patterns are followed in the design of the + protocol: + </para><itemizedlist> + <listitem><para>Request-Response + </para></listitem> + <listitem><para>Query-Indication + </para></listitem> + <listitem><para>Unsolicited Indication + </para></listitem> + </itemizedlist><section role="h4" id="ManagementDesignnotes-TheRequestResponsePattern"><title> + The + Request-Response Pattern + </title> + + <para> + In the request-response pattern, a requestor sends a + <emphasis>request</emphasis> message to one of its peers. The peer then does + one of two things: If the request can be successfully processed, + a single <emphasis>response</emphasis> message is sent back to the requestor. + This response contains the requested results and serves as the + positive acknowledgement that the request was successfully + completed. + </para><para> + If the request cannot be successfully completed, the peer sends a + <emphasis>command complete</emphasis> message back to the requestor with an + error code and error text describing what went wrong. + </para><para> + The sequence number in the <emphasis>response</emphasis> or <emphasis>command + complete</emphasis> message is the same as the sequence number in the + <emphasis>request</emphasis>. + </para> + <programlisting> + Requestor Peer + | | + | --- Request (seq) ------------------------------------------> | + | | + | <----------------------------------------- Response (seq) --- | + | | +</programlisting> + + <programlisting> + Requestor Peer + | | + | --- Request (seq) ------------------------------------------> | + | | + | <-------------------------- Command Complete (seq, error) --- | + | | +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-TheQueryIndicationPattern"><title> + The + Query-Indication Pattern + </title> + + <para> + The query-indication pattern is used when there may be zero or + more answers to a question. In this case, the requestor sends a + <emphasis>query</emphasis> message to its peer. The peer processes the query, + sending as many <emphasis>indication</emphasis> messages as needed back to the + requestor (zero or more). Once the last <emphasis>indication</emphasis> has + been sent, the peer then sends a <emphasis>command complete</emphasis> message + with a success code indicating that the query is complete. + </para><para> + If there is an error in the <emphasis>query</emphasis>, the peer may reply with + a <emphasis>command complete</emphasis> message containg an error code. In this + case, no <emphasis>indication</emphasis> messages may be sent. + </para><para> + All <emphasis>indication</emphasis> and <emphasis>command complete</emphasis> messages shall + have the same sequence number that appeared in the <emphasis>query</emphasis> + message. + </para> + <programlisting> + Requestor Peer + | | + | --- Query (seq) --------------------------------------------> | + | | + | <--------------------------------------- Indication (seq) --- | + | <--------------------------------------- Indication (seq) --- | + | <--------------------------------------- Indication (seq) --- | + | <--------------------------------------- Indication (seq) --- | + | <--------------------------------------- Indication (seq) --- | + | | + | <------------------------ Command Complete (seq, success) --- | + | | +</programlisting> + + <programlisting> + Requestor Peer + | | + | --- Query (seq) --------------------------------------------> | + | | + | <-------------------------- Command Complete (seq, error) --- | + | | +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-TheUnsolicitedIndicationPattern"><title> + The + Unsolicited-Indication Pattern + </title> + + <para> + The unsolicited-indication pattern is used when one peer needs to + send unsolicited information to another peer, or to broadcast + information to multiple peers via a topic exchange. In this case, + indication messages are sent with the sequence number field set + to zero. + </para> + <programlisting> + Peer Peer + | | + | <----------------------------------- Indication (seq = 0) --- | + | <----------------------------------- Indication (seq = 0) --- | + | <----------------------------------- Indication (seq = 0) --- | + | <----------------------------------- Indication (seq = 0) --- | + | | +</programlisting> +<!--h4--></section> +<!--h3--></section> + + <section role="h3" id="ManagementDesignnotes-ObjectIdentifiers"><title> + Object + Identifiers + </title> + + <para> + Manageable objects are tagged with a unique 64-bit object + identifier. The object identifier space is owned and managed by + the management broker. Objects managed by a single management + broker shall have unique object identifiers. Objects managed by + separate management brokers may have the same object identifier. + </para><para> + If a management console is designed to manage multiple management + brokers, it must use the broker identifier as well as the object + identifier to ensure global uniqueness. + </para> + <programlisting> + 62 48 47 24 23 0 + +-+-------------+-----------------------+-----------------------+ + |0| sequence | bank | object | + +-+-------------+-----------------------+-----------------------+ + + bit 63 - reserved, must be zero + bits 63 .. 48 - broker boot sequence (32K) + bits 47 .. 24 - bank (16M) + bits 23 .. 0 - object (16M) +</programlisting> + <itemizedlist> + <listitem><para>For persistent IDs, boot-sequence is zero + </para></listitem> + <listitem><para>For non-persistent IDs, boot sequence is a constant number + which increments each time the management broker is restarted. + </para></listitem> + <listitem><para>Bank number: + <itemizedlist> + <listitem><para>0 - reserved + </para></listitem> + <listitem><para>1 - broker-persistent objects + </para></listitem> + <listitem><para>2..4 - store-persistent objects + </para></listitem> + <listitem><para>> 4 - transient objects + </para></listitem> + </itemizedlist> + </para></listitem> + </itemizedlist> +<!--h3--></section> + + + <section role="h3" id="ManagementDesignnotes-EstablishingCommunicationBetweenClientandAgent"><title> + Establishing Communication Between Client and Agent + </title> + + <para> + Communication is established between the management client and + management agent using normal AMQP procedures. The client creates + a connection to the broker and then establishes a session with + its corresponding channel. + </para><para> + Two private queues are then declared (only one if method + invocation is not needed). A management queue is declared and + bound to the qpid.management exchange. If the binding key is + "mgmt.#", all management-related messages sent to the exchange + will be received by this client. A more specific binding key will + result in a more restricted set of messages being received (see + the section on Routing Key Structure below). + </para><para> + If methods are going to be invoked on managed objects, a second + private queue must be declared so the client can receive method + replies. This queue is bound to the amq.direct exchange using a + routing key equal to the name of the queue. + </para><para> + When a client successfully binds to the qpid.management exchange, + the management agent schedules a schema broadcast to be sent to + the exchange. The agent will publish, via the exchange, a + description of the schema for all manageable objects in its + control. + </para> + <programlisting> + Client Broker + | | + | --- AMQP Connection and Session Setup ----------------------> | + | | + | --- Queue.declare (private data queue) ---------------------> | + | --- Bind queue to exchange 'qpid.management' key 'mgmt.#' --> | + | | + | --- Queue.declare (private method-reply queue) -------------> | + | --- Bind queue to exchange 'amq.direct' --------------------> | + | | + | --- Broker Request -----------------------------------------> | + | <---------------------------------------- Broker Response --- | + | | + | | + | | + | <------- Management schema via exchange 'qpid.management' --- | + | | +</programlisting> +<!--h3--></section> + + <section role="h3" id="ManagementDesignnotes-BroadcastofConfigurationandInstrumentationUpdates"><title> + Broadcast of Configuration and Instrumentation Updates + </title> + + <para> + The management agent will periodically publish updates to the + configuration and instrumentation of management objects under its + control. Under normal circumstances, these updates are published + only if they have changed since the last time they were + published. Configuration updates are only published if + configuration has changed and instrumentation updates are only + published if instrumentation has changed. The exception to this + rule is that after a management client binds to the + qpid.management exchange, all configuration and instrumentation + records are published as though they had changed whether or not + they actually did. + </para> + <programlisting> + Client Broker + | | + | <------------------ Object properties via 'mgmt.*.prop.#' --- | | + | <------------------ Object statistics via 'mgmt.*.stat.#' --- | | + | | | + | | | Publish Interval + | | | + | | | + | | V + | <------------------ Object properties via 'mgmt.*.prop.#' --- | + | <------------------ Object statistics via 'mgmt.*.stat.#' --- | + | | +</programlisting> +<!--h3--></section> + + <section role="h3" id="ManagementDesignnotes-InvokingaMethodonaManagedObject"><title> + Invoking + a Method on a Managed Object + </title> + + <para> + When the management client wishes to invoke a method on a managed + object, it sends a method request message to the qpid.management + exchange. The routing key contains the object class and method + name (refer to Routing Key Structure below). The method request + must have a header entry (reply-to) that contains the name of the + method-reply queue so that the method response can be properly + routed back to the requestor. + </para><para> + The method request contains a sequence number that is copied to + the method reply. This number is opaque to the management agent + and may be used by the management client to correlate the reply + to the request. The asynchronous nature of requests and replies + allows any number of methods to be in-flight at a time. Note that + there is no guarantee that methods will be replied to in the + order in which they were requested. + </para> + <programlisting> + Client Broker + | | + | --- Method Request (to exchange 'qpid.management') ---------> | + | | + | | + | <--------------- Method Reply (via exchange 'amq.direct') --- | + | | +</programlisting> +<!--h3--></section> + + + <section role="h3" id="ManagementDesignnotes-MessagesfortheBasicScenario"><title> + Messages + for the Basic Scenario + </title> + + <para> + The principals in a management exchange are the <emphasis>management + client</emphasis> and the <emphasis>management agent</emphasis>. The management + agent is integrated into the QPID broker and the management + client is a remote entity. A management agent may be managed by + zero or more management clients at any given time. Additionally, + a management client may manage multiple management agents at the + same time. + </para><para> + For authentication and access control, management relies on the + mechanisms supplied by the AMQP protocol. + </para><section role="h4" id="ManagementDesignnotes-BasicOpcodes"><title> + Basic Opcodes + </title> + + <table><title/><tgroup cols="3"> + <tbody> + <row> + <entry> + <emphasis>opcode</emphasis> + </entry> + <entry> + <emphasis>message</emphasis> + </entry> + <entry> + <emphasis>description</emphasis> + </entry> + </row> + <row> + <entry> + 'B' + </entry> + <entry> + Broker Request + </entry> + <entry> + This message contains a broker request, sent from the + management console to the broker to initiate a management + session. + </entry> + </row> + <row> + <entry> + 'b' + </entry> + <entry> + Broker Response + </entry> + <entry> + This message contains a broker response, sent from the + broker in response to a broker request message. + </entry> + </row> + <row> + <entry> + 'z' + </entry> + <entry> + Command Completion + </entry> + <entry> + This message is sent to indicate the completion of a + request. + </entry> + </row> + <row> + <entry> + 'Q' + </entry> + <entry> + Class Query + </entry> + <entry> + Class query messages are used by a management console to + request a list of schema classes that are known by the + management broker. + </entry> + </row> + <row> + <entry> + 'q' + </entry> + <entry> + Class Indication + </entry> + <entry> + Sent by the management broker, a class indication notifies + the peer of the existence of a schema class. + </entry> + </row> + <row> + <entry> + 'S' + </entry> + <entry> + Schema Request + </entry> + <entry> + Schema request messages are used to request the full schema + details for a class. + </entry> + </row> + <row> + <entry> + 's' + </entry> + <entry> + Schema Response + </entry> + <entry> + Schema response message contain a full description of the + schema for a class. + </entry> + </row> + <row> + <entry> + 'h' + </entry> + <entry> + Heartbeat Indication + </entry> + <entry> + This message is published once per publish-interval. It can + be used by a client to positively determine which objects + did not change during the interval (since updates are not + published for objects with no changes). + </entry> + </row> + <row> + <entry> + 'c', 'i', 'g' + </entry> + <entry> + Content Indication + </entry> + <entry> + This message contains a content record. Content records + contain the values of all properties or statistics in an + object. Such records are broadcast on a periodic interval + if 1) a change has been made in the value of one of the + elements, or 2) if a new management client has bound a + queue to the management exchange. + </entry> + </row> + <row> + <entry> + 'G' + </entry> + <entry> + Get Query + </entry> + <entry> + Sent by a management console, a get query requests that the + management broker provide content indications for all + objects that match the query criteria. + </entry> + </row> + <row> + <entry> + 'M' + </entry> + <entry> + Method Request + </entry> + <entry> + This message contains a method request. + </entry> + </row> + <row> + <entry> + 'm' + </entry> + <entry> + Method Response + </entry> + <entry> + This message contains a method result. + </entry> + </row> + </tbody> + </tgroup></table> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-BrokerRequestMessage"><title> + Broker + Request Message + </title> + + <para> + When a management client first establishes contact with the + broker, it sends a Hello message to initiate the exchange. + </para> + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'B' | 0 | + +-----+-----+-----+-----+-----------------------+ +</programlisting> + <para> + The Broker Request message has no payload. + </para> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-BrokerResponseMessage"><title> + Broker + Response Message + </title> + + <para> + When the broker receives a Broker Request message, it responds + with a Broker Response message. This message contains an + identifier unique to the broker. + </para> + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'b' | 0 | + +-----+-----+-----+-----+-----------------------+----------------------------+ + | brokerId (uuid) | + +----------------------------------------------------------------------------+ +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-CommandCompletionMessage"><title> + Command + Completion Message + </title> + + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'z' | seq | + +-----+-----+-----+-----+-----------------------+ + | Completion Code | + +-----------------------+-----------------------------------------+ + | Completion Text | + +-----------------------------------------------------------------+ +</programlisting> +<!--h4--></section> + + + <section role="h4" id="ManagementDesignnotes-ClassQuery"><title> + Class Query + </title> + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'Q' | seq | + +-----+-----+-----+-----+-----------------------+----------+ + | package name (str8) | + +----------------------------------------------------------+ +</programlisting> +<!--h4--></section> + + + <section role="h4" id="ManagementDesignnotes-ClassIndication"><title> + Class + Indication + </title> + + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'q' | seq | + +-----+-----+-----+-----+-----------------------+----------+ + | package name (str8) | + +----------------------------------------------------------+ + | class name (str8) | + +----------------------------------------------------------+ + | schema hash (bin128) | + +----------------------------------------------------------+ +</programlisting> +<!--h4--></section> + + + <section role="h4" id="ManagementDesignnotes-SchemaRequest"><title> + Schema Request + </title> + + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'S' | seq | + +-----+-----+-----+-----+-----------------------+----------+ + | packageName (str8) | + +----------------------------------------------------------+ + | className (str8) | + +----------------------------------------------------------+ + | schema-hash (bin128) | + +----------------------------------------------------------+ +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-SchemaResponse"><title> + Schema + Response + </title> + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 's' | seq | + +-----+-----+-----+-----+-----------------------+----------+ + | packageName (str8) | + +----------------------------------------------------------+ + | className (str8) | + +----------------------------------------------------------+ + | schema-hash (bin128) | + +-----------+-----------+-----------+-----------+----------+ + | propCnt | statCnt | methodCnt | eventCnt | + +-----------+-----------+-----------+-----------+----------------------------+ + | propCnt property records | + +----------------------------------------------------------------------------+ + | statCnt statistic records | + +----------------------------------------------------------------------------+ + | methodCnt method records | + +----------------------------------------------------------------------------+ + | eventCnt event records | + +----------------------------------------------------------------------------+ +</programlisting> + <para> + Each <emphasis>property</emphasis> record is an AMQP map with the following + fields. Optional fields may optionally be omitted from the map. + </para><table><title/><tgroup cols="3"> + <tbody> + <row> + <entry> + <emphasis>field name</emphasis> + </entry> + <entry> + <emphasis>optional</emphasis> + </entry> + <entry> + <emphasis>description</emphasis> + </entry> + </row> + <row> + <entry> + name + </entry> + <entry> + no + </entry> + <entry> + Name of the property + </entry> + </row> + <row> + <entry> + type + </entry> + <entry> + no + </entry> + <entry> + Type code for the property + </entry> + </row> + <row> + <entry> + access + </entry> + <entry> + no + </entry> + <entry> + Access code for the property + </entry> + </row> + <row> + <entry> + index + </entry> + <entry> + no + </entry> + <entry> + 1 = index element, 0 = not an index element + </entry> + </row> + <row> + <entry> + optional + </entry> + <entry> + no + </entry> + <entry> + 1 = optional element (may be not present), 0 = mandatory + (always present) + </entry> + </row> + <row> + <entry> + unit + </entry> + <entry> + yes + </entry> + <entry> + Units for numeric values (i.e. seconds, bytes, etc.) + </entry> + </row> + <row> + <entry> + min + </entry> + <entry> + yes + </entry> + <entry> + Minimum value for numerics + </entry> + </row> + <row> + <entry> + max + </entry> + <entry> + yes + </entry> + <entry> + Maximum value for numerics + </entry> + </row> + <row> + <entry> + maxlen + </entry> + <entry> + yes + </entry> + <entry> + Maximum length for strings + </entry> + </row> + <row> + <entry> + desc + </entry> + <entry> + yes + </entry> + <entry> + Description of the property + </entry> + </row> + </tbody> + </tgroup></table><para> + Each <emphasis>statistic</emphasis> record is an AMQP map with the following + fields: + </para><table><title/><tgroup cols="3"> + <tbody> + <row> + <entry> + <emphasis>field name</emphasis> + </entry> + <entry> + <emphasis>optional</emphasis> + </entry> + <entry> + <emphasis>description</emphasis> + </entry> + </row> + <row> + <entry> + name + </entry> + <entry> + no + </entry> + <entry> + Name of the statistic + </entry> + </row> + <row> + <entry> + type + </entry> + <entry> + no + </entry> + <entry> + Type code for the statistic + </entry> + </row> + <row> + <entry> + unit + </entry> + <entry> + yes + </entry> + <entry> + Units for numeric values (i.e. seconds, bytes, etc.) + </entry> + </row> + <row> + <entry> + desc + </entry> + <entry> + yes + </entry> + <entry> + Description of the statistic + </entry> + </row> + </tbody> + </tgroup></table><para> + <emphasis>method</emphasis> and <emphasis>event</emphasis> records contain a main map that + describes the method or header followed by zero or more maps + describing arguments. The main map contains the following fields: + </para><table><title/><tgroup cols="3"> + <tbody> + <row> + <entry> + <emphasis>field name</emphasis> + </entry> + <entry> + <emphasis>optional</emphasis> + </entry> + <entry> + <emphasis>description</emphasis> + </entry> + </row> + <row> + <entry> + name + </entry> + <entry> + no + </entry> + <entry> + Name of the method or event + </entry> + </row> + <row> + <entry> + argCount + </entry> + <entry> + no + </entry> + <entry> + Number of argument records to follow + </entry> + </row> + <row> + <entry> + desc + </entry> + <entry> + yes + </entry> + <entry> + Description of the method or event + </entry> + </row> + </tbody> + </tgroup></table><para> + Argument maps contain the following fields: + </para><table><title/><tgroup cols="5"> + <tbody> + <row> + <entry> + <emphasis>field name</emphasis> + </entry> + <entry> + <emphasis>method</emphasis> + </entry> + <entry> + <emphasis>event</emphasis> + </entry> + <entry> + <emphasis>optional</emphasis> + </entry> + <entry> + <emphasis>description</emphasis> + </entry> + </row> + <row> + <entry> + name + </entry> + <entry> + yes + </entry> + <entry> + yes + </entry> + <entry> + no + </entry> + <entry> + Argument name + </entry> + </row> + <row> + <entry> + type + </entry> + <entry> + yes + </entry> + <entry> + yes + </entry> + <entry> + no + </entry> + <entry> + Type code for the argument + </entry> + </row> + <row> + <entry> + dir + </entry> + <entry> + yes + </entry> + <entry> + no + </entry> + <entry> + yes + </entry> + <entry> + Direction code for method arguments + </entry> + </row> + <row> + <entry> + unit + </entry> + <entry> + yes + </entry> + <entry> + yes + </entry> + <entry> + yes + </entry> + <entry> + Units for numeric values (i.e. seconds, bytes, etc.) + </entry> + </row> + <row> + <entry> + min + </entry> + <entry> + yes + </entry> + <entry> + no + </entry> + <entry> + yes + </entry> + <entry> + Minimum value for numerics + </entry> + </row> + <row> + <entry> + max + </entry> + <entry> + yes + </entry> + <entry> + no + </entry> + <entry> + yes + </entry> + <entry> + Maximum value for numerics + </entry> + </row> + <row> + <entry> + maxlen + </entry> + <entry> + yes + </entry> + <entry> + no + </entry> + <entry> + yes + </entry> + <entry> + Maximum length for strings + </entry> + </row> + <row> + <entry> + desc + </entry> + <entry> + yes + </entry> + <entry> + yes + </entry> + <entry> + yes + </entry> + <entry> + Description of the argument + </entry> + </row> + <row> + <entry> + default + </entry> + <entry> + yes + </entry> + <entry> + no + </entry> + <entry> + yes + </entry> + <entry> + Default value for the argument + </entry> + </row> + </tbody> + </tgroup></table><para> + <emphasis>type codes</emphasis> are numerics with the following values: + </para><table><title/><tgroup cols="2"> + <tbody> + <row> + <entry> + <emphasis>value</emphasis> + </entry> + <entry> + <emphasis>type</emphasis> + </entry> + </row> + <row> + <entry> + 1 + </entry> + <entry> + uint8 + </entry> + </row> + <row> + <entry> + 2 + </entry> + <entry> + uint16 + </entry> + </row> + <row> + <entry> + 3 + </entry> + <entry> + uint32 + </entry> + </row> + <row> + <entry> + 4 + </entry> + <entry> + uint64 + </entry> + </row> + <row> + <entry> + 6 + </entry> + <entry> + str8 + </entry> + </row> + <row> + <entry> + 7 + </entry> + <entry> + str16 + </entry> + </row> + <row> + <entry> + 8 + </entry> + <entry> + absTime(uint64) + </entry> + </row> + <row> + <entry> + 9 + </entry> + <entry> + deltaTime(uint64) + </entry> + </row> + <row> + <entry> + 10 + </entry> + <entry> + objectReference(uint64) + </entry> + </row> + <row> + <entry> + 11 + </entry> + <entry> + boolean(uint8) + </entry> + </row> + <row> + <entry> + 12 + </entry> + <entry> + float + </entry> + </row> + <row> + <entry> + 13 + </entry> + <entry> + double + </entry> + </row> + <row> + <entry> + 14 + </entry> + <entry> + uuid + </entry> + </row> + <row> + <entry> + 15 + </entry> + <entry> + map + </entry> + </row> + <row> + <entry> + 16 + </entry> + <entry> + int8 + </entry> + </row> + <row> + <entry> + 17 + </entry> + <entry> + int16 + </entry> + </row> + <row> + <entry> + 18 + </entry> + <entry> + int32 + </entry> + </row> + <row> + <entry> + 19 + </entry> + <entry> + int64 + </entry> + </row> + </tbody> + </tgroup></table><para> + <emphasis>access codes</emphasis> are numerics with the following values: + </para><table><title/><tgroup cols="2"> + <tbody> + <row> + <entry> + <emphasis>value</emphasis> + </entry> + <entry> + <emphasis>access</emphasis> + </entry> + </row> + <row> + <entry> + 1 + </entry> + <entry> + Read-Create access + </entry> + </row> + <row> + <entry> + 2 + </entry> + <entry> + Read-Write access + </entry> + </row> + <row> + <entry> + 3 + </entry> + <entry> + Read-Only access + </entry> + </row> + </tbody> + </tgroup></table><para> + <emphasis>direction codes</emphasis> are numerics with the following values: + </para><table><title/><tgroup cols="2"> + <tbody> + <row> + <entry> + <emphasis>value</emphasis> + </entry> + <entry> + <emphasis>direction</emphasis> + </entry> + </row> + <row> + <entry> + 1 + </entry> + <entry> + Input (from client to broker) + </entry> + </row> + <row> + <entry> + 2 + </entry> + <entry> + Output (from broker to client) + </entry> + </row> + <row> + <entry> + 3 + </entry> + <entry> + IO (bidirectional) + </entry> + </row> + </tbody> + </tgroup></table> +<!--h4--></section> + + + <section role="h4" id="ManagementDesignnotes-HeartbeatIndication"><title> + Heartbeat + Indication + </title> + + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'h' | 0 | + +-----+-----+-----+-----+-----------------------+ + | timestamp of current interval (datetime) | + +-----------------------------------------------+ +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-ConfigurationandInstrumentationContentMessages"><title> + Configuration and Instrumentation Content Messages + </title> + + <para> + Content messages are published when changes are made to the + values of properties or statistics or when new management clients + bind a queue to the management exchange. + </para> + <programlisting> + +-----+-----+-----+-------+-----------------------+ + | 'A' | 'M' | '1' |'g/c/i'| seq | + +-----+-----+-----+-------+-----------------------+--------+ + | packageName (str8) | + +----------------------------------------------------------+ + | className (str8) | + +----------------------------------------------------------+ + | class hash (bin128) | + +-----+-----+-----+-----+-----+-----+-----+-----+----------+ + | timestamp of current sample (datetime) | + +-----+-----+-----+-----+-----+-----+-----+-----+ + | time object was created (datetime) | + +-----+-----+-----+-----+-----+-----+-----+-----+ + | time object was deleted (datetime) | + +-----+-----+-----+-----+-----+-----+-----+-----+ + | objectId (uint64) | + +-----+-----+-----+-----+-----+-----+-----+-----+ + | presence bitmasks (0 or more uint8 fields) | + +-----+-----+-----+-----+-----+-----+-----+-----+------------------------+ + | config/inst values (in schema order) | + +------------------------------------------------------------------------+ +</programlisting> + <para> + All timestamps are uint64 values representing nanoseconds since + the epoch (January 1, 1970). The objectId is a uint64 value that + uniquely identifies this object instance. + </para><para> + If any of the properties in the object are defined as optional, + there will be 1 or more "presence bitmask" octets. There are as + many octets as are needed to provide one bit per optional + property. The bits are assigned to the optional properties in + schema order (first octet first, lowest order bit first). + </para><para> + For example: If there are two optional properties in the schema + called "option1" and "option2" (defined in that order), there + will be one presence bitmask octet and the bits will be assigned + as bit 0 controls option1 and bit 1 controls option2. + </para><para> + If the bit for a particular optional property is set (1), the + property will be encoded normally in the "values" portion of the + message. If the bit is clear (0), the property will be omitted + from the list of encoded values and will be considered "NULL" or + "not present". + </para><para> + The element values are encoded by their type into the message in + the order in which they appeared in the schema message. + </para> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-GetQueryMessage"><title> + Get Query + Message + </title> + + <para> + A Get Request may be sent by the management console to cause a + management agent to immediately send content information for + objects of a class. + </para> + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'G' | seq | + +-----+-----+-----+-----+-----------------------+----------+ + | Get request field table | + +----------------------------------------------------------+ +</programlisting> + <para> + The content of a get request is a field table that specifies what + objects are being requested. Most of the fields are optional and + are available for use in more extensive deployments. + </para><table><title/><tgroup cols="4"> + <tbody> + <row> + <entry> + <emphasis>Field Key</emphasis> + </entry> + <entry> + <emphasis>Mandatory</emphasis> + </entry> + <entry> + <emphasis>Type</emphasis> + </entry> + <entry> + <emphasis>Description</emphasis> + </entry> + </row> + <row> + <entry> + "_class" + </entry> + <entry> + yes + </entry> + <entry> + short-string + </entry> + <entry> + The name of the class of objects being requested. + </entry> + </row> + <row> + <entry> + "_package" + </entry> + <entry> + no + </entry> + <entry> + short-string + </entry> + <entry> + The name of the extension package the class belongs to. If + omitted, the package defaults to "qpid" for access to + objects in the connected broker. + </entry> + </row> + <row> + <entry> + "_agent" + </entry> + <entry> + no + </entry> + <entry> + uuid + </entry> + <entry> + The management agent that is the target of the request. If + omitted, agent defaults to the connected broker. + </entry> + </row> + </tbody> + </tgroup></table><para> + When the management agent receives a get request, it sends + content messages describing the requested objects. Once the last + content message is sent, it then sends a Command Completion + message with the same sequence number supplied in the request to + indicate to the requestor that there are no more messages coming. + </para> +<!--h4--></section> + + + <section role="h4" id="ManagementDesignnotes-MethodRequest"><title> + Method Request + </title> + + <para> + Method request messages have the following structure. The + sequence number is opaque to the management agent. It is returned + unchanged in the method reply so the calling client can correctly + associate the reply to the request. The objectId is the unique ID + of the object on which the method is to be executed. + </para> + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'M' | seq | + +-----+-----+-----+-----+-----------------------+ + | objectId (uint64) | + +-----------------------------------------------+ + | methodName (str8) | + +-----------------------------------------------+------------------------+ + | input and bidirectional argument values (in schema order) | + +------------------------------------------------------------------------+ +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-MethodResponse"><title> + Method + Response + </title> + + <para> + Method reply messages have the following structure. The sequence + number is identical to that supplied in the method request. The + status code (and text) indicate whether or not the method was + successful and if not, what the error was. Output and + bidirectional arguments are only included if the status code was + 0 (STATUS_OK). + </para> + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'm' | seq | + +-----+-----+-----+-----+-----------------------+ + | status code | + +-----------------------+----------------------------------+ + | status text (str8) | + +-----------------------+----------------------------------+-------------+ + | output and bidirectional argument values (in schema order) | + +------------------------------------------------------------------------+ +</programlisting> + <para> + <emphasis>status code</emphasis> values are: + </para><table><title/><tgroup cols="2"> + <tbody> + <row> + <entry> + <emphasis>value</emphasis> + </entry> + <entry> + <emphasis>description</emphasis> + </entry> + </row> + <row> + <entry> + 0 + </entry> + <entry> + STATUS_OK - successful completion + </entry> + </row> + <row> + <entry> + 1 + </entry> + <entry> + STATUS_UNKNOWN_OBJECT - objectId not found in the agent + </entry> + </row> + <row> + <entry> + 2 + </entry> + <entry> + STATUS_UNKNOWN_METHOD - method is not known by the object + type + </entry> + </row> + <row> + <entry> + 3 + </entry> + <entry> + STATUS_NOT_IMPLEMENTED - method is not currently + implemented + </entry> + </row> + </tbody> + </tgroup></table> +<!--h4--></section> +<!--h3--></section> + + <section role="h3" id="ManagementDesignnotes-MessagesforExtendedScenario"><title> + Messages + for Extended Scenario + </title> + + <section role="h4" id="ManagementDesignnotes-ExtendedManagementProtocol"><title> + Extended + Management Protocol + </title> + + <para> + Qpid supports management extensions that allow the management + broker to be a central point for the management of multiple + external entities with their own management schemas. + </para> + <programlisting> + Broker Remote Agent + | | + | <----------------------------------------- Attach Request --- | + | --- Attach Response ----------------------------------------> | + | | + | <------------------------------------- Package Indication --- | + | <------------------------------------- Package Indication --- | + | | + | <--------------------------------------- Class Indication --- | + | <--------------------------------------- Class Indication --- | + | <--------------------------------------- Class Indication --- | + | <--------------------------------------- Class Indication --- | + | <--------------------------------------- Class Indication --- | + | | + | --- Schema Request (class key) -----------------------------> | + | <---------------------------------------- Schema Response --- | + | | + | --- Schema Request (class key) -----------------------------> | + | <---------------------------------------- Schema Response --- | + | | + | | +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-ExtendedOpcodes"><title> + Extended + Opcodes + </title> + + <table><title/><tgroup cols="3"> + <tbody> + <row> + <entry> + <emphasis>opcode</emphasis> + </entry> + <entry> + <emphasis>message</emphasis> + </entry> + <entry> + <emphasis>description</emphasis> + </entry> + </row> + <row> + <entry> + 'P' + </entry> + <entry> + Package Query + </entry> + <entry> + This message contains a schema package query request, + requesting that the broker dump the list of known packages + </entry> + </row> + <row> + <entry> + 'p' + </entry> + <entry> + Package Indication + </entry> + <entry> + This message contains a schema package indication, + identifying a package known by the broker + </entry> + </row> + <row> + <entry> + 'A' + </entry> + <entry> + Agent Attach Request + </entry> + <entry> + This message is sent by a remote agent when it wishes to + attach to a management broker + </entry> + </row> + <row> + <entry> + 'a' + </entry> + <entry> + Agent Attach Response + </entry> + <entry> + The management broker sends this response if an attaching + remote agent is permitted to join + </entry> + </row> + <row> + <entry> + 'x' + </entry> + <entry> + Console Added Indication + </entry> + <entry> + This message is sent to all remote agents by the management + broker when a new console binds to the management exchange + </entry> + </row> + </tbody> + </tgroup></table> +<!--h4--></section> + + + <section role="h4" id="ManagementDesignnotes-PackageQuery"><title> + Package Query + </title> + + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'P' | seq | + +-----+-----+-----+-----+-----------------------+ +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-PackageIndication"><title> + Package + Indication + </title> + + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'p' | seq | + +-----+-----+-----+-----+-----------------------+----------+ + | package name (str8) | + +----------------------------------------------------------+ +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-AttachRequest"><title> + Attach Request + </title> + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'A' | seq | + +-----+-----+-----+-----+-----------------------+----------+ + | label (str8) | + +-----------------------+----------------------------------+ + | system-id (uuid) | + +-----------------------+----------------------------------+ + | requested objId bank | + +-----------------------+ +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-AttachResponse-28success-29"><title> + Attach + Response (success) + </title> + + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'a' | seq | + +-----+-----+-----+-----+-----------------------+ + | assigned broker bank | + +-----------------------+ + | assigned objId bank | + +-----------------------+ +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-ConsoleAddedIndication"><title> + Console Added + Indication + </title> + + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'x' | seq | + +-----+-----+-----+-----+-----------------------+ +</programlisting> + + + + <!--h4--></section> + <!--h3--></section> + <!--h2--></section> + + +</section> + diff --git a/qpid/doc/book/src/old/NET-User-Guide.xml b/qpid/doc/book/src/old/NET-User-Guide.xml new file mode 100644 index 0000000000..7bfa20b8c8 --- /dev/null +++ b/qpid/doc/book/src/old/NET-User-Guide.xml @@ -0,0 +1,1383 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section> + <title> + Apache Qpid: Open Source AMQP Messaging - .NET User Guide + </title> + <section role="h1" id="NETUserGuide-Tutorial"> + <title> + Tutorial + </title> + <para> + This tutorial consists of a series of examples using the three + most commonly used exchange types - Direct, Fanout and + Topic + exchanges. These examples show how to write applications that use + the most common messaging paradigms. + </para> + <itemizedlist> + <listitem> + <para>direct</para> + <para>In the direct examples, a message producer writes to the direct + exchange, specifying a routing key. A message consumer reads + messages from a named queue. This illustrates clean separation + of concerns - message producers need to know only the exchange + and the routing key, message consumers need to know only which + queue to use on the broker. + </para> + </listitem> + <listitem> + <para>fanout</para> + <para>The fanout examples use a fanout exchange and do not use + routing keys. Each binding specifies that all messages for a + given exchange should be delivered to a given queue. + </para> + </listitem> + <listitem> + <para>pub-sub</para> + <para>In the publish/subscribe examples, a publisher + application writes messages to an exchange, specifying a + multi-part key. A subscriber application subscribes to + messages that match the relevant parts of these keys, using a + private queue for each subscription. + </para> + </listitem> + <listitem> + <para>request-response</para> + <para>In the request/response examples, a simple service accepts + requests from clients and sends responses back to them. Clients + create their own private queues and corresponding routing keys. + When a client sends a request to the server, it specifies its + own routing key in the reply-to field of the request. The + server uses the client's reply-to field as the routing key for + the response. + </para> + </listitem> + </itemizedlist> + <section role="h2" id="NETUserGuide-RunningtheExamples"> + <title> + Running the + Examples + </title> + <para> + Before running the examples, you need to unzip the file + Qpid.NET-net-2.0-M4.zip, the following tree is created: + </para> + + + <programlisting> +<home> + |-qpid + |-lib (contains the required dlls) + |-examples + |- direct + | |-example-direct-Listener.exe + | |-example-direct-Producer.exe + |- fanout + | |-example-fanout-Listener.exe + | |-example-fanout-Producer.exe + |- pub-sub + | |-example-pub-sub-Listener.exe + | |-example-pub-sub-Publisher.exe + |- request-response + |-example-request-response-Client.exe + |-example-request-response-Server.exe + </programlisting> + + + <para> + Make sure your PATH contains the directory + <home>/qpid/lib + The examples can be run by executing the provided exe files: + </para> + + + <programlisting> +$ cd <home>/qpid/examples/examplefolder +$ example-...-.exe [hostname] [portnumber] + </programlisting> + + + <para> + where [hostname] is the qpid broker host name + (default is localhost) and [portnumber] is the port number on which the + qpid broker is accepting connection (default is 5672). + </para> + <!--h2--> + </section> + + <section role="h2" id="NETUserGuide-CreatingandClosingSessions"> + <title> + Creating + and Closing Sessions + </title> + + <para> + All of the examples have been written using the Apache Qpid .NEt + 0.10 API. The examples use the same skeleton code to initialize + the program, create a session, and clean up before exiting: + </para> + + + <programlisting> +using System; +using System.IO; +using System.Text; +using System.Threading; +using org.apache.qpid.client; +using org.apache.qpid.transport; + +... + + private static void Main(string[] args) + { + string host = args.Length > 0 ? args[0] : "localhost"; + int port = args.Length > 1 ? Convert.ToInt32(args[1]) : 5672; + Client connection = new Client(); + try + { + connection.connect(host, port, "test", "guest", "guest"); + ClientSession session = connection.createSession(50000); + + //--------- Main body of program -------------------------------------------- + + connection.close(); + } + catch (Exception e) + { + Console.WriteLine("Error: \n" + e.StackTrace); + } + } +... + </programlisting> + <!--h2--> + </section> + + <section role="h2" id="NETUserGuide-WritingDirectApplications"> + <title> + Writing + Direct Applications + </title> + + <para> + This section describes two programs that implement direct + messaging using a Direct exchange: + • org.apache.qpid.example.direct.Producer (from + example-direct-producer) publishes messages to the amq.direct + exchange, using the routing key routing_key. + •org.apache.qpid.example.direct.Listener (from + example-direct-Listener) uses a message listener to receive + messages from the queue named message_queue. + </para> + <section role="h3" id="NETUserGuide-RunningtheDirectExamples"> + <title> + Running the + Direct Examples + </title> + <para> + 1) Make sure your PATH contains the directory + <home>/qpid/lib + </para> + <para> + 2) Make sure that a qpid broker is running: + </para> + + + <programlisting> +$ ps -eaf | grep qpidd + </programlisting> + + + <para> + If a broker is running, you should see the qpidd process in the + output of the above + command. + </para> + <para> + 3) Read the messages from the message queue using direct + listener, as follows: + </para> + + + <programlisting> +$ cd <home>/qpid/examples/direct + </programlisting> + + + <para> + With cygwin: + </para> + + + <programlisting> +$ ./example-direct-Listener.exe [hostname] [portnumber] + </programlisting> + + + <para> + or with mono: + </para> + + + <programlisting> +$ mono ./example-direct-Listener.exe [hostname] [portnumber] + </programlisting> + + + <para> + This program is waiting for messages to be published, see next + step: + </para> + <para> + 4) Publish a series of messages to the amq.direct exchange by + running direct producer, as follows: + </para> + + + <programlisting> +$ cd <home>/qpid/examples/direct + </programlisting> + + + <para> + With cygwin: + </para> + + + <programlisting> +$ ./example-direct-Producer.exe [hostname] [portnumber] + </programlisting> + + + <para> + or with mono: + </para> + + + <programlisting> +$ mono ./example-direct-Producer.exe [hostname] [portnumber] + </programlisting> + + + <para> + This program has no output; the messages are routed to the + message queue, as instructed by the binding. + </para> + <para> + 5) Go to the windows where you are running your listener. You + should see the following output: + </para> + + + <programlisting> +Message: Message 0 +Message: Message 1 +Message: Message 2 +Message: Message 3 +Message: Message 4 +Message: Message 5 +Message: Message 6 +Message: Message 7 +Message: Message 8 +Message: Message 9 +Message: That's all, folks! + </programlisting> + + + <para> + Now we will examine the code for each of these programs. In each + section, we will discuss only + the code that must be added to the skeleton shown in Section + "Creating and Closing Sessions". + </para> + <!--h3--> + </section> + + <section role="h3" id="NETUserGuide-ReadingMessagesfromtheQueue"> + <title> + Reading + Messages from the Queue + </title> + + <para> + The program , listener.cs, is a message listener that receives + messages from a queue. + </para> + <para> + First it creates a queue named message_queue, then binds it to + the amq.direct exchange using the binding key routing_key. + </para> + + + <programlisting> +//--------- Main body of program -------------------------------------------- +// Create a queue named "message_queue", and route all messages whose +// routing key is "routing_key" to this newly created queue. +session.queueDeclare("message_queue"); +session.exchangeBind("message_queue", "amq.direct", "routing_key"); + </programlisting> + + + <para> + The queue created by this program continues to exist after the + program exits, and any message whose routing key matches the key + specified in the binding will be routed to the corresponding + queue by the broker. Note that the queue could have been be + deleted using the following code: + </para> + + + <programlisting> +session.queueDelete("message_queue"); + </programlisting> + + + <para> + To create a message listener, create a class derived from + IMessageListener, and override the messageTransfer method, + providing the code that should be executed when a message is + received. + </para> + + + <programlisting> +public class MessageListener : IMessageListener +{ + ...... + public void messageTransfer(IMessage m) + { + ..... +} + </programlisting> + + + <para> + The main body of the program creates a listener for the + subscription; attaches the listener to a message queue; and + subscribe to the queue to receive messages from the queue. + </para> + + + <programlisting> +lock (session) +{ + // Create a listener and subscribe it to the queue named "message_queue" + IMessageListener listener = new MessageListener(session); + session.attachMessageListener(listener, "message_queue"); + session.messageSubscribe("message_queue"); + // Receive messages until all messages are received + Monitor.Wait(session); +} + </programlisting> + + + <para> + The MessageListener's messageTransfer() function is called + whenever a message is received. In this example the message is + printed and tested to see if it is the final message. Once the + final message is received, the messages are acknowledged. + </para> + + + <programlisting> +BinaryReader reader = new BinaryReader(m.Body, Encoding.UTF8); +byte[] body = new byte[m.Body.Length - m.Body.Position]; +reader.Read(body, 0, body.Length); +ASCIIEncoding enc = new ASCIIEncoding(); +string message = enc.GetString(body); + Console.WriteLine("Message: " + message); +// Add this message to the list of message to be acknowledged +_range.add(m.Id); +if( message.Equals("That's all, folks!") ) +{ + // Acknowledge all the received messages + _session.messageAccept(_range); + lock(_session) + { + Monitor.Pulse(_session); + } +} + </programlisting> + <!--h3--> + </section> + + <section role="h3" id="NETUserGuide-PublishingMessagestoaDirectExchange"> + <title> + Publishing + Messages to a Direct Exchange + </title> + <para> + The second program in the direct example, Producer.cs, publishes + messages to the amq.direct exchange using the routing key + routing_key. + </para> + <para> + First, create a message and set a routing key. The same routing + key will be used for each message we send, so you only need to + set this property once. + </para> + + + <programlisting> +IMessage message = new Message(); +// The routing key is a message property. We will use the same +// routing key for each message, so we'll set this property +// just once. (In most simple cases, there is no need to set +// other message properties.) +message.DeliveryProperties.setRoutingKey("routing_key"); + </programlisting> + + + <para> + Now send some messages: + </para> + + + <programlisting> +// Asynchronous transfer sends messages as quickly as +// possible without waiting for confirmation. +for (int i = 0; i < 10; i++) +{ + message.clearData(); + message.appendData(Encoding.UTF8.GetBytes("Message " + i)); + session.messageTransfer("amq.direct", message); +} + </programlisting> + + + <para> + Send a final synchronous message to indicate termination: + </para> + + + <programlisting> +// And send a syncrhonous final message to indicate termination. +message.clearData(); +message.appendData(Encoding.UTF8.GetBytes("That's all, folks!")); +session.messageTransfer("amq.direct", "routing_key", message); +session.sync(); + </programlisting> + <!--h3--> + </section> + + <!--h2--> + </section> + + + <section role="h2" id="NETUserGuide-WritingFanoutApplications"> + <title> + Writing + Fanout Applications + </title> + + <para> + This section describes two programs that illustrate the use of a + Fanout exchange. + </para> + <itemizedlist> + <listitem> + <para>Listener.cs makes a unique queue private for each instance of + the listener, and binds that queue to the fanout exchange. All + messages sent to the fanout exchange are delivered to each + listener's queue. + </para> + </listitem> + <listitem> + <para>Producer.cs publishes messages to the fanout exchange. It + does not use a routing key, which is not needed by the fanout + exchange. + </para> + </listitem> + </itemizedlist> + <section role="h3" id="NETUserGuide-RunningtheFanoutExamples"> + <title> + Running the + Fanout Examples + </title> + + <para> + 1) Make sure your PATH contains the directory + <home>/qpid/lib + </para> + <para> + 2) Make sure that a qpid broker is running: + </para> + + + <programlisting> +$ ps -eaf | grep qpidd + </programlisting> + + + <para> + If a broker is running, you should see the qpidd process in the + output of the above + command. + </para> + <para> + 3) In separate windows, start one or more fanout listeners as + follows: + </para> + + + <programlisting> +$ cd <home>/qpid/examples/direct + </programlisting> + + + <para> + With cygwin: + </para> + + + <programlisting> +$ ./example-fanout-Listener.exe [hostname] [portnumber] + </programlisting> + + + <para> + or with mono: + </para> + + + <programlisting> +$ mono ./example-fanout-Listener.exe [hostname] [portnumber] + </programlisting> + + + <para> + The listener creates a private queue, binds it to the amq.fanout + exchange, and waits for messages to arrive on the queue. When the + listener starts, you will see the following message: + </para> + + + <programlisting> +Listening + </programlisting> + + + <para> + This program is waiting for messages to be published, see next + step: + </para> + <para> + 4) In a separate window, publish a series of messages to the + amq.fanout exchange by running fanout producer, as follows: + </para> + + + <programlisting> +$ cd <home>/qpid/examples/direct + </programlisting> + + + <para> + With cygwin: + </para> + + + <programlisting> +$ ./example-fanout-Producer.exe [hostname] [portnumber] + </programlisting> + + + <para> + or with mono: + </para> + + + <programlisting> +$ mono ./example-fanout-Producer.exe [hostname] [portnumber] + </programlisting> + + + <para> + This program has no output; the messages are routed to the + message queue, as prescribed by the binding. + </para> + <para> + 5) Go to the windows where you are running listeners. You should + see the following output for each listener: + </para> + + + <programlisting> +Message: Message 0 +Message: Message 1 +Message: Message 2 +Message: Message 3 +Message: Message 4 +Message: Message 5 +Message: Message 6 +Message: Message 7 +Message: Message 8 +Message: Message 9 +Message: That's all, folks! + </programlisting> + + + <para> + Now we will examine the code for each of these programs. In each + section, we will discuss only + the code that must be added to the skeleton shown in Section + "Creating and Closing Sessions". + </para> + + <!--h3--> + </section> + + <!--h2--> + </section> + + <section role="h2" id="NETUserGuide-ConsumingfromaFanoutExchange"> + <title> + Consuming from a + Fanout Exchange + </title> + + <para> + The first program in the fanout example, Listener.cs, creates a + private queue, binds it to the amq.fanout exchange, and waits for + messages to arrive on the queue, printing them out as they + arrive. It uses a Listener that is identical to the one used in + the direct example: + </para> + + + <programlisting> + public class MessageListener : IMessageListener + { + private readonly ClientSession _session; + private readonly RangeSet _range = new RangeSet(); + public MessageListener(ClientSession session) + { + _session = session; + } + + public void messageTransfer(IMessage m) + { + BinaryReader reader = new BinaryReader(m.Body, Encoding.UTF8); + byte[] body = new byte[m.Body.Length - m.Body.Position]; + reader.Read(body, 0, body.Length); + ASCIIEncoding enc = new ASCIIEncoding(); + string message = enc.GetString(body); + Console.WriteLine("Message: " + message); + // Add this message to the list of message to be acknowledged + _range.add(m.Id); + if (message.Equals("That's all, folks!")) + { + // Acknowledge all the received messages + _session.messageAccept(_range); + lock (_session) + { + Monitor.Pulse(_session); + } + } + } + } + </programlisting> + + + <para> + The listener creates a private queue to receive its messages and + binds it to the fanout exchange: + </para> + + + <programlisting> +string myQueue = session.Name; +session.queueDeclare(myQueue, Option.EXCLUSIVE, Option.AUTO_DELETE); +session.exchangeBind(myQueue, "amq.fanout", "my-key"); + </programlisting> + + + <para> + Now we create a listener and subscribe it to the queue: + </para> + + + <programlisting> +lock (session) +{ + Console.WriteLine("Listening"); + // Create a listener and subscribe it to my queue. + IMessageListener listener = new MessageListener(session); + session.attachMessageListener(listener, myQueue); + session.messageSubscribe(myQueue); + // Receive messages until all messages are received + Monitor.Wait(session); +} + </programlisting> + + + <section role="h3" id="NETUserGuide-PublishingMessagestotheFanoutExchange"> + <title> + Publishing + Messages to the Fanout Exchange + </title> + + <para> + The second program in this example, Producer.cs, writes messages + to the fanout queue. + </para> + + + <programlisting> +// Unlike topic exchanges and direct exchanges, a fanout +// exchange need not set a routing key. +IMessage message = new Message(); +// Asynchronous transfer sends messages as quickly as +// possible without waiting for confirmation. +for (int i = 0; i < 10; i++) +{ + message.clearData(); + message.appendData(Encoding.UTF8.GetBytes("Message " + i)); + session.messageTransfer("amq.fanout", message); +} + +// And send a syncrhonous final message to indicate termination. +message.clearData(); +message.appendData(Encoding.UTF8.GetBytes("That's all, folks!")); +session.messageTransfer("amq.fanout", message); +session.sync(); + </programlisting> + + <!--h3--> + </section> + + <!--h2--> + </section> + + <section role="h2" id="NETUserGuide-WritingPublish-2FSubscribeApplications"> + <title> + Writing + Publish/Subscribe Applications + </title> + + <para> + This section describes two programs that implement + Publish/Subscribe messaging using a topic exchange. + </para> + <para> + • Publisher.cS sends messages to the amq.topic exchange, + using the multipart routing keys usa.news, usa.weather, + europe.news, and europe.weather. + • Listener.cs creates private queues for news, weather, + usa, and europe, binding them to the amq.topic exchange using + bindings that match the corresponding parts of the multipart + routing keys. + </para> + <para> + In this example, the publisher creates messages for topics like + news, weather, and sports that happen in regions like Europe, + Asia, or the United States. A given consumer may be interested in + all weather messages, regardless of region, or it may be + interested in news and weather for the United States, but + uninterested in items for other regions. In this example, each + consumer sets up its own private queues, which receive precisely + the messages that particular consumer is interested in. + </para> + <section role="h3" id="NETUserGuide-RunningthePublishSubscribeExamples"> + <title> + Running + the Publish-Subscribe Examples + </title> + <para> + 1) Make sure your PATH contains the directory + <home>/qpid/lib + </para> + <para> + 2) Make sure that a qpid broker is running: + </para> + + + <programlisting> +$ ps -eaf | grep qpidd + </programlisting> + + + <para> + If a broker is running, you should see the qpidd process in the + output of the above + command. + </para> + <para> + 3) In separate windows, start one or more topic subscribers as + follows: + </para> + + + <programlisting> +$ cd <home>/qpid/examples/direct + </programlisting> + + + <para> + With cygwin: + </para> + + + <programlisting> +$ ./example-pub-sub--Listener.exe [hostname] [portnumber] + </programlisting> + + + <para> + or with mono: + </para> + + + <programlisting> +$ mono ./example-pub-sub-Listener.exe [hostname] [portnumber] + </programlisting> + + + <para> + You will see output similar to this: + </para> + + + <programlisting> +Listening for messages ... +Declaring queue: usa +Declaring queue: europe +Declaring queue: news +Declaring queue: weather + </programlisting> + + + <para> + Each topic consumer creates a set of private queues, and binds + each queue to the amq.topic exchange together with a binding that + indicates which messages should be routed to the queue. + </para> + <para> + 4) In another window, start the topic publisher, which publishes + messages to the amq.topic exchange, as follows: + </para> + + + <programlisting> +$ cd <home>/qpid/examples/direct + </programlisting> + + + <para> + With cygwin: + </para> + + + <programlisting> +$ ./example-pub-sub-Producer.exe [hostname] [portnumber] + </programlisting> + + + <para> + or with mono: + </para> + + + <programlisting> +$ mono ./example-pub-sub-Producer.exe [hostname] [portnumber] + </programlisting> + + + <para> + This program has no output; the messages are routed to the + message queues for each topic_consumer as specified by the + bindings the consumer created. + </para> + <para> + 5) Go back to the window for each topic consumer. You should see + output like this: + </para> + + + <programlisting> +Message: Message 0 from usa +Message: Message 0 from news +Message: Message 0 from weather +Message: Message 1 from usa +Message: Message 1 from news +Message: Message 2 from usa +Message: Message 2 from news +Message: Message 3 from usa +Message: Message 3 from news +Message: Message 4 from usa +Message: Message 4 from news +Message: Message 5 from usa +Message: Message 5 from news +Message: Message 6 from usa +Message: Message 6 from news +Message: Message 7 from usa +Message: Message 7 from news +Message: Message 8 from usa +Message: Message 8 from news +Message: Message 9 from usa +.... +Message: That's all, folks! from weather +Shutting down listener for control +Message: That's all, folks! from europe +Shutting down listener for control + </programlisting> + + + <para> + Now we will examine the code for each of these programs. In each + section, we will discuss only + the code that must be added to the skeleton shown in Section + "Creating and Closing Sessions". + </para> + <!--h3--> + </section> + + + <section role="h3" id="NETUserGuide-PublishingMessagestoaTopicExchange"> + <title> + Publishing + Messages to a Topic Exchange + </title> + + <para> + The first program in the publish/subscribe example, Publisher.cs, + defines two new functions: one that publishes messages to the + topic exchange, and one that indicates that no more messages are + coming. + </para> + <para> + The publishMessages function publishes a series of five messages + using the specified routing key. + </para> + + + <programlisting> +private static void publishMessages(ClientSession session, string routing_key) +{ + IMessage message = new Message(); + // Asynchronous transfer sends messages as quickly as + // possible without waiting for confirmation. + for (int i = 0; i < 10; i++) + { + message.clearData(); + message.appendData(Encoding.UTF8.GetBytes("Message " + i)); + session.messageTransfer("amq.topic", routing_key, message); + } +} + </programlisting> + + + <para> + The noMoreMessages function signals the end of messages using the + control routing key, which is reserved for control messages. + </para> + + + <programlisting> +private static void noMoreMessages(ClientSession session) +{ + IMessage message = new Message(); + // And send a syncrhonous final message to indicate termination. + message.clearData(); + message.appendData(Encoding.UTF8.GetBytes("That's all, folks!")); + session.messageTransfer("amq.topic", "control", message); + session.sync(); +} + </programlisting> + + + <para> + In the main body of the program, messages are published using + four different routing keys, and then the end of messages is + indicated by a message sent to a separate routing key. + </para> + + + <programlisting> +publishMessages(session, "usa.news"); +publishMessages(session, "usa.weather"); +publishMessages(session, "europe.news"); +publishMessages(session, "europe.weather"); + +noMoreMessages(session); + </programlisting> + <!--h3--> + </section> + + <section role="h3" id="NETUserGuide-ReadingMessagesfromtheQueue2"> + <title> + Reading + Messages from the Queue + </title> + + <para> + The second program in the publish/subscribe example, Listener.cs, + creates a local private queue, with a unique name, for each of + the four binding keys it specifies: usa.#, europe.#, #.news, and + #.weather, and creates a listener. + </para> + + + <programlisting> +Console.WriteLine("Listening for messages ..."); +// Create a listener +prepareQueue("usa", "usa.#", session); +prepareQueue("europe", "europe.#", session); +prepareQueue("news", "#.news", session); +prepareQueue("weather", "#.weather", session); + </programlisting> + + + <para> + The prepareQueue() method creates a queue using a queue name and + a routing key supplied as arguments it then attaches a listener + with the session for the created queue and subscribe for this + receiving messages from the queue: + </para> + + + <programlisting> +// Create a unique queue name for this consumer by concatenating +// the queue name parameter with the Session ID. +Console.WriteLine("Declaring queue: " + queue); +session.queueDeclare(queue, Option.EXCLUSIVE, Option.AUTO_DELETE); + +// Route messages to the new queue if they match the routing key. +// Also route any messages to with the "control" routing key to +// this queue so we know when it's time to stop. A publisher sends +// a message with the content "That's all, Folks!", using the +// "control" routing key, when it is finished. + +session.exchangeBind(queue, "amq.topic", routing_key); +session.exchangeBind(queue, "amq.topic", "control"); + +// subscribe the listener to the queue +IMessageListener listener = new MessageListener(session); +session.attachMessageListener(listener, queue); +session.messageSubscribe(queue); + </programlisting> + <!--h3--> + </section> + <!--h2--> + </section> + + <section role="h2" id="NETUserGuide-WritingRequest-2FResponseApplications"> + <title> + Writing + Request/Response Applications + </title> + + <para> + In the request/response examples, we write a server that accepts + strings from clients and converts them to upper case, sending the + result back to the requesting client. This example consists of + two programs. + </para> + <itemizedlist> + <listitem> + <para>Client.cs is a client application that sends messages to the + server. + • Server.cs is a service that accepts messages, converts + their content to upper case, and sends the result to the + amq.direct exchange, using the request's reply-to property as + the routing key for the response. + </para> + </listitem> + </itemizedlist> + <section role="h3" id="NETUserGuide-RunningtheRequest-2FResponseExamples"> + <title> + Running + the Request/Response Examples + </title> + <para> + 1) Make sure your PATH contains the directory + <home>/qpid/lib + </para> + <para> + 2) Make sure that a qpid broker is running: + </para> + + + <programlisting> +$ ps -eaf | grep qpidd + </programlisting> + + + <para> + If a broker is running, you should see the qpidd process in the + output of the above + command. + </para> + <para> + 3) Run the server. + </para> + <para> + $ cd <home>/qpid/examples/direct + </para> + + + <programlisting> + With cygwin: + </programlisting> + + + <para> + $ ./example-request-response-Server.exe [hostname] [portnumber] + </para> + + + <programlisting> + or with mono: + </programlisting> + + + <para> + $ mono ./example-request-response-Server.exe [hostname] [portnumber] + </para> + + + <programlisting> + You will see output similar to this: + </programlisting> + + + <para> + Waiting for requests + </para> + + + <programlisting> +4) In a separate window, start a client: + +$ cd <home>/qpid/examples/direct + </programlisting> + + + <para> + With cygwin: + </para> + + + <programlisting> +$ ./example-request-response-Client.exe [hostname] [portnumber] + </programlisting> + + + <para> + or with mono: + </para> + + + <programlisting> +$ mono ./example-request-response-Client.exe [hostname] [portnumber] + </programlisting> + + + <para> + You will see output similar to this: + </para> + + + <programlisting> +Activating response queue listener for: clientSystem.Byte[] +Waiting for all responses to arrive ... +Response: TWAS BRILLIG, AND THE SLITHY TOVES +Response: DID GIRE AND GYMBLE IN THE WABE. +Response: ALL MIMSY WERE THE BOROGROVES, +Response: AND THE MOME RATHS OUTGRABE. +Shutting down listener for clientSystem.Byte[] +Response: THAT'S ALL, FOLKS! + </programlisting> + + + <para> + 4) Go back to the server window, the output should be similar to + this: + </para> + + + <programlisting> +Waiting for requests +Request: Twas brillig, and the slithy toves +Request: Did gire and gymble in the wabe. +Request: All mimsy were the borogroves, +Request: And the mome raths outgrabe. +Request: That's all, folks! + </programlisting> + + + <para> + Now we will examine the code for each of these programs. In each + section, we will discuss only the code that must be added to the + skeleton shown in Section "Creating and Closing Sessions". + </para> + <!--h3--> + </section> + + + <section role="h3" id="NETUserGuide-TheClientApplication"> + <title> + The Client + Application + </title> + + <para> + The first program in the request-response example, Client.cs, + sets up a private response queue to receive responses from the + server, then sends messages the server, listening to the response + queue for the server's responses. + </para> + + + <programlisting> +string response_queue = "client" + session.getName(); +// Use the name of the response queue as the routing key +session.queueDeclare(response_queue); +session.exchangeBind(response_queue, "amq.direct", response_queue); + +// Create a listener for the response queue and listen for response messages. +Console.WriteLine("Activating response queue listener for: " + response_queue); +IMessageListener listener = new ClientMessageListener(session); +session.attachMessageListener(listener, response_queue); +session.messageSubscribe(response_queue); + </programlisting> + + + <para> + Set some properties that will be used for all requests. The + routing key for a request is request. + The reply-to property is set to the routing key for the client's + private queue. + </para> + + + <programlisting> +IMessage request = new Message(); +request.DeliveryProperties.setRoutingKey("request"); +request.MessageProperties.setReplyTo(new ReplyTo("amq.direct", response_queue)); + </programlisting> + + + <para> + Now send some requests... + </para> + + + <programlisting> +string[] strs = { + "Twas brillig, and the slithy toves", + "Did gire and gymble in the wabe.", + "All mimsy were the borogroves,", + "And the mome raths outgrabe.", + "That's all, folks!" + }; +foreach (string s in strs) +{ + request.clearData(); + request.appendData(Encoding.UTF8.GetBytes(s)); + session.messageTransfer("amq.direct", request); +} + </programlisting> + + + <para> + And wait for responses to arrive: + </para> + + + <programlisting> +Console.WriteLine("Waiting for all responses to arrive ..."); +Monitor.Wait(session); + </programlisting> + <!--h3--> + </section> + + <section role="h3" id="NETUserGuide-TheServerApplication"> + <title> + The Server + Application + </title> + + <para> + The second program in the request-response example, Server.cs, + uses the reply-to property as the routing key for responses. + </para> + <para> + The main body of Server.cs creates an exclusive queue for + requests, then waits for messages to arrive. + </para> + + + <programlisting> +const string request_queue = "request"; +// Use the name of the request queue as the routing key +session.queueDeclare(request_queue); +session.exchangeBind(request_queue, "amq.direct", request_queue); + +lock (session) +{ + // Create a listener and subscribe it to the request_queue + IMessageListener listener = new MessageListener(session); + session.attachMessageListener(listener, request_queue); + session.messageSubscribe(request_queue); + // Receive messages until all messages are received + Console.WriteLine("Waiting for requests"); + Monitor.Wait(session); +} + </programlisting> + + + <para> + The listener's messageTransfer() method converts the request's + content to upper case, then sends a response to the broker, using + the request's reply-to property as the routing key for the + response. + </para> + + + <programlisting> +BinaryReader reader = new BinaryReader(request.Body, Encoding.UTF8); +byte[] body = new byte[request.Body.Length - request.Body.Position]; +reader.Read(body, 0, body.Length); +ASCIIEncoding enc = new ASCIIEncoding(); +string message = enc.GetString(body); +Console.WriteLine("Request: " + message); + +// Transform message content to upper case +string responseBody = message.ToUpper(); + +// Send it back to the user +response.clearData(); +response.appendData(Encoding.UTF8.GetBytes(responseBody)); +_session.messageTransfer("amq.direct", routingKey, response); + </programlisting> + + <!--h3--> + </section> + <!--h2--> + </section> + <!--h1--> + </section> + + + </section> diff --git a/qpid/doc/book/src/old/PythonBrokerTest.xml b/qpid/doc/book/src/old/PythonBrokerTest.xml new file mode 100644 index 0000000000..ae7edade40 --- /dev/null +++ b/qpid/doc/book/src/old/PythonBrokerTest.xml @@ -0,0 +1,98 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section> + <title> + PythonBrokerTest + </title> + <section role="h2" id="PythonBrokerTest-PythonBrokerSystemTestSuite"> + <title> + Python Broker System Test Suite + </title> + <para> + This is a suite of python client tests that exercise and verify + broker functionality. Python allows us to rapidly develop client + test scenarios and provides a 'neutral' set of tests that can run + against any AMQP-compliant broker. + </para> + <para> + The python/tests directory contains a collection of python + modules, each containing several unittest classes, each + containing a set of test methods that represent some test + scenario. Test classes inherit qpid.TestBas from + qpid/testlib.py, it inherits unittest.TestCase + but adds some qpid-specific setUp/tearDown and + convenience functions. + </para> + <para> + TODO: get pydoc generated up to qpid wiki or website + automatically? + </para> + <section role="h3" id="PythonBrokerTest-Runningthetests"> + <title> + Running the tests + </title> + <para> + Simplest way to run the tests: + </para> + <itemizedlist> + <listitem> + <para>Run a broker on the default port + </para> + </listitem> + <listitem> + <para> + ./run_tests + </para> + </listitem> + </itemizedlist> + <para> + For additional options: ./run_tests --help + </para> + <!--h3--> + </section> + + <section role="h3" id="PythonBrokerTest-Expectedfailures"> + <title> + Expected failures + </title> + <para> + Until we complete functionality, tests may fail because the + tested functionality is missing in the broker. To skip + expected failures in the C++ or Java brokers: + </para> + <programlisting> +./run_tests -I cpp_failing.txt +./run_tests -I java_failing.txt + </programlisting> + <para> + If you fix a failure, please remove it from the corresponding + list. + </para> + + <!--h3--> + </section> + + <!--h2--> + </section> + +</section> diff --git a/qpid/doc/book/src/old/QMan-Qpid-Management-bridge.xml b/qpid/doc/book/src/old/QMan-Qpid-Management-bridge.xml new file mode 100644 index 0000000000..f2c366dcbb --- /dev/null +++ b/qpid/doc/book/src/old/QMan-Qpid-Management-bridge.xml @@ -0,0 +1,166 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section><title> + QMan - Qpid Management bridge + </title><section role="h1" id="QMan-QpidManagementbridge-QMan-3AQpidManagementBridge"><title> + QMan + : Qpid Management Bridge + </title> + <para> + QMan is a management bridge for Qpid. It allows external clients + to manage and monitor one or more Qpid brokers. + </para> + <para> + Please note: All WS-DM related concerns have to be considered + part of M5 release. + </para><para> + QMan exposes the broker management interfaces using Java + Management Extensions (JMX) and / or OASIS Web Services + Distributed Management (WSDM). While the first one is supposed to + be used by java based clients only the latter is an interoperable + protocol that enables management clients to access and receive + notifications of management-enabled resources using Web Services. + </para><para> + QMan can be easily integrated in your preexisting system in + different ways : + </para><itemizedlist> + <listitem><para>As a standalone application : in this case it runs as a + server. More specifically it enables communication via RMI (for + JMX) or via HTTP (for WS-DM); Note that when the WS-DM adapter is + used the JMX interface is not exposed; + </para></listitem> + <listitem><para>As a deployable unit : it is also available as a standard + Java web application (war); This is useful when there's a + preexisting Application Server in your environment and you don't + want start another additional server in order to run QMan. + </para></listitem> + </itemizedlist> + + <section role="h2" id="QMan-QpidManagementbridge-UserDocumentation"><title> + User + Documentation + </title> + <para> + With "User Documentation" we mean all information that you need + to know in order to use QMan from a user perspective. Those + information include : + </para><table><title/><tgroup cols="2"> + <tbody> + <row> + <entry> + Section + </entry> + <entry> + Description + </entry> + </row> + <row> + <entry> + <xref linkend="qpid_Get-me-up-and-running"/> + </entry> + <entry> + How to install & start QMan. + </entry> + </row> + <row> + <entry> + <xref linkend="qpid_QMan-User-Guide"/> + </entry> + <entry> + QMan (WS-DM version only) Administration Console. + </entry> + </row> + <row> + <entry> + <xref linkend="qpid_JMX-Interface-Specification"/> + </entry> + <entry> + Describes each JMX interface exposed by QMan. + </entry> + </row> + <row> + <entry> + <xref linkend="qpid_WS-DM-Interface-Specification"/> + </entry> + <entry> + Describes each WS-DM interface exposed by QMan. + </entry> + </row> + <row> + <entry> + <xref linkend="qpid_QMan-Messages-Catalogue"/> + </entry> + <entry> + Informational / Debug / Error / Warning messages catalogue. + </entry> + </row> + </tbody> + </tgroup></table> + <!--h2--></section> + + + <section role="h2" id="QMan-QpidManagementbridge-TechnicalDocumentation"><title> + Technical + Documentation + </title> + <para> + If you are interested in technical details about QMan and related + technologies this is a good starting point. In general this + section provides information about QMan design, interfaces, + patterns and so on... + </para> + + <table><title/><tgroup cols="2"> + <tbody> + <row> + <entry> + Section + </entry> + <entry> + Description + </entry> + </row> + <row> + <entry> + <xref linkend="qpid_QMan-System-Overview"/> + </entry> + <entry> + A short introduction about QMan deployment context. + </entry> + </row> + <row> + <entry> + <xref linkend="qpid_QMan-Components-View"/> + </entry> + <entry> + Describes QMan components, their interactions and + responsibilities. + </entry> + </row> + </tbody> + </tgroup></table> + +<!--h2--></section> +<!--h1--></section> + +</section> diff --git a/qpid/doc/book/src/old/Qpid-ACLs.xml b/qpid/doc/book/src/old/Qpid-ACLs.xml new file mode 100644 index 0000000000..a2b64061c3 --- /dev/null +++ b/qpid/doc/book/src/old/Qpid-ACLs.xml @@ -0,0 +1,49 @@ +<?xml version="1.0"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section> + <title>Qpid ACL Formats</title> + <para> + The Qpid project has two ACL implementations currently. The java broker + has a simple XML configuration mechanism icluded as part of the main + broker configuration. The C++ broker and the latest versions of the Java + broker also have a new, text based ACL file format. + </para> + <bridgehead id="QpidACLs-Specifications"><anchor id="QpidACLs-Specifications" />Specifications</bridgehead> + <para> + The specifications for each of the ACL formats are linked here: + </para> + <para> + <xref linkend="JavaXMLACLs-specification" /> + <xref linkend="ACL-specification" /> + </para> + <bridgehead id="QpidACLs-UserGuides"><anchor id="QpidACLs-UserGuides" />User Guides</bridgehead> + <para> + To aid users in defining their ACLs we have a user guide for each + of the ACL formats and a page describing the security plugin mechanism in the Java broker. + </para> + <para> + <xref linkend="JavaXMLACLs-userguide" /> + <xref linkend="ACL-userguide" /> + <xref linkend="Security-Plugins-Documentation" /> + </para> +</section> diff --git a/qpid/doc/book/src/old/Qpid-Book.xml b/qpid/doc/book/src/old/Qpid-Book.xml new file mode 100644 index 0000000000..ee69532152 --- /dev/null +++ b/qpid/doc/book/src/old/Qpid-Book.xml @@ -0,0 +1,93 @@ +<?xml version='1.0' encoding='utf-8' ?> + +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<book> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Book-Info.xml"/> + <part> + <title>Basics</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Introduction.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Getting-Started.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Download.xml"/> + </part> + +<!-- + The broker sections define their own <part/> elements, with <partintro/> text. +--> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Messaging-Broker-CPP.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Messaging-Broker-Java.xml"/> + + <part> + <title>AMQP Messaging Clients Clients</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Java-JMS-Messaging-Client.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-C++-Messaging-Client.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-.NET-Messaging-Client.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Python-Messaging-Client.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Ruby-Messaging-Client.xml"/> + + </part> + <part> + <title>Appendices</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Compatibility.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Qpid-Interoperability-Documentation.xml"/> +<!-- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="FAQ.xml"/> --> + </part> +</book> + +<!-- +Documentation +Getting Started + + * Download + * Getting Started + +AMQP (Advanced Message Queueing Protocol) + + * Toward a Commodity Enterprise Middleware + * AMQP (Advanced Message Queueing Protocol) + +Qpid AMQP Brokers + + * AMQP Messaging Broker (implemented in C++) + * AMQP Messaging Broker (implemented in Java) + +Qpid AMQP Clients + + * AMQP Java JMS Messaging Client + * AMQP C++ Messaging Client + * AMQP .NET Messaging Client + * AMQP Python Messaging Client + * AMQP Ruby Messaging Client + +Interoperability + + * AMQP Compatibility + * SASL Interoperability + +FAQ + + * Frequently Asked Questions +--> diff --git a/qpid/doc/book/src/old/Qpid-Compatibility-And-Interoperability-Book.xml b/qpid/doc/book/src/old/Qpid-Compatibility-And-Interoperability-Book.xml new file mode 100644 index 0000000000..f382f390c7 --- /dev/null +++ b/qpid/doc/book/src/old/Qpid-Compatibility-And-Interoperability-Book.xml @@ -0,0 +1,36 @@ +<?xml version='1.0' encoding='utf-8' ?> + +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<book> + <chapter> + <title>AMQP Compatibility</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Compatibility.xml"/> + </chapter> + <chapter> + <title>Qpid Interoperability Documentation</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Qpid-Interoperability-Documentation.xml"/> + </chapter> +</book> diff --git a/qpid/doc/book/src/old/SASL-Compatibility.xml b/qpid/doc/book/src/old/SASL-Compatibility.xml new file mode 100644 index 0000000000..ad223792b5 --- /dev/null +++ b/qpid/doc/book/src/old/SASL-Compatibility.xml @@ -0,0 +1,70 @@ +<!-- + - + - Licensed to the Apache Software Foundation (ASF) under one + - or more contributor license agreements. See the NOTICE file + - distributed with this work for additional information + - regarding copyright ownership. The ASF licenses this file + - to you 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. + - + --> +h2. Qpid Interoperability Documentation + +This page documents the various interoperable features of the Qpid clients. + + +h3. SASL +{anchor:sasl} +h4. Standard Mechanisms +[SASL Mechanisms |http://en.wikipedia.org/wiki/Simple_Authentication_and_Security_Layer#SASL_Mechanisms] + +This table list the various SASL mechanisms that each component supports. The version listed shows when this +functionality was added to the product. + +|| Component || ANONYMOUS || CRAM-MD5 || DIGEST-MD5 || EXTERNAL || GSSAPI/Kerberos || PLAIN || +| C++ Broker |M3 |M3 | M3 |0.8\[[#1]\]|M3 | M1 | +| C++ Client |M3 |0.5 | 0.5 |0.8\[[#1]\]| | M1 | +| Java Broker | | M1 | | | | M1 | +| Java Client | | M1 | | M1 | | M1 | +| .Net Client | M2 | M2 | M2 | M2 | | M2 | +| Python Client |0.6\[[#2]\]|0.6\[[#2]\]|0.6\[[#2]\] |0.6\[[#2]\]|0.6\[[#2]\] | M4 | +| Ruby Client |0.6\[[#2]\]|0.6\[[#2]\]|0.6\[[#2]\] |0.6\[[#2]\]|0.6\[[#2]\] | M4 | + +{anchor:1} +1: Only enabled for client authenticated SSL connections. +{anchor:2} +2: On linux only via cyrus-sasl integration. + +h4. Custom Mechanisms + +There have been some custom mechanisms added to our implementations. + +|| Component || AMQPLAIN || CRAM-MD5-HASHED || +| C++ Broker | | | +| C++ Client | | | +| Java Broker | M1 | M2 | +| Java Client | M1 | M2 | +| .Net Client | | | +| Python Client | M2 | | +| Ruby Client | M2 | | + + +h5. AMQPLAIN + +h5. CRAM-MD5-HASHED + +The Java SASL implementations require that you have the password of the user to validate the incoming request. This then means that the user's password must be stored on disk. For this to be secure either the broker must encrypt the password file or the need for the password being stored must be removed. + +The CRAM-MD5-HASHED SASL plugin removes the need for the plain text password to be stored on disk. The mechanism defers all functionality to the build in CRAM-MD5 module the only change is on the client side where it generates the hash of the password and uses that value as the password. This means that the Java Broker only need store the password hash on the file system. While a one way hash is not very secure compared to other forms of encryption in environments where the having the password in plain text is unacceptable this will provide and additional layer to protect the password. In particular this offers some protection where the same password may be shared amongst many systems. It offers no real extra protection against attacks on the broker (the secret is now the hash rather than the password). + + diff --git a/qpid/doc/book/src/old/SSL.xml b/qpid/doc/book/src/old/SSL.xml new file mode 100644 index 0000000000..a9a5cb953a --- /dev/null +++ b/qpid/doc/book/src/old/SSL.xml @@ -0,0 +1,180 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section><title> + SSL + </title> + + <section role="h1" id="SSL-SSLHowto"><title> + SSL How to + </title> + + <section role="h2" id="SSL-C-5Cbroker-28M4andup-29"><title> + C++ broker (M4 and up) + </title> + <itemizedlist> + <listitem><para>You need to get a certificate signed by a CA, trusted by your + client. + </para></listitem> + </itemizedlist><itemizedlist> + <listitem><para>If you require client authentication, the clients certificate + needs to be signed by a CA trusted by the broker. + </para></listitem> + </itemizedlist><itemizedlist> + <listitem><para>Setting up the certificates for testing. + <itemizedlist> + <listitem><para>For testing purposes you could use the <xref linkend="qpid_gtstd"/> to setup your certificates. + </para></listitem> + <listitem><para>In summary you need to create a root CA and import it to + the brokers certificate data base. + </para></listitem> + <listitem><para>Create a certificate for the broker, sign it using the + root CA and then import it into the brokers certificate data + base. + </para></listitem> + </itemizedlist> + </para></listitem> + </itemizedlist><itemizedlist> + <listitem><para>Load the acl module using --load-module or if loading more + than one module, copy ssl.so to the location pointed by + --module-dir + + <programlisting> +Ex if running from source. ./qpidd --load-module /libs/ssl.so +</programlisting> + + </para></listitem> + </itemizedlist><itemizedlist> + <listitem><para>Specify the password file (a plain text file with the + password), certificate database and the brokers certificate name + using the following options + + <programlisting> +Ex ./qpidd ... --ssl-cert-password-file ~/pfile --ssl-cert-db ~/server_db/ --ssl-cert-name localhost.localdomain +</programlisting> + + </para></listitem> + </itemizedlist><itemizedlist> + <listitem><para>If you require client authentication you need to add + --ssl-require-client-authentication as a command line argument. + </para></listitem> + </itemizedlist><itemizedlist> + <listitem><para>Please note that the default port for SSL connections is + 5671, unless specified by --ssl-port + </para></listitem> + </itemizedlist><para> + Here is an example of a broker instance that requires SSL client + side authenticaiton + </para> + <programlisting> +./qpidd ./qpidd --load-module /libs/ssl.so --ssl-cert-password-file ~/pfile --ssl-cert-db ~/server_db/ --ssl-cert-name localhost.localdomain --ssl-require-client-authentication +</programlisting> + <!--h2--></section> + <section role="h2" id="SSL-JavaClient-28M4andup-29"><title> + Java Client (M4 and up) + </title> + <itemizedlist> + <listitem><para>This guide is for connecting with the Qpid c++ broker. + </para></listitem> + </itemizedlist><itemizedlist> + <listitem><para>Setting up the certificates for testing. In summary, + <itemizedlist> + <listitem><para>You need to import the trusted CA in your trust store and + keystore + </para></listitem> + <listitem><para>Generate keys for the certificate in your key store + </para></listitem> + <listitem><para>Create a certificate request using the generated keys + </para></listitem> + <listitem><para>Create a certficate using the request, signed by the + trusted CA. + </para></listitem> + <listitem><para>Import the signed certificate into your keystore. + </para></listitem> + </itemizedlist> + </para></listitem> + </itemizedlist><itemizedlist> + <listitem><para>Pass the following JVM arguments to your client. + + <programlisting> +-Djavax.net.ssl.keyStore=/home/bob/ssl_test/keystore.jks + -Djavax.net.ssl.keyStorePassword=password + -Djavax.net.ssl.trustStore=/home/bob/ssl_test/certstore.jks + -Djavax.net.ssl.trustStorePassword=password +</programlisting> + + </para></listitem> + </itemizedlist> + <!--h2--></section> + + <section role="h2" id="SSL-.NetClient-28M4andup-29"><title> + .Net Client (M4 and up) + </title> + <itemizedlist> + <listitem><para>If the Qpid broker requires client authentication then you + need to get a certificate signed by a CA, trusted by your client. + </para></listitem> + </itemizedlist><para> + Use the connectSSL instead of the standard connect method of the + client interface. + </para><para> + connectSSL signature is as follows: + </para> + <programlisting> +public void connectSSL(String host, int port, String virtualHost, String username, String password, String serverName, String certPath, bool rejectUntrusted) +</programlisting> + <para> + Where + </para><itemizedlist> + <listitem><para>host: Host name on which a Qpid broker is deployed + </para></listitem> + <listitem><para>port: Qpid broker port + </para></listitem> + <listitem><para>virtualHost: Qpid virtual host name + </para></listitem> + <listitem><para>username: User Name + </para></listitem> + <listitem><para>password: Password + </para></listitem> + <listitem><para>serverName: Name of the SSL server + </para></listitem> + </itemizedlist><itemizedlist> + <listitem><para>certPath: Path to the X509 certificate to be used when the + broker requires client authentication + </para></listitem> + <listitem><para>rejectUntrusted: If true connection will not be established + if the broker is not trusted (the server certificate must be + added in your truststore) + </para></listitem> + </itemizedlist> + <!--h2--></section> + + <section role="h2" id="SSL-Python-26RubyClient-28M4andup-29"><title> + Python & + Ruby Client (M4 and up) + </title> + <para> + Simply use amqps:// in the URL string as defined above + </para> + <!--h2--></section> + <!--h1--></section> +</section> diff --git a/qpid/doc/book/src/old/Security-Plugins.xml b/qpid/doc/book/src/old/Security-Plugins.xml new file mode 100644 index 0000000000..bf5cb726b3 --- /dev/null +++ b/qpid/doc/book/src/old/Security-Plugins.xml @@ -0,0 +1,611 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd" + version="5.0" + label="Security-Plugins-Documentation"> + <title>Security Plugins Documentation</title> + + <section role="h2" label="SPD-Introduction"> + <title>Introduction</title> + <para> + This document describes the structure and design of Qpid security plugins, for + the Java broker. In particular, the new <emphasis>Access Control</emphasis> plugin, which implements + the same ACL file syntax as the C++ broker, is examined in detail. The security + plugins use the broker's OSGi bundle functionality to manage their lifecycle, + and the <code>ConfigurationPlugin</code> mechanism to manage their configuration via the + Apache commons configuration XML configuration file. + </para> + <para> + The Java interfaces and packages used by the security plugins are described here, + although the Javadoc documentation generated from the source should also be + consulted, and as always reading the source should provide further insight and information. + </para> + </section> + <section role="h2" label="SPD-Use-Cases"> + <title>Use Cases</title> + <para> + The following use cases were identified and used to drive the design and development + of both the security plugin mechanism in general, and the access control plugin in particular. + </para> + <itemizedlist> + <listitem> + <para> + Allow access to broker functions to be controlled by an ACL, with the checks being + carried out independently of the mechanism used to access the broker. This would + mean that a single <literal>CREATE </literal> permission would apply whether the queue was + created when a user logged in and used it, or if that user connected to the broker + via JMX or QMF and used the management operations to create the queue. + </para> + </listitem> + <listitem> + <para> + Permissions must be definable at a virtualhost level, with fallback to global + permissions. This allows access to be granted for operations only on a certain + host, while global operations such as broker administration can be defined at + the global level. It also allows default behaviour to be specified globally and + then overridden on a per-host basis. + </para> + </listitem> + <listitem> + <para> + The ACL mechanism controls access to operations on particular objects for all users, + if at least one user has a rule controlling access to that operation on that type of + object. This means that all users requiring access to a particular operation must be + configured. The default behaviour will be to deny access. + </para> + </listitem> + <listitem> + <para> + It should be possible for the addition of one access control rule to trigger the + addition of other rules, to simplify creation of rulesets. + </para> + </listitem> + <listitem> + <para> + The behaviour of the access control mechanism should be configurable. + </para> + </listitem> + <listitem> + <para> + The Java and C++ brokers should share a common configuration file format. + </para> + </listitem> + <listitem> + <para> + It should be possible to configure access to not just internal broker application + objects, but to the management operations and attributes of the broker, as well + as to external objects such as plugins. + </para> + </listitem> + <listitem> + <para> + As long as a suitably authenticated channel is used to connect, access control + rules should be applied when performing operations on broker objects. This does + not hold when, for example, an operator has local access and is using JConsole + to manage the broker. + </para> + </listitem> + </itemizedlist> + </section> + <section role="h2" label="SPD-Java-Interfaces-Packages-Classes"> + <title>Java Interfaces, Packages and Classes</title> + <para> + This section describes the Java artifacts that are involved in security plugin development. + They are mostly contained in the package <code>org.apache.qpid.server.security</code> which + is part of the broker code. It is recommended that a package prefix is chosen for new + security plugins, and this should be used to form the packages for the implementing classes. + </para> + <para> + In general, when creating a new plugin, you need three classes. These would be the main + <code>PluginName</code> class, which should implement the <code>SecurityPlugin</code> + interface and have a public static instance of an anonymous internal classes that implements + <code>SecurityPluginfactory</code>. Additionally, the <code>PluginNameConfiguration</code> + class, which should implement the <code>ConfigurationPlugin</code> interface and have a + public static instance of an anonymous internal classes that implements + <code>ConfigurationPluginfactory</code>, and finally the <code>PluginNameActivator</code> + class, which should extend the <code>SecurityPluginActivator</code> abstract class + and implement the required methods exposing the factories from the other classes. + </para> + <para> + These classes need to be visible from the broker, so they should be placed in the + <code>org.apache.qpid.server.security.pluginname.plugins</code> package, which should be + listed in the manifest file. Any internal classes for the plugin should be placed in + the <code>org.apache.qpid.server.security.pluginname.config</code> package which + should be marked as provate in the manifest. + </para> + <para> + If logging using the actor and subject framework is required, the property file should + be located in the <code>org.apache.qpid.server.security.pluginname.logging</code> + package, and this should also be exported in the manifest file. + </para> + <section role="h3" label="SPD-OSGi"> + <title>OSGi</title> + <para> + The security plugins are now loaded using the <emphasis>Felix</emphasis> OSGi container, which is started + as an embedded process inside the broker. This loads all plugin .jar files from the + directory named in the <code>plugin-directory</code> configuration element, cacheing them in the + <code>cache-directory</code> directory. Note that, at present, the cache directory is cleared at + startup, although this behaviour may change. To create OSGi plugin bundles, a manifest + file - <code>MANIFEST.MF</code> is created that specifies certain attributes of the bundle. A + sample manifest file for one of the security plugins is shown below. + </para> + <programlisting> +Manifest-Version: 1.0 +Bundle-ManifestVersion: 2 +Bundle-Name: Qpid Broker-Plugins PluginName +Bundle-SymbolicName: broker-plugins-pluginname +Bundle-Description: Name description. +Bundle-License: http://www.apache.org/licenses/LICENSE-2.0.txt +Bundle-DocURL: http://www.apache.org/qpid/pluginname.html +Bundle-Version: 1.0.0 +Bundle-Activator: org.apache.qpid.server.security.pluginname.plugins.PluginNameActivator +Bundle-RequiredExecutionEnvironment: JavaSE-1.5 +Bundle-ActivationPolicy: lazy +Import-Package: org.apache.qpid +Private-Package: org.apache.qpid.server.security.pluginname.config, + org.apache.qpid.server.security.pluginname.logging +Export-Package: org.apache.qpid.server.security.pluginname.plugins + </programlisting> + <para> + The complete list of packages to import will be determined by the actual operation of + the plugin, however the number of exported packages should be kept to a minimum. + </para> + </section> + <section role="h3" label="SPD-Plugin"> + <title>Plugin</title> + <para> + This is the main interface to be extended by all plugins. It contains a + method that allows configuration via the <code>ConfigurationPlugin</code> + mechanism. + </para> + <programlisting> +public void configure(ConfigurationPlugin config); + </programlisting> + </section> + <section role="h3" label="SPD-PluginFactory"> + <title>PluginFactory and SecurityPluginFactory</title> + <para> + These factories are used to initialise instances of plugins and configure them appropriately. + The factories are managed by the OSGI framework started by the <code>PluginManager</code>, + which is also used to retrieve the instances. + </para> + <programlisting> +public Class<P> getPluginClass(); +public String getPluginName(); +public P newInstance(ConfigurationPlugin config) throws ConfigurationException; + </programlisting> + </section> + <section role="h3" label="SPD-SecurityPlugin"> + <title>SecurityPlugin</title> + <para> + This is the interface that defines security plugins. The <code>getDefault</code> method + returns the default result for the plugin when no configuration is found for some + situation. + </para> + <para> + The <code>authorise</code> method is the main entry-point to the plugin, and is called + by the <code>SecurityManager</code> with the relevant paramaters. Similarly, the + <code>access</code> method is used for the special case of controlling access to + the entire virtual host, and the <code></code> + </para> + <programlisting> +Result getDefault(); +Result access(ObjectType objectType, Object instance); +Result authorise(Operation operation, ObjectType objectType, ObjectProperties properties); + </programlisting> + </section> + <section role="h3" label="SPD-SecurityPluginActivator"> + <title>SecurityPluginActivator</title> + <para> + The activator registers the factories with the OSGI framework, based on the + implementations of the abstract methods. + </para> + <programlisting> +public abstract SecurityPluginFactory getFactory(); +public abstract ConfigurationPluginFactory getConfigurationFactory(); + </programlisting> + </section> + <section role="h3" label="SPD-AbstractPlugin"> + <title>AbstractPlugin</title> + <para> + This is a simple parent class, which allows a common point of extension + for shared plugin code. Currently it simply implements the interface with + abstract methods. + </para> + <programlisting> +public abstract Result access(ObjectType object, Object instance); +public abstract Result authorise(Operation operation, ObjectType object, ObjectProperties properties); + </programlisting> + </section> + <section role="h3" label="SPD-AbstractProxyPlugin"> + <title>AbstractProxyPlugin</title> + <para> + This class is designed to be extended by plugins that only wish to take part in a subset + of the possible security descisions. Normally, a call to the <code>authorise</code> method + is proxied to one of the provided methods, based on the operation, for example a <literal>CONSUME</literal> + access control check would be proxied to the <code>authoriseConsume</code> method with + the appropriate paramaters set. The default behaviour is to return <literal>ABSTAIN</literal>, meaning + the plugin does not handle this type of operation. If a method is overridden, it can then perform + whatever security checks are required and return <literal>ALLOWED</literal> or <literal>DENIED</literal> + as appropriate. + </para> + <programlisting> +public Result authoriseConsume(ObjectType object, ObjectProperties properties); +public Result authorisePublish(ObjectType object, ObjectProperties properties); +public Result authoriseCreate(ObjectType object, ObjectProperties properties); +public Result authoriseAccess(ObjectType object, ObjectProperties properties); +public Result authoriseBind(ObjectType object, ObjectProperties properties); +public Result authoriseUnbind(ObjectType object, ObjectProperties properties); +public Result authoriseDelete(ObjectType object, ObjectProperties properties); +public Result authorisePurge(ObjectType object, ObjectProperties properties); +public Result authoriseExecute(ObjectType object, ObjectProperties properties); +public Result authoriseUpdate(ObjectType object, ObjectProperties properties); +public Result accessVirtualhost(Object instance); + </programlisting> + </section> + </section> + <section role="h2" label="SPD-Access-Control-Security-Plugin"> + <title>Access Control Security Plugin</title> + <para> + This security plugin implements access control using the same configuration file syntax as the + C++ broker. The classes are all in sub-packages of the <code>org.apache.qpid.server.security.access</code> + package. The exposed classes consist of the plugoin itself, its OSGi activator and the configuration + plugin, as well as the properties file and generated code for logging. The private, internal classes, + consist of the ruleset implementation for managing access control list rules. The plugin also makes + extensive use of the enumerations provided by the broker as part of the security plugin interfaces, + for operations, objects and permissions. + </para> + <section role="h3" label="SPD-ACL-Enumerations"> + <title>Enumerations</title> + <para> + These enumerations are used to define exactly what a security plugin can control. + </para> + <para> + The <code>ObjectProperties</code> and <code>ObjectProperties.Property</code> lalala + </para> + <para> + The <code>ObjectType</code> + </para> + <para> + The <code>Operation</code> + </para> + <para> + The <code>Permission</code> + </para> + </section> + <section role="h3" label="SPD-ACL-Configuration"> + <title>Configuration</title> + <para> + Security plugins are configurable using the Qpid XML configuration file, under the <code><security></code> + element. This can be either inside the main <code><broker /></code> element, as a global plugin affecting + all virtual hosts, or under a <code><virtualhosts><virtualhost><name></code> element, where + the <code><name></code> element is the name of the virtual host that is to be configured. Each security + plugin must register the elements it expects to process using a <code>ConfigurationPlugin</code>, which is + documented elsewhere. + </para> + <para> + The plugins are checked in order, first for the virtual host, then globally, and the first <literal>ALLOWED</literal> or + <literal>DENIED</literal> response is used. + </para> + <para> + The ACL configuration file is specified via the contents of the <code><aclv2></code> element. This is simply + the path to the file, which is a plain text format, and is parseable by both Java and C++ brokers. The path can be + specified with embedded property value interpolation, for environment variables or other properties defined in the + configuration file. + </para> + <programlisting> +<![CDATA[ +<security> + <!-- global access control configuration file --> + <aclv2>${QPID_HOME}/etc/global-security-config.txt</aclv2> +</security> +]]> + </programlisting> + <section role="h4" label="SPD-ACL-File-Format"> + <title>File Format</title> + <para> + The file format is described below. + </para> + <itemizedlist> + <listitem> + <para> + Whitespace is considered to be any ASCII + byte with a value below <literal>0x20</literal>, and is + ignored when it occurs between tokens. + </para> + </listitem> + <listitem> + <para> + Continuations using the <literal>\</literal> + character (ASCII <literal>0x5c</literal>) are allowed + anywhere on a line, and + can consist of a blank line with a continuation + character as the last non-whitespace token + </para> + <programlisting> +group group1 name1 name2 \ + name3 name4 \ + name5 +acl allow group1 create queue \ + property1 = "value1" \ + property2 \ + = "value2" + </programlisting> + </listitem> + <listitem> + <para> + Comments are line-style comments, and any text after + an un-quoted <literal>#</literal> (ASCII <literal>0x23</literal>) + are ignored, including continuations. The <literal>#</literal> + charater may appear in a quoted string. + </para> + </listitem> + <listitem> + <para> + Quoted strings consist of any ASCII inside matching pairs of + <literal>'</literal> or <literal>"</literal> (ASCII <literal>0x27</literal> + and <literal>0x22</literal>) characters, including any + otherwise special characters. + </para> + </listitem> + <listitem> + <para> + Tokens are <emphasis>NOT</emphasis> case sensitive, but quoted + strings <emphasis>ARE</emphasis>. + </para> + </listitem> + <listitem> + <para> + The <literal>=</literal> (ASCII <literal>0x3d</literal>) character + is special, and is used to indicate property value assignment. + </para> + </listitem> + <listitem> + <para> + Wildcards are specified using the <literal>*</literal> (ASCII + <literal>0x2a</literal>) character in a property value string, + which may be quoted. + </para> + </listitem> + <listitem> + <para> + Empty lines and lines that contain only whitespace are ignored. + </para> + </listitem> + <listitem> + <para> + The keyword <literal>all</literal> is reserved, and matches all individuals, + groups and actions. It may be used in place of a group or + individual name and/or an action - eg <literal>acl allow all all</literal>, + <literal>acl deny all all</literal> or <literal>acl deny user1 all</literal>. + </para> + </listitem> + <listitem> + <para> + Rules are interpreted from the top of the file down until the + name match is obtained; at which point processing stops. + </para> + </listitem> + <listitem> + <para> + The last line of the file (whether present or not) will be + assumed to be <literal>acl deny all all</literal>. If present in the file, any + lines below this one are ignored. + </para> + </listitem> + <listitem> + <para> + Names and group names may contain only <literal>a-z</literal>, + <literal>A-Z</literal>, <literal>0-9</literal>, + <literal>-</literal>, <literal>@</literal>, <literal>/</literal> + or <literal>_</literal>. + </para> + </listitem> + <listitem> + <para> + Rules must be preceded by any configuration and group definitions they may use; + any name not previously defined as a group will be assumed to be + that of an individual user. + </para> + </listitem> + <listitem> + <para> + <literal>CONFIG</literal> lines must have the following tokens in order: + </para> + <itemizedlist> + <listitem> + <para>The string literal <literal>config</literal></para> + </listitem> + <listitem> + <para>One or more property name-value pairs, in the form <literal>property = value</literal> + where value is the token <literal>true</literal> or <literal>false</literal></para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> + GROUP lines must have the following tokens in order: + </para> + <itemizedlist> + <listitem> + <para>The string literal <literal>group</literal></para> + </listitem> + <listitem> + <para>The name of the group, which cannot contain <literal>@</literal> or + <literal>/</literal> characters</para> + </listitem> + <listitem> + <para>A whitespace separated list of user and group names. User names are formatted + as <literal>username/domain@realm</literal> and group names must have been defined + earlier in the file</para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> + ACL rules must have the following tokens in order: + </para> + <itemizedlist> + <listitem> + <para>An optional rule number, which should be expressible as a positive Java integer</para> + </listitem> + <listitem> + <para>The string literal <literal>acl</literal></para> + </listitem> + <listitem> + <para>The permission, one of <literal>allow</literal>, <literal>allow-log</literal>, + <literal>deny</literal> or <literal>deny-log</literal></para> + </listitem> + <listitem> + <para>The name of a single group or individual or the keyword <literal>all</literal></para> + </listitem> + <listitem> + <para>The name of an operation, which should be one of <literal>consume</literal>, + <literal>publish</literal>, <literal>create</literal>, <literal>access</literal>, + <literal>bind</literal>, <literal>unbind</literal>, <literal>delete</literal>, + <literal>purge</literal>, <literal>update</literal>, <literal>execute</literal> + or the keyword <literal>all</literal></para> + </listitem> + <listitem> + <para>Optionally, a single object type or the keyword <literal>all</literal></para> + <para>Objects allowed are <literal>virtualhost</literal>, <literal>queue</literal>, + <literal>topic</literal> and <literal>exchange</literal></para> + <para>Objects allowed are <literal>virtualhost</literal>, <literal>queue</literal>, + <literal>topic</literal>, <literal>exchange</literal>, <literal>link</literal>, + <literal>route</literal>, <literal>method</literal> and <literal>object</literal></para> + </listitem> + <listitem> + <para>If the object is present, then optionally one or more property name-value pairs in the form + <literal>property=value</literal>. The property and value can be separated from the + <literal>=</literal> charater by any amount of whitespace, and the calue can be quoted if + it contains special characters or whitespace.</para> + </listitem> + <listitem> + <para>Property values can add the wildcard <literal>*</literal> character at the end of the string + to indicate that any string beginning with the characters up to the wildcard will match, or + if the wildcard is the only character, that any string will match</para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + <para> + This allows a rather looser and more readable style for ACL files, + while still retaining the ability to read the stricter files accepted + by the C++ broker. Bear in mind that the group declarations are to be + deprecated, in favour of an external directory service, using a plugin + mechanism. + </para> + <para> + The initial number is used to allow rulesets to be created which allow + individual rules to be enabled and disabled using an admin interface, + and an ACL file using numbered lines would be restricted to having + increasing numbers per rule, although gaps would be allowed to enable + rules to be inserted later, again using an admin interface. This + administrative interface would also allow saving of a modified ruleset + and re-loading. + </para> + </section> + <section role="h4" label="SPD-ACL-Broker-Access-Control"> + <title>Broker Access Control</title> + <para> + The Java broker access control mechanism is used to protect internal + entities used by the broker. These are virtual hosts, queues, topics + and exchanges. The actual access control checks take place in the + methods that carry out the operations on these objects, in order to + ensure thatsecurity is both mechanism and protocol agnostic. + </para> + <para> + <emphasis>The Java broker does not support <code>LINK</code> or + <code>ROUTE</code> object types.</emphasis> + </para> + <para> + An example of the various rules that can be specified follows: + </para> + <programlisting> +acl allow robot create exchange name="robot.*" +acl deny kitten create queue +acl allow guest bind exchange name=amq.topic routingkey="kitten.#" +acl allow all create queue name="tmp.*" +acl allow guest publish all durable="false" +acl allow robot create queue name="robot" +acl allow kitten consume queue durable="true" +acl allow guest create all + </programlisting> + </section> + <section role="h4" label="SPD-ACL-Management-Access-Control"> + <title>Management Access Control</title> + <para> + The management of the broker using JMX is also protected by the security + plugins, in two ways. If the management interface is used to perform + operations that would be access controlled normally, the same rules + would still apply and be applied. However, this only occurs when the + JMX connection was authenticated. If JConsole is used to connect directly + to a broker process started by the same user, then no extra checks are made. + </para> + <para> + The management operations themselves are also able to be access controlled. + This is done using the <code>METHOD</code> object type. A component name + and method name are specified as properties, and these indicate the MBean + type name and JMX method name respectively. If the operation is set to + <code>ALL</code> then reading JMX attributes, writing JMX attributes and + invoking JMX operations are controlled by the rule. Otherwise, the three + operations <code>ACCESS</code>, <code>UPDATE</code> and <code>EXECUTE</code> + control reading, writing and invocation respectively. + </para> + <programlisting> +ACL ALLOW user ALL METHOD +ACL ALLOW user ALL METHOD name="method" +ACL ALLOW user ALL METHOD name="prefix*" +ACL ALLOW user ALL METHOD component="MBean" name="method" +ACL ALLOW user ACCESS METHOD component="MBean" +ACL ALLOW user UPDATE METHOD component="MBean" +ACL ALLOW user EXECUTE METHOD component="MBean" + </programlisting> + </section> + <section role="h4" label="SPD-ACL-External-Object-Access-Control"> + <title>External Object Access Control</title> + <para> + At the moment the C++ broker has an extension point to allow access control + of external objects. This will be provided in the Java broker as well, using the + <code>ACCESS OBJECT</code> rule, with package name and class name properties. + The external object must be able to retrieve a reference to the virtual host + it is running on, and then call the <code>accessObject</code> method. This + must be the responsibility of the external object. + </para> + <para> + <emphasis>Note that this is not currently implemented in the <code>SecurityManager</code>.</emphasis> + </para> + <programlisting> +ACL ALLOW user ACCESS OBJECT package="com.example.application" class="Extension" + </programlisting> + <programlisting> +if (!_vhost.getSecurityManager().accessObject("com.example.application", "Extension")) +{ + // TODO reject access somehow - exception +} + </programlisting> + </section> + </section> + </section> +</section> diff --git a/qpid/doc/book/src/old/System-Properties.xml b/qpid/doc/book/src/old/System-Properties.xml new file mode 100644 index 0000000000..40b823185f --- /dev/null +++ b/qpid/doc/book/src/old/System-Properties.xml @@ -0,0 +1,357 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section> + + <title> + System Properties + </title> + + <section role="h2" id="SystemProperties-ExplanationofSystempropertiesusedinQpid"> + + <title> Explanation of System properties used in Qpid </title> + + <para> + This page documents the various System Properties that are + currently used in the Qpid Java code base. + </para> + +<!-- ######################################################### --> + + <section role="h3" id="SystemProperties-ClientProperties"> + <title> Client Properties </title> + + <variablelist> + <varlistentry> + <term>STRICT_AMQP</term> + <listitem> + <variablelist> + <varlistentry> + <term>Type</term> + <listitem><para>Boolean</para></listitem> + </varlistentry> + <varlistentry> + <term>Default</term> + <listitem><para>FALSE</para></listitem> + </varlistentry> + </variablelist> + <para> This forces the client to only send AMQP compliant + frames. This will disable a number of JMS features.</para> + + <itemizedlist> + <title> Features disabled by STRICT_AMQP</title> + <listitem><para>Queue Browser + </para></listitem> + <listitem><para>Message Selectors + </para></listitem> + <listitem><para>Durable Subscriptions + </para></listitem> + <listitem><para>Session Recover may result in duplicate message delivery + </para></listitem> + <listitem><para>Destination validation, so no InvalidDestinationException + will be thrown + </para></listitem> + </itemizedlist> + <para> + This is associated with property <xref linkend="SystemProperties-STRICTAMQPFATAL"/> + </para> + </listitem> + </varlistentry> + + + + <varlistentry id="SystemProperties-STRICTAMQPFATAL"> + <term>STRICT_AMQP_FATAL</term> + <listitem> + <variablelist> + <varlistentry> + <term>Type</term> + <listitem><para>Boolean</para></listitem> + </varlistentry> + <varlistentry> + <term>Default</term> + <listitem><para>FALSE</para></listitem> + </varlistentry> + </variablelist> + <para> + This will cause any attempt to utilise an enhanced feature to + throw and UnsupportedOperationException. When set to false then + the exception will not occur but the feature will be disabled. + </para> + <para> + e.g. + The Queue Browser will always show no messages. + Any message selector will be removed. + </para> + </listitem> + </varlistentry> + + + <varlistentry> + <term>IMMEDIATE_PREFETCH</term> + <listitem> + <variablelist> + <varlistentry> + <term>Type</term> + <listitem><para>Boolean</para></listitem> + </varlistentry> + <varlistentry> + <term>Default</term> + <listitem><para>FALSE</para></listitem> + </varlistentry> + </variablelist> + <para> + The default with AMQP is to start prefetching messages. However, + with certain 3rd party Java tools, such as Mule this can cause a + problem. Mule will create a consumer but never consume from it so + any any prefetched messages will be stuck until that session is + closed. This property is used to re-instate the default AMQP + behaviour. The default Qpid behaviour is to prevent prefetch + occurring, by starting the connection Flow Controlled, until a + request for a message is made on the consumer either via a + receive() or setting a message listener.</para> + </listitem> + </varlistentry> + + + + <varlistentry> + <term>qpid.sync_op_timeout</term> + <listitem> + <variablelist> + <varlistentry> + <term>Type</term> + <listitem><para>long</para></listitem> + </varlistentry> + <varlistentry> + <term>Default</term> + <listitem><para>60000</para></listitem> + </varlistentry> + </variablelist> + <para>The length of time (in milliseconds) to wait for a synchronous operation to complete. + For compatibility with older clients, the synonym amqj.default_syncwrite_timeout is supported.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>amq.dynamicsaslregistrar.properties</term> + <listitem> + <variablelist> + <varlistentry> + <term>Type</term> + <listitem><para>String</para></listitem> + </varlistentry> + <varlistentry> + <term>Default</term> + <listitem><para>org/apache/qpid/client/security/DynamicSaslRegistrar.properties</para></listitem> + </varlistentry> + </variablelist> + <para>The name of the SASL configuration properties file. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>amqj.heartbeat.timeoutFactor</term> + <listitem> + <variablelist> + <varlistentry> + <term>Type</term> + <listitem><para>float</para></listitem> + </varlistentry> + <varlistentry> + <term>Default</term> + <listitem><para>2.0</para></listitem> + </varlistentry> + </variablelist> + <para> + The factor used to get the timeout from the delay between + heartbeats + </para> + </listitem> + </varlistentry> + + + <varlistentry> + <term>amqj.tcp_nodelay</term> + <listitem> + <variablelist> + <varlistentry> + <term>Type</term> + <listitem><para>Boolean</para></listitem> + </varlistentry> + <varlistentry> + <term>Default</term> + <listitem><para>TRUE</para></listitem> + </varlistentry> + </variablelist> + <para> Disable Nagle's algorithm on the TCP connection. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>amqj.protocol.logging.level</term> + <listitem> + <variablelist> + <varlistentry> + <term>Type</term> + <listitem><para>Boolean</para></listitem> + </varlistentry> + <varlistentry> + <term>Default</term> + <listitem><para>null</para></listitem> + </varlistentry> + </variablelist> + <para>If set this will turn on protocol logging on the + client. </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>jboss.host</term> + <listitem> + <para> + Used by the JBossConnectionFactoryInitialiser to specify the host + to connect to perform JNDI lookups. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>jboss.port</term> + <listitem> + <para> + Used by the JBossConnectionFactoryInitialiser to specify the port + to connect to perform JNDI lookups. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>amqj.MaximumStateWait</term> + <listitem> + <variablelist> + <varlistentry> + <term>Default</term> + <listitem><para>30000</para></listitem> + </varlistentry> + </variablelist> + <para> + Used to set the maximum time the State Manager should wait before + timing out a frame wait. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> +<!-- ######################################################### --> + + <section role="h3" id="SystemProperties-ManagementProperties"> + + <title> + Management Properties + </title> + + <variablelist> + <varlistentry> + <term>security</term> + <listitem> + <variablelist> + <varlistentry> + <term>Default</term> + <listitem><para>null</para></listitem> + </varlistentry> + </variablelist> + <para> + String representing the Security level to be used to on + the connection to the broker. The null default results + in no security or PLAIN. When used with jmxconnector + 'javax.management.remote.jmxmp.JMXMPConnector' a + security value of 'CRAM-MD5' will result in all + communication to the broker being encrypted. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>jmxconnector</term> + <listitem> + <variablelist> + <varlistentry> + <term>Default</term> + <listitem><para>null</para></listitem> + </varlistentry> + </variablelist> + <para> + String representing the JMXConnector class used to + perform the connection to the broker. The null default + results in the standard JMX connector. Utilising + 'javax.management.remote.jmxmp.JMXMPConnector' and + security 'CRAM-MD5' will result in all communication to + the broker being encrypted. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>timeout</term> + <listitem> + <variablelist> + <varlistentry> + <term>Default</term> + <listitem><para>5000</para></listitem> + </varlistentry> + </variablelist> + <para> + Long value representing the milli seconds before + connection to the broker should timeout. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </section> + + +<!-- ######################################################### --> + + + <section role="h3" id="SystemProperties-PropertiesusedinExamples"> + + <title> Properties used in Examples </title> + + <variablelist> + <varlistentry> + <term>archivepath</term> + <listitem> + <para> + Used in <filename>FileMessageDispatcher</filename>. This + properties specifies the directory to move payload + file(s) to archive location as no error</para> + </listitem> + </varlistentry> + </variablelist> +</section> +</section> +</section> diff --git a/qpid/doc/book/src/old/Using-Qpid-with-other-JNDI-Providers.xml b/qpid/doc/book/src/old/Using-Qpid-with-other-JNDI-Providers.xml new file mode 100644 index 0000000000..2bd7d761ef --- /dev/null +++ b/qpid/doc/book/src/old/Using-Qpid-with-other-JNDI-Providers.xml @@ -0,0 +1,215 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<chapter> + + <title> + Using Qpid with other JNDI Providers + </title> + + <section role="h2" id="UsingQpidwithotherJNDIProviders-HowtouseaJNDIProvider"> + + <title> How to use a JNDI Provider </title> + + <para> + Qpid will work with any JNDI provider capable of storing Java + objects. We have a task to add our own initial context factory, + but until that's available .... + </para> + + <para> + First you must select a JNDI provider to use. If you aren't + already using an application server (i.e. Tomcat ?) which + provides JNDI support you could consider using either: + </para> + + <itemizedlist> + <listitem><para>Apache's <xref linkend="qpid_index"/> + which provides an LDAP JNDI implementation + </para></listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para>OR the SUN JNDI SPI for the FileSystem which can be + downloaded from <xref linkend="qpid_index"/> + </para> + <itemizedlist> + <listitem><para>Click : Download JNDI 1.2.1 & More button + </para></listitem> + <listitem><para>Download: File System Service Provider, 1.2 Beta 3 + </para></listitem> + <listitem><para>and then add the two jars in the lib dir to your class path. + </para></listitem> + </itemizedlist> + </listitem> + </itemizedlist> + + + <para> + There are two steps to using JNDI objects. + </para> + + <itemizedlist> + <listitem><para>Bind : Which stores a reference to a JMS + Object in the provider.</para></listitem> + <listitem><para>Lookup : Which tries to retrieve the + reference and create the JMS Object. </para></listitem> + </itemizedlist> + + <para> + There are two objects that would normally be stored in JNDI. + </para> + + <itemizedlist> + <listitem><para>A ConnectionFactory + </para></listitem> + <listitem><para>A Destination (Queue or Topic) + </para></listitem> + </itemizedlist> + + + <section role="h3" id="UsingQpidwithotherJNDIProviders-Binding"> + <title> + Binding + </title> + + <para> + Then you need to setup the values that the JNDI provider will + used to bind your references, something like this: + </para> + + <example> + <title>Setup JNDI</title> + + + <programlisting> +Hashtable env = new Hashtable(11); + env.put(Context.INITIAL_CONTEXT_FACTORY,"com.sun.jndi.fscontext.RefFSContextFactory"); + env.put(Context.PROVIDER_URL,LOCAL_FILE_PATH_FOR_STORING_BINDS_PATH_MUST_EXIST); +</programlisting> +</example> + + <para> + These values are then used to create a context to bind your + references. + </para> + +<example> + <title>Perform Binding of ConnectionFactory</title> + + + <programlisting> +try +{ + Context ctx = new InitialContext(env); + + // Create the object to be bound in this case a ConnectionFactory + ConnectionFactory factory = null; + + try + { + factory = new AMQConnectionFactory(CONNECTION_URL); + try + { + ctx.bind(binding, factory); + } + catch (NamingException e) + { + //Handle problems with binding. Such as the binding already exists. + } + } + catch (URLSyntaxException amqe) + { + //Handle any exception with creating ConnnectionFactory + } +} +catch (NamingException e) +{ + //Handle problem creating the Context. +} +</programlisting> +</example> + + <para> + To bind a queue instead simply create a AMQQueue object and use + that in the binding call. + </para> + +<example> +<title> Bind a AMQQueue</title> + <programlisting> +AMQQueue queue = new AMQQueue(QUEUE_URL); +ctx.bind(binding, queue); +</programlisting> +</example> + </section> + + <section role="h3" id="UsingQpidwithotherJNDIProviders-Lookup"> + <title> + Lookup + </title> + <para> + You can then get a queue connection factory from the JNDI + context. + </para> + + +<example> +<title> Perform Binding of ConnectionFactory</title> + + + <programlisting> +ConnectionFactory factory; +try +{ + factory= (ConnectionFactory)ctx.lookup(binding); +} +catch (NamingException e) +{ + //Handle problems with lookup. Such as binding does not exist. +} +</programlisting> +</example> + + <para> + Note that you need not cast the bound object back to an + AMQConnectionFactory so all your current JMS apps that + use JNDI can start using Qpid straight away. + </para> + + <!--h2--> + </section> + + <section role="h2" id="UsingQpidwithotherJNDIProviders-HowtocreateaTopicConnectionFactoryandQueueConnectionFactory"><title> + How to create a TopicConnectionFactory and + QueueConnectionFactory + </title> + <para> + AMQConnectionFactory implements TopicConnectionFactory and + QueueConnectionFactory as well as the ConnectionFactory. + </para> +<!--h3--> + </section> +<!--h2--> + </section> +</chapter> diff --git a/qpid/doc/book/src/old/WCF.xml b/qpid/doc/book/src/old/WCF.xml new file mode 100644 index 0000000000..aaf54463db --- /dev/null +++ b/qpid/doc/book/src/old/WCF.xml @@ -0,0 +1,137 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section> + <title> + WCF + </title> + <section role="h1" id="WCF-Introduction"> + <title> + Introduction + </title> + + <para> + WCF (<emphasis>Windows Communication Foundation)</emphasis> unifies the .Net + communication capabilities into a single, common, general Web + service oriented framework. A good WCF tutorial can be found + <ulink url="http://www.netfxharmonics.com/2008/11/Understanding-WCF-Services-in-Silverlight-2#WCFSilverlightIntroduction">here</ulink>. + </para> + <para> + WCF separates how service logic is written from how services + communicate with clients. Bindings are used to specify the + transport, encoding, and protocol details required for clients + and services to communicate with each other. Qpid provide a WCF + binding: org.apache.qpid.wcf.model.QpidBinding. WCF Services that + use the Qpid binding communicate through queues that are + dynamically created on a Qpid broker. + </para> + <!--h1--> + </section> + <section role="h1" id="WCF-HowtouseQpidbinding"> + <title> + How to use Qpid binding + </title> + + <para> + WCF services are implemented using: + </para> + <itemizedlist> + <listitem> + <para>A service contract with one or more operation contracts. + </para> + </listitem> + <listitem> + <para>A service implementation for those contracts. + </para> + </listitem> + <listitem> + <para>A configuration file to provide that implementation with an + endpoint and a binding for that specific contract. + </para> + </listitem> + </itemizedlist> + <para> + The following configuration file can be used to configure a Hello + Service: + </para> + <programlisting> +<configuration> + <system.serviceModel> + <services> + <!-- the service class --> + <service name="org.apache.qpid.wcf.demo.HelloService"> + <host> + <baseAddresses> + <!-- Use SOAP over AMQP --> + <add baseAddress="soap.amqp:///" /> + </baseAddresses> + </host> + + <endpoint + address="Hello" + <!-- We use a Qpid Binding, see below def --> + binding="customBinding" + bindingConfiguration="QpidBinding" + <!-- The service contract --> + contract="org.apache.qpid.wcf.demo.IHelloContract"/> + </service> + </services> + + <bindings> + <customBinding> + <!-- cf def of the qpid binding --> + <binding name="QpidBinding"> + <textMessageEncoding /> + <!-- specify the host and port number of the broker --> + <QpidTransport + host="192.168.1.14" + port="5673" /> + </binding> + </customBinding> + </bindings> + + <extensions> + <bindingElementExtensions> + <!-- use Qpid binding element: org.apache.qpid.wcf.model.QpidTransportElement --> + <add + name="QpidTransport" + type="org.apache.qpid.wcf.model.QpidTransportElement, qpidWCFModel"/> + </bindingElementExtensions> + </extensions> + + </system.serviceModel> +</configuration> + </programlisting> + <para> + Endpoints and bindings can also be set within the service code: + </para> + <programlisting> +/* set HostName, portNumber and MyService accordingly */ +Binding binding = new QpidBinding("HostName", portNumber); +ServiceHost service = new ServiceHost(typeof(MyService), new Uri("soap.amqp:///")); +service.AddServiceEndpoint(typeof(IBooking), binding, "MyService"); +service.Open(); +.... + </programlisting> + <!--h1--> + </section> +</section> diff --git a/qpid/doc/book/src/old/schemas.xml b/qpid/doc/book/src/old/schemas.xml new file mode 100644 index 0000000000..6102e65f07 --- /dev/null +++ b/qpid/doc/book/src/old/schemas.xml @@ -0,0 +1,102 @@ +<?xml version="1.0"?> +<!-- + +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you 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. + +--> + +<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0"> + <uri resource="foo.xml" typeId="DocBook"/> + <uri resource="foo.xml" typeId="DocBook"/> + <uri resource="Programming-In-Apache-Qpid.xml" typeId="DocBook"/> + <uri resource="queue-state-replication.xml" typeId="DocBook"/> + <uri resource="AMQP-Messaging-Broker-Java-Book.xml" typeId="DocBook"/> + <uri resource="AMQP-Messaging-Broker-CPP-Book.xml" typeId="DocBook"/> + <uri resource="High-Level-API.xml" typeId="DocBook"/> + <uri resource="High-Level-API.xml" typeId="DocBook"/> + <uri resource="Java-JMS-Selector-Syntax.xml" typeId="DocBook"/> + <uri resource="ACL.xml" typeId="DocBook"/> + <uri resource="Add-New-Users.xml" typeId="DocBook"/> + <uri resource="AMQP-C++-Messaging-Client.xml" typeId="DocBook"/> + <uri resource="AMQP-Compatibility.xml" typeId="DocBook"/> + <uri resource="AMQP-Java-JMS-Messaging-Client.xml" typeId="DocBook"/> + <uri resource="AMQP-Messaging-Broker-CPP.xml" typeId="DocBook"/> + <uri resource="AMQP-Messaging-Broker-Java.xml" typeId="DocBook"/> + <uri resource="AMQP-.NET-Messaging-Client.xml" typeId="DocBook"/> + <uri resource="AMQP-Python-Messaging-Client.xml" typeId="DocBook"/> + <uri resource="AMQP-Ruby-Messaging-Client.xml" typeId="DocBook"/> + <uri resource="AMQP.xml" typeId="DocBook"/> + <uri resource="Binding-URL-Format.xml" typeId="DocBook"/> + <uri resource="Book-Info.xml" typeId="DocBook"/> + <uri resource="Book.xml" typeId="DocBook"/> + <uri resource="Broker-CPP.xml" typeId="DocBook"/> + <uri resource="Broker-Java.xml" typeId="DocBook"/> + <uri resource="Cheat-Sheet-for-configuring-Exchange-Options.xml" typeId="DocBook"/> + <uri resource="Cheat-Sheet-for-configuring-Queue-Options.xml" typeId="DocBook"/> + <uri resource="Clients.xml" typeId="DocBook"/> + <uri resource="Configure-ACLs.xml" typeId="DocBook"/> + <uri resource="Configure-Java-Qpid-to-use-a-SSL-connection.xml" typeId="DocBook"/> + <uri resource="Configure-Log4j-CompositeRolling-Appender.xml" typeId="DocBook"/> + <uri resource="Configure-the-Broker-via-config.xml.xml" typeId="DocBook"/> + <uri resource="Configure-the-Virtual-Hosts-via-virtualhosts.xml.xml" typeId="DocBook"/> + <uri resource="Configuring-Management-Users.xml" typeId="DocBook"/> + <uri resource="Configuring-Qpid-JMX-Management-Console.xml" typeId="DocBook"/> + <uri resource="Connection-URL-Format.xml" typeId="DocBook"/> + <uri resource="Debug-using-log4j.xml" typeId="DocBook"/> + <uri resource="Download.xml" typeId="DocBook"/> + <uri resource="Excel-AddIn.xml" typeId="DocBook"/> + <uri resource="FAQ.xml" typeId="DocBook"/> + <uri resource="foo.xml" typeId="DocBook"/> + <uri resource="f.xml" typeId="DocBook"/> + <uri resource="Getting-Started.xml" typeId="DocBook"/> + <uri resource="How-to-Tune-M3-Java-Broker-Performance.xml" typeId="DocBook"/> + <uri resource="How-to-Use-JNDI.xml" typeId="DocBook"/> + <uri resource="Introduction.xml" typeId="DocBook"/> + <uri resource="Java-Broker-Feature-Guide.xml" typeId="DocBook"/> + <uri resource="Java-Environment-Variables.xml" typeId="DocBook"/> + <uri resource="LVQ.xml" typeId="DocBook"/> + <uri resource="Management-Console-Security.xml" typeId="DocBook"/> + <uri resource="Management-Design-notes.xml" typeId="DocBook"/> + <uri resource="Managing-CPP-Broker.xml" typeId="DocBook"/> + <uri resource="MessageStore-Tool.xml" typeId="DocBook"/> + <uri resource="NET-User-Guide.xml" typeId="DocBook"/> + <uri resource="PythonBrokerTest.xml" typeId="DocBook"/> + <uri resource="QMan-Qpid-Management-bridge.xml" typeId="DocBook"/> + <uri resource="QMF-Python-Console-Tutorial.xml" typeId="DocBook"/> + <uri resource="Qpid-ACLs.xml" typeId="DocBook"/> + <uri resource="Qpid-Interoperability-Documentation.xml" typeId="DocBook"/> + <uri resource="Qpid-Java-Broker-Management-CLI.xml" typeId="DocBook"/> + <uri resource="Qpid-Java-Build-How-To.xml" typeId="DocBook"/> + <uri resource="Qpid-Java-FAQ.xml" typeId="DocBook"/> + <uri resource="Qpid-JMX-Management-Console-FAQ.xml" typeId="DocBook"/> + <uri resource="Qpid-JMX-Management-Console-User-Guide.xml" typeId="DocBook"/> + <uri resource="Qpid-JMX-Management-Console.xml" typeId="DocBook"/> + <uri resource="Qpid-Management-Features.xml" typeId="DocBook"/> + <uri resource="Qpid-Management-Framework.xml" typeId="DocBook"/> + <uri resource="Qpid-Troubleshooting-Guide.xml" typeId="DocBook"/> + <uri resource="queue-state-replication.xml" typeId="DocBook"/> + <uri resource="Running-CPP-Broker.xml" typeId="DocBook"/> + <uri resource="SASL-Compatibility.xml" typeId="DocBook"/> + <uri resource="SSL.xml" typeId="DocBook"/> + <uri resource="Active-Active-Cluster.xml" typeId="DocBook"/> + <uri resource="System-Properties.xml" typeId="DocBook"/> + <uri resource="Use-Priority-Queues.xml" typeId="DocBook"/> + <uri resource="Using-Broker-Federation.xml" typeId="DocBook"/> + <uri resource="Using-Qpid-with-other-JNDI-Providers.xml" typeId="DocBook"/> + <uri resource="WCF.xml" typeId="DocBook"/> +</locatingRules> diff --git a/qpid/doc/book/src/programming/Makefile b/qpid/doc/book/src/programming/Makefile new file mode 100644 index 0000000000..0266a0f54d --- /dev/null +++ b/qpid/doc/book/src/programming/Makefile @@ -0,0 +1,20 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you 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. +# + +include ../Makefile.inc diff --git a/qpid/doc/book/src/programming/Message-Groups-Guide.xml b/qpid/doc/book/src/programming/Message-Groups-Guide.xml new file mode 100644 index 0000000000..0ec6982bac --- /dev/null +++ b/qpid/doc/book/src/programming/Message-Groups-Guide.xml @@ -0,0 +1,163 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<section id="Message-Groups-Guide"> + <title>Using Message Groups</title> + <para> + This section describes how messaging applications can use the Message Group feature + provided by the Broker. + </para> + <note> + The content of this section assumes the reader is familiar with the Message Group + feature as described in the AMQP Messaging Broker user's guide. Please read the + message grouping section in the Broker user's guide before using the + examples given in this section. + </note> + <section role="h2" id="messagegroups-setup"> + <title>Creating Message Group Queues</title> + <para> + The following examples show how to create a message group queue that enforces + ordered group consumption across multiple consumers. + </para> + <example> + <title>Message Group Queue Creation - Python</title> + <programlisting lang="python"> +sender = connection.session().sender("msg-group-q;" + + " {create:always, delete:receiver," + + " node: {x-declare: {arguments:" + + " {'qpid.group_header_key':'THE-GROUP'," + + " 'qpid.shared_msg_group':1}}}}") + </programlisting> + </example> + <example> + <title>Message Group Queue Creation - C++</title> + <programlisting lang="c++"> +std::string addr("msg-group-q; " + " {create:always, delete:receiver," + " node: {x-declare: {arguments:" + " {qpid.group_header_key:'THE-GROUP'," + " qpid.shared_msg_group:1}}}}"); +Sender sender = session.createSender(addr); + </programlisting> + </example> + <example> + <title>Message Group Queue Creation - Java</title> + <programlisting lang="java"> +Session s = c.createSession(false, Session.CLIENT_ACKNOWLEDGE); +String addr = "msg-group-q; {create:always, delete:receiver," + + " node: {x-declare: {arguments:" + + " {'qpid.group_header_key':'THE-GROUP'," + + " 'qpid.shared_msg_group':1}}}}"; +Destination d = (Destination) new AMQAnyDestination(addr); +MessageProducer sender = s.createProducer(d); + </programlisting> + </example> + <para> + The example code uses the x-declare map to specify the message group configuration + that should be used for the queue. See the AMQP Messaging Broker user's guide + for a detailed description of these arguments. Note that the + qpid.group_header_key's value MUST be a string type if using the C++ broker. + </para> + </section> + <section role="h2" id="messagegroups-sending"> + <title>Sending Grouped Messages</title> + <para> + When sending grouped messages, the client must add a message property containing the + group identifier to the outgoing message. If using the C++ broker, the group identifier + must be a string type. The key used for the property must exactly match the value passed in the + 'qpid.group_header_key' configuration argument. + </para> + <example> + <title>Sending Grouped Messages - Python</title> + <programlisting lang="python"> +group = "A" +m = Message(content="some data", properties={"THE-GROUP": group}) +sender.send(m) + +group = "B" +m = Message(content="some other group's data", properties={"THE-GROUP": group}) +sender.send(m) + +group = "A" +m = Message(content="more data for group 'A'", properties={"THE-GROUP": group}) +sender.send(m) + </programlisting> + </example> + <example> + <title>Sending Grouped Messages - C++</title> + <programlisting lang="C++"> + +const std::string groupKey("THE-GROUP"); +{ + Message msg("some data"); + msg.getProperties()[groupKey] = std::string("A"); + sender.send(msg); +} +{ + Message msg("some other group's data"); + msg.getProperties()[groupKey] = std::string("B"); + sender.send(msg); +} +{ + Message msg("more data for group 'A'"); + msg.getProperties()[groupKey] = std::string("A"); + sender.send(msg); +} + </programlisting> + </example> + <example> + <title>Sending Grouped Messages - Java</title> + <programlisting lang="java"> +String groupKey = "THE-GROUP"; + +TextMessage tmsg1 = s.createTextMessage("some data"); +tmsg1.setStringProperty(groupKey, "A"); +sender.send(tmsg1); + +TextMessage tmsg2 = s.createTextMessage("some other group's data"); +tmsg2.setStringProperty(groupKey, "B"); +sender.send(tmsg2); + +TextMessage tmsg3 = s.createTextMessage("more data for group 'A'"); +tmsg3.setStringProperty(groupKey, "A"); +sender.send(tmsg3); + </programlisting> + </example> + <para> + The examples above send two groups worth of messages to the queue created in the + previous example. Two messages belong to group "A", and one belongs to group + "B". Note that it is not necessary to complete sending one group's messages before + starting another. Also note that there is no need to indicate to the broker when a + new group is created or an existing group retired - the broker tracks group state + automatically. + </para> + </section> + <section role="h2" id="messagegroups-receiving"> + <title>Receiving Grouped Messages</title> + <para> + Since the broker enforces group policy when delivering messages, no special actions + are necessary for receiving grouped messages from the broker. However, applications + must adhere to the rules for message group consumption as described in the AMQP + Messaging Broker user's guide. + </para> + </section> +</section> diff --git a/qpid/doc/book/src/programming/Programming-In-Apache-Qpid.xml b/qpid/doc/book/src/programming/Programming-In-Apache-Qpid.xml new file mode 100644 index 0000000000..8bd9225fb2 --- /dev/null +++ b/qpid/doc/book/src/programming/Programming-In-Apache-Qpid.xml @@ -0,0 +1,6594 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> + +<!-- + +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you 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. + +--> + +<book id="client-api-tutorial"> + <title>Programming in Apache Qpid</title> + <subtitle>Cross-Platform AMQP Messaging in Java JMS, .NET, C++, and Python</subtitle> + + <chapter> + <title>Introduction</title> + + <para>Apache Qpid is a reliable, asynchronous messaging system that + supports the AMQP messaging protocol in several common programming + languages. Qpid is supported on most common platforms. + </para> + + <itemizedlist> + <listitem> + <para> + On the Java platform, Qpid uses the + established <ulink url="http://java.sun.com/products/jms/">Java JMS + API</ulink>. + </para> + </listitem> + <listitem> + <para> + For Python, C++, and .NET, Qpid defines its own messaging API, the + <firstterm>Qpid Messaging API</firstterm>, which is + conceptually similar in each. + </para> + <para> + On the .NET platform, Qpid also provides a WCF binding. + </para> + </listitem> + <listitem> + <para> + Ruby will also use the Qpid Messaging API, which will soon + be implemented. (Ruby currently uses an API that is closely + tied to the AMQP version). + </para> + </listitem> + </itemizedlist> + + </chapter> + + <chapter> + <title>Using the Qpid Messaging API</title> + + <para>The Qpid Messaging API is quite simple, consisting of only a + handful of core classes. + </para> + + <itemizedlist> + + <listitem> + <para> + A <firstterm>message</firstterm> consists of a standard set + of fields (e.g. <literal>subject</literal>, + <literal>reply-to</literal>), an application-defined set of + properties, and message content (the main body of the + message). + </para> + </listitem> + + <listitem> + <para> + A <firstterm>connection</firstterm> represents a network + connection to a remote endpoint. + </para> + </listitem> + + <listitem> + <para> + A <firstterm>session</firstterm> provides a sequentially + ordered context for sending and receiving + <emphasis>messages</emphasis>. A session is obtained from a + connection. + </para> + </listitem> + + <listitem> + <para> + A <firstterm>sender</firstterm> sends messages to a target + using the <literal>sender.send</literal> method. A sender is + obtained from a session for a given target address. + </para> + </listitem> + + <listitem> + <para> + A <firstterm>receiver</firstterm> receives messages from a + source using the <literal>receiver.fetch</literal> method. + A receiver is obtained from a session for a given source + address. + </para> + </listitem> + + </itemizedlist> + + <para> + The following sections show how to use these classes in a + simple messaging program. + </para> + + <section> + <title>A Simple Messaging Program in C++</title> + + <para>The following C++ program shows how to create a connection, + create a session, send messages using a sender, and receive + messages using a receiver.</para> + + <example> + <title>"Hello world!" in C++</title> + <programlisting lang="c++"><![CDATA[ + #include <qpid/messaging/Connection.h> + #include <qpid/messaging/Message.h> + #include <qpid/messaging/Receiver.h> + #include <qpid/messaging/Sender.h> + #include <qpid/messaging/Session.h> + + #include <iostream>]]> + + using namespace qpid::messaging; + + int main(int argc, char** argv) { + std::string broker = argc > 1 ? argv[1] : "localhost:5672"; + std::string address = argc > 2 ? argv[2] : "amq.topic"; + std::string connectionOptions = argc > 3 ? argv[3] : ""; + + Connection connection(broker, connectionOptions); + try { + connection.open(); <co id="hello-cpp-open" linkends="callout-cpp-open"/> + Session session = connection.createSession(); <co id="hello-cpp-session" linkends="callout-cpp-session"/> + + Receiver receiver = session.createReceiver(address); <co id="hello-cpp-receiver" linkends="callout-cpp-receiver"/> + Sender sender = session.createSender(address); <co id="hello-cpp-sender" linkends="callout-cpp-sender"/> + + sender.send(Message("Hello world!")); + + Message message = receiver.fetch(Duration::SECOND * 1); <co id="hello-cpp-fetch" linkends="callout-cpp-fetch"/> + <![CDATA[std::cout << message.getContent() << std::endl;]]> + session.acknowledge(); <co id="hello-cpp-acknowledge" linkends="callout-cpp-acknowledge"/> + + connection.close(); <co id="hello-cpp-close" linkends="callout-cpp-close"/> + return 0; + } catch(const std::exception& error) { + <![CDATA[std::cerr << error.what() << std::endl;]]> + connection.close(); + return 1; + } + }</programlisting> + + <calloutlist> + <callout id="callout-cpp-open" arearefs="hello-cpp-open"> + <para>Establishes the connection with the messaging broker.</para> + </callout> + <callout id="callout-cpp-session" arearefs="hello-cpp-session"> + <para>Creates a session object on which messages will be sent and received.</para> + </callout> + <callout id="callout-cpp-receiver" arearefs="hello-cpp-receiver"> + <para>Creates a receiver that receives messages from the given address.</para> + </callout> + <callout id="callout-cpp-sender" arearefs="hello-cpp-sender"> + <para>Creates a sender that sends to the given address.</para> + </callout> + <callout id="callout-cpp-fetch" arearefs="hello-cpp-fetch"> + <para>Receives the next message. The duration is optional, if omitted, will wait indefinitely for the next message.</para> + </callout> + <callout id="callout-cpp-acknowledge" arearefs="hello-cpp-acknowledge"> + <para>Acknowledges receipt of all fetched messages on the + session. This informs the broker that the messages were + transferred and processed by the client successfully.</para> + </callout> + <callout id="callout-cpp-close" arearefs="hello-cpp-close"> + <para>Closes the connection, all sessions managed by the connection, and all senders and receivers managed by each session.</para> + </callout> + </calloutlist> + </example> + + + </section> + + <section> + <title>A Simple Messaging Program in Python</title> + + <para>The following Python program shows how to create a + connection, create a session, send messages using a sender, and + receive messages using a receiver.</para> + + <example> + <title>"Hello world!" in Python</title> + <programlisting lang="python"><![CDATA[ + import sys + from qpid.messaging import * + + broker = "localhost:5672" if len(sys.argv)<2 else sys.argv[1] + address = "amq.topic" if len(sys.argv)<3 else sys.argv[2]]]> + + connection = Connection(broker) + + try: + connection.open() <co id="hello-python-open" linkends="callout-python-open"/> + session = connection.session() <co id="hello-python-session" linkends="callout-python-session"/> + + sender = session.sender(address) <co id="hello-python-sender" linkends="callout-python-sender"/> + receiver = session.receiver(address) <co id="hello-python-receiver" linkends="callout-python-receiver"/> + + sender.send(Message("Hello world!")); + + message = receiver.fetch(timeout=1) <co id="hello-python-fetch" linkends="callout-python-fetch"/> + print message.content + session.acknowledge() <co id="hello-python-acknowledge" linkends="callout-python-acknowledge"/> + + except MessagingError,m: + print m + finally: + connection.close() <co id="hello-python-close" linkends="callout-python-close"/> + </programlisting> + + <calloutlist> + <callout id="callout-python-open" arearefs="hello-python-open"> + <para>Establishes the connection with the messaging broker.</para> + </callout> + <callout id="callout-python-session" arearefs="hello-python-session"> + <para>Creates a session object on which messages will be sent and received.</para> + </callout> + <callout id="callout-python-receiver" arearefs="hello-python-receiver"> + <para>Creates a receiver that receives messages from the given address.</para> + </callout> + <callout id="callout-python-sender" arearefs="hello-python-sender"> + <para>Creates a sender that sends to the given address.</para> + </callout> + <callout id="callout-python-fetch" arearefs="hello-python-fetch"> + <para>Receives the next message. The duration is optional, if omitted, will wait indefinitely for the next message.</para> + </callout> + <callout id="callout-python-acknowledge" arearefs="hello-python-acknowledge"> + <para>Acknowledges receipt of all fetched messages on + the session. This informs the broker that the messages were + transfered and processed by the client successfully.</para> + </callout> + <callout id="callout-python-close" arearefs="hello-python-close"> + <para>Closes the connection, all sessions managed by the connection, and all senders and receivers managed by each session.</para> + </callout> + </calloutlist> + + </example> + + </section> + + + + + <section> + <title>A Simple Messaging Program in .NET C#</title> + + <para>The following .NET C# + <footnote> + <para> + The .NET binding for the Qpid C++ Messaging API + applies to all .NET Framework managed code languages. C# was chosen + for illustration purposes only. + </para> + </footnote> + program shows how to create a connection, + create a session, send messages using a sender, and receive + messages using a receiver. + </para> + + <example> + <title>"Hello world!" in .NET C#</title> + <programlisting lang="c++"> + using System; + using Org.Apache.Qpid.Messaging; <co id="hello-csharp-using" linkends="callout-csharp-using"/> + + namespace Org.Apache.Qpid.Messaging { + class Program { + static void Main(string[] args) { + String broker = args.Length > 0 ? args[0] : "localhost:5672"; + String address = args.Length > 1 ? args[1] : "amq.topic"; + + Connection connection = null; + try { + connection = new Connection(broker); + connection.Open(); <co id="hello-csharp-open" linkends="callout-csharp-open"/> + Session session = connection.CreateSession(); <co id="hello-csharp-session" linkends="callout-csharp-session"/> + + Receiver receiver = session.CreateReceiver(address); <co id="hello-csharp-receiver" linkends="callout-csharp-receiver"/> + Sender sender = session.CreateSender(address); <co id="hello-csharp-sender" linkends="callout-csharp-sender"/> + + sender.Send(new Message("Hello world!")); + + Message message = new Message(); + message = receiver.Fetch(DurationConstants.SECOND * 1); <co id="hello-csharp-fetch" linkends="callout-csharp-fetch"/> + Console.WriteLine("{0}", message.GetContent()); + session.Acknowledge(); <co id="hello-csharp-acknowledge" linkends="callout-csharp-acknowledge"/> + + connection.Close(); <co id="hello-csharp-close" linkends="callout-csharp-close"/> + } catch (Exception e) { + Console.WriteLine("Exception {0}.", e); + if (null != connection) + connection.Close(); + } + } + } + } + + </programlisting> + + <calloutlist> + <callout id="callout-csharp-using" arearefs="hello-csharp-using"> + <para> Permits use of Org.Apache.Qpid.Messaging types and methods without explicit namespace qualification. Any .NET project must have a project reference to the assembly file <literal>Org.Apache.Qpid.Messaging.dll</literal> in order to obtain the definitions of the .NET Binding for Qpid Messaging namespace.</para> + </callout> + <callout id="callout-csharp-open" arearefs="hello-csharp-open"> + <para>Establishes the connection with the messaging broker.</para> + </callout> + <callout id="callout-csharp-session" arearefs="hello-csharp-session"> + <para>Creates a session object on which messages will be sent and received.</para> + </callout> + <callout id="callout-csharp-receiver" arearefs="hello-csharp-receiver"> + <para>Creates a receiver that receives messages from the given address.</para> + </callout> + <callout id="callout-csharp-sender" arearefs="hello-csharp-sender"> + <para>Creates a sender that sends to the given address.</para> + </callout> + <callout id="callout-csharp-fetch" arearefs="hello-csharp-fetch"> + <para>Receives the next message. The duration is optional, if omitted, will wait indefinitely for the next message.</para> + </callout> + <callout id="callout-csharp-acknowledge" arearefs="hello-csharp-acknowledge"> + <para>Acknowledges receipt of all fetched messages on the + session. This informs the broker that the messages were + transfered and processed by the client successfully.</para> + </callout> + <callout id="callout-csharp-close" arearefs="hello-csharp-close"> + <para>Closes the connection, all sessions managed by the connection, and all senders and receivers managed by each session.</para> + </callout> + </calloutlist> + </example> + + + </section> + + + + + + + <section id="section-addresses"> + <title>Addresses</title> + + <para>An <firstterm>address</firstterm> is the name of a message + target or message source. + + <footnote><para>In the programs we have just seen, we used + <literal>amq.topic</literal> as the default address if none is + passed in. This is the name of a standard exchange that always + exists on an AMQP 0-10 messaging broker.</para></footnote> + + The methods that create senders and receivers require an + address. The details of sending to a particular target or + receiving from a particular source are then handled by the + sender or receiver. A different target or source can be used + simply by using a different address. + </para> + + <para>An address resolves to a <firstterm>node</firstterm>. The + Qpid Messaging API recognises two kinds of nodes, + <firstterm>queues</firstterm> and <firstterm>topics</firstterm> + + <footnote><para>The terms <emphasis>queue</emphasis> and + <emphasis>topic</emphasis> here were chosen to align with + their meaning in JMS. These two addressing 'patterns', + queue and topic, are sometimes refered as point-to-point + and publish-subscribe. AMQP 0-10 has an exchange type + called a <emphasis>topic exchange</emphasis>. When the term + <emphasis>topic</emphasis> occurs alone, it refers to a + Messaging API topic, not the topic + exchange.</para></footnote>. + + A queue stores each message until it has been received and + acknowledged, and only one receiver can receive a given message + + <footnote><para>There are exceptions to this rule; for instance, + a receiver can use <literal>browse</literal> mode, which leaves + messages on the queue for other receivers to + read.</para></footnote>. + + A topic immediately delivers a message to all eligible + receivers; if there are no eligible receivers, it discards the + message. In the AMQP 0-10 implementation of the API, + + <footnote><para>The AMQP 0-10 implementation is the only one + that currently exists.</para></footnote> + + queues map to AMQP queues, and topics map to AMQP exchanges. + + <footnote><para>In AMQP 0-10, messages are sent to + exchanges, and read from queues. The Messaging API also + allows a sender to send messages to a queue; internally, + Qpid implements this by sending the message to the default + exchange, with the name of the queue as the routing key. The + Messaging API also allows a receiver to receive messages + from a topic; internally, Qpid implements this by setting up + a private subscription queue for the receiver and binding + the subscription queue to the exchange that corresponds to + the topic.</para></footnote> + </para> + + <para>In the rest of this tutorial, we present many examples + using two programs that take an address as a command line + parameter. <command>spout</command> sends messages to the + target address, <command>drain</command> receives messages from + the source address. The source code is available in C++, Python, and + .NET C# and can be found in the examples directory for each + language. These programs can use any address string as a source + or a destination, and have many command line options to + configure behavior—use the <command>-h</command> option + for documentation on these options. + + <footnote><para>Currently, the C++, Python, and .NET C# + implementations of <command>drain</command> and + <command>spout</command> have slightly different + options. This tutorial uses the C++ implementation. The + options will be reconciled in the near + future.</para></footnote> + + + The examples in this tutorial also use the + <command>qpid-config</command> utility to configure AMQP 0-10 + queues and exchanges on a Qpid broker. + </para> + + + <example> + <title>Queues</title> + + <para>Create a queue with <command>qpid-config</command>, send a message using + <command>spout</command>, and read it using <command>drain</command>:</para> + + <screen> + $ qpid-config add queue hello-world + $ ./spout hello-world + $ ./drain hello-world + + Message(properties={spout-id:c877e622-d57b-4df2-bf3e-6014c68da0ea:0}, content='') + </screen> + + <para>The queue stored the message sent by <command>spout</command> and delivered + it to <command>drain</command> when requested.</para> + + <para>Once the message has been delivered and and acknowledged + by <command>drain</command>, it is no longer available on the queue. If we run + <command>drain</command> one more time, no messages will be retrieved.</para> + + <screen> + $ ./drain hello-world + $ + </screen> + + </example> + + <example> + <title>Topics</title> + + <para>This example is similar to the previous example, but it + uses a topic instead of a queue.</para> + + <para>First, use <command>qpid-config</command> to remove the queue + and create an exchange with the same name:</para> + + <screen> + $ qpid-config del queue hello-world + $ qpid-config add exchange topic hello-world + </screen> + + <para>Now run <command>drain</command> and <command>spout</command> the same way we did in the previous example:</para> + + <screen> + $ ./spout hello-world + $ ./drain hello-world + $ + </screen> + + <para>Topics deliver messages immediately to any interested + receiver, and do not store messages. Because there were no + receivers at the time <command>spout</command> sent the + message, it was simply discarded. When we ran + <command>drain</command>, there were no messages to + receive.</para> + + <para>Now let's run <command>drain</command> first, using the + <literal>-t</literal> option to specify a timeout in seconds. + While <command>drain</command> is waiting for messages, + run <command>spout</command> in another window.</para> + + <para><emphasis>First Window:</emphasis></para> + + <screen> + $ ./drain -t 30 hello-word + </screen> + + + <para><emphasis>Second Window:</emphasis></para> + + <screen> + $ ./spout hello-word + </screen> + + <para>Once <command>spout</command> has sent a message, return + to the first window to see the output from + <command>drain</command>:</para> + + <screen> + Message(properties={spout-id:7da2d27d-93e6-4803-8a61-536d87b8d93f:0}, content='') + </screen> + + <para>You can run <command>drain</command> in several separate + windows; each creates a subscription for the exchange, and + each receives all messages sent to the exchange.</para> + + </example> + + <section> + <title>Address Strings</title> + + <para>So far, our examples have used address strings that + contain only the name of a node. An <firstterm>address + string</firstterm> can also contain a + <firstterm>subject</firstterm> and + <firstterm>options</firstterm>.</para> + + <para>The syntax for an address string is:</para> + + <programlisting><![CDATA[ + address_string ::= <address> [ / <subject> ] [ ; <options> ] + options ::= { <key> : <value>, ... } + ]]></programlisting> + + <para>Addresses, subjects, and keys are strings. Values can + be numbers, strings (with optional single or double quotes), + maps, or lists. A complete BNF for address strings appears in + <xref linkend="section-address-string-bnf"/>.</para> + + + <para>So far, the address strings in this tutorial have only + used simple names. The following sections show how to use + subjects and options.</para> + + </section> + + <section> + <title>Subjects</title> + + + <para>Every message has a property called + <firstterm>subject</firstterm>, which is analogous to the + subject on an email message. If no subject is specified, the + message's subject is null. For convenience, address strings + also allow a subject. If a sender's address contains a + subject, it is used as the default subject for the messages + it sends. + + If a receiver's address contains a subject, it is used to + select only messages that match the subject—the matching + algorithm depends on the message source. + </para> + + <para> + In AMQP 0-10, each exchange type has its own matching + algorithm. This is discussed in + <xref linkend="section-amqp0-10-mapping"/>. + </para> + + <note> + <para> + Currently, a receiver bound to a queue ignores subjects, + receiving messages from the queue without filtering. Support + for subject filtering on queues will be implemented soon. + </para> + </note> + + + <example> + <title>Using subjects</title> + + <para>In this example we show how subjects affect message + flow.</para> + + <para>First, let's use <command>qpid-config</command> to create a topic exchange.</para> + + <screen> + $ qpid-config add exchange topic news-service + </screen> + + <para>Now we use drain to receive messages from <literal>news-service</literal> that match the subject <literal>sports</literal>.</para> + <para><emphasis>First Window:</emphasis></para> + <screen> + $ ./drain -t 30 news-service/sports + </screen> + + <para>In a second window, let's send messages to <literal>news-service</literal> using two different subjects:</para> + + <para><emphasis>Second Window:</emphasis></para> + <screen> + $ ./spout news-service/sports + $ ./spout news-service/news + </screen> + + <para>Now look at the first window, the message with the + subject <literal>sports</literal> has been received, but not + the message with the subject <literal>news</literal>:</para> + + <screen> + Message(properties={qpid.subject:sports, spout-id:9441674e-a157-4780-a78e-f7ccea998291:0}, content='') + </screen> + + <para>If you run <command>drain</command> in multiple + windows using the same subject, all instances of + <command>drain</command> receive the messages for that + subject.</para> + </example> + + + <para>The AMQP exchange type we are using here, + <literal>amq.topic</literal>, can also do more sophisticated + matching. + + A sender's subject can contain multiple words separated by a + <quote>.</quote> delimiter. For instance, in a news + application, the sender might use subjects like + <literal>usa.news</literal>, <literal>usa.weather</literal>, + <literal>europe.news</literal>, or + <literal>europe.weather</literal>. + + The receiver's subject can include wildcard characters— + <quote>#</quote> matches one or more words in the message's + subject, <quote>*</quote> matches a single word. + + For instance, if the subject in the source address is + <literal>*.news</literal>, it matches messages with the + subject <literal>europe.news</literal> or + <literal>usa.news</literal>; if it is + <literal>europe.#</literal>, it matches messages with subjects + like <literal>europe.news</literal> or + <literal>europe.pseudo.news</literal>.</para> + + <example> + <title>Subjects with multi-word keys</title> + + <para>This example uses drain and spout to demonstrate the + use of subjects with two-word keys.</para> + + <para>Let's use <command>drain</command> with the subject + <literal>*.news</literal> to listen for messages in which + the second word of the key is + <literal>news</literal>.</para> + + <para><emphasis>First Window:</emphasis></para> + + <screen> + $ ./drain -t 30 news-service/*.news + </screen> + + <para>Now let's send messages using several different + two-word keys:</para> + + <para><emphasis>Second Window:</emphasis></para> + + <screen> + $ ./spout news-service/usa.news + $ ./spout news-service/usa.sports + $ ./spout news-service/europe.sports + $ ./spout news-service/europe.news + </screen> + + <para>In the first window, the messages with + <literal>news</literal> in the second word of the key have + been received:</para> + + <screen> + Message(properties={qpid.subject:usa.news, spout-id:73fc8058-5af6-407c-9166-b49a9076097a:0}, content='') + Message(properties={qpid.subject:europe.news, spout-id:f72815aa-7be4-4944-99fd-c64c9747a876:0}, content='') + </screen> + + + <para>Next, let's use <command>drain</command> with the + subject <literal>#.news</literal> to match any sequence of + words that ends with <literal>news</literal>.</para> + + <para><emphasis>First Window:</emphasis></para> + + <screen> + $ ./drain -t 30 news-service/#.news + </screen> + + <para>In the second window, let's send messages using a + variety of different multi-word keys:</para> + + <para><emphasis>Second Window:</emphasis></para> + + <screen> + $ ./spout news-service/news + $ ./spout news-service/sports + $ ./spout news-service/usa.news + $ ./spout news-service/usa.sports + $ ./spout news-service/usa.faux.news + $ ./spout news-service/usa.faux.sports + </screen> + + <para>In the first window, messages with + <literal>news</literal> in the last word of the key have been + received:</para> + + <screen> + Message(properties={qpid.subject:news, spout-id:cbd42b0f-c87b-4088-8206-26d7627c9640:0}, content='') + Message(properties={qpid.subject:usa.news, spout-id:234a78d7-daeb-4826-90e1-1c6540781eac:0}, content='') + Message(properties={qpid.subject:usa.faux.news, spout-id:6029430a-cfcb-4700-8e9b-cbe4a81fca5f:0}, content='') + </screen> + </example> + + </section> + + <section> + <title>Address String Options</title> + + <para> + The options in an address string can contain additional + information for the senders or receivers created for it, + including: + </para> + <itemizedlist> + <listitem> + <para> + Policies for assertions about the node to which an address + refers. + </para> + <para> + For instance, in the address string <literal>my-queue; + {assert: always, node:{ type: queue }}</literal>, the node + named <literal>my-queue</literal> must be a queue; if not, + the address does not resolve to a node, and an exception + is raised. + </para> + </listitem> + <listitem> + <para> + Policies for automatically creating or deleting the node to which an address refers. + </para> + <para> + For instance, in the address string <literal>xoxox ; {create: always}</literal>, + the queue <literal>xoxox</literal> is created, if it does + not exist, before the address is resolved. + </para> + </listitem> + <listitem> + <para> + Extension points that can be used for sender/receiver configuration. + </para> + <para> + For instance, if the address for a receiver is + <literal>my-queue; {mode: browse}</literal>, the receiver + works in <literal>browse</literal> mode, leaving messages + on the queue so other receivers can receive them. + </para> + </listitem> + <listitem> + <para> + Extension points providing more direct control over the underlying protocol. + </para> + <para> + For instance, the <literal>x-bindings</literal> property + allows greater control over the AMQP 0-10 binding process + when an address is resolved. + </para> + </listitem> + </itemizedlist> + + + <para> + Let's use some examples to show how these different kinds of + address string options affect the behavior of senders and + receives. + </para> + + <section> + <title>assert</title> + <para> + In this section, we use the <literal>assert</literal> option + to ensure that the address resolves to a node of the required + type. + </para> + + + <example> + <title>Assertions on Nodes</title> + + <para>Let's use <command>qpid-config</command> to create a + queue and a topic.</para> + + <screen> + $ qpid-config add queue my-queue + $ qpid-config add exchange topic my-topic + </screen> + + <para> + We can now use the address specified to drain to assert that it is + of a particular type: + </para> + + <screen> + $ ./drain 'my-queue; {assert: always, node:{ type: queue }}' + $ ./drain 'my-queue; {assert: always, node:{ type: topic }}' + 2010-04-20 17:30:46 warning Exception received from broker: not-found: not-found: Exchange not found: my-queue (../../src/qpid/broker/ExchangeRegistry.cpp:92) [caused by 2 \x07:\x01] + Exchange my-queue does not exist + </screen> + + <para> + The first attempt passed without error as my-queue is indeed a + queue. The second attempt however failed; my-queue is not a + topic. + </para> + + <para> + We can do the same thing for my-topic: + </para> + + <screen> + $ ./drain 'my-topic; {assert: always, node:{ type: topic }}' + $ ./drain 'my-topic; {assert: always, node:{ type: queue }}' + 2010-04-20 17:31:01 warning Exception received from broker: not-found: not-found: Queue not found: my-topic (../../src/qpid/broker/SessionAdapter.cpp:754) [caused by 1 \x08:\x01] + Queue my-topic does not exist + </screen> + </example> + + <para>Now let's use the <literal>create</literal> option to + create the queue <literal>xoxox</literal> if it does not already + exist:</para> + + </section> + + <section> + <title>create</title> + + <para>In previous examples, we created the queue before + listening for messages on it. Using <literal>create: + always</literal>, the queue is automatically created if it + does not exist.</para> + + <example> + <title>Creating a Queue Automatically</title> + + <para><emphasis>First Window:</emphasis></para> + <screen>$ ./drain -t 30 "xoxox ; {create: always}"</screen> + + + <para>Now we can send messages to this queue:</para> + + <para><emphasis>Second Window:</emphasis></para> + <screen>$ ./spout "xoxox ; {create: always}"</screen> + + <para>Returning to the first window, we see that <command>drain</command> has received this message:</para> + + <screen>Message(properties={spout-id:1a1a3842-1a8b-4f88-8940-b4096e615a7d:0}, content='')</screen> + </example> + <para>The details of the node thus created can be controlled by further options within the node. See <xref linkend="table-node-properties"/> for details.</para> + </section> + + <section> + <title>browse</title> + <para>Some options specify message transfer semantics; for + instance, they may state whether messages should be consumed or + read in browsing mode, or specify reliability + characteristics. The following example uses the + <literal>browse</literal> option to receive messages without + removing them from a queue.</para> + + <example> + <title>Browsing a Queue</title> + <para> + Let's use the browse mode to receive messages without + removing them from the queue. First we send three messages to the + queue: + </para> + <screen> + $ ./spout my-queue --content one + $ ./spout my-queue --content two + $ ./spout my-queue --content three + </screen> + + <para>Now we use drain to get those messages, using the browse option:</para> + <screen> + $ ./drain 'my-queue; {mode: browse}' + Message(properties={spout-id:fbb93f30-0e82-4b6d-8c1d-be60eb132530:0}, content='one') + Message(properties={spout-id:ab9e7c31-19b0-4455-8976-34abe83edc5f:0}, content='two') + Message(properties={spout-id:ea75d64d-ea37-47f9-96a9-d38e01c97925:0}, content='three') + </screen> + + <para>We can confirm the messages are still on the queue by repeating the drain:</para> + <screen> + $ ./drain 'my-queue; {mode: browse}' + Message(properties={spout-id:fbb93f30-0e82-4b6d-8c1d-be60eb132530:0}, content='one') + Message(properties={spout-id:ab9e7c31-19b0-4455-8976-34abe83edc5f:0}, content='two') + Message(properties={spout-id:ea75d64d-ea37-47f9-96a9-d38e01c97925:0}, content='three') + </screen> + </example> + </section> + + <section> + <title>x-bindings</title> + + <para>Greater control over the AMQP 0-10 binding process can + be achieved by including an <literal>x-bindings</literal> + option in an address string. + + For instance, the XML Exchange is an AMQP 0-10 custom exchange + provided by the Apache Qpid C++ broker. It allows messages to + be filtered using XQuery; queries can address either message + properties or XML content in the body of the message. The + xquery is specified in the arguments field of the AMQP 0-10 + command. When using the messaging API an xquery can be + specified in and address that resolves to an XML exchange by + using the x-bindings property.</para> + + + <para>An instance of the XML Exchange must be added before it + can be used:</para> + + <programlisting> + $ qpid-config add exchange xml xml + </programlisting> + + <para>When using the XML Exchange, a receiver provides an + XQuery as an x-binding argument. If the query contains a + context item (a path starting with <quote>.</quote>), then it + is applied to the content of the message, which must be + well-formed XML. For instance, <literal>./weather</literal> is + a valid XQuery, which matches any message in which the root + element is named <literal>weather</literal>. Here is an + address string that contains this query:</para> + + <programlisting><![CDATA[ + xml; { + link: { + x-bindings: [{exchange:xml, key:weather, arguments:{xquery:"./weather"} }] + } + } + ]]></programlisting> + + <para>When using longer queries with <command>drain</command>, + it is often useful to place the query in a file, and use + <command>cat</command> in the command line. We do this in the + following example.</para> + + <example> + <title>Using the XML Exchange</title> + + <para>This example uses an x-binding that contains queries, which filter based on the content of XML messages. Here is an XQuery that we will use in this example:</para> + + <programlisting> + <![CDATA[ + let $w := ./weather + return $w/station = 'Raleigh-Durham International Airport (KRDU)' + and $w/temperature_f > 50 + and $w/temperature_f - $w/dewpoint > 5 + and $w/wind_speed_mph > 7 + and $w/wind_speed_mph < 20 ]]> + </programlisting> + + <para>We can specify this query in an x-binding to listen to messages that meet the criteria specified by the query:</para> + + <para><emphasis>First Window:</emphasis></para> + + <screen> + $ ./drain -f "xml; {link:{x-bindings:[{key:'weather', + arguments:{xquery:\"$(cat rdu.xquery )\"}}]}}" + </screen> + + <para>In another window, let's create an XML message that meets the criteria in the query, and place it in the file <filename>rdu.xml</filename>:</para> + + <programlisting> + <![CDATA[ + <weather> + <station>Raleigh-Durham International Airport (KRDU)</station> + <wind_speed_mph>16</wind_speed_mph> + <temperature_f>70</temperature_f> + <dewpoint>35</dewpoint> + </weather> + ]]></programlisting> + + <para>Now let's use <command>spout</command> to send this message to the XML exchange:</para> + + <para><emphasis>Second Window:</emphasis></para> + <screen> + spout --content "$(cat rdu.xml)" xml/weather + </screen> + + <para>Returning to the first window, we see that the message has been received:</para> + + <screen><![CDATA[$ ./drain -f "xml; {link:{x-bindings:[{exchange:'xml', key:'weather', arguments:{xquery:\"$(cat rdu.xquery )\"}}]}}" + Message(properties={qpid.subject:weather, spout-id:31c431de-593f-4bec-a3dd-29717bd945d3:0}, + content='<weather> + <station>Raleigh-Durham International Airport (KRDU)</station> + <wind_speed_mph>16</wind_speed_mph> + <temperature_f>40</temperature_f> + <dewpoint>35</dewpoint> + </weather>') ]]> + </screen> + </example> + </section> + + <!-- + <para>When sending data using <command>cat</command> to provide arguments to <command>spout</command>, you can use <command>sed</command> to change the values that are sent:</para> + +<screen> +spout - -content "$(cat rdu.xml | sed -e 's/70/45/')" xml/weather +</screen> + --> + + <!-- + TODO: Add some reliability option examples + --> + + <section> + <title>Address String Options - Reference</title> + + <table pgwide="1"> + <title>Address String Options</title> + <tgroup cols="3"> + <thead> + <colspec colnum="1" colwidth="1*"/> + <colspec colnum="2" colwidth="3*"/> + <colspec colnum="3" colwidth="3*"/> + <row> + <entry>option</entry> + <entry>value</entry> + <entry>semantics</entry> + </row> + </thead> + <tbody> + <row> + <entry> + assert + </entry> + <entry> + one of: always, never, sender or receiver + </entry> + <entry> + Asserts that the properties specified in the node option + match whatever the address resolves to. If they do not, + resolution fails and an exception is raised. <!-- ### + Which exception --> + </entry> + </row> + + <row> + <entry> + create + </entry> + <entry> + one of: always, never, sender or receiver + </entry> + <entry> + Creates the node to which an address refers if it does + not exist. No error is raised if the node does + exist. The details of the node may be specified in the + node option. + </entry> + </row> + <row> + <entry> + delete + </entry> + <entry> + one of: always, never, sender or receiver + </entry> + <entry> + Delete the node when the sender or receiver is closed. + </entry> + </row> + <row> + <entry> + node + </entry> + <entry> + A nested map containing the entries shown in <xref linkend="table-node-properties"/>. + </entry> + <entry> + Specifies properties of the node to which the address + refers. These are used in conjunction with the assert or + create options. + </entry> + </row> + <row> + <entry> + link + </entry> + <entry> + A nested map containing the entries shown in <xref linkend="table-link-properties"/>. + </entry> + <entry> + Used to control the establishment of a conceptual link + from the client application to or from the target/source + address. + </entry> + </row> + <row> + <entry> + mode + </entry> + <entry> + one of: browse, consume + </entry> + <entry> + This option is only of relevance for source addresses + that resolve to a queue. If browse is specified the + messages delivered to the receiver are left on the queue + rather than being removed. If consume is specified the + normal behaviour applies; messages are removed from the + queue once the client acknowledges their receipt. + </entry> + </row> + </tbody> + </tgroup> + </table> + + + <table id="table-node-properties" pgwide="1"> + <title>Node Properties</title> + <tgroup cols="3"> + <thead> + <colspec colnum="1" colwidth="1*"/> + <colspec colnum="2" colwidth="3*"/> + <colspec colnum="3" colwidth="3*"/> + <row> + <entry>property</entry> + <entry>value</entry> + <entry>semantics</entry> + </row> + </thead> + <tbody> + <row> + <entry> + type + </entry> + <entry> + topic, queue + </entry> + <entry> + Indicates the type of the node. + </entry> + </row> + <row> + <entry> + durable + </entry> + <entry> + True, False + </entry> + <entry> + Indicates whether the node survives a loss of + volatile storage e.g. if the broker is restarted. + </entry> + </row> + <row> + <entry> + x-declare + </entry> + <entry> + A nested map whose values correspond to the valid fields + on an AMQP 0-10 queue-declare or exchange-declare + command. + </entry> + <entry> + These values are used to fine tune the creation or + assertion process. Note however that they are protocol + specific. + </entry> + </row> + <row> + <entry> + x-bindings + </entry> + <entry> + A nested list in which each binding is represented by + a map. The entries of the map for a binding contain + the fields that describe an AMQP 0-10 binding. Here is + the format for x-bindings: + + <programlisting><![CDATA[ + [ + { + exchange: <exchange>, + queue: <queue>, + key: <key>, + arguments: { + <key_1>: <value_1>, + ..., + <key_n>: <value_n> } + }, + ... + ] + ]]></programlisting> + </entry> + <entry> + In conjunction with the create option, each of these + bindings is established as the address is resolved. In + conjunction with the assert option, the existence of + each of these bindings is verified during + resolution. Again, these are protocol specific. + </entry> + </row> + </tbody> + </tgroup> + </table> + + <table id="table-link-properties" pgwide="1"> + <title>Link Properties</title> + <tgroup cols="3"> + <thead> + <colspec colnum="1" colwidth="1*"/> + <colspec colnum="2" colwidth="3*"/> + <colspec colnum="3" colwidth="3*"/> + <row> + <entry>option</entry> + <entry>value</entry> + <entry>semantics</entry> + </row> + </thead> + <tbody> + <row> + <entry> + reliability + </entry> + <entry> + one of: unreliable, at-least-once, at-most-once, exactly-once + </entry> + <entry> + Reliability indicates the level of reliability that + the sender or receiver. <literal>unreliable</literal> + and <literal>at-most-once</literal> are currently + treated as synonyms, and allow messages to be lost if + a broker crashes or the connection to a broker is + lost. <literal>at-least-once</literal> guarantees that + a message is not lost, but duplicates may be + received. <literal>exactly-once</literal> guarantees + that a message is not lost, and is delivered precisely + once. Currently only <literal>unreliable</literal> + and <literal>at-least-once</literal> are supported. + <footnote><para>If at-most-once is requested, + unreliable will be used and for durable messages on + durable queues there is the possibility that messages + will be redelivered; if exactly-once is requested, + at-least-once will be used and the application needs to + be able to deal with duplicates.</para></footnote> + </entry> + </row> + <row> + <entry> + durable + </entry> + <entry> + True, False + </entry> + <entry> + Indicates whether the link survives a loss of + volatile storage e.g. if the broker is restarted. + </entry> + </row> + <row> + <entry> + x-declare + </entry> + <entry> + A nested map whose values correspond to the valid fields + of an AMQP 0-10 queue-declare command. + </entry> + <entry> + These values can be used to customise the subscription + queue in the case of receiving from an exchange. Note + however that they are protocol specific. + </entry> + </row> + <row> + <entry> + x-subscribe + </entry> + <entry> + A nested map whose values correspond to the valid fields + of an AMQP 0-10 message-subscribe command. + </entry> + <entry> + These values can be used to customise the subscription. + </entry> + </row> + <row> + <entry> + x-bindings + </entry> + <entry> + A nested list each of whose entries is a map that may + contain fields (queue, exchange, key and arguments) + describing an AMQP 0-10 binding. + </entry> + <entry> + These bindings are established during resolution + independent of the create option. They are considered + logically part of the linking process rather than of + node creation. + </entry> + </row> + </tbody> + </tgroup> + </table> + + </section> + </section> + + <section id="section-address-string-bnf"> + <title>Address String Grammar</title> + + <para>This section provides a formal grammar for address strings.</para> + + <formalpara> + <title>Tokens</title> + <para>The following regular expressions define the tokens used + to parse address strings:</para></formalpara> + <programlisting><![CDATA[ + LBRACE: \\{ + RBRACE: \\} + LBRACK: \\[ + RBRACK: \\] + COLON: : + SEMI: ; + SLASH: / + COMMA: , + NUMBER: [+-]?[0-9]*\\.?[0-9]+ + ID: [a-zA-Z_](?:[a-zA-Z0-9_-]*[a-zA-Z0-9_])? + STRING: "(?:[^\\\\"]|\\\\.)*"|\'(?:[^\\\\\']|\\\\.)*\' + ESC: \\\\[^ux]|\\\\x[0-9a-fA-F][0-9a-fA-F]|\\\\u[0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F] + SYM: [.#*%@$^!+-] + WSPACE: [ \\n\\r\\t]+ + ]]></programlisting> + + <formalpara> + <title>Grammar</title> + <para>The formal grammar for addresses is given below:</para> + </formalpara> + + <programlisting><![CDATA[ + address := name [ SLASH subject ] [ ";" options ] + name := ( part | quoted )+ + subject := ( part | quoted | SLASH )* + quoted := STRING / ESC + part := LBRACE / RBRACE / COLON / COMMA / NUMBER / ID / SYM + options := map + map := "{" ( keyval ( "," keyval )* )? "}" + keyval "= ID ":" value + value := NUMBER / STRING / ID / map / list + list := "[" ( value ( "," value )* )? "]" + ]]></programlisting> + + + <formalpara> + <title>Address String Options</title> + <para>The address string options map supports the following parameters:</para> + </formalpara> + + <programlisting><![CDATA[ + <name> [ / <subject> ] ; { + create: always | sender | receiver | never, + delete: always | sender | receiver | never, + assert: always | sender | receiver | never, + mode: browse | consume, + node: { + type: queue | topic, + durable: True | False, + x-declare: { ... <declare-overrides> ... }, + x-bindings: [<binding_1>, ... <binding_n>] + }, + link: { + name: <link-name>, + durable: True | False, + reliability: unreliable | at-most-once | at-least-once | exactly-once, + x-declare: { ... <declare-overrides> ... }, + x-bindings: [<binding_1>, ... <binding_n>], + x-subscribe: { ... <subscribe-overrides> ... } + } + } + ]]></programlisting> + + + <itemizedlist> + <title>Create, Delete, and Assert Policies</title> + <para>The create, delete, and assert policies specify who should + perfom the associated action:</para> + <listitem><para><emphasis>always</emphasis>: the action is performed by any messaging client</para></listitem> + <listitem><para><emphasis>sender</emphasis>: the action is only performed by a sender</para></listitem> + <listitem><para><emphasis>receiver</emphasis>: the action is only performed by a receiver</para></listitem> + <listitem><para><emphasis>never</emphasis>: the action is never performed (this is the default)</para></listitem> + </itemizedlist> + + <itemizedlist> + <title>Node-Type</title> + <para>The node-type is one of:</para> + <listitem><para><emphasis>topic</emphasis>: in the AMQP 0-10 + mapping, a topic node defaults to the topic exchange, x-declare + may be used to specify other exchange types</para></listitem> + <listitem><para><emphasis>queue</emphasis>: this is the default node-type</para></listitem> + </itemizedlist> + </section> + + + </section> + + <section id="replay"> + <title>Sender Capacity and Replay</title> + + <para>The send method of a sender has an optional second parameter + that controls whether the send call is synchronous or not. A + synchronous send call will block until the broker has confirmed + receipt of the message. An asynchronous send call will return + before the broker confirms receipt of the message, allowing for + example further send calls to be made without waiting for a + roundtrip to the broker for each message. This is desirable where + increased throughput is important.</para> + + <para>The sender maintains a list of sent messages whose receipt + has yet to be confirmed by the broker. The maximum number of such + messages that it will hold is defined by the capacity of the + sender, which can be set by the application. If an application + tries to send with a sender whose capacity is already fully used + up, the send call will block waiting for capacity regardless of + the value of the sync flag.</para> + + <para>The sender can be queried for the available space (i.e. the + unused capacity), and for the current count of unsettled messages + (i.e. those held in the replay list pending confirmation by the + server). When the unsettled count is zero, all messages on that + sender have been successfully sent.</para> + + <para>If the connection fails and is transparently reconnected + (see <xref linkend="connection-options"/> for details on how to control + this feature), the unsettled messages for each sender over that + connection will be re-transmitted. This provides a transparent + level of reliability. This feature can be controlled through the + link's reliability as defined in the address (see + <xref linkend="table-link-properties"/>). At present only + at-least-once guarantees are offered. </para> + </section> + + <section id="prefetch"> + <title>Receiver Capacity (Prefetch)</title> + + <para>By default, a receiver requests the next message from the + server in response to each fetch call, resulting in messages being + sent to the receiver one at a time. As in the case of sending, it + is often desirable to avoid this roundtrip for each message. This + can be achieved by allowing the receiver + to <firstterm>prefetch</firstterm> messages in anticipation of + fetch calls being made. The receiver needs to be able to store + these prefetched messages, the number it can hold is controlled by + the receivers capacity.</para> + + </section> + + <section id="acknowledgements"> + <title>Acknowledging Received Messages</title> + + <para>Applications that receive messages should acknowledge their + receipt by calling the session's acknowledge method. As in the + case of sending messages, acknowledged transfer of messages to + receivers provides at-least-once reliability, which means that the + loss of the connection or a client crash does not result in lost + messages; durable messages are not lost even if the broker is + restarted. + + Some cases may not require this however and the reliability can be + controlled through a link property in the address options (see + <xref linkend="table-link-properties"/>).</para> + + <para>The acknowledge call acknowledges all messages received on + the session (i.e. all message that have been returned from a fetch + call on a receiver created on that session).</para> + + <para>The acknowledge call also support an optional parameter + controlling whether the call is synchronous or not. A synchronous + acknowledge will block until the server has confirmed that it has + received the acknowledgement. In the asynchronous case, when the + call returns there is not yet any guarantee that the server has + received and processed the acknowledgement. The session may be + queried for the number of unsettled acknowledgements; when that + count is zero all acknowledgements made for received messages have + been successful.</para> + + </section> + + + <section> + <title>Receiving Messages from Multiple Sources</title> + + <para>A receiver can only read from one source, but many + programs need to be able to read messages from many sources. In + the Qpid Messaging API, a program can ask a session for + the <quote>next receiver</quote>; that is, the receiver that is + responsible for the next available message. The following + examples show how this is done in C++, Python, and .NET C#. + </para> + + <para>Note that to use this pattern you must enable prefetching + for each receiver of interest so that the broker will send + messages before a fetch call is made. See + <xref linkend="prefetch"/> for more on this.</para> + + <example> + <title>Receiving Messages from Multiple Sources</title> + + <para>C++:</para> + + <programlisting><![CDATA[ + Receiver receiver1 = session.createReceiver(address1); + receiver1.setCapacity(10); + Receiver receiver2 = session.createReceiver(address2); + receiver2.setCapacity(10); + + Message message = session.nextReceiver().fetch(); + std::cout << message.getContent() << std::endl; + session.acknowledge(); // acknowledge message receipt + ]]> </programlisting> + + <para>Python:</para> + <programlisting><![CDATA[ + receiver1 = session.receiver(address1) + receiver1.capacity = 10 + receiver2 = session.receiver(address) + receiver2.capacity = 10 + message = session.next_receiver().fetch() + print message.content + session.acknowledge() + ]]> </programlisting> + + <para>.NET C#:</para> + <programlisting><![CDATA[ + Receiver receiver1 = session.CreateReceiver(address1); + receiver1.Capacity = 10; + Receiver receiver2 = session.CreateReceiver(address2); + receiver2.Capacity = 10; + + Message message = new Message(); + message = session.NextReceiver().Fetch(); + Console.WriteLine("{0}", message.GetContent()); + session.Acknowledge(); + ]]> </programlisting> + + </example> + </section> + + <section> + <title>Transactions</title> + + <para>Sometimes it is useful to be able to group messages + transfers - sent and/or received - on a session into atomic + grouping. This can be done be creating the session as + transactional. On a transactional session sent messages only + become available at the target address on commit. Likewise any + received and acknowledged messages are only discarded at their + source on commit + + <footnote><para>Note that this currently is only true for + messages received using a reliable mode + e.g. at-least-once. Messages sent by a broker to a receiver in + unreliable receiver will be discarded immediately regardless of + transctionality.</para></footnote> + + .</para> + + <example> + <title>Transactions</title> + <para>C++:</para> + <programlisting><![CDATA[ + Connection connection(broker); + Session session = connection.createTransactionalSession(); + ... + if (smellsOk()) + session.commit(); + else + session.rollback(); + ]]></programlisting> + <para> + .NET C#: + </para> + + <programlisting> + Connection connection = new Connection(broker); + Session session = connection.CreateTransactionalSession(); + ... + if (smellsOk()) + session.Commit(); + else + session.Rollback(); + </programlisting> + <!-- + <para>Python</para> + <programlisting><![CDATA[ + ### TODO + ]]></programlisting> + --> + </example> + + </section> + + <section id="connections"> + <title>Connections</title> + + <para> + Messaging connections are created by specifying a broker or a list of brokers, and + an optional set of connection options. The constructor prototypes for Connections + are: + </para> + + <programlisting><![CDATA[ + Connection connection(); + Connection connection(const string url); + Connection connection(const string url, const string& options); + Connection connection(const string url, const Variant::Map& options); + ]]></programlisting> + + <para> + Messaging connection URLs specify only the network host address(es). Connection + options are specified separately as an options string or map. This is different + from JMS Connection URLs that combine the network address and connection properties + in a single string. + </para> + + <section id="connection-url"> + <title>Connection URLs</title> + <para> + Connection URLs describe the broker or set of brokers to which the connection + is to attach. The format of the Connection URL is defined by AMQP 0.10 + Domain:connection.amqp-host-url. + </para> + + <programlisting><![CDATA[ + amqp_url = "amqp:" prot_addr_list + prot_addr_list = [prot_addr ","]* prot_addr + prot_addr = tcp_prot_addr | tls_prot_addr + + tcp_prot_addr = tcp_id tcp_addr + tcp_id = "tcp:" | "" + tcp_addr = [host [":" port] ] + host = <as per http://www.ietf.org/rfc/rfc3986.txt> + port = number ]]></programlisting> + + <para> + Examples of Messaging Connection URLs + </para> + + <programlisting><![CDATA[ + localhost + localhost:5672 + localhost:9999 + 192.168.1.2:5672 + mybroker.example.com:5672 + amqp:tcp:localhost:5672 + tcp:locahost:5672,localhost:5800 + ]]></programlisting> + + </section> + + <section id="connection-options"> + <title>Connection Options</title> + + <para> + Aspects of the connections behaviour can be controlled through + specifying connection options. For example, connections can be + configured to automatically reconnect if the connection to a + broker is lost. + </para> + + <example> + <title>Specifying Connection Options in C++, Python, and .NET</title> + + <para>In C++, these options can be set using <function>Connection::setOption()</function> or by passing in a set of options to the constructor. The options can be passed in as a map or in string form:</para> + + + <para>or</para> + + <programlisting><![CDATA[ + Connection connection("localhost:5672"); + connection.setOption("reconnect", true); + try { + connection.open(); + !!! SNIP !!! + ]]></programlisting> + + <para>In Python, these options can be set as attributes of the connection or using named arguments in + the <function>Connection</function> constructor:</para> + + <programlisting><![CDATA[ + connection = Connection("localhost:5672", reconnect=True) + try: + connection.open() + !!! SNIP !!! + ]]></programlisting> + + <para>or</para> + + <programlisting><![CDATA[ + connection = Connection("localhost:5672") + connection.reconnect = True + try: + connection.open() + !!! SNIP !!! + ]]></programlisting> + <para> + In .NET, these options can be set using <function>Connection.SetOption()</function> or by passing in a set of options to the constructor. The options can be passed in as a map or in string form: + </para> + + <programlisting> + Connection connection= new Connection("localhost:5672", "{reconnect: true}"); + try { + connection.Open(); + !!! SNIP !!! + </programlisting> + <para> + or + </para> + + <programlisting> + Connection connection = new Connection("localhost:5672"); + connection.SetOption("reconnect", true); + try { + connection.Open(); + !!! SNIP !!! + </programlisting> + + <para>See the reference documentation for details in each language.</para> + </example> + + <para>The following table lists the supported connection options.</para> + + <table pgwide="1"> + <title>Connection Options</title> + <tgroup cols="3"> + <thead> + <colspec colnum="1" colwidth="1*"/> + <colspec colnum="2" colwidth="1*"/> + <colspec colnum="3" colwidth="3*"/> + <row> + <entry>option name</entry> + <entry>value type</entry> + <entry>semantics</entry> + </row> + </thead> + <tbody> + + <row> + <entry> + <literal>username</literal> + </entry> + <entry> + string + </entry> + <entry> + The username to use when authenticating to the broker. + </entry> + </row> + <row> + <entry> + <literal>password</literal> + </entry> + <entry> + string + </entry> + <entry> + The password to use when authenticating to the broker. + </entry> + </row> + <row> + <entry> + <literal>sasl_mechanisms</literal> + </entry> + <entry> + string + </entry> + <entry> + The specific SASL mechanisms to use with the python + client when authenticating to the broker. The value + is a space separated list. + </entry> + </row> + + + <row> + <entry> + <literal>reconnect</literal> + </entry> + <entry> + boolean + </entry> + <entry> + Transparently reconnect if the connection is lost. + </entry> + </row> + <row> + <entry> + <literal>reconnect_timeout</literal> + </entry> + <entry> + integer + </entry> + <entry> + Total number of seconds to continue reconnection attempts before giving up and raising an exception. + </entry> + </row> + <row> + <entry> + <literal>reconnect_limit</literal> + </entry> + <entry> + integer + </entry> + <entry> + Maximum number of reconnection attempts before giving up and raising an exception. + </entry> + </row> + <row> + <entry> + <literal>reconnect_interval_min</literal> + </entry> + <entry> + integer representing time in seconds + </entry> + <entry> + Minimum number of seconds between reconnection attempts. The first reconnection attempt is made immediately; if that fails, the first reconnection delay is set to the value of <literal>reconnect_interval_min</literal>; if that attempt fails, the reconnect interval increases exponentially until a reconnection attempt succeeds or <literal>reconnect_interval_max</literal> is reached. + </entry> + </row> + <row> + <entry> + <literal>reconnect_interval_max</literal> + </entry> + <entry> + integer representing time in seconds + </entry> + <entry> + Maximum reconnect interval. + </entry> + </row> + <row> + <entry> + <literal>reconnect_interval</literal> + </entry> + <entry> + integer representing time in seconds + </entry> + <entry> + Sets both <literal>reconnection_interval_min</literal> and <literal>reconnection_interval_max</literal> to the same value. + </entry> + </row> + + <row> + <entry> + <literal>heartbeat</literal> + </entry> + <entry> + integer representing time in seconds + </entry> + <entry> + Requests that heartbeats be sent every N seconds. If two + successive heartbeats are missed the connection is + considered to be lost. + </entry> + </row> + <row> + <entry> + <literal>transport</literal> + </entry> + <entry> + string + </entry> + <entry> + Sets the underlying transport protocol used. The default option is 'tcp'. To enable ssl, set to 'ssl'. The C++ client additionally supports 'rdma'. + </entry> + </row> + <row> + <entry> + <literal>tcp-nodelay</literal> + </entry> + <entry> + boolean + </entry> + <entry> + Set tcp no-delay, i.e. disable Nagle algorithm. [C++ only] + </entry> + </row> + <row> + <entry> + <literal>protocol</literal> + </entry> + <entry> + string + </entry> + <entry> + Sets the application protocol used. The default option is 'amqp0-10'. To enable AMQP 1.0, set to 'amqp1.0'. + </entry> + </row> + </tbody> + </tgroup> + </table> + + </section> + </section> + + <section id="section-Maps"> + <title>Maps and Lists in Message Content</title> + + <para>Many messaging applications need to exchange data across + languages and platforms, using the native datatypes of each + programming language.</para> + + <para>The Qpid Messaging API supports <classname>map</classname> and <classname>list</classname> in message content. + + <footnote><para>Unlike JMS, there is not a specific message type for + map messages.</para></footnote> + + <footnote> + <para> + Note that the Qpid JMS client supports MapMessages whose values can be nested maps or lists. This is not standard JMS behaviour. + </para> + </footnote> + Specific language support for <classname>map</classname> and <classname>list</classname> objects are shown in the following table. + </para> + <table id="tabl-Programming_in_Apache_Qpid-Qpid_Maps_in_Message_Content"> + <title>Map and List Representation in Supported Languages</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Language</entry> + <entry>map</entry> + <entry>list</entry> + </row> + </thead> + <tbody> + <row> + <entry>Python</entry> + <entry><classname>dict</classname></entry> + <entry><classname>list</classname></entry> + </row> + <row> + <entry>C++</entry> + <entry><classname>Variant::Map</classname></entry> + <entry><classname>Variant::List</classname></entry> + </row> + <row> + <entry>Java</entry> + <entry><classname>MapMessage</classname></entry> + <entry><classname> </classname></entry> + </row> + <row> + <entry>.NET</entry> + <entry><classname>Dictionary<string, object></classname></entry> + <entry><classname>Collection<object></classname></entry> + </row> + </tbody> + </tgroup> + </table> + <para> + In all languages, messages are encoded using AMQP's portable datatypes. + </para> + + <tip> + <para>Because of the differences in type systems among + languages, the simplest way to provide portable messages is to + rely on maps, lists, strings, 64 bit signed integers, and + doubles for messages that need to be exchanged across languages + and platforms.</para> + </tip> + + <section id="section-Python-Maps"> + <title>Qpid Maps and Lists in Python</title> + + <para>In Python, Qpid supports the <classname>dict</classname> and <classname>list</classname> types directly in message content. The following code shows how to send these structures in a message:</para> + + <example> + <title>Sending Qpid Maps and Lists in Python</title> + <programlisting><![CDATA[ + from qpid.messaging import * + # !!! SNIP !!! + + content = {'Id' : 987654321, 'name' : 'Widget', 'percent' : 0.99} + content['colours'] = ['red', 'green', 'white'] + content['dimensions'] = {'length' : 10.2, 'width' : 5.1,'depth' : 2.0}; + content['parts'] = [ [1,2,5], [8,2,5] ] + content['specs'] = {'colors' : content['colours'], + 'dimensions' : content['dimensions'], + 'parts' : content['parts'] } + message = Message(content=content) + sender.send(message) + ]]> </programlisting> + </example> + + + <para>The following table shows the datatypes that can be sent in a Python map message, + and the corresponding datatypes that will be received by clients in Java or C++.</para> + + + <table id="table-Python-Maps" > + <title>Python Datatypes in Maps</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Python Datatype</entry> + <entry>→ C++</entry> + <entry>→ Java</entry> + </row> + </thead> + <tbody> + <row><entry>bool</entry><entry>bool</entry><entry>boolean</entry></row> + <row><entry>int</entry><entry>int64</entry><entry>long</entry></row> + <row><entry>long</entry><entry>int64</entry><entry>long</entry></row> + <row><entry>float</entry><entry>double</entry><entry>double</entry></row> + <row><entry>unicode</entry><entry>string</entry><entry>java.lang.String</entry></row> + <row><entry>uuid</entry><entry>qpid::types::Uuid</entry><entry>java.util.UUID</entry></row> + <row><entry>dict</entry><entry>Variant::Map</entry><entry>java.util.Map</entry></row> + <row><entry>list</entry><entry>Variant::List</entry><entry>java.util.List</entry></row> + </tbody> + </tgroup> + </table> + + </section> + + + + + <section id="section-cpp-Maps"> + <title>Qpid Maps and Lists in C++</title> + + + <para>In C++, Qpid defines the the + <classname>Variant::Map</classname> and + <classname>Variant::List</classname> types, which can be + encoded into message content. The following code shows how to + send these structures in a message:</para> + + <example> + <title>Sending Qpid Maps and Lists in C++</title> + <programlisting><![CDATA[ + using namespace qpid::types; + + // !!! SNIP !!! + + Message message; + Variant::Map content; + content["id"] = 987654321; + content["name"] = "Widget"; + content["percent"] = 0.99; + Variant::List colours; + colours.push_back(Variant("red")); + colours.push_back(Variant("green")); + colours.push_back(Variant("white")); + content["colours"] = colours; + + Variant::Map dimensions; + dimensions["length"] = 10.2; + dimensions["width"] = 5.1; + dimensions["depth"] = 2.0; + content["dimensions"]= dimensions; + + Variant::List part1; + part1.push_back(Variant(1)); + part1.push_back(Variant(2)); + part1.push_back(Variant(5)); + + Variant::List part2; + part2.push_back(Variant(8)); + part2.push_back(Variant(2)); + part2.push_back(Variant(5)); + + Variant::List parts; + parts.push_back(part1); + parts.push_back(part2); + content["parts"]= parts; + + Variant::Map specs; + specs["colours"] = colours; + specs["dimensions"] = dimensions; + specs["parts"] = parts; + content["specs"] = specs; + + encode(content, message); + sender.send(message, true); + ]]> </programlisting> + </example> + + <para>The following table shows the datatypes that can be sent + in a C++ map message, and the corresponding datatypes that + will be received by clients in Java and Python.</para> + + <table id="table-cpp-Maps"> + <title>C++ Datatypes in Maps</title> + <tgroup cols="3"> + <thead> + <row> + <entry>C++ Datatype</entry> + <entry>→ Python</entry> + <entry>→ Java</entry> + </row> + </thead> + <tbody> + <row><entry>bool</entry><entry>bool</entry><entry>boolean</entry></row> + <row><entry>uint16</entry><entry>int | long</entry><entry>short</entry></row> + <row><entry>uint32</entry><entry>int | long</entry><entry>int</entry></row> + <row><entry>uint64</entry><entry>int | long</entry><entry>long</entry></row> + <row><entry>int16</entry><entry>int | long</entry><entry>short</entry></row> + <row><entry>int32</entry><entry>int | long</entry><entry>int</entry></row> + <row><entry>int64</entry><entry>int | long</entry><entry>long</entry></row> + <row><entry>float</entry><entry>float</entry><entry>float</entry></row> + <row><entry>double</entry><entry>float</entry><entry>double</entry></row> + <row><entry>string</entry><entry>unicode</entry><entry>java.lang.String</entry></row> + <row><entry>qpid::types::Uuid</entry><entry>uuid</entry><entry>java.util.UUID</entry></row> + <row><entry>Variant::Map</entry><entry>dict</entry><entry>java.util.Map</entry></row> + <row><entry>Variant::List</entry><entry>list</entry><entry>java.util.List</entry></row> + </tbody> + </tgroup> + </table> + </section> + + <section id="section-dotnet-Maps"> + <title>Qpid Maps and Lists in .NET</title> + + + <para> + The .NET binding for the Qpid Messaging API binds .NET managed data types + to C++ <classname>Variant</classname> data types. The following code shows how to + send Map and List structures in a message: + </para> + + <example> + <?dbfo keep-together="auto" ?> + <title>Sending Qpid Maps and Lists in .NET C#</title> + <programlisting><![CDATA[ + using System; + using Org.Apache.Qpid.Messaging; + + // !!! SNIP !!! + + Dictionary<string, object> content = new Dictionary<string, object>(); + Dictionary<string, object> subMap = new Dictionary<string, object>(); + Collection<object> colors = new Collection<object>(); + + // add simple types + content["id"] = 987654321; + content["name"] = "Widget"; + content["percent"] = 0.99; + + // add nested amqp/map + subMap["name"] = "Smith"; + subMap["number"] = 354; + content["nestedMap"] = subMap; + + // add an amqp/list + colors.Add("red"); + colors.Add("green"); + colors.Add("white"); + content["colorsList"] = colors; + + // add one of each supported amqp data type + bool mybool = true; + content["mybool"] = mybool; + + byte mybyte = 4; + content["mybyte"] = mybyte; + + UInt16 myUInt16 = 5; + content["myUInt16"] = myUInt16; + + UInt32 myUInt32 = 6; + content["myUInt32"] = myUInt32; + + UInt64 myUInt64 = 7; + content["myUInt64"] = myUInt64; + + char mychar = 'h'; + content["mychar"] = mychar; + + Int16 myInt16 = 9; + content["myInt16"] = myInt16; + + Int32 myInt32 = 10; + content["myInt32"] = myInt32; + + Int64 myInt64 = 11; + content["myInt64"] = myInt64; + + Single mySingle = (Single)12.12; + content["mySingle"] = mySingle; + + Double myDouble = 13.13; + content["myDouble"] = myDouble; + + Guid myGuid = new Guid("000102030405060708090a0b0c0d0e0f"); + content["myGuid"] = myGuid; + + Message message = new Message(content); + Send(message, true); + ]]> </programlisting> + </example> + + <para> + The following table shows the mapping between datatypes in .NET and C++. + </para> + + <table id="table-dotnet-Maps"> + <title>Datatype Mapping between C++ and .NET binding</title> + <tgroup cols="2"> + <thead> + <row> + <entry>C++ Datatype</entry> + <entry>→ .NET binding</entry> + </row> + </thead> + <tbody> + <row><entry>void</entry><entry>nullptr</entry></row> + <row><entry>bool</entry><entry>bool</entry></row> + <row><entry>uint8</entry><entry>byte</entry></row> + <row><entry>uint16</entry><entry>UInt16</entry></row> + <row><entry>uint32</entry><entry>UInt32</entry></row> + <row><entry>uint64</entry><entry>UInt64</entry></row> + <row><entry>uint8</entry><entry>char</entry></row> + <row><entry>int16</entry><entry>Int16</entry></row> + <row><entry>int32</entry><entry>Int32</entry></row> + <row><entry>int64</entry><entry>Int64</entry></row> + <row><entry>float</entry><entry>Single</entry></row> + <row><entry>double</entry><entry>Double</entry></row> + <row><entry>string</entry><entry>string + <footnote id="callout-dotnet-string"> + <para>Strings are currently interpreted only with UTF-8 encoding.</para> + </footnote></entry></row> + <row><entry>qpid::types::Uuid</entry><entry>Guid</entry></row> + <row><entry>Variant::Map</entry><entry><![CDATA[Dictionary<string, object>]]> + <footnoteref linkend="callout-dotnet-string"/></entry></row> + <row><entry>Variant::List</entry><entry><![CDATA[Collection<object>]]> + <footnoteref linkend="callout-dotnet-string"/></entry></row> + </tbody> + </tgroup> + </table> + + + </section> + + + </section> + + <section> + <title>The Request / Response Pattern</title> + <para>Request / Response applications use the reply-to property, + described in <xref + linkend="table-amqp0-10-message-properties"/>, to allow a server + to respond to the client that sent a message. A server sets up a + service queue, with a name known to clients. A client creates a + private queue for the server's response, creates a message for a + request, sets the request's reply-to property to the address of + the client's response queue, and sends the request to the + service queue. The server sends the response to the address + specified in the request's reply-to property. + </para> + <example> + <title>Request / Response Applications in C++</title> + + <para>This example shows the C++ code for a client and server + that use the request / response pattern.</para> + + <para>The server creates a service queue and waits for a + message to arrive. If it receives a message, it sends a + message back to the sender.</para> + + <programlisting><![CDATA[Receiver receiver = session.createReceiver("service_queue; {create: always}"); + + Message request = receiver.fetch(); + const Address& address = request.getReplyTo(); // Get "reply-to" from request ... + if (address) { + Sender sender = session.createSender(address); // ... send response to "reply-to" + Message response("pong!"); + sender.send(response); + session.acknowledge(); + } + ]]></programlisting> + + <para>The client creates a sender for the service queue, and + also creates a response queue that is deleted when the + client closes the receiver for the response queue. In the C++ + client, if the address starts with the character + <literal>#</literal>, it is given a unique name.</para> + + <programlisting><![CDATA[ + Sender sender = session.createSender("service_queue"); + + Address responseQueue("#response-queue; {create:always, delete:always}"); + Receiver receiver = session.createReceiver(responseQueue); + + Message request; + request.setReplyTo(responseQueue); + request.setContent("ping"); + sender.send(request); + Message response = receiver.fetch(); + std::cout << request.getContent() << " -> " << response.getContent() << std::endl; + ]]> </programlisting> + + <para>The client sends the string <literal>ping</literal> to + the server. The server sends the response + <literal>pong</literal> back to the same client, using the + <varname>replyTo</varname> property.</para> + + </example> + <!-- + <example> + <title>Request / Response Applications in Python</title> + <programlisting>### TODO</programlisting> + </example> + --> + </section> + + + <section> + <title>Performance Tips</title> + + <itemizedlist> + <listitem> + <para>Consider prefetching messages for receivers (see + <xref linkend="prefetch"/>). This helps eliminate roundtrips + and increases throughput. Prefetch is disabled by default, + and enabling it is the most effective means of improving + throughput of received messages.</para> + </listitem> + <listitem> + <para>Send messages asynchronously. Again, this helps + eliminate roundtrips and increases throughput. The C++ and + .NET clients send asynchronously by default, however the + python client defaults to synchronous sends. </para> + </listitem> + <listitem> + <para>Acknowledge messages in batches (see + <xref linkend="acknowledgements"/>). Rather than + acknowledging each message individually, consider issuing + acknowledgements after n messages and/or after a particular + duration has elapsed.</para> + </listitem> + <listitem> + <para>Tune the sender capacity (see + <xref linkend="replay"/>). If the capacity is too low the + sender may block waiting for the broker to confirm receipt + of messages, before it can free up more capacity.</para> + </listitem> + <listitem> + <para>If you are setting a reply-to address on messages + being sent by the c++ client, make sure the address type is + set to either queue or topic as appropriate. This avoids the + client having to determine which type of node is being + refered to, which is required when hanling reply-to in AMQP + 0-10. </para> + </listitem> + <listitem> + <para>For latency sensitive applications, setting tcp-nodelay + on qpidd and on client connections can help reduce the + latency.</para> + </listitem> + </itemizedlist> + </section> + + <section> + <title>Cluster Failover</title> + + <para>The messaging broker can be run in clustering mode, which provides high reliability through replicating state between brokers in the cluster. If one broker in a cluster fails, clients can choose another broker in the cluster and continue their work. Each broker in the cluster also advertises the addresses of all known brokers + + <footnote><para>This is done via the amq.failover exchange in AMQP 0-10</para></footnote> + + . A client can use this information to dynamically keep the list of reconnection urls up to date.</para> + + <para>In C++, the <classname>FailoverUpdates</classname> class provides this functionality:</para> + + <example> + <title>Tracking cluster membership</title> + + <para>In C++:</para> + + <programlisting><![CDATA[ + #include <qpid/messaging/FailoverUpdates.h> + ... + Connection connection("localhost:5672"); + connection.setOption("reconnect", true); + try { + connection.open(); + std::auto_ptr<FailoverUpdates> updates(new FailoverUpdates(connection)); + ]]> + </programlisting> + + <para>In python:</para> + + <programlisting><![CDATA[ + import qpid.messaging.util + ... + connection = Connection("localhost:5672") + connection.reconnect = True + try: + connection.open() + auto_fetch_reconnect_urls(connection) + ]]> + </programlisting> + <para> + In .NET C#: + </para> + + <programlisting> + using Org.Apache.Qpid.Messaging; + ... + connection = new Connection("localhost:5672"); + connection.SetOption("reconnect", true); + try { + connection.Open(); + FailoverUpdates failover = new FailoverUpdates(connection); + + </programlisting> + + + </example> + </section> + + + + <section> + <title>Logging</title> + + <para>To simplify debugging, Qpid provides a logging facility + that prints out messaging events.</para> + + <section> + <title>Logging in C++</title> + <para> + The Qpidd broker and C++ clients can both use environment variables to enable logging. Linux and Windows systems use the same named environment variables and values. + </para> + <para>Use QPID_LOG_ENABLE to set the level of logging you are interested in (trace, debug, info, notice, warning, error, or critical): + </para> + + <screen> + export QPID_LOG_ENABLE="warning+" + </screen> + <para> + The Qpidd broker and C++ clients use QPID_LOG_OUTPUT to determine where logging output should be sent. This is either a file name or the special values stderr, stdout, or syslog: + </para> + + <screen> + export QPID_LOG_TO_FILE="/tmp/myclient.out" + </screen> + + <para> + From a Windows command prompt, use the following command format to set the environment variables: + </para> + + <screen> + set QPID_LOG_ENABLE=warning+ + set QPID_LOG_TO_FILE=D:\tmp\myclient.out + </screen> + </section> + + <section> + <title>Logging in Python</title> + <para> + The Python client library supports logging using the standard Python logging module. The easiest way to do logging is to use the <command>basicConfig()</command>, which reports all warnings and errors: + </para> + + <programlisting>from logging import basicConfig + basicConfig() + </programlisting> + <para> + Qpidd also provides a convenience method that makes it easy to specify the level of logging desired. For instance, the following code enables logging at the <command>DEBUG</command> level: + </para> + + <programlisting>from qpid.log import enable, DEBUG + enable("qpid.messaging.io", DEBUG) + </programlisting> + <para> + For more information on Python logging, see <ulink url="http://docs.python.org/lib/node425.html">http://docs.python.org/lib/node425.html</ulink>. For more information on Qpid logging, use <command>$ pydoc qpid.log</command>. + </para> + </section> + </section> + + + + <section id="section-amqp0-10-mapping"> + <title>The AMQP 0-10 mapping</title> + + <para> + This section describes the AMQP 0-10 mapping for the Qpid + Messaging API. + </para> + <para> + The interaction with the broker triggered by creating a sender + or receiver depends on what the specified address resolves + to. Where the node type is not specified in the address, the + client queries the broker to determine whether it refers to a + queue or an exchange. + </para> + <para> + When sending to a queue, the queue's name is set as the + routing key and the message is transfered to the default (or + nameless) exchange. When sending to an exchange, the message + is transfered to that exchange and the routing key is set to + the message subject if one is specified. A default subject may + be specified in the target address. The subject may also be + set on each message individually to override the default if + required. In each case any specified subject is also added as + a qpid.subject entry in the application-headers field of the + message-properties. + </para> + <para> + When receiving from a queue, any subject in the source address + is currently ignored. The client sends a message-subscribe + request for the queue in question. The accept-mode is + determined by the reliability option in the link properties; + for unreliable links the accept-mode is none, for reliable + links it is explicit. The default for a queue is reliable. The + acquire-mode is determined by the value of the mode option. If + the mode is set to browse the acquire mode is not-acquired, + otherwise it is set to pre-acquired. The exclusive and + arguments fields in the message-subscribe command can be + controlled using the x-subscribe map. + </para> + <para> + When receiving from an exchange, the client creates a + subscription queue and binds that to the exchange. The + subscription queue's arguments can be specified using the + x-declare map within the link properties. The reliability + option determines most of the other parameters. If the + reliability is set to unreliable then an auto-deleted, + exclusive queue is used meaning that if the client or + connection fails messages may be lost. For exactly-once the + queue is not set to be auto-deleted. The durability of the + subscription queue is determined by the durable option in the + link properties. The binding process depends on the type of + the exchange the source address resolves to. + </para> + + <itemizedlist> + <listitem> + <para> + For a topic exchange, if no subject is specified and no + x-bindings are defined for the link, the subscription + queue is bound using a wildcard matching any routing key + (thus satisfying the expectation that any message sent to + that address will be received from it). If a subject is + specified in the source address however, it is used for + the binding key (this means that the subject in the source + address may be a binding pattern including wildcards). + </para> + </listitem> + <listitem> + <para> + For a fanout exchange the binding key is irrelevant to + matching. A receiver created from a source address that + resolves to a fanout exchange receives all messages + sent to that exchange regardless of any subject the source + address may contain. An x-bindings element in the link + properties should be used if there is any need to set the + arguments to the bind. + </para> + </listitem> + <listitem> + <para> + For a direct exchange, the subject is used as the binding + key. If no subject is specified an empty string is used as + the binding key. + </para> + </listitem> + <listitem> + <para> + For a headers exchange, if no subject is specified the + binding arguments simply contain an x-match entry and no + other entries, causing all messages to match. If a subject + is specified then the binding arguments contain an x-match + entry set to all and an entry for qpid.subject whose value + is the subject in the source address (this means the + subject in the source address must match the message + subject exactly). For more control the x-bindings element + in the link properties must be used. + </para> + </listitem> + <listitem> + <para> + For the XML exchange,<footnote><para>Note that the XML + exchange is not a standard AMQP exchange type. It is a + Qpid extension and is currently only supported by the C++ + broker.</para></footnote> if a subject is specified it is + used as the binding key and an XQuery is defined that + matches any message with that value for + qpid.subject. Again this means that only messages whose + subject exactly match that specified in the source address + are received. If no subject is specified then the empty + string is used as the binding key with an xquery that will + match any message (this means that only messages with an + empty string as the routing key will be received). For more + control the x-bindings element in the link properties must + be used. A source address that resolves to the XML + exchange must contain either a subject or an x-bindings + element in the link properties as there is no way at + present to receive any message regardless of routing key. + </para> + </listitem> + </itemizedlist> + + <para> + If an x-bindings list is present in the link options a binding + is created for each element within that list. Each element is + a nested map that may contain values named queue, exchange, + key or arguments. If the queue value is absent the queue name + the address resolves to is implied. If the exchange value is + absent the exchange name the address resolves to is implied. + </para> + + <para>The following table shows how Qpid Messaging API message + properties are mapped to AMQP 0-10 message properties and + delivery properties. In this table <varname>msg</varname> + refers to the Message class defined in the Qpid Messaging API, + <varname>mp</varname> refers to an AMQP 0-10 + <varname>message-properties</varname> struct, and + <varname>dp</varname> refers to an AMQP 0-10 + <varname>delivery-properties</varname> struct.</para> + + <table id="table-amqp0-10-message-properties" pgwide="1"> + <title>Mapping to AMQP 0-10 Message Properties</title> + <tgroup cols="3"> + <thead> + <colspec colnum="1" colname="Python API" colwidth="3*"/> + <colspec colnum="2" colname="C++ API" colwidth="3*"/> + <colspec colnum="3" colname="AMPQ 0-10 Property" colwidth="6*"/> + <row> + <entry>Python API</entry> + <entry>C++ API + <footnote> + <para> + The .NET Binding for C++ Messaging provides all the + message and delivery properties described in the C++ API. + See <xref linkend="table-Dotnet-Binding-Message" /> . + </para> + </footnote> + </entry> + <entry>AMQP 0-10 Property<footnote><para>In these entries, <literal>mp</literal> refers to an AMQP message property, and <literal>dp</literal> refers to an AMQP delivery property.</para></footnote></entry> + </row> + </thead> + <tbody> + <row> + <entry>msg.id</entry><entry>msg.{get,set}MessageId()</entry><entry>mp.message_id</entry> + </row> + <row> + <entry>msg.subject</entry><entry>msg.{get,set}Subject()</entry><entry>mp.application_headers["qpid.subject"]</entry> + </row> + <row> + <entry>msg.user_id</entry><entry>msg.{get,set}UserId()</entry><entry>mp.user_id</entry> + </row> + <row> + <entry>msg.reply_to</entry><entry>msg.{get,set}ReplyTo()</entry><entry>mp.reply_to<footnote><para>The reply_to is converted from the protocol representation into an address.</para></footnote></entry> + </row> + <row> + <entry>msg.correlation_id</entry><entry>msg.{get,set}CorrelationId()</entry><entry>mp.correlation_id</entry> + </row> + <row> + <entry>msg.durable</entry><entry>msg.{get,set}Durable()</entry><entry>dp.delivery_mode == delivery_mode.persistent<footnote><para>Note that msg.durable is a boolean, not an enum.</para></footnote></entry> + </row> + <row> + <entry>msg.priority</entry><entry>msg.{get,set}Priority()</entry><entry>dp.priority</entry> + </row> + <row> + <entry>msg.ttl</entry><entry>msg.{get,set}Ttl()</entry><entry>dp.ttl</entry> + </row> + <row> + <entry>msg.redelivered</entry><entry>msg.{get,set}Redelivered()</entry><entry>dp.redelivered</entry> + </row> + <row><entry>msg.properties</entry><entry>msg.getProperties()/msg.setProperty()</entry><entry>mp.application_headers</entry> + </row> + <row> + <entry>msg.content_type</entry><entry>msg.{get,set}ContentType()</entry><entry>mp.content_type</entry> + </row> + </tbody> + </tgroup> + </table> + + <section role="h3" id="section-amqp0-10-message-props"> + <title>0-10 Message Property Keys</title> + <para> + The QPID Messaging API also recognises special message property keys and + automatically provides a mapping to their corresponding AMQP 0-10 definitions. + </para> + <itemizedlist> + <listitem> + <para> + When sending a message, if the properties contain an entry for + <literal>x-amqp-0-10.app-id</literal>, its value will be used to set the + <literal>message-properties.app-id</literal> property in the outgoing + message. Likewise, if an incoming message has + <literal>message-properties.app-id</literal> set, its value can be accessed + via the <literal>x-amqp-0-10.app-id</literal> message property key. + </para> + </listitem> + <listitem> + <para> + When sending a message, if the properties contain an entry for + <literal>x-amqp-0-10.content-encoding</literal>, its value will be used to + set the <literal>message-properties.content-encoding</literal> property in + the outgoing message. Likewise, if an incoming message has + <literal>message-properties.content-encoding</literal> set, its value can be + accessed via the <literal>x-amqp-0-10.content-encoding</literal> message + property key. + </para> + </listitem> + <listitem> + <para> + The routing key (<literal>delivery-properties.routing-key</literal>) in an + incoming messages can be accessed via the + <literal>x-amqp-0-10.routing-key</literal> message property. + </para> + </listitem> + <listitem> + <para> + If the timestamp delivery property is set in an incoming message + (<literal>delivery-properties.timestamp</literal>), the timestamp value will + be made available via the <literal>x-amqp-0-10.timestamp</literal> message + property. + <footnote> + <para> + This special property is currently not supported by the Qpid JMS client. + </para> + </footnote> + </para> + </listitem> + </itemizedlist> + <example> + <title>Accessing the AMQP 0-10 Message Timestamp in Python</title> + <para> + The following code fragment checks for and extracts the message timestamp from + a received message. + </para> + <programlisting lang="python"> + try: + msg = receiver.fetch(timeout=1) + if "x-amqp-0-10.timestamp" in msg.properties: + print("Timestamp=%s" % str(msg.properties["x-amqp-0-10.timestamp"])) + except Empty: + pass + </programlisting> + </example> + <example> + <title>Accessing the AMQP 0-10 Message Timestamp in C++</title> + <para> + The same example, except in C++. + </para> + <programlisting lang="c++"> + messaging::Message msg; + if (receiver.fetch(msg, messaging::Duration::SECOND*1)) { + if (msg.getProperties().find("x-amqp-0-10.timestamp") != msg.getProperties().end()) { + <![CDATA[std::cout << "Timestamp=" << msg.getProperties()["x-amqp-0-10.timestamp"].asString() << std::endl;]]> + } + } + </programlisting> + </example> + </section> + </section> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Message-Groups-Guide.xml"/> + + </chapter> + + + <chapter id="QpidJMS"> + <title>Using the Qpid JMS client</title> + <section> + <title>A Simple Messaging Program in Java JMS</title> + + <para>The following program shows how to send and receive a + message using the Qpid JMS client. JMS programs typically use + JNDI to obtain connection factory and destination objects which + the application needs. In this way the configuration is kept + separate from the application code itself.</para> + + <para>In this example, we create a JNDI context using a + properties file, use the context to lookup a connection factory, + create and start a connection, create a session, and lookup a + destination from the JNDI context. Then we create a producer and + a consumer, send a message with the producer and receive it with + the consumer. This code should be straightforward for anyone + familiar with Java JMS.</para> + + <example> + <title>"Hello world!" in Java</title> + <programlisting lang="java"> + package org.apache.qpid.example.jmsexample.hello; + + import javax.jms.*; + import javax.naming.Context; + import javax.naming.InitialContext; + import java.util.Properties; + + public class Hello { + + public Hello() { + } + + public static void main(String[] args) { + Hello producer = new Hello(); + producer.runTest(); + } + + private void runTest() { + try { + Properties properties = new Properties(); + properties.load(this.getClass().getResourceAsStream("hello.properties")); <co id="hello-java-properties" linkends="callout-java-properties"/> + Context context = new InitialContext(properties); <co id="hello-java-context" linkends="callout-java-context"/> + + ConnectionFactory connectionFactory + = (ConnectionFactory) context.lookup("qpidConnectionfactory"); <co id="hello-java-connection-factory" linkends="callout-java-connection-factory"/> + Connection connection = connectionFactory.createConnection(); <co id="hello-java-connection" linkends="callout-java-connection"/> + connection.start(); <co id="hello-java-start" linkends="callout-java-start"/> + + Session session=connection.createSession(false,Session.AUTO_ACKNOWLEDGE);<co id="hello-java-session" linkends="callout-java-session"/> + Destination destination = (Destination) context.lookup("topicExchange"); <co id="hello-java-destination" linkends="callout-java-destination"/> + + MessageProducer messageProducer = session.createProducer(destination); <co id="hello-java-producer" linkends="callout-java-producer"/> + MessageConsumer messageConsumer = session.createConsumer(destination); <co id="hello-java-consumer" linkends="callout-java-consumer"/> + + TextMessage message = session.createTextMessage("Hello world!"); + messageProducer.send(message); + + message = (TextMessage)messageConsumer.receive(); <co id="hello-java-receive" linkends="callout-java-receive"/> + System.out.println(message.getText()); + + connection.close(); <co id="hello-java-close" linkends="callout-java-close"/> + context.close(); <co id="hello-java-jndi-close" linkends="callout-java-jndi-close"/> + } + catch (Exception exp) { + exp.printStackTrace(); + } + } + } + </programlisting> + </example> + + <calloutlist> + <callout id="callout-java-properties" arearefs="hello-java-properties"> + <para>Loads the JNDI properties file, which specifies connection properties, queues, topics, and addressing options. See <xref linkend="QpidJNDI"/> for details.</para> + </callout> + <callout id="callout-java-context" arearefs="hello-java-context"> + <para>Creates the JNDI initial context.</para> + </callout> + <callout id="callout-java-connection-factory" arearefs="hello-java-connection-factory"> + <para>Creates a JMS connection factory for Qpid.</para> + </callout> + <callout id="callout-java-connection" arearefs="hello-java-connection"> + <para>Creates a JMS connection.</para> + </callout> + <callout id="callout-java-start" arearefs="hello-java-start"> + <para>Activates the connection.</para> + </callout> + <callout id="callout-java-session" arearefs="hello-java-session"> + <para>Creates a session. This session is not transactional (transactions='false'), and messages are automatically acknowledged.</para> + </callout> + <callout id="callout-java-destination" arearefs="hello-java-destination"> + <para>Creates a destination for the topic exchange, so senders and receivers can use it.</para> + </callout> + <callout id="callout-java-producer" arearefs="hello-java-producer"> + <para>Creates a producer that sends messages to the topic exchange.</para> + </callout> + <callout id="callout-java-consumer" arearefs="hello-java-consumer"> + <para>Creates a consumer that reads messages from the topic exchange.</para> + </callout> + <callout id="callout-java-receive" arearefs="hello-java-receive"> + <para>Reads the next available message.</para> + </callout> + <callout id="callout-java-close" arearefs="hello-java-close"> + <para>Closes the connection, all sessions managed by the connection, and all senders and receivers managed by each session.</para> + </callout> + <callout id="callout-java-jndi-close" arearefs="hello-java-jndi-close"> + <para>Closes the JNDI context.</para> + </callout> + </calloutlist> + + <para>The contents of the hello.properties file are shown below.</para> + + <example> + <title>JNDI Properties File for "Hello world!" example</title> + <programlisting> + java.naming.factory.initial + = org.apache.qpid.jndi.PropertiesFileInitialContextFactory + + # connectionfactory.[jndiname] = [ConnectionURL] + connectionfactory.qpidConnectionfactory + = amqp://guest:guest@clientid/test?brokerlist='tcp://localhost:5672' <co id="hello-properties-connectionfactory" linkends="callout-hello-properties-connectionfactory"/> + # destination.[jndiname] = [address_string] + destination.topicExchange = amq.topic <co id="hello-properties-destination" linkends="callout-hello-properties-destination"/> + </programlisting> + </example> + + <calloutlist> + <callout id="callout-hello-properties-connectionfactory" arearefs="hello-properties-connectionfactory"> + <para>Defines a connection factory from which connections + can be created. The syntax of a ConnectionURL is given in + <xref linkend="QpidJNDI"/>.</para> + </callout> + <callout id="callout-hello-properties-destination" arearefs="hello-properties-destination"> + <para>Defines a destination for which MessageProducers + and/or MessageConsumers can be created to send and receive + messages. The value for the destination in the properties + file is an address string as described in + <xref linkend="section-addresses"/>. In the JMS + implementation MessageProducers are analogous to senders in + the Qpid Message API, and MessageConsumers are analogous to + receivers.</para> + </callout> + </calloutlist> + + </section> + + <section id="QpidJNDI"> + <title>Apache Qpid JNDI Properties for AMQP Messaging</title> + + + <para> + Apache Qpid defines JNDI properties that can be used to specify JMS Connections and Destinations. Here is a typical JNDI properties file: + </para> + + <example> + <title>JNDI Properties File</title> + <programlisting><![CDATA[ + java.naming.factory.initial + = org.apache.qpid.jndi.PropertiesFileInitialContextFactory + + # connectionfactory.[jndiname] = [ConnectionURL] + connectionfactory.qpidConnectionfactory + = amqp://guest:guest@clientid/test?brokerlist='tcp://localhost:5672' + # destination.[jndiname] = [address_string] + destination.topicExchange = amq.topic + ]]></programlisting> + </example> + + <para>The following sections describe the JNDI properties that Qpid uses.</para> + + + <section> + <title>JNDI Properties for Apache Qpid</title> + <para> + Apache Qpid supports the properties shown in the following table: + </para> + <table> + <title>JNDI Properties supported by Apache Qpid</title> + <tgroup cols="2"> + <thead> + <row> + <entry> + Property + </entry> + <entry> + Purpose + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + connectionfactory.<jndiname> + </entry> + <entry> + <para> + The Connection URL that the connection factory uses to perform connections. + </para> + </entry> + </row> + <row> + <entry> + queue.<jndiname> + </entry> + <entry> + <para> + A JMS queue, which is implemented as an amq.direct exchange in Apache Qpid. + </para> + </entry> + </row> + <row> + <entry> + topic.<jndiname> + </entry> + <entry> + <para> + A JMS topic, which is implemented as an amq.topic exchange in Apache Qpid. + </para> + </entry> + </row> + <row> + <entry> + destination.<jndiname> + </entry> + <entry> + <para> + Can be used for defining all amq destinations, + queues, topics and header matching, using an + address string. + + <footnote><para>Binding URLs, which were used in + earlier versions of the Qpid Java JMS client, can + still be used instead of address + strings.</para></footnote> + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section id="section-jms-connection-url"> + <title>Connection URLs</title> + <para> + In JNDI properties, a Connection URL specifies properties for a connection. The format for a Connection URL is: + </para> + + <programlisting>amqp://[<user>:<pass>@][<clientid>]<virtualhost>[?<option>='<value>'[&<option>='<value>']] + </programlisting> + <para> + For instance, the following Connection URL specifies a user name, a password, a client ID, a virtual host ("test"), a broker list with a single broker, and a TCP host with the host name <quote>localhost</quote> using port 5672: + </para> + + <programlisting>amqp://username:password@clientid/test?brokerlist='tcp://localhost:5672' + </programlisting> + <para> + Apache Qpid supports the following properties in Connection URLs: + </para> + <table pgwide="1"> + <title>Connection URL Properties</title> + <tgroup cols="3"> + <thead> + <row> + <entry> + Option + </entry> + <entry> + Type + </entry> + <entry> + Description + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + brokerlist + </entry> + <entry> + see below + </entry> + <entry> + List of one or more broker addresses. + </entry> + </row> + <row> + <entry> + maxprefetch + </entry> + <entry> + integer + </entry> + <entry> + <para> + The maximum number of pre-fetched messages per consumer. If not specified, default value of 500 is used. + </para> + <para> + Note: You can also set the default per-consumer prefetch value on a client-wide basis by configuring the client using <link linkend="client-jvm-properties">Java system properties.</link> + </para> + </entry> + </row> + <row> + <entry> + sync_publish + </entry> + <entry> + {'persistent' | 'all'} + </entry> + <entry> + A sync command is sent after every persistent message to guarantee that it has been received; if the value is 'persistent', this is done only for persistent messages. + </entry> + </row> + <row> + <entry> + sync_ack + </entry> + <entry> + Boolean + </entry> + <entry> + A sync command is sent after every acknowledgement to guarantee that it has been received. + </entry> + </row> + <row> + <entry> + use_legacy_map_msg_format + </entry> + <entry> + Boolean + </entry> + <entry> + If you are using JMS Map messages and deploying a new client with any JMS client older than 0.8 release, you must set this to true to ensure the older clients can understand the map message encoding. + </entry> + </row> + <row> + <entry> + failover + </entry> + <entry> + {'singlebroker' | 'roundrobin' | 'failover_exchange' | 'nofailover' | '<class>'} + </entry> + <entry> + <para> + This option controls failover behaviour. The method <literal>singlebroker</literal> uses only the first broker in the list, + <literal>roundrobin</literal> will try each broker given in the broker list until a connection is established, + <literal>failover_exchange</literal> connects to the initial broker given in the broker URL and will receive membership updates + via the failover exchange. <literal>nofailover</literal> disables all retry and failover logic. Any other value is interpreted as a + classname which must implement the <literal>org.apache.qpid.jms.failover.FailoverMethod</literal> interface. + </para> + <para> + The broker list options <literal>retries</literal> and <literal>connectdelay</literal> (described below) determine the number of times a + connection to a broker will be retried and the the length of time to wait between successive connection attempts before moving on to + the next broker in the list. The failover option <literal>cyclecount</literal> controls the number of times to loop through the list of + available brokers before finally giving up. + </para> + <para> + Defaults to <literal>roundrobin</literal> if the brokerlist contains multiple brokers, or <literal>singlebroker</literal> otherwise. + </para> + </entry> + </row> + <row> + <entry> + ssl + </entry> + <entry> + boolean + </entry> + <entry> + <para> + If <literal>ssl='true'</literal>, use SSL for all broker connections. Overrides any per-broker settings in the brokerlist (see below) entries. If not specified, the brokerlist entry for each given broker is used to determine whether SSL is used. + </para> + <para> + Introduced in version 0.22. + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + <para> + Broker lists are specified using a URL in this format: + </para> + + <programlisting>brokerlist=<transport>://<host>[:<port>](?<param>='<value>')(&<param>='<value>')*</programlisting> + <para> + For instance, this is a typical broker list: + </para> + + <programlisting>brokerlist='tcp://localhost:5672' + </programlisting> + + <para> + A broker list can contain more than one broker address; if so, the connection is made to the first broker in the list that is available. In general, it is better to use the failover exchange when using multiple brokers, since it allows applications to fail over if a broker goes down. + </para> + + <example> + <title>Broker Lists</title> + <para>A broker list can specify properties to be used when connecting to the broker, such as security options. This broker list specifies options for a Kerberos connection using GSSAPI:</para> + <programlisting><![CDATA[ + amqp://guest:guest@test/test?sync_ack='true' + &brokerlist='tcp://ip1:5672?sasl_mechs='GSSAPI'' + ]]></programlisting> + + <para>This broker list specifies SSL options:</para> + + <programlisting><![CDATA[ + amqp://guest:guest@test/test?sync_ack='true' + &brokerlist='tcp://ip1:5672?ssl='true'&ssl_cert_alias='cert1'' + ]]></programlisting> + + <para> + This broker list specifies two brokers using the connectdelay and retries broker options. It also illustrates the failover connection URL + property. + </para> + + <programlisting><![CDATA[ + + amqp://guest:guest@/test?failover='roundrobin?cyclecount='2'' + &brokerlist='tcp://ip1:5672?retries='5'&connectdelay='2000';tcp://ip2:5672?retries='5'&connectdelay='2000'' + ]]></programlisting> + </example> + + <para>The following broker list options are supported.</para> + + <table pgwide="1"> + <title>Broker List Options</title> + <tgroup cols="3"> + <thead> + <row> + <entry> + Option + </entry> + <entry> + Type + </entry> + <entry> + Description + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + heartbeat + </entry> + <entry> + integer + </entry> + <entry> + Frequency of heartbeat messages (in seconds). A value of 0 disables heartbeating. <para>For compatibility + with old client configuration, option <varname>idle_timeout</varname> (in milliseconds) is also supported.</para> + </entry> + </row> + <row> + <entry> + sasl_mechs + </entry> + <entry> + -- + </entry> + <entry> + For secure applications, we suggest CRAM-MD5, + DIGEST-MD5, or GSSAPI. The ANONYMOUS method is not + secure. The PLAIN method is secure only when used + together with SSL. For Kerberos, sasl_mechs must be + set to GSSAPI, sasl_protocol must be set to the + principal for the qpidd broker, e.g. qpidd/, and + sasl_server must be set to the host for the SASL + server, e.g. sasl.com. SASL External is supported + using SSL certification, e.g. + <literal>ssl='true'&sasl_mechs='EXTERNAL'</literal> + </entry> + </row> + <row> + <entry> + sasl_encryption + </entry> + <entry> + Boolean + </entry> + <entry> + If <literal>sasl_encryption='true'</literal>, the JMS client attempts to negotiate a security layer with the broker using GSSAPI to encrypt the connection. Note that for this to happen, GSSAPI must be selected as the sasl_mech. + </entry> + </row> + <row> + <entry> + sasl_protocol + </entry> + <entry> + -- + </entry> + <entry> + Used only for + Kerberos. <literal>sasl_protocol</literal> must be + set to the principal for the qpidd broker, + e.g. <literal>qpidd/</literal> + </entry> + </row> + <row> + <entry> + sasl_server + </entry> + <entry> + -- + </entry> + <entry> + For Kerberos, sasl_mechs must be set to GSSAPI, + sasl_server must be set to the host for the SASL + server, e.g. <literal>sasl.com</literal>. + </entry> + </row> + <row> + <entry> + trust_store + </entry> + <entry> + -- + </entry> + <entry> + path to trust store + </entry> + </row> + <row> + <entry> + trust_store_password + </entry> + <entry> + -- + </entry> + <entry> + Trust store password + </entry> + </row> + <row> + <entry> + key_store + </entry> + <entry> + -- + </entry> + <entry> + path to key store + </entry> + </row> + <row> + <entry> + key_store_password + </entry> + <entry> + -- + </entry> + <entry> + key store password + </entry> + </row> + <row> + <entry> + ssl + </entry> + <entry> + Boolean + </entry> + <entry> + <para>If <literal>ssl='true'</literal>, the JMS client will encrypt the connection to this broker using SSL.</para> + + <para>This can also be set/overridden for all brokers using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para> + </entry> + </row> + <row> + <entry> + ssl_verify_hostname + </entry> + <entry> + Boolean + </entry> + <entry> + When using SSL you can enable hostname verification + by using <literal>ssl_verify_hostname='true'</literal> in the broker + URL. + </entry> + </row> + <row> + <entry> + ssl_cert_alias + </entry> + <entry> + -- + </entry> + <entry> + If multiple certificates are present in the keystore, the alias will be used to extract the correct certificate. + </entry> + </row> + <row> + <entry> + retries + </entry> + <entry> + integer + </entry> + <entry> + The number of times to retry connection to each broker in the broker list. Defaults to 1. + </entry> + </row> + <row> + <entry> + connectdelay + </entry> + <entry> + integer + </entry> + <entry> + Length of time (in milliseconds) to wait before attempting to reconnect. Defaults to 0. + </entry> + </row> + <row> + <entry> + connecttimeout + </entry> + <entry> + integer + </entry> + <entry> + Length of time (in milliseconds) to wait for the socket connection to succeed. A value of 0 represents an infinite timeout, i.e. the connection attempt will block until established or an error occurs. Defaults to 30000. + </entry> + </row> + <row> + <entry> + tcp_nodelay + </entry> + <entry> + Boolean + </entry> + <entry> + If <literal>tcp_nodelay='true'</literal>, TCP packet + batching is disabled. Defaults to true since Qpid 0.14. + </entry> + </row> + </tbody> + </tgroup> + </table> + </section> + </section> + + <section> + <title>Java JMS Message Properties</title> + + <para>The following table shows how Qpid Messaging API message + properties are mapped to AMQP 0-10 message properties and + delivery properties. In this table <varname>msg</varname> + refers to the Message class defined in the Qpid Messaging API, + <varname>mp</varname> refers to an AMQP 0-10 + <varname>message-properties</varname> struct, and + <varname>dp</varname> refers to an AMQP 0-10 + <varname>delivery-properties</varname> struct.</para> + + <table > + <title>Java JMS Mapping to AMQP 0-10 Message Properties</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Java JMS Message Property</entry> + <entry>AMQP 0-10 Property<footnote><para>In these entries, <literal>mp</literal> refers to an AMQP message property, and <literal>dp</literal> refers to an AMQP delivery property.</para></footnote></entry> + + </row> + </thead> + <tbody> + <row> + <entry>JMSMessageID</entry><entry>mp.message_id</entry> + </row> + <row> + <entry>qpid.subject<footnote><para>This is a custom JMS property, set automatically by the Java JMS client implementation.</para></footnote></entry><entry>mp.application_headers["qpid.subject"]</entry> + </row> + <row> + <entry>JMSXUserID</entry><entry>mp.user_id</entry> + </row> + <row> + <entry>JMSReplyTo</entry><entry>mp.reply_to<footnote><para>The reply_to is converted from the protocol representation into an address.</para></footnote></entry> + </row> + <row> + <entry>JMSCorrelationID</entry><entry>mp.correlation_id</entry> + </row> + <row> + <entry>JMSDeliveryMode</entry><entry>dp.delivery_mode</entry> + </row> + <row> + <entry>JMSPriority</entry><entry>dp.priority</entry> + </row> + <row> + <entry>JMSExpiration</entry><entry>dp.ttl<footnote><para>JMSExpiration = dp.ttl + currentTime</para></footnote></entry> + </row> + <row> + <entry>JMSRedelivered</entry><entry>dp.redelivered</entry> + </row> + <row> + <entry>JMS Properties</entry><entry>mp.application_headers</entry> + </row> + <row> + <entry>JMSType</entry><entry>mp.content_type</entry> + </row> + </tbody> + </tgroup> + </table> + + </section> + + <section id="section-JMS-MapMessage"> + <title>JMS MapMessage Types</title> + + <para>Qpid supports the Java JMS <classname>MapMessage</classname> interface, which provides support for maps in messages. The following code shows how to send a <classname>MapMessage</classname> in Java JMS.</para> + + <example> + <title>Sending a Java JMS MapMessage</title> + <programlisting><![CDATA[ + import java.util.ArrayList; + import java.util.HashMap; + import java.util.List; + import java.util.Map; + + import javax.jms.Connection; + import javax.jms.Destination; + import javax.jms.MapMessage; + import javax.jms.MessageProducer; + import javax.jms.Session; + + import java.util.Arrays; + + // !!! SNIP !!! + + MessageProducer producer = session.createProducer(queue); + + MapMessage m = session.createMapMessage(); + m.setIntProperty("Id", 987654321); + m.setStringProperty("name", "Widget"); + m.setDoubleProperty("price", 0.99); + + List<String> colors = new ArrayList<String>(); + colors.add("red"); + colors.add("green"); + colors.add("white"); + m.setObject("colours", colors); + + Map<String,Double> dimensions = new HashMap<String,Double>(); + dimensions.put("length",10.2); + dimensions.put("width",5.1); + dimensions.put("depth",2.0); + m.setObject("dimensions",dimensions); + + List<List<Integer>> parts = new ArrayList<List<Integer>>(); + parts.add(Arrays.asList(new Integer[] {1,2,5})); + parts.add(Arrays.asList(new Integer[] {8,2,5})); + m.setObject("parts", parts); + + Map<String,Object> specs = new HashMap<String,Object>(); + specs.put("colours", colors); + specs.put("dimensions", dimensions); + specs.put("parts", parts); + m.setObject("specs",specs); + + producer.send(m); + ]]></programlisting> + </example> + + <para>The following table shows the datatypes that can be sent in a <classname>MapMessage</classname>, and the corresponding datatypes that will be received by clients in Python or C++.</para> + + <table id="table-Java-Maps"> + <title>Java Datatypes in Maps</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Java Datatype</entry> + <entry>→ Python</entry> + <entry>→ C++</entry> + </row> + </thead> + <tbody> + <row><entry>boolean</entry><entry>bool</entry><entry>bool</entry></row> + <row><entry>short</entry><entry>int | long</entry><entry>int16</entry></row> + <row><entry>int</entry><entry>int | long</entry><entry>int32</entry></row> + <row><entry>long</entry><entry>int | long</entry><entry>int64</entry></row> + <row><entry>float</entry><entry>float</entry><entry>float</entry></row> + <row><entry>double</entry><entry>float</entry><entry>double</entry></row> + <row><entry>java.lang.String</entry><entry>unicode</entry><entry>std::string</entry></row> + <row><entry>java.util.UUID</entry><entry>uuid</entry><entry>qpid::types::Uuid</entry></row> + <row><entry>java.util.Map<footnote><para>In Qpid, maps can nest. This goes beyond the functionality required by the JMS specification.</para></footnote></entry><entry>dict</entry><entry>Variant::Map</entry></row> + <row><entry>java.util.List</entry><entry>list</entry><entry>Variant::List</entry></row> + </tbody> + </tgroup> + </table> + + </section> + + <section id="section-JMS-Logging"> + <title>JMS Client Logging</title> + <para>The JMS Client logging is handled using the Simple Logging Facade for Java (<ulink url="http://www.slf4j.org/">SLF4J</ulink>). As the name implies, slf4j is a facade that delegates to other logging systems like log4j or JDK 1.4 logging. For more information on how to configure slf4j for specific logging systems, please consult the slf4j documentation.</para> + + <para>When using the log4j binding, please set the log level for org.apache.qpid explicitly. Otherwise log4j will default to DEBUG which will degrade performance considerably due to excessive logging. The recommended logging level for production is <literal>WARN</literal>.</para> + + <para>The following example shows the logging properties used to configure client logging for slf4j using the log4j binding. These properties can be placed in a log4j.properties file and placed in the <varname>CLASSPATH</varname>, or they can be set explicitly using the <literal>-Dlog4j.configuration</literal> property.</para> + + <example> + <title>log4j Logging Properties</title> + + <programlisting><![CDATA[ + log4j.logger.org.apache.qpid=WARN, console + log4j.additivity.org.apache.qpid=false + + log4j.appender.console=org.apache.log4j.ConsoleAppender + log4j.appender.console.Threshold=all + log4j.appender.console.layout=org.apache.log4j.PatternLayout + log4j.appender.console.layout.ConversionPattern=%t %d %p [%c{4}] %m%n + ]]></programlisting> + </example> + + </section> + + <section> + <title>Configuring the JMS Client</title> + + <para>The Qpid JMS Client allows several configuration options to customize it's behaviour at different levels of granualarity.</para> + + <itemizedlist> + <listitem> + <para> + JVM level using JVM arguments : Configuration that affects all connections, sessions, consumers and producers created within that JVM. + </para> + <para>Ex. <varname>-Dmax_prefetch=1000</varname> property specifies the message credits to use.</para> + </listitem> + + <listitem> + <para> + Connection level using Connection/Broker properties : Affects the respective connection and sessions, consumers and produces created by that connection. + </para> + <para>Ex. <varname>amqp://guest:guest@test/test?max_prefetch='1000' + &brokerlist='tcp://localhost:5672' + </varname> property specifies the message credits to use. This overrides any value specified via the JVM argument <varname>max_prefetch</varname>.</para> + <para>Please refer to the <xref linkend="section-jms-connection-url"/> section for a complete list of all properties and how to use them.</para> + </listitem> + + <listitem> + <para> + Destination level using Addressing options : Affects the producer(s) and consumer(s) created using the respective destination. + </para> + <para>Ex. <varname>my-queue; {create: always, link:{capacity: 10}}</varname>, where <varname>capacity</varname> option specifies the message credits to use. This overrides any connection level configuration.</para> + <para>Please refer to the <xref linkend="section-addresses"/> section for a complete understanding of addressing and it's various options.</para> + </listitem> + </itemizedlist> + + <para>Some of these config options are available at all three levels (Ex. <varname>max_prefetch</varname>), while others are available only at JVM or connection level.</para> + + <section id="client-jvm-properties"> + <title>Qpid JVM Arguments</title> + + <table > + <title>Config Options For Connection Behaviour</title> + <tgroup cols="4"> + <thead> + <row> + <entry>Property Name</entry> + <entry>Type</entry> + <entry>Default Value</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>qpid.amqp.version</entry> + <entry>string</entry> + <entry>0-10</entry> + <entry><para>Sets the AMQP version to be used - currently supports one of {0-8,0-9,0-91,0-10}.</para><para>The client will begin negotiation at the specified version and only negotiate downwards if the Broker does not support the specified version.</para></entry> + </row> + <row> + <entry>qpid.heartbeat</entry> + <entry>int</entry> + <entry><para>When using the 0-10 protocol, the default is 120 (secs)</para><para>When using protocols 0-8...0-91, the default is the broker-supplied value.</para></entry> + <entry>Frequency of heartbeat messages (in seconds). A value of 0 disables heartbeating. <para>Two consective misssed heartbeats will result in the connection timing out.</para><para>This can also be set per connection using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para><para>For compatibility with old client configuration, the synonym <varname>amqj.heartbeat.delay</varname> is supported.</para></entry> + </row> + <row> + <entry>ignore_setclientID</entry> + <entry>boolean</entry> + <entry>false</entry> + <entry>If a client ID is specified in the connection URL it's used or else an ID is generated. If an ID is specified after it's been set Qpid will throw an exception. <para>Setting this property to 'true' will disable that check and allow you to set a client ID of your choice later on.</para></entry> + </row> + </tbody> + </tgroup> + </table> + + + <table > + <title>Config Options For Session Behaviour</title> + <tgroup cols="4"> + <thead> + <row> + <entry>Property Name</entry> + <entry>Type</entry> + <entry>Default Value</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>qpid.session.command_limit</entry> + <entry>int</entry> + <entry>65536</entry> + <entry>Limits the # of unacked commands</entry> + </row> + + <row> + <entry>qpid.session.byte_limit</entry> + <entry>int</entry> + <entry>1048576</entry> + <entry>Limits the # of unacked commands in terms of bytes</entry> + </row> + + <row> + <entry>qpid.use_legacy_map_message</entry> + <entry>boolean</entry> + <entry>false</entry> + <entry><para>If set will use the old map message encoding. By default the Map messages are encoded using the 0-10 map encoding.</para><para>This can also be set per connection using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para></entry> + </row> + + <row> + <entry>qpid.jms.daemon.dispatcher</entry> + <entry>boolean</entry> + <entry>false</entry> + <entry><para>Controls whether the Session dispatcher thread is a daemon thread or not. If this system property is set to true then the Session dispatcher threads will be created as daemon threads. This setting is introduced in version 0.16.</para></entry> + </row> + </tbody> + </tgroup> + </table> + + <table > + <title>Config Options For Consumer Behaviour</title> + <tgroup cols="4"> + <thead> + <row> + <entry>Property Name</entry> + <entry>Type</entry> + <entry>Default Value</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>max_prefetch</entry> + <entry>int</entry> + <entry>500</entry> + <entry>Maximum number of pre-fetched messages per consumer. <para>This can also be defaulted for consumers created on a particular connection using the <link linkend="section-jms-connection-url">Connection URL</link> options, or per destination (see the <varname>capacity</varname> option under link properties in addressing)</para></entry> + </row> + + <row> + <entry>qpid.session.max_ack_delay</entry> + <entry>long</entry> + <entry>1000 (ms)</entry> + <entry><para>Timer interval to flush message acks in buffer when using AUTO_ACK and DUPS_OK.</para> <para>When using the above ack modes, message acks are batched and sent if one of the following conditions are met (which ever happens first). + <itemizedlist> + <listitem><para>When the ack timer fires.</para></listitem> + <listitem><para>if un_acked_msg_count > max_prefetch/2.</para></listitem> + </itemizedlist> + </para> + <para>The ack timer can be disabled by setting it to 0.</para> + </entry> + </row> + + <row> + <entry>sync_ack</entry> + <entry>boolean</entry> + <entry>false</entry> + <entry><para>If set, each message will be acknowledged synchronously. When using AUTO_ACK mode, you need to set this to "true", in order to get the correct behaviour as described by the JMS spec.</para><para>This is set to false by default for performance reasons, therefore by default AUTO_ACK behaves similar to DUPS_OK.</para><para>This can also be set per connection using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para></entry> + </row> + </tbody> + </tgroup> + </table> + + <table > + <title>Config Options For Producer Behaviour</title> + <tgroup cols="4"> + <thead> + <row> + <entry>Property Name</entry> + <entry>Type</entry> + <entry>Default Value</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>sync_publish</entry> + <entry>string</entry> + <entry>"" (disabled)</entry> + <entry><para>If one of {persistent|all} is set then persistent messages or all messages will be sent synchronously.</para><para>This can also be set per connection using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para></entry> + </row> + </tbody> + </tgroup> + </table> + + <table > + <title>Config Options For Threading</title> + <tgroup cols="4"> + <thead> + <row> + <entry>Property Name</entry> + <entry>Type</entry> + <entry>Default Value</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>qpid.thread_factory</entry> + <entry>string</entry> + <entry>org.apache.qpid.thread.DefaultThreadFactory</entry> + <entry><para>Specifies the thread factory to use.</para><para>If using a real time JVM, you need to set the above property to <varname>org.apache.qpid.thread.RealtimeThreadFactory</varname>.</para></entry> + </row> + + <row> + <entry>qpid.rt_thread_priority</entry> + <entry>int</entry> + <entry>20</entry> + <entry><para>Specifies the priority (1-99) for Real time threads created by the real time thread factory.</para></entry> + </row> + </tbody> + </tgroup> + </table> + + <table > + <title>Config Options For I/O</title> + <tgroup cols="4"> + <thead> + <row> + <entry>Property Name</entry> + <entry>Type</entry> + <entry>Default Value</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>qpid.transport</entry> + <entry>string</entry> + <entry>org.apache.qpid.transport.network.io.IoNetworkTransport</entry> + <entry><para>The transport implementation to be used.</para><para>A user could specify an alternative transport mechanism that implements the interface <varname>org.apache.qpid.transport.network.OutgoingNetworkTransport</varname>.</para></entry> + </row> + <row> + <entry>qpid.sync_op_timeout</entry> + <entry>long</entry> + <entry>60000</entry> + <entry><para>The length of time (in milliseconds) to wait for a synchronous operation to complete.</para><para>For compatibility with older clients, the synonym <varname>amqj.default_syncwrite_timeout</varname> is supported.</para></entry> + </row> + <row> + <entry>qpid.tcp_nodelay</entry> + <entry>boolean</entry> + <entry>true</entry> + <entry> + <para>Sets the TCP_NODELAY property of the underlying socket. The default was changed to true as of Qpid 0.14.</para> + <para>This can also be set per connection using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para> + <para>For compatibility with older clients, the synonym <varname>amqj.tcp_nodelay</varname> is supported.</para> + </entry> + </row> + <row> + <entry>qpid.send_buffer_size</entry> + <entry>integer</entry> + <entry>65535</entry> + <entry> + <para>Sets the SO_SNDBUF property of the underlying socket. Added in Qpid 0.16.</para> + <para>For compatibility with older clients, the synonym <varname>amqj.sendBufferSize</varname> is supported.</para> + </entry> + </row> + <row> + <entry>qpid.receive_buffer_size</entry> + <entry>integer</entry> + <entry>65535</entry> + <entry> + <para>Sets the SO_RCVBUF property of the underlying socket. Added in Qpid 0.16.</para> + <para>For compatibility with older clients, the synonym <varname>amqj.receiveBufferSize</varname> is supported.</para> + </entry> + </row> + <row> + <entry>qpid.failover_method_timeout</entry> + <entry>long</entry> + <entry>60000</entry> + <entry> + <para>During failover, this is the timeout for each attempt to try to re-establish the connection. + If a reconnection attempt exceeds the timeout, the entire failover process is aborted.</para> + <para>It is only applicable for AMQP 0-8/0-9/0-9-1 clients.</para> + </entry> + </row> + </tbody> + </tgroup> + </table> + + <table > + <title>Config Options For Security</title> + <tgroup cols="4"> + <thead> + <row> + <entry>Property Name</entry> + <entry>Type</entry> + <entry>Default Value</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>qpid.sasl_mechs</entry> + <entry>string</entry> + <entry>PLAIN</entry> + <entry><para>The SASL mechanism to be used. More than one could be specified as a comma separated list.</para><para>We currently support the following mechanisms {PLAIN | GSSAPI | EXTERNAL}.</para><para>This can also be set per connection using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para></entry> + </row> + + <row> + <entry>qpid.sasl_protocol</entry> + <entry>string</entry> + <entry>AMQP</entry> + <entry><para>When using GSSAPI as the SASL mechanism, <varname>sasl_protocol</varname> must be set to the principal for the qpidd broker, e.g. <varname>qpidd</varname>.</para><para>This can also be set per connection using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para></entry> + </row> + + <row> + <entry>qpid.sasl_server_name</entry> + <entry>string</entry> + <entry>localhost</entry> + <entry><para>When using GSSAPI as the SASL mechanism, <varname>sasl_server</varname> must be set to the host for the SASL server, e.g. <varname>example.com</varname>.</para><para>This can also be set per connection using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para></entry> + </row> + </tbody> + </tgroup> + </table> + + <table> + <title>Config Options For Security - Standard JVM properties needed when using GSSAPI as the SASL mechanism.<footnote><para>Please refer to the Java security documentation for a complete understanding of the above properties.</para></footnote></title> + <tgroup cols="4"> + <thead> + <row> + <entry>Property Name</entry> + <entry>Type</entry> + <entry>Default Value</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>javax.security.auth.useSubjectCredsOnly</entry> + <entry>boolean</entry> + <entry>true</entry> + <entry><para>If set to 'false', forces the SASL GASSPI client to obtain the kerberos credentials explicitly instead of obtaining from the "subject" that owns the current thread.</para></entry> + </row> + + <row> + <entry>java.security.auth.login.config</entry> + <entry>string</entry> + <entry></entry> + <entry><para>Specifies the jass configuration file.</para><para><varname>Ex-Djava.security.auth.login.config=myjas.conf</varname> + </para><para>Here is the sample myjas.conf JASS configuration file: <programlisting><![CDATA[ + + com.sun.security.jgss.initiate { + com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true; + }; + + ]]></programlisting></para></entry> + </row> + </tbody> + </tgroup> + </table> + + <table> + <title>Config Options For Security - Using SSL for securing connections or using EXTERNAL as the SASL mechanism.</title> + <tgroup cols="4"> + <thead> + <row> + <entry>Property Name</entry> + <entry>Type</entry> + <entry>Default Value</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>qpid.ssl_timeout</entry> + <entry>long</entry> + <entry>60000</entry> + <entry><para>Timeout value used by the Java SSL engine when waiting on operations.</para></entry> + </row> + + <row> + <entry>qpid.ssl.KeyManagerFactory.algorithm</entry> + <entry>string</entry> + <entry>-</entry> + <entry> + <para>The key manager factory algorithm name. If not set, defaults to the value returned from the Java runtime call <literal>KeyManagerFactory.getDefaultAlgorithm()</literal></para> + <para>For compatibility with older clients, the synonym <varname>qpid.ssl.keyStoreCertType</varname> is supported.</para> + </entry> + </row> + + <row> + <entry>qpid.ssl.TrustManagerFactory.algorithm</entry> + <entry>string</entry> + <entry>-</entry> + <entry> + <para>The trust manager factory algorithm name. If not set, defaults to the value returned from the Java runtime call <literal>TrustManagerFactory.getDefaultAlgorithm()</literal></para> + <para>For compatibility with older clients, the synonym <varname>qpid.ssl.trustStoreCertType</varname> is supported.</para> + </entry> + </row> + </tbody> + </tgroup> + </table> + + <table> + <title>Config Options For Security - Standard JVM properties needed when Using SSL for securing connections or using EXTERNAL as the SASL mechanism.<footnote><para>Qpid allows you to have per connection key and trust stores if required. If specified per connection, the JVM arguments are ignored.</para></footnote></title> + <tgroup cols="4"> + <thead> + <row> + <entry>Property Name</entry> + <entry>Type</entry> + <entry>Default Value</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>javax.net.ssl.keyStore</entry> + <entry>string</entry> + <entry>jvm default</entry> + <entry><para>Specifies the key store path.</para><para>This can also be set per connection using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para></entry> + </row> + + <row> + <entry>javax.net.ssl.keyStorePassword</entry> + <entry>string</entry> + <entry>jvm default</entry> + <entry><para>Specifies the key store password.</para><para>This can also be set per connection using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para></entry> + </row> + + <row> + <entry>javax.net.ssl.trustStore</entry> + <entry>string</entry> + <entry>jvm default</entry> + <entry><para>Specifies the trust store path.</para><para>This can also be set per connection using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para></entry> + </row> + + <row> + <entry>javax.net.ssl.trustStorePassword</entry> + <entry>string</entry> + <entry>jvm default</entry> + <entry><para>Specifies the trust store password.</para><para>This can also be set per connection using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + </section> + + </chapter> + + <chapter id="QpidWCF"> + <title>Using the Qpid WCF client</title> + <section> + <title>XML and Binary Bindings</title> + + <para>The Qpid WCF client provides two bindings, each with support for + Windows .NET transactions.</para> + + <para>The AmqpBinding is suitable for communication between two WCF + applications. By default it uses the WCF binary .NET XML encoder + (BinaryMessageEncodingBindingElement) for efficient message + transmission, but it can also use the text and Message Transmission + Optimization Mechanism (MTOM) encoders. Here is a traditional service + model sample program using the AmqpBinding. It assumes that the queue + "hello_service_node" has been created and configured on the AMQP + broker.</para> + + <example><?dbfo keep-together="auto" ?> + <title>Traditional service model "Hello world!" example</title> + <programlisting><![CDATA[ + namespace Apache.Qpid.Documentation.HelloService + { + using System; + using System.ServiceModel; + using System.ServiceModel.Channels; + using System.Threading; + using Apache.Qpid.Channel; + + [ServiceContract] + public interface IHelloService + { + [OperationContract(IsOneWay = true, Action = "*")] + void SayHello(string greeting); + } + + public class HelloService : IHelloService + { + private static int greetingCount; + + public static int GreetingCount + { + get { return greetingCount; } + } + + public void SayHello(string greeting) + { + Console.WriteLine("Service received: " + greeting); + greetingCount++; + }]]></programlisting> + + <programlisting><![CDATA[ + static void Main(string[] args) + { + try + { + AmqpBinding amqpBinding = new AmqpBinding(); + amqpBinding.BrokerHost = "localhost"; + amqpBinding.BrokerPort = 5672; + + ServiceHost serviceHost = new ServiceHost(typeof(HelloService)); + serviceHost.AddServiceEndpoint(typeof(IHelloService), + amqpBinding, "amqp:hello_service_node"); + serviceHost.Open(); + + // Send the service a test greeting + Uri amqpClientUri=new Uri("amqp:amq.direct?routingkey=hello_service_node"); + EndpointAddress clientEndpoint = new EndpointAddress(amqpClientUri); + ChannelFactory<IHelloService> channelFactory = + new ChannelFactory<IHelloService>(amqpBinding, clientEndpoint); + IHelloService clientProxy = channelFactory.CreateChannel(); + + clientProxy.SayHello("Greetings from WCF client"); + + // wait for service to process the greeting + while (HelloService.GreetingCount == 0) + { + Thread.Sleep(100); + } + channelFactory.Close(); + serviceHost.Close(); + } + catch (Exception e) + { + Console.WriteLine("Exception: {0}", e); + } + } + } + } + ]]></programlisting> + </example> + + <para>The second binding, AmqpBinaryBinding, is suitable for WCF + applications that need to inter-operate with non-WCF clients or that + wish to have direct access to the raw wire representation of the + message body. It relies on a custom encoder to read and write raw + (binary) content which operates similarly to the ByteStream encoder + (introduced in .NET 4.0). The encoder presents an abstract XML + infoset view of the raw message content on input. On output, the + encoder does the reverse and peels away the XML infoset layer exposing + the raw content to the wire representation of the message body. The + application must do the inverse of what the encoder does to allow the + XML infoset wrapper to cancel properly. This is demonstrated in the + following sample code (using the channel programming model) which + directly manipulates or provides callbacks to the WCF message readers + and writers when the content is consumed. In contrast to the + AmqpBinding sample where the simple greeting is encapsulated in a + compressed SOAP envelope, the wire representation of the message + contains the raw content and is identical and fully interoperable with + the Qpid C++ "Hello world!" example.</para> + + <example><?dbfo keep-together="auto" ?> + <title>Binary "Hello world!" example using the channel model</title> + <programlisting><![CDATA[ + namespace Apache.Qpid.Samples.Channel.HelloWorld + { + using System; + using System.ServiceModel; + using System.ServiceModel.Channels; + using System.ServiceModel.Description; + using System.Text; + using System.Xml; + using Apache.Qpid.Channel; + + public class HelloWorld + { + static void Main(string[] args) + { + String broker = "localhost"; + int port = 5672; + String target = "amq.topic"; + String source = "my_topic_node"; + + if (args.Length > 0) + { + broker = args[0]; + } + + if (args.Length > 1) + { + port = int.Parse(args[1]); + } + + if (args.Length > 2) + { + target = args[2]; + } + + if (args.Length > 3) + { + source = args[3]; + } + + AmqpBinaryBinding binding = new AmqpBinaryBinding(); + binding.BrokerHost = broker; + binding.BrokerPort = port; + + IChannelFactory<IInputChannel> receiverFactory = binding.BuildChannelFactory<IInputChannel>(); + receiverFactory.Open(); + IInputChannel receiver = receiverFactory.CreateChannel(new EndpointAddress("amqp:" + source)); + receiver.Open(); + + IChannelFactory<IOutputChannel> senderFactory = binding.BuildChannelFactory<IOutputChannel>(); + senderFactory.Open(); + IOutputChannel sender = senderFactory.CreateChannel(new EndpointAddress("amqp:" + target)); + sender.Open(); + + sender.Send(Message.CreateMessage(MessageVersion.None, "", new HelloWorldBinaryBodyWriter())); + + Message message = receiver.Receive(); + XmlDictionaryReader reader = message.GetReaderAtBodyContents(); + while (!reader.HasValue) + { + reader.Read(); + } + + byte[] binaryContent = reader.ReadContentAsBase64(); + string text = Encoding.UTF8.GetString(binaryContent); + + Console.WriteLine(text); + + senderFactory.Close(); + receiverFactory.Close(); + } + } + + public class HelloWorldBinaryBodyWriter : BodyWriter + { + public HelloWorldBinaryBodyWriter() : base (true) {} + + protected override void OnWriteBodyContents(XmlDictionaryWriter writer) + { + byte[] binaryContent = Encoding.UTF8.GetBytes("Hello world!"); + + // wrap the content: + writer.WriteStartElement("Binary"); + writer.WriteBase64(binaryContent, 0, binaryContent.Length); + } + } + } + ]]></programlisting> + </example> + + <para>Bindings define ChannelFactories and ChannelListeners associated with + an AMQP Broker. WCF will frequently automatically create and manage + the life cycle of a these and the resulting IChannel objects used in + message transfer. The binding parameters that can be set are:</para> + + <table pgwide="1"> + <title>WCF Binding Parameters</title> + <tgroup cols="3"> + <thead> + <colspec colnum="1" colwidth="1*"/> + <colspec colnum="2" colwidth="3*"/> + <colspec colnum="3" colwidth="3*"/> + <row> + <entry>Parameter</entry> + <entry>Default</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry> + BrokerHost + </entry> + <entry> + localhost + </entry> + <entry> + The broker's server name. Currently the WCF channel + only supports connections with a single broker. + Failover to multiple brokers will be provided in the + future. + </entry> + </row> + + <row> + <entry> + BrokerPort + </entry> + <entry> + 5672 + </entry> + <entry> + The port the broker is listening on. + </entry> + </row> + + <row> + <entry> + PrefetchLimit + </entry> + <entry> + 0 + </entry> + <entry> + The number of messages to prefetch from the amqp + broker before the application actually consumes them. + Increasing this number can dramatically increase the + read performance in some circumstances. + </entry> + </row> + + <row> + <entry> + Shared + </entry> + <entry> + false + </entry> + <entry> + Indicates if separate channels to the same broker can + share an underlying AMQP tcp connection (provided they + also share the same authentication credentials). + </entry> + </row> + + <row> + <entry> + TransferMode + </entry> + <entry> + buffered + </entry> + <entry> + Indicates whether the channel's encoder uses the WCF + BufferManager cache to temporarily store message + content during the encoding/decoding phase. For small + to medium sized SOAP based messages, buffered is + usually the preferred choice. For binary messages, + streamed TransferMode is the more efficient mode. + </entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section> + <title>Endpoints</title> + + <para>In Qpid 0.6 the WCF Endpoints map to simple AMQP 0-10 + exchanges (IOutputChannel) or AMQP 0-10 queues (IInputChannel). + The format for an IOutputChannel is</para> + + <programlisting><![CDATA[ + "amqp:amq.direct" or "amqp:my_exchange?routingkey=my_routing_key" +]]></programlisting> + + <para>and for an IInputChannel is</para> + + <programlisting><![CDATA[ + "amqp:my_queue" +]]></programlisting> + + <para>The routing key is in fact a default value associated with + the particular channel. Outgoing messages can always have their + routing key uniquely set.</para> + + <para>If the respective queue or exchange doesn't exist, an exception + is thrown when opening the channel. Queues and exchanges can be + created and configured using qpid-config.</para> + + </section> + + <section> + <title>Message Headers</title> + + <para>AMQP specific message headers can be set on or retrieved + from the ServiceModel.Channels.Message using the AmqpProperties + type.</para> + + <para>For example, on output:</para> + + <programlisting><![CDATA[ +AmqpProperties props = new AmqpProperties(); +props.Durable = true; +props.PropertyMap.Add("my_custom_header", new AmqpString("a custom value")); +Message msg = Message.CreateMessage(args); +msg.Properties.Add("AmqpProperties", amqpProperties); +outputChannel.Send(msg); +]]></programlisting> + + <para>On input the headers can be accessed from the Message or extracted + from the operation context</para> + + <programlisting><![CDATA[ +public void SayHello(string greeting) +{ + AmqpProperties props = (AmqpProperties) OperationContext. + Current.IncomingMessageProperties["AmqpProperties"]; + AmqpString extra = (AmqpString) props.PropertyMap["my_custom_header"]; + Console.WriteLine("Service received: {0} and {1}", greeting, extra); +} +]]></programlisting> + + </section> + + <section> + <title>Security</title> + + <para>To engage TLS/SSL:</para> + + <programlisting><![CDATA[ +binding.Security.Mode = AmqpSecurityMode.Transport; +binding.Security.Transport.UseSSL = true; +binding.BrokerPort = 5671; +]]></programlisting> + + <para>Currently the WCF client only provides SASL PLAIN (i.e. username and + password) authentication. To provide a username and password, you can + set the DefaultAmqpCredential value in the binding. This value can be + overridden or set for a binding's channel factories and listeners, + either by setting the ClientCredentials as a binding parameter, or by + using an AmqpCredential as a binding parameter. The search order for + credentials is the AmqpCredential binding parameter, followed by the + ClientCredentials (unless IgnoreEndpointClientCredentials has been + set), and finally defaulting to the DefaultAmqpCredential of the + binding itself. Here is a sample using ClientCredentials:</para> + + <programlisting><![CDATA[ +ClientCredentials credentials = new ClientCredentials(); +credentials.UserName.UserName = "guest"; +credentials.UserName.Password = "guest"; +bindingParameters = new BindingParameterCollection(); +bindingParameters.Add(credentials); +readerFactory = binding.BuildChannelFactory<IInputChannel>(bindingParameters); +]]></programlisting> + + </section> + + <section> + <title>Transactions</title> + + <para>The WCF channel provides a transaction resource manager + module and a recovery module that together provide distributed + transaction support with one-phase optimization. Some + configuration is required on Windows machines to enable + transaction support (see your installation notes or top level + ReadMe.txt file for instructions). Once properly configured, + the Qpid WCF channel acts as any other System.Transactions aware + resource, capable of participating in explicit or implicit + transactions.</para> + + <para>Server code:</para> + + <programlisting><![CDATA[ +[OperationBehavior(TransactionScopeRequired = true, + TransactionAutoComplete = true)] + +public void SayHello(string greeting) +{ + // increment ExactlyOnceReceived counter on DB + + // Success: transaction auto completes: +} +]]></programlisting> + + <para>Because this operation involves two transaction resources, the + database and the AMQP message broker, this operates as a full two + phase commit transaction managed by the Distributed Transaction + Coordinator service. If the transaction proceeds without error, + both ExactlyOnceReceived is incremented in the database and the AMQP + message is consumed from the broker. Otherwise, ExactlyOnceReceived is + unchanged and AMQP message is returned to its queue on the broker.</para> + + <para>For the client code a few changes are made to the non-transacted + example. For "exactly once" semantics, we set the AMQP "Durable" + message property and enclose the transacted activities in a + TransactionScope:</para> + + <programlisting><![CDATA[ +AmqpProperties myDefaults = new AmqpProperties(); +myDefaults.Durable = true; +amqpBinding.DefaultMessageProperties = myDefaults; +ChannelFactory<IHelloService> channelFactory = +new ChannelFactory<IHelloService>(amqpBinding, clientEndpoint); +IHelloService clientProxy = channelFactory.CreateChannel(); + +using (TransactionScope ts = new TransactionScope()) +{ + AmqpProperties amqpProperties = new AmqpProperties(); + clientProxy.SayHello("Greetings from WCF client"); + // increment ExactlyOnceSent counter on DB + ts.Complete(); +} +]]></programlisting> + + </section> + </chapter> + + <chapter> + <title>The .NET Binding for the C++ Messaging Client</title> + <para> + The .NET Binding for the C++ Qpid Messaging Client is a library that gives + any .NET program access to Qpid C++ Messaging objects and methods. + </para> + <section> + <title>.NET Binding for the C++ Messaging Client Component Architecture</title> + + <programlisting><![CDATA[ + +----------------------------+ + | Dotnet examples | + | Managed C# | + +------+---------------+-----+ + | | + V | + +---------------------------+ | + | .NET Managed Callback | | + | org.apache.qpid.messaging.| | + | sessionreceiver.dll | | + +----------------------+----+ | + | | +managed V V +(.NET) +--------------------------------+ +:::::::::::::::::::::::| .NET Binding Library |:::::::::::: +unmanaged | org.apache.qpid.messaging.dll | +(Native Win32/64) +---------------+----------------+ + | + | + +----------------+ | + | Native examples| | + | Unmanaged C++ | | + +--------+-------+ | + | | + V V + +----------------------------------+ + | QPID Messaging C++ Libraries | + | qpid*.dll qmf*.dll | + +--------+--------------+----------+ +]]></programlisting> + + +<para>This diagram illustrates the code and library components of the binding +and the hierarchical relationships between them.</para> + + <table id="table-Dotnet-Binding-Component-Architecture" > + <title>.NET Binding for the C++ Messaging Client Component Architecture</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Component Name</entry> + <entry>Component Function</entry> + </row> + </thead> + <tbody> + <row> + <entry>QPID Messaging C++ Libraries</entry> + <entry>The QPID Messaging C++ core run time system</entry> + </row> + <row> + <entry>Unmanaged C++ Example Source Programs</entry> + <entry>Ordinary C++ programs that illustrate using qpid/cpp Messaging directly + in a native Windows environment.</entry> + </row> + <row> + <entry>.NET Messaging Binding Library</entry> + <entry>The .NET Messaging Binding library provides interoprability between + managed .NET programs and the unmanaged, native Qpid Messaging C++ core + run time system. .NET programs create a Reference to this library thereby + exposing all of the native C++ Messaging functionality to programs + written in any .NET language.</entry> + </row> + <row> + <entry>.NET Messaging Managed Callback Library</entry> + <entry>An extension of the .NET Messaging Binding Library that provides message + callbacks in a managed .NET environment.</entry> + </row> + <row> + <entry>Managed C# .NET Example Source Programs</entry> + <entry>Various C# example programs that illustrate using .NET Binding for C++ Messaging in the .NET environment.</entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section> + <title>.NET Binding for the C++ Messaging Client Examples</title> + + <para>This chapter describes the various sample programs that + are available to illustrate common Qpid Messaging usage.</para> + + <table id="table-Dotnet-Binding-Example-Client-Server"> + <title>Example : Client - Server</title> + <tgroup cols="2"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <thead> + <row> + <entry>Example Name</entry> + <entry>Example Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>csharp.example.server</entry> + <entry>Creates a Receiver and listens for messages. + Upon message reception the message content is converted to upper case + and forwarded to the received message's ReplyTo address.</entry> + </row> + <row> + <entry>csharp.example.client</entry> + <entry>Sends a series of messages to the Server and prints the original message + content and the received message content.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table id="table-Dotnet-Binding-Example-MapSender-MapReceiver"> + <title>Example : Map Sender – Map Receiver</title> + <tgroup cols="2"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <thead> + <row> + <entry>Example Name</entry> + <entry>Example Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>csharp.map.receiver</entry> + <entry>Creates a Receiver and listens for a map message. + Upon message reception the message is decoded and displayed on the console.</entry> + </row> + <row> + <entry>csharp.map.sender</entry> + <entry>Creates a map message and sends it to map.receiver. + The map message contains values for every supported .NET Messaging + Binding data type.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table id="table-Dotnet-Binding-Example-Spout-Drain"> + <title>Example : Spout - Drain</title> + <tgroup cols="2"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <thead> + <row> + <entry>Example Name</entry> + <entry>Example Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>csharp.example.spout</entry> + <entry>Spout is a more complex example of code that generates a series of messages + and sends them to peer program Drain. Flexible command line arguments allow + the user to specify a variety of message and program options.</entry> + </row> + <row> + <entry>csharp.example.drain</entry> + <entry>Drain is a more complex example of code that receives a series of messages + and displays their contents on the console.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table id="table-Dotnet-Binding-Example-CallbackSender-CallbackReceiver"> + <title>Example : Map Callback Sender – Map Callback Receiver</title> + <tgroup cols="2"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <thead> + <row> + <entry>Example Name</entry> + <entry>Example Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>csharp.map.callback.receiver</entry> + <entry>Creates a Receiver and listens for a map message. + Upon message reception the message is decoded and displayed on the console. + This example illustrates the use of the C# managed code callback mechanism + provided by .NET Messaging Binding Managed Callback Library.</entry> + </row> + <row> + <entry>csharp.map.callback.sender</entry> + <entry>Creates a map message and sends it to map_receiver. + The map message contains values for every supported .NET Messaging + Binding data type.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table id="table-Dotnet-Binding-Example-DeclareQueues"> + <title>Example - Declare Queues</title> + <tgroup cols="2"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <thead> + <row> + <entry>Example Name</entry> + <entry>Example Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>csharp.example.declare_queues</entry> + <entry>A program to illustrate creating objects on a broker. + This program creates a queue used by spout and drain.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table id="table-Dotnet-Binding-Example-DirectSender-DirectReceiver"> + <title>Example: Direct Sender - Direct Receiver</title> + <tgroup cols="2"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <thead> + <row> + <entry>Example Name</entry> + <entry>Example Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>csharp.direct.receiver</entry> + <entry>Creates a Receiver and listens for a messages. + Upon message reception the message is decoded and displayed on the console.</entry> + </row> + <row> + <entry>csharp.direct.sender</entry> + <entry> Creates a series of messages and sends them to csharp.direct.receiver.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table id="table-Dotnet-Binding-Example-Helloworld"> + <title>Example: Hello World</title> + <tgroup cols="2"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <thead> + <row> + <entry>Example Name</entry> + <entry>Example Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>csharp.example.helloworld</entry> + <entry>A program to send a message and to receive the same message.</entry> + </row> + </tbody> + </tgroup> + </table> + + </section> + + <section> + <title>.NET Binding Class Mapping to Underlying C++ Messaging API</title> + + <para>This chapter describes the specific mappings between + classes in the .NET Binding and the underlying C++ Messaging + API.</para> + + <section> + <title>.NET Binding for the C++ Messaging API Class: Address</title> + <table id="table-Dotnet-Binding-Address"> + <title>.NET Binding for the C++ Messaging API Class: Address</title> + <tgroup cols="2"> + <colspec colname="c1" colwidth="1*"/> + <colspec colname="c2" colwidth="7*"/> + <thead> + <row> + <entry namest="c1" nameend="c2" align="center">.NET Binding Class: Address</entry> + </row> + <row> + <entry>Language</entry> + <entry>Syntax</entry> + </row> + </thead> + <tbody> + <row> + <entry>C++</entry> + <entry>class Address</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public ref class Address</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Constructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>Address();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Address();</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Constructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>Address(const std::string& address);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Address(string address);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Constructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>Address(const std::string& name, const std::string& subject, const qpid::types::Variant::Map& options, const std::string& type = "");</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Address(string name, string subject, Dictionary<string, object> options);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Address(string name, string subject, Dictionary<string, object> options, string type);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Copy constructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>Address(const Address& address);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Address(Address address);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Destructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>~Address();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>~Address();</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Finalizer</entry> + </row> + <row> + <entry>C++</entry> + <entry>n/a</entry> + </row> + <row> + <entry>.NET</entry> + <entry>!Address();</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Copy assignment operator</entry> + </row> + <row> + <entry>C++</entry> + <entry>Address& operator=(const Address&);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Address op_Assign(Address rhs);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: Name</entry> + </row> + <row> + <entry>C++</entry> + <entry>const std::string& getName() const;</entry> + </row> + <row> + <entry>C++</entry> + <entry>void setName(const std::string&);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public string Name { get; set; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: Subject</entry> + </row> + <row> + <entry>C++</entry> + <entry>const std::string& getSubject() const;</entry> + </row> + <row> + <entry>C++</entry> + <entry>void setSubject(const std::string&);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public string Subject { get; set; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: Options</entry> + </row> + <row> + <entry>C++</entry> + <entry>const qpid::types::Variant::Map& getOptions() const;</entry> + </row> + <row> + <entry>C++</entry> + <entry>qpid::types::Variant::Map& getOptions();</entry> + </row> + <row> + <entry>C++</entry> + <entry>void setOptions(const qpid::types::Variant::Map&);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Dictionary<string, object> Options { get; set; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: Type</entry> + </row> + <row> + <entry>C++</entry> + <entry>std::string getType() const;</entry> + </row> + <row> + <entry>C++</entry> + <entry>void setType(const std::string&);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public string Type { get; set; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Miscellaneous</entry> + </row> + <row> + <entry>C++</entry> + <entry>std::string str() const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public string ToStr();</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Miscellaneous</entry> + </row> + <row> + <entry>C++</entry> + <entry>operator bool() const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>n/a</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Miscellaneous</entry> + </row> + <row> + <entry>C++</entry> + <entry>bool operator !() const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>n/a</entry> + </row> + </tbody> + </tgroup> + </table> + </section> + <section> + <title>.NET Binding for the C++ Messaging API Class: Connection</title> + <table id="table-Dotnet-Binding-Connection"> + <title>.NET Binding for the C++ Messaging API Class: Connection</title> + <tgroup cols="2"> + <colspec colname="c1" colwidth="1*"/> + <colspec colname="c2" colwidth="7*"/> + <thead> + <row> + <entry namest="c1" nameend="c2" align="center">.NET Binding Class: Connection</entry> + </row> + <row> + <entry>Language</entry> + <entry>Syntax</entry> + </row> + </thead> + <tbody> + <row> + <entry>C++</entry> + <entry>class Connection : public qpid::messaging::Handle<ConnectionImpl></entry> + </row> + <row> + <entry>.NET</entry> + <entry>public ref class Connection</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Constructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>Connection(ConnectionImpl* impl);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>n/a</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Constructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>Connection();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>n/a</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Constructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>Connection(const std::string& url, const qpid::types::Variant::Map& options = qpid::types::Variant::Map());</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Connection(string url);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Connection(string url, Dictionary<string, object> options);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Constructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>Connection(const std::string& url, const std::string& options);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Connection(string url, string options); </entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Copy Constructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>Connection(const Connection&);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Connection(Connection connection);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Destructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>~Connection();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>~Connection();</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Finalizer</entry> + </row> + <row> + <entry>C++</entry> + <entry>n/a</entry> + </row> + <row> + <entry>.NET</entry> + <entry>!Connection();</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Copy assignment operator</entry> + </row> + <row> + <entry>C++</entry> + <entry>Connection& operator=(const Connection&);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Connection op_Assign(Connection rhs);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: SetOption</entry> + </row> + <row> + <entry>C++</entry> + <entry>void setOption(const std::string& name, const qpid::types::Variant& value);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void SetOption(string name, object value);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: open</entry> + </row> + <row> + <entry>C++</entry> + <entry>void open();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void Open();</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: isOpen</entry> + </row> + <row> + <entry>C++</entry> + <entry>bool isOpen();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public bool IsOpen { get; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: close</entry> + </row> + <row> + <entry>C++</entry> + <entry>void close();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void Close();</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: createTransactionalSession</entry> + </row> + <row> + <entry>C++</entry> + <entry>Session createTransactionalSession(const std::string& name = std::string());</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Session CreateTransactionalSession();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Session CreateTransactionalSession(string name);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: createSession</entry> + </row> + <row> + <entry>C++</entry> + <entry>Session createSession(const std::string& name = std::string());</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Session CreateSession();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Session CreateSession(string name);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: getSession</entry> + </row> + <row> + <entry>C++</entry> + <entry>Session getSession(const std::string& name) const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Session GetSession(string name);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: AuthenticatedUsername</entry> + </row> + <row> + <entry>C++</entry> + <entry>std::string getAuthenticatedUsername();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public string GetAuthenticatedUsername();</entry> + </row> + </tbody> + </tgroup> + </table> + </section> + <section> + <title>.NET Binding for the C++ Messaging API Class: Duration</title> + <table id="table-Dotnet-Binding-Duration"> + <title>.NET Binding for the C++ Messaging API Class: Duration</title> + <tgroup cols="2"> + <colspec colname="c1" colwidth="1*"/> + <colspec colname="c2" colwidth="7*"/> + <thead> + <row> + <entry namest="c1" nameend="c2" align="center">.NET Binding Class: Duration</entry> + </row> + <row> + <entry>Language</entry> + <entry>Syntax</entry> + </row> + </thead> + <tbody> + <row> + <entry>C++</entry> + <entry>class Duration</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public ref class Duration</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Constructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>explicit Duration(uint64_t milliseconds);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Duration(ulong mS);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Copy constructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>n/a</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Duration(Duration rhs);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Destructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>default</entry> + </row> + <row> + <entry>.NET</entry> + <entry>default</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Finalizer</entry> + </row> + <row> + <entry>C++</entry> + <entry>n/a</entry> + </row> + <row> + <entry>.NET</entry> + <entry>default</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: Milliseconds</entry> + </row> + <row> + <entry>C++</entry> + <entry>uint64_t getMilliseconds() const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public ulong Milliseconds { get; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Operator: *</entry> + </row> + <row> + <entry>C++</entry> + <entry>Duration operator*(const Duration& duration, uint64_t multiplier);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public static Duration operator *(Duration dur, ulong multiplier);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public static Duration Multiply(Duration dur, ulong multiplier);</entry> + </row> + <row> + <entry>C++</entry> + <entry>Duration operator*(uint64_t multiplier, const Duration& duration);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public static Duration operator *(ulong multiplier, Duration dur);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public static Duration Multiply(ulong multiplier, Duration dur);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Constants</entry> + </row> + <row> + <entry>C++</entry> + <entry>static const Duration FOREVER;</entry> + </row> + <row> + <entry>C++</entry> + <entry>static const Duration IMMEDIATE;</entry> + </row> + <row> + <entry>C++</entry> + <entry>static const Duration SECOND;</entry> + </row> + <row> + <entry>C++</entry> + <entry>static const Duration MINUTE;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public sealed class DurationConstants</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public static Duration FORVER;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public static Duration IMMEDIATE;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public static Duration MINUTE;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public static Duration SECOND;</entry> + </row> + </tbody> + </tgroup> + </table> + </section> + <section> + <title>.NET Binding for the C++ Messaging API Class: FailoverUpdates</title> + <table id="table-Dotnet-Binding-FailoverUpdates"> + <title>.NET Binding for the C++ Messaging API Class: FailoverUpdates</title> + <tgroup cols="2"> + <colspec colname="c1" colwidth="1*"/> + <colspec colname="c2" colwidth="7*"/> + <thead> + <row> + <entry namest="c1" nameend="c2" align="center">.NET Binding Class: FailoverUpdates</entry> + </row> + <row> + <entry>Language</entry> + <entry>Syntax</entry> + </row> + </thead> + <tbody> + <row> + <entry>C++</entry> + <entry>class FailoverUpdates</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public ref class FailoverUpdates</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Constructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>FailoverUpdates(Connection& connection);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public FailoverUpdates(Connection connection);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Destructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>~FailoverUpdates();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>~FailoverUpdates();</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Finalizer</entry> + </row> + <row> + <entry>C++</entry> + <entry>n/a</entry> + </row> + <row> + <entry>.NET</entry> + <entry>!FailoverUpdates();</entry> + </row> + </tbody> + </tgroup> + </table> + </section> + <section> + <title>.NET Binding for the C++ Messaging API Class: Message</title> + <table id="table-Dotnet-Binding-Message"> + <title>.NET Binding for the C++ Messaging API Class: Message</title> + <tgroup cols="2"> + <colspec colname="c1" colwidth="1*"/> + <colspec colname="c2" colwidth="7*"/> + <thead> + <row> + <entry namest="c1" nameend="c2" align="center">.NET Binding Class: Message</entry> + </row> + <row> + <entry>Language</entry> + <entry>Syntax</entry> + </row> + </thead> + <tbody> + <row> + <entry>C++</entry> + <entry>class Message</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public ref class Message</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Constructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>Message(const std::string& bytes = std::string());</entry> + </row> + <row> + <entry>.NET</entry> + <entry>Message();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>Message(System::String ^ theStr);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>Message(System::Object ^ theValue);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>Message(array<System::Byte> ^ bytes);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Constructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>Message(const char*, size_t);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Message(byte[] bytes, int offset, int size);</entry> + </row> + <row> + <entry> </entry> + <entry>Copy constructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>Message(const Message&);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Message(Message message);</entry> + </row> + <row> + <entry> </entry> + <entry>Copy assignment operator</entry> + </row> + <row> + <entry>C++</entry> + <entry>Message& operator=(const Message&);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Message op_Assign(Message rhs);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Destructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>~Message();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>~Message();</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Finalizer</entry> + </row> + <row> + <entry>C++</entry> + <entry>n/a</entry> + </row> + <row> + <entry>.NET</entry> + <entry>!Message()</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: ReplyTo</entry> + </row> + <row> + <entry>C++</entry> + <entry>void setReplyTo(const Address&);</entry> + </row> + <row> + <entry>C++</entry> + <entry>const Address& getReplyTo() const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Address ReplyTo { get; set; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: Subject</entry> + </row> + <row> + <entry>C++</entry> + <entry>void setSubject(const std::string&);</entry> + </row> + <row> + <entry>C++</entry> + <entry>const std::string& getSubject() const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public string Subject { get; set; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: ContentType</entry> + </row> + <row> + <entry>C++</entry> + <entry>void setContentType(const std::string&);</entry> + </row> + <row> + <entry>C++</entry> + <entry>const std::string& getContentType() const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public string ContentType { get; set; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: MessageId</entry> + </row> + <row> + <entry>C++</entry> + <entry>void setMessageId(const std::string&);</entry> + </row> + <row> + <entry>C++</entry> + <entry>const std::string& getMessageId() const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public string MessageId { get; set; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: UserId</entry> + </row> + <row> + <entry>C++</entry> + <entry>void setUserId(const std::string&);</entry> + </row> + <row> + <entry>C++</entry> + <entry>const std::string& getUserId() const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public string UserId { get; set; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: CorrelationId</entry> + </row> + <row> + <entry>C++</entry> + <entry>void setCorrelationId(const std::string&);</entry> + </row> + <row> + <entry>C++</entry> + <entry>const std::string& getCorrelationId() const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public string CorrelationId { get; set; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: Priority</entry> + </row> + <row> + <entry>C++</entry> + <entry>void setPriority(uint8_t);</entry> + </row> + <row> + <entry>C++</entry> + <entry>uint8_t getPriority() const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public byte Priority { get; set; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: Ttl</entry> + </row> + <row> + <entry>C++</entry> + <entry>void setTtl(Duration ttl);</entry> + </row> + <row> + <entry>C++</entry> + <entry>Duration getTtl() const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Duration Ttl { get; set; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: Durable</entry> + </row> + <row> + <entry>C++</entry> + <entry>void setDurable(bool durable);</entry> + </row> + <row> + <entry>C++</entry> + <entry>bool getDurable() const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public bool Durable { get; set; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: Redelivered</entry> + </row> + <row> + <entry>C++</entry> + <entry>bool getRedelivered() const;</entry> + </row> + <row> + <entry>C++</entry> + <entry>void setRedelivered(bool);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public bool Redelivered { get; set; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: SetProperty</entry> + </row> + <row> + <entry>C++</entry> + <entry>void setProperty(const std::string&, const qpid::types::Variant&);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void SetProperty(string name, object value);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: Properties</entry> + </row> + <row> + <entry>C++</entry> + <entry>const qpid::types::Variant::Map& getProperties() const;</entry> + </row> + <row> + <entry>C++</entry> + <entry>qpid::types::Variant::Map& getProperties();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Dictionary<string, object> Properties { get; set; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: SetContent</entry> + </row> + <row> + <entry>C++</entry> + <entry>void setContent(const std::string&);</entry> + </row> + <row> + <entry>C++</entry> + <entry>void setContent(const char* chars, size_t count);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void SetContent(byte[] bytes);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void SetContent(string content);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void SetContent(byte[] bytes, int offset, int size);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: GetContent</entry> + </row> + <row> + <entry>C++</entry> + <entry>std::string getContent() const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public string GetContent();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void GetContent(byte[] arr);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void GetContent(Collection<object> __p1);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void GetContent(Dictionary<string, object> dict);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: GetContentPtr</entry> + </row> + <row> + <entry>C++</entry> + <entry>const char* getContentPtr() const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>n/a</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: ContentSize</entry> + </row> + <row> + <entry>C++</entry> + <entry>size_t getContentSize() const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public ulong ContentSize { get; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Struct: EncodingException</entry> + </row> + <row> + <entry>C++</entry> + <entry>struct EncodingException : qpid::types::Exception</entry> + </row> + <row> + <entry>.NET</entry> + <entry>n/a</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: decode</entry> + </row> + <row> + <entry>C++</entry> + <entry>void decode(const Message& message, qpid::types::Variant::Map& map, const std::string& encoding = std::string());</entry> + </row> + <row> + <entry>C++</entry> + <entry>void decode(const Message& message, qpid::types::Variant::List& list, const std::string& encoding = std::string());</entry> + </row> + <row> + <entry>.NET</entry> + <entry>n/a</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: encode</entry> + </row> + <row> + <entry>C++</entry> + <entry>void encode(const qpid::types::Variant::Map& map, Message& message, const std::string& encoding = std::string());</entry> + </row> + <row> + <entry>C++</entry> + <entry>void encode(const qpid::types::Variant::List& list, Message& message, const std::string& encoding = std::string());</entry> + </row> + <row> + <entry>.NET</entry> + <entry>n/a</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: AsString</entry> + </row> + <row> + <entry>C++</entry> + <entry>n/a</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public string AsString(object obj);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public string ListAsString(Collection<object> list);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public string MapAsString(Dictionary<string, object> dict);</entry> + </row> + </tbody> + </tgroup> + </table> + </section> + <section> + <title>.NET Binding for the C++ Messaging API Class: Receiver</title> + <table id="table-Dotnet-Binding-Receiver"> + <title>.NET Binding for the C++ Messaging API Class: Receiver</title> + <tgroup cols="2"> + <colspec colname="c1" colwidth="1*"/> + <colspec colname="c2" colwidth="7*"/> + <thead> + <row> + <entry namest="c1" nameend="c2" align="center">.NET Binding Class: Receiver</entry> + </row> + <row> + <entry>Language</entry> + <entry>Syntax</entry> + </row> + </thead> + <tbody> + <row> + <entry>C++</entry> + <entry>class Receiver</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public ref class Receiver</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Constructor</entry> + </row> + <row> + <entry>.NET</entry> + <entry>Constructed object is returned by Session.CreateReceiver</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Copy constructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>Receiver(const Receiver&);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Receiver(Receiver receiver);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Destructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>~Receiver();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>~Receiver();</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Finalizer</entry> + </row> + <row> + <entry>C++</entry> + <entry>n/a</entry> + </row> + <row> + <entry>.NET</entry> + <entry>!Receiver()</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Copy assignment operator</entry> + </row> + <row> + <entry>C++</entry> + <entry>Receiver& operator=(const Receiver&);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Receiver op_Assign(Receiver rhs);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: Get</entry> + </row> + <row> + <entry>C++</entry> + <entry>bool get(Message& message, Duration timeout=Duration::FOREVER);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public bool Get(Message mmsgp);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public bool Get(Message mmsgp, Duration durationp);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: Get</entry> + </row> + <row> + <entry>C++</entry> + <entry>Message get(Duration timeout=Duration::FOREVER);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Message Get();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Message Get(Duration durationp);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: Fetch</entry> + </row> + <row> + <entry>C++</entry> + <entry>bool fetch(Message& message, Duration timeout=Duration::FOREVER);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public bool Fetch(Message mmsgp);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public bool Fetch(Message mmsgp, Duration duration);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: Fetch</entry> + </row> + <row> + <entry>C++</entry> + <entry>Message fetch(Duration timeout=Duration::FOREVER);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Message Fetch();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Message Fetch(Duration durationp);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: Capacity</entry> + </row> + <row> + <entry>C++</entry> + <entry>void setCapacity(uint32_t);</entry> + </row> + <row> + <entry>C++</entry> + <entry>uint32_t getCapacity();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public uint Capacity { get; set; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: Available</entry> + </row> + <row> + <entry>C++</entry> + <entry>uint32_t getAvailable();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public uint Available { get; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: Unsettled</entry> + </row> + <row> + <entry>C++</entry> + <entry>uint32_t getUnsettled();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public uint Unsettled { get; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: Close</entry> + </row> + <row> + <entry>C++</entry> + <entry>void close();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void Close();</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: IsClosed</entry> + </row> + <row> + <entry>C++</entry> + <entry>bool isClosed() const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public bool IsClosed { get; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: Name</entry> + </row> + <row> + <entry>C++</entry> + <entry>const std::string& getName() const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public string Name { get; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: Session</entry> + </row> + <row> + <entry>C++</entry> + <entry>Session getSession() const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Session Session { get; }</entry> + </row> + </tbody> + </tgroup> + </table> + </section> + <section> + <title>.NET Binding for the C++ Messaging API Class: Sender</title> + <table id="table-Dotnet-Binding-Sender"> + <title>.NET Binding for the C++ Messaging API Class: Sender</title> + <tgroup cols="2"> + <colspec colname="c1" colwidth="1*"/> + <colspec colname="c2" colwidth="7*"/> + <thead> + <row> + <entry namest="c1" nameend="c2" align="center">.NET Binding Class: Sender</entry> + </row> + <row> + <entry>Language</entry> + <entry>Syntax</entry> + </row> + </thead> + <tbody> + <row> + <entry>C++</entry> + <entry>class Sender</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public ref class Sender</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Constructor</entry> + </row> + <row> + <entry>.NET</entry> + <entry>Constructed object is returned by Session.CreateSender</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Copy constructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>Sender(const Sender&);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Sender(Sender sender);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Destructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>~Sender();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>~Sender();</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Finalizer</entry> + </row> + <row> + <entry>C++</entry> + <entry>n/a</entry> + </row> + <row> + <entry>.NET</entry> + <entry>!Sender()</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Copy assignment operator</entry> + </row> + <row> + <entry>C++</entry> + <entry>Sender& operator=(const Sender&);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Sender op_Assign(Sender rhs);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: Send</entry> + </row> + <row> + <entry>C++</entry> + <entry>void send(const Message& message, bool sync=false);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void Send(Message mmsgp);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void Send(Message mmsgp, bool sync);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: Close</entry> + </row> + <row> + <entry>C++</entry> + <entry>void close();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void Close();</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: Capacity</entry> + </row> + <row> + <entry>C++</entry> + <entry>void setCapacity(uint32_t);</entry> + </row> + <row> + <entry>C++</entry> + <entry>uint32_t getCapacity();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public uint Capacity { get; set; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: Available</entry> + </row> + <row> + <entry>C++</entry> + <entry>uint32_t getAvailable();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public uint Available { get; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: Unsettled</entry> + </row> + <row> + <entry>C++</entry> + <entry>uint32_t getUnsettled();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public uint Unsettled { get; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: Name</entry> + </row> + <row> + <entry>C++</entry> + <entry>const std::string& getName() const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public string Name { get; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: Session</entry> + </row> + <row> + <entry>C++</entry> + <entry>Session getSession() const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Session Session { get; }</entry> + </row> + </tbody> + </tgroup> + </table> + </section> + <section> + <title>.NET Binding for the C++ Messaging API Class: Session</title> + <table id="table-Dotnet-Binding-Session"> + <title>.NET Binding for the C++ Messaging API Class: Session</title> + <tgroup cols="2"> + <colspec colname="c1" colwidth="1*"/> + <colspec colname="c2" colwidth="7*"/> + <thead> + <row> + <entry namest="c1" nameend="c2" align="center">.NET Binding Class: Session</entry> + </row> + <row> + <entry>Language</entry> + <entry>Syntax</entry> + </row> + </thead> + <tbody> + <row> + <entry>C++</entry> + <entry>class Session</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public ref class Session</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Constructor</entry> + </row> + <row> + <entry>.NET</entry> + <entry>Constructed object is returned by Connection.CreateSession</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Copy constructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>Session(const Session&);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Session(Session session);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Destructor</entry> + </row> + <row> + <entry>C++</entry> + <entry>~Session();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>~Session();</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Finalizer</entry> + </row> + <row> + <entry>C++</entry> + <entry>n/a</entry> + </row> + <row> + <entry>.NET</entry> + <entry>!Session()</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Copy assignment operator</entry> + </row> + <row> + <entry>C++</entry> + <entry>Session& operator=(const Session&);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Session op_Assign(Session rhs);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: Close</entry> + </row> + <row> + <entry>C++</entry> + <entry>void close();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void Close();</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: Commit</entry> + </row> + <row> + <entry>C++</entry> + <entry>void commit();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void Commit();</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: Rollback</entry> + </row> + <row> + <entry>C++</entry> + <entry>void rollback();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void Rollback();</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: Acknowledge</entry> + </row> + <row> + <entry>C++</entry> + <entry>void acknowledge(bool sync=false);</entry> + </row> + <row> + <entry>C++</entry> + <entry>void acknowledge(Message&, bool sync=false);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void Acknowledge();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void Acknowledge(bool sync);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void Acknowledge(Message __p1);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void Acknowledge(Message __p1, bool __p2);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: Reject</entry> + </row> + <row> + <entry>C++</entry> + <entry>void reject(Message&);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void Reject(Message __p1);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: Release</entry> + </row> + <row> + <entry>C++</entry> + <entry>void release(Message&);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void Release(Message __p1);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: Sync</entry> + </row> + <row> + <entry>C++</entry> + <entry>void sync(bool block=true);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void Sync();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void Sync(bool block);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: Receivable</entry> + </row> + <row> + <entry>C++</entry> + <entry>uint32_t getReceivable();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public uint Receivable { get; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: UnsettledAcks</entry> + </row> + <row> + <entry>C++</entry> + <entry>uint32_t getUnsettledAcks();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public uint UnsetledAcks { get; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: NextReceiver</entry> + </row> + <row> + <entry>C++</entry> + <entry>bool nextReceiver(Receiver&, Duration timeout=Duration::FOREVER);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public bool NextReceiver(Receiver rcvr);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public bool NextReceiver(Receiver rcvr, Duration timeout);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: NextReceiver</entry> + </row> + <row> + <entry>C++</entry> + <entry>Receiver nextReceiver(Duration timeout=Duration::FOREVER);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Receiver NextReceiver();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Receiver NextReceiver(Duration timeout);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: CreateSender</entry> + </row> + <row> + <entry>C++</entry> + <entry>Sender createSender(const Address& address);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Sender CreateSender(Address address);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: CreateSender</entry> + </row> + <row> + <entry>C++</entry> + <entry>Sender createSender(const std::string& address);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Sender CreateSender(string address);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: CreateReceiver</entry> + </row> + <row> + <entry>C++</entry> + <entry>Receiver createReceiver(const Address& address);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Receiver CreateReceiver(Address address);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: CreateReceiver</entry> + </row> + <row> + <entry>C++</entry> + <entry>Receiver createReceiver(const std::string& address);</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Receiver CreateReceiver(string address);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: GetSender</entry> + </row> + <row> + <entry>C++</entry> + <entry>Sender getSender(const std::string& name) const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Sender GetSender(string name);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: GetReceiver</entry> + </row> + <row> + <entry>C++</entry> + <entry>Receiver getReceiver(const std::string& name) const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Receiver GetReceiver(string name);</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: Connection</entry> + </row> + <row> + <entry>C++</entry> + <entry>Connection getConnection() const;</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public Connection Connection { get; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Property: HasError</entry> + </row> + <row> + <entry>C++</entry> + <entry>bool hasError();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public bool HasError { get; }</entry> + </row> + <row> + <entry namest="c1" nameend="c2" align="center">Method: CheckError</entry> + </row> + <row> + <entry>C++</entry> + <entry>void checkError();</entry> + </row> + <row> + <entry>.NET</entry> + <entry>public void CheckError();</entry> + </row> + </tbody> + </tgroup> + </table> + </section> + <section> + <title>.NET Binding Class: SessionReceiver</title> + <para> + The SessionReceiver class provides a convenient callback + mechanism for Messages received by all Receivers on a given + Session. + </para> + <para> + <programlisting><![CDATA[ +using Org.Apache.Qpid.Messaging; +using System; + +namespace Org.Apache.Qpid.Messaging.SessionReceiver +{ + public interface ISessionReceiver + { + void SessionReceiver(Receiver receiver, Message message); + } + + public class CallbackServer + { + public CallbackServer(Session session, ISessionReceiver callback); + + public void Close(); + } +} +]]> + </programlisting> + </para> + <para> + To use this class a client program includes references to both + Org.Apache.Qpid.Messaging and Org.Apache.Qpid.Messaging.SessionReceiver. + The calling program creates a function that implements the + ISessionReceiver interface. This function will be called whenever + message is received by the session. The callback process is started + by creating a CallbackServer and will continue to run until the + client program calls the CallbackServer.Close function. + </para> + <para> + A complete operating example of using the SessionReceiver callback + is contained in cpp/bindings/qpid/dotnet/examples/csharp.map.callback.receiver. + </para> + </section> + </section> + </chapter> +</book> + +<!-- + - client code remains exactly the same, but routing behavior + changes + - exchanges drop messages if nobody is listening, so we need to + start drain first + - drain will exit immediately if the source is empty (note that + this is actually a semantic guarantee provided by the API, we + know for a fact that the source is empty when drain/fetch + reports it, no fudge factor timeout is required [this assumes + nobody is concurrently publishing of course]) + - drain -f invokes blocking fetch (you could use a timeout here also) + --> diff --git a/qpid/doc/book/src/qmf/QmfBook.xml b/qpid/doc/book/src/qmf/QmfBook.xml new file mode 100644 index 0000000000..64a6545fb5 --- /dev/null +++ b/qpid/doc/book/src/qmf/QmfBook.xml @@ -0,0 +1,101 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + + --> + +<book id="qmf-book"> + <title>QMF - The Qpid Management Framework</title> + <subtitle>Object and Service-Oriented Management Leveraging the Capabilities of Qpid Messaging</subtitle> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="QmfIntroduction.xml"/> + + <!-- As these chapters are fleshed out, move them into separate include files for easier text management --> + <chapter><title>QMF Architecture</title> + <section><title>Components: Agents and Consoles</title> + </section> + <section><title>QMF Domains</title> + </section> + <section><title>Data: Objects, Methods, Events, and Schemata</title> + </section> + <section><title>Agent Discovery</title> + </section> + <section><title>Data Access: Queries and Subscriptions</title> + </section> + </chapter> + + <chapter><title>QMF Schema Definition</title> + <section><title>Packages, Objects, and Events</title> + </section> + <section><title>Data Types</title> + </section> + <section><title>Programmatic Schema Definition</title> + </section> + <section><title>XML Schema Definition</title> + </section> + </chapter> + + <chapter><title>How to Write an Agent</title> + </chapter> + + <chapter><title>How to Write a Console</title> + </chapter> + + <chapter><title>QMF Queries</title> + </chapter> + + <chapter><title>API Reference</title> + <section><title>C++ API</title> + </section> + <section><title>Python API</title> + </section> + <section><title>Ruby API</title> + </section> +<!-- + <section><title>.NET API</title> + </section> + <section><title>Java API</title> + </section> +--> + </chapter> + + <chapter><title>Scale: Large QMF Networks</title> + </chapter> + + <chapter><title>Security</title> + </chapter> + + <chapter><title>The QMF Protocol</title> + <section><title>Message Headers</title> + </section> + <section><title>Addressing</title> + </section> + <section><title>Message Protocol</title> + </section> + <section><title>Message Body Details</title> + </section> + </chapter> + + <chapter><title>Using QMF Messages to Manage the Qpid Broker</title> + </chapter> + +</book> diff --git a/qpid/doc/book/src/qmf/QmfIntroduction.xml b/qpid/doc/book/src/qmf/QmfIntroduction.xml new file mode 100644 index 0000000000..db7b8949a5 --- /dev/null +++ b/qpid/doc/book/src/qmf/QmfIntroduction.xml @@ -0,0 +1,45 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + +--> + +<chapter> +<title>Introduction</title> + +<para> +QMF enhances Qpid Messaging by providing a layer of functionality that makes it easy to implement common management patterns +using messaging as the basis for communication. QMF consists of three primary parts: +</para> + +<itemizedlist> + <listitem><para> +A protocol definition defines conventions for the use of message addresses, message headers, and structured message bodies. + </para></listitem> + + <listitem><para> +A core QMF engine provides a C++ API and an implementation of a set of protocol handlers for QMF message communication. + </para></listitem> + + <listitem><para> +Bindings are provided that wrap the C++ API for use in other languages such as Python, Ruby, and .NET. + </para></listitem> +</itemizedlist> + +</chapter> diff --git a/qpid/doc/book/xsl/html-custom.xsl b/qpid/doc/book/xsl/html-custom.xsl new file mode 100644 index 0000000000..dbfbcc44c7 --- /dev/null +++ b/qpid/doc/book/xsl/html-custom.xsl @@ -0,0 +1,188 @@ +<?xml version='1.0'?> +<!-- + - + - Licensed to the Apache Software Foundation (ASF) under one + - or more contributor license agreements. See the NOTICE file + - distributed with this work for additional information + - regarding copyright ownership. The ASF licenses this file + - to you 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. + - + --> +<xsl:stylesheet + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> + <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"/> + +<xsl:template name="chunk-element-content"> + <xsl:param name="prev"/> + <xsl:param name="next"/> + <xsl:param name="nav.context"/> + <xsl:param name="content"> + <xsl:apply-imports/> + </xsl:param> + + <xsl:call-template name="user.preroot"/> + + <html> + <xsl:call-template name="html.head"> + <xsl:with-param name="prev" select="$prev"/> + <xsl:with-param name="next" select="$next"/> + </xsl:call-template> + + <body> +<div class="container"> + <xsl:call-template name="body.attributes"/> + <xsl:call-template name="user.header.navigation"/> + + <xsl:call-template name="header.navigation"> + <xsl:with-param name="prev" select="$prev"/> + <xsl:with-param name="next" select="$next"/> + <xsl:with-param name="nav.context" select="$nav.context"/> + </xsl:call-template> + +<div class="main_text_area"> + <div class="main_text_area_top"> + </div> + <div class="main_text_area_body"> + <xsl:call-template name="user.header.content"/> + <xsl:copy-of select="$content"/> + + <xsl:call-template name="user.footer.content"/> + </div> + <xsl:call-template name="footer.navigation"> + <xsl:with-param name="prev" select="$prev"/> + <xsl:with-param name="next" select="$next"/> + <xsl:with-param name="nav.context" select="$nav.context"/> + </xsl:call-template> + + <xsl:call-template name="user.footer.navigation"/> + <div class="main_text_area_bottom"> + </div> +</div> +</div> + </body> + </html> + <xsl:value-of select="$chunk.append"/> +</xsl:template> + +<xsl:template name="breadcrumbs"> + <xsl:param name="this.node" select="."/> + <DIV class="breadcrumbs"> + <xsl:for-each select="$this.node/ancestor::*"> + <span class="breadcrumb-link"> + <a> + <xsl:attribute name="href"> + <xsl:call-template name="href.target"> + <xsl:with-param name="object" select="."/> + <xsl:with-param name="context" select="$this.node"/> + </xsl:call-template> + </xsl:attribute> + <xsl:apply-templates select="." mode="title.markup"/> + </a> + </span> + <xsl:text> > </xsl:text> + </xsl:for-each> + <!-- And display the current node, but not as a link --> + <span class="breadcrumb-node"> + <xsl:apply-templates select="$this.node" mode="title.markup"/> + </span> + </DIV> +</xsl:template> + +<xsl:template name="header.navigation"> + <DIV class="header"> + <DIV class="logo"> + <H1>Apache Qpid™</H1> + <H2>Open Source AMQP Messaging</H2> + </DIV> + </DIV> + + <DIV class="menu_box"> + <DIV class="menu_box_top"></DIV> + <DIV class="menu_box_body"> + <H3>Apache Qpid</H3> + <UL> + <LI><A href="http://qpid.apache.org/index.html">Home</A></LI> + <LI><A href="http://qpid.apache.org/download.html">Download</A></LI> + <LI><A href="http://qpid.apache.org/getting_started.html">Getting Started</A></LI> + <LI><A href="http://www.apache.org/licenses/">License</A></LI> + <LI><A href="https://cwiki.apache.org/qpid/faq.html">FAQ</A></LI> + </UL> + </DIV> + <DIV class="menu_box_bottom"></DIV> + + <DIV class="menu_box_top"></DIV> + <DIV class="menu_box_body"> + <H3>Documentation</H3> + <UL> + <LI><A href="http://qpid.apache.org/documentation.html#doc-release">Latest Release</A></LI> + <LI><A href="http://qpid.apache.org/documentation.html#doc-trunk">Trunk</A></LI> + <LI><A href="http://qpid.apache.org/documentation.html#doc-archives">Archive</A></LI> + </UL> + </DIV> + <DIV class="menu_box_bottom"></DIV> + + <DIV class="menu_box_top"></DIV> + <DIV class="menu_box_body"> + <H3>Community</H3> + <UL> + <LI><A href="http://qpid.apache.org/getting_involved.html">Getting Involved</A></LI> + <LI><A href="http://qpid.apache.org/source_repository.html">Source Repository</A></LI> + <LI><A href="http://qpid.apache.org/mailing_lists.html">Mailing Lists</A></LI> + <LI><A href="https://cwiki.apache.org/qpid/">Wiki</A></LI> + <LI><A href="https://issues.apache.org/jira/browse/qpid">Issue Reporting</A></LI> + <LI><A href="http://qpid.apache.org/people.html">People</A></LI> + <LI><A href="http://qpid.apache.org/acknowledgements.html">Acknowledgements</A></LI> + </UL> + </DIV> + <DIV class="menu_box_bottom"></DIV> + + <DIV class="menu_box_top"></DIV> + <DIV class="menu_box_body"> + <H3>Developers</H3> + <UL> + <LI><A href="https://cwiki.apache.org/qpid/building.html">Building Qpid</A></LI> + <LI><A href="https://cwiki.apache.org/qpid/developer-pages.html">Developer Pages</A></LI> + </UL> + </DIV> + <DIV class="menu_box_bottom"></DIV> + + <DIV class="menu_box_top"></DIV> + <DIV class="menu_box_body"> + <H3>About AMQP</H3> + <UL> + <LI><A href="http://qpid.apache.org/amqp.html">What is AMQP?</A></LI> + </UL> + </DIV> + <DIV class="menu_box_bottom"></DIV> + + <DIV class="menu_box_top"></DIV> + <DIV class="menu_box_body"> + <H3>About Apache</H3> + <UL> + <LI><A href="http://www.apache.org">Home</A></LI> + <LI><A href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</A></LI> + <LI><A href="http://www.apache.org/foundation/thanks.html">Thanks</A></LI> + <LI><A href="http://www.apache.org/security/">Security</A></LI> + </UL> + </DIV> + <DIV class="menu_box_bottom"></DIV> + </DIV> + +</xsl:template> + +<xsl:template name="user.header.content"> + <xsl:call-template name="breadcrumbs"/> +</xsl:template> + +</xsl:stylesheet> diff --git a/qpid/doc/dev-readme/QPID-Component-README.odg b/qpid/doc/dev-readme/QPID-Component-README.odg Binary files differnew file mode 100644 index 0000000000..217a6d68d8 --- /dev/null +++ b/qpid/doc/dev-readme/QPID-Component-README.odg diff --git a/qpid/doc/dev-readme/QPID-Component-README.pdf b/qpid/doc/dev-readme/QPID-Component-README.pdf Binary files differnew file mode 100644 index 0000000000..3012372889 --- /dev/null +++ b/qpid/doc/dev-readme/QPID-Component-README.pdf diff --git a/qpid/doc/dev-readme/README.txt b/qpid/doc/dev-readme/README.txt new file mode 100644 index 0000000000..65a8626e53 --- /dev/null +++ b/qpid/doc/dev-readme/README.txt @@ -0,0 +1,6 @@ +This directory holds documents of interest to developers. + +The documents are descriptions of how Qpid is organized at the source code +level and not of how Qpid works as a delivered product. They provide +supporting graphics and illustrations for top-level README.txt files +located elsewhere in the source tree. diff --git a/qpid/doc/website/README.txt b/qpid/doc/website/README.txt new file mode 100644 index 0000000000..dcb3b423e5 --- /dev/null +++ b/qpid/doc/website/README.txt @@ -0,0 +1,10 @@ +To edit the website, check out the /site repo area: + + svn co https://svn.apache.org/repos/asf/qpid/site + +The HTML files for the site reside in the docs directory, where a README +can be found to describe the process of adding new content. + +It is no longer necessary to generate the main website pages, the live files +are now edited directly, and are deployed to the web server after check in. + |
