amqp 0.8.0.rc14 → 0.8.0.rc15

data/docs/Bindings.textile

@@ -1,12 +1,13 @@
 # @title Ruby AMQP gem: Bindings
 
-h1. TBD
+h1. Working With Bindings
 
 h2. About this guide
 
 This guide covers bindings in AMQP 0.9.1, what they are, what role do they play and how to accomplish typical operations using
 Ruby amqp gem.
 
+This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a> (including images & stylesheets). The source is available "on Github":https://github.com/ruby-amqp/amqp/tree/master/docs.
 
 h2. Covered versions
 
@@ -16,27 +17,127 @@ This guide covers "Ruby amqp gem":http://github.com/ruby-amqp/amqp v0.8.0 and la
 
 h2. Bindings in AMQP 0.9.1
 
-TBD
+Bindings are rules that exchanges use (among other things) to route messages to queues. To instruct an exchange E to route messages to a queue Q,
+Q has to _be bound_ to E. Bindings may have an optional _routing key_ attribute used by some exchange types. The purpose of the routing key is to
+selectively match only specific (matching) messages published to an exchange to the bound queue. In other words, the routing key acts like a filter.
 
+Learn more about how bindings fit into the AMQP Model in the {file:docs/AMQP091ModelExplained.textile AMQP 0.9.1 Model Explained} documentation guide.
 
-h2. One day in life of an AMQP 0.9.1 message
 
-TBD
+h2. What Are AMQP 0.9.1 Bindings
+
+Bindings are rules that exchanges use (among other things) to route messages to queues. To instruct an exchange E to route messages to a queue Q,
+Q has to _be bound_ to E. Bindings may have an optional _routing key_ attribute used by some exchange types. The purpose of the routing key is to
+selectively match only specific (matching) messages published to an exchange to the bound queue. In other words, the routing key acts like a filter.
+
+To draw an analogy:
+
+ * Queue is like your destination in New York city
+ * Exchange is like JFK airport
+ * Bindings are routes from JFK to your destination. There can be none or more than one way to reach it
+
+Some exchange types use routing key while some others do not (and route messages unconditionally or based on message metadata).
+If AMQP message cannot be routed to any queue (for example, because there are no bindings for the exchange it was published to), it is either
+dropped or returned to the publisher, depending on message attributes the publisher has set.
+
+If application wants to connect a queue to an exchange, it needs to _bind_ them. The opposite operation is called _unbinding_.
 
 
 h2. Binding queues to exchanges
 
