amqp gem 0.8 migration guide

This Documentation Has Moved to rubyamqp.info

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.

Covered versions

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 was formed and now maintains number of other libraries
in the Ruby AMQP ecosystem, most notably the Bunny gem.

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.

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 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 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. Documentation guides
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.

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.

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

amqp gem 0.8.0 and later versions implement AMQP 0.9.1 and thus requires RabbitMQ version 2.0 or later

Follow established AMQP terminology

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.

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.

MQ class is now AMQP::Channel

MQ class was renamed to AMQP::Channel to follow established AMQP 0.9.1 terminology. Implicit per-thread
channels are deprecated so code like this:

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.

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.

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.

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.

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 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.

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.

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.

AMQP::Buffer is removed

AMQP::Buffer was AMQP 0.8 protocol implementation detail. With the new amq-protocol gem, it is no
longer relevant.

AMQP::Buffer class was removed in the the amqp gem 0.8.0 development cycle.

AMQP::Frame is removed

AMQP::Frame was AMQP 0.8 protocol implementation detail. With the new amq-protocol gem, it is no
longer relevant.

AMQP::Frame class was removed in the the amqp gem 0.8.0 development cycle.

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.

AMQP::Protocol::* classes are removed

AMQP::Protocol::* classes were AMQP 0.8 protocol implementation detail. With the new amq-protocol gem, they are no
longer relevant.

AMQP::Protocol::* classes were removed in the the amqp gem 0.8.0 development cycle.

Authors

Tell us what you think!

Please take a moment and tell us what you think about this guide on Twitter or Ruby AMQP mailing list:
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.