# @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 Creative Commons Attribution 3.0 Unported License (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.RCs series implemented (most of) AMQP 0.8 specification.
h2. Follow established AMQP terminology
h3. require "mq" is deprecated
Instead of the following:
require "amqp"
require "mq"
or
require "mq"
switch to
require "amqp"
mq.rb will be removed before 1.0 release.
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.
MQ class and class methods that use implicit connection (MQ.queue and so on) will be removed before 1.0 release.
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:
# 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")
# 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")
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.
h2. MQ::Queue is now AMQP::Queue
MQ::Queue is now AMQP::Queue. All the methods from 0.6.x series are still available.
MQ::Queue alias will be removed before 1.0 release. Please switch to AMQP::Queue.
h2. MQ::Exchange is now AMQP::Exchange
MQ::Exchange is now AMQP::Exchange. All the methods from 0.6.x series are still available.
MQ::Exchange alias will be removed before 1.0 release. Please switch to AMQP::Exchange.
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.
AMQP.error method will be removed before 1.0 release.
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.
MQ::RPC class will be removed before 1.0 release.
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.
MQ::Logger class was removed in the the amqp gem 0.8.0 development cycle.
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.
AMQP::Buffer class was removed in the the amqp gem 0.8.0 development cycle.
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.
AMQP::Frame class was removed in the the amqp gem 0.8.0 development cycle.
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.
AMQP::Server class was removed in the the amqp gem 0.8.0 development cycle.
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.
AMQP::Protocol::* classes were removed in the the amqp gem 0.8.0 development cycle.
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