stomper 1.0.0 → 2.0.0

data/lib/stomper/subscription.rb

@@ -1,128 +0,0 @@
-module Stomper
-  # A representation of a subscription to a stomp broker destination.  The
-  # attributes +id+, +destination+, +ack+ and +selector+ have the same
-  # semantic meaning as the headers of a Stomp "SUBSCRIBE" frame with the same
-  # name.
-  class Subscription
-    attr_reader :id, :destination, :ack, :selector
-
-    # Creates a new Subscription instance from the given parameters.
-    # The +destination_or_options+ parameter can either be a string
-    # specification of the destination, such as "/queue/target", or a hash
-    # corresponding to the headers of a "SUBSCRIBE" frame
-    # (eg: { :destination => "/queue/target", :id => "sub-001", ... })
-    #
-    # The optional +subscription_id+ parameter is a string corresponding
-    # to the name of this subscription.  If this parameter is specified, it
-    # should be unique within the context of a given Stomper::Client, otherwise
-    # the behavior of the Stomper::Client#unsubscribe method may have unintended
-    # consequences.
-    #
-    # The optional +ack+ parameter specifies the mode that a client
-    # will use to acknowledge received messages and may be either :client or :auto.
-    # The default, :auto, does not require the client to notify the broker when
-    # it has received a message; however, setting +ack+ to :client will require
-    # each message received by this subscription to be acknowledged through the
-    # use of Stomper::Client#ack in order to ensure proper interaction between
-    # client and broker.
-    #
-    # The +selector+ parameter (again, optional) sets a SQL 92 selector for
-    # this subscription with the stomp broker as per the Stomp Protocol specification.
-    # Support of this functionality is entirely the responsibility of the broker,
-    # there is no client side filtering being done on incoming messages.
-    #
-    # When a message is "received" by an instance of Subscription, the supplied
-    # +block+ is inovked with the received message sent as a parameter.
-    #
-    # If no +subscription_id+ is specified, either explicitly or through a
-    # hash key of 'id' in +destination_or_options+, one may be automatically
-    # generated of the form +sub-<Time.now.to_f>+.  The automatic generation
-    # of a subscription id occurs if and only if naive? returns false.
-    #
-    # While direct creation of Subscription instances is possible, the preferred
-    # method is for them to be constructed by a Stomper::Client through the use
-    # of the Stomper::Client#subscribe method.
-    #
-    # @see naive?
-    # @see Subscriber#subscribe
-    # @see Subscriber#unsubscribe
-    # @see Client#ack
-    def initialize(destination_or_options, subscription_id=nil, ack=nil, selector=nil, &block)
-      if destination_or_options.is_a?(Hash)
-        destination = destination_or_options[:destination]
-        subscription_id ||= destination_or_options[:id]
-        ack ||= destination_or_options[:ack]
-        selector ||= destination_or_options[:selector]
-      else
-        destination = destination_or_options.to_s
-      end
-      @id = subscription_id
-      @destination = destination
-      @ack = (ack || :auto).to_sym
-      @selector = selector
-      @call_back = block
-      @id ||= "sub-#{Time.now.to_f}" unless naive?
-    end
-
-    # Returns true if this subscription has no explicitly specified id,
-    # has no selector specified, and acknowledges messages through the :auto
-    # mode.
-    def naive?
-      @id.nil? && @selector.nil? && @ack == :auto
-    end
-
-    # Returns true if this subscription is responsible for a Stomper::Client
-    # instance receiving +message_frame+.
-    #
-    # See also: receives_for?, perform
-    def accepts?(message_frame)
-      receives_for?(message_frame.destination, message_frame.subscription)
-    end
-
-    # Returns true if this subscription is responsible for receiving
-    # messages for the given destination or subscription id, specified
-    # by +dest+ and +subid+ respectively.
-    #
-    # Note: if +subid+ is non-nil or this subscription is not naive?,
-    # then this method returns true if and only if the supplied +subid+ is
-    # equal to the +id+ of this subscription.  Otherwise, the return value
-    # depends only upon the equality of +dest+ and this subscriptions +destination+
-    # attribute.
-    #
-    # See also: naive?
-    def receives_for?(dest, subid=nil)
-      if naive? && subid.nil?
-        @destination == dest
-      else
-        @id == subid
-      end
-    end
-
-    # Invokes the block associated with this subscription if
-    # this subscription accepts the supplied +message_frame+.
-    #
-    # See also: accepts?
-    def perform(message_frame)
-      @call_back.call(message_frame) if accepts?(message_frame)
-    end
-
-    # Converts this representation of a subscription into a
-    # Stomper::Frames::Subscribe client frame that can be transmitted
-    # to a stomp broker through a Stomper::Connection instance.
-    def to_subscribe
-      headers = { :destination => @destination, :ack => @ack.to_s }
-      headers[:id] = @id unless @id.nil?
-      headers[:selector] = @selector unless @selector.nil?
-      Stomper::Frames::Subscribe.new(@destination, headers)
-    end
-
-    # Converts this representation of a subscription into a
-    # Stomper::Frames::Unsubscribe client frame that can be transmitted
-    # to a stomp broker through a Stomper::Connection instance.
-    def to_unsubscribe
-      headers = { :destination => @destination }
-      headers[:id] = @id unless @id.nil?
-      Stomper::Frames::Unsubscribe.new(@destination, headers)
-    end
-  end
-end

