hot_bunnies 2.0.0.pre11-java → 2.0.0.pre12-java

data/lib/hot_bunnies.rb

@@ -21,6 +21,8 @@ module HotBunnies
     Session.connect(*args)
   end
 end
+
+# @see HotBunnies
 Hotbunnies = HotBunnies
 
 require 'hot_bunnies/channel'

data/lib/hot_bunnies/channel.rb

@@ -168,6 +168,9 @@ module HotBunnies
       v
     end
 
+    # Defines a shutdown event callback. Shutdown events are
+    # broadcasted when a channel is closed, either explicitly
+    # or forcefully, or due to a network/peer failure.
     def on_shutdown(&block)
       sh = ShutdownListener.new(self, &block)
 
@@ -207,7 +210,6 @@ module HotBunnies
     # Recovers basic.qos setting. Used by the Automatic Network Failure
     # Recovery feature.
     #
-    # @api plugin
     def recover_prefetch_setting
       basic_qos(@prefetch_count) if @prefetch_count
     end
@@ -215,7 +217,6 @@ module HotBunnies
     # Recovers exchanges. Used by the Automatic Network Failure
     # Recovery feature.
     #
-    # @api plugin
     def recover_exchanges
       @exchanges.values.each do |x|
         x.recover_from_network_failure
@@ -224,8 +225,6 @@ module HotBunnies
 
     # Recovers queues and bindings. Used by the Automatic Network Failure
     # Recovery feature.
-    #
-    # @api private
     def recover_queues
       @queues.values.each do |q|
         q.recover_from_network_failure
@@ -234,8 +233,6 @@ module HotBunnies
 
     # Recovers consumers. Used by the Automatic Network Failure
     # Recovery feature.
-    #
-    # @api private
     def recover_consumers
       @consumers.values.each do |c|
         self.unregister_consumer(c)
@@ -248,6 +245,8 @@ module HotBunnies
       @recoveries_counter.increment
     end
 
+    attr_reader :recoveries_counter
+
     # @group Exchanges
 
     # Declares a headers exchange or looks it up in the cache of previously
@@ -285,7 +284,6 @@ module HotBunnies
     # @return [HotBunnies::Exchange] Exchange instance
     # @see http://hotbunnies.info/articles/exchanges.html Exchanges and Publishing guide
     # @see http://hotbunnies.info/articles/extensions.html RabbitMQ Extensions to AMQP 0.9.1 guide
-    # @api public
     def fanout(name, opts = {})
       dx = Exchange.new(self, name, opts.merge(:type => "fanout")).tap do |x|
         x.declare!
@@ -307,7 +305,6 @@ module HotBunnies
     # @return [HotBunnies::Exchange] Exchange instance
     # @see http://hotbunnies.info/articles/exchanges.html Exchanges and Publishing guide
     # @see http://hotbunnies.info/articles/extensions.html RabbitMQ Extensions to AMQP 0.9.1 guide
-    # @api public
     def direct(name, opts = {})
       dx = Exchange.new(self, name, opts.merge(:type => "direct")).tap do |x|
         x.declare!
@@ -329,7 +326,6 @@ module HotBunnies
     # @return [HotBunnies::Exchange] Exchange instance
     # @see http://hotbunnies.info/articles/exchanges.html Exchanges and Publishing guide
     # @see http://hotbunnies.info/articles/extensions.html RabbitMQ Extensions to AMQP 0.9.1 guide
-    # @api public
     def topic(name, opts = {})
       dx = Exchange.new(self, name, opts.merge(:type => "topic")).tap do |x|
         x.declare!
@@ -351,7 +347,6 @@ module HotBunnies
     # @return [HotBunnies::Exchange] Exchange instance
     # @see http://hotbunnies.info/articles/exchanges.html Exchanges and Publishing guide
     # @see http://hotbunnies.info/articles/extensions.html RabbitMQ Extensions to AMQP 0.9.1 guide
-    # @api public
     def headers(name, opts = {})
       dx = Exchange.new(self, name, opts.merge(:type => "headers")).tap do |x|
         x.declare!
@@ -362,7 +357,6 @@ module HotBunnies
 
     # Provides access to the default exchange
     # @see http://hotbunnies.info/articles/exchanges.html Exchanges and Publishing guide
