qup 1.1.0

data/lib/qup/consumer.rb

@@ -0,0 +1,42 @@
+module Qup
+  # Public: Consumes items for a queue
+  #
+  # A Consumer is created from a Queue and consumes messages from the queue.
+  #
+  #
+  class Consumer
+    # Public: Create a new Consumer
+    #
+    # queue - the Queue this producer is for
+    #
+    # Returns a new Consumer
+    def initialize( queue )
+      @queue = queue
+    end
+
+    # Public: Consume a message for the queue
+    #
+    # Yields the message
+    #
+    # Most of the time you will want to call this message with a block as the
+    # Message will be auto-acknowledged. If you do not consume messages with a
+    # block, then you are required to acknowledge the messages on your own.
+    #
+    # Returns a Message
+    def consume(&block)
+      @queue.consume(&block)
+    end
+
+    # Public: Acknowledge a consumed message
+    #
+    # message - The message you are acknowledging
+    #
+    # A consumed message must be acknowledge so the back end system can
+    # be assured that the message has been a fully processed.
+    #
+    # Returns nothing.
+    def acknowledge( message )
+      @queue.acknowledge( message )
+    end
+  end
+end

data/lib/qup/message.rb

@@ -0,0 +1,18 @@
+module Qup
+  # Public: A Message is an item that may be put on and taken off the queue.
+  #
+  class Message
+
+    # Public: The unique identifier of this message
+    attr_reader :key
+
+    # Public: The data in this Message
+    attr_reader :data
+
+    # Public: Create a Message from the given data
+    def initialize( key, data )
+      @key  = key
+      @data = data
+    end
+  end
+end

data/lib/qup/producer.rb

@@ -0,0 +1,28 @@
+module Qup
+  # Public: Produces items for a queue
+  #
+  # Examples:
+  #
+  #   producer = queue.producer
+  #   producer.produce( my_message )
+  #
+  class Producer
+    # Public: Create a new Producer
+    #
+    # queue - the Queue this producer is for
+    #
+    # Returns a new Producer
+    def initialize( queue )
+      @queue = queue
+    end
+
+    # Public: Produce a message for the queue
+    #
+    # message - the Object to put onto the queue
+    #
+    # Returns nothing.
+    def produce( message )
+      @queue.produce( message )
+    end
+  end
+end

data/lib/qup/publisher.rb

@@ -0,0 +1,30 @@
+module Qup
+  # Public: A Publisher produces messages on a Topic
+  #
+  # Example:
+  #
+  #   pub = topic.publisher
+  #   pub.publish( my_message )
+  #
+  class Publisher
+
+    # Public: The Topic this Publisher publishes to.
+    attr_reader :topic
+
+    # Public: Create a new Publisher for a Topic
+    #
+    # Returns a Publisher
+    def initialize( topic )
+      @topic = topic
+    end
+
+    # Public: Publish a Message to all the Subscribers
+    #
+    # message - the Object to send to all Subscribers.
+    #
+    # Returns nothing
+    def publish( message )
+      @topic.publish( message )
+    end
+  end
+end

data/lib/qup/queue_api.rb