data/lib/stomper/subscriptions.rb

@@ -1,95 +0,0 @@
-module Stomper
-  # A Subscription collection class used internally by Stomper::Client to store
-  # its subscriptions.  Instances of this class utilize synchronization making
-  # it safe to use in a multi-threaded context.
-  class Subscriptions
-    include Enumerable
-
-    # Creates a new Subscriptions container.
-    def initialize
-      @subs = []
-      @sub_lock = Mutex.new
-    end
-
-    # Adds the supplied subscription, +sub+, to the collection.
-    def <<(sub)
-      add(sub)
-    end
-
-    # Adds the supplied subscription, +sub+, to the collection.
-    def add(sub)
-      raise ArgumentError, "appended object must be a subscription" unless sub.is_a?(Subscription)
-      @sub_lock.synchronize { @subs << sub }
-    end
-
-    # Removes all Subscription objects from the collection that match
-    # the supplied destination, +dest+, and subscription id, +subid+.
-    # If +dest+ is a hash, the value referenced by the :destination key
-    # will be used as the destination, and +subid+ will be set to the value
-    # referenced by :id, unless it is explicitly set beforehand.  If +dest+ is
-    # an instance of Subscription, the +destination+ attribute will be used
-    # as the destination, and +subid+ will be set to the +id+ attribute, unless
-    # explicitly set beforehand.  The Subscription objects removed are all of
-    # those, and only those, for which the Stomper::Subscription#receives_for?
-    # method returns true given the destination and/or subscription id.
-    #
-    # This method returns an array of all the Subscription objects that were
-    # removed, or an empty array if none were removed.
-    #
-    # See also: Stomper::Subscription#receives_for?, Stomper::Client#unsubscribe
-    def remove(dest, subid=nil)
-      if dest.is_a?(Hash)
-        subid ||= dest[:id]
-        dest = dest[:destination]
-      elsif dest.is_a?(Subscription)
-        subid ||= dest.id
-        dest = dest.destination
-      end
-      _remove(dest, subid)
-    end
-
-    # Returns the number of Subscription objects within the container through
-    # the use of synchronization.
-    def size
-      @sub_lock.synchronize { @subs.size }
-    end
-
-    # Returns the first Subscription object within the container through
-    # the use of synchronization.
-    def first
-      @sub_lock.synchronize { @subs.first }
-    end
-
-    # Returns the last Subscription object within the container through
-    # the use of synchronization.
-    def last
-      @sub_lock.synchronize { @subs.last }
-    end
-
-    # Evaluates the supplied +block+ for each Subscription object
-    # within the container, or yields an Enumerator for the collection
-    # if no +block+ is given.  As this method is synchronized, it is
-    # entirely possible to enter into a dead-lock if the supplied block
-    # in turn calls any other synchronized method of the container.
-    # [This could be remedied by creating a new array with
-    # the same Subscription objects currently contained, and performing
-    # the +each+ call on the new array. Give this some thought.]
-    def each(&block)
-      @sub_lock.synchronize { @subs.each(&block) }
-    end
-
-    # Passes the supplied +message+ to all Subscription objects within the
-    # collection through their Stomper::Subscription#perform method.
-    def perform(message)
-      @sub_lock.synchronize { @subs.each { |sub| sub.perform(message) } }
-    end
-
-    private
-    def _remove(dest, subid)
-      @sub_lock.synchronize do
-        to_remove, @subs = @subs.partition { |s| s.receives_for?(dest,subid) }
-        to_remove
-      end
-    end
-  end
-end