-    # @api public
     def default_exchange
       @default_exchange ||= self.exchange("", :durable => true, :auto_delete => false, :type => "direct")
     end
@@ -374,15 +368,22 @@ module HotBunnies
     #                                            can survive broker restarts? Typically set to true for long-lived exchanges.
     # @param [Boolean] auto_delete (false) Should this echange be deleted when it is no longer used?
     # @param [Boolean] passive (false)   If true, exchange will be checked for existence. If it does not
-    #                                          exist, {Bunny::NotFound} will be raised.
+    #                                          exist, {HotBunnies::NotFound} will be raised.
     #
     # @return RabbitMQ response
     # @see http://hotbunnies.info/articles/echanges.html Exchanges and Publishing guide
-    # @api public
     def exchange_declare(name, type, durable = false, auto_delete = false, arguments = nil)
       @delegate.exchange_declare(name, type, durable, auto_delete, arguments)
     end
 
+    def exchange_bind(destination, source, routing_key, arguments = nil)
+      @delegate.exchange_bind(destination, source, routing_key, arguments)
+    end
+
+    def exchange_unbind(destination, source, routing_key, arguments = nil)
+      @delegate.exchange_unbind(destination, source, routing_key, arguments)
+    end
+
     # @endgroup
 
 
@@ -401,7 +402,6 @@ module HotBunnies
     # @return [HotBunnies::Queue] Queue that was declared or looked up in the cache
     # @see http://hotbunnies.info/articles/queues.html Queues and Consumers guide
     # @see http://hotbunnies.info/articles/extensions.html RabbitMQ Extensions guide
-    # @api public
     def queue(name, options={})
       dq = Queue.new(self, name, @thread_pool, options).tap do |q|
         q.declare!
@@ -421,11 +421,10 @@ module HotBunnies
     #                                      If true, the queue will be automatically deleted when this
     #                                      connection is closed
     # @param [Boolean] passive (false)     If true, queue will be checked for existence. If it does not
-    #                                      exist, {Bunny::NotFound} will be raised.
+    #                                      exist, {HotBunnies::NotFound} will be raised.
     #
     # @return RabbitMQ response
     # @see http://hotbunnies.info/articles/queues.html Queues and Consumers guide
-    # @api public
     def queue_declare(name, durable, exclusive, auto_delete, arguments = {})
       converting_rjc_exceptions_to_ruby do
         @delegate.queue_declare(name, durable, exclusive, auto_delete, arguments)
@@ -438,7 +437,6 @@ module HotBunnies
     # @param [String] name Queue name
     #
     # @see http://hotbunnies.info/articles/queues.html Queues and Consumers guide
-    # @api public
     def queue_declare_passive(name)
       converting_rjc_exceptions_to_ruby do
         @delegate.queue_declare_passive(name)
@@ -454,7 +452,6 @@ module HotBunnies
     #
     # @return RabbitMQ response
     # @see http://hotbunnies.info/articles/queues.html Queues and Consumers guide
-    # @api public
     def queue_delete(name, if_empty = false, if_unused = false)
       converting_rjc_exceptions_to_ruby do
         @delegate.queue_delete(name, if_empty, if_unused)
@@ -472,7 +469,6 @@ module HotBunnies
     # @return RabbitMQ response
     # @see http://hotbunnies.info/articles/queues.html Queues and Consumers guide
     # @see http://hotbunnies.info/articles/bindings.html Bindings guide
-    # @api public
     def queue_bind(queue, exchange, routing_key, arguments = nil)
       converting_rjc_exceptions_to_ruby do
         @delegate.queue_bind(queue, exchange, routing_key, arguments)
@@ -490,7 +486,6 @@ module HotBunnies
     # @return RabbitMQ response
     # @see http://hotbunnies.info/articles/queues.html Queues and Consumers guide
     # @see http://hotbunnies.info/articles/bindings.html Bindings guide
-    # @api public
     def queue_unbind(queue, exchange, routing_key, arguments = nil)
       converting_rjc_exceptions_to_ruby do
         @delegate.queue_unbind(queue, exchange, routing_key, arguments)
@@ -503,7 +498,6 @@ module HotBunnies
     #
     # @return RabbitMQ response
     # @see http://hotbunnies.info/articles/queues.html Queues and Consumers guide
-    # @api public
     def queue_purge(name)
       converting_rjc_exceptions_to_ruby do
         @delegate.queue_purge(name)
