README.md in amqp-0.8.0.rc13 vs README.md in amqp-0.8.0.rc14
- old
+ new
@@ -1,13 +1,13 @@
# About Ruby amqp gem #
Ruby amqp gem is a widely used, feature-rich, well-maintained asynchronous AMQP 0.9.1 client with batteries included.
This library works with Ruby 1.8.7 (p174 and p334), Ruby 1.9.2, [JRuby](http://jruby.org) (highly recommended to Microsoft Windows users), [REE](http://www.rubyenterpriseedition.com) and [Rubinius](http://rubini.us), and is licensed under the [Ruby License](http://www.ruby-lang.org/en/LICENSE.txt)
-Versions 0.8.0 and later of amqp gem implement [AMQP 0.9.1](http://bit.ly/hw2ELX) and supports [RabbitMQ extensions to AMQP 0.9.1](http://www.rabbitmq.com/extensions.html).
+Versions 0.8.0.RC13 and later of amqp gem implement [AMQP 0.9.1](http://bit.ly/amqp-model-explained) (see also [AMQP 0.9.1 spec document](http://bit.ly/hw2ELX)) and support [RabbitMQ extensions to AMQP 0.9.1](http://www.rabbitmq.com/extensions.html).
-[](http://travis-ci.org/ruby-amqp/amqp)
+[](http://travis-ci.org/ruby-amqp/amqp)
## I know what AMQP is, how do I get started? ##
See [Getting started with amqp gem](http://bit.ly/getting-started-with-amqp-ruby-gem) and other [documentation guides](http://bit.ly/amqp-gem-docs).
@@ -18,11 +18,11 @@
AMQP is an [open standard for messaging middleware](http://www.amqp.org/confluence/display/AMQP/About+AMQP) that
emphasizes interoperability between different technologies (for example, Java, .NET, Ruby, Python, Node.js, Erlang, C and so on).
Key features of AMQP are very flexible yet simple routing and binary protocol efficiency. AMQP supports many sophisticated features, for example,
-message acknowledgements, returning messages to producer, delivery confirmation, flow control and so on.
+message acknowledgements, returning of messages to producer, redelivery of messages that couldn't be processed, load balancing between message consumers and so on.
## What is amqp gem good for? ##
One can use amqp gem to make Ruby applications interoperate with other
@@ -30,24 +30,28 @@
simple work queues to complex multi-stage data processing workflows that involve
dozens or hundreds of applications built with all kinds of technologies.
Specific examples:
+ * Events collectors, metrics & analytics applications can aggregate events produced by various applications
+ (Web and not) in the company network.
+
* A Web application may route messages to a Java app that works
with SMS delivery gateways.
- * Periodically run (Cron-driven) application may notify other systems that
- there are some new results.
+ * MMO games can use flexible routing AMQP provides to propagate event notifications to players and locations.
+ * Price updates from public markets or other sources can be distributed between interested parties, from trading systems to points of sale in a specific geographic region.
+
* Content aggregators may update full-text search and geospatial search indexes
by delegating actual indexing work to other applications over AMQP.
* Companies may provide streaming/push APIs to their customers, partners
or just general public.
- * A new shiny Ruby-based system may be integrated with an existing C++-based component
- using AMQP.
+ * Continuous integration systems can distribute builds between multiple machines with various hardware and software
+ configurations using advanced routing features of AMQP.
* An application that watches updates from a real-time stream (be it markets data
or Twitter stream) can propagate updates to interested parties, including
Web applications that display that information in the real time.
@@ -65,15 +69,15 @@
### Install the gem ###
On Microsoft Windows 7
gem install eventmachine --pre
- gem install amqp --pre --version "~> 0.8.0.RC12"
+ gem install amqp --pre
On other OSes or [JRuby](http://jruby.org):
- gem install amqp --pre --version "~> 0.8.0.RC12"
+ gem install amqp --pre
### "Hello, World" example ###
#!/usr/bin/env ruby
@@ -108,19 +112,20 @@
exchange.publish "Hello, world!", :routing_key => queue.name
end
[Getting started guide](http://bit.ly/getting-started-with-amqp-ruby-gem) explains this and two more examples in detail,
-and is written in a form of a tutorial.
+and is written in a form of a tutorial. See [AMQP Model Explained](http://bit.ly/amqp-model-explained) if you want
+to learn more about AMQP principles & concepts.
## Documentation: tutorials, guides & API reference ##
We believe that in order to be a library our users **really** love, we need to care about documentation as much as (or more)
code readability, API beauty and autotomated testing across 5 Ruby implementations on multiple operating systems. We do care
-about our documentation: **if you don't find your answer in documentation, we consider it a high severity bug** that you
+about our [documentation](http://bitly.com/amqp-gem-docs): **if you don't find your answer in documentation, we consider it a high severity bug** that you
should [file to us](http://github.com/ruby-amqp/amqp/issues). Or just complain to [@rubyamqp](https://twitter.com/rubyamqp) on Twitter.
### Tutorials ###
@@ -138,14 +143,17 @@
### Examples ###
You can find many examples (both real-world cases and simple demonstrations) under [examples directory](https://github.com/ruby-amqp/amqp/tree/master/examples) in the repository.
Note that those examples are written against version 0.8.0.rc1 and later. 0.6.x and 0.7.x may not support certain AMQP protocol or "DSL syntax" features.
+There is also a work-in-progress [Messaging Patterns and Use Cases With AMQP](http://bit.ly/amqp-gem-patterns) documentation guide.
+
### Documentation guides ###
-[Documentation guides](http://bit.ly/amqp-gem-docs) describe the library itself as well as AMQP usage scenarios, topics like routing, error handing & recovery, broker-specific extensions, TLS support, troubleshooting and so on.
+[Documentation guides](http://bit.ly/amqp-gem-docs) describe the library itself as well as AMQP concepts, usage scenarios, topics like working with exchanges and queues,
+error handing & recovery, broker-specific extensions, TLS support, troubleshooting and so on. Most of the documentation is in these guides.
### API reference ###
[API reference](http://bit.ly/mDm1JE) is up on [rubydoc.info](http://rubydoc.info) and is updated daily.
@@ -163,11 +171,11 @@
## Community
* Join [Ruby AMQP mailing list](http://groups.google.com/group/ruby-amqp)
* Follow [@rubyamqp](https://twitter.com/rubyamqp) on Twitter for Ruby AMQP ecosystem updates.
* Join also [RabbitMQ mailing list](https://lists.rabbitmq.com/cgi-bin/mailman/listinfo/rabbitmq-discuss) (AMQP community epicenter).
- * Stop by #rabbitmq on irc.freenode.net. You can use [Web IRC client](http://webchat.freenode.net?channels=rabbitmq) if you don't have an IRC client installed.
+ * Stop by #rabbitmq on irc.freenode.net. You can use [Web IRC client](http://webchat.freenode.net?channels=rabbitmq) if you don't have IRC client installed.
## Links ##
@@ -221,20 +229,22 @@
### So, does amqp gem only work with RabbitMQ? ###
This library is developed and tested primarily with [RabbitMQ](http://rabbitmq.com), although it should be compatible with any
server implementing the [AMQP 0.9.1 spec](http://bit.ly/hw2ELX). For AMQP 0.8 brokers, use amqp gem version 0.7.x.
-### Why isn't Ruby 1.8.7.-p249 supported? ###
+### Why isn't Ruby 1.8.7.-p249 supported? Will it be supported in the future? ###
-Because there is absolutely no way we can both make code like the following (pseudo-synchronous) work
+In order to make code like the following (pseudo-synchronous) work
conn = AMQP.connect
ch = AMQP::Channel.new(conn)
ex = ch.default_exchange
ex.publish(some_data)
-and not be affected by this [Ruby 1.8.7-p249-specific bug (super called outside of method)](http://bit.ly/iONBmH)
+and not be affected by this [Ruby 1.8.7-p249-specific bug (super called outside of method)](http://bit.ly/iONBmH), we need to
+avoid any inheritance for key amqp gem classes: Channel, Queue, Exchange. This will take a moderate refactoring effort, and
+is likely to happen in 0.8.0.RC15.
### How does amqp gem relate to amq-client gem, amq-protocol and libraries like bunny? ###
See [this page about AMQP gems family](https://github.com/ruby-amqp/amq-client/blob/master/README.textile)