hot_bunnies 2.0.0.pre8-java → 2.0.0.pre9-java

data/lib/hot_bunnies.rb

@@ -6,10 +6,17 @@ require 'ext/rabbitmq-client'
 
 require 'hot_bunnies/version'
 require 'hot_bunnies/exceptions'
+require 'hot_bunnies/thread_pools'
 require 'hot_bunnies/session'
 
+# HotBunnies is a JRuby client for RabbitMQ built on top of the official Java client.
+#
+# @see HotBunnies.connect
+# @see HotBunnies::Session
+# @see HotBunnies::Channel
 module HotBunnies
   # Delegates to {HotBunnies::Session.connect}
+  # @see HotBunnies::Session.connect
   def self.connect(*args)
     Session.connect(*args)
   end

data/lib/hot_bunnies/channel.rb

@@ -2,9 +2,121 @@
 require "hot_bunnies/shutdown_listener"
 
 module HotBunnies
+  # ## Channels in RabbitMQ
+  #
+  # To quote {http://www.rabbitmq.com/resources/specs/amqp0-9-1.pdf AMQP 0.9.1 specification}:
+  #
+  # AMQP 0.9.1 is a multi-channelled protocol. Channels provide a way to multiplex
+  # a heavyweight TCP/IP connection into several light weight connections.
+  # This makes the protocol more “firewall friendly” since port usage is predictable.
+  # It also means that traffic shaping and other network QoS features can be easily employed.
+  # Channels are independent of each other and can perform different functions simultaneously
+  # with other channels, the available bandwidth being shared between the concurrent activities.
+  #
+  #
+  # ## Opening Channels
+  #
+  # Channels can be opened either via `HotBunnies::Session#create_channel` (sufficient in the majority
+  # of cases) or by instantiating `HotBunnies::Channel` directly:
+  #
+  # @example Using {HotBunnies::Session#create_channel}:
+  #   conn = HotBunnies.new
+  #   conn.start
+  #
+  #   ch   = conn.create_channel
+  #
+  # This will automatically allocate a channel id.
+  #
+  # ## Closing Channels
+  #
+  # Channels are closed via {HotBunnies::Channel#close}. Channels that get a channel-level exception are
+  # closed, too. Closed channels can no longer be used. Attempts to use them will raise
+  # {HotBunnies::ChannelAlreadyClosed}.
+  #
+  # @example
+  #
+  #   ch  = conn.create_channel
+  #   ch.close
+  #
+  # ## Higher-level API
+  #
+  # HotBunnies offers two sets of methods on {HotBunnies::Channel}: known as higher-level and lower-level
+  # APIs, respectively. Higher-level API mimics {http://rubyamqp.info amqp gem} API where
+  # exchanges and queues are objects (instance of {HotBunnies::Exchange} and {HotBunnies::Queue}, respectively).
+  # Lower-level API is built around AMQP 0.9.1 methods (commands), where queues and exchanges are
+  # passed as strings (à la RabbitMQ Java client, {http://clojurerabbitmq.info Langohr} and Pika).
+  #
+  # ### Queue Operations In Higher-level API
+  #
+  # * {HotBunnies::Channel#queue} is used to declare queues. The rest of the API is in {HotBunnies::Queue}.
+  #
+  #
+  # ### Exchange Operations In Higher-level API
+  #
+  # * {HotBunnies::Channel#topic} declares a topic exchange. The rest of the API is in {HotBunnies::Exchange}.
+  # * {HotBunnies::Channel#direct} declares a direct exchange.
+  # * {HotBunnies::Channel#fanout} declares a fanout exchange.
+  # * {HotBunnies::Channel#headers} declares a headers exchange.
+  # * {HotBunnies::Channel#default_exchange}
+  # * {HotBunnies::Channel#exchange} is used to declare exchanges with type specified as a symbol or string.
+  #
+  #
+  # ## Channel Qos (Prefetch Level)
+  #
+  # It is possible to control how many messages at most a consumer will be given (before it acknowledges
+  # or rejects previously consumed ones). This setting is per channel and controlled via {HotBunnies::Channel#prefetch}.
+  #
+  #
+  # ## Channel IDs
+  #
+  # Channels are identified by their ids which are integers. HotBunnies takes care of allocating and
+  # releasing them as channels are opened and closed. It is almost never necessary to specify
+  # channel ids explicitly.
+  #
+  # There is a limit on the maximum number of channels per connection, usually 65536. Note
+  # that allocating channels is very cheap on both client and server so having tens, hundreds
+  # or even thousands of channels is possible.
+  #
+  # ## Channels and Error Handling
+  #
+  # Channel-level exceptions are more common than connection-level ones and often indicate
+  # issues applications can recover from (such as consuming from or trying to delete
+  # a queue that does not exist).
+  #
+  # With HotBunnies, channel-level exceptions are raised as Ruby exceptions, for example,
+  # {HotBunnies::NotFound}, that provide access to the underlying `channel.close` method
+  # information.
+  #
+  # @example Handling 404 NOT_FOUND
+  #   begin
+  #     ch.queue_delete("queue_that_should_not_exist#{rand}")
+  #   rescue HotBunnies::NotFound => e
+  #     puts "Channel-level exception! Code: #{e.channel_close.reply_code}, message: #{e.channel_close.reply_text}"
+  #   end
+  #
+  # @example Handling 406 PRECONDITION_FAILED
+  #   begin
+  #     ch2 = conn.create_channel
+  #     q   = "hotbunnies.examples.recovery.q#{rand}"
+  #
+  #     ch2.queue_declare(q, :durable => false)
+  #     ch2.queue_declare(q, :durable => true)
+  #   rescue HotBunnies::PreconditionFailed => e
+  #     puts "Channel-level exception! Code: #{e.channel_close.reply_code}, message: #{e.channel_close.reply_text}"
+  #   ensure
+  #     conn.create_channel.queue_delete(q)
+  #   end
+  #
+  # @see HotBunnies::Session#create_channel
+  # @see http://www.rabbitmq.com/tutorials/amqp-concepts.html AMQP 0.9.1 Model Concepts Guide
+  # @see http://hotbunnies.info/articles/getting_started.html Getting Started with RabbitMQ Using HotBunnies
+  # @see http://hotbunnies.info/articles/queues.html Queues and Consumers
+  # @see http://hotbunnies.info/articles/exchanges.html Exchanges and Publishing
   class Channel
