Return-Path: Delivered-To: apmail-qpid-commits-archive@www.apache.org Received: (qmail 1559 invoked from network); 23 Jul 2010 16:49:12 -0000 Received: from unknown (HELO mail.apache.org) (140.211.11.3) by 140.211.11.9 with SMTP; 23 Jul 2010 16:49:12 -0000 Received: (qmail 78195 invoked by uid 500); 23 Jul 2010 16:49:12 -0000 Delivered-To: apmail-qpid-commits-archive@qpid.apache.org Received: (qmail 78179 invoked by uid 500); 23 Jul 2010 16:49:12 -0000 Mailing-List: contact commits-help@qpid.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@qpid.apache.org Delivered-To: mailing list commits@qpid.apache.org Received: (qmail 78172 invoked by uid 99); 23 Jul 2010 16:49:12 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 23 Jul 2010 16:49:12 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 23 Jul 2010 16:49:05 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id 1FD0523889B3; Fri, 23 Jul 2010 16:48:13 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: svn commit: r967163 [1/4] - in /qpid/site/docs/books/0.7/Programming-In-Apache-Qpid: html/ pdf/ Date: Fri, 23 Jul 2010 16:48:12 -0000 To: commits@qpid.apache.org From: jonathan@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20100723164813.1FD0523889B3@eris.apache.org> Author: jonathan Date: Fri Jul 23 16:48:11 2010 New Revision: 967163 URL: http://svn.apache.org/viewvc?rev=967163&view=rev Log: .NET binding, various editorial changes. Modified: qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch01.html qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02.html qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s02.html qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s03.html qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s04.html qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s05.html qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s06.html qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s07.html qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s08.html qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s09.html qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s10.html qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s11.html qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s12.html qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch03.html qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch03s02.html qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch03s03.html qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch03s04.html qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch03s05.html qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch04.html qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch04s02.html qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch04s03.html qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch04s04.html qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch04s05.html qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/index.html qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/pdf/Programming-In-Apache-Qpid.fo qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/pdf/Programming-In-Apache-Qpid.pdf Modified: qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch01.html URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch01.html?rev=967163&r1=967162&r2=967163&view=diff ============================================================================== --- qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch01.html (original) +++ qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch01.html Fri Jul 23 16:48:11 2010 @@ -1,20 +1,20 @@ -Chapter 1. Introduction
Chapter 1. Introduction
Prev   Next

Chapter 1. Introduction

Apache Qpid is a reliable, asynchronous messaging system that +Chapter 1. Introduction

Chapter 1. Introduction
Prev   Next

