a13g 0.1.0.beta3 → 0.1.0.beta4

data/lib/a13g/command.rb

@@ -0,0 +1,69 @@
+require 'rubygems'
+require 'daemons'
+require 'optparse'
+
+module A13g
+  class Command
+    ##
+    # Number of instances to create.
+    #
+    attr_accessor :worker_count
+    
+    def initialize(args) # :nodoc:
+      @options = { :quiet => true, :pid_dir => "#{A13g::Base.path.root}/tmp/pids" }
+      @worker_count = 1
+      @monitor = false
+      @args = OptionParser.new do |opts|
+        opts.banner = "Usage: script/messaging [options] start|stop|restart|run"
+        opts.on('-h', '--help', 'Show this message') { puts opts; exit 1 }
+        opts.on('-n', '--number_of_workers=workers', "Number of unique workers to spawn") {|worker_count| @worker_count = worker_count.to_i rescue 1 }
+        opts.on('--pid-dir=DIR', 'Specifies an alternate directory in which to store the process ids.') {|dir| @options[:pid_dir] = dir }
+        opts.on('-i', '--identifier=n', 'A numeric identifier for the worker.') {|n| @options[:identifier] = n }
+        opts.on('-m', '--monitor', 'Start monitor process.') { @monitor = true }
+      end.parse!(args)
+    end
+    
+    ##
+    # Runs A13g daemons. 
+    #
+    def daemonize!
+      dir = @options[:pid_dir]
+      Dir.mkdir(dir) unless File.exists?(dir)
+      
+      if @worker_count > 1 && @options[:identifier]
+        raise ArgumentError, 'Cannot specify both --number-of-workers and --identifier'
+      elsif @worker_count == 1 && @options[:identifier]
+        process_name = "messaging.#{@options[:identifier]}"
+        run_process(process_name, dir)
+      else
+        worker_count.times do |worker_index|
+          process_name = worker_count == 1 ? "messaging" : "messaging.#{worker_index}"
+          run_process(process_name, dir)
+        end
+      end
+    end
+    
+    protected
+    
+    ##
+    # Creates single daemonized process.
+    #
+    def run_process(process_name, dir)
+      Daemons.run_proc(process_name, :dir => dir, :dir_mode => :normal, :monitor => @monitor, :ARGV => @args) do |*args|
+        run process_name
+      end
+    end
+    
+    ##
+    # Runs single a13g worker.  
+    #
+    def run(worker_name = nil)
+      Dir.chdir(A13g::Base.path.root)
+      A13g::Listener.start!
+    #rescue => e
+    #  Rails.logger.fatal e
+    #  STDERR.puts e.message
+    #  exit 1
+    end
+  end
+end

data/lib/a13g/consumer.rb

@@ -0,0 +1,129 @@
+module A13g 
+  # Message consumers are classes where received messages are processed. You 
+  # can define there how message should be served. 
+  #
+  # === Subscribing and processing messages
+  #  
+  # Each consumer can subscribe only one destination (queue or topic). Because 
+  # of security reasons it's not possible to listen many destinations by single 
+  # consumer.  
+  #
+  #   class MyConsumer < A13g::Consumer
+  #     subscribe "/queue/MyQueue", :ack => :client      
+  #
+  #     def on_message(message)
+  #       if message.body == 'Abort me!'
+  #         abort!
+  #       else
+  #         print message.body
+  #         ack! message
+  #       end
+  #     end
+  #   end
+  #
+  # === Handling errors
+  #
+  # There is also opportunity to define own error handler. Usually it's defined  
+  # in ApplicationConsumer. 
+  #
+  #   class ApplicationConsumer < A13g::Consumer
+  #     def on_error(err)
+  #       raise err
+  #       logger.error err
+  #     end
+  #   end
+  #
+  # === Multiple connections
+  # 
+  # You can also select connection context in your consumer. Thanks to it
+  # each consumer can work with different server. 
+  #
+  #   A13g.setup(:first, :adapter => 'stomp', :host => 'first.host.com')
+  #   A13g.setup(:second, :adapter => 'stomp', :host => 'second.host.com')
+  #
+  #   class FirstConsumer < A13g::Consumer
+  #     context :first
+  #     # ...
+  #   end
+  #
+  #   class SecondConsumer < A13g::Consumer
+  #     context :second 
+  #     # ...
+  #   end
+  class Consumer < Base
+    include Singleton
+    include Producer
+    
+    # This destination will be subscribed by consumer
+    #
+    # @api public
+    cattr_reader :subscription
+    @@subscription = nil
+    
+    class << self
+      # Assigns specified destination to consumer. Destination can be assigned
+      # to consumer only once.
+      #
+      # @param [String] destination
+      #   destination name
+      # @param [Hash] headers
+      #   subscription headers
+      # @param [Array] args
+      #   additional arguments
+      #
+      # @api public  
+      def subscribe(destination, headers={}, *args)
+        unless @@subscription
+          @@subscription = Subscription.create(instance, destination, headers, connection, *args)
+        else
+          Subscription.all.delete(self.name)
+          @@subscription = nil
+          subscribe(destination, headers, *args)
+        end
+      end
+    end
+    
+    # This action should be implemented in your own processor. It will be 
+    # executed when subsriber will receive message. 
+    #
+    # @param [A13g::Message] message
+    #   received message
+    #
+    # @api public
+    def on_message(message)
+      raise NotImplementedError, "Implement the `on_message` method in your own consumer class"
+    end
+
+    # This action should be implemented in your own processor. It will be 
+    # executed when some exception will be caught while receiving message.
+    #
+    # @param [Exception, StandardError] err
+    #   catched error
+    #
+    # @api public
+    def on_error(err)
+      raise err
+    end
+    
+    # Processing message to `on_message` or `on_error`.
+    #
+    # @param [A13g::Message] message
+    #   received message
+    #
+    # @api public
+    def process!(message)
+      logger.info("#{self.class.name} is processing message #{message.id}")
+      on_message(message)  
+    rescue Object => err
+      begin 
+        on_error(err)
+      rescue AbortMessage => ex
+        raise ex
+      rescue IgnoreMessage => ex
+        raise ex
+      rescue Object => ex
+        logger.error("#{self.class.name}: error in `on_error`, will propagate no further: #{ex.message}")        
+      end
+    end
+  end
+end

