qup 1.1.0

data/lib/qup.rb

@@ -0,0 +1,48 @@
+module Qup
+  # The Current Version of the library
+  VERSION = '1.1.0'
+
+  class Error < StandardError; end
+
+  # Public: Create a new Session using the given provider URI
+  #
+  # uri - the String representing the provider to talk to
+  #
+  # Yields the created Session. When the block returns, the session is closed
+  #
+  # Examples
+  #
+  #   session = Qup.open( 'kestrel://localhost:22133' )
+  #   session = Qup.open( 'maildir:///tmp/qup' )
+  #
+  # Returns a Session.
+  def self.open( uri, &block )
+    Qup::Session.open( uri, &block )
+  end
+
+  KNOWN_ADAPTERS = {
+    # require => gem
+    'maildir' => 'maildir',
+    'kestrel' => 'kestrel-client',
+    'redis'   => 'redis'
+  }
+end
+
+require 'qup/adapter'
+require 'qup/consumer'
+require 'qup/message'
+require 'qup/producer'
+require 'qup/publisher'
+require 'qup/queue_api'
+require 'qup/session'
+require 'qup/subscriber'
+require 'qup/topic_api'
+
+# Load the known adapters, print a warning if $VERBOSE is set
+Qup::KNOWN_ADAPTERS.each do |adapter, gemname|
+  begin
+    require "qup/adapter/#{adapter}"
+  rescue LoadError
+    warn "Install the '#{gemname}' gem of you want to use the #{adapter} adapter" if $VERBOSE
+  end
+end

data/lib/qup/adapter.rb

@@ -0,0 +1,57 @@
+module Qup
+  # The list of registered Adapters
+  Adapters = Hash.new
+
+  #
+  # Public: The module that Qup Adapters must extend
+  #
+  # Any backing system that implements the Qup API must have an entry point that
+  # inherits from Adapter.
+  class Adapter
+
+    # Public: Register the child as an Adapter
+    #
+    # name - the name of the adapter. This will be the URI scheme value
+    #
+    # Return nothing
+    def self.register( name )
+      Adapters[name.to_s] ||= self
+    end
+
+
+    # Public: Create a Queue with the given name
+    #
+    # name - then name of the Queue to create
+    #
+    # Returns a Qup::QueueAPI compatible object
+    def queue( name )
+      raise NotImplementedError, "please implement 'queue'"
+    end
+
+
+    # Public: Create a Topic with the given name
+    #
+    # name - then name of the Topic to create
+    #
+    # Returns a Qup::TopicAPI compatible object
+    def topic( name )
+      raise NotImplementedError, "please implement 'topic'"
+    end
+
+
+    # Public: close the Adapter for further use
+    #
+    # Returns nothing
+    def close
+      raise NotImplementedError, "please implement 'close'"
+    end
+
+
+    # Public: is the Adapter closed
+    #
+    # Returns true or false
+    def closed?
+      raise NotImplementedError, "please implement 'closed?'"
+    end
+  end
+end

data/lib/qup/adapter/kestrel.rb

@@ -0,0 +1,56 @@
+require 'qup/adapter'
+require 'kestrel-client'
+
+class Qup::Adapter
+  # Internal: The backing adapter for Qup that uses Kestrel as the messaging
+  # infrastructure
+  class Kestrel < ::Qup::Adapter
+
+    # Register this adapter as :kestrel
+    register :kestrel
+
+    # Internal: Create a new Kestrel Adapter
+    #
+    # uri - the URI instance for this adapter to use
+    def initialize( uri, options = {} )
+      @uri        = uri
+      @addr       = "#{@uri.host}:#{@uri.port}"
+      @options    = options
+      @closed     = false
+    end
+
+    # Internal: Create a new Queue from this Adapter
+    #
+    # name - the String name of the Queue
+    #
+    # Returns a Qup::Queue
+    def queue( name )
+      Qup::Adapter::Kestrel::Queue.new( @addr, name )
+    end
+
+    # Internal: Create a new Topic from this Adapter
+    #
+    # name - the name of this Topic
+    #
+    # Returns a Qup::Topic
+    def topic( name )
+      Qup::Adapter::Kestrel::Topic.new( @addr, name )
+    end
+
+    # Internal: Close the Kestrel adapter
+    #
+    # Return nothing
+    def close
+      @closed = true
+    end
+
+    # Internal: Is the Kestrel Adapter closed
+    #
+    # Returns true or false
+    def closed?
+      @closed
+    end
+  end
+end
+require 'qup/adapter/kestrel/queue'
+require 'qup/adapter/kestrel/topic'