Chapter 1. Introduction

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.

  • - On the Java platform, Qpid uses the - established Java JMS - API. -

  • - On the .NET platform, Qpid defines - a WCF - binding. -

  • - For Python, C++, and .NET, Qpid defines its own messaging API, the - Qpid Messaging API, which is - conceptually similar in each supported language. -

  • - Support for this API in Ruby will be added - soon (Ruby currently uses an API that is closely + On the Java platform, Qpid uses the + established Java JMS + API. +

  • + On the .NET platform, Qpid defines + a WCF + binding. +

  • + For Python and C++, Qpid defines its own messaging API, the + Qpid Messaging API, which is + conceptually similar in each supported language. +

  • + Support for this API in Ruby will be added + soon (Ruby currently uses an API that is closely tied to the AMQP version). -

Prev   Next
Programming in Apache Qpid Home Chapter 2. Using the Qpid Messaging API
+

Prev   Next
Programming in Apache Qpid Home Chapter 2. Using the Qpid Messaging API
Modified: qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02.html URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02.html?rev=967163&r1=967162&r2=967163&view=diff ============================================================================== --- qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02.html (original) +++ qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02.html Fri Jul 23 16:48:11 2010 @@ -1,4 +1,4 @@ -Chapter 2. Using the Qpid Messaging API
Chapter 2. Using the Qpid Messaging API
Prev   Next

Chapter 2. Using the Qpid Messaging API

Table of Contents

1. A Simple Messaging Program in C++
2. A Simple Messaging Program in Python
3. A Simple Messaging Program in .NET C#
4. Addresses
4.1. Address Strings
4.2. Subjects
4.3. Address String Options
4.4. Address String Grammar
5. Logging
5.1. Logging in C++
5.2. Logging in Python
6. Receiving Messages from Multiple Sources
7. Request / Response
8. Maps in Message Content
8.1. Qpid Maps in Python
8.2. Qpid Maps in C++
9. Performance
9.1. Batching Acknowledgements
9.2. Prefetch
9.3. Sizing the Replay Buffer
10. Reliability
10.1. Reconnect
10.2. Guaranteed Delivery
10.3. Reliability Options in Senders and Receivers
10.4. Cluster Failover
11. Security
12. Transactions
13. The AMQP 0-10 mapping

The Qpid Messaging API is quite simple, consisting of only a +Chapter 2. Using the Qpid Messaging API

Chapter 2. Using the Qpid Messaging API
Prev   Next

Chapter 2. Using the Qpid Messaging API

Table of Contents

2.1. A Simple Messaging Program in C++
2.2. A Simple Messaging Program in Python
2.3. A Simple Messaging Program in .NET C#
2.4. Addresses
2.4.1. Address Strings
2.4.2. Subjects
2.4.3. Address String Options
2.4.4. Address String Grammar
2.5. Sender Capacity and Replay
2.6. Receiver Capacity (Prefetch)
2.7. Acknowledging Received Messages
2.8. Receiving Messages from Multiple Sources
2.9. Transactions
2.10. Connection Options
2.11. Maps in Message Content
2.11.1. Qpid Maps in Python
2.11.2. Qpid Maps in C++
2.11.3. Qpid Maps in .NET
2.12. The Request / Response Pattern
2.13. Performance Tips
2.14. Cluster Failover
2.15. Logging
2.15.1. Logging in C++
2.15.2. Logging in Python
2.16. The AMQP 0-10 mapping

The Qpid Messaging API is quite simple, consisting of only a handful of core classes.

  • A message consists of a standard set @@ -26,9 +26,9 @@

The following sections show how to use these classes in a simple messaging program. -

1. A Simple Messaging Program in C++

The following C++ program shows how to create a connection, +

2.1. A Simple Messaging Program in C++

The following C++ program shows how to create a connection, create a session, send messages using a sender, and receive - messages using a receiver.

Example 2.1. "Hello world!" in C++

+        messages using a receiver.
Example 2.1. "Hello world!" in C++
 #include <qpid/messaging/Connection.h>
 #include <qpid/messaging/Message.h>
 #include <qpid/messaging/Receiver.h>
@@ -63,4 +63,6 @@ int main(int argc, char** argv) {
         connection.close();
         return 1;   
     }
-}
(1) 
Establishes the connection with the messaging broker.
(2) 
Creates a session object, which maintains the state of all interactions with the messaging broker, and manages senders and receivers.
(3) 
Creates a receiver that reads from the given address.
(4) 

 
Creates a sender that sends to the given address.
(5) 
Reads the next message. The duration is optional, if omitted, will wait indefinitely for the next message.
(6) 
Acknowledges messages that have been read. To guarantee delivery, a message remains on the messaging broker until it is acknowledged by a client. session.acknowledge() acknowledges all unacknowledged messages for the given session—this allows acknowledgements to be batched, which is  more efficient than acknowledging messages individually.
(7) <
 /p>
Closes the connection, all sessions managed by the connection, and all senders and receivers managed by each session.

Prev   Next
Chapter 1. Introduction Home 2. A Simple Messaging Program in Python
+}

(1)

Establishes the connection with the messaging broker.

(2)

Creates a session object on which messages will be sent and received.

(3)

Creates a receiver that receives messages from the given address.

(4)

Creates a sender that sends to the given address.

(5)

Receives the next message. The duration is optional, if omitted, will wait indefinitely for the next message.