data/lib/a13g/destination.rb

@@ -0,0 +1,22 @@
+module A13g
+  # It's recommended having a destination object to represent each subscribed
+  # destination. 
+  class Destination
+    attr_reader :name
+
+    # Constructor. 
+    #
+    # @param [String] name
+    #   name of destination
+    #
+    # @api public
+    def initialize(name)
+      @name = name
+    end
+
+    def to_s # :nodoc:
+      "<A13g::Destination @name='#{name}'>"
+    end
+    alias :inspect :to_s
+  end
+end

data/lib/a13g/errors.rb

@@ -0,0 +1,60 @@
+module A13g
+  # Generic a13g exception class.
+  MessagingError = Class.new(StandardError)
+  
+  # Raised when default connection context is not specified.
+  MissingDefaultContext = Class.new(MessagingError)
+  
+  # Raised when connection to the broker could not been established 
+  # (for example when <tt>connection=</tt> is given a nil object).
+  ConnectionNotEstablished = Class.new(MessagingError)
+  
+  # Raised when destination for message is not specified. 
+  NoDestinationError = Class.new(MessagingError)
+  
+  # Error raised when invalid adapter were specified in configuration.
+  AdapterNotSpecified = Class.new(ArgumentError)
+  
+  # Error raised when adapter wasn't found.
+  AdapterNotFound = Class.new(LoadError)
+  
+  # Error raised when configuration file wasn't found.
+  ConfigurationFileNotFound = Class.new(MessagingError)
+  
+  # Used to indicate that the processing for a thread shoud complete.
+  StopProcessing = Class.new(Interrupt)
+  
+  # Used to indicate that the processing on a message should cease, 
+  # and the message should be returned back to the broker as best it can be.
+  AbortMessage = Class.new(MessagingError)
+  
+  # Used when message should be ignored by dispatcher. 
+  IgnoreMessage = Class.new(MessagingError)
+  
+  # Raised when destination is defined in gateway more than once.
+  DestinationAlreadyDefined = Class.new(MessagingError)
+  
+  # Raised when destination specified for sending message wasn't subscribed. 
+  DestinationNotDefinedError = Class.new(ArgumentError)
+  
+  # Raised when destination is subscribed by more than one consumer.
+  class DestinationAlreadySubscribedError < MessagingError
+    def message
+      "More than one consumer can't subcribe the same destination"
+    end
+  end
+  
+  # Error raised when consumer has defined more than one subscription.
+  class TooManySubscriptionsError < MessagingError
+    def message
+      "Each consumer can subscribe only one destination"
+    end
+  end
+  
+  # Error raised when consumer has assigned more than one context.
+  class ContextAlreadyDefinedError < MessagingError
+    def message
+      "Each consumer can use only one connection context"
+    end
+  end
+end

data/lib/a13g/listener.rb