data/lib/stomper/threaded_receiver.rb

@@ -1,59 +0,0 @@
-module Stomper
-  module ThreadedReceiver
-    def self.extended(base)
-      base.instance_eval do
-        @receiver_mutex = Mutex.new
-      end
-    end
-
-    # Starts the threaded receiver on a connection, calling receive
-    # on the connection repeatedly in a separate thread until the receiver
-    # is stopped or the connection is closed.
-    #
-    # @return self
-    # @see ThreadedReceiver#stop
-    # @see Connection#receive
-    # @see Connection#connected?
-    def start(opts={})
-      connect unless connected?
-      do_start = false
-      @receiver_mutex.synchronize do
-        do_start = !started?
-      end
-      if do_start
-        @started = true
-        @run_thread = Thread.new() do
-          while started? && connected?
-            receive
-          end
-        end
-      end
-      self
-    end
-
-    # Stops the threaded receiver on a connection thereby stopping further
-    # calls to receive.
-    #
-    # @return self
-    # @see ThreadedReceiver#start
-    # @see Connection#receive
-    # @see Connection#connected?
-    def stop
-      do_stop = false
-      @receiver_mutex.synchronize do
-        do_stop = started?
-      end
-      if do_stop
-        @started = false
-        @run_thread.join
-        @run_thread = nil
-      end
-      self
-    end
-
-    private
-    def started?
-      @started
-    end
-  end
-end

data/lib/stomper/transaction.rb