-    attr_reader :session, :consumers
+    # @return [Array<HotBunnies::Consumer>] Consumers on this channel
+    attr_reader :consumers
 
+    # @private
     def initialize(session, delegate)
       @connection = session
       @delegate   = delegate
@@ -19,26 +131,41 @@ module HotBunnies
       end
     end
 
+    # @return [HotBunnies::Session] Connection this channel is on
     def client
       @connection
     end
 
+    # @return [HotBunnies::Session] Connection this channel is on
+    def session
+      @connection
+    end
+
+    # @return [HotBunnies::Session] Connection this channel is on
     def connection
       @connection
     end
 
+    # @return [Integer] Channel id
     def id
       @delegate.channel_number
     end
 
+    # @return [Integer] Channel id
     def number
       @delegate.channel_number
     end
 
+    # @return [Integer] Channel id
     def channel_number
       @delegate.channel_number
     end
 
+    # Closes the channel.
+    #
+    # Closed channels can no longer be used. Closed channel id is
+    # returned back to the pool of available ids and may be used by
+    # a different channel opened later.
     def close(code = 200, reason = "Goodbye")
       v = @delegate.close(code, reason)
 
@@ -60,40 +187,125 @@ module HotBunnies
 
     # @group Exchanges
 
+    # Declares a headers exchange or looks it up in the cache of previously
+    # declared exchanges.
+    #
+    # @param [String] name Exchange name
+    # @param [Hash] opts Exchange parameters
+    #
+    # @option options [String,Symbol] :type (:direct) Exchange type, e.g. :fanout or "x-consistent-hash"
+    # @option options [Boolean] :durable (false) Should the exchange be durable?
+    # @option options [Boolean] :auto_delete (false) Should the exchange be automatically deleted when no longer in use?
+    # @option options [Hash] :arguments ({}) Optional exchange arguments
+    #
+    # @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
     def exchange(name, options={})
       Exchange.new(self, name, options).tap do |x|
         x.declare!
       end
     end
 
+    # Declares a fanout exchange or looks it up in the cache of previously
+    # declared exchanges.
+    #
+    # @param [String] name Exchange name
+    # @param [Hash] opts Exchange parameters
+    #
+    # @option opts [Boolean] :durable (false) Should the exchange be durable?
+    # @option opts [Boolean] :auto_delete (false) Should the exchange be automatically deleted when no longer in use?
+    # @option opts [Hash] :arguments ({}) Optional exchange arguments (used by RabbitMQ extensions)
+    #
+    # @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 = {})
       Exchange.new(self, name, opts.merge(:type => "fanout")).tap do |x|
         x.declare!
       end
     end
 
+    # Declares a direct exchange or looks it up in the cache of previously
+    # declared exchanges.
+    #
+    # @param [String] name Exchange name
+    # @param [Hash] opts Exchange parameters
+    #
+    # @option opts [Boolean] :durable (false) Should the exchange be durable?
+    # @option opts [Boolean] :auto_delete (false) Should the exchange be automatically deleted when no longer in use?
+    # @option opts [Hash] :arguments ({}) Optional exchange arguments (used by RabbitMQ extensions)
+    #
+    # @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 = {})
       Exchange.new(self, name, opts.merge(:type => "direct")).tap do |x|
         x.declare!
       end
     end
 
