diff options
author | Rajith Muditha Attapattu <rajith@apache.org> | 2011-05-27 15:44:23 +0000 |
---|---|---|
committer | Rajith Muditha Attapattu <rajith@apache.org> | 2011-05-27 15:44:23 +0000 |
commit | 66765100f4257159622cefe57bed50125a5ad017 (patch) | |
tree | a88ee23bb194eb91f0ebb2d9b23ff423e3ea8e37 /qpid/cpp/examples/messaging/readme.txt | |
parent | 1aeaa7b16e5ce54f10c901d75c4d40f9f88b9db6 (diff) | |
parent | 88b98b2f4152ef59a671fad55a0d08338b6b78ca (diff) | |
download | qpid-python-66765100f4257159622cefe57bed50125a5ad017.tar.gz |
Creating a branch for experimenting with some ideas for JMS client.rajith_jms_client
git-svn-id: https://svn.apache.org/repos/asf/qpid/branches/rajith_jms_client@1128369 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'qpid/cpp/examples/messaging/readme.txt')
-rw-r--r-- | qpid/cpp/examples/messaging/readme.txt | 146 |
1 files changed, 146 insertions, 0 deletions
diff --git a/qpid/cpp/examples/messaging/readme.txt b/qpid/cpp/examples/messaging/readme.txt new file mode 100644 index 0000000000..ff145e0160 --- /dev/null +++ b/qpid/cpp/examples/messaging/readme.txt @@ -0,0 +1,146 @@ +The messaging API is intended as a high level abstraction for +messaging that avoids some of the protocol specific interactions +forced by the earlier API. This allows applications to concern +themselves with handling incoming messages and producing their own +messages and delegates knowledge of the protocol interactions required +to do so to the Qpid client library. + +To send or receive messages you first need to establish a connection +to a broker. You can then create one or more sessions on that +connection. Once you have a session you can create 'senders' or +'receivers'. These are objects through which you can send or receive +messages respectively. + +Senders and receivers are both created for a specified 'address'. An +address will often just be a simple name. As far as the API is +concerned, addresses are fairly opaque. This allows different types of +messaging pattern to be selected without affecting the code simply by +changing the address used, or configuring the broker to correctly +handle addresses of a certain name. + +At present there are two 'types' of address supported: queues and +topics. Messages sent to a queue are stored on the queue until there +is a subscriber who can receive them. Each message is in general +allocated to one subscriber (i.e. a competing consumer pattern). A +topic on the other hand will not store messages if there are no +subscriptions active and each message will be delivered to all +interested subscribers. + +In the current AMQP 0-10 implementation, queues are represented by +AMQP queues and topic are represented by AMQP exchanges to which +subscribers bind their own private subscription queue to receive +messages. + +The drain and spout examples in this directory are useful for +exploring the behaviour of the messaging API over AMQP 0-10 and +different uses of addresses. There is also some documentation around +the address syntax and currently supported options in the doxygen +reference material for the Address class itself. + +For example, to demonstrate classic message queueing behaviour: + +* create a queue e.g. by running: qpid-config add queue my-queue + +* use spout to send a message to that queue: ./spout --address my-queue + +* now use drain to receive that message: ./drain --address my-queue + +You can use the --content option to spout to specify text to put n the +message body. You can also alter the id used to unqieuly identify +each message using the --id option. + +To demonstrate the publish-subscribe pattern used for topics: + +* create an exchange e.g. by running: qpid-config add exchange topic my-topic + +* start up a subscriber using drain: ./drain -f --address my-topic + (the -f here causes the drain program to wait indefinitely for messages) + +* now send a message to the topic using spout: ./spout --address my-topic + +If you run spout before drain, the message will not be stored. If you +start multiple instances of drain, they will each receive the message. + +For a topic, you can select the messages you wish to receive by +'subject', eg. using the same exchange as above: + +* start a subscriber using drain for a specific subject: + ./drain -f --address my-topic/my-subject + +* now if you send a message with that subject you can see the + subscriber receives it: ./spout --address my-topic/my-subject + +* however were you to specify another subject for sent messages, those + would not be received, e.g: ./spout --address my-topic/another-subject + +In AMQP 0-10, the routing key is used to route messages for a given +subject. As my-topic is a topic exchange we can use the special +widlcard selection patterns when creating a subscriber: + +E.g. A subscriber reciving from address 'my-topic/#.dog' will receive +messages sent to 'my-topic/big.dog' and 'my-topic/blue.dog', but not +those sent to 'my-topic.blue-cat'. + +Though preconfiguring the valid addresses on a broker is a very common +pattern, it is still possible to have them created automatically +'on-demand'. This is done by specifying a create 'policy' for the address. + +* run: ./spout --address 'my-new-queue; {create: always}' +* then run: ./drain --address my-new-queue + +You can see that the queue was created by spout before it sent the +message to it, no explicit creation of the queue was needed. + +We can do the same for a topic, but there we need to specify the type +of address (as there is no existing entity from which to infer that +type and as we do not want the default type to be created, namely a +queue): + +* run: ./drain -f --address 'my-new-topic; {create: always, node:{type:topic}}' +* then run: ./spout --address my-new-queue + +The value to the create policy is one of always, sender, receiver or +never (which is the default). (Note: You can see the exchange created +using qpid-config exchanges, likewise to see the list of all queues +use qpid-config queues). + +In addition to a create policy there are assert and delete +policies. These have the same valid values as the create policy - +always, sender, receiver and never - indicating when they come in to +effect. + +An example using the headers exchange (uses default instance, though +this need not of course be the case. You could create another using +qpid-config or even auto-create one): + +* First start a subscriber, e.g.: + ./drain -f --address 'amq.match; {filter:{x-match:all, colour:blue}}' + +* Any message with a property name colour with value blue will be + received: + + ./spout --address amq.match --property colour=blue --content 'matched!' + +* But if the value of the colour property is something else, the + message will not be received: + ./spout --address amq.match --property colour=red --content 'not matched' + +An example using xquery based filtering with the xml exchange: + +* First start a subscriber with an xquery filter specified: + ./drain -f --address 'xml; {link:{x-bindings:[{arguments:{xquery:"declare variable $colour external; $colour = '\''red'\''"}}]}}' + +* Then test receipt of messages that match the xquery filter: + ./spout --address 'xml' --property colour=red --content 'matched!' + and + ./spout --address 'xml' --property colour=blue --content 'not matched' + +TODO: + +* auto-creating exchanges of different types + +* 'durable' and 'reliable' subscriptions + +* map content + +* client/server example: temp queues and reply-to |