@@ -519,7 +513,7 @@ module HotBunnies
     #
     # @param [String] exchange Exchange to publish to
     # @param [String] routing_key Routing key
-    # @param [String] body Message payload. It will never be modified by Bunny or RabbitMQ in any way.
+    # @param [String] body Message payload. It will never be modified by HotBunnies or RabbitMQ in any way.
     # @option opts [Boolean] :mandatory Should the message be returned if it cannot be routed to any queue?
     #
     # @param [Hash] properties Message properties
@@ -538,7 +532,6 @@ module HotBunnies
     # @option properties [String] :app_id Optional application ID
     #
     # @return [HotBunnies::Channel] Self
-    # @api public
     def basic_publish(exchange, routing_key, mandatory, properties, body)
       converting_rjc_exceptions_to_ruby do
         @delegate.basic_publish(exchange, routing_key, mandatory, false, BasicPropertiesBuilder.build_properties_from(properties || Hash.new), body)
@@ -583,7 +576,6 @@ module HotBunnies
     # @param [Integer] prefetch_count Prefetch (QoS setting) for this channel
     # @see http://hotbunnies.info/articles/exchanges.html Exchanges and Publishing guide
     # @see http://hotbunnies.info/articles/queues.html Queues and Consumers guide
-    # @api public
     def prefetch=(n)
       basic_qos(n)
     end
@@ -594,10 +586,9 @@ module HotBunnies
     # @param [Boolean] multiple (false) Should all unacknowledged messages up to this be acknowledged as well?
     # @see #nack
     # @see http://hotbunnies.info/articles/queues.html Queues and Consumers guide
-    # @api public
     def ack(delivery_tag, multiple = false)
-      converting_rjc_exceptions_to_ruby do
-        basic_ack(delivery_tag, multiple)
+      guarding_against_stale_delivery_tags(delivery_tag) do
+        basic_ack(delivery_tag.to_i, multiple)
       end
     end
     alias acknowledge ack
@@ -610,15 +601,14 @@ module HotBunnies
     # @see #ack
     # @see #nack
     # @see http://hotbunnies.info/articles/queues.html Queues and Consumers guide
-    # @api public
     def reject(delivery_tag, requeue = false)
-      converting_rjc_exceptions_to_ruby do
-        basic_reject(delivery_tag, requeue)
+      guarding_against_stale_delivery_tags(delivery_tag) do
+        basic_reject(delivery_tag.to_i, requeue)
       end
     end
 
     # Rejects a message. A rejected message can be requeued or
-    # dropped by RabbitMQ. This method is similar to {Bunny::Channel#reject} but
+    # dropped by RabbitMQ. This method is similar to {HotBunnies::Channel#reject} but
     # supports rejecting multiple messages at once, and is usually preferred.
     #
     # @param [Integer] delivery_tag Delivery tag to reject
@@ -626,10 +616,9 @@ module HotBunnies
     # @param [Boolean] requeue  (false) Should this message be requeued instead of dropping it?
     # @see #ack
     # @see http://hotbunnies.info/articles/queues.html Queues and Consumers guide
-    # @api public
     def nack(delivery_tag, multiple = false, requeue = false)
-      converting_rjc_exceptions_to_ruby do
-        basic_nack(delivery_tag, multiple, requeue)
+      guarding_against_stale_delivery_tags(delivery_tag) do
+        basic_nack(delivery_tag.to_i, multiple, requeue)
       end
     end
 
@@ -640,7 +629,7 @@ module HotBunnies
     # @return [NilClass] nil
     #
     # @example Requeue a message
-    #   conn  = Bunny.new
+    #   conn  = HotBunnies.new
     #   conn.start
     #
     #   ch    = conn.create_channel
@@ -650,7 +639,7 @@ module HotBunnies
     #   end
     #
     # @example Reject a message
-    #   conn  = Bunny.new
+    #   conn  = HotBunnies.new
     #   conn.start
     #
     #   ch    = conn.create_channel
@@ -660,7 +649,7 @@ module HotBunnies
     #   end
     #
     # @example Requeue a message fetched via basic.get
-    #   conn  = Bunny.new
+    #   conn  = HotBunnies.new
     #   conn.start
     #
     #   ch    = conn.create_channel