+    # Declares a topic exchange or looks it up in the cache of previously
+    # declared exchanges.
+    #
+    # @param [String] name Exchange name
+    # @param [Hash] opts Exchange parameters
+    #
+    # @option opts [Boolean] :durable (false) Should the exchange be durable?
+    # @option opts [Boolean] :auto_delete (false) Should the exchange be automatically deleted when no longer in use?
+    # @option opts [Hash] :arguments ({}) Optional exchange arguments (used by RabbitMQ extensions)
+    #
+    # @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 = {})
       Exchange.new(self, name, opts.merge(:type => "topic")).tap do |x|
         x.declare!
       end
     end
 
+    # Declares a headers exchange or looks it up in the cache of previously
+    # declared exchanges.
+    #
+    # @param [String] name Exchange name
+    # @param [Hash] opts Exchange parameters
+    #
+    # @option opts [Boolean] :durable (false) Should the exchange be durable?
+    # @option opts [Boolean] :auto_delete (false) Should the exchange be automatically deleted when no longer in use?
+    # @option opts [Hash] :arguments ({}) Optional exchange arguments
+    #
+    # @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 = {})
       Exchange.new(self, name, opts.merge(:type => "headers")).tap do |x|
         x.declare!
       end
     end
 
+    # 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
 
+    # Declares a echange using echange.declare AMQP 0.9.1 method.
+    #
+    # @param [String] name Exchange name
+    # @param [Boolean] durable (false)     Should information about this echange be persisted to disk so that it
+    #                                            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.
+    #
+    # @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
@@ -103,42 +315,120 @@ module HotBunnies
 
     # @group Queues
 
+    # Declares a queue or looks it up in the per-channel cache.
+    #
+    # @param  [String] name  Queue name. Pass an empty string to declare a server-named queue (make RabbitMQ generate a unique name).
+    # @param  [Hash]   options  Queue properties and other options
+    #
+    # @option options [Boolean] :durable (false) Should this queue be durable?
+    # @option options [Boolean] :auto-delete (false) Should this queue be automatically deleted when the last consumer disconnects?
+    # @option options [Boolean] :exclusive (false) Should this queue be exclusive (only can be used by this connection, removed when the connection is closed)?
+    # @option options [Boolean] :arguments ({}) Additional optional arguments (typically used by RabbitMQ extensions and plugins)
+    #
+    # @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={})
       Queue.new(self, name, options).tap do |q|
         q.declare!
       end
     end
 
+    # Declares a queue using queue.declare AMQP 0.9.1 method.
+    #
+    # @param [String] name Queue name
+    #
+    # @param [Boolean] durable (false)     Should information about this queue be persisted to disk so that it
+    #                                      can survive broker restarts? Typically set to true for long-lived queues.
+    # @param [Boolean] auto_delete (false) Should this queue be deleted when the last consumer is cancelled?
+    # @param [Boolean] exclusive (false)   Should only this connection be able to use this queue?
+    #                                      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.
+    #
+    # @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)
       end
     end
 
+    # Checks if a queue exists using queue.declare AMQP 0.9.1 method.
+    # If it does not, a channel exception will be raised.
+    #
+    # @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)
       end
     end
 
+    # Deletes a queue using queue.delete AMQP 0.9.1 method
+    #
+    # @param [String] name Queue name
+    #
+    # @param [Boolean] if_empty (false) Should this queue be deleted only if it has no messages?
+    # @param [Boolean] if_unused (false) Should this queue be deleted only if it has no consumers?
+    #
+    # @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)
       end
     end
 
+    # Binds a queue to an exchange using queue.bind AMQP 0.9.1 method
+    #
+    # @param [String] name Queue name
+    # @param [String] exchange Exchange name
+    #
+    # @param [String] routing_key Routing key used for binding
+    # @param [Hash] arguments (nil) Optional arguments
+    #
+    # @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)
       end
     end
 
+    # Unbinds a queue from an exchange using queue.unbind AMQP 0.9.1 method
+    #
+    # @param [String] name Queue name
+    # @param [String] exchange Exchange name
+    #
+    # @param [String] routing_key Routing key used for binding
+    # @param [Hash] arguments ({}) Optional arguments
+    #
+    # @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)
       end
     end
 
+    # Purges a queue (removes all messages from it) using queue.purge AMQP 0.9.1 method.
+    #
+    # @param [String] name Queue name
+    #
+    # @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)
@@ -150,6 +440,30 @@ module HotBunnies
 
     # @group basic.*
 
