http://git-wip-us.apache.org/repos/asf/qpid-site/blob/c3ab60f6/input/releases/qpid-cpp-1.39.0/messaging-api/book/connections.html.in ---------------------------------------------------------------------- diff --git a/input/releases/qpid-cpp-1.39.0/messaging-api/book/connections.html.in b/input/releases/qpid-cpp-1.39.0/messaging-api/book/connections.html.in new file mode 100644 index 0000000..cae0392 --- /dev/null +++ b/input/releases/qpid-cpp-1.39.0/messaging-api/book/connections.html.in @@ -0,0 +1,158 @@ +<div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">1.10. Connections</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="ch01s09.html">Prev</a> </td><th align="center" width="60%">Chapter 1. Using the Qpid Messaging API</th><td align="right" width="20%"> <a accesskey="n" href="section-Maps.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="connections"></a>1.10. Connections</h2></div></div></div><p> + 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: + </p><pre class="programlisting"> + Connection connection(); + Connection connection(const string url); + Connection connection(const string url, const string& options); + Connection connection(const string url, const Variant::Map& options); + </pre><p> + 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. + </p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="connection-url"></a>1.10.1. Connection URLs</h3></div></div></div><p> + 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. + </p><pre class="programlisting"> + 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 </pre><p> + Examples of Messaging Connection URLs + </p><pre class="programlisting"> + localhost + localhost:5672 + localhost:9999 + 192.168.1.2:5672 + mybroker.example.com:5672 + amqp:tcp:localhost:5672 + tcp:locahost:5672,localhost:5800 + </pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="connection-options"></a>1.10.2. Connection Options</h3></div></div></div><p> + 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. + </p><div class="example"><a id="idm140612067903856"></a><p class="title"><strong>Example 1.14. Specifying Connection Options in C++, Python, and .NET</strong></p><div class="example-contents"><p>In C++, these options can be set using <code class="function">Connection::setOption()</code> or by passing in a set of options to the constructor. The options can be passed in as a map or in string form:</p><p>or</p><pre class="programlisting"> + Connection connection("localhost:5672"); + connection.setOption("reconnect", true); + try { + connection.open(); + !!! SNIP !!! + </pre><p>In Python, these options can be set as attributes of the connection or using named arguments in + the <code class="function">Connection</code> constructor:</p><pre class="programlisting"> + connection = Connection("localhost:5672", reconnect=True) + try: + connection.open() + !!! SNIP !!! + </pre><p>or</p><pre class="programlisting"> + connection = Connection("localhost:5672") + connection.reconnect = True + try: + connection.open() + !!! SNIP !!! + </pre><p> + In .NET, these options can be set using <code class="function">Connection.SetOption()</code> or by passing in a set of options to the constructor. The options can be passed in as a map or in string form: + </p><pre class="programlisting"> + Connection connection= new Connection("localhost:5672", "{reconnect: true}"); + try { + connection.Open(); + !!! SNIP !!! + </pre><p> + or + </p><pre class="programlisting"> + Connection connection = new Connection("localhost:5672"); + connection.SetOption("reconnect", true); + try { + connection.Open(); + !!! SNIP !!! + </pre><p>See the reference documentation for details in each language.</p></div></div><br class="example-break" /><p>The following table lists the supported connection options.</p><div class="table"><a id="idm140612067893440"></a><p class="title"><strong>Table 1.4. Connection Options</strong></p><div class="table-contents"><table border="1" class="table" summary="Connection Options" width="100%"><colgroup><col /><col /><col /></colgroup><thead><tr><th>option name</th><th>value type</th><th>semantics</th></tr></thead><tbody><tr><td> + <code class="literal">username</code> + </td><td> + string + </td><td> + The username to use when authenticating to the broker. + </td></tr><tr><td> + <code class="literal">password</code> + </td><td> + string + </td><td> + The password to use when authenticating to the broker. + </td></tr><tr><td> + <code class="literal">sasl_mechanisms</code> + </td><td> + string + </td><td> + The specific SASL mechanisms to use with the python + client when authenticating to the broker. The value + is a space separated list. + </td></tr><tr><td> + <code class="literal">reconnect</code> + </td><td> + boolean + </td><td> + Transparently reconnect if the connection is lost. + </td></tr><tr><td> + <code class="literal">reconnect_timeout</code> + </td><td> + integer + </td><td> + Total number of seconds to continue reconnection attempts before giving up and raising an exception. + </td></tr><tr><td> + <code class="literal">reconnect_limit</code> + </td><td> + integer + </td><td> + Maximum number of reconnection attempts before giving up and raising an exception. + </td></tr><tr><td> + <code class="literal">reconnect_interval_min</code> + </td><td> + integer representing time in seconds + </td><td> + 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 <code class="literal">reconnect_interval_min</code>; if that attempt fails, the reconnect interval increases exponentially until a reconnection attempt succeeds or <code class="literal">reconnect_interval_max</code> is reached. + </td></tr><tr><td> + <code class="literal">reconnect_interval_max</code> + </td><td> + integer representing time in seconds + </td><td> + Maximum reconnect interval. + </td></tr><tr><td> + <code class="literal">reconnect_interval</code> + </td><td> + integer representing time in seconds + </td><td> + Sets both <code class="literal">reconnection_interval_min</code> and <code class="literal">reconnection_interval_max</code> to the same value. + </td></tr><tr><td> + <code class="literal">heartbeat</code> + </td><td> + integer representing time in seconds + </td><td> + Requests that heartbeats be sent every N seconds. If two + successive heartbeats are missed the connection is + considered to be lost. + </td></tr><tr><td> + <code class="literal">transport</code> + </td><td> + string + </td><td> + Sets the underlying transport protocol used. The default option is 'tcp'. To enable ssl, set to 'ssl'. The C++ client additionally supports 'rdma'. + </td></tr><tr><td> + <code class="literal">tcp-nodelay</code> + </td><td> + boolean + </td><td> + Set tcp no-delay, i.e. disable Nagle algorithm. [C++ only] + </td></tr><tr><td> + <code class="literal">protocol</code> + </td><td> + string + </td><td> + Sets the application protocol used. The default option is 'amqp0-10'. To enable AMQP 1.0, set to 'amqp1.0'. + </td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="navfooter"><hr /><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="ch01s09.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="using-the-qpid-messaging-api.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="section-Maps.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">1.9. Transactions </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td align="right" valign="top" width="40%"> 1.11. Maps and Lists in Message Content</td></tr></table></div></div> \ No newline at end of file
http://git-wip-us.apache.org/repos/asf/qpid-site/blob/c3ab60f6/input/releases/qpid-cpp-1.39.0/messaging-api/book/css/style.css ---------------------------------------------------------------------- diff --git a/input/releases/qpid-cpp-1.39.0/messaging-api/book/css/style.css b/input/releases/qpid-cpp-1.39.0/messaging-api/book/css/style.css new file mode 100644 index 0000000..c681596 --- /dev/null +++ b/input/releases/qpid-cpp-1.39.0/messaging-api/book/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; +} + + http://git-wip-us.apache.org/repos/asf/qpid-site/blob/c3ab60f6/input/releases/qpid-cpp-1.39.0/messaging-api/book/index.html.in ---------------------------------------------------------------------- diff --git a/input/releases/qpid-cpp-1.39.0/messaging-api/book/index.html.in b/input/releases/qpid-cpp-1.39.0/messaging-api/book/index.html.in new file mode 100644 index 0000000..0229ba7 --- /dev/null +++ b/input/releases/qpid-cpp-1.39.0/messaging-api/book/index.html.in @@ -0,0 +1 @@ +<div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Using the Qpid Messaging API</th></tr><tr><td align="left" width="20%"> </td><th align="center" width="60%"> </th><td align="right" width="20%"> <a accesskey="n" href="using-the-qpid-messaging-api.html">Next</a></td></tr></table><hr /></div><div class="book"><div class="titlepage"><div><div><h1 class="title"><a id="client-api-tutorial"></a>Using the Qpid Messaging API</h1></div><div><h2 class="subtitle">Cross-Platform AMQP Messaging</h2></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="chapter"><a href="using-the-qpid-messaging-api.html">1. Using the Qpid Messaging API</a></span></dt><dd><dl><dt><span class="section"><a href="using-the-qpid-messaging-api.html#idm140612069842624">1.1. A Simple Messaging Program in C++</a></span></dt><dt><span class="section"><a href="ch01s02.html" >1.2. A Simple Messaging Program in Python</a></span></dt><dt><span >class="section"><a href="ch01s03.html">1.3. A Simple Messaging Program in >.NET C#</a></span></dt><dt><span class="section"><a >href="section-addresses.html">1.4. Addresses</a></span></dt><dd><dl><dt><span >class="section"><a href="section-addresses.html#idm140612068111184">1.4.1. >Address Strings</a></span></dt><dt><span class="section"><a >href="section-addresses.html#idm140612068105936">1.4.2. >Subjects</a></span></dt><dt><span class="section"><a >href="section-addresses.html#idm140612068065424">1.4.3. Address String >Options</a></span></dt><dt><span class="section"><a >href="section-addresses.html#section-address-string-bnf">1.4.4. Address >String Grammar</a></span></dt></dl></dd><dt><span class="section"><a >href="replay.html">1.5. Sender Capacity and Replay</a></span></dt><dt><span >class="section"><a href="prefetch.html">1.6. Receiver Capacity >(Prefetch)</a></span></dt><dt><span class="section"><a href="acknowledgements. html">1.7. Acknowledging Received Messages</a></span></dt><dt><span class="section"><a href="ch01s08.html">1.8. Receiving Messages from Multiple Sources</a></span></dt><dt><span class="section"><a href="ch01s09.html">1.9. Transactions</a></span></dt><dt><span class="section"><a href="connections.html">1.10. Connections</a></span></dt><dd><dl><dt><span class="section"><a href="connections.html#connection-url">1.10.1. Connection URLs</a></span></dt><dt><span class="section"><a href="connections.html#connection-options">1.10.2. Connection Options</a></span></dt></dl></dd><dt><span class="section"><a href="section-Maps.html">1.11. Maps and Lists in Message Content</a></span></dt><dd><dl><dt><span class="section"><a href="section-Maps.html#section-Python-Maps">1.11.1. Qpid Maps and Lists in Python</a></span></dt><dt><span class="section"><a href="section-Maps.html#section-cpp-Maps">1.11.2. Qpid Maps and Lists in C++</a></span></dt><dt><span class="section"><a href="section-Maps.html#sect ion-dotnet-Maps">1.11.3. Qpid Maps and Lists in .NET</a></span></dt></dl></dd><dt><span class="section"><a href="ch01s12.html">1.12. The Request / Response Pattern</a></span></dt><dt><span class="section"><a href="ch01s13.html">1.13. Performance Tips</a></span></dt><dt><span class="section"><a href="ch01s14.html">1.14. Cluster Failover</a></span></dt><dt><span class="section"><a href="ch01s15.html">1.15. Logging</a></span></dt><dd><dl><dt><span class="section"><a href="ch01s15.html#idm140612067732448">1.15.1. Logging in C++</a></span></dt><dt><span class="section"><a href="ch01s15.html#idm140612067727440">1.15.2. Logging in Python</a></span></dt></dl></dd><dt><span class="section"><a href="section-amqp0-10-mapping.html">1.16. The AMQP 0-10 mapping</a></span></dt><dd><dl><dt><span class="section"><a href="section-amqp0-10-mapping.html#section-amqp0-10-message-props">1.16.1. 0-10 Message Property Keys</a></span></dt></dl></dd><dt><span class="section"><a href="Message-Groups-Guide.htm l">1.17. Using Message Groups</a></span></dt><dd><dl><dt><span class="section"><a href="Message-Groups-Guide.html#messagegroups-setup">1.17.1. Creating Message Group Queues</a></span></dt><dt><span class="section"><a href="Message-Groups-Guide.html#messagegroups-sending">1.17.2. Sending Grouped Messages</a></span></dt><dt><span class="section"><a href="Message-Groups-Guide.html#messagegroups-receiving">1.17.3. Receiving Grouped Messages</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="ch02.html">2. The .NET Binding for the C++ Messaging Client</a></span></dt><dd><dl><dt><span class="section"><a href="ch02.html#idm140612067656496">2.1. .NET Binding for the C++ Messaging Client Component Architecture</a></span></dt><dt><span class="section"><a href="ch02s02.html">2.2. .NET Binding for the C++ Messaging Client Examples</a></span></dt><dt><span class="section"><a href="ch02s03.html">2.3. .NET Binding Class Mapping to Underlying C++ Messaging API</a></span></dt><dd>< dl><dt><span class="section"><a href="ch02s03.html#idm140612067592256">2.3.1. .NET Binding for the C++ Messaging API Class: Address</a></span></dt><dt><span class="section"><a href="ch02s03.html#idm140612067521424">2.3.2. .NET Binding for the C++ Messaging API Class: Connection</a></span></dt><dt><span class="section"><a href="ch02s03.html#idm140612067446304">2.3.3. .NET Binding for the C++ Messaging API Class: Duration</a></span></dt><dt><span class="section"><a href="ch02s03.html#idm140612067396976">2.3.4. .NET Binding for the C++ Messaging API Class: FailoverUpdates</a></span></dt><dt><span class="section"><a href="ch02s03.html#idm140612067375856">2.3.5. .NET Binding for the C++ Messaging API Class: Message</a></span></dt><dt><span class="section"><a href="ch02s03.html#idm140612067237616">2.3.6. .NET Binding for the C++ Messaging API Class: Receiver</a></span></dt><dt><span class="section"><a href="ch02s03.html#idm140612067162192">2.3.7. .NET Binding for the C++ Messaging API Cla ss: Sender</a></span></dt><dt><span class="section"><a href="ch02s03.html#idm140612067105680">2.3.8. .NET Binding for the C++ Messaging API Class: Session</a></span></dt><dt><span class="section"><a href="ch02s03.html#idm140612066993296">2.3.9. .NET Binding Class: SessionReceiver</a></span></dt></dl></dd></dl></dd></dl></div><div class="list-of-tables"><p><strong>List of Tables</strong></p><dl><dt>1.1. <a href="section-addresses.html#idm140612068007696">Address String Options</a></dt><dt>1.2. <a href="section-addresses.html#table-node-properties">Node Properties</a></dt><dt>1.3. <a href="section-addresses.html#table-link-properties">Link Properties</a></dt><dt>1.4. <a href="connections.html#idm140612067893440">Connection Options</a></dt><dt>1.5. <a href="section-Maps.html#tabl-Programming_in_Apache_Qpid-Qpid_Maps_in_Message_Content">Map and List Representation in Supported Languages</a></dt><dt>1.6. <a href="section-Maps.html#table-Python-Maps">Python Datatypes in Maps</a></dt><dt>1 .7. <a href="section-Maps.html#table-cpp-Maps">C++ Datatypes in Maps</a></dt><dt>1.8. <a href="section-Maps.html#table-dotnet-Maps">Datatype Mapping between C++ and .NET binding</a></dt><dt>1.9. <a href="section-amqp0-10-mapping.html#table-amqp0-10-message-properties">Mapping to AMQP 0-10 Message Properties</a></dt><dt>2.1. <a href="ch02.html#table-Dotnet-Binding-Component-Architecture">.NET Binding for the C++ Messaging Client Component Architecture</a></dt><dt>2.2. <a href="ch02s02.html#table-Dotnet-Binding-Example-Client-Server">Example : Client - Server</a></dt><dt>2.3. <a href="ch02s02.html#table-Dotnet-Binding-Example-MapSender-MapReceiver">Example : Map Sender – Map Receiver</a></dt><dt>2.4. <a href="ch02s02.html#table-Dotnet-Binding-Example-Spout-Drain">Example : Spout - Drain</a></dt><dt>2.5. <a href="ch02s02.html#table-Dotnet-Binding-Example-CallbackSender-CallbackReceiver">Example : Map Callback Sender – Map Callback Receiver</a></dt><dt>2.6. <a href="ch02s02. html#table-Dotnet-Binding-Example-DeclareQueues">Example - Declare Queues</a></dt><dt>2.7. <a href="ch02s02.html#table-Dotnet-Binding-Example-DirectSender-DirectReceiver">Example: Direct Sender - Direct Receiver</a></dt><dt>2.8. <a href="ch02s02.html#table-Dotnet-Binding-Example-Helloworld">Example: Hello World</a></dt><dt>2.9. <a href="ch02s03.html#table-Dotnet-Binding-Address">.NET Binding for the C++ Messaging API Class: Address</a></dt><dt>2.10. <a href="ch02s03.html#table-Dotnet-Binding-Connection">.NET Binding for the C++ Messaging API Class: Connection</a></dt><dt>2.11. <a href="ch02s03.html#table-Dotnet-Binding-Duration">.NET Binding for the C++ Messaging API Class: Duration</a></dt><dt>2.12. <a href="ch02s03.html#table-Dotnet-Binding-FailoverUpdates">.NET Binding for the C++ Messaging API Class: FailoverUpdates</a></dt><dt>2.13. <a href="ch02s03.html#table-Dotnet-Binding-Message">.NET Binding for the C++ Messaging API Class: Message</a></dt><dt>2.14. <a href="ch02s03.html#t able-Dotnet-Binding-Receiver">.NET Binding for the C++ Messaging API Class: Receiver</a></dt><dt>2.15. <a href="ch02s03.html#table-Dotnet-Binding-Sender">.NET Binding for the C++ Messaging API Class: Sender</a></dt><dt>2.16. <a href="ch02s03.html#table-Dotnet-Binding-Session">.NET Binding for the C++ Messaging API Class: Session</a></dt></dl></div><div class="list-of-examples"><p><strong>List of Examples</strong></p><dl><dt>1.1. <a href="using-the-qpid-messaging-api.html#idm140612069910464">"Hello world!" in C++</a></dt><dt>1.2. <a href="ch01s02.html#idm140612073698272">"Hello world!" in Python</a></dt><dt>1.3. <a href="ch01s03.html#idm140612073667520">"Hello world!" in .NET C#</a></dt><dt>1.4. <a href="section-addresses.html#idm140612068136432">Queues</a></dt><dt>1.5. <a href="section-addresses.html#idm140612068127312">Topics</a></dt><dt>1.6. <a href="section-addresses.html#idm140612068102064">Using subjects</a></dt><dt>1.7. <a href="section-addresses.html#idm140612068081200">Subje cts with multi-word keys</a></dt><dt>1.8. <a href="section-addresses.html#idm140612068051648">Assertions on Nodes</a></dt><dt>1.9. <a href="section-addresses.html#idm140612068042064">Creating a Queue Automatically</a></dt><dt>1.10. <a href="section-addresses.html#idm140612068033824">Browsing a Queue</a></dt><dt>1.11. <a href="section-addresses.html#idm140612068020320">Using the XML Exchange</a></dt><dt>1.12. <a href="ch01s08.html#idm140612067924000">Receiving Messages from Multiple Sources</a></dt><dt>1.13. <a href="ch01s09.html#idm140612067915952">Transactions</a></dt><dt>1.14. <a href="connections.html#idm140612067903856">Specifying Connection Options in C++, Python, and .NET</a></dt><dt>1.15. <a href="section-Maps.html#idm140612067834544">Sending Qpid Maps and Lists in Python</a></dt><dt>1.16. <a href="section-Maps.html#idm140612067815680">Sending Qpid Maps and Lists in C++</a></dt><dt>1.17. <a href="section-Maps.html#idm140612067792336">Sending Qpid Maps and Lists in .NET C#</a> </dt><dt>1.18. <a href="ch01s12.html#idm140612067758816">Request / Response Applications in C++</a></dt><dt>1.19. <a href="ch01s14.html#idm140612067739088">Tracking cluster membership</a></dt><dt>1.20. <a href="section-amqp0-10-mapping.html#idm140612067663776">Accessing the AMQP 0-10 Message Timestamp in Python</a></dt><dt>1.21. <a href="section-amqp0-10-mapping.html#idm140612067661392">Accessing the AMQP 0-10 Message Timestamp in C++</a></dt><dt>1.22. <a href="Message-Groups-Guide.html#idm140612067785264">Message Group Queue Creation - Python</a></dt><dt>1.23. <a href="Message-Groups-Guide.html#idm140612067783456">Message Group Queue Creation - C++</a></dt><dt>1.24. <a href="Message-Groups-Guide.html#idm140612067782016">Message Group Queue Creation - Java</a></dt><dt>1.25. <a href="Message-Groups-Guide.html#idm140612073762496">Sending Grouped Messages - Python</a></dt><dt>1.26. <a href="Message-Groups-Guide.html#idm140612073760720">Sending Grouped Messages - C++</a></dt><dt>1.27. < a href="Message-Groups-Guide.html#idm140612073758864">Sending Grouped Messages - Java</a></dt></dl></div></div><div class="navfooter"><hr /><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"> </td><td align="center" width="20%"> </td><td align="right" width="40%"> <a accesskey="n" href="using-the-qpid-messaging-api.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%"> </td><td align="center" width="20%"> </td><td align="right" valign="top" width="40%"> Chapter 1. Using the Qpid Messaging API</td></tr></table></div></div> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/qpid-site/blob/c3ab60f6/input/releases/qpid-cpp-1.39.0/messaging-api/book/prefetch.html.in ---------------------------------------------------------------------- diff --git a/input/releases/qpid-cpp-1.39.0/messaging-api/book/prefetch.html.in b/input/releases/qpid-cpp-1.39.0/messaging-api/book/prefetch.html.in new file mode 100644 index 0000000..8da5681 --- /dev/null +++ b/input/releases/qpid-cpp-1.39.0/messaging-api/book/prefetch.html.in @@ -0,0 +1,9 @@ +<div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">1.6. Receiver Capacity (Prefetch)</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="replay.html">Prev</a> </td><th align="center" width="60%">Chapter 1. Using the Qpid Messaging API</th><td align="right" width="20%"> <a accesskey="n" href="acknowledgements.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="prefetch"></a>1.6. Receiver Capacity (Prefetch)</h2></div></div></div><p>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 <em class="firstterm">prefetch</em> 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.</p></div><div class="navfooter"><hr /><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="replay.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="using-the-qpid-messaging-api.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="acknowledgements.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">1.5. Sender Capacity and Replay </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td align="right" valign="top" width="40%"> 1.7. Acknowledging Received Messages</td></tr></table></div></div> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/qpid-site/blob/c3ab60f6/input/releases/qpid-cpp-1.39.0/messaging-api/book/replay.html.in ---------------------------------------------------------------------- diff --git a/input/releases/qpid-cpp-1.39.0/messaging-api/book/replay.html.in b/input/releases/qpid-cpp-1.39.0/messaging-api/book/replay.html.in new file mode 100644 index 0000000..bf03f83 --- /dev/null +++ b/input/releases/qpid-cpp-1.39.0/messaging-api/book/replay.html.in @@ -0,0 +1,25 @@ +<div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">1.5. Sender Capacity and Replay</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="section-addresses.html">Prev</a> </td><th align="center" width="60%">Chapter 1. Using the Qpid Messaging API</th><td align="right" width="20%"> <a accesskey="n" href="prefetch.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="replay"></a>1.5. Sender Capacity and Replay</h2></div></div></div><p>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.</p><p>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.</p><p>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.</p><p>If the connection fails and is transparently reconnected + (see <a class="xref" href="connections.html#connection-options" title="1.10.2. Connection Options">Section 1.10.2, “Connection Options”</a> 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 + <a class="xref" href="section-addresses.html#table-link-properties" title="Table 1.3. Link Properties">Table 1.3, “Link Properties”</a>). At present only + at-least-once guarantees are offered. </p></div><div class="navfooter"><hr /><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="section-addresses.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="using-the-qpid-messaging-api.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="prefetch.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">1.4. Addresses </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td align="right" valign="top" width="40%"> 1.6. Receiver Capacity (Prefetch)</td></tr></table></div></div> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/qpid-site/blob/c3ab60f6/input/releases/qpid-cpp-1.39.0/messaging-api/book/section-Maps.html.in ---------------------------------------------------------------------- diff --git a/input/releases/qpid-cpp-1.39.0/messaging-api/book/section-Maps.html.in b/input/releases/qpid-cpp-1.39.0/messaging-api/book/section-Maps.html.in new file mode 100644 index 0000000..0517de7 --- /dev/null +++ b/input/releases/qpid-cpp-1.39.0/messaging-api/book/section-Maps.html.in @@ -0,0 +1,157 @@ +<div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">1.11. Maps and Lists in Message Content</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="connections.html">Prev</a> </td><th align="center" width="60%">Chapter 1. Using the Qpid Messaging API</th><td align="right" width="20%"> <a accesskey="n" href="ch01s12.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="section-Maps"></a>1.11. Maps and Lists in Message Content</h2></div></div></div><p>Many messaging applications need to exchange data across + languages and platforms, using the native datatypes of each + programming language.</p><p>The Qpid Messaging API supports <code class="classname">map</code> and <code class="classname">list</code> in message content. + + <a class="footnote" href="#ftn.idm140612067852752" id="idm140612067852752"><sup class="footnote">[9]</sup></a> + + <a class="footnote" href="#ftn.idm140612067852144" id="idm140612067852144"><sup class="footnote">[10]</sup></a> + Specific language support for <code class="classname">map</code> and <code class="classname">list</code> objects are shown in the following table. + </p><div class="table"><a id="tabl-Programming_in_Apache_Qpid-Qpid_Maps_in_Message_Content"></a><p class="title"><strong>Table 1.5. Map and List Representation in Supported Languages</strong></p><div class="table-contents"><table border="1" class="table" summary="Map and List Representation in Supported Languages"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Language</th><th>map</th><th>list</th></tr></thead><tbody><tr><td>Python</td><td><code class="classname">dict</code></td><td><code class="classname">list</code></td></tr><tr><td>C++</td><td><code class="classname">Variant::Map</code></td><td><code class="classname">Variant::List</code></td></tr><tr><td>Java</td><td><code class="classname">MapMessage</code></td><td><code class="classname"> </code></td></tr><tr><td>.NET</td><td><code class="classname">Dictionary<string, object></code></td><td><code class="classname">Collection<object></code></td></tr></tbody></table></div></div><br clas s="table-break" /><p> + In all languages, messages are encoded using AMQP's portable datatypes. + </p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="section-Python-Maps"></a>1.11.1. Qpid Maps and Lists in Python</h3></div></div></div><p>In Python, Qpid supports the <code class="classname">dict</code> and <code class="classname">list</code> types directly in message content. The following code shows how to send these structures in a message:</p><div class="example"><a id="idm140612067834544"></a><p class="title"><strong>Example 1.15. Sending Qpid Maps and Lists in Python</strong></p><div class="example-contents"><pre class="programlisting"> + 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) + </pre></div></div><br class="example-break" /><p>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++.</p><div class="table"><a id="table-Python-Maps"></a><p class="title"><strong>Table 1.6. Python Datatypes in Maps</strong></p><div class="table-contents"><table border="1" class="table" summary="Python Datatypes in Maps"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Python Datatype</th><th>→ C++</th><th>→ Java</th></tr></thead><tbody><tr><td>bool</td><td>bool</td><td>boolean</td></tr><tr><td>int</td><td>int64</td><td>long</td></tr><tr><td>long</td><td>int64</td><td>long</td></tr><tr><td>float</td><td>double</td><td>double</td></tr><tr><td>unicode</td><td>string</td><td>java.lang.String</td></tr><tr><td>uuid</td><td>qpid::types::Uuid</td><td>java.util.UUID</td></tr><tr><td>dict</td><td>Variant::Map</td><td>java.util.Map</td></tr><tr><td>list</td><td>Variant::List</td><td>java.util.List</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sectio n"><div class="titlepage"><div><div><h3 class="title"><a id="section-cpp-Maps"></a>1.11.2. Qpid Maps and Lists in C++</h3></div></div></div><p>In C++, Qpid defines the the + <code class="classname">Variant::Map</code> and + <code class="classname">Variant::List</code> types, which can be + encoded into message content. The following code shows how to + send these structures in a message:</p><div class="example"><a id="idm140612067815680"></a><p class="title"><strong>Example 1.16. Sending Qpid Maps and Lists in C++</strong></p><div class="example-contents"><pre class="programlisting"> + 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); + </pre></div></div><br class="example-break" /><p>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.</p><div class="table"><a id="table-cpp-Maps"></a><p class="title"><strong>Table 1.7. C++ Datatypes in Maps</strong></p><div class="table-contents"><table border="1" class="table" summary="C++ Datatypes in Maps"><colgroup><col /><col /><col /></colgroup><thead><tr><th>C++ Datatype</th><th>→ Python</th><th>→ Java</th></tr></thead><tbody><tr><td>bool</td><td>bool</td><td>boolean</td></tr><tr><td>uint16</td><td>int | long</td><td>short</td></tr><tr><td>uint32</td><td>int | long</td><td>int</td></tr><tr><td>uint64</td><td>int | long</td><td>long</td></tr><tr><td>int16</td><td>int | long</td><td>short</td></tr><tr><td>int32</td><td>int | long</td><td>int</td></tr><tr><td>int64</td><td>int | long</td><td>long</td></tr><tr><td>float</td><td>float</td><td>float</td></tr><tr><td>double</td><td>float</td><td>double</td></tr><tr><td>string</td><td>unicode</td><td>java.lang.String</td></tr><tr><td>qpid::types::Uuid</td><td>uu id</td><td>java.util.UUID</td></tr><tr><td>Variant::Map</td><td>dict</td><td>java.util.Map</td></tr><tr><td>Variant::List</td><td>list</td><td>java.util.List</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="section-dotnet-Maps"></a>1.11.3. Qpid Maps and Lists in .NET</h3></div></div></div><p> + The .NET binding for the Qpid Messaging API binds .NET managed data types + to C++ <code class="classname">Variant</code> data types. The following code shows how to + send Map and List structures in a message: + </p><div class="example"><a id="idm140612067792336"></a><p class="title"><strong>Example 1.17. Sending Qpid Maps and Lists in .NET C#</strong></p><div class="example-contents"><pre class="programlisting"> + 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); + </pre></div></div><br class="example-break" /><p> + The following table shows the mapping between datatypes in .NET and C++. + </p><div class="table"><a id="table-dotnet-Maps"></a><p class="title"><strong>Table 1.8. Datatype Mapping between C++ and .NET binding</strong></p><div class="table-contents"><table border="1" class="table" summary="Datatype Mapping between C++ and .NET binding"><colgroup><col /><col /></colgroup><thead><tr><th>C++ Datatype</th><th>→ .NET binding</th></tr></thead><tbody><tr><td>void</td><td>nullptr</td></tr><tr><td>bool</td><td>bool</td></tr><tr><td>uint8</td><td>byte</td></tr><tr><td>uint16</td><td>UInt16</td></tr><tr><td>uint32</td><td>UInt32</td></tr><tr><td>uint64</td><td>UInt64</td></tr><tr><td>uint8</td><td>char</td></tr><tr><td>int16</td><td>Int16</td></tr><tr><td>int32</td><td>Int32</td></tr><tr><td>int64</td><td>Int64</td></tr><tr><td>float</td><td>Single</td></tr><tr><td>double</td><td>Double</td></tr><tr><td>string</td><td>string + <a class="footnote" href="#ftn.callout-dotnet-string" id="callout-dotnet-string"><sup class="footnote">[a]</sup></a></td></tr><tr><td>qpid::types::Uuid</td><td>Guid</td></tr><tr><td>Variant::Map</td><td>Dictionary<string, object> + <a class="footnoteref" href="section-Maps.html#ftn.callout-dotnet-string"><sup class="footnoteref">[a]</sup></a></td></tr><tr><td>Variant::List</td><td>Collection<object> + <a class="footnoteref" href="section-Maps.html#ftn.callout-dotnet-string"><sup class="footnoteref">[a]</sup></a></td></tr></tbody><tbody class="footnotes"><tr><td colspan="2"><div class="footnote" id="ftn.callout-dotnet-string"><p><a class="para" href="#callout-dotnet-string"><sup class="para">[a] </sup></a>Strings are currently interpreted only with UTF-8 encoding.</p></div></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="footnotes"><br /><hr align="left" width="100" /><div class="footnote" id="ftn.idm140612067852752"><p><a class="para" href="#idm140612067852752"><sup class="para">[9] </sup></a>Unlike JMS, there is not a specific message type for + map messages.</p></div><div class="footnote" id="ftn.idm140612067852144"><p><a class="para" href="#idm140612067852144"><sup class="para">[10] </sup></a> + Note that the Qpid JMS client supports MapMessages whose values can be nested maps or lists. This is not standard JMS behaviour. + </p></div></div></div><div class="navfooter"><hr /><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="connections.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="using-the-qpid-messaging-api.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="ch01s12.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">1.10. Connections </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td align="right" valign="top" width="40%"> 1.12. The Request / Response Pattern</td></tr></table></div></div> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/qpid-site/blob/c3ab60f6/input/releases/qpid-cpp-1.39.0/messaging-api/book/section-addresses.html.in ---------------------------------------------------------------------- diff --git a/input/releases/qpid-cpp-1.39.0/messaging-api/book/section-addresses.html.in b/input/releases/qpid-cpp-1.39.0/messaging-api/book/section-addresses.html.in new file mode 100644 index 0000000..db9b845 --- /dev/null +++ b/input/releases/qpid-cpp-1.39.0/messaging-api/book/section-addresses.html.in @@ -0,0 +1,577 @@ +<div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">1.4. Addresses</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="ch01s03.html">Prev</a> </td><th align="center" width="60%">Chapter 1. Using the Qpid Messaging API</th><td align="right" width="20%"> <a accesskey="n" href="replay.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="section-addresses"></a>1.4. Addresses</h2></div></div></div><p>An <em class="firstterm">address</em> is the name of a message + target or message source. + + <a class="footnote" href="#ftn.idm140612068151440" id="idm140612068151440"><sup class="footnote">[2]</sup></a> + + 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. + </p><p>An address resolves to a <em class="firstterm">node</em>. The + Qpid Messaging API recognises two kinds of nodes, + <em class="firstterm">queues</em> and <em class="firstterm">topics</em> + + <a class="footnote" href="#ftn.idm140612068148208" id="idm140612068148208"><sup class="footnote">[3]</sup></a>. + + A queue stores each message until it has been received and + acknowledged, and only one receiver can receive a given message + + <a class="footnote" href="#ftn.idm140612068145664" id="idm140612068145664"><sup class="footnote">[4]</sup></a>. + + 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, + + <a class="footnote" href="#ftn.idm140612068144112" id="idm140612068144112"><sup class="footnote">[5]</sup></a> + + queues map to AMQP queues, and topics map to AMQP exchanges. + + <a class="footnote" href="#ftn.idm140612068143408" id="idm140612068143408"><sup class="footnote">[6]</sup></a> + </p><p>In the rest of this tutorial, we present many examples + using two programs that take an address as a command line + parameter. <span class="command"><strong>spout</strong></span> sends messages to the + target address, <span class="command"><strong>drain</strong></span> 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 <span class="command"><strong>-h</strong></span> option + for documentation on these options. + + <a class="footnote" href="#ftn.idm140612068139744" id="idm140612068139744"><sup class="footnote">[7]</sup></a> + + + The examples in this tutorial also use the + <span class="command"><strong>qpid-config</strong></span> utility to configure AMQP 0-10 + queues and exchanges on a Qpid broker. + </p><div class="example"><a id="idm140612068136432"></a><p class="title"><strong>Example 1.4. Queues</strong></p><div class="example-contents"><p>Create a queue with <span class="command"><strong>qpid-config</strong></span>, send a message using + <span class="command"><strong>spout</strong></span>, and read it using <span class="command"><strong>drain</strong></span>:</p><pre class="screen"> + $ qpid-config add queue hello-world + $ ./spout hello-world + $ ./drain hello-world + + Message(properties={spout-id:c877e622-d57b-4df2-bf3e-6014c68da0ea:0}, content='') + </pre><p>The queue stored the message sent by <span class="command"><strong>spout</strong></span> and delivered + it to <span class="command"><strong>drain</strong></span> when requested.</p><p>Once the message has been delivered and and acknowledged + by <span class="command"><strong>drain</strong></span>, it is no longer available on the queue. If we run + <span class="command"><strong>drain</strong></span> one more time, no messages will be retrieved.</p><pre class="screen"> + $ ./drain hello-world + $ + </pre></div></div><br class="example-break" /><div class="example"><a id="idm140612068127312"></a><p class="title"><strong>Example 1.5. Topics</strong></p><div class="example-contents"><p>This example is similar to the previous example, but it + uses a topic instead of a queue.</p><p>First, use <span class="command"><strong>qpid-config</strong></span> to remove the queue + and create an exchange with the same name:</p><pre class="screen"> + $ qpid-config del queue hello-world + $ qpid-config add exchange topic hello-world + </pre><p>Now run <span class="command"><strong>drain</strong></span> and <span class="command"><strong>spout</strong></span> the same way we did in the previous example:</p><pre class="screen"> + $ ./spout hello-world + $ ./drain hello-world + $ + </pre><p>Topics deliver messages immediately to any interested + receiver, and do not store messages. Because there were no + receivers at the time <span class="command"><strong>spout</strong></span> sent the + message, it was simply discarded. When we ran + <span class="command"><strong>drain</strong></span>, there were no messages to + receive.</p><p>Now let's run <span class="command"><strong>drain</strong></span> first, using the + <code class="literal">-t</code> option to specify a timeout in seconds. + While <span class="command"><strong>drain</strong></span> is waiting for messages, + run <span class="command"><strong>spout</strong></span> in another window.</p><p><span class="emphasis"><em>First Window:</em></span></p><pre class="screen"> + $ ./drain -t 30 hello-word + </pre><p><span class="emphasis"><em>Second Window:</em></span></p><pre class="screen"> + $ ./spout hello-word + </pre><p>Once <span class="command"><strong>spout</strong></span> has sent a message, return + to the first window to see the output from + <span class="command"><strong>drain</strong></span>:</p><pre class="screen"> + Message(properties={spout-id:7da2d27d-93e6-4803-8a61-536d87b8d93f:0}, content='') + </pre><p>You can run <span class="command"><strong>drain</strong></span> in several separate + windows; each creates a subscription for the exchange, and + each receives all messages sent to the exchange.</p></div></div><br class="example-break" /><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm140612068111184"></a>1.4.1. Address Strings</h3></div></div></div><p>So far, our examples have used address strings that + contain only the name of a node. An <em class="firstterm">address + string</em> can also contain a + <em class="firstterm">subject</em> and + <em class="firstterm">options</em>.</p><p>The syntax for an address string is:</p><pre class="programlisting"> + address_string ::= <address> [ / <subject> ] [ ; <options> ] + options ::= { <key> : <value>, ... } + </pre><p>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 + <a class="xref" href="section-addresses.html#section-address-string-bnf" title="1.4.4. Address String Grammar">Section 1.4.4, “Address String Grammar”</a>.</p><p>So far, the address strings in this tutorial have only + used simple names. The following sections show how to use + subjects and options.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm140612068105936"></a>1.4.2. Subjects</h3></div></div></div><p>Every message has a property called + <em class="firstterm">subject</em>, 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. + </p><p> + In AMQP 0-10, each exchange type has its own matching + algorithm. This is discussed in + <a class="xref" href="section-amqp0-10-mapping.html" title="1.16. The AMQP 0-10 mapping">Section 1.16, “The AMQP 0-10 mapping”</a>. + </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> + 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. + </p></div><div class="example"><a id="idm140612068102064"></a><p class="title"><strong>Example 1.6. Using subjects</strong></p><div class="example-contents"><p>In this example we show how subjects affect message + flow.</p><p>First, let's use <span class="command"><strong>qpid-config</strong></span> to create a topic exchange.</p><pre class="screen"> + $ qpid-config add exchange topic news-service + </pre><p>Now we use drain to receive messages from <code class="literal">news-service</code> that match the subject <code class="literal">sports</code>.</p><p><span class="emphasis"><em>First Window:</em></span></p><pre class="screen"> + $ ./drain -t 30 news-service/sports + </pre><p>In a second window, let's send messages to <code class="literal">news-service</code> using two different subjects:</p><p><span class="emphasis"><em>Second Window:</em></span></p><pre class="screen"> + $ ./spout news-service/sports + $ ./spout news-service/news + </pre><p>Now look at the first window, the message with the + subject <code class="literal">sports</code> has been received, but not + the message with the subject <code class="literal">news</code>:</p><pre class="screen"> + Message(properties={qpid.subject:sports, spout-id:9441674e-a157-4780-a78e-f7ccea998291:0}, content='') + </pre><p>If you run <span class="command"><strong>drain</strong></span> in multiple + windows using the same subject, all instances of + <span class="command"><strong>drain</strong></span> receive the messages for that + subject.</p></div></div><br class="example-break" /><p>The AMQP exchange type we are using here, + <code class="literal">amq.topic</code>, can also do more sophisticated + matching. + + A sender's subject can contain multiple words separated by a + <span class="quote">“<span class="quote">.</span>”</span> delimiter. For instance, in a news + application, the sender might use subjects like + <code class="literal">usa.news</code>, <code class="literal">usa.weather</code>, + <code class="literal">europe.news</code>, or + <code class="literal">europe.weather</code>. + + The receiver's subject can include wildcard characters— + <span class="quote">“<span class="quote">#</span>”</span> matches one or more words in the message's + subject, <span class="quote">“<span class="quote">*</span>”</span> matches a single word. + + For instance, if the subject in the source address is + <code class="literal">*.news</code>, it matches messages with the + subject <code class="literal">europe.news</code> or + <code class="literal">usa.news</code>; if it is + <code class="literal">europe.#</code>, it matches messages with subjects + like <code class="literal">europe.news</code> or + <code class="literal">europe.pseudo.news</code>.</p><div class="example"><a id="idm140612068081200"></a><p class="title"><strong>Example 1.7. Subjects with multi-word keys</strong></p><div class="example-contents"><p>This example uses drain and spout to demonstrate the + use of subjects with two-word keys.</p><p>Let's use <span class="command"><strong>drain</strong></span> with the subject + <code class="literal">*.news</code> to listen for messages in which + the second word of the key is + <code class="literal">news</code>.</p><p><span class="emphasis"><em>First Window:</em></span></p><pre class="screen"> + $ ./drain -t 30 news-service/*.news + </pre><p>Now let's send messages using several different + two-word keys:</p><p><span class="emphasis"><em>Second Window:</em></span></p><pre class="screen"> + $ ./spout news-service/usa.news + $ ./spout news-service/usa.sports + $ ./spout news-service/europe.sports + $ ./spout news-service/europe.news + </pre><p>In the first window, the messages with + <code class="literal">news</code> in the second word of the key have + been received:</p><pre class="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='') + </pre><p>Next, let's use <span class="command"><strong>drain</strong></span> with the + subject <code class="literal">#.news</code> to match any sequence of + words that ends with <code class="literal">news</code>.</p><p><span class="emphasis"><em>First Window:</em></span></p><pre class="screen"> + $ ./drain -t 30 news-service/#.news + </pre><p>In the second window, let's send messages using a + variety of different multi-word keys:</p><p><span class="emphasis"><em>Second Window:</em></span></p><pre class="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 + </pre><p>In the first window, messages with + <code class="literal">news</code> in the last word of the key have been + received:</p><pre class="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='') + </pre></div></div><br class="example-break" /></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm140612068065424"></a>1.4.3. Address String Options</h3></div></div></div><p> + The options in an address string can contain additional + information for the senders or receivers created for it, + including: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + Policies for assertions about the node to which an address + refers. + </p><p> + For instance, in the address string <code class="literal">my-queue; + {assert: always, node:{ type: queue }}</code>, the node + named <code class="literal">my-queue</code> must be a queue; if not, + the address does not resolve to a node, and an exception + is raised. + </p></li><li class="listitem"><p> + Policies for automatically creating or deleting the node to which an address refers. + </p><p> + For instance, in the address string <code class="literal">xoxox ; {create: always}</code>, + the queue <code class="literal">xoxox</code> is created, if it does + not exist, before the address is resolved. + </p></li><li class="listitem"><p> + Extension points that can be used for sender/receiver configuration. + </p><p> + For instance, if the address for a receiver is + <code class="literal">my-queue; {mode: browse}</code>, the receiver + works in <code class="literal">browse</code> mode, leaving messages + on the queue so other receivers can receive them. + </p></li><li class="listitem"><p> + Extension points providing more direct control over the underlying protocol. + </p><p> + For instance, the <code class="literal">x-bindings</code> property + allows greater control over the AMQP 0-10 binding process + when an address is resolved. + </p></li></ul></div><p> + Let's use some examples to show how these different kinds of + address string options affect the behavior of senders and + receives. + </p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="idm140612068053408"></a>1.4.3.1. assert</h4></div></div></div><p> + In this section, we use the <code class="literal">assert</code> option + to ensure that the address resolves to a node of the required + type. + </p><div class="example"><a id="idm140612068051648"></a><p class="title"><strong>Example 1.8. Assertions on Nodes</strong></p><div class="example-contents"><p>Let's use <span class="command"><strong>qpid-config</strong></span> to create a + queue and a topic.</p><pre class="screen"> + $ qpid-config add queue my-queue + $ qpid-config add exchange topic my-topic + </pre><p> + We can now use the address specified to drain to assert that it is + of a particular type: + </p><pre class="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 + </pre><p> + The first attempt passed without error as my-queue is indeed a + queue. The second attempt however failed; my-queue is not a + topic. + </p><p> + We can do the same thing for my-topic: + </p><pre class="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 + </pre></div></div><br class="example-break" /><p>Now let's use the <code class="literal">create</code> option to + create the queue <code class="literal">xoxox</code> if it does not already + exist:</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="idm140612068043904"></a>1.4.3.2. create</h4></div></div></div><p>In previous examples, we created the queue before + listening for messages on it. Using <code class="literal">create: + always</code>, the queue is automatically created if it + does not exist.</p><div class="example"><a id="idm140612068042064"></a><p class="title"><strong>Example 1.9. Creating a Queue Automatically</strong></p><div class="example-contents"><p><span class="emphasis"><em>First Window:</em></span></p><pre class="screen">$ ./drain -t 30 "xoxox ; {create: always}"</pre><p>Now we can send messages to this queue:</p><p><span class="emphasis"><em>Second Window:</em></span></p><pre class="screen">$ ./spout "xoxox ; {create: always}"</pre><p>Returning to the first window, we see that <span class="command"><strong>drain</strong></span> has received this message:</p><pre class="screen">Message(properties={spout-id:1a1a3842-1a8b-4f88-8940-b4096e615a7d:0}, content='')</pre></div></div><br class="example-break" /><p>The details of the node thus created can be controlled by further options within the node. See <a class="xref" href="section-addresses.html#table-node-properties" title="Table 1.2. Node Properties">Table 1.2, ̶ 0;Node Properties”</a> for details.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="idm140612068035792"></a>1.4.3.3. browse</h4></div></div></div><p>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 + <code class="literal">browse</code> option to receive messages without + removing them from a queue.</p><div class="example"><a id="idm140612068033824"></a><p class="title"><strong>Example 1.10. Browsing a Queue</strong></p><div class="example-contents"><p> + Let's use the browse mode to receive messages without + removing them from the queue. First we send three messages to the + queue: + </p><pre class="screen"> + $ ./spout my-queue --content one + $ ./spout my-queue --content two + $ ./spout my-queue --content three + </pre><p>Now we use drain to get those messages, using the browse option:</p><pre class="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') + </pre><p>We can confirm the messages are still on the queue by repeating the drain:</p><pre class="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') + </pre></div></div><br class="example-break" /></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="idm140612068028704"></a>1.4.3.4. x-bindings</h4></div></div></div><p>Greater control over the AMQP 0-10 binding process can + be achieved by including an <code class="literal">x-bindings</code> + 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.</p><p>An instance of the XML Exchange must be added before it + can be used:</p><pre class="programlisting"> + $ qpid-config add exchange xml xml + </pre><p>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 <span class="quote">“<span class="quote">.</span>”</span>), then it + is applied to the content of the message, which must be + well-formed XML. For instance, <code class="literal">./weather</code> is + a valid XQuery, which matches any message in which the root + element is named <code class="literal">weather</code>. Here is an + address string that contains this query:</p><pre class="programlisting"> + xml; { + link: { + x-bindings: [{exchange:xml, key:weather, arguments:{xquery:"./weather"} }] + } + } + </pre><p>When using longer queries with <span class="command"><strong>drain</strong></span>, + it is often useful to place the query in a file, and use + <span class="command"><strong>cat</strong></span> in the command line. We do this in the + following example.</p><div class="example"><a id="idm140612068020320"></a><p class="title"><strong>Example 1.11. Using the XML Exchange</strong></p><div class="example-contents"><p>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:</p><pre class="programlisting"> + + 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 + </pre><p>We can specify this query in an x-binding to listen to messages that meet the criteria specified by the query:</p><p><span class="emphasis"><em>First Window:</em></span></p><pre class="screen"> + $ ./drain -f "xml; {link:{x-bindings:[{key:'weather', + arguments:{xquery:\"$(cat rdu.xquery )\"}}]}}" + </pre><p>In another window, let's create an XML message that meets the criteria in the query, and place it in the file <code class="filename">rdu.xml</code>:</p><pre class="programlisting"> + + <weather> + <station>Raleigh-Durham International Airport (KRDU)</station> + <wind_speed_mph>16</wind_speed_mph> + <temperature_f>70</temperature_f> + <dewpoint>35</dewpoint> + </weather> + </pre><p>Now let's use <span class="command"><strong>spout</strong></span> to send this message to the XML exchange:</p><p><span class="emphasis"><em>Second Window:</em></span></p><pre class="screen"> + spout --content "$(cat rdu.xml)" xml/weather + </pre><p>Returning to the first window, we see that the message has been received:</p><pre class="screen">$ ./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>') + </pre></div></div><br class="example-break" /></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="idm140612068008336"></a>1.4.3.5. Address String Options - Reference</h4></div></div></div><div class="table"><a id="idm140612068007696"></a><p class="title"><strong>Table 1.1. Address String Options</strong></p><div class="table-contents"><table border="1" class="table" summary="Address String Options" width="100%"><colgroup><col /><col /><col /></colgroup><thead><tr><th>option</th><th>value</th><th>semantics</th></tr></thead><tbody><tr><td> + assert + </td><td> + one of: always, never, sender or receiver + </td><td> + 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. + </td></tr><tr><td> + create + </td><td> + one of: always, never, sender or receiver + </td><td> + 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. + </td></tr><tr><td> + delete + </td><td> + one of: always, never, sender or receiver + </td><td> + Delete the node when the sender or receiver is closed. + </td></tr><tr><td> + node + </td><td> + A nested map containing the entries shown in <a class="xref" href="section-addresses.html#table-node-properties" title="Table 1.2. Node Properties">Table 1.2, “Node Properties”</a>. + </td><td> + Specifies properties of the node to which the address + refers. These are used in conjunction with the assert or + create options. + </td></tr><tr><td> + link + </td><td> + A nested map containing the entries shown in <a class="xref" href="section-addresses.html#table-link-properties" title="Table 1.3. Link Properties">Table 1.3, “Link Properties”</a>. + </td><td> + Used to control the establishment of a conceptual link + from the client application to or from the target/source + address. + </td></tr><tr><td> + mode + </td><td> + one of: browse, consume + </td><td> + 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. + </td></tr></tbody></table></div></div><br class="table-break" /><div class="table"><a id="table-node-properties"></a><p class="title"><strong>Table 1.2. Node Properties</strong></p><div class="table-contents"><table border="1" class="table" summary="Node Properties" width="100%"><colgroup><col /><col /><col /></colgroup><thead><tr><th>property</th><th>value</th><th>semantics</th></tr></thead><tbody><tr><td> + type + </td><td> + topic, queue + </td><td> + Indicates the type of the node. + </td></tr><tr><td> + durable + </td><td> + True, False + </td><td> + Indicates whether the node survives a loss of + volatile storage e.g. if the broker is restarted. + </td></tr><tr><td> + x-declare + </td><td> + A nested map whose values correspond to the valid fields + on an AMQP 0-10 queue-declare or exchange-declare + command. + </td><td> + These values are used to fine tune the creation or + assertion process. Note however that they are protocol + specific. + </td></tr><tr><td> + x-bindings + </td><td> + 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: + + <pre class="programlisting"> + [ + { + exchange: <exchange>, + queue: <queue>, + key: <key>, + arguments: { + <key_1>: <value_1>, + ..., + <key_n>: <value_n> } + }, + ... + ] + </pre> + </td><td> + 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. + </td></tr></tbody></table></div></div><br class="table-break" /><div class="table"><a id="table-link-properties"></a><p class="title"><strong>Table 1.3. Link Properties</strong></p><div class="table-contents"><table border="1" class="table" summary="Link Properties" width="100%"><colgroup><col /><col /><col /></colgroup><thead><tr><th>option</th><th>value</th><th>semantics</th></tr></thead><tbody><tr><td> + reliability + </td><td> + one of: unreliable, at-least-once, at-most-once, exactly-once + </td><td> + Reliability indicates the level of reliability that + the sender or receiver. <code class="literal">unreliable</code> + and <code class="literal">at-most-once</code> are currently + treated as synonyms, and allow messages to be lost if + a broker crashes or the connection to a broker is + lost. <code class="literal">at-least-once</code> guarantees that + a message is not lost, but duplicates may be + received. <code class="literal">exactly-once</code> guarantees + that a message is not lost, and is delivered precisely + once. Currently only <code class="literal">unreliable</code> + and <code class="literal">at-least-once</code> are supported. + <a class="footnote" href="#ftn.idm140612067963728" id="idm140612067963728"><sup class="footnote">[a]</sup></a> + </td></tr><tr><td> + durable + </td><td> + True, False + </td><td> + Indicates whether the link survives a loss of + volatile storage e.g. if the broker is restarted. + </td></tr><tr><td> + x-declare + </td><td> + A nested map whose values correspond to the valid fields + of an AMQP 0-10 queue-declare command. + </td><td> + 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. + </td></tr><tr><td> + x-subscribe + </td><td> + A nested map whose values correspond to the valid fields + of an AMQP 0-10 message-subscribe command. + </td><td> + These values can be used to customise the subscription. + </td></tr><tr><td> + x-bindings + </td><td> + 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. + </td><td> + 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. + </td></tr></tbody><tbody class="footnotes"><tr><td colspan="3"><div class="footnote" id="ftn.idm140612067963728"><p><a class="para" href="#idm140612067963728"><sup class="para">[a] </sup></a>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.</p></div></td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="section-address-string-bnf"></a>1.4.4. Address String Grammar</h3></div></div></div><p>This section provides a formal grammar for address strings.</p><p><strong>Tokens. </strong>The following regular expressions define the tokens used + to parse address strings:</p><pre class="programlisting"> + 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]+ + </pre><p><strong>Grammar. </strong>The formal grammar for addresses is given below:</p><pre class="programlisting"> + 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 )* )? "]" + </pre><p><strong>Address String Options. </strong>The address string options map supports the following parameters:</p><pre class="programlisting"> + <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> ... } + } + } + </pre><div class="itemizedlist"><p class="title"><strong>Create, Delete, and Assert Policies</strong></p><p>The create, delete, and assert policies specify who should + perfom the associated action:</p><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>always</em></span>: the action is performed by any messaging client</p></li><li class="listitem"><p><span class="emphasis"><em>sender</em></span>: the action is only performed by a sender</p></li><li class="listitem"><p><span class="emphasis"><em>receiver</em></span>: the action is only performed by a receiver</p></li><li class="listitem"><p><span class="emphasis"><em>never</em></span>: the action is never performed (this is the default)</p></li></ul></div><div class="itemizedlist"><p class="title"><strong>Node-Type</strong></p><p>The node-type is one of:</p><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>topic</em></span>: in the AMQP 0-10 + mapping, a topic node defaults to the topic exchange, x-declare + may be used to specify other exchange types</p></li><li class="listitem"><p><span class="emphasis"><em>queue</em></span>: this is the default node-type</p></li></ul></div></div><div class="footnotes"><br /><hr align="left" width="100" /><div class="footnote" id="ftn.idm140612068151440"><p><a class="para" href="#idm140612068151440"><sup class="para">[2] </sup></a>In the programs we have just seen, we used + <code class="literal">amq.topic</code> 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.</p></div><div class="footnote" id="ftn.idm140612068148208"><p><a class="para" href="#idm140612068148208"><sup class="para">[3] </sup></a>The terms <span class="emphasis"><em>queue</em></span> and + <span class="emphasis"><em>topic</em></span> 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 <span class="emphasis"><em>topic exchange</em></span>. When the term + <span class="emphasis"><em>topic</em></span> occurs alone, it refers to a + Messaging API topic, not the topic + exchange.</p></div><div class="footnote" id="ftn.idm140612068145664"><p><a class="para" href="#idm140612068145664"><sup class="para">[4] </sup></a>There are exceptions to this rule; for instance, + a receiver can use <code class="literal">browse</code> mode, which leaves + messages on the queue for other receivers to + read.</p></div><div class="footnote" id="ftn.idm140612068144112"><p><a class="para" href="#idm140612068144112"><sup class="para">[5] </sup></a>The AMQP 0-10 implementation is the only one + that currently exists.</p></div><div class="footnote" id="ftn.idm140612068143408"><p><a class="para" href="#idm140612068143408"><sup class="para">[6] </sup></a>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.</p></div><div class="footnote" id="ftn.idm140612068139744"><p><a class="para" href="#idm140612068139744"><sup class="para">[7] </sup></a>Currently, the C++, Python, and .NET C# + implementations of <span class="command"><strong>drain</strong></span> and + <span class="command"><strong>spout</strong></span> have slightly different + options. This tutorial uses the C++ implementation. The + options will be reconciled in the near + future.</p></div></div></div><div class="navfooter"><hr /><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="ch01s03.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="using-the-qpid-messaging-api.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="replay.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">1.3. A Simple Messaging Program in .NET C# </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td align="right" valign="top" width="40%"> 1.5. Sender Capacity and Replay</td></tr></table></div></div> \ No newline at end of file --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org For additional commands, e-mail: commits-h...@qpid.apache.org
