Browse files

One more "Working With Exchanges" doc guide update

Corrects an embarassing issue with mandatory messages being named/explained as immediate.
  • Loading branch information...
1 parent d167e5f commit d4c7e98f899f61f9da1d6c584fbadd0b3586d748 @michaelklishin michaelklishin committed Jun 23, 2011
Showing with 58 additions and 15 deletions.
  1. +25 −15 docs/Exchanges.textile
  2. +33 −0 examples/routing/unroutable_mandatory_message_is_returned.rb
View
40 docs/Exchanges.textile
@@ -597,15 +597,11 @@ More detailed overview of pros and cons of each option can be found in a "blog p
Next sections of this guide will describe how those features can be used with the Ruby amqp gem.
-h3. Publishing messages as immediate. Returned messages.
+h3. Publishing messages as immediate.
When publishing messages, it is possible to use :immediate option to publish message as "immediate". When an immediate message cannot be
-routed to any queue (it can be that there are no bindings for the exchange or none of the bindings matches), it is returned to the
-producer. Producer then can handle that message, for example:
-
- * Store it for later redelivery in a persistent store like Redis or Riak
- * Publish it to a different destination
- * Log the event and discard the message
+delivered to any consumer (one or more queues the message was routed to have no active consumers), it is returned to the
+producer.
An example of {AMQP::Exchange#publish} being used to publish an immediate message:
@@ -615,6 +611,28 @@ exchange.publish("Message ##{i}", :immediate => true)
</code>
</pre>
+The following code example demonstrates a message that is published as immediate but cannot be immediately consumed (no consumers) and thus returned
+back to the producer:
+<script src="https://gist.github.com/1025700.js"></script>
+
+
+h3. Publishing messages as mandatory.
+
+When publishing messages, it is possible to use :mandatory option to publish message as "mandatory". When a mandatory message cannot be
+*routed* to any queue (for example, there are no bindings or none of the bindings match), it is returned to the producer.
+
+The following code example demonstrates a message that is published as mandatory but cannot be routed (no bindings) and thus returned
+back to the producer:
+<script src="https://gist.github.com/1041835.js"> </script>
+
+
+h3. Returned messages.
+
+When message is returned, the application that produced it then can handle that message, for example:
+
+ * Store it for later redelivery in a persistent store
+ * Publish it to a different destination
+ * Log the event and discard the message
Returned messages have information about the exchange they were published to. For convenience, amqp gem associates returned messages callbacks with {AMQP::Exchange}
instances. To handle returned messages, use {AMQP::Exchange#on_return}:
@@ -631,14 +649,6 @@ Returned message handler has access to AMQP method (basic.return) information, m
as is, without modifications, so application can store it for later redelivery.
-Full example:
-<script src="https://gist.github.com/1025700.js"></script>
-
-
-h3. Publishing messages as mandatory.
-
-TBD
-
h3. Sending one-off messages
View
33 examples/routing/unroutable_mandatory_message_is_returned.rb
@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "bundler"
+Bundler.setup
+
+$:.unshift(File.expand_path("../../../lib", __FILE__))
+
+require 'amqp'
+
+puts "=> Handling a returned unroutable message that was published as mandatory"
+puts
+
+AMQP.start(:host => '127.0.0.1') do |connection|
+ channel = AMQP.channel
+ channel.on_error { |ch, channel_close| EventMachine.stop; raise "channel error: #{channel_close.reply_text}" }
+
+ # this exchange has no bindings, so messages published to it cannot be routed.
+ exchange = channel.fanout("amqpgem.examples.fanout", :auto_delete => true)
+ exchange.on_return do |basic_return, metadata, payload|
+ puts "#{payload} was returned! reply_code = #{basic_return.reply_code}, reply_text = #{basic_return.reply_text}"
+ end
+
+ EventMachine.add_timer(0.3) {
+ 10.times do |i|
+ exchange.publish("Message ##{i}", :mandatory => true)
+ end
+ }
+
+ EventMachine.add_timer(2) {
+ connection.close { EventMachine.stop }
+ }
+end

0 comments on commit d4c7e98

Please sign in to comment.