+    # Publishes a message using basic.publish AMQP 0.9.1 method.
+    #
+    # @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.
+    # @option opts [Boolean] :mandatory Should the message be returned if it cannot be routed to any queue?
+    #
+    # @param [Hash] properties Message properties
+    #
+    # @option properties [Boolean] :persistent Should the message be persisted to disk?
+    # @option properties [Integer] :timestamp A timestamp associated with this message
+    # @option properties [Integer] :expiration Expiration time after which the message will be deleted
+    # @option properties [String] :type Message type, e.g. what type of event or command this message represents. Can be any string
+    # @option properties [String] :reply_to Queue name other apps should send the response to
+    # @option properties [String] :content_type Message content type (e.g. application/json)
+    # @option properties [String] :content_encoding Message content encoding (e.g. gzip)
+    # @option properties [String] :correlation_id Message correlated to this one, e.g. what request this message is a reply for
+    # @option properties [Integer] :priority Message priority, 0 to 9. Not used by RabbitMQ, only applications
+    # @option properties [String] :message_id Any message identifier
+    # @option properties [String] :user_id Optional user ID. Verified by RabbitMQ against the actual connection username
+    # @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)
@@ -181,10 +495,24 @@ module HotBunnies
       end
     end
 
+    # Sets how many messages will be given to consumers on this channel before they
+    # have to acknowledge or reject one of the previously consumed messages
+    #
+    # @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
 
+    # Acknowledges a message. Acknowledged messages are completely removed from the queue.
+    #
+    # @param [Integer] delivery_tag Delivery tag to acknowledge
+    # @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)
@@ -192,24 +520,120 @@ module HotBunnies
     end
     alias acknowledge ack
 
+    # Rejects a message. A rejected message can be requeued or
+    # dropped by RabbitMQ.
+    #
+    # @param [Integer] delivery_tag Delivery tag to reject
+    # @param [Boolean] requeue      Should this message be requeued instead of dropping it?
+    # @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)
       end
     end
 
+    # Rejects a message. A rejected message can be requeued or
+    # dropped by RabbitMQ. This method is similar to {Bunny::Channel#reject} but
+    # supports rejecting multiple messages at once, and is usually preferred.
+    #
+    # @param [Integer] delivery_tag Delivery tag to reject
+    # @param [Boolean] multiple (false) Should all unacknowledged messages up to this be rejected as well?
+    # @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)
       end
     end
 
+    # Rejects or requeues a message.
+    #
+    # @param [Integer] delivery_tag Delivery tag obtained from delivery info
+    # @param [Boolean] requeue Should the message be requeued?
+    # @return [NilClass] nil
+    #
+    # @example Requeue a message
+    #   conn  = Bunny.new
+    #   conn.start
+    #
+    #   ch    = conn.create_channel
+    #   q.subscribe do |delivery_info, properties, payload|
+    #     # requeue the message
+    #     ch.basic_reject(delivery_info.delivery_tag, true)
+    #   end
+    #
+    # @example Reject a message
+    #   conn  = Bunny.new
+    #   conn.start
+    #
+    #   ch    = conn.create_channel
+    #   q.subscribe do |delivery_info, properties, payload|
+    #     # requeue the message
+    #     ch.basic_reject(delivery_info.delivery_tag, false)
+    #   end
+    #
+    # @example Requeue a message fetched via basic.get
+    #   conn  = Bunny.new
+    #   conn.start
+    #
+    #   ch    = conn.create_channel
+    #   # we assume the queue exists and has messages
+    #   delivery_info, properties, payload = ch.basic_get("bunny.examples.queue3", :ack => true)
+    #   ch.basic_reject(delivery_info.delivery_tag, true)
+    #
+    # @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)
+      end
+    end
+
+    def basic_ack(delivery_tag, multiple)
+      converting_rjc_exceptions_to_ruby do
+        @delegate.basic_ack(delivery_tag, multiple)
+      end
+    end
+
+    # Rejects or requeues messages just like {Bunny::Channel#basic_reject} but can do so
+    # with multiple messages at once.
+    #
+    # @param [Integer] delivery_tag Delivery tag obtained from delivery info
+    # @param [Boolean] requeue Should the message be requeued?
+    # @param [Boolean] multiple Should all deliveries up to this one be rejected/requeued?
+    # @return [NilClass] nil
+    #
+    # @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)
+      end
+    end
+
+    # Redeliver unacknowledged messages
+    #
+    # @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)
       end
     end
 
+    # Redeliver unacknowledged messages
+    #
+    # @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)

data/lib/hot_bunnies/consumers.rb

