| <!DOCTYPE html> |
| <html> |
| <head> |
| <meta charset="UTF-8"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <title> |
| File: README |
| |
| — Qpid Proton Ruby API |
| |
| </title> |
| |
| <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" /> |
| |
| <link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" /> |
| |
| <script type="text/javascript" charset="utf-8"> |
| pathId = "README"; |
| relpath = ''; |
| </script> |
| |
| |
| <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script> |
| |
| <script type="text/javascript" charset="utf-8" src="js/app.js"></script> |
| |
| |
| </head> |
| <body> |
| <div class="nav_wrap"> |
| <iframe id="nav" src="class_list.html?1"></iframe> |
| <div id="resizer"></div> |
| </div> |
| |
| <div id="main" tabindex="-1"> |
| <div id="header"> |
| <div id="menu"> |
| |
| <a href="_index.html">Index</a> » |
| <span class="title">File: README</span> |
| |
| </div> |
| |
| <div id="search"> |
| |
| <a class="full_list_link" id="class_list_link" |
| href="class_list.html"> |
| |
| <svg width="24" height="24"> |
| <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect> |
| <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect> |
| <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect> |
| </svg> |
| </a> |
| |
| </div> |
| <div class="clear"></div> |
| </div> |
| |
| <div id="content"><div id='filecontents'> |
| <h1 id="label-Qpid+Proton+AMQP+Library">Qpid Proton AMQP Library</h1> |
| |
| <p>This is a library for sending and receiving AMQP messages. It can be used |
| to build clients and servers.</p> |
| |
| <h2 id="label-Installing">Installing</h2> |
| |
| <p>You can install the latest published Gem with</p> |
| |
| <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='id identifier rubyid_install'>install</span> <span class='id identifier rubyid_qpid_proton'>qpid_proton</span> |
| </code></pre> |
| |
| <p><strong>NOTE:</strong> before installing the Gem, you must install the |
| proton-C library.</p> |
| |
| <p>The proton-C library can be installed by the package manager on many |
| platforms,</p> |
| |
| <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_e'>e</span><span class='period'>.</span><span class='id identifier rubyid_g'>g</span><span class='period'>.</span> <span class='id identifier rubyid_yum'>yum</span> <span class='id identifier rubyid_install'>install</span> <span class='id identifier rubyid_qpid'>qpid</span><span class='op'>-</span><span class='id identifier rubyid_proton'>proton</span><span class='op'>-</span><span class='id identifier rubyid_c'>c</span> <span class='comment'># Fedora < 25, RHEL < 7 dnf install |
| </span><span class='id identifier rubyid_qpid'>qpid</span><span class='op'>-</span><span class='id identifier rubyid_proton'>proton</span><span class='op'>-</span><span class='id identifier rubyid_c'>c</span> <span class='comment'># Fedora >= 25, RHEL >= 7 |
| </span></code></pre> |
| |
| <p>You can also download a source release or the latest development code from |
| <a href="http://qpid.apache.org/proton">qpid.apache.org/proton</a>. To |
| build from source:</p> |
| |
| <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_cmake'>cmake</span> <span class='op'>-</span><span class='const'>DBUILD_BINDINGS</span><span class='op'>=</span><span class='id identifier rubyid_ruby'>ruby</span> <span class='op'>&&</span> <span class='id identifier rubyid_make'>make</span> |
| </code></pre> |
| |
| <p>This produces a Gem file at:</p> |
| |
| <pre class="code ruby"><code class="ruby"><span class='const'>BUILD_DIR</span><span class='op'>/</span><span class='id identifier rubyid_ruby'>ruby</span><span class='op'>/</span><span class='id identifier rubyid_qpid_proton'>qpid_proton</span><span class='op'>-</span><span class='const'>VERSION</span><span class='period'>.</span><span class='id identifier rubyid_gem'>gem</span> |
| </code></pre> |
| |
| <p>You can install the gem with <tt>gem install</tt></p> |
| |
| <h2 id="label-Overview">Overview</h2> |
| |
| <p><span class='object_link'><a href="Qpid/Proton/Message.html" title="Qpid::Proton::Message (class)">Qpid::Proton::Message</a></span> represents a message that can be sent or received. |
| A message body can be a string or byte sequence encoded any way you choose. |
| However, AMQP also provides standard, interoperable encodings for basic |
| data types like <span class='object_link'>Hash</span> and <span class='object_link'>Array</span>. The equivalent AMQP encodings can be |
| understood as maps or sequences in any programming langauge with an AMQP |
| library.</p> |
| |
| <p><span class='object_link'><a href="Qpid/Proton/Link.html" title="Qpid::Proton::Link (class)">Qpid::Proton::Link</a></span> allows messages to be transferred to or from a remote |
| AMQP process. The <span class='object_link'><a href="Qpid/Proton/Sender.html" title="Qpid::Proton::Sender (class)">Qpid::Proton::Sender</a></span> subclass sends messages, the |
| <span class='object_link'><a href="Qpid/Proton/Receiver.html" title="Qpid::Proton::Receiver (class)">Qpid::Proton::Receiver</a></span> subclass receives them. Links have a source and |
| target address, as explained below.</p> |
| |
| <p>Links are grouped in a <span class='object_link'><a href="Qpid/Proton/Session.html" title="Qpid::Proton::Session (class)">Qpid::Proton::Session</a></span>. Messages in the same |
| session are sent sequentially, while those on different sessions can be |
| interleaved. A large message being sent on one session does not block |
| messages being sent on another session.</p> |
| |
| <p>Sessions belong to a <span class='object_link'><a href="Qpid/Proton/Connection.html" title="Qpid::Proton::Connection (class)">Qpid::Proton::Connection</a></span>. If you don't need |
| multiple sessions, a connection will create links directly using a default |
| session.</p> |
| |
| <p>A <span class='object_link'><a href="Qpid/Proton/Transfer.html" title="Qpid::Proton::Transfer (class)">Qpid::Proton::Transfer</a></span> represents the transfer of a message, the |
| <span class='object_link'><a href="Qpid/Proton/Delivery.html" title="Qpid::Proton::Delivery (class)">Qpid::Proton::Delivery</a></span> subclass allows a receiver to accept or reject an |
| incoming message. The <span class='object_link'><a href="Qpid/Proton/Tracker.html" title="Qpid::Proton::Tracker (class)">Qpid::Proton::Tracker</a></span> subclass allows a sender to |
| track the status of a sent message and find out if it was accepted or |
| rejected.</p> |
| |
| <p>A transfer is <em>settled</em> when both ends are done with it. Different |
| settlement methods give different levels of reliability: at-most-once, |
| at-least-once, and exactly-once. See below.</p> |
| |
| <h2 id="label-Anatomy+of+a+Proton+application">Anatomy of a Proton application</h2> |
| |
| <p><span class='object_link'><a href="Qpid/Proton/Container.html" title="Qpid::Proton::Container (class)">Qpid::Proton::Container</a></span> is the top-level object in a Proton application. |
| A client uses <span class='object_link'><a href="Qpid/Proton/Container.html#connect-instance_method" title="Qpid::Proton::Container#connect (method)">Qpid::Proton::Container#connect</a></span> to establish connections. A |
| server uses <span class='object_link'><a href="Qpid/Proton/Container.html#listen-instance_method" title="Qpid::Proton::Container#listen (method)">Qpid::Proton::Container#listen</a></span> to accept connections.</p> |
| |
| <p>Proton is an event-driven library. You implement one or more |
| <em>handlers</em> which subclass <span class='object_link'><a href="Qpid/Proton/MessagingHandler.html" title="Qpid::Proton::MessagingHandler (class)">MessagingHandler</a></span> and override functions to handle AMQP events, such as |
| <span class='object_link'>#on_message</span>. Each connection is |
| associated with a handler for its events. <span class='object_link'><a href="Qpid/Proton/Container.html#run-instance_method" title="Qpid::Proton::Container#run (method)">Qpid::Proton::Container#run</a></span> |
| polls all connections and listeners and calls the event handling functions |
| on your handlers.</p> |
| |
| <p>A multi-threaded application can call <span class='object_link'><a href="Qpid/Proton/Container.html#run-instance_method" title="Qpid::Proton::Container#run (method)">Qpid::Proton::Container#run</a></span> in more |
| than one thread, the container will use all the |
| <span class='object_link'><a href="Qpid/Proton/Container.html#run-instance_method" title="Qpid::Proton::Container#run (method)">#run</a></span> threads as a thread pool to dispatch |
| events.</p> |
| |
| <h2 id="label-Sources+and+targets">Sources and targets</h2> |
| |
| <p>Every link has two addresses, <em>source</em> and <em>target</em>. The most |
| common pattern for using these addresses is as follows:</p> |
| |
| <p>When a client creates a <span class='object_link'><a href="Qpid/Proton/Receiver.html" title="Qpid::Proton::Receiver (class)">Receiver</a></span> link, it sets the |
| <em>source</em> address. This means “I want to receive messages from this |
| source”. This is often referred to as “subscribing” to the source. When a |
| client creates a <span class='object_link'><a href="Qpid/Proton/Sender.html" title="Qpid::Proton::Sender (class)">Sender</a></span> link, it sets the |
| <em>target</em> address. This means “I want to send to this target”.</p> |
| |
| <p>In the case of a broker, the source or target usually refers to a queue or |
| topic. In general they can refer to any AMQP-capable node.</p> |
| |
| <p>In the request-response pattern, a request message carries a reply-to |
| address for the response message. This can be any AMQP address, but it is |
| often useful to create a temporary address for the response message. The |
| client creates a receiver with no source address and the dynamic flag set. |
| The server generates a unique source address for the receiver, which is |
| discarded when the link closes. The client uses this source address as the |
| reply-to when it sends the request, so the response is delivered to the |
| client's receiver.</p> |
| |
| <p>The server_direct.cpp example shows how to implement a request-response |
| server.</p> |
| |
| <h2 id="label-Settling+a+Message+Transfer">Settling a Message Transfer</h2> |
| |
| <p>A message transfer is <em>settled</em> at one end of a link when that end |
| of the link has finished with the message and forgotten it.</p> |
| |
| <p><em>Pre-settled</em> messages are settled by the sender before sending. |
| This gives _at most once_ reliability(also known as _best effort_, |
| <em>unreliable</em> or _fire and forget_) since the sender never knows for |
| sure if the message arrived. If the connection is lost before the message |
| is received by the receiver, the message will not be delivered.</p> |
| |
| <p>If the sender does not pre-settle a message, then the receiver settles it |
| once it has been processed. The sender is informed of the settlement via |
| the <span class='object_link'><a href="Qpid/Proton/Tracker.html" title="Qpid::Proton::Tracker (class)">Tracker</a></span>. If the connection is lost before the |
| sender has received notice of settlement, the delivery is considered |
| in-doubt and the sender can re-send it. This ensures it eventually gets |
| delivered (provided the connection and link can be reestablished) but it is |
| possible for multiple copies of the same message are delivered, so the |
| receiver must be aware of that. This is known as <em>at_least_once</em> |
| reliability.</p> |
| |
| <h2 id="label-Multi-threaded+applications">Multi-threaded applications</h2> |
| |
| <p><span class='object_link'><a href="Qpid/Proton/Container.html#run-instance_method" title="Qpid::Proton::Container#run (method)">Qpid::Proton::Container#run</a></span> can be called by multiple threads |
| concurrently, giving the container a thread-pool to execute handler methods |
| in parallel.</p> |
| |
| <p>Instances of <span class='object_link'><a href="Qpid/Proton/Connection.html" title="Qpid::Proton::Connection (class)">Qpid::Proton::Connection</a></span> and objects associated with it |
| (<span class='object_link'><a href="Qpid/Proton/Session.html" title="Qpid::Proton::Session (class)">Qpid::Proton::Session</a></span>, <span class='object_link'><a href="Qpid/Proton/Sender.html" title="Qpid::Proton::Sender (class)">Qpid::Proton::Sender</a></span>, <span class='object_link'><a href="Qpid/Proton/Receiver.html" title="Qpid::Proton::Receiver (class)">Qpid::Proton::Receiver</a></span>, |
| <span class='object_link'><a href="Qpid/Proton/Delivery.html" title="Qpid::Proton::Delivery (class)">Qpid::Proton::Delivery</a></span>, <span class='object_link'><a href="Qpid/Proton/Tracker.html" title="Qpid::Proton::Tracker (class)">Qpid::Proton::Tracker</a></span>) are not thread-safe and |
| must be used correctly when multiple threads call |
| <span class='object_link'><a href="Qpid/Proton/Container.html#run-instance_method" title="Qpid::Proton::Container#run (method)">Qpid::Proton::Container#run</a></span></p> |
| |
| <p>Calls to <span class='object_link'><a href="Qpid/Proton/MessagingHandler.html" title="Qpid::Proton::MessagingHandler (class)">Qpid::Proton::MessagingHandler</a></span> and |
| <span class='object_link'><a href="Qpid/Proton/Listener/Handler.html" title="Qpid::Proton::Listener::Handler (class)">Qpid::Proton::Listener::Handler</a></span> methods by the <span class='object_link'><a href="Qpid/Proton/Container.html" title="Qpid::Proton::Container (class)">Qpid::Proton::Container</a></span> |
| are automatically serialized for each connection instance.</p> |
| |
| <p>Other threads may have code similarly serialized by adding it to the |
| <span class='object_link'><a href="Qpid/Proton/Connection.html#work_queue-instance_method" title="Qpid::Proton::Connection#work_queue (method)">Qpid::Proton::Connection#work_queue</a></span> for the connection. Each object |
| related to a <span class='object_link'><a href="Qpid/Proton/Connection.html" title="Qpid::Proton::Connection (class)">Qpid::Proton::Connection</a></span> also provides a |
| <code>work_queue</code> method.</p> |
| |
| <p>You also need to use the <span class='object_link'><a href="Qpid/Proton/WorkQueue.html" title="Qpid::Proton::WorkQueue (class)">Qpid::Proton::WorkQueue</a></span> to communicate between a |
| <span class='object_link'><a href="Qpid/Proton/MessagingHandler.html" title="Qpid::Proton::MessagingHandler (class)">Qpid::Proton::MessagingHandler</a></span> method call for one connection instance, |
| and a different <span class='object_link'><a href="Qpid/Proton/Connection.html" title="Qpid::Proton::Connection (class)">Qpid::Proton::Connection</a></span> instance in the same container, |
| as separate connections can be processed in parallel.</p> |
| </div></div> |
| |
| <div id="footer"> |
| Generated on Fri Sep 7 14:46:35 2018 by |
| <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a> |
| 0.9.8 (ruby-2.4.4). |
| </div> |
| |
| </div> |
| </body> |
| </html> |