@@ -670,20 +659,26 @@ module HotBunnies
     #
     # @see #basic_nack
     # @see http://hotbunnies.info/articles/queues.html Queues and Consumers guide
-    # @api public
     def basic_reject(delivery_tag, requeue)
       converting_rjc_exceptions_to_ruby do
-        @delegate.basic_reject(delivery_tag, requeue)
+        @delegate.basic_reject(delivery_tag.to_i, requeue)
       end
     end
 
+    # Acknowledges one or more messages (deliveries).
+    #
+    # @param [Integer] delivery_tag Delivery tag obtained from delivery info
+    # @param [Boolean] multiple Should all deliveries up to this one be acknowledged?
+    # @return [NilClass] nil
+    #
+    # @see http://hotbunnies.info/articles/queues.html Queues and Consumers guide
     def basic_ack(delivery_tag, multiple)
       converting_rjc_exceptions_to_ruby do
-        @delegate.basic_ack(delivery_tag, multiple)
+        @delegate.basic_ack(delivery_tag.to_i, multiple)
       end
     end
 
-    # Rejects or requeues messages just like {Bunny::Channel#basic_reject} but can do so
+    # Rejects or requeues messages just like {HotBunnies::Channel#basic_reject} but can do so
     # with multiple messages at once.
     #
     # @param [Integer] delivery_tag Delivery tag obtained from delivery info
@@ -693,10 +688,9 @@ module HotBunnies
     #
     # @see http://hotbunnies.info/articles/queues.html Queues and Consumers guide
     # @see http://hotbunnies.info/articles/extensions.html RabbitMQ Extensions guide
-    # @api public
     def basic_nack(delivery_tag, multiple = false, requeue = false)
       converting_rjc_exceptions_to_ruby do
-        @delegate.basic_nack(delivery_tag, multiple, requeue)
+        @delegate.basic_nack(delivery_tag.to_i, multiple, requeue)
       end
     end
 
@@ -704,7 +698,6 @@ module HotBunnies
     #
     # @param [Boolean] requeue Should messages be requeued?
     # @return RabbitMQ response
-    # @api public
     def basic_recover(requeue = true)
       converting_rjc_exceptions_to_ruby do
         @delegate.basic_recover(requeue)
@@ -715,7 +708,6 @@ module HotBunnies
     #
     # @param [Boolean] requeue Should messages be requeued?
     # @return RabbitMQ response
-    # @api public
     def basic_recover_async(requeue = true)
       converting_rjc_exceptions_to_ruby do
         @delegate.basic_recover_async(requeue)
@@ -724,7 +716,11 @@ module HotBunnies
 
     # @endgroup
 
-
+    # Enables publisher confirms on the channel.
+    # @return [NilClass] nil
+    #
+    # @see http://hotbunnies.info/articles/exchanges.html Exchanges and Publishers guide
+    # @see http://hotbunnies.info/articles/extensions.html RabbitMQ Extensions guide
     def confirm_select
       converting_rjc_exceptions_to_ruby do
         @delegate.confirm_select
@@ -753,31 +749,37 @@ module HotBunnies
       @delegate.next_publisher_seq_no
     end
 
+    # Enables transactions on the channel
     def tx_select
       converting_rjc_exceptions_to_ruby do
         @delegate.tx_select
       end
     end
 
+    # Commits a transaction
     def tx_commit
       converting_rjc_exceptions_to_ruby do
         @delegate.tx_commit
       end
     end
 
+    # Rolls back a transaction
     def tx_rollback
       converting_rjc_exceptions_to_ruby do
         @delegate.tx_rollback
       end
     end
 
+    # Enables or disables channel flow. This feature id deprecated
+    # in RabbitMQ.
     def channel_flow(active)
       converting_rjc_exceptions_to_ruby do
         @delegate.channel_flow(active)
       end
     end
 
-
+    # Defines a returned message handler.
+    # @see http://hotbunnies.info/articles/exchanges.html Exchanges and Publishers guide
     def on_return(&block)
       self.add_return_listener(BlockReturnListener.from(block))
     end
@@ -791,6 +793,7 @@ module HotBunnies
     # Implementation
     #
 
+    # @private
     class BlockReturnListener
       include com.rabbitmq.client.ReturnListener
 
@@ -866,5 +869,21 @@ module HotBunnies
         Exceptions.convert_and_reraise(e)
       end
     end