@@ -1,209 +1,5 @@
-module HotBunnies
-  import com.rabbitmq.client.DefaultConsumer
+require "hot_bunnies/thread_pools"
 
-  class BaseConsumer < DefaultConsumer
-    attr_accessor :consumer_tag
-
-    def initialize(channel)
-      super(channel)
-      @channel    = channel
-
-      @cancelling = JavaConcurrent::AtomicBoolean.new
-      @cancelled  = JavaConcurrent::AtomicBoolean.new
-
-      @terminated = JavaConcurrent::AtomicBoolean.new
-    end
-
-    def handleDelivery(consumer_tag, envelope, properties, body)
-      body    = String.from_java_bytes(body)
-      headers = Headers.new(channel, consumer_tag, envelope, properties)
-
-      deliver(headers, body)
-    end
-
-    def handleCancel(consumer_tag)
-      @cancelled.set(true)
-      @channel.unregister_consumer(consumer_tag)
-
-      if f = @opts[:on_cancellation]
-        case f.arity
-        when 0 then
-          f.call
-        when 1 then
-          f.call(self)
-        when 2 then
-          f.call(@channel, self)
-        when 3 then
-          f.call(@channel, self, consumer_tag)
-        else
-          f.call(@channel, self, consumer_tag)
-        end
-      end
-
-      @terminated.set(true)
-    end
-
-    def handleCancelOk(consumer_tag)
-      @cancelled.set(true)
-      @channel.unregister_consumer(consumer_tag)
-
-      @terminated.set(true)
-    end
-
-    def start
-    end
-
-    def deliver(headers, message)
-      raise NotImplementedError, 'To be implemented by a subclass'
-    end
-
-    def cancel
-      @cancelling.set(true)
-      response = channel.basic_cancel(consumer_tag)
-      @cancelled.set(true)
-      @terminated.set(true)
-
-      response
-    end
-
-    def cancelled?
-      @cancelling.get || @cancelled.get
-    end
-
-    def active?
-      !terminated?
-    end
-
-    def terminated?
-      @terminated.get
-    end
-  end
-
-
-  class CallbackConsumer < BaseConsumer
-    def initialize(channel, callback)
-      raise ArgumentError, "callback must not be nil!" if callback.nil?
-
-      super(channel)
-      @callback = callback
-      @callback_arity = @callback.arity
-    end
-
-    def callback(headers, message)
-      if @callback_arity == 2
-        @callback.call(headers, message)
-      else
-        @callback.call(message)
-      end
-    end
-  end
-
-  class AsyncCallbackConsumer < CallbackConsumer
-    def initialize(channel, opts, callback, executor)
-      super(channel, callback)
-      @executor = executor
-      @executor_submit = executor.java_method(:submit, [JavaConcurrent::Runnable.java_class])
-      @opts = opts
-    end
-
-    def deliver(headers, message)
-      unless @executor.shutdown?
-        @executor_submit.call do
-          begin
-            callback(headers, message)
-          rescue Exception => e
-            $stderr.puts "Unhandled exception in consumer #{@consumer_tag}: #{e.message}"
-          end
-        end
-      end
-    end
-
-    def cancel
-      super
-
-      gracefully_shutdown
-    end
-
-    def handleCancel(consumer_tag)
-      super(consumer_tag)
-
-      gracefully_shutdown
-    end
-
-    def shutdown!
-      @executor.shutdown_now if @executor
-    end
-    alias shut_down! shutdown!
-
-    def gracefully_shut_down
-      unless @executor.await_termination(1, JavaConcurrent::TimeUnit::SECONDS)
-        @executor.shutdown_now
-      end
-      @terminated.set(true)
-    end
-    alias maybe_shut_down_executor gracefully_shut_down
-    alias gracefully_shutdown      gracefully_shut_down
-  end
-
-  class BlockingCallbackConsumer < CallbackConsumer
-    include JavaConcurrent
-
-    POISON = :__poison__
-
-    def initialize(channel, buffer_size, opts, callback)
-      super(channel, callback)
-      if buffer_size
-        @internal_queue = ArrayBlockingQueue.new(buffer_size)
-      else
-        @internal_queue = LinkedBlockingQueue.new
-      end
-
-      @opts = opts
-    end
-
-    def start
-      interrupted = false
-      until (@cancelling.get || @cancelled.get) || JavaConcurrent::Thread.current_thread.interrupted?
-        begin
-          pair = @internal_queue.take
-          if pair
-            if pair == POISON
-              @cancelling.set(true)
-            else
-              callback(*pair)
-            end
-          end
-        rescue InterruptedException => e
-          interrupted = true
-        end
-      end
-      while (pair = @internal_queue.poll)
-        callback(*pair)
-      end
-      @terminated.set(true)
-      if interrupted
-        JavaConcurrent::Thread.current_thread.interrupt
-      end
-    end
-
-    def deliver(*pair)
-      if (@cancelling.get || @cancelled.get) || JavaConcurrent::Thread.current_thread.interrupted?
-        @internal_queue.offer(pair)
-      else
-        begin
-          @internal_queue.put(pair)
-        rescue InterruptedException => e
-          JavaConcurrent::Thread.current_thread.interrupt
-        end
-      end
-    end
-
-    def gracefully_shut_down
-      @cancelling.set(true)
-      @internal_queue.offer(POISON)
-
-      @terminated.set(true)
-    end
-
-  end
-end
+require "hot_bunnies/consumers/base"
+require "hot_bunnies/consumers/non_blocking"
+require "hot_bunnies/consumers/blocking"

