# @title Ruby AMQP gem documentation guides

h1. Ruby AMQP gem documentation guides

h2. Which versions of the amqp gem do the guides cover?

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

We recommend that you read the documentation guides in the order that they are listed. The *Getting Started* guide is written as a tutorial that
describes several typical applications and their problem scope, then provides full code examples and finally breaks them down
into smaller pieces that are explained in detail.

Once you are finished with the tutorial, reading the other guides in sequence will gradually explain all of the AMQP 0.9.1 features that are relevant to
application developers, including application design concerns and common practices. At present, some guides are yet to be written
but *most of the content is concentrated in just 3-4 guides* that are about 80% finished and provide plenty of examples.

Here is a summary of guides and their content:

<dl>
  <dt>{file:docs/GettingStarted.textile Getting Started with Ruby amqp gem and RabbitMQ}</dt>
  <dd>
  Walks you through gem installation and 3 applications that demonstrate what AMQP has to offer. Explains how amqp gem should
  be integrated into rich object-oriented Ruby programs.
  </dd>


  <dt>{file:docs/AMQP091ModelExplained.textile AMQP 0.9.1 Model Explained}</dt>
  <dd>
  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.
  </dd>

  <dt>{file:docs/ConnectingToTheBroker.textile Connecting to the Broker}</dt>
  <dd>
  Connecting to AMQP broker. How to integrate with standalone applications as well as Ruby on Rails, Merb, Sinatra or Rack apps.
  What difference application server (Unicorn, Passenger, Thin, etc) makes. How to handle authentication failures and network
  connectivity issues. Closing AMQP connection gracefully.
  </dd>

  <dt>{file:docs/Queues.textile Working With Queues}</dt>
  <dd>
  What AMQP queues are. How to declare AMQP queues. When and how to use server-named and explicitly named queues. How to subscribe
  for "push" message delivery. What message acknowledgements are. How to access AMQP message metadata. How to fetch ("pull") messages
  from queues on demand. How to bind and unbind a queue to an exchange. How to delete a queue.
  </dd>

  <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. 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>
  <dd>Typical use cases, patterns and routing topologies.</dd>

  <dt>{file:docs/Durability.textile Durability and Message Persistence}</dt>
  <dd>Exchange durability. Queue durability. Message persistence. Performance implications.</dd>

  <dt>{file:docs/ErrorHandling.textile Error Handling and Recovery}</dt>
  <dd>
  Network failures. Connection-level exceptions. Channel-level exceptions. Why error handling is easy but
  recovery is hard. How to survive typical problems. What other tools can help (e.g. HAProxy).
  </dd>

  <dt>{file:docs/TestingWithEventedSpec.textile Unit and integration testing of AMQP applications}</dt>
  <dd>
  Unit testing of asynchronous code: typical problems and ways to solve them. An oviewview of evented-spec, the gem that amqp gem itself uses
  for "its test suite":https://github.com/ruby-amqp/amqp/tree/master/spec.
  </dd>


  <dt>{file:docs/RabbitMQVersions.textile RabbitMQ versions}</dt>
  <dd>
  RabbitMQ versions that amqp gem supports. Popular Linux distributions and RabbitMQ versions they ship. How to obtain up-to-date official
  packages of RabbitMQ.
  </dd>

  <dt>{file:docs/ConnectionEncryptionWithTLS.textile Using TLS (SSL)}</dt>
  <dd>All things related to TLS-encrypted connections.</dd>
</dl>


When more than one guide describes the same concept, we make sure to use cross-references, however, only one guide discusses the concept in detail.


h2. Full guide list

 * {file:docs/GettingStarted.textile Getting Started with Ruby amqp gem and RabbitMQ}
 * {file:docs/AMQP091ModelExplained.textile AMQP 0.9.1 Model Explained}
 * {file:docs/ConnectingToTheBroker.textile Connecting to the Broker}
 * {file:docs/Queues.textile Working With Queues}
 * {file:docs/Exchanges.textile Working With Exchanges}
 * {file:docs/Bindings.textile Bindings}
 * {file:docs/PatternsAndUseCases.textile Patterns and Use Cases}
 * {file:docs/Durability.textile Durability and Message Persistence}
 * {file:docs/ErrorHandling.textile Error Handling and Recovery}
 * {file:docs/08Migration.textile Upgrading from version 0.6.x/0.7.x to 0.8.x and above}
 * {file:docs/TestingWithEventedSpec.textile Unit and integration testing of AMQP applications}
 * {file:docs/Troubleshooting.textile Troubleshooting and debugging AMQP applications}
 * {file:docs/Clustering.textile Clustering}
 * {file:docs/RabbitMQVersions.textile RabbitMQ versions}
 * {file:docs/ConnectionEncryptionWithTLS.textile Using TLS (SSL)}
 * {file:docs/VendorSpecificExtensions.textile Vendor-specific Extensions to AMQP 0.9.1 spec}
 * {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.
 Let us know what was unclear or what has not been covered. Maybe you do not like the guide style or grammar or discover spelling mistakes. Reader feedback is
key to making the documentation better.

If, for some reason, you cannot use the communication channels mentioned above, you can "contact the author of the guides directly":mailto:michael@novemberain.com?subject=amqp%20gem%20documentation


<div id="disqus_thread"></div>
<script type="text/javascript">
    /* * * CONFIGURATION VARIABLES * * */
    var disqus_shortname = 'rubyamqpdocs'; // required: replace example with your forum shortname

    var disqus_developer = 0; // set to 1 on local machine for testing comments
    var disqus_identifier = 'amqp_documentation_guides_index';
    var disqus_url = 'http://rdoc.info/github/ruby-amqp/amqp/master/file/docs/DocumentationGuidesIndex.textile';

    /* * * DON'T EDIT BELOW THIS LINE * * */
    (function() {
        var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
        dsq.src = 'http://' + disqus_shortname + '.disqus.com/embed.js';
        (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
    })();
</script>