From 6067a44801a0fbb807c527beff6dfd57ce063698 Mon Sep 17 00:00:00 2001 From: Jonathan Robie Date: Tue, 18 May 2010 11:27:07 +0000 Subject: XML exchange is discussed under x-bindings now, extended reliability with failover, reliability options. Still working on security ... git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk/qpid@945591 13f79535-47bb-0310-9956-ffa450edef68 --- doc/book/src/Programming-In-Apache-Qpid.xml | 663 ++++++++++++++++------------ 1 file changed, 378 insertions(+), 285 deletions(-) (limited to 'doc/book/src/Programming-In-Apache-Qpid.xml') diff --git a/doc/book/src/Programming-In-Apache-Qpid.xml b/doc/book/src/Programming-In-Apache-Qpid.xml index 5af14139f6..8971a7befc 100644 --- a/doc/book/src/Programming-In-Apache-Qpid.xml +++ b/doc/book/src/Programming-In-Apache-Qpid.xml @@ -681,6 +681,17 @@ Message(properties={qpid.subject:usa.faux.news, spout-id:6029430a-cfcb-4700-8e9b on the queue so other receivers can receive them. + + + Extension points that rely on the functionality of specific node types. + + + 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. + + @@ -690,10 +701,11 @@ Message(properties={qpid.subject:usa.faux.news, spout-id:6029430a-cfcb-4700-8e9b receives. - +
+ assert - First, let's use the assert option to - ensure that the address resolves to a node of the required + In this section, we use the assert option + to ensure that the address resolves to a node of the required type. @@ -743,16 +755,24 @@ Queue my-topic does not exist create the queue xoxox if it does not already exist: - - Creating a Queue Automatically +
- First Window: - $ ./drain -t 30 "xoxox ; {create: always}" +
+ 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. Now we can send messages to this queue: + does not exist. + + + 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}" @@ -762,16 +782,16 @@ Queue my-topic does not exist Message(properties={spout-id:1a1a3842-1a8b-4f88-8940-b4096e615a7d:0}, content='') - +
- Other 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. +
+ 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. Browsing a Queue @@ -802,11 +822,121 @@ Message(properties={spout-id:ab9e7c31-19b0-4455-8976-34abe83edc5f:0}, content='t Message(properties={spout-id:ea75d64d-ea37-47f9-96a9-d38e01c97925:0}, content='three') +
+ +
+ 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 + can be used: + + +$ qpid-config add exchange xml xml + + + 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 .), then it + is applied to the content of the message, which must be + well-formed XML. For instance, ./weather is + a valid XQuery, which matches any message in which the root + element is named weather. Here is an + address string that contains this query: + + + + 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. + + + 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: + + + 50 + and $w/temperature_f - $w/dewpoint > 5 + and $w/wind_speed_mph > 7 + and $w/wind_speed_mph < 20 ]]> + + + We can specify this query in an x-binding to listen to messages that meet the criteria specified by the query: + + First Window: + + +$ ./drain -f "xml; {link:{x-bindings:[{key:'weather', +arguments:{xquery:\"$(cat rdu.xquery )\"}}]}}" + + + In another window, let's create an XML message that meets the criteria in the query, and place it in the file rdu.xml: + + + + Raleigh-Durham International Airport (KRDU) + 16 + 70 + 35 + + ]]> + + Now let's use spout to send this message to the XML exchange: + + Second Window: + +spout --content "$(cat rdu.xml)" xml/weather + + + Returning to the first window, we see that the message has been received: + + + Raleigh-Durham International Airport (KRDU) + 16 + 40 + 35 +') ]]> + + +
+ + +
+ Address String Options - Reference + Address String Options @@ -1018,7 +1148,17 @@ Message(properties={spout-id:ea75d64d-ea37-47f9-96a9-d38e01c97925:0}, content='t one of: unreliable, at-least-once, at-most-once, exactly-once - + + Reliability indicates the level of reliability that + the sender or receiver. unreliable + and at-most-once are currently + treated as synonyms, and allow messages to be lost if + a broker crashes or the connection to a broker is + lost. at-least-once guarantees that + a message is not lost, but duplicates may be + received. exactly-once guarantees + that a message is not lost, and is delivered precisely + once. @@ -1080,7 +1220,7 @@ Message(properties={spout-id:ea75d64d-ea37-47f9-96a9-d38e01c97925:0}, content='t
- +
Address String Grammar @@ -1229,127 +1369,6 @@ enable("qpid.messaging.io", DEBUG)
-
- Reconnect and Failover - Connections in the Qpid Messaging API support automatic - reconnect if a connection is lost. This is done using connection - options. The following example shows how to use connection options in C++ and Python. - - - Specifying Connection Options in C++ and Python - - In C++, these options are set using Connection::setOption(): - - - - In Python, these options are set using named arguments in - the Connection constructor: - - - - See the reference documentation for details on how to set - these on connections for each language. - - - The following table lists the connection options that can - be used. - - - Connection Options - - - - - - - option - value - semantics - - - - - - reconnect - - - True, False - - - Transparently reconnect if the connection is lost. - - - - - reconnect_timeout - - - N - - - Total number of seconds to continue reconnection attempts before giving up and raising an exception. - - - - - reconnect_limit - - - N - - - Maximum number of reconnection attempts before giving up and raising an exception. - - - - - reconnect_interval_min - - - N - - - 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 reconnect_interval_min; if that attempt fails, the reconnect interval increases exponentially until a reconnection attempt succeeds or reconnect_interval_max is reached. - - - - - reconnect_interval_max - - - N - - - Maximum reconnect interval. - - - - - reconnect_interval - - - N - - - Sets both reconnection_interval_min and reconnection_interval_max to the same value. - - - - -
-
-
Receiving Messages from Multiple Sources @@ -1705,7 +1724,127 @@ sender.setCapacity(100);
Reliability + The Qpid Messaging API supports automatic reconnect, guaranteed delivery via persistent messages, reliability options in senders and receivers, and cluster failover. This section shows how programs can take advantage of these features. +
+ Reconnect + Connections in the Qpid Messaging API support automatic + reconnect if a connection is lost. This is done using connection + options. The following example shows how to use connection options in C++ and Python. + + + Specifying Connection Options in C++ and Python + In C++, these options are set using Connection::setOption(): + + + + In Python, these options are set using named arguments in + the Connection constructor: + + + + See the reference documentation for details on how to set + these on connections for each language. + + + The following table lists the connection options that can + be used. + + + Connection Options + + + + + + + option + value + semantics + + + + + + reconnect + + + True, False + + + Transparently reconnect if the connection is lost. + + + + + reconnect_timeout + + + N + + + Total number of seconds to continue reconnection attempts before giving up and raising an exception. + + + + + reconnect_limit + + + N + + + Maximum number of reconnection attempts before giving up and raising an exception. + + + + + reconnect_interval_min + + + N + + + 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 reconnect_interval_min; if that attempt fails, the reconnect interval increases exponentially until a reconnection attempt succeeds or reconnect_interval_max is reached. + + + + + reconnect_interval_max + + + N + + + Maximum reconnect interval. + + + + + reconnect_interval + + + N + + + Sets both reconnection_interval_min and reconnection_interval_max to the same value. + + + + +
+
Guaranteed Delivery @@ -1735,14 +1874,50 @@ sender.send(Message("Hello world!")); Python: --> -
+ +
+ Reliability Options in Senders and Receivers + + When creating a sender or a receiver, you can specify a reliability option in the address string. For instance, the following specifies at-least-once as the reliability mode for a sender: + + +Sender = session.createSender("topic;{create:always,link:{reliability:at-least-once}}"); + + + The modes unreliable, at-most-once, at-least-once, and exactly-once are supported. These modes govern the reliability of the connection between the client and the messaging broker. + + The modes unreliable and at-most-once are currently synonyms. In a receiver, this mode means that messages received on an auto-delete subscription queue may be lost in the event of a broker failure. In a sender, this mode means that the sender can consider a message sent as soon as it is written to the wire, and need not wait for broker acknowledgement before considering the message sent. + + The mode at-most-once ensures that messages are not lost, but duplicates of a message may occur. In a receiver, this mode ensures that messages are not lost in event of a broker failure. In a sender, this means that messages are kept in a replay buffer after they have been sent, and removed from this buffer only after the broker acknowledges receipt; if a broker failure occurs, messages in the replay buffer are resent upon reconnection. The mode exactly-once is similar to at-most-once, but eliminates duplicate messages. + + + +
+ +
+ Cluster Failover + + The messaging broker can be run in clustering mode, which provides high reliability at-least-once messaging. If one broker in a cluster fails, clients can choose another broker in the cluster and continue their work. + + In C++, the FailoverUpdates class keeps track of the brokers in a cluster, so a reconnect can select another broker in the cluster to connect to: + + + Cluster Failover in C++ + +... +Connection connection(broker); +connection.setOption("reconnect", true); +try { + connection.open(); + std::auto_ptr updates(new FailoverUpdates(connection));]]> + + +
+