@@ -1,185 +0,0 @@
-module Stomper
-  # An exception raised whenever a Transaction object has been aborted
-  # due to an unhandled exception generated by its supplied block, or when
-  # the block explicitly aborts the transaction.
-  #
-  # See also: Stomper::Transaction#perform
-  class TransactionAborted < RuntimeError; end
-
-  # An encapsulation of a stomp transaction.  Manually managing transactions
-  # is possible through the use of Stomper::Client#begin, Stomper::Client#commit,
-  # and Stomper::Client#abort.
-  #
-  # === Example Usage
-  #
-  # When the transaction is passed to the block:
-  #
-  #   client.transaction do |t|
-  #     t.send("/queue/target", "doing some work")
-  #
-  #     # do something that might raise an exception, indicating that any
-  #     # messages and acknowledgements we have sent should be "undone"
-  #
-  #     t.send("/queue/target", "completed work")
-  #   end
-  #
-  # When the block is evaluated within the transaction:
-  #
-  #   client.transaction do
-  #     send("/queue/target", "doing some work")
-  #
-  #     # ...
-  #
-  #     send("/queue/target", "completed work")
-  #   end
-  #
-  # Nesting transactions:
-  #
-  #   client.transaction do |t|
-  #     t.transaction do |nt|
-  #       nt.send("/queue/target", ...)
-  #
-  #       nt.transaction do |nnt|
-  #         nnt.send("/queue/target", ...)
-  #
-  #         # do something with potentially exceptional results
-  #       end
-  #
-  #       nt.send("/queue/target", ...)
-  #     end
-  #
-  #     t.send("/queue/target", ...)
-  #   end
-  #
-  # See also: Stomper::Client#transaction
-  #
-  class Transaction
-    # The id of this transaction, used to reference the transaction with the stomp broker.
-    attr_reader :id
-
-    # Creates a new Transaction instance.  The +client+ parameter
-    # is an instance of Stomper::Client and is required so that the Transaction
-    # instance has somewhere to forward +begin+, +ack+ and +abort+ methods
-    # to.  If the +trans_id+ parameter is not specified, an id is automatically
-    # generated of the form +tx-<Time.now.to_f>+.  This name can be accessed
-    # through the +id+ attribute and is used in naming the transaction to
-    # the stomp broker.  If +block+ is given, the Transaction instance immediately
-    # calls its perform method with the supplied +block+.
-    def initialize(client, trans_id=nil, &block)
-      @client = client
-      @id = trans_id || "tx-#{Time.now.to_f}"
-      @committed = false
-      @aborted = false
-      perform(&block) if block_given?
-    end
-
-    # Invokes the given +block+.  If the +block+ executes normally, the
-    # transaction is committed, otherwise it is aborted.
-    # If +block+ accepts a parameter, this method yields itself to the block,
-    # otherwise, +block+ is evaluated within the context of this instance through
-    # +instance_eval+.
-    #
-    # If a call to +abort+ is issued within the block, the transaction is aborted
-    # as demanded, and no attempt is made to commit it; however, no code after the
-    # call to +abort+ will be evaluated, as +abort+ raises a TransactionAborted
-    # exception.
-    #
-    # If a call to +commit+ is issued within the block, the transaction is committed
-    # as demanded, and no attempt is made to commit it after +block+ has finished
-    # executing.  As +commit+ does not raise an excpetion, all code after the call
-    # to commit will be evaluated.
-    #
-    # If you are using Transaction objects directly, and not relying on their
-    # generation through Stomper::Client#transaction, be warned that this method
-    # will raise a TransactionAborted exception if the +block+ evaluation fails.
-    # This behavior allows for nesting transactions and ensuring that if a nested
-    # transaction fails, so do all of its ancestors.
-    #
-    # @param [Proc] block A block of code that is evaluated as part of the transaction.
-    # @raise [TransactionAborted] raises an exception if the given block raises an exception
-    def perform(&block) #:yields: transaction
-      begin
-        @client.begin(@id)
-        if block.arity == 1
-          yield self
-        else
-          instance_eval(&block)
-        end
-        commit
-      rescue => err
-        _abort
-        raise TransactionAborted, "aborted transaction '#{@id}' originator: #{err.to_s}"
-      end
-    end
-
-    # Returns true if the Transaction object has already been committed, false
-    # otherwise.
-    def committed?
-      @committed
-    end
-
-    # Returns true if the Transaction object has already been aborted, false
-    # otherwise.
-    def aborted?
-      @aborted
-    end
-
-    # Similar to Stomper::Client#transaction, this method creates a new
-    # Transaction object, nested inside of this one.  To prevent name
-    # collisions, this method automatically generates a transaction id,
-    # if one is not specified, of the form +<parent_transaction_id>-<Time.now.to_f>+.
-    def transaction(transaction_id=nil,&block)
-      # To get a transaction name guaranteed to not collide with this one
-      # we will supply an explicit id to the constructor unless an id was
-      # provided
-      transaction_id ||= "#{@id}-#{Time.now.to_f}"
-      self.class.new(@client, transaction_id, &block)
-    end
-
-    # Wraps the Stomper::Client#send method, injecting a "transaction" header
-    # into the +headers+ hash, thus informing the stomp broker that the message
-    # generated here is part of this transaction.
-    def send(destination, body, headers={})
-      @client.send(destination, body, headers.merge({:transaction => @id }))
-    end
-
-    # Wraps the Stomper::Client#ack method, injecting a "transaction" header
-    # into the +headers+ hash, thus informing the stomp broker that the message
-    # acknowledgement is part of this transaction.
-    def ack(message_or_id, headers={})
-      @client.ack(message_or_id, headers.merge({ :transaction => @id }))
-    end
-
-    # Aborts this transaction if it has not already been committed or aborted.
-    # Note that it does so by raising a TransactionAborted exception, allowing
-    # the +abort+ call to force any ancestral transactions to also fail.
-    #
-    # @see Transaction#commit
-    # @see Transaction#committed?
-    # @see Transaction#aborted?
-    def abort
-      raise TransactionAborted, "transaction '#{@id}' aborted explicitly" if _abort
-    end
-
-    # Commits this transaction unless it has already been committed or aborted.
-    #
-    # @see Transaction#abort
-    # @see Transaction#committed?
-    # @see Transaction#aborted?
-    def commit
-      # Guard against sending multiple commit messages to the server for a
-      # single transaction.
-      @client.commit(@id) unless committed? || aborted?
-      @committed = true
-    end
-
-    private
-    def _abort
-      # Guard against sending multiple abort messages to the server for a
-      # single transaction.
-      return false if committed? || aborted?
-      @client.abort(@id)
-      @aborted = true
-    end
-  end
-end