@@ -0,0 +1,190 @@
+module A13g
+  # Listener creates receiving loops for active connections. Receiving loops are 
+  # running in separated threads and dispatches all received messages to 
+  # related consumer.  
+  class Listener
+    include Singleton
+  
+    class << self
+      # @see A13g::Listener#start!
+      # @api public
+      def start!
+        instance.start!
+      end
+      
+      # @see @see A13g::Listener#stop!
+      # @api public
+      def stop!
+        instance.stop!
+      end
+    end
+    
+    attr_reader :logger
+    
+    # @api public
+    def initialize 
+      @logger = Base.logger
+      @dispatcher_mutex = Mutex.new
+      @connection_threads = {}
+      @running = true
+      @exiting = false
+    end
+    
+    # Starts message listerers with receiving loop for each active connection.
+    #
+    # @api public
+    def start!
+      logger.debug "Initializing subscriptions..."
+      Thread.new do 
+        Base.create_subscriptions
+        begin
+          Base.contexts.values.each do |context|
+            @connection_threads[context] = Thread.new do
+              receiving_loop(context.connection) if context.connection
+            end
+          end
+          prevent_clean_exit
+        rescue Interrupt
+          logger.error "\n<<Interrupt received>>"
+        rescue Object => ex
+          logger.error "#{ex.class.name}: #{ex.message}\n\t#{ex.backtrace.join("\n\t")}"
+          raise ex
+        ensure
+          logger.debug "Cleaning up..."
+          stop!
+        end
+      end
+    end
+    
+    # It cleaning up all active subscriptions and dispatching all received but 
+    # not processed messages. It's also closing all active connections with brokers. 
+    #
+    # @api public
+    def stop!
+      @running = false
+      dispatching = true
+      while dispatching
+        dispatching = false
+        @connection_threads.each do |name, thread|
+          if thread[:message] && thread[:connection]
+            dispatching = true
+            message = thread[:message]
+            connection = thread[:connection]
+            if thread.alive?
+              connection.logger.error "Waiting on thread `#{name}` to finish processing last message..."
+            else
+              connection.logger.error "Starting thread `#{name}` to finish processing last message..."
+              thread.exit
+              thread = Thread.start do
+                begin
+                  Thread.current[:connection] = connection
+                  Thread.current[:message] = message
+                  dispatch(message, connection)
+                ensure
+                  Thread.current[:message] = nil
+                  Thread.current[:connection] = nil
+                end
+              end
+            end
+          else
+            thread.raise StopProcessing if thread.alive?
+          end        
+        end
+      end
+      Base.teardown
+    end
+    
+    private
+    
+    # Protection for "clean" exit. This method makes sure, that all threads 
+    # have been completed.
+    #
+    # @api private
+    def prevent_clean_exit
+      trap('TERM') { raise Interrupt }
+      while @running
+        living = false
+        @connection_threads.each {|name, thread| living ||= thread.alive? }
+        @running = living
+        return logger.error("All threads have died...") unless @running
+        sleep 1
+      end
+    end
+    
+    # Receives messages from specified connection in loop, and it's sending 
+    # redirects received messages to dispatcher. 
+    #
+    # @param [A13g::Adapters::AbstracAdapter] connection
+    #   connection object
+    #
+    # @api private
+    def receiving_loop(connection)
+      Thread.current[:connection] = connection
+      while @running
+        begin 
+          Thread.current[:message] = nil
+          Thread.current[:message] = message = connection.receive
+        rescue StopProcessing
+          connection.logger.error "Processing Stopped in thread[#{name}]: receive interrupted, will process last message if already received"
+        rescue Object => ex
+          connection.logger.error "Exception from connection.receive in thread[#{name}]: #{ex.message}\n#{ex.backtrace.join("\n\t")}"
+        ensure
+          if message = Thread.current[:message]
+            Thread.current[:message] = nil
+            dispatch(message, connection)
+          end
+        end
+        Thread.pass
+      end
+      connection.logger.error "Receive loop terminated in thread[#{name}]"
+    end
+    
+    # It processes message in synchronized thread. If received message come 
+    # from queue/topic subscribed by one of consumers, then will be dispatched
+    # by proper one, otherwise message will be signed as unreceived.
+    # 
+    # @param [A13g::Message] message
+    #   received message
+    # @param [A13g::Adapters::AbstracAdapter] connection
+    #   connection object
+    #
+    # @api private
+    def dispatch(message, connection)
+      @dispatcher_mutex.synchronize do 
+        begin
+          case message.command
+          when 'ERROR'
+            connection.logger.error("<< (#{connection.url}#{message.destination.name}): ERROR #{message.headers['message']}")
+          when 'MESSAGE'
+            connection.logger.info("<< "+Utils.format_message("#{connection.url}#{message.destination.name}", message.body, message.headers))
+            abort, ignore, processed = false, false, false
+            if subscription = Subscription.find(message.destination.name, connection) 
+              begin 
+                processed = true
+                return subscription.consumer.process!(message)
+              rescue AbortMessage
+                abort = true
+                connection.logger.info(">> (#{connection.url}#{message.destination.name}): ABORT #{message.id}")
+                return connection.unreceive(message, subscription.headers)
+              rescue IgnoreMessage
+                ignore = true
+                connection.logger.info(">> (#{connection.url}#{message.destination.name}): IGNORE #{message.id}")
+                return
+              ensure
+                if !abort && !ignore && subscription.headers[:ack] == 'auto'
+                  message.ack!
+                end
+              end
+            end
+          else
+            connection.logger.error("<< (#{connection.url}#{message.destination.name}): Unknown message command: #{message.command}")
+          end
+        rescue Object => ex
+          connection.logger.error "Dispatch exception: #{ex}"
+          connection.logger.error ex.backtrace.join("\n\t")
+          raise ex
+        end
+      end
+    end
+  end
+end