(6)

Acknowledges receipt of all fetched messages on the + session. This informs the broker that the messages were + transferred and processed by the client successfully.

(7)

Closes the connection, all sessions managed by the connection, and all senders and receivers managed by each session.


Prev   Next
Chapter 1. Introduction Home 2.2. A Simple Messaging Program in Python
Modified: qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s02.html URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s02.html?rev=967163&r1=967162&r2=967163&view=diff ============================================================================== --- qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s02.html (original) +++ qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s02.html Fri Jul 23 16:48:11 2010 @@ -1,6 +1,6 @@ -2. A Simple Messaging Program in Python
2. A Simple Messaging Program in Python
Prev Chapter 2. Using the Qpid Messaging API Next

2. A Simple Messaging Program in Python

The following Python program shows how to create a +2.2. A Simple Messaging Program in Python

2.2. A Simple Messaging Program in Python
Prev Chapter 2. Using the Qpid Messaging API Next

2.2. A Simple Messaging Program in Python

The following Python program shows how to create a connection, create a session, send messages using a sender, and - receive messages using a receiver.

Example 2.2. "Hello world!" in Python

+        receive messages using a receiver.
Example 2.2. "Hello world!" in Python
 import sys
 from qpid.messaging import *
 
@@ -26,4 +26,6 @@ except MessagingError,m:
   print m
 finally:
   connection.close()  (7)
-
(1) 
Establishes the connection with the messaging broker.
(2) 
Creates a session object, which maintains the state of all interactions with the messaging broker, and manages senders and receivers.
(4) 
Creates a receiver that reads from the given address.
(3) 
Creates a sender that sends to the given address.
(5) 
Reads the next message. The duration is optional, if omitted, will wait indefinitely for the next message.
(6) 
Acknowledges messages that have been read. To guarantee delivery, a message remains on the messaging broker until it is acknowledged by a client. session.acknowledge() acknowledges all unacknowledged messages for the given session—this allows acknowledgements to be batched, which is  more efficient than acknowledging messages individually.
(7) 
Closes the connection, all sessions managed by the connection, and all senders and receivers managed by each session.

Prev Up Next
Chapter 2. Using the Qpid Messaging API Home 3. A Simple Messaging Program in .NET C#
+

(1)

Establishes the connection with the messaging broker.

(2)

Creates a session object on which messages will be sent and received.

(4)

Creates a receiver that receives messages from the given address.

(3)

Creates a sender that send s to the given address.

(5)

Receives the next message. The duration is optional, if omitted, will wait indefinitely for the next message.

(6)

Acknowledges receipt of all fetched messages on + the session. This informs the broker that the messages were + transfered and processed by the client successfully.

(7)

Closes the connection, all sessions managed by the connection, and all senders and receivers managed by each session.


Prev Up Next
Chapter 2. Using the Qpid Messaging API Home 2.3. A Simple Messaging Progr am in .NET C#
Modified: qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s03.html URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s03.html?rev=967163&r1=967162&r2=967163&view=diff ============================================================================== --- qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s03.html (original) +++ qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s03.html Fri Jul 23 16:48:11 2010 @@ -1,6 +1,9 @@ -3. A Simple Messaging Program in .NET C#
3. A Simple Messaging Program in .NET C#
Prev Chapter 2. Using the Qpid Messaging API Next

3. A Simple Messaging Program in .NET C#

The following .NET C# program shows how to create a connection, +2.3. A Simple Messaging Program in .NET C#

2.3. A Simple Messaging Program in .NET C#
Prev Chapter 2. Using the Qpid Messaging API Ne xt

2.3. A Simple Messaging Program in .NET C#

The following .NET C# program shows how to create a connection, create a session, send messages using a sender, and receive - messages using a receiver.

Example 2.3. "Hello world!" in .NET C#

+        messages using a receiver. The .NET binding for the Qpid C++ Messaging API
+        applies to all .NET Framework managed code languages. C# was chosen
+        for illustration purposes only.
+      
Example 2.3. "Hello world!" in .NET C#
 using System;
 using Org.Apache.Qpid.Messaging;  (1)
 