-TBD
+In order to receive messages, a queue needs to be bound to at least one exchange. Most of the time binding is explcit
+(done by applications). To bind a queue to an exchange, use {AMQP::Queue#bind} where the argument passed can be
+either an {AMQP::Exchange} instance or a string.
+
+<pre>
+<code>
+queue.bind(exchange) do |bind_ok|
+  puts "Just bound #{queue.name} to #{exchange.name}"
+end
+</code>
+</pre>
+
+Full example:
+<script src="https://gist.github.com/998727.js"> </script>
+
+The same example using a string without callback:
+
+<pre>
+<code>
+queue.bind("amq.fanout")
+</code>
+</pre>
+
+Full example:
+<script src="https://gist.github.com/998729.js"> </script>
 
 
 h2. Unbinding queues from exchanges
 
-TBD
+To unbind a queue from an exchange use {AMQP::Queue#unbind}:
+
+<pre>
+<code>
+queue.unbind(exchange)
+</code>
+</pre>
+
+Full example:
+<script src="https://gist.github.com/998742.js"> </script>
+
+<span class="note">
+Trying to unbind a queue from an exchange that the queue was never bound to will result in a
+channel-level exception.
+</span>
+
+
+h2. Bindings, Routing and Returned Messages
+
+h3. How AMQP 0.9.1 Brokers Route Messages
+
+After AMQP message reaches AMQP broker and before it reaches a consumer, several things happen:
+
+ * AMQP broker needs to find one or more queues the message needs to be routed to, depending on exchange
+ * AMQP broker puts a copy of the message into each of those queues or decides to return the messages to the publisher
+ * AMQP broker pushes messages to consumers on those queues or waits for applications to fetch them on demand
+
+A more in-depth description is this:
+
+ * AMQP broker needs to consult bindings list for the exchange the message was published to find one or more queues the message needs to be routed to (step 1)
+ * If there are no suitable queues found during step 1 and the message was published as mandatory, it is returned to the publisher (step 1b)
+ * If there are suitable queues, a _copy_ of the message is placed into each one (step 2)
+ * If the message was published as mandatory, but there are no active consumers for it, it is returned to the publisher (step 2b)
+ * If there are active consumers on those queues and basic.qos setting permits, message is pushed to those consumers (step 3)
+ * If there are no active consumers and the message is *not* published as mandatory, it will be left in the queue
+
+The takeaway is that messages may or may not be routed and it is important for applications to handle unroutable messages.
+
+
+h3. Handling of Unroutable Messages
+
+Unroutable messages are either dropped or returned back to producers. Vendor-specific extensions can provide additional ways of handing of unroutable
+messages: for example, RabbitMQ's "Alternate Exchanges extension":http://www.rabbitmq.com/extensions.html#alternate-exchange makes it possible to route unroutable messages to another exchange.
+amqp gem support for it is documented in the {file:docs/VendorSpecificExtensions.textile Vendor-specific Extensions guide}.
+
+RabbitMQ 2.6 will introduce a new feature callled dead letter queue where unroutable messages will be put instead of dropping them.
+
+amqp gem provides a way to handle returned messages with the {AMQP::Exchange#on_return} method:
+
+<pre>
+<code>
+exchange.on_return do |basic_return, metadata, payload|
+  puts "#{payload} was returned! reply_code = #{basic_return.reply_code}, reply_text = #{basic_return.reply_text}"
+end
+</code>
+</pre>
+
+{file:docs/Exchanges.textile Working With Exchanges} documentation guide provides more information on the subject, including full code examples.
+
 
 
-h2. Binding attributes
+h2. Authors
 
-TBD
+This guide was written by "Michael Klishin":http://twitter.com/michaelklishin and edited by "Chris Duncan":https://twitter.com/celldee.
 
 
 

data/docs/ConnectingToTheBroker.textile

@@ -8,6 +8,8 @@ h2. About this guide
 This guide covers connection to an AMQP broker from standalone and Web applications,
 connection error handling, authentication failure handling and related issues.
 
+This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a> (including images & stylesheets). The source is available "on Github":https://github.com/ruby-amqp/amqp/tree/master/docs.
+
 
 h2. Which versions of the amqp gem does this guide cover?
 
@@ -502,6 +504,12 @@ h2. What to read next
  * {file:docs/ConnectionEncryptionWithTLS.textile Using TLS (SSL)} (if you want to use an SSL encrypted connection to the broker)
 
 
+h2. Authors
+
+This guide was written by "Michael Klishin":http://twitter.com/michaelklishin and edited by "Chris Duncan":https://twitter.com/celldee.
+
+
+
 h2. Tell us what you think!
 
 Please take a moment to tell us what you think about this guide "on Twitter":http://twitter.com/rubyamqp or the "Ruby AMQP mailing list":http://groups.google.com/group/ruby-amqp.

data/docs/ConnectionEncryptionWithTLS.textile

@@ -79,6 +79,11 @@ h2. Example code
 TLS example (as well as sample certificates you can use to get started with) can be found in the "amqp gem git repository":https://github.com/ruby-amqp/amqp/tree/master/examples
 
 
+h2. Authors
+
+This guide was written by "Michael Klishin":http://twitter.com/michaelklishin and edited by "Chris Duncan":https://twitter.com/celldee.
+
+
 
 h2. Tell us what you think!
 

data/docs/DocumentationGuidesIndex.textile

@@ -4,7 +4,7 @@ h1. Ruby AMQP gem documentation guides
 
 h2. Which versions of the amqp gem do the guides cover?
 
-These guides cover v0.8.0.RC13 and later of the "Ruby amqp gem":http://github.com/ruby-amqp/amqp.
+These guides cover v0.8.0.RC14 and later of the "Ruby amqp gem":http://github.com/ruby-amqp/amqp.
 
 
 h2. Documentation structure and how to read these guides
@@ -29,9 +29,9 @@ Here is a summary of guides and their content:
 
   <dt>{file:docs/AMQP091ModelExplained.textile AMQP 0.9.1 Model Explained}</dt>
   <dd>
-  Explains the AMQP 0.9.1 model, focusing on what purpose individual features have. Reading
+  A simple, 2 page long introduction to the AMQP 0.9.1 model, focusing on what purpose individual features have. Reading
   other documentation guides will be easier when you are armed with this knowledge: a lot of the AMQP & RabbitMQ power
-  comes from the AMQP model.
+  comes from the AMQP Model.
   </dd>
 
   <dt>{file:docs/ConnectingToTheBroker.textile Connecting to the Broker}</dt>
@@ -51,8 +51,14 @@ Here is a summary of guides and their content:
   <dt>{file:docs/Exchanges.textile Working With Exchanges}</dt>
   <dd>
   What AMQP exchanges are. Concept of binding. How to declare AMQP exchanges. How different exchange types route messages and common
-  use cases. How to publish messages, especially how to do it reliably. What AMQP transactions are. What Publisher Confirms are.
-  How to delete an exchange.
+  use cases. How to publish messages, especially how to do it reliably. What AMQP transactions are. What Publisher Confirms are. When
+  messages are returned. How to delete an exchange.
+  </dd>
+
+  <dt>{file:docs/Bindings.textile Bindings}</dt>
+  <dd>
+  What AMQP bindings are, in-depth. How to bind queues to exchanges. How to unbind queues from exchanges. What's the life cycle
+  of messages is. How unroutable messages are handled.
   </dd>
 
   <dt>{file:docs/PatternsAndUseCases.textile Patterns and Use Cases}</dt>
@@ -101,6 +107,16 @@ h2. Full guide list
  * {file:docs/RunningTests.textile Running amqp gem test suite}
 
 
+h2. License
+
+This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a> (including images & stylesheets). The source is available "on Github":https://github.com/ruby-amqp/amqp/tree/master/docs.
+
+h2. Authors
+
+These guides were written by "Michael Klishin":http://twitter.com/michaelklishin and edited by "Chris Duncan":https://twitter.com/celldee
+
+
+
 h2. Tell us what you think!
 
 Please take a moment to tell us what you think about this guide "on Twitter":http://twitter.com/rubyamqp or the "Ruby AMQP mailing list":http://groups.google.com/group/ruby-amqp.

data/docs/Durability.textile

@@ -8,6 +8,8 @@ h2. About this guide
 This guide covers queue, exchange and message durability, as well as other
 topics related to durability, for example, durability in cluster environment.
 
+This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a> (including images & stylesheets). The source is available "on Github":https://github.com/ruby-amqp/amqp/tree/master/docs.
+
 
 h2. Covered versions
 
@@ -43,7 +45,7 @@ AMQP broker persist them to disk. If the server is restarted, the system ensures
 are not lost. Simply publishing message to a durable exchange or the fact that queue(s) they are routed to
 is durable doesn't make messages persistent: it all depends on persistence mode of the messages itself.
 Publishing messages as persistent affects performance (just like with data stores, durability comes at a certain cost
-in performance and vise versa). Pass :persistent => true to {Exchange#publish} to publish your message as persistent.
+in performance and vise versa). Pass :persistent => true to {AMQP::Exchange#publish} to publish your message as persistent.
 
 
 h3. Transactions

data/docs/ErrorHandling.textile

@@ -21,6 +21,7 @@ as well as
  * How to recover after a network failure
  * What is automatic recovery mode, when you should and should not use it
 
+This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a> (including images & stylesheets). The source is available "on Github":https://github.com/ruby-amqp/amqp/tree/master/docs.
 
 
 h2. Covered versions
@@ -271,6 +272,11 @@ Detecting network connections is nearly useless if AMQP-based application cannot
 in "error handling and recovery". Fortunately, recovery process for many applications follows one simple scheme that amqp
 gem can perform automatically for you.
 
+<span class="note">
+Recovery process, both manual and automatic, always begins with re-opening AMQP connection and then all the channels on that connection.
+</span>
+
+
 h3. Manual recovery
 
 Similarly to the Shutdown Protocol, amqp gem entities implement Recovery Protocol. Recovery Protocol consists of 3 methods
@@ -286,6 +292,15 @@ re-established but before AMQP connection is reopened*. {AMQP::Session#after_rec
 
 {AMQP::Channel}, {AMQP::Queue}, {AMQP::Consumer} and {AMQP::Exchange} methods behavior is identical.
 
+Recovery process for AMQP applications usually involves the following steps:
+
+ # Re-open AMQP connection.
+ # Once connection is open again, re-open all AMQP channels on that connection.
+ # For each channel, re-declare all exchanges
+ # For each channel, re-declare all queues
+ # Once queue is declared, for each queue, re-register all bindings
+ # Once queue is declared, for each queue, re-register all consumers
+
 
 h3. Automatic recovery
 
@@ -591,6 +606,11 @@ but they turn out to be similar with respect to network failures and connection-
 TBD
 
 
+h2. Authors
+
+This guide was written by "Michael Klishin":http://twitter.com/michaelklishin and edited by "Chris Duncan":https://twitter.com/celldee.
+
+
 
 h2. Tell us what you think!
 

data/docs/Exchanges.textile

@@ -6,7 +6,7 @@ h1. Working with exchanges
 h2. About this guide
 
 This guide covers the use of exchanges according to the AMQP v0.9.1 specification including message publishing,
-common usage scenarios and how to accomplish typical operations using the Ruby amqp gem.
+common usage scenarios and how to accomplish typical operations using the Ruby amqp gem. This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a> (including images & stylesheets). The source is available "on Github":https://github.com/ruby-amqp/amqp/tree/master/docs.
 
 
 h2. Which versions of the amqp gem does this guide cover?
@@ -1051,6 +1051,12 @@ topics. Guides related to this one are
  * {file:docs/ErrorHandling.textile Error handling and recovery}
 
 
+h2. Authors
+
+This guide was written by "Michael Klishin":http://twitter.com/michaelklishin and edited by "Chris Duncan":https://twitter.com/celldee.
+
+
+
 h2. Tell us what you think!
 
 Please take a moment to tell us what you think about this guide "on Twitter":http://twitter.com/rubyamqp or the "Ruby AMQP mailing list":http://groups.google.com/group/ruby-amqp.

data/docs/GettingStarted.textile

@@ -15,6 +15,8 @@ It should take about 20 minutes to read and study the provided code examples. Th
  * Creating a topic routing example with 2 publishers and 8 subscribers showcasing n:m communication when subscribers only receive messages that they are interested in.
  * Learning how the amqp gem can be integrated with Ruby objects in a way that makes unit testing easy.
 
+This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a> (including images & stylesheets). The source is available "on Github":https://github.com/ruby-amqp/amqp/tree/master/docs.
+
 
 h2. Which versions of the amqp gem does this guide cover?
 
@@ -588,6 +590,8 @@ topics from {file:docs/Exchanges.textile use cases for various exchange types} t
 
 We recommend that you read the following guides next, if possible, in this order:
 
+ * {file:docs/AMQP091ModelExplained.textile AMQP 0.9.1 Model Explained}. A simple 2 page long introduction to the AMQP Model concepts and features. Understanding the AMQP Model
+   will make a lot of other documentation, both for the Ruby amqp gem and RabbitMQ itself, easier to follow. With this guide, you don't have to waste hours of time reading the whole specification.
  * {file:docs/ConnectingToTheBroker.textile Connection to the broker}. This guide explains how to connect to an AMQP broker and how to integrate the amqp gem into standalone and Web applications.
  * {file:docs/Queues.textile Working With Queues}. This guide focuses on features that consumer applications use heavily.
  * {file:docs/Exchanges.textile Working With Exchanges}. This guide focuses on features that producer applications use heavily.
@@ -598,6 +602,12 @@ If you are migrating your application from earlier versions of the amqp gem (0.6
 {file:docs/08Migration.textile amqp gem 0.8 migration guide}.
 
 
+h2. Authors
+
+This guide was written by "Michael Klishin":http://twitter.com/michaelklishin and edited by "Chris Duncan":https://twitter.com/celldee.
+
+
+
 h2. Tell us what you think!
 
 Please take a moment to tell us what you think about this guide "on Twitter":http://twitter.com/rubyamqp or the "Ruby AMQP mailing list":http://groups.google.com/group/ruby-amqp.

data/docs/PatternsAndUseCases.textile

@@ -9,6 +9,8 @@ h2. About this guide
 This guide explains typical messaging patterns and use cases. It only covers the most common scenarios. For comprehensive list
 of messaging patterns, consult books on this subject, for example, "Enterprise Integration Patterns":http://www.eaipatterns.com.
 
+This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a> (including images & stylesheets). The source is available "on Github":https://github.com/ruby-amqp/amqp/tree/master/docs.
+
 
 h2. Covered versions
 
@@ -410,6 +412,10 @@ h3. Code example
 TBD
 
 
+h2. Authors
+
+These guides were written by "Michael Klishin":http://twitter.com/michaelklishin and edited by "Chris Duncan":https://twitter.com/celldee
+
 
 h2. Tell us what you think!
 

data/docs/Queues.textile

@@ -6,7 +6,7 @@ h1. Working with queues
 h2. About this guide
 
 This guide covers everything related to queues in the AMQP v0.9.1 specification, common usage scenarios and how to accomplish typical operations using the
-amqp gem.
+amqp gem. This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a> (including images & stylesheets). The source is available "on Github":https://github.com/ruby-amqp/amqp/tree/master/docs.
 
 
 h2. Which versions of the amqp gem does this guide cover?
@@ -1161,6 +1161,12 @@ RabbitMQ implements a number of extensions to AMQP v0.9.1 functionality that are
 per-queue messages time-to-live (TTL), is related to this guide and can be used with the amqp gem v0.8.0 and later.
 
 
+h2. Authors
+
+This guide was written by "Michael Klishin":http://twitter.com/michaelklishin and edited by "Chris Duncan":https://twitter.com/celldee.
+
+
+
 h2. Tell us what you think!
 
 Please take a moment to tell us what you think about this guide "on Twitter":http://twitter.com/rubyamqp or the "Ruby AMQP mailing list":http://groups.google.com/group/ruby-amqp.

data/docs/RabbitMQVersions.textile

@@ -46,7 +46,12 @@ support, RabbitMQ 1.7.0 requires
  * Erlang/OTP R13B or later
  * Erlang SSL 3.10 or later
 
-and recommends using Erlang R141B that ships with Erlang SSL 4.0.1.
+and recommends using Erlang R141B that ships with Erlang SSL 4.0.1. Learn more in our {file:docs/ConnectionEncryptionWithTLS.textile Using TLS (SSL)} guide.
+
+
+h2. Authors
+
+This guide was written by "Michael Klishin":http://twitter.com/michaelklishin and edited by "Chris Duncan":https://twitter.com/celldee.
 
 
 

data/docs/RunningTests.textile

@@ -8,6 +8,8 @@ h2. About this guide
 This guide is for people who want to contribute to amqp gem development. It has no relevant information for those
 who want to build applications using the library.
 
+This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a> (including images & stylesheets). The source is available "on Github":https://github.com/ruby-amqp/amqp/tree/master/docs.
+
 
 h2. Covered versions
 
@@ -42,7 +44,7 @@ h2. Dependencies
 Dependencies are managed by Bundler. So begin with
 
 <pre><code>
-gem install bundler --version "~> 1.0.13"
+gem install bundler
 </code></pre>
 
 and then, from the root of the repository run
@@ -82,9 +84,12 @@ For that, we use Rake:
 rake spec:ci
 </code></pre>
 
-Thanks to the excellent "Travis CI":http://travis-ci.org project, we run test suites across 5 Ruby implementations and 2 EventMachine versions, and can
-add more implementations/versions so easily it still seems unreal.
+Thanks to the excellent "Travis CI":http://travis-ci.org project, we run test suites across multiple Ruby implementations/versions and 2 EventMachine versions.
+
+
+h2. Authors
 
+This guide was written by "Michael Klishin":http://twitter.com/michaelklishin and edited by "Chris Duncan":https://twitter.com/celldee.