From 7b16c98f46201da3bedb2732f0f4ea223e1a7cd7 Mon Sep 17 00:00:00 2001 From: Jonathan Robie Date: Mon, 3 May 2010 19:46:00 +0000 Subject: Significant improvement to XML Exchange section, completed Java JMS tables. git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk/qpid@940587 13f79535-47bb-0310-9956-ffa450edef68 --- doc/book/src/High-Level-API.xml | 164 ++++++++++++++++++++++++++++++++-------- 1 file changed, 132 insertions(+), 32 deletions(-) diff --git a/doc/book/src/High-Level-API.xml b/doc/book/src/High-Level-API.xml index f658d73050..c0256a4bb2 100644 --- a/doc/book/src/High-Level-API.xml +++ b/doc/book/src/High-Level-API.xml @@ -914,6 +914,7 @@ Message(properties={spout-id:ea75d64d-ea37-47f9-96a9-d38e01c97925:0}, content='t 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: + - In conjunction with the create option, each of these @@ -1371,6 +1371,7 @@ std::cout << request.getContent() << " -> " << response.getContent() << std::end -->
XML Exchange + 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. An instance of the XML Exchange must be added before it can be used: @@ -1379,52 +1380,115 @@ std::cout << request.getContent() << " -> " << response.getContent() << std::end $ qpid-config add exchange xml xml + When using the XML exchange, a sender's address string must provide a subject, e.g. xml/weather. - Here is a Python program that shows how to use the XML Exchange: + If a receiver that is using the XML exchange also provides a subject, it receives messages if the subject exactly matches a message's subject. - - This program does not work. Not sure if the bug is in my code or the broker. - + + When using the XML Exchange, a receiver normally 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: + + + + Note that each x-binding is created in addition to any other bindings that may exist, and each x-binding must include the exchange name, the key, and the xquery. If you specify the subject in the address string (e.g. xml/weather; link ...), it creates a binding that is used in addition to the x-bindings; the binding created for the subject matches any message whose subject is weather, the binding created for the x-binding matches any message that satisfies the query, i.e. any message with a root element named weather. + + + + The XML Exchange can also be used to query message properties by declaring an external variable with the same name as each property that is to be queried. The following XQuery queries the control property, as well as the content of the message: + + + + If the XQuery addresses message content, and the message is not well-formed XML, the message will not be received. If the XQuery does not query message content, the message need not contain XML. - Using the XML Exchange in Python - Using the XML Exchange with drain + + The following shows the arguments used with drain to retrieve messages whose root element is named weather: -broker = "localhost:5672" -query = """ + + + + + Using the XML Exchange with C++ + + In C++, it is convenient to place an XQuery in a string, and use a stringstream to add the query to the template for an address string that specifies an x-binding. + + 50" + " and $w/temperature_f - $w/dewpoint > 5" + " and $w/wind_speed_mph > 7" + " and $w/wind_speed_mph < 20"; + +stringstream address; + +address << "xml; {" + " link: { " + " x-bindings: [{ exchange: xml, key: weather, arguments: { xquery:\"" + << query + << "\"} }] " + " } " + "}"; + + +Receiver receiver = session.createReceiver(address.str()); +Message response = receiver.fetch(); +session.acknowledge(); +std::cout << response.getContent() << std::endl; + + ]]> + + + + + Using the XML Exchange with Python + + In Python, it is often convenient to place the query in + a separate string, and use the repr() value of the query + string in an address template string. + + 50 and $w/temperature_f - $w/dewpoint > 5 and $w/wind_speed_mph > 7 - and $w/wind_speed_mph < 20 -""" - -address = "subscription; {create: always, delete:always, link: { x-bindings: [{ exchange: xml, queue: subscription, key: xml, arguments: { xquery: %r} }] } }" % query + and $w/wind_speed_mph < 20 """ -connection = Connection(broker) - -try: - connection.open() - session = connection.session() + address = """ + xml; { + link: { + x-bindings: [{ exchange: xml, key: weather, arguments: { xquery: %r} }] + } + } + """ % query - sender = session.sender("xml") receiver = session.receiver(address) - sender.send(Message("Raleigh-Durham International Airport (KRDU)167035")); +# Retrieve matching message from the receiver and print it message = receiver.fetch(timeout=1) print message.content session.acknowledge() - -except MessagingError,m: - print m -finally: - connection.close() - ]]> + ]]> +
@@ -1993,13 +2057,47 @@ destination.topicExchange = amq.topic - sync_persistence + sync_publish + + + {'persistent' | 'all'} + + + A sync command is sent after every persistent message to guarantee that it has been received; if the value is 'persistent', this is done only for persistent messages. + + + + + sync_ack + + + Boolean + + + A sync command is sent after every acknowledgement to guarantee that it has been received. + + + + + use_legacy_map_msg_format + + + Boolean + + + If you are using JMS Map messages and deploying a new client with any JMS client older than 0.7 release, you must set this to true to ensure the older clients can understand the map message encoding. + + + + + failover - false + {'roundrobin' | 'failover_exchange'} - When true, a sync command is sent after every persistent message to guarantee that it has been received. + If roundrobin is selected it will try each broker given in the broker list. + If failover_exchange is selected it connects to the initial broker given in the broker URL and will receive membership updates via the failover exchange. @@ -2091,8 +2189,10 @@ amqp://guest:guest@test/test?sync_ack='true' sasl_encryption + Boolean + If sasl_encryption='true', the JMS client attempts to negotiate a security layer with the broker using GSSAPI to encrypt the connection. Note that for this to happen, GSSAPI must be selected as the sasl_mech. @@ -2103,8 +2203,7 @@ amqp://guest:guest@test/test?sync_ack='true' Boolean - If ssl='true', only encrypted - connections are accepted. + If ssl='true', the JMS client will encrypt the connection using SSL. @@ -2209,6 +2308,7 @@ amqp://guest:guest@test/test?sync_ack='true' + If multiple certificates are present in the keystore, the alias will be used to extract the correct certificate. -- cgit v1.2.1