@@ -0,0 +1,124 @@
+require 'qup/producer'
+require 'qup/consumer'
+module Qup
+  #
+  # Public: A QueueAPI for use in a point-to-point messaging pattern.
+  #
+  # The Queue guarantees that each Message that is on the Queue is delivered and
+  # acknowledged only once.
+  #
+  # A very common pattern for Queue usage is a worker pattern where you have a
+  # Producer putting job Messages on the Queue and a collection of Consumers
+  # which work on those job Messages.
+  #
+  # This is the API that MUST be implemented in the adapter.
+  #
+  # Example:
+  #
+  #   session = Session.new( uri )
+  #   queue = session.queue( 'my_queue' )
+  #
+  #   queue.producer  # => Producer
+  #   queue.consumer  # => Consumer
+  #   queue.depth     # => 4
+  #
+  module QueueAPI
+
+    # Public: create a Producer for this Queue
+    #
+    # Returns a new Producer
+    def producer
+      Producer.new( self )
+    end
+
+    # Public: create a Consumer for this Queue
+    #
+    # Returns a new Consumer
+    def consumer
+      Consumer.new( self )
+    end
+
+
+    #--------------------------------------------------------------------------
+    # The API that Adapters must implement
+    #--------------------------------------------------------------------------
+
+    # Public: the name of the Queue
+    #
+    # Returns the String name
+    def name
+      super
+    rescue NoMethodError
+      raise NotImplementedError, "please implement 'name'"
+    end
+
+
+    # Public: return the number of Messages on the Queue
+    #
+    # Returns an integer of the Queue depth
+    def depth
+      raise NotImplementedError, "please implement 'depth'"
+    end
+
+
+    # Public: empty all the messages from the Queue, this does not consume them,
+    # this removes the from the Queue
+    #
+    # Returns nothing
+    def flush
+      raise NotImplementedError, "please implement 'flush'"
+    end
+
+
+    # Public: destroy the Queue if possible
+    #
+    # This will clear the Queue and remove it from the system if possible
+    #
+    # Returns nothing.
+    def destroy
+      super
+    rescue NoMethodError
+      raise NotImplementedError, "please implement 'destroy'"
+    end
+
+
+    # Internal: Put an item onto the Queue
+    #
+    # message - the data to put onto the queue
+    #
+    # A user of the Qup API should use a Producer instance to put items onto the
+    # queue.
+    #
+    # Returns the Message that was put onto the Queue
+    def produce( message )
+      raise NotImplementedError, "please implement 'produce'"
+    end
+
+
+    # Internal: Retrieve an item from the Queue
+    #
+    # options - a Hash of options determining how long to wait for a Message
+    #           :block   - should we block until a Message is available
+    #                      (default: true )
+    #           :timeout - how long to wait for a Message, only valid if
+    #                      :block is false
+    #
+    # A user of the Qup API should use a Consumer instance to retrieve items
+    # from the Queue.
+    #
+    # Returns a Message
+    def consume(&block)
+      raise NotImplementedError, "please implement 'consume'"
+    end
+
+
+    # Internal: Acknowledge that message is completed and remove it from the
+    # Queue.
+    #
+    # Returns nothing
+    def acknowledge( message )
+      raise NotImplementedError, "please implement 'acknowledge'"
+    end
+
+  end
+end

data/lib/qup/session.rb

@@ -0,0 +1,111 @@
+require 'uri'
+require 'pathname'
+module Qup
+  # Public: Manage communicating with a provider
+  #
+  # Examples:
+  #
+  #   Session.new( 'maildir:///tmp/qup' )
+  #   Session.new( 'kestrel://user:pass@host:port/' )
+  #
+  #   session.queue( 'foo' ) # => Queue
+  #   session.topic( 'bar' ) # => Topic
+  #
+  # At the moment, a Session is not considered thread safe, so each Thread should
+  # create its own Session.
+  class Session
+    class ClosedError < Qup::Error; end
+
+    # Public: The URI of this Session
+    attr_reader :uri
+
+    # Public: Create a new Session
+    #
+    # uri     - The connection String used to connect to appropriate provider
+    # options - The Hash of options that are passed to the underlying Adapter
+    #
+    # Yields the created Session
+    #
+    # If a session is yielded, it is closed at the end of the block
+    #
+    # Returns a new Session
+    def self.open( uri, options = {}, &block )
+      session = ::Qup::Session.new( uri, options )
+      return session unless block_given?
+      yield session
+    ensure
+      session.close if block_given?
+    end
+
+    # Public: Create a new Session
+    #
+    # uri     - The connection String used to connect to appropriate provider
+    # options - The Hash of options that are passed to the underlying Adapter
+    #
+    # Returns a new Session
+    def initialize( uri, options = {} )
+      @uri       = URI.parse( uri )
+      @root_path = Pathname.new( @uri.path )
+
+      adapter_klass = Qup::Adapters[@uri.scheme]
+      @adapter      = adapter_klass.new( @uri, options )
+
+      @queues  = Hash.new
+      @topics  = Hash.new
+    end
+
+    # Public: Allocate a new Queue
+    #
+    # Connect to an existing, or Create a new Queue with the given name and
+    # options.
+    #
+    # Yields the Queue.
+    #
+    # name    - The String name of the Queue to connect/create
+    #
+    # Returns a new Queue instance
+    def queue( name, &block )
+      destination( name, :queue, @queues, &block )
+    end
+
+    # Public: Allocate a new Topic
+    #
+    # Connect to an existing, or Create a new Topic with the given name and
+    # options.
+    #
+    # Yields the Topic.
+    #
+    # name    - The String name of the Topic to connect/create
+    #
+    # Returns a new Topic instance
+    def topic( name, &block )
+      destination( name, :topic, @topics, &block )
+    end
+
+    # Public: Close the Session
+    #
+    # Calling closed on an already closed Session does nothing.
+    #
+    # Returns nothing
+    def close
+      @adapter.close
+    end
+
+    # Public: Is the Session closed?
+    #
+    # Returns true if the session is closed, false otherwise.
+    def closed?
+      @adapter.closed?
+    end
+
+    #######
+    private
+    #######
+    def destination( name, type, collection, &block )
+      raise Qup::Session::ClosedError, "Session connected to #{@uri} is closed" if closed?
+      d = (collection[name] ||= @adapter.send( type, name ))
+      return d unless block_given?
+      yield d
+    end
+  end
+end

data/lib/qup/subscriber.rb

@@ -0,0 +1,28 @@
+module Qup
+  # Public: Receives Messages from a Topic
+  #
+  # All Subscribers to a Topic will receive each Message that is published to
+  # the Topic.
+  #
+  class Subscriber < Consumer
+    # Public: The name of this subscriber
+    attr_reader :name
+
+    # Public: Create a new Subscriber on a Topic
+    #
+    # Returns a Subscriber
+    def initialize( topic, queue )
+      super( queue )
+      @topic = topic
+      @name  = @queue.name
+    end
+
+    # Public: Remove the Subscriber from the Topic
+    #
+    # This just means to destroy the Queue that it is attached to
+    #
+    def unsubscribe
+      @queue.destroy
+    end
+  end
+end

data/lib/qup/topic_api.rb

@@ -0,0 +1,92 @@
+module Qup
+  #
+  # Public: A TopicAPI for use in a publish-subscribe Messaging
+  #
+  # The Topic delivers each Message that it is give to each and every Subscriber
+  #
+  # This API MUST be implemented in each Adapter
+  #
+  # Example:
+  #
+  #   session = Qup::Session.new( uri )
+  #   topic = session.topic( 'news' )
+  #
+  #   pub = topic.publisher
+  #
+  #   sub1 = topic.subscriber( 'sub1' )
+  #   sub2 = topic.subscriber( 'sub2' )
+  #
+  #   pub.publish( 'some news' )
+  #
+  #   message1 = sub1.consume
+  #   message2 = sub2.consume
+  #
+  module TopicAPI
+    #--------------------------------------------------------------------------
+    # The API that Adapters must implement
+    #--------------------------------------------------------------------------
+
+    # Public: Creates a Publisher for the Topic
+    #
+    # Returns a new Publisher
+    def publisher
+      raise NotImplementedError, "please implement 'publisher'"
+    end
+
+
+    # Public: Create a subscriber for the Topic
+    #
+    # name - the String name of the subscriber
+    #
+    # Creating a subscriber creates a new Subscriber that will receive a copy of
+    # every message that is published to the Topic.
+    #
+    # Subscribers are unique by name, two subscribers with the same name will
+    # act as individual Consumers on a queue of their name.
+    #
+    # Returns a Subscriber
+    def subscriber( name )
+      raise NotImplementedError, "please implement 'subscriber'"
+    end
+
+
+    # Public: the name of the Topic
+    #
+    # Returns the String name
+    def name
+      super
+    rescue NoMethodError
+      raise NotImplementedError, "please implement 'name'"
+    end
+
+
+    # Public: destroy the Topic if possible
+    #
+    # This will remove the Topic from the system if possible
+    #
+    # Returns nothing.
+    def destroy
+      super
+    rescue NoMethodError
+      raise NotImplementedError, "please implement 'destroy'"
+    end
+
+
+    # Public: Return the number of Subscribers to this Topic
+    #
+    # Returns integer
+    def subscriber_count
+      raise NotImplementedError, "please implement 'subscriber_count'"
+    end
+
+
+    # Internal: Publish a Message to all the Subscribers
+    #
+    # message - the Object to send to all subscribers
+    #
+    # Returns nothing
+    def publish( message )
+      raise NotImplementedError, "please implement 'publish'"
+    end
+  end
+end