# @title Ruby AMQP gem: Migrating to version 0.8.0 and later

h1. amqp gem 0.8 migration guide


h2. About this guide

This guide explains how (and why) applications that use amqp gem versions 0.6.x and 0.7.x should migrate
to 0.8.0.RCs and future versions. It also outlines deprecated features, when and why they will be removed.

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

This guide covers "Ruby amqp gem":http://github.com/ruby-amqp/amqp v0.6.x and v0.7.x.



h2. Brief history of amqp gem

amqp gem was born in early July 2008. Since then, it has seen 7 releases, used by all kinds of companies, have been
key component to systems that process more than 100 gigabytes of data per day and, despite not being a "1.0 library",
proven to be very usable.

For the most part of 2008 and 2009 the gem did not receive much of attention. In 2010, some other AMQP clients (for example,
RabbitMQ Java & .NET clients) switched to AMQP 0.9.1 specification. By the fall of 2010 it became clear that amqp gem needs
a new team of maintainers, deep refactoring, new solid test suite and extensive documentation guides. Long story short,
by December 2010, the "new maintainers group":https://github.com/ruby-amqp was formed and now maintains number of other libraries
in the Ruby AMQP ecosystem, most notably the "Bunny gem":github.com/ruby-amqp/bunny.

Over first few months of 2011, amqp gem undergone a number of maintenance releases (known as 0.7.x series), a ground up rewrite of
the test suite, major documentation update as well as a major refactoring. It was upgraded to AMQP 0.9.1 specification and
based on a new, much more efficient AMQP serialization library, "amq-protocol":https://github.com/ruby-amqp/amq-protocol.

As part of this transition, amqp gem maintainers team pursued a number of goals:

 * Implement AMQP 0.9.1 spec plus all the RabbitMQ extensions
 * End "300 of 1 patch forks" situation that had gotten especially bad in early 2010
 * Produce a solid end-to-end test suite that imitates real asynchronous applications
 * Resolve many API usability issues: inconsistent behavior, weird class and method naming, heavy reliance on implicit connection objects and so on
 * Produce documentation guides that other AMQP client users will be envious of
 * Define a stable public API
 * Improve memory efficiency and performance
 * Resolve many limitations of the original API and implementation design
 * Drop all the "experimental-stuff-that-was-never-finished"

In the end, several projects like "evented-spec":https://github.com/ruby-amqp/evented-spec were born and became part of the amqp gem
family of libraries. "300 one patch forks" hell is a thing of the past. Even initial pure Ruby implementation of the new serialization
library is "several times as memory efficient":http://www.rabbitmq.com/blog/2011/03/01/ruby-amqp-benchmarks/. "Documentation guides":http://bit.ly/amqp-gem-docs
response if very positive. amqp gem 0.8.0.RCs implement all but 1 RabbitMQ extensions as well as AMQP 0.9.1 spec features original gem
never implemented fully. Many large users of the gem upgraded to 0.8.0.RCs. The future for amqp gem and its spin-offs is bright.


h2. amqp gem 0.8.0 backwards compatibility policy

amqp gem 0.8.0 is *not 100% backwards compatible*. That said, for most applications, upgrade path will be easy.
Over 90% of the deprecated API classes & methods are still in place and will only be dropped in the 0.9.0 release.

Plenty of incompatibilities between 0.6.x and 0.7.x series were ironed out in 0.8.0.RCs. Finally, this guide will explain
what has changed, why, why it is the right thing to do and how you should adapt your application code.



h2. Why developers should upgrade to 0.8.0

 * Great documentation
 * amqp gem 0.8.0 RCs and later versions are actively maintained
 * Largest library users either already switched to amqp gem 0.8.0 RCs or are switching in the near future (2011)
 * AMQP 0.9.1 spec implementation: many other popular clients, for example the RabbitMQ Java client, has dropped support for AMQP 0.8 specification
 * RabbitMQ extensions
 * Several AMQP brokers, including RabbitMQ (by far the most popular from the maintainers team observation), are planning to drop AMQP 0.8 spec support
 * Applications that do not use depricated API features & behaviors will have very seamless upgrade path to the amqp gem 0.9.0 and beyond



h2. AMQP protocol version change

amqp gem before 0.8.0 (0.6.x, 0.7.x) series implemented (most of) AMQP 0.8 specification. amqp gem 0.8.0 implements AMQP 0.9.1 and thus
*requires RabbitMQ version 2.0 or later*. See {file:docs/RabbitMQVersions.textile RabbitMQ versions} for more information about
RabbitMQ versions support and how obtain up-todate packages for your operating system.

<span class="note">
amqp gem 0.8.0 and later versions implement AMQP 0.9.1 and thus *requires RabbitMQ version 2.0 or later*
</span>



h2. Follow established AMQP terminology

h3. require "mq" is deprecated

Instead of the following:

<pre>
<code>
require "amqp"
require "mq"
</code>
</pre>

or

<pre>
<code>
require "mq"
</code>
</pre>


switch to

<pre>
<code>
require "amqp"
</code>
</pre>

<span class="note">
mq.rb will be removed before 1.0 release.
</span>


h3. MQ class is deprecated

Please use {AMQP::Channel} instead. MQ class & its methods are implemented in amqp gem 0.8.x for backwards compatibility,
but only for transition period (that will end after 0.9 release).