+
+    # @private
+    def guarding_against_stale_delivery_tags(tag, &block)
+      case tag
+      # if a fixnum was passed, execute unconditionally. MK.
+      when Fixnum then
+        block.call
+        # versioned delivery tags should be checked to avoid
+        # sending out stale (invalid) tags after channel was reopened
+        # during network failure recovery. MK.
+      when VersionedDeliveryTag then
+        if !tag.stale?(@recoveries_counter.get)
+          block.call
+        end
+      end
+    end
   end
 end

data/lib/hot_bunnies/consumers/base.rb

@@ -1,3 +1,5 @@
+require "hot_bunnies/versioned_delivery_tag"
+
 module HotBunnies
   import com.rabbitmq.client.DefaultConsumer
 

data/lib/hot_bunnies/exchange.rb

@@ -3,8 +3,19 @@
 module HotBunnies
   import com.rabbitmq.client.AMQP
 
+  # Represents AMQP 0.9.1 exchanges.
+  #
+  # @see http://hotbunnies.info/articles/exchanges.html Exchanges and Publishing guide
+  # @see http://hotbunnies.info/articles/extensions.html RabbitMQ Extensions guide
   class Exchange
-    attr_reader :name, :channel
+    # @return [String] Exchange name
+    attr_reader :name
+    # @return [HotBunnies::Channel] Channel this exchange object uses
+    attr_reader :channel
+
+    # Type of this exchange (one of: :direct, :fanout, :topic, :headers).
+    # @return [Symbol]
+    attr_reader :type
 
     def initialize(channel, name, options = {})
       raise ArgumentError, "exchange channel cannot be nil" if channel.nil?
@@ -17,6 +28,29 @@ module HotBunnies
       @options = {:type => :fanout, :durable => false, :auto_delete => false, :internal => false, :passive => false}.merge(options)
     end
 
+    # Publishes a message
+    #
+    # @param [String] payload Message payload. It will never be modified by HotBunnies or RabbitMQ in any way.
+    # @param [Hash] opts Message properties (metadata) and delivery settings
+    #
+    # @option opts [String] :routing_key Routing key
+    # @option opts [Boolean] :persistent Should the message be persisted to disk?
+    # @option opts [Boolean] :mandatory Should the message be returned if it cannot be routed to any queue?
+    # @option opts [Integer] :timestamp A timestamp associated with this message
+    # @option opts [Integer] :expiration Expiration time after which the message will be deleted
+    # @option opts [String] :type Message type, e.g. what type of event or command this message represents. Can be any string
+    # @option opts [String] :reply_to Queue name other apps should send the response to
+    # @option opts [String] :content_type Message content type (e.g. application/json)
+    # @option opts [String] :content_encoding Message content encoding (e.g. gzip)
+    # @option opts [String] :correlation_id Message correlated to this one, e.g. what request this message is a reply for
+    # @option opts [Integer] :priority Message priority, 0 to 9. Not used by RabbitMQ, only applications
+    # @option opts [String] :message_id Any message identifier
+    # @option opts [String] :user_id Optional user ID. Verified by RabbitMQ against the actual connection username
+    # @option opts [String] :app_id Optional application ID
+    #
+    # @return [HotBunnies::Exchange] Self
+    # @see http://hotbunnies.info/articles/exchanges.html Exchanges and Publishing guide
+    # @api public
     def publish(body, opts = {})
       options = {:routing_key => '', :mandatory => false}.merge(opts)
       @channel.basic_publish(@name,
@@ -26,24 +60,78 @@ module HotBunnies
                              body.to_java_bytes)
     end
 
+    # Deletes the exchange unless it is predefined
+    #
+    # @param [Hash] options Options
+    #
+    # @option opts [Boolean] if_unused (false) Should this exchange be deleted only if it is no longer used
+    #
+    # @see http://hotbunnies.info/articles/exchanges.html Exchanges and Publishing guide
+    # @api public
     def delete(options={})
-      @channel.exchange_delete(@name, options.fetch(:if_unused, false))
+      @channel.deregister_exchange(self)
+      @channel.exchange_delete(@name, options.fetch(:if_unused, false)) unless predefined?
     end
 