@@ -36,4 +39,6 @@ namespace Org.Apache.Qpid.Messaging {
     }
 }
 
-
(1) 
Selects the Qpid Messaging namespace. A project reference to the Org.Apache.Qpid.Messaging dll defines the Qpid Messaging namespace objects and methods.
(2) 
Establishes the connection with the messaging broker.
(3) 
Creates a session object, which maintains the state of all interactions with the messaging broker, and manages senders and receivers.
<
 p>(4) 
Creates a receiver that reads from the given address.
(5) 
Creates a sender that sends to the given address.
(6) 
Reads the next message. The duration is optional, if omitted, will wait indefinitely for the next message.
(7) 
Acknowledges messages that have been read. To guarantee delivery, a message remains on the messaging broker until
  it is acknowledged by a client. session.acknowledge() acknowledges all unacknowledged messages for the given session—this allows acknowledgements to be batched, which is  more efficient than acknowledging messages individually.
(8) 
Closes the connection, all sessions managed by the connection, and all senders and receivers managed by each session.

Prev Up Next
2. A Simple Messagi ng Program in Python Home 4. Addresses
+

(1)

Selects the Qpid Messaging namespace. A project reference to the Org.Apache.Qpid.Messaging dll defines the Qpid Messaging namespace objects and methods.

(2)

Establishes the connection with the messaging broker.

(3)

Creates a session object on which messages will be sent and received.

(4)

Creates a receiver that receives messages from the given address.

(5)

Creates a sender that sends to the given address.

(6)

Receives the next message. The duration is optional, if omitted, will wait indefinitely for the next message.

(7)

Acknowledges receipt of all fetched messages on the + session. This informs the broker that the messages were + transfered and processed by the client successfully.

(8)

Closes the connection, all sessions managed by the connection, and all senders and receivers managed by each session.


< /table> Modified: qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s04.html URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s04.html?rev=967163&r1=967162&r2=967163&view=diff ============================================================================== --- qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s04.html (original) +++ qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s04.html Fri Jul 23 16:48:11 2010 @@ -1,7 +1,7 @@ -4. Addresses
Prev Up Next
2.2. A Simple Messaging Program in Python Home 2.4. Addresses
4. Addresses
Prev Chapter 2. Using the Qpid Messaging API Next

4. Addresses

An address is the name of a message - target or message source. In the programs we have just seen, we - used the address amq.topic (which is the name - of an exchange on an AMQP 0-10 messaging broker). +2.4. Addresses

2.4. Addresses
Prev Chapter 2. Using the Qpid Messaging API Next

2.4. Addresses

An address is the name of a message + target or message source. + + [1] The methods that create senders and receivers require an address. The details of sending to a particular target or @@ -12,22 +12,22 @@ Qpid Messaging API recognises two kinds of nodes, queues and topics - [1]. + [2]. A queue stores each message until it has been received and acknowledged, and only one receiver can receive a given message - [2]. + [3]. 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, - [3] + [4] queues map to AMQP queues, and topics map to AMQP exchanges. - [4] + [5]

In the rest of this tutorial, we present many examples using two programs that take an address as a command line parameter. spout sends messages to the @@ -39,13 +39,13 @@ configure behavior—use the -h option for documentation on these options. - [5] + [6] The examples in this tutorial also use the qpid-config utility to configure AMQP 0-10 queues and exchanges on a Qpid broker. -

Example 2.4. Queues

Create a queue with qpid-config, send a message using +

Example 2.4. Queues

Create a queue with qpid-config, send a message using spout, and read it using drain:

 $ qpid-config add queue hello-world
 $ ./spout hello-world