data/lib/hot_bunnies/consumers/base.rb

@@ -0,0 +1,72 @@
+module HotBunnies
+  import com.rabbitmq.client.DefaultConsumer
+
+  class BaseConsumer < DefaultConsumer
+    attr_accessor :consumer_tag
+
+    def initialize(channel)
+      super(channel)
+      @channel    = channel
+
+      @cancelling = JavaConcurrent::AtomicBoolean.new
+      @cancelled  = JavaConcurrent::AtomicBoolean.new
+
+      @terminated = JavaConcurrent::AtomicBoolean.new
+    end
+
+    def handleDelivery(consumer_tag, envelope, properties, body)
+      body    = String.from_java_bytes(body)
+      headers = Headers.new(channel, consumer_tag, envelope, properties)
+
+      deliver(headers, body)
+    end
+
+    def handleCancel(consumer_tag)
+      @cancelled.set(true)
+      @channel.unregister_consumer(consumer_tag)
+
+      if f = @opts[:on_cancellation]
+        case f.arity
+        when 0 then
+          f.call
+        when 1 then
+          f.call(self)
+        when 2 then
+          f.call(@channel, self)
+        when 3 then
+          f.call(@channel, self, consumer_tag)
+        else
+          f.call(@channel, self, consumer_tag)
+        end
+      end
+
+      @terminated.set(true)
+    end
+
+    def handleCancelOk(consumer_tag)
+      @cancelled.set(true)
+      @channel.unregister_consumer(consumer_tag)
+
+      @terminated.set(true)
+    end
+
+    def start
+    end
+
+    def deliver(headers, message)
+      raise NotImplementedError, 'To be implemented by a subclass'
+    end
+
+    def cancelled?
+      @cancelling.get || @cancelled.get
+    end
+
+    def active?
+      !terminated?
+    end
+
+    def terminated?
+      @terminated.get
+    end
+  end
+end

data/lib/hot_bunnies/consumers/blocking.rb

@@ -0,0 +1,82 @@
+require "hot_bunnies/consumers/base"
+
+module HotBunnies
+  class BlockingCallbackConsumer < CallbackConsumer
+    include JavaConcurrent
+
+    POISON = :__poison__
+
+    def initialize(channel, buffer_size, opts, callback)
+      super(channel, callback)
+      if buffer_size
+        @internal_queue = ArrayBlockingQueue.new(buffer_size)
+      else
+        @internal_queue = LinkedBlockingQueue.new
+      end
+
+      @opts = opts
+    end
+
+    def cancel
+      @cancelling.set(true)
+      response = channel.basic_cancel(consumer_tag)
+      @cancelled.set(true)
+
+      @internal_queue.offer(POISON)
+      @terminated.set(true)
+
+      response
+    end
+
+    def start
+      interrupted = false
+      until (@cancelling.get || @cancelled.get) || JavaConcurrent::Thread.current_thread.interrupted?
+        begin
+          pair = @internal_queue.take
+          if pair
+            if pair == POISON
+              @cancelling.set(true)
+            else
+              callback(*pair)
+            end
+          end
+        rescue InterruptedException => e
+          interrupted = true
+        end
+      end
+      while (pair = @internal_queue.poll)
+        if pair
+          if pair == POISON
+            @cancelling.set(true)
+          else
+            callback(*pair)
+          end
+        end
+      end
+      @terminated.set(true)
+      if interrupted
+        JavaConcurrent::Thread.current_thread.interrupt
+      end
+    end
+
+    def deliver(*pair)
+      if (@cancelling.get || @cancelled.get) || JavaConcurrent::Thread.current_thread.interrupted?
+        @internal_queue.offer(pair)
+      else
+        begin
+          @internal_queue.put(pair)
+        rescue InterruptedException => e
+          JavaConcurrent::Thread.current_thread.interrupt
+        end
+      end
+    end
+
+    def gracefully_shut_down
+      @cancelling.set(true)
+      @internal_queue.offer(POISON)
+
+      @terminated.set(true)
+    end
+
+  end
+end