+    # Binds an exchange to another (source) exchange using exchange.bind AMQP 0.9.1 extension
+    # that RabbitMQ provides.
+    #
+    # @param [String] exchange Source exchange name
+    # @param [Hash] options Options
+    #
+    # @option opts [String] routing_key (nil) Routing key used for binding
+    # @option opts [Hash] arguments ({}) Optional arguments
+    #
+    # @return [HotBunnies::Exchange] Self
+    # @see http://hotbunnies.info/articles/exchanges.html Exchanges and Publishing guide
+    # @see http://hotbunnies.info/articles/bindings.html Bindings guide
+    # @see http://hotbunnies.info/articles/extensions.html RabbitMQ Extensions guide
+    # @api public
     def bind(exchange, options={})
       exchange_name = if exchange.respond_to?(:name) then exchange.name else exchange.to_s end
       @channel.exchange_bind(@name, exchange_name, options.fetch(:routing_key, ''))
     end
 
+    # Unbinds an exchange from another (source) exchange using exchange.unbind AMQP 0.9.1 extension
+    # that RabbitMQ provides.
+    #
+    # @param [String] source Source exchange name
+    # @param [Hash] opts Options
+    #
+    # @option opts [String] routing_key (nil) Routing key used for binding
+    # @option opts [Hash] arguments ({}) Optional arguments
+    #
+    # @return [Bunny::Exchange] Self
+    # @see http://rubybunny.info/articles/exchanges.html Exchanges and Publishing guide
+    # @see http://rubybunny.info/articles/bindings.html Bindings guide
+    # @see http://rubybunny.info/articles/extensions.html RabbitMQ Extensions guide
+    # @api public
+    def unbind(exchange, opts = {})
+      exchange_name = if exchange.respond_to?(:name) then exchange.name else exchange.to_s end
+      @channel.exchange_unbind(@name, exchange_name, opts.fetch(:routing_key, ''), opts[:arguments])
+    end
+
+    # @return [Boolean] true if this exchange is a pre-defined one (amq.direct, amq.fanout, amq.match and so on)
     def predefined?
       @name.empty? || @name.start_with?("amq.")
     end
 
+    # Waits until all outstanding publisher confirms on the channel
+    # arrive.
+    #
+    # This is a convenience method that delegates to {Channel#wait_for_confirms}
+    #
+    # @api public
+    def wait_for_confirms
+      @channel.wait_for_confirms
+    end
+
+
     #
     # Implementation
     #
 
-    # @api private
+    # @private
     def declare!
       unless predefined?
         if @options[:passive]

data/lib/hot_bunnies/metadata.rb