data/lib/qup/adapter/kestrel/destination.rb

@@ -0,0 +1,54 @@
+class Qup::Adapter::Kestrel
+  #
+  # Internal: The Common base class for Kestrel Topic and Queue
+  #
+  class Destination
+
+    # Internal: the name of the Queue or Topic
+    attr_reader :name
+
+    # Internal: Create a new Topic or Queue
+    #
+    # address - the Connection Address string for the Kestrel Client
+    # name    - the String name of the Topic
+    #
+    # Returns a new Topic.
+    def initialize( address, name )
+      @address      = address
+      @client       = blocking_transactional_client( @address )
+      @admin_client = regular_client( @address )
+      @name         = name
+      ping
+    end
+
+    # Internal: Destroy the Topic or Queue
+    #
+    # If possible remove the existence of the Topic from the System
+    #
+    # Returns nothing.
+    def destroy
+      @admin_client.delete( name )
+      @admin_client.delete( name+"_errors" )
+    end
+
+    # Internal: Make sure the Topic or Queue exists
+    #
+    # Returns nothing
+    def ping
+      @admin_client.peek( name )
+      return true
+    end
+
+    #######
+    private
+    #######
+
+    def regular_client( addr )
+      Kestrel::Client.new( addr )
+    end
+
+    def blocking_transactional_client( addr )
+      Kestrel::Client::Blocking.new( Kestrel::Client::Transactional.new( regular_client(addr) ) )
+    end
+  end
+end

data/lib/qup/adapter/kestrel/queue.rb

@@ -0,0 +1,101 @@
+require 'qup/adapter/kestrel/destination'
+
+class Qup::Adapter::Kestrel
+  #
+  # Internal: The Implementation of Queue in the Kestrel Adapter
+  #
+  class Queue < Destination
+    include Qup::QueueAPI
+
+    # Internal: Create a new Queue
+    #
+    # address - the Connection Address string for the Kestrel Client
+    # name    - the String name of the Topic
+    #
+    # Returns a new Queue
+    def initialize( address, name )
+      super(address, name)
+      @open_messages = {}
+    end
+
+    # Internal: The name of the Queue
+    attr_reader :name
+
+    # Internal: Remove all messages from the Queue
+    #
+    # Returns nothing.
+    def flush
+      @admin_client.flush(@name)
+    end
+
+
+    # Internal: return the number of Messages on the Queue
+    #
+    # Returns an integer of the Queue depth
+    def depth
+      stats = @admin_client.stat( @name )
+      return stats['items']
+    end
+
+
+    # Internal: Put an item onto the Queue
+    #
+    # message - the data to put onto the queue.
+    #
+    # The 'message' that is passed in is wrapped in a Qup::Message before being
+    # stored.
+    #
+    # 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 )
+      @client.set( @name, message )
+      return ::Qup::Message.new( message.object_id, message )
+    end
+
+
+    # Internal: Retrieve a Message from the Queue
+    #
+    # Yields a Message
+    #
+    # A user of the Qup API should use a Consumer instance to retrieve items
+    # from the Queue.
+    #
+    # Returns a Message
+    def consume(&block)
+      data = @client.get( @name )
+      q_message = ::Qup::Message.new( data.object_id, data )
+      @open_messages[q_message.key] = q_message
+      if block_given? then
+        yield_message( q_message, &block )
+      else
+        return q_message
+      end
+    end
+
+
+    # Internal: Acknowledge that message is completed and remove it from the
+    # Queue.
+    #
+    # For Kestrel, this really just closes the last message, the message that is
+    # sent in does not matter.
+    #
+    # Returns nothing
+    def acknowledge( message )
+      open_msg = @open_messages.delete( message.key )
+      raise Qup::Error, "Message #{message.key} is not currently being consumed" unless open_msg
+      @client.close_last_transaction
+    end
+
+    #######
+    private
+    #######
+
+    def yield_message( message, &block )
+      yield message
+    ensure
+      acknowledge( message )
+    end
+  end
+end

data/lib/qup/adapter/kestrel/topic.rb

@@ -0,0 +1,68 @@
+require 'qup/adapter/kestrel/destination'
+class Qup::Adapter::Kestrel
+  #
+  # Internal: The Topic implementation for the Kestrel Adapter
+  #
+  # The topic delivers each Message that it is give to each and every Subscriber
+  #
+  class Topic < Destination
+    include Qup::TopicAPI
+
+    # Internal : Creates a Publisher for the Topic
+    #
+    # Returns a new Publisher
+    def publisher
+      ::Qup::Publisher.new( self )
+    end
+
+    # Internal: 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 )
+      ::Qup::Subscriber.new( self, subscriber_queue( name ) )
+    end
+
+
+    # Internal: Return the number of Subscribers to this Topic
+    #
+    # Returns integer
+    def subscriber_count
+      c = 0
+      @client.stats['queues'].keys.each do |k|
+        next if k =~ /errors$/
+        c += 1 if k =~ /^#{@name}\+/
+      end
+      return c
+    end
+
+    # Internal: Publish a Message to all the Subscribers
+    #
+    # message - the Object to send to all subscribers
+    #
+    # Returns nothing
+    def publish( message )
+      @client.set( @name, message )
+    end
+
+    #######
+    private
+    #######
+
+    def subscriber_queue( sub_name )
+      sname = subscriber_queue_name( sub_name )
+      ::Qup::Adapter::Kestrel::Queue.new( @address, sname )
+    end
+
+    def subscriber_queue_name( sub_name )
+      "#{@name}+#{sub_name}"
+    end
+  end
+end

data/lib/qup/adapter/maildir.rb

@@ -0,0 +1,57 @@
+require 'qup/adapter'
+require 'maildir'
+
+class Qup::Adapter
+  # Internal: The backing adapter for Qup that uses Maildir as the messaging
+  # infrastructure
+  class Maildir < ::Qup::Adapter
+
+    # Register this adapter as :maildir
+    register :maildir
+
+    # Internal: Create a new Maildir Adapter
+    #
+    # uri - the URI instance for this adapter to use
+    def initialize( uri, options = {} )
+      @uri       = uri
+      @options   = options
+      @root_path = uri.path
+      @closed    = false
+    end
+
+    # Internal: Create a new Queue from this Adapter
+    #
+    # name - the String name of the Queue
+    #
+    # Returns a Qup::Queue
+    def queue( name )
+      Qup::Adapter::Maildir::Queue.new( @root_path, name )
+    end
+
+    # Internal: Create a new Topic from this Adapter
+    #
+    # name - the name of this Topic
+    #
+    # Returns a Qup::Topic
+    def topic( name )
+      Qup::Adapter::Maildir::Topic.new( @root_path, name )
+    end
+
+    # Internal: Close the Maildir adapter
+    #
+    # Return nothing
+    def close
+      @closed = true
+    end
+
+    # Internal: Is the Maildir Adapter closed
+    #
+    # Returns true or false
+    def closed?
+      @closed
+    end
+  end
+end
+
+require 'qup/adapter/maildir/queue'
+require 'qup/adapter/maildir/topic'