data/lib/hot_bunnies/consumers/non_blocking.rb

@@ -0,0 +1,73 @@
+require "hot_bunnies/consumers/base"
+
+module HotBunnies
+  class CallbackConsumer < BaseConsumer
+    def initialize(channel, callback)
+      raise ArgumentError, "callback must not be nil!" if callback.nil?
+
+      super(channel)
+      @callback = callback
+      @callback_arity = @callback.arity
+    end
+
+    def callback(headers, message)
+      if @callback_arity == 2
+        @callback.call(headers, message)
+      else
+        @callback.call(message)
+      end
+    end
+  end
+
+  class AsyncCallbackConsumer < CallbackConsumer
+    def initialize(channel, opts, callback, executor)
+      super(channel, callback)
+      @executor = executor
+      @executor_submit = executor.java_method(:submit, [JavaConcurrent::Runnable.java_class])
+      @opts = opts
+    end
+
+    def deliver(headers, message)
+      unless @executor.shutdown?
+        @executor_submit.call do
+          begin
+            callback(headers, message)
+          rescue Exception => e
+            $stderr.puts "Unhandled exception in consumer #{@consumer_tag}: #{e.message}"
+          end
+        end
+      end
+    end
+
+    def cancel
+      @cancelling.set(true)
+      response = channel.basic_cancel(consumer_tag)
+      @cancelled.set(true)
+      @terminated.set(true)
+
+      gracefully_shutdown
+
+      response
+    end
+
+    def handleCancel(consumer_tag)
+      super(consumer_tag)
+
+      gracefully_shutdown
+    end
+
+    def shutdown!
+      @executor.shutdown_now if @executor
+    end
+    alias shut_down! shutdown!
+
+    def gracefully_shut_down
+      unless @executor.await_termination(1, JavaConcurrent::TimeUnit::SECONDS)
+        @executor.shutdown_now
+      end
+      @terminated.set(true)
+    end
+    alias maybe_shut_down_executor gracefully_shut_down
+    alias gracefully_shutdown      gracefully_shut_down
+  end
+end

data/lib/hot_bunnies/session.rb

@@ -6,6 +6,16 @@ module HotBunnies
   java_import com.rabbitmq.client.Connection
   java_import java.util.concurrent.ConcurrentHashMap
 
+  # Connection to a RabbitMQ node.
+  #
+  # Used to open and close connections and open (create) new channels.
+  #
+  # @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
 
     #
@@ -14,13 +24,26 @@ module HotBunnies
 
     # Connects to a RabbitMQ node.
     #
+    # @param [Hash] options Connection options
+    #
+    # @option options [String] :host ("127.0.0.1") Hostname or IP address to connect to
+    # @option options [Integer] :port (5672) Port RabbitMQ listens on
+    # @option options [String] :username ("guest") Username
+    # @option options [String] :password ("guest") Password
+    # @option options [String] :vhost ("/") Virtual host to use
+    # @option options [Integer] :heartbeat (600) Heartbeat interval. 0 means no heartbeat.
+    # @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
 
       cf.uri                = options[:uri]          if options[:uri]
       cf.host               = hostname_from(options) if include_host?(options)
-      cf.port               = options[:port]         if options[:port]
+      cf.port               = options[:port].to_i    if options[:port]
       cf.virtual_host       = vhost_from(options)    if include_vhost?(options)
       cf.connection_timeout = timeout_from(options)  if include_timeout?(options)
       cf.username           = username_from(options) if include_username?(options)
@@ -45,9 +68,13 @@ module HotBunnies
       new(cf)
     end
 
-    attr_reader :thread, :channels
+    # @private
+    attr_reader :thread
+    # @return [Array<HotBunnies::Channel>] Channels opened on this connection
+    attr_reader :channels
 
 
+    # @private
     def initialize(connection_factory)
       @cf         = connection_factory
       @connection = converting_rjc_exceptions_to_ruby do
@@ -58,6 +85,15 @@ module HotBunnies
       @thread     = Thread.current
     end
 
+    # Opens a new channel.
+    #
+    # @param [Integer] (nil): Channel number. Pass nil to let HotBunnies allocate an available number
+    #                         in a safe way.
+    #
+    # @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)
@@ -86,7 +122,7 @@ module HotBunnies
       sh
     end
 
-
+    # Flushes the socket used by this connection.
     def flush
       @connection.flush
     end
@@ -95,6 +131,7 @@ module HotBunnies
       @connection.heartbeat = n
     end
 
+    # No-op, exists for better API compatibility with Bunny.
     def start
       # no-op
       #