@@ -19,7 +19,6 @@ module HotBunnies
 
     begin :envelope_delegation
       [
-        :delivery_tag,
         :routing_key,
         :redeliver,
         :exchange
@@ -30,6 +29,10 @@ module HotBunnies
       alias_method :redelivered?, :redeliver
     end
 
+    def delivery_tag
+      @delivery_tag ||= VersionedDeliveryTag.new(@envelope.delivery_tag, @channel.recoveries_counter.get)
+    end
+
     begin :message_properties_delegation
       [
         :content_encoding,

data/lib/hot_bunnies/queue.rb

@@ -28,7 +28,6 @@ module HotBunnies
     # @see HotBunnies::Channel#queue
     # @see http://hotbunnies.info/articles/queues.html Queues and Consumers guide
     # @see http://hotbunnies.info/articles/extensions.html RabbitMQ Extensions guide
-    # @api public
     def initialize(channel, name, thread_pool, options={})
       @channel = channel
       @name = name
@@ -46,35 +45,30 @@ module HotBunnies
 
 
     # @return [Boolean] true if this queue was declared as durable (will survive broker restart).
-    # @api public
     # @see http://hotbunnies.info/articles/queues.html Queues and Consumers guide
     def durable?
       @durable
     end # durable?
 
     # @return [Boolean] true if this queue was declared as exclusive (limited to just one consumer)
-    # @api public
     # @see http://hotbunnies.info/articles/queues.html Queues and Consumers guide
     def exclusive?
       @exclusive
     end # exclusive?
 
     # @return [Boolean] true if this queue was declared as automatically deleted (deleted as soon as last consumer unbinds).
-    # @api public
     # @see http://hotbunnies.info/articles/queues.html Queues and Consumers guide
     def auto_delete?
       @auto_delete
     end # auto_delete?
 
     # @return [Boolean] true if this queue was declared as server named.
-    # @api public
     # @see http://hotbunnies.info/articles/queues.html Queues and Consumers guide
     def server_named?
       @server_named
     end # server_named?
 
     # @return [Hash] Additional optional arguments (typically used by RabbitMQ extensions and plugins)
-    # @api public
     def arguments
       @arguments
     end
@@ -91,7 +85,6 @@ module HotBunnies
     #
     # @see http://hotbunnies.info/articles/queues.html Queues and Consumers guide
     # @see http://hotbunnies.info/articles/bindings.html Bindings guide
-    # @api public
     def bind(exchange, options={})
       exchange_name = if exchange.respond_to?(:name) then
                         exchange.name
@@ -118,7 +111,6 @@ module HotBunnies
     #
     # @see http://hotbunnies.info/articles/queues.html Queues and Consumers guide
     # @see http://hotbunnies.info/articles/bindings.html Bindings guide
-    # @api public
     def unbind(exchange, options={})
       exchange_name = if exchange.respond_to?(:name) then
                         exchange.name
@@ -139,11 +131,13 @@ module HotBunnies
     # @option [Boolean] if_empty (false) Should this queue be deleted only if it has no messages?
     #
     # @see http://hotbunnies.info/articles/queues.html Queues and Consumers guide
-    # @api public
     def delete(if_unused = false, if_empty = false)
       @channel.queue_delete(@name, if_unused, if_empty)
     end
 
+    # Purges a queue (removes all messages from it)
+    # @see http://hotbunnies.info/articles/queues.html Queues and Consumers guide
+    # @api public
     def purge
       @channel.queue_purge(@name)
     end
@@ -167,8 +161,21 @@ module HotBunnies
       end
     end
 
+    # Adds a consumer to the queue (subscribes for message deliveries).
+    #
+    # @param [Hash] opts Options
+    #
+    # @option opts [Boolean] :manual_ack (false) Will this consumer use manual acknowledgements?
+    # @option opts [Boolean] :exclusive (false) Should this consumer be exclusive for this queue?
+    # @option opts [Boolean] :block (false) Should the call block calling thread?
+    # @option opts [#call] :on_cancellation Block to execute when this consumer is cancelled remotely (e.g. via the RabbitMQ Management plugin)
+    # @option opts [String] :consumer_tag Unique consumer identifier. It is usually recommended to let HotBunnies generate it for you.
+    # @option opts [Hash] :arguments ({}) Additional (optional) arguments, typically used by RabbitMQ extensions
+    #
+    # @see http://hotbunnies.info/articles/queues.html Queues and Consumers guide
+    # @api public
     def subscribe(opts = {}, &block)
-      subscribe_with(build_consumer(opts, &block))
+      subscribe_with(build_consumer(opts, &block), opts)
     end
 
     def subscribe_with(consumer, opts = {})
@@ -182,23 +189,28 @@ module HotBunnies
       consumer
     end
 
+    # @return [Array<Integer>] A pair with information about the number of queue messages and consumers
+    # @see #message_count
+    # @see #consumer_count
     def status
       response = @channel.queue_declare_passive(@name)
       [response.message_count, response.consumer_count]
     end
 
+    # @return [Integer] How many messages the queue has ready (e.g. not delivered but not unacknowledged)
     def message_count
       response = @channel.queue_declare_passive(@name)
       response.message_count
     end
 
+    # @return [Integer] How many active consumers the queue has
     def consumer_count
       response = @channel.queue_declare_passive(@name)
       response.consumer_count
     end
 
     # Publishes a message to the queue via default exchange. Takes the same arguments
-    # as {Bunny::Exchange#publish}
+    # as {HotBunnies::Exchange#publish}
     #
     # @see HotBunnies::Exchange#publish
     # @see HotBunnies::Channel#default_exchange
@@ -213,6 +225,7 @@ module HotBunnies
     # Implementation
     #
 
+    # @private
     def declare!
       response = if @options[:passive]
                  then @channel.queue_declare_passive(@name)

data/lib/hot_bunnies/session.rb

@@ -13,7 +13,6 @@ module HotBunnies
   # @see .connect
   # @see #create_channel
   # @see #close
-  # @api public
   # @see http://hotbunnies.info/articles/getting_started.html Getting Started guide
   # @see http://hotbunnies.info/articles/connecting.html Connecting to RabbitMQ guide
   class Session
@@ -38,9 +37,6 @@ module HotBunnies
     # @option options [Boolean] :tls (false) Set to true to use TLS/SSL connection. This will switch port to 5671 by default.
     #
     # @see http://hotbunnies.info/articles/connecting.html Connecting to RabbitMQ guide
-    #
-    #
-    # @api public
     def self.connect(options={})
       cf = ConnectionFactory.new
 
@@ -107,7 +103,6 @@ module HotBunnies
     # @return [HotBunnies::Channel] Newly created channel
     # @see HotBunnies::Channel
     # @see http://hotbunnies.info/articles/getting_started.html Getting Started guide
-    # @api public
     def create_channel(n = nil)
       jc = if n
              @connection.create_channel(n)
@@ -121,6 +116,11 @@ module HotBunnies
       ch
     end
 
+    # Closes connection gracefully.
+    #
+    # This includes shutting down consumer work pool gracefully,
+    # waiting up to 5 seconds for all consumer deliveries to be
+    # processed.
     def close
       @channels.select { |_, ch| ch.open? }.each do |_, ch|
         ch.close
@@ -134,11 +134,15 @@ module HotBunnies
       @connection.close
     end
 
+    # @return [Boolean] true if connection is open, false otherwise
     def open?
       @connection.open?
     end
     alias connected? open?
 
+    # Defines a shutdown event callback. Shutdown events are
+    # broadcasted when a connection is closed, either explicitly
+    # or forcefully, or due to a network/peer failure.
     def on_shutdown(&block)
       sh = ShutdownListener.new(self, &block)
       @shutdown_hooks << sh
@@ -164,6 +168,8 @@ module HotBunnies
       @connetion.remove_shutdown_listener(@automatic_recovery_hook) if @automatic_recovery_hook
     end
 
+    # Begins automatic connection recovery (typically only used internally
+    # to recover from network failures)
     def automatically_recover
       # recovering immediately makes little sense. Wait a bit first. MK.
       java.lang.Thread.sleep(@network_recovery_interval * 1000)
@@ -191,6 +197,7 @@ module HotBunnies
       @connection.flush
     end
 
+    # @private
     def heartbeat=(n)
       @connection.heartbeat = n
     end
@@ -212,7 +219,6 @@ module HotBunnies
     end
 
     # @return [String]
-    # @api public
     def to_s
       "#<#{self.class.name}:#{object_id} #{@cf.username}@#{@cf.host}:#{@cf.port}, vhost=#{@cf.virtual_host}>"
     end
@@ -222,6 +228,7 @@ module HotBunnies
     # Implementation
     #
 
+    # @private
     def register_channel(ch)
       @channels[ch.channel_number] = ch
     end

data/lib/hot_bunnies/version.rb

@@ -1,5 +1,5 @@
 # encoding: utf-8
 
 module HotBunnies
-  VERSION = "2.0.0.pre11"
+  VERSION = "2.0.0.pre12"
 end

data/lib/hot_bunnies/versioned_delivery_tag.rb

@@ -0,0 +1,28 @@
+module HotBunnies
+  # Wraps a delivery tag (which is an integer) so that {Bunny::Channel} could
+  # detect stale tags after connection recovery.
+  #
+  # @private
+  class VersionedDeliveryTag
+    attr_reader :tag
+    attr_reader :version
+
+    def initialize(tag, version)
+      raise ArgumentError.new("tag cannot be nil") unless tag
+      raise ArgumentError.new("version cannot be nil") unless version
+
+      @tag     = tag
+      @version = version
+    end
+
+    def to_i
+      @tag
+    end
+
+    def stale?(version)
+      raise ArgumentError.new("version cannot be nil") unless version
+
+      @version < version
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hot_bunnies
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre11
+  version: 2.0.0.pre12
   prerelease: 6
 platform: java
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2013-08-20 00:00:00.000000000 Z
+date: 2013-08-27 00:00:00.000000000 Z
 dependencies: []
 description: RabbitMQ client for JRuby built around the official RabbitMQ Java client
 email:
@@ -35,6 +35,7 @@ files:
 - lib/hot_bunnies/shutdown_listener.rb
 - lib/hot_bunnies/thread_pools.rb
 - lib/hot_bunnies/version.rb
+- lib/hot_bunnies/versioned_delivery_tag.rb
 homepage: http://hotbunnies.info
 licenses: []
 post_install_message: