amqp-boilerplate 0.0.3 → 0.0.4

data/.gitignore

@@ -4,6 +4,7 @@
 .bundle
 .rvmrc
 .yardoc
+bin/*
 doc/*
 Gemfile.lock
 pkg/*

data/CHANGELOG

@@ -1,3 +1,7 @@
+= version 0.0.4
+
+  * [ENHANCEMENT] Documentation
+
 = version 0.0.3
 
   * [FEATURE] Added amqp_exchange macro to Consumer for selecting the exchange

data/README.rdoc

@@ -1,7 +1,7 @@
 = amqp-boilerplate
 
 amqp-boilerplate is a set of helper classes and modules to be used with the
-Ruby amqp gem.
+{https://github.com/ruby-amqp/amqp Ruby amqp gem}.
 
 == Install
 
@@ -11,6 +11,24 @@ Ruby amqp gem.
 
 See {AMQP::Boilerplate.configure} for configuration options.
 
+=== Ruby on Rails
+
+Add a initializer +amqp.rb+ to your config/initializer folder with the following code:
+
+  Rails.configuration.threadsafe!
+
+  AMQP::Boilerplate.configure do |config|
+    config.logger = ::Rails.logger
+    config.consumer_paths += %W( #{Rails.root}/app/consumers )
+    config.connection_options = { :host => "localhost", :port => 5672, :vhost => Rails.env }
+  end
+
+  # Require all files that are no longer auto-loaded when Rails is in thread-safe mode
+  Dir[File.expand_path(File.join(Rails.root,'lib','**','*.rb'))].each {|f| require f}
+  Dir[File.expand_path(File.join(Rails.root,'app','producers','**','*.rb'))].each {|f| require f}
+
+  AMQP::Boilerplate.boot
+
 == Usage
 
 amqp-boilerplate provides the AMQP::Boilerplate::Producer module for creating

data/lib/amqp/boilerplate/consumer.rb

@@ -1,5 +1,12 @@
 module AMQP
   module Boilerplate
+    # Inherit from this class to turn a class into a potential consumer that can
+    # handle messages delivered to them by AMQP broker.
+    #
+    # You should call the macro {.amqp_queue} method and implement {#handle_message}.
+    #
+    # To specify subscription options you can call the optional macro {.amqp_subscription} method.
+    #
     # @example Basic consumer
     #   class MyConsumer < AMQP::Boilerplate::Consumer
     #     amqp_queue "hello.world"
@@ -8,6 +15,16 @@ module AMQP
     #       puts "Received message: #{payload}"
     #     end
     #   end
+    #
+    # @example Configuring subscription
+    #   class MyConsumer < AMQP::Boilerplate::Consumer
+    #     amqp_queue "queue.name.here", :durable => true
+    #     amqp_subscription :ack => true
+    #
+    #     def handle_message(payload, metadata)
+    #       puts "Received message: #{payload}"
+    #     end
+    #   end
     class Consumer
       class << self
         # Macro for selecting exchange to bind to
@@ -18,12 +35,20 @@ module AMQP
           @exchange_name = name
         end
 
+        # Macro that sets up the amqp_queue for a class.
+        #
+        # @param [String] name Queue name. If you want a server-named queue, you can omit the name.
+        # @param [Hash] options Options that will be passed as options to {http://rdoc.info/github/ruby-amqp/amqp/master/AMQP/Channel#queue-instance_method AMQP::Channel#queue}
+        # @return [void]
         def amqp_queue(name=AMQ::Protocol::EMPTY_STRING, options={})
           @queue_name = name
           @queue_options = options
           AMQP::Boilerplate.register_consumer(self)
         end
 
+        # Macro that subscribes to asynchronous message delivery.
+        # 
+        # @param [Hash] options Options that will be passed as options to {http://rdoc.info/github/ruby-amqp/amqp/master/AMQP/Queue#subscribe-instance_method AMQP::Queue#subscribe}
         def amqp_subscription(options={})
           @subscription_options = options
         end

data/lib/amqp/boilerplate/consumer_registry.rb

@@ -3,6 +3,11 @@ module AMQP
     module ConsumerRegistry
       attr_writer :consumer_paths
 
+      # Returns an array of paths which files are loaded when {AMQP::Boilerplate.boot} is called.
+      # You should define the consumer_paths when you configure +AMQP::Boilerplate+ and assign
+      # an array of paths pointing to the folder where your consumer files are located, to it. 
+      #
+      # @see AMQP::Boilerplate.configure
       def consumer_paths
         @consumer_paths ||= []
       end

data/lib/amqp/boilerplate/logging.rb

@@ -5,6 +5,10 @@ module AMQP
     module Logging
       attr_writer :logger
 
+      # Returns the logger used to write logging output to.
+      # You can define the logger when you configure +AMQP::Boilerplate+ if you want to use a different logger than the default Ruby Logger.
+      #
+      # @see AMQP::Boilerplate.configure
       def logger
         @logger ||= ::Logger.new(STDOUT)
       end

data/lib/amqp/boilerplate/producer.rb

@@ -3,6 +3,11 @@ module AMQP
     # Use this module to turn a class into a potential producer that can
     # deliver messages to an AMQP exchange.
     #
+    # You turn your class into a producer by extending the module
+    # and call the required macros {#amqp} and {#amqp_message} methods.
+    #
+    # To specify exchange options you can call the optional macro {#amqp_exchange} method.
+    #
     # @example Getting started
     #   class MyProducer
     #     extend AMQP::Boilerplate::Producer
@@ -30,7 +35,7 @@ module AMQP
     module Producer
       # Macro that sets up amqp for a class.
       #
-      # @param [Hash] opts Options that will be passed to +AMQP::Exchange#publish
+      # @param [Hash] opts Options that will be passed as options to {http://rdoc.info/github/ruby-amqp/amqp/master/AMQP/Exchange#publish-instance_method AMQP::Exchange#publish}
       # @return [void]
       def amqp(opts={})
         send :include, InstanceMethods
@@ -40,6 +45,8 @@ module AMQP
       # Configuration for the exchange to be used
       #
       # @param [Symbol] type Exchange type
+      #
+      #   There are 4 supported exchange types: direct, fanout, topic and headers. Exchange type determines how exchange processes and routes messages.
       # @param [String] name Exchange name
       # @param [Hash] opts a customizable set of options
       # @see AMQP::Exchange#initialize
@@ -55,6 +62,12 @@ module AMQP
       #
       # @param [Symbol] method_name Name of method that generates message
       # @return [void]
+      # @example
+      #   amqp_message :message
+      #
+      #   def message
+      #     "Look! I am a string that will be posted to the exchange."
+      #   end
       def amqp_message(method_name)
         @amqp_boilerplate_message = method_name
       end

data/lib/amqp/boilerplate/version.rb

@@ -1,5 +1,5 @@
 module AMQP
   module Boilerplate
-    VERSION = "0.0.3"
+    VERSION = "0.0.4"
   end
 end

data/lib/amqp/boilerplate.rb

@@ -41,7 +41,14 @@ module AMQP
       end
     end
 
-    # TODO Documentation!
+    # Configures AMQP::Boilerplate and yields AMQP::Boilerplate object to the block
+    #
+    # @example
+    #   AMQP::Boilerplate.configure do |config|
+    #     config.logger = ::Rails.logger
+    #     config.consumer_paths += %W( #{Rails.root}/app/consumers )
+    #     config.connection_options = { :host => "localhost", :port => 5672, :vhost => Rails.env }
+    #   end
     def self.configure
       yield self if block_given?
     end
@@ -50,6 +57,9 @@ module AMQP
       @connection_options
     end
 
+    # AMQP connection options (:host, :port, :username, :vhost, :password) that
+    # will be passed as connection_options to {http://rdoc.info/github/ruby-amqp/amqp/master/AMQP#connect-class_method AMQP#start}
+    # when starting an EventMachine event loop.
     def self.connection_options=(options)
       @connection_options = options
     end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: amqp-boilerplate
 version: !ruby/object:Gem::Version 
-  hash: 25
+  hash: 23
   prerelease: 
   segments: 
   - 0
   - 0
-  - 3
-  version: 0.0.3
+  - 4
+  version: 0.0.4
 platform: ruby
 authors: 
 - Patrick Baselier
@@ -21,8 +21,8 @@ default_executable:
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rake
-  type: :development
-  version_requirements: &id001 !ruby/object:Gem::Requirement 
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -32,12 +32,12 @@ dependencies:
         - 0
         - 9
         version: "0.9"
-  prerelease: false
-  requirement: *id001
+  type: :development
+  version_requirements: *id001
 - !ruby/object:Gem::Dependency 
   name: rspec
-  type: :development
-  version_requirements: &id002 !ruby/object:Gem::Requirement 
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -47,12 +47,12 @@ dependencies:
         - 2
         - 6
         version: "2.6"
-  prerelease: false
-  requirement: *id002
+  type: :development
+  version_requirements: *id002
 - !ruby/object:Gem::Dependency 
   name: yard
-  type: :development
-  version_requirements: &id003 !ruby/object:Gem::Requirement 
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -62,12 +62,12 @@ dependencies:
         - 0
         - 7
         version: "0.7"
-  prerelease: false
-  requirement: *id003
+  type: :development
+  version_requirements: *id003
 - !ruby/object:Gem::Dependency 
   name: amqp
-  type: :runtime
-  version_requirements: &id004 !ruby/object:Gem::Requirement 
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -77,8 +77,8 @@ dependencies:
         - 0
         - 8
         version: "0.8"
-  prerelease: false
-  requirement: *id004
+  type: :runtime
+  version_requirements: *id004
 description: Collection of modules that aid in setting up AMQP producers and consumers.
 email: 
 - patrick@kabisa.nl