Why is it deprecated? Because it was a poor name choice all along. Both mq.rb and MQ class step away from AMQP terminology and
make 8 out of 10 engineers think it has something to do with AMQP queues (in fact, MQ should have been called Channel all along).
No other AMQP client library we know of invents its own terminology when it comes to AMQP entities, and amqp gem shouldn't, too.

<span class="note">
MQ class and class methods that use implicit connection (MQ.queue and so on) will be removed before 1.0 release.
</span>


h2. MQ class is now AMQP::Channel

MQ class was renamed to AMQP::Channel to follow established {file:docs/AMQP091ModelExplained.textile AMQP 0.9.1 terminology}. Implicit per-thread
channels are deprecated so code like this:

<pre>
<code>
# amqp gem 0.6.x code style: connection is implicit, channel is implicit. Error handling & recovery are thus
# not possible.
# Deprecated, do not use.
MQ.queue("search.indexing")

# same for exchanges. Deprecated, do not use.
MQ.direct("services.imaging")
MQ.fanout("services.broadcast")
MQ.topic("services.weather_updates")
</code>
</pre>

<pre>
<code>
# connection object lets you define error handlers
connection = AMQP.connect(:vhost => "myapp/production", :host => "192.168.0.18")
# channek object lets you define error handlers and use multiple channels per application,
# for example, one per thread
channel    = AMQP::Channel.new(connection)
# AMQP::Channel#queue has unchanged otherwise
channel.queue("search.indexing")

# exchanges examples
channel.direct("services.imaging")
channel.fanout("services.broadcast")
channel.topic("services.weather_updates")
</code>
</pre>

<span class="note">
MQ.queue, MQ.direct, MQ.fanout and MQ.topic methods will be removed before 1.0 release. Use
instance methods on AMQP::Channel (AMQP::Channel#queue, AMQP::Channel#direct, AMQP::Channel#default_exchange
and so on) instead.
</span>


h2. MQ::Queue is now AMQP::Queue

MQ::Queue is now AMQP::Queue. All the methods from 0.6.x series are still available.

<span class="note">
MQ::Queue alias will be removed before 1.0 release. Please switch to AMQP::Queue.
</span>


h2. MQ::Exchange is now AMQP::Exchange

MQ::Exchange is now AMQP::Exchange. All the methods from 0.6.x series are still available.

<span class="note">
MQ::Exchange alias will be removed before 1.0 release. Please switch to AMQP::Exchange.
</span>



h2. MQ::Header is now AMQP::Header

MQ::Header is now AMQP::Header. If you code has any type checks or case matches on
MQ::Header, it needs to change to AMQP::Header.


h2. AMQP.error is deprecated

Catch-all solutions for error handling are very difficult to use. Automatic recovery and fine-grained
event handling is also not possible. amqp gem 0.8.0.RC14 and later includes fine-grained {file:docs/ErrorHandling.textile Error Handling and Recovery API}
that is both significantly easier to use in real-world cases but also makes automatic recovery mode possible.

<span class="note">
AMQP.error method will be removed before 1.0 release.
</span>


h2. MQ::RPC is deprecated

It was an experiment that was never finished. Some API design choices are very opinionated as well. amqp gem should not ship with
half-baked poorly designed or overly opinionated solutions.

<span class="note">
MQ::RPC class will be removed before 1.0 release.
</span>


h2. MQ::Logger is removed

It was an experiment that was never finished. Some API design choices are very opinionated as well. amqp gem should not ship with
half-baked poorly designed or overly opinionated solutions.

<span class="note">
MQ::Logger class was removed in the the amqp gem 0.8.0 development cycle.
</span>


h2. AMQP::Buffer is removed

AMQP::Buffer was AMQP 0.8 protocol implementation detail. With the new "amq-protocol gem":http://rubygems.org/gems/amq-protocol, it is no
longer relevant.

<span class="note">
AMQP::Buffer class was removed in the the amqp gem 0.8.0 development cycle.
</span>


h2. AMQP::Frame is removed

AMQP::Frame was AMQP 0.8 protocol implementation detail. With the new "amq-protocol gem":http://rubygems.org/gems/amq-protocol, it is no
longer relevant.

<span class="note">
AMQP::Frame class was removed in the the amqp gem 0.8.0 development cycle.
</span>


h2. AMQP::Server is removed

AMQP::Server was (an unfinished) toy implementation of AMQP 0.8 broker in Ruby on top of EventMachine. We believe that Ruby is not an optimal
choice for AMQP broker implementations. We also never heard from anyone using it.

<span class="note">
AMQP::Server class was removed in the the amqp gem 0.8.0 development cycle.
</span>


h2. AMQP::Protocol::* classes are removed

AMQP::Protocol::* classes were AMQP 0.8 protocol implementation detail. With the new "amq-protocol gem":http://rubygems.org/gems/amq-protocol, they are no
longer relevant.

<span class="note">
AMQP::Protocol::* classes were removed in the the amqp gem 0.8.0 development cycle.
</span>




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 and tell us what you think about this guide "on Twitter":http://twitter.com/rubyamqp or "Ruby AMQP mailing list":http://groups.google.com/group/ruby-amqp:
what was unclear? what wasn't covered? maybe you don't like guide style or grammar and spelling are incorrect? Readers feedback is
key to making documentation better.

If mailing list communication is not an option for you for some reason, you can "contact guides author directly":mailto:michael@novemberain.com?subject=amqp%20gem%20documentation