You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by mg...@apache.org on 2013/04/18 15:47:41 UTC
svn commit: r1469325 - in /qpid/proton/trunk/docs/markdown/messenger:
addressing-and-routing.md index.md message-disposition.md
quick-start-linux.md sending-and-receiving.md
Author: mgoulish
Date: Thu Apr 18 13:47:40 2013
New Revision: 1469325
URL: http://svn.apache.org/r1469325
Log:
PROTON-260 : name change for all doc files, add title to index
Added:
qpid/proton/trunk/docs/markdown/messenger/addressing-and-routing.md
qpid/proton/trunk/docs/markdown/messenger/message-disposition.md
qpid/proton/trunk/docs/markdown/messenger/quick-start-linux.md
qpid/proton/trunk/docs/markdown/messenger/sending-and-receiving.md
Modified:
qpid/proton/trunk/docs/markdown/messenger/index.md
Added: qpid/proton/trunk/docs/markdown/messenger/addressing-and-routing.md
URL: http://svn.apache.org/viewvc/qpid/proton/trunk/docs/markdown/messenger/addressing-and-routing.md?rev=1469325&view=auto
==============================================================================
--- qpid/proton/trunk/docs/markdown/messenger/addressing-and-routing.md (added)
+++ qpid/proton/trunk/docs/markdown/messenger/addressing-and-routing.md Thu Apr 18 13:47:40 2013
@@ -0,0 +1,210 @@
+
+Messenger Addressing and Routing
+=================================================
+
+
+Addressing
+-------------------------
+
+An address has the following form:
+
+ [ amqp[s]:// ] [user[:password]@] domain [/[name]]
+
+Where domain can be one of:
+
+ host | host:port | ip | ip:port | name
+
+The following are valid examples of addresses:
+
+ * example.org
+ * example.org:1234
+ * amqp://example.org
+ * amqps://example.org
+ * example.org/incoming
+ * amqps://example.org/outgoing
+ * amqps://fred:trustno1@example.org
+ * 127.0.0.1:1234
+ * amqps://127.0.0.1:1234
+
+The "/name" part of the address, that optionally follows
+the domain, is not used by the Messenger library.
+For example, if a receiver subscribes to
+
+ amqp://~0.0.0.0:5678
+
+Then it will receive messages sent to
+
+ amqp://~0.0.0.0:5678
+as well as
+ amqp://~0.0.0.0:5678/foo
+
+
+Likewise, if the receiver subscribes to
+
+ amqp://~0.0.0.0:5678/foo
+
+it will receive messages addressed to
+
+ amqp://~0.0.0.0:5678/foo
+ amqp://~0.0.0.0:5678
+
+and
+
+ amqp://~0.0.0.0:5678/bar
+
+
+
+
+<br/>
+
+Routing
+------------------------------
+
+### Pattern Matching, Address Translation, and Message Routing ###
+
+The Messenger library provides message routing capability
+with an address translation table. Each entry in the table
+consists of a _pattern_ and a _translation_.
+
+You store a new route entry in the table with the call:
+
+ pn_messenger_route ( messenger, pattern, translation );
+
+
+The address of each outgoing message is compared to the
+table's patterns until the first matching pattern is found,
+or until all patterns have failed to match.
+
+If no pattern matches, then Messenger will send (or attempt
+to send) your message with the address as given.
+
+If a pattern does match your outgoing message's address, then
+Messenger will create a temporary address by transforming
+your message's address. Your message will be sent to the
+transformed address, but **(note!)** the address on your
+outgoing message will not be changed. The receiver will see
+the original, not the transformed address.
+
+
+<br/>
+
+### Two Translation Mechanisms ###
+
+
+Messenger uses two mechanisms to translate addresses.
+The first is simple string substitution.
+
+
+ pattern: COLOSSUS
+ translation: amqp://0.0.0.0:6666
+ input addr: COLOSSUS
+ result: amqp://0.0.0.0:6666
+
+
+The second mechanism is wildcard/variable substitution.
+A wildcard in the pattern matches all or part of your
+input address. The part of your input address that matched
+the wildcard is stored. The matched value is then inserted
+into your translated address in place of numbered variables:
+$1, $2, and so on, up to a maximum of 64.
+
+There are two wildcards: * and % .
+The rules for matching are:
+
+ * matches anything
+ % matches anything but a /
+ other characters match themselves
+ the whole input addr must be matched
+
+
+Examples of wildcard matching:
+
+ pattern: /%/%/%
+ translation: $1x$2x$3
+ input addr: /foo/bar/baz
+ result: fooxbarxbaz
+
+ pattern: *
+ translation: $1
+ inout addr: /foo/bar/baz
+ result: /foo/bar/baz
+
+ pattern: /*
+ translation: $1
+ input addr: /foo/bar/baz
+ result: foo/bar/baz
+
+ pattern: /*baz
+ translation: $1
+ input addr: /foo/bar/baz
+ result: foo/bar/
+
+ pattern: /%baz
+ translation: $1
+ input addr: /foo/bar/baz
+ result: FAIL
+
+ pattern: /%/baz
+ translation: $1
+ input addr: /foo/bar/baz
+ result: FAIL
+
+ pattern: /%/%/baz
+ translation: $1
+ input addr: /foo/bar/baz
+ result: foo
+
+ pattern: /*/baz
+ translation: $1
+ input addr: /foo/bar/baz
+ result: foo/bar
+
+
+Examples of route translation usage:
+
+ pattern: foo
+ translation: amqp://foo.com
+ explanation: Any message sent to "foo" will be routed to "amqp://foo.com"
+
+
+ pattern: bar/*
+ translation: amqp://bar.com/$1
+ explanation: Any message sent to bar/<path> will be routed to the corresponding path within the amqp://bar.com domain.
+
+
+ pattern: amqp:*
+ translation: amqps:$1
+ explanation: Route all messages over TLS.
+
+
+ pattern: amqp://foo.com/*
+ translation: amqp://user:password@foo.com/$1
+ explanation: Supply credentials for foo.com.
+
+
+ pattern: amqp://*
+ translation: amqp://user:password@$1
+ explanation: Supply credentials for all domains.
+
+
+ pattern: amqp://%/*
+ translation: amqp://user:password@proxy/$1/$2
+ explanation: Route all addresses through a single proxy while preserving the
+ original destination.
+
+
+ pattern: *
+ translation: amqp://user:password@broker/$1
+ explanation: Route any address through a single broker.
+
+
+
+<br/>
+
+### First Match Wins ###
+
+If you create multiple routing rules, each new rule is appended
+to your Messenger's list. At send-time, Messenger looks down the
+list, and the first rule that matches your outgoing message's
+address wins. Thus, when creating your routing rules, you should
+create them in order of most specific first, most general last.
Modified: qpid/proton/trunk/docs/markdown/messenger/index.md
URL: http://svn.apache.org/viewvc/qpid/proton/trunk/docs/markdown/messenger/index.md?rev=1469325&r1=1469324&r2=1469325&view=diff
==============================================================================
--- qpid/proton/trunk/docs/markdown/messenger/index.md (original)
+++ qpid/proton/trunk/docs/markdown/messenger/index.md Thu Apr 18 13:47:40 2013
@@ -1,8 +1,13 @@
+Proton Messenger Documentation
+==========================================
+
Proton Messenger is a high-level API that lets you build simple but powerful messaging systems.
-- Use the [Linux Quick Start](quick_start_linux.html) to download, build, and run your first Messenger example in two minutes.
+- Use the [Linux Quick Start](quick-start-linux.html) to download, build, and run your first Messenger example in two minutes.
+
+- Examples and explanations of Messenger's [Sending and Receiving](sending-and-receiving.html) capabilities.
-- Examples and explanations of Messenger's [Sending and Receiving](sending_and_receiving.html) capabilities.
+- Use [Message Disposition](message-disposition.html) functionality to create reliable messaging systems.
-- Use [Message Disposition](message_disposition.html) functionality to create reliable messaging systems.
+- Messenger's [Addressing and Routing](addressing-and-routing.html) capabilities allow you to separate application code from installation-specific configuration information.
Added: qpid/proton/trunk/docs/markdown/messenger/message-disposition.md
URL: http://svn.apache.org/viewvc/qpid/proton/trunk/docs/markdown/messenger/message-disposition.md?rev=1469325&view=auto
==============================================================================
--- qpid/proton/trunk/docs/markdown/messenger/message-disposition.md (added)
+++ qpid/proton/trunk/docs/markdown/messenger/message-disposition.md Thu Apr 18 13:47:40 2013
@@ -0,0 +1,158 @@
+Message Disposition
+===============================
+
+
+Messenger disposition operations allow a receiver to accept or
+reject specific messages, or ranges of messages. Senders can
+detect the disposition of their messages.
+
+
+Message States
+---------------------------
+
+Messages have one of four different states:
+ * `PN_STATUS_UNKNOWN`
+ * `PN_STATUS_PENDING`
+ * `PN_STATUS_ACCEPTED`
+ * `PN_STATUS_REJECTED`
+
+<br/>
+
+
+Windows and Trackers
+----------------------------
+
+<br/>
+
+
+### receiving ###
+
+To explicitly set or get message dispositions, your messenger
+must set a positive size for its incoming window:
+
+ pn_messenger_set_incoming_window ( messenger, N );
+
+You can implicity accept messages by simply letting enough
+new messages arrive. As older messages pass beyond the threshold
+of your incoming window size, they will be automatically
+accepted. Thus, if you want to automatically accept all
+messages as they arrive, you can set your incoming window
+size to 0.
+
+To exercise _explicit_ control over particular messages or ranges
+of messages, the receiver can use trackers. The call
+
+ pn_messenger_incoming_tracker ( messenger );
+
+will return a tracker for the message most recently returned
+by a call to
+
+ pn_messenger_get ( messenger, message );
+With a message that is being tracked, the messenger can accept
+(or reject) that individual message:
+
+ pn_messenger_accept ( messenger, tracker, 0 );
+ pn_messenger_reject ( messenger, tracker, 0 );
+
+Or it can accept (or reject) the tracked message as well as all older
+messages back to the limit of the incoming window:
+
+ pn_messenger_accept ( messenger, tracker, PN_CUMULATIVE );
+ pn_messenger_reject ( messenger, tracker, PN_CUMULATIVE );
+
+Once a message is accepted or rejected, its status can no longer
+be changed, even if you have a separate tracker associated with it.
+
+
+
+<br/>
+###when to accept###
+
+Although you _can_ accept messages implicitly by letting them fall
+off the edge of your incoming window, you _shouldn't_. Message
+disposition is an important form of communication to the sender.
+The best practice is to let the sender know your response, by
+explicit acceptance or rejection, as soon as you can. Implicitly
+accepting messages by allowing them to fall off the edge of the
+incoming window could delay your response to the sender for an
+unpredictable amount of time.
+
+The purpose of a nonzero window size is really to place
+a limit on how much state your Messenger needs to track.
+
+
+
+<br/>
+<br/>
+
+
+
+### sending ###
+
+A sender can learn how an individual message has been received
+if it has a positive outgoing window size:
+
+ pn_messenger_set_outgoing_window ( messenger, N );
+
+and if a tracker has been associated with that message in question.
+This call:
+
+ pn_messenger_outgoing_tracker ( messenger );
+
+will return a tracker for the message most recently given to:
+
+ pn_messenger_put ( messenger, message );
+
+To later find the status of the individual tracked message, you can call:
+
+ pn_messenger_status ( messenger, tracker );
+
+The returned value will be one of
+
+* `PN_STATUS_ACCEPTED`
+* `PN_STATUS_REJECTED` , or
+* `PN_STATUS_PENDING` - If the receiver has not disposed the message yet.
+
+
+If either the sender or the receiver simply declares the message (or range of messages) to
+be settled, with one of these calls:
+
+ pn_messenger_settle ( messenger, tracker, 0 );
+ pn_messenger_settle ( messenger, tracker, PN_CUMULATIVE );
+
+then the sender will see `PN_STATUS_UNKNOWN` as the status of any
+settled messages.
+
+<br/>
+
+### windows do not fill up ###
+When your incoming window fills up with messages it does not stop
+you from receiving more messages. If your incoming window has size *N*
+the only effect of receiving *N+1* messages is that the oldest message
+is automatically accepted (if you have not already accepted or rejected
+it).
+
+If your outgoing window fills, and new messages going out force the
+oldest ones to fall off the edge, your application will just lose
+the ability to track those oldest messages.
+<br/>
+
+_Note_
+If a message is rejected by the receiver, it does not mean that
+the message was malformed. Malformed messages cannot be sent.
+Even messages with no content are valid messages.
+Rejection by a receiver should be understood as the receiver
+saying "I don't want this." or possibly "I don't want this _yet_."
+depending on your application.
+The sender could decide to try sending the same message again later,
+or to send the message to another receiver, or to discard it.
+
+The AMQP 1.0 specification permits a distinction
+between _rejecting_ the message, and _releasing_ the message,
+but the Proton library does not (yet) expose the _releasing_
+disposition.
+
+
+
+
+
Added: qpid/proton/trunk/docs/markdown/messenger/quick-start-linux.md
URL: http://svn.apache.org/viewvc/qpid/proton/trunk/docs/markdown/messenger/quick-start-linux.md?rev=1469325&view=auto
==============================================================================
--- qpid/proton/trunk/docs/markdown/messenger/quick-start-linux.md (added)
+++ qpid/proton/trunk/docs/markdown/messenger/quick-start-linux.md Thu Apr 18 13:47:40 2013
@@ -0,0 +1,73 @@
+Linux Proton Messenger Quick Start
+==============================================
+
+
+On a Linux system, these instructions take you from
+zero to running your first example code. You will
+need root privileges for one of the commands.
+
+
+
+
+Prerequisite Packages
+---------------------------------
+
+For a minimum build, you will need packages installed on your
+box for :
+
+ subversion
+ gcc
+ cmake
+ libuuid-devel
+
+
+
+Quick Start Commands
+---------------------------
+
+ svn co http://svn.apache.org/repos/asf/qpid/proton/trunk proton
+ cd ./proton
+ mkdir ./build
+ cd ./build
+ cmake ..
+ make all
+ # Become root and go to your build dir.
+ make install
+ # Stop being root.
+ # Now let's see if it works.
+ cd ./proton-c/examples/messenger/c
+ ./recv &
+ ./send
+ # You're done ! ( Kill that recv process. )
+ # The output you should see:
+
+ Address: amqp://0.0.0.0
+ Subject: (no subject)
+ Content: "Hello World!"
+
+
+
+
+
+Notes
+----------------------------
+
+1. If you will be editing and checking in code from this tree,
+ replace the "svn co" line with this:
+
+ svn co https://svn.apache.org/repos/asf/qpid/proton/trunk
+
+ You must check out through https, or you will not be able to
+ check in code changes from your tree.
+
+
+2. The recv application in the example defaults to the same port
+ as the qpid demon. If you happen to have that demon running,
+ and using the default port, the recv app above will fail.
+
+
+3. If you don't have root privileges, you can still do the
+ "make install" step by setting a non-standard prefix, thus:
+ cmake -DCMAKE_INSTALL_PREFIX=/my/path ..
+
+
Added: qpid/proton/trunk/docs/markdown/messenger/sending-and-receiving.md
URL: http://svn.apache.org/viewvc/qpid/proton/trunk/docs/markdown/messenger/sending-and-receiving.md?rev=1469325&view=auto
==============================================================================
--- qpid/proton/trunk/docs/markdown/messenger/sending-and-receiving.md (added)
+++ qpid/proton/trunk/docs/markdown/messenger/sending-and-receiving.md Thu Apr 18 13:47:40 2013
@@ -0,0 +1,144 @@
+Sending and Receiving Messages
+=======================================================
+
+The Proton Messenger API provides a mixture of synchronous
+and asynchronous operations to give you flexibility in
+deciding when you application should block waiting for I/O,
+and when it should not.
+
+
+When sending messages, you can:
+
+* send a message immediately,
+* enqueue a message to be sent later,
+* block until all enqueued messages are sent,
+* send enqueued messages until a timeout occurs, or
+* send all messages that can be sent without blocking.
+
+When receiving messages, you can:
+
+* receive messages that can be received without blocking,
+* block until at least one message is received,
+* receive no more than a fixed number of messages.
+
+
+
+Functions
+------------------------------
+
+* `pn_messenger_put ( messenger )`
+
+ Stage message for later transmission, and possibly
+ transmit any messages currently staged that are not
+ blocked.
+ This function will not block.
+
+
+
+* `pn_messenger_send ( messenger )`
+
+ If messenger timeout is negative (initial default ),
+ block until all staged messages have been sent.
+
+ If messenger timeout is 0, send all messages that
+ can be sent without blocking.
+
+ If messenger timeout is positive, send all messages
+ that can be sent until timeout expires.
+
+ _note: If there are any messages that can be received
+ when `pn_messenger_send()` is called, they will
+ be received._
+
+
+
+* `pn_messenger_get ( messenger, msg )`
+
+ Dequeue the head of the incoming message queue to
+ your application.
+ This call does not block.
+
+
+
+* `pn_messenger_recv ( messenger )`
+
+ If messenger timeout is negative ( initial default ),
+ block until at least one message is received.
+
+ If timeout is 0, receive whatever messages are available,
+ but do not block.
+
+ If timeout is positive, receive available messages until
+ timeout expires.
+
+ _note: If there are any unblocked outgoing messages,
+ they will be sent during this call._
+
+
+
+
+
+Examples
+------------------------------
+
+* send a message immediately
+
+ pn_messenger_put ( messenger, msg );
+ pn_messenger_send ( messenger );
+
+
+
+* enqueue a message to be sent later
+
+ pn_messenger_put ( messenger, msg );
+
+ _note:
+ The message will be sent whenever it is not blocked and
+ the Messenger code has other I/O work to be done._
+
+
+
+* block until all enqueued messages are sent
+
+ pn_messenger_set_timeout ( messenger, -1 );
+ pn_messenger_send ( messenger );
+
+ _note:
+ A negative timeout means 'forever'. That is the initial
+ default for a messenger._
+
+
+
+* send enqueued messages until a timeout occurs
+
+ pn_messenger_set_timeout ( messenger, 100 ); /* 100 msec */
+ pn_messenger_send ( messenger );
+
+
+
+* send all messages that can be sent without blocking
+
+ pn_messenger_set_timeout ( messenger, 0 );
+ pn_messenger_send ( messenger );
+
+
+
+* receive messages that can be received without blocking
+
+ pn_messenger_set_timeout ( messenger, 0 );
+ pn_messenger_recv ( messenger, -1 );
+
+
+* block until at least one message is received
+
+ pn_messenger_set_timeout ( messenger, -1 );
+ pn_messenger_recv ( messenger, -1 );
+
+ _note: -1 is initial messenger default._
+
+
+
+* receive no more than a fixed number of messages
+
+ pn_messenger_recv ( messenger, 10 );
+
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org