@@ -125,64 +162,79 @@ module HotBunnies
       @channels[ch.channel_number] = ch
     end
 
+    # @private
     def unregister_channel(ch)
       @channels.delete(ch.channel_number)
     end
 
     protected
 
+    # @private
     def self.hostname_from(options)
       options[:host] || options[:hostname] || ConnectionFactory.DEFAULT_HOST
     end
 
+    # @private
     def self.include_host?(options)
       !!(options[:host] || options[:hostname])
     end
 
+    # @private
     def self.vhost_from(options)
       options[:virtual_host] || options[:vhost] || ConnectionFactory.DEFAULT_VHOST
     end
 
+    # @private
     def self.include_vhost?(options)
       !!(options[:virtual_host] || options[:vhost])
     end
 
+    # @private
     def self.timeout_from(options)
       options[:connection_timeout] || options[:timeout]
     end
 
+    # @private
     def self.include_timeout?(options)
       !!(options[:connection_timeout] || options[:timeout])
     end
 
+    # @private
     def self.username_from(options)
       options[:username] || options[:user] || ConnectionFactory.DEFAULT_USER
     end
 
+    # @private
     def self.heartbeat_from(options)
       options[:heartbeat_interval] || options[:requested_heartbeat] || ConnectionFactory.DEFAULT_HEARTBEAT
     end
 
+    # @private
     def self.connection_timeout_from(options)
       options[:connection_timeout_interval] || options[:connection_timeout] || ConnectionFactory.DEFAULT_CONNECTION_TIMEOUT
     end
 
+    # @private
     def self.include_username?(options)
       !!(options[:username] || options[:user])
     end
 
+    # @private
     def self.password_from(options)
       options[:password] || options[:pass] || ConnectionFactory.DEFAULT_PASS
     end
 
+    # @private
     def self.include_password?(options)
       !!(options[:password] || options[:pass])
     end
 
+    # @private
     def self.include_heartbeat?(options)
       !!(options[:heartbeat_interval] || options[:requested_heartbeat] || options[:heartbeat])
     end
 
+    # @private
     def self.include_connection_timeout?(options)
       !!(options[:connection_timeout_interval] || options[:connection_timeout])
     end
@@ -203,6 +255,7 @@ module HotBunnies
       end
     end
 
+    # @private
     def new_connection
       converting_rjc_exceptions_to_ruby do
         @cf.new_connection

data/lib/hot_bunnies/thread_pools.rb

@@ -0,0 +1,32 @@
+module HotBunnies
+  import java.util.concurrent.Executors
+
+  # A slighly more Ruby developer-friendly way of instantiating various
+  # JDK executors (thread pools).
+  class ThreadPools
+    # Returns a new thread pool (JDK executor) of a fixed size.
+    #
+    # @return A thread pool (JDK executor)
+    def self.fixed_of_size(n)
+      raise ArgumentError.new("n must be a positive integer!") unless Integer === n
+      raise ArgumentError.new("n must be a positive integer!") unless n > 0
+
+      Executors.new_fixed_thread_pool(n)
+    end
+
+    # Returns a new thread pool (JDK executor) of a fixed size of 1.
+    #
+    # @return A thread pool (JDK executor)
+    def self.single_threaded
+      Executors.new_single_thread_executor
+    end
+
+    # Returns a new thread pool (JDK executor) that will create new
+    # threads as needed.
+    #
+    # @return A thread pool (JDK executor)
+    def self.dynamically_growing
+      Executors.new_cached_thread_pool
+    end
+  end
+end

data/lib/hot_bunnies/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hot_bunnies
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre8
+  version: 2.0.0.pre9
   prerelease: 6
 platform: java
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2013-07-04 00:00:00.000000000 Z
+date: 2013-07-11 00:00:00.000000000 Z
 dependencies: []
 description: RabbitMQ client for JRuby built around the official RabbitMQ Java client
 email:
@@ -24,6 +24,9 @@ files:
 - lib/hot_bunnies.rb
 - lib/hot_bunnies/channel.rb
 - lib/hot_bunnies/consumers.rb
+- lib/hot_bunnies/consumers/base.rb
+- lib/hot_bunnies/consumers/blocking.rb
+- lib/hot_bunnies/consumers/non_blocking.rb
 - lib/hot_bunnies/exceptions.rb
 - lib/hot_bunnies/exchange.rb
 - lib/hot_bunnies/juc.rb
@@ -31,6 +34,7 @@ files:
 - lib/hot_bunnies/queue.rb
 - lib/hot_bunnies/session.rb
 - lib/hot_bunnies/shutdown_listener.rb
+- lib/hot_bunnies/thread_pools.rb
 - lib/hot_bunnies/version.rb
 homepage: http://hotbunnies.info
 licenses: []