@@ -58,7 +58,7 @@ Message(properties={spout-id:c877e622-d5
 	drain one more time, no messages will be retrieved.
 $ ./drain hello-world
 $
-

Example 2.5. Topics

This example is similar to the previous example, but it +


Example 2.5. Topics

This example is similar to the previous example, but it uses a topic instead of a queue.

First, use qpid-config to remove the queue and create an exchange with the same name:

 $ qpid-config del queue hello-world
@@ -85,7 +85,7 @@ $ ./spout hello-word
 Message(properties={spout-id:7da2d27d-93e6-4803-8a61-536d87b8d93f:0}, content='')

You can run drain in several separate windows; each creates a subscription for the exchange, and - each receives all messages sent to the exchange.


4.1. Address Strings

So far, our examples have used address strings that + each receives all messages sent to the exchange.


2.4.1. Address Strings

So far, our examples have used address strings that contain only the name of a node. An address string can also contain a subject and @@ -95,9 +95,9 @@ options ::= { <key> : <value&g

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 - Section 4.4, “Address String Grammar”.

So far, the address strings in this tutorial have used - only addresses. The following sections show how to use - subjects and options.

4.2. Subjects

Every message has a property called + Section 2.4.4, “Address String Grammar”.

So far, the address strings in this tutorial have only + used simple names. The following sections show how to use + subjects and options.

2.4.2. Subjects

Every message has a property called subject, 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 @@ -110,16 +110,13 @@ options ::= { <key> : <value&g algorithm depends on the message source.

In AMQP 0-10, each exchange type has its own matching - algorithm, and queues do not provide filtering. This is - discussed in Section 13, “The AMQP 0-10 mapping”. + algorithm. This is discussed in + Section 2.16, “The AMQP 0-10 mapping”.

Note

Currently, a receiver bound to a queue ignores subjects, - receiving messages from the queue without filtering. - - In the future, if a receiver is bound to a queue, and its - address contains a subject, the subject will be used as a - selector to filter messages. -

Example 2.6. Using subjects

In this example we show how subjects affect message + receiving messages from the queue without filtering. Support + for subject filtering on queues will be implemented soon. +

Example 2.6. Using subjects

In this example we show how subjects affect message flow.

First, let's use qpid-config to create a topic exchange.

 $ qpid-config add exchange topic news-service

Now we use drain to receive messages from news-service that match the subject sports.

First Window:

@@ -155,7 +152,7 @@ Message(properties={qpid.subject:sports,
 	usa.news; if it is
 	europe.#, it matches messages with subjects
 	like europe.news or
-	europe.pseudo.news.
Example 2.7. Subjects with multi-word keys
This example uses drain and spout to demonstrate the
+	europe.pseudo.news.
Example 2.7. Subjects with multi-word keys
This example uses drain and spout to demonstrate the
 	    use of subjects with two-word keys.
Let's use drain with the subject
 	    *.news to listen for messages in which
 	    the second word of the key is
@@ -190,8 +187,8 @@ $ ./spout news-service/usa.faux.sports
 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='')
-

4.3. Address String Options

- The options in an address string contain additional +


2.4.3. Address String Options

+ The options in an address string can contain additional information for the senders or receivers created for it, including:

  • @@ -217,21 +214,20 @@ Message(properties={qpid.subject:usa.fau works in browse mode, leaving messages on the queue so other receivers can receive them.

  • - Extension points that rely on the functionality of specific node types. + Extension points providing more direct control over the underlying protocol.

    - For instance, the Qpid XML exchange can use XQuery to do - content-based routing for XML messages, or to query - message data using XQuery. Queries can be specified using - options. + For instance, the x-bindings property + allows greater control over the AMQP 0-10 binding process + when an address is resolved.

Let's use some examples to show how these different kinds of address string options affect the behavior of senders and receives. -

4.3.1. assert

+

2.4.3.1. assert

In this section, we use the assert option to ensure that the address resolves to a node of the required type. -

Example 2.8. Assertions on Nodes

Let's use qpid-config to create a +

Example 2.8. Assertions on Nodes

Let's use qpid-config to create a queue and a topic.

 $ qpid-config add queue my-queue
 $ qpid-config add exchange topic my-topic
@@ -256,15 +252,15 @@ $ ./drain 'my-topic; {assert: always, no
 Queue my-topic does not exist

Now let's use the create option to create the queue xoxox if it does not already - exist:

4.3.2. create

In previous examples, we created the queue before + exist:

2.4.3.2. create

In previous examples, we created the queue before listening for messages on it. Using create: always, the queue is automatically created if it - does not exist.

Example 2.9. Creating a Queue Automatically

First Window:

$ ./drain -t 30 "xoxox ; {create: always}"

Now we can send messages to this queue:

Second Window:

$ ./spout "xoxox ; {create: always}"

Returning to the first window, we see that drain has received this message:

Message(properties={spout-id:1a1a3842-1a8b-4f88-8940-b4096e615a7d:0}, content='')

4.3.3. browse

Some options specify message transfer semantics; for + does not exist.

Example 2.9. Creating a Queue Automatically

First Window:

$ ./drain -t 30 "xoxox ; {create: always}"

Now we can send messages to this queue:

Second Window:

$ ./spout "xoxox ; {create: always}"

Returning to the first window, we see that drain has received this message:

Message(properties={spout-id:1a1a3842-1a8b-4f88-8940-b4096e615a7d:0}, content='')

2.4.3.3. browse

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 browse option to receive messages without - removing them from a queue.

Example 2.10. Browsing a Queue

+ removing them from a queue.

Example 2.10. Browsing a Queue

Let's use the browse mode to receive messages without removing them from the queue. First we send three messages to the queue: @@ -282,13 +278,18 @@ $ ./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') -


4.3.4. x-bindings

x-bindings allows an address string - to specify properties AMQP 0-10 bindings. 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. These queries can be - specified in addresses using x-bindings

An instance of the XML Exchange must be added before it +


2.4.3.4. x-bindings

Greater control over the AMQP 0-10 binding process can + be achieved by including an x-bindings + 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.

An instance of the XML Exchange must be added before it can be used:

 $ qpid-config add exchange xml xml

When using the XML Exchange, a receiver provides an @@ -307,7 +308,7 @@ xml; {

When using longer queries with drain, it is often useful to place the query in a file, and use cat in the command line. We do this in the - following example.

Example 2.11. Using the XML Exchange

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:

+	following example.
Example 2.11. Using the XML Exchange
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:
 	  
 let $w := ./weather 
 return $w/station = 'Raleigh-Durham International Airport (KRDU)' 
@@ -336,7 +337,7 @@ content='<weather>
   <temperature_f>40</temperature_f>
   <dewpoint>35</dewpoint>
 </weather>') 
-

4.3.5. Address String Options - Reference

Table 2.1. Address String Options

optionvaluesemantics
+

2.4.3.5. Address String Options - Reference

Table 2.1. Address String Options

optionvaluesemantics
assert one of: always, never, sender or receiver @@ -384,8 +385,8 @@ content='<weather> 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 teh - queue once the client acknoweldges their receipt. + normal behaviour applies; messages are removed from the + queue once the client acknowledges their receipt.

Table 2.2. Node Properties

propertyvaluesemantics
type @@ -451,7 +452,9 @@ content='<weather> a message is not lost, but duplicates may be received. exactly-once guarantees that a message is not lost, and is delivered precisely - once. + once. Currently only unreliable + and at-least-once are supported. + [a]
durable @@ -486,7 +489,12 @@ content='<weather> independent of the create option. They are considered logically part of the linking process rather than of node creation. -

4.4. Address String Grammar

This section provides a formal grammar for address strings.

Tokens. The following regular expressions define the tokens used +

[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-most-once will be used and the application needs to + be able to deal with duplicates.


2.4.4. Address String Grammar

This section provides a formal grammar for address strings.

Tokens. The following regular expressions define the tokens used to parse address strings:

 LBRACE: \\{
 RBRACE: \\}
@@ -537,7 +545,10 @@ options := map

Create, Delete, and Assert Policies

The create, delete, and assert policies specify who should perfom the associated action:

  • always: the action is performed by any messaging client

  • sender: the action is only performed by a sender

  • receiver: the action is only performed by a receiver

  • never: the action is never performed (this is the default)

Node-Type

The node-type is one of:

  • topic: in the AMQP 0-10 mapping, a topic node defaults to the topic exchange, x-declare - may be used to specify other exchange types

  • queue: this is the default node-type


[1] The terms queue and + may be used to specify other exchange types

  • queue: this is the default node-type


    • [1] In the programs we have just seen, we used + amq.topic 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.

    [2] The terms queue and topic here were chosen to align with their meaning in JMS. These two addressing 'patterns', queue and topic, are sometimes refered as point-to-point @@ -545,11 +556,11 @@ options := map called a topic exchange. When the term topic occurs alone, it refers to a Messaging API topic, not the topic - exchange.

    [2] There are exceptions to this rule; for instance, + exchange.

    [3] There are exceptions to this rule; for instance, a receiver can use browse mode, which leaves messages on the queue for other receivers to - read.

    [3] The AMQP 0-10 implementation is the only one - that currently exists.

    [4] In AMQP 0-10, messages are sent to + read.

    [4] The AMQP 0-10 implementation is the only one + that currently exists.

    [5] 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 @@ -558,9 +569,9 @@ options := map 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.

    [5] Currently, the C++, Python, and .NET C# + the topic.

    [6] Currently, the C++, Python, and .NET C# implementations of drain and spout have slightly different options. This tutorial uses the C++ implementation. The options will be reconciled in the near - future.

    Prev Up Next
    3. A Simple Messaging Program in .NET C# Home 5. Logging
    + future.

    Prev Up Next
    2.3. A Simple Messaging Program in .NET C# Home 2.5. Sender Capacity and Replay
    Modified: qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s05.html URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s05.html?rev=967163&r1=967162&r2=967163&view=diff ============================================================================== --- qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s05.html (original) +++ qpid/site/docs/books/0.7/Programming-In-Apache-Qpid/html/ch02s05.html Fri Jul 23 16:48:11 2010 @@ -1,21 +1,25 @@ -5. Logging
    5. Logging
    Prev Chapter 2. Using the Qpid Messaging API Next

    5. Logging

    To simplify debugging, Qpid provides a logging facility - that prints out messaging events.

    5.1. Logging in C++

    The Qpidd broker and C++ clients can both use environment - variables to enable logging. Use QPID_LOG_ENABLE to set the - level of logging you are interested in (trace, debug, info, - notice, warning, error, or critical):

    -$ export QPID_LOG_ENABLE="warning+"
-

    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:

    -export QPID_LOG_TO_FILE="/tmp/myclient.out"
-

    5.2. Logging in Python

    - The Python client library supports logging using the standard Python logging module. The easiest way to do logging is to use the basicConfig(), which reports all warnings and errors: - 

    from logging import basicConfig
-basicConfig()
-

    - 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 DEBUG level: - 

    from qpid.log import enable, DEBUG
-enable("qpid.messaging.io", DEBUG)
-

    - For more information on Python logging, see http://docs.python.org/lib/node425.html. For more information on Qpid logging, use $ pydoc qpid.log. -

    Prev Up Next
    4. Addresses Home 6. Receiving Messages from Multiple Sources
    +2.5. Sender Capacity and Replay
    2.5. Sender Capacity and Replay
    Prev Chapter 2. Using the Qpid Messaging API Next

    2.5. Sender Capacity and Replay

    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.

    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.

    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 queue pending confirmation by the + server). When the unsettled count is zero, all messages on that + sender have been successfully sent.

    If the connection fails and is transparently reconnected + (see Section 2.10, “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 + Table 2.3, “Link Properties”). At present only + at-least-once guarantees are offered.

    Prev Up Next
    2.4. Addresses Home 2.6. Receiver Capacity (Prefetch)
    --------------------------------------------------------------------- Apache Qpid - AMQP Messaging Implementation Project: http://qpid.apache.org Use/Interact: mailto:commits-subscribe@qpid.apache.org