stomper 0.3.0

data/lib/stomper/frames/headers.rb

@@ -0,0 +1,68 @@
+module Stomper
+  module Frames
+    # Encapsulates the headers attached to a Frame from the Stomper::Frames
+    # module.  Instances of this class wrap a hash, but do so in a way
+    # to allow its values to be accessed by string, symbol, or method name,
+    # similar to an OpenStruct.
+    class Headers
+      # Creates a new Header instance, derived from the supplied hash, +hsh+.
+      def initialize(hsh = {})
+        @intern_head = hsh.inject({}) { |acc, (k,v)| acc[k.to_sym] = v; acc }
+      end
+
+      # Returns the 'id' header value, if it exists.  Explicitly implemented
+      # because Object#id is a valid method by default.
+      def id
+        @intern_head[:id]
+      end
+
+      # Assigns the 'id' header value.  Explicitly implemented because Object#id
+      # is a valid method, and we implemented +id+ explicitly so why not +id=+
+      def id=(id)
+        @intern_head[:id] = id
+      end
+
+      # Allows the headers to be accessed as though they were a Hash instance.
+      def [](idx)
+        @intern_head[idx.to_sym]
+      end
+
+      # Allows the headers to be assigned as though they were a Hash instance.
+      def []=(idx, val)
+        @intern_head[idx.to_sym] = val
+      end
+
+      def method_missing(meth, *args) # :nodoc:
+        raise TypeError, "can't modify frozen headers" if frozen?
+        meth_str = meth.to_s
+        ret = if meth_str =~ /=$/
+          raise ArgumentError, "setter #{meth_str} can only accept one value" if args.size != 1
+          meth_str.chop!
+          @intern_head[meth_str.to_sym] = args.first
+        else
+          raise ArgumentError, "getter #{meth_str} cannot accept any values" if args.size > 0
+          @intern_head[meth_str.to_sym]
+        end
+        _create_helpers(meth_str)
+        # Do the appropriate thing the first time around.
+        ret
+      end
+
+      # Converts the headers encapsulated by this object into a format that
+      # the Stomp Protocol expects them to be presented as.
+      def to_stomp
+        @intern_head.sort { |a, b| a.first.to_s <=> b.first.to_s }.inject("") do |acc, (k,v)|
+          acc << "#{k.to_s}:#{v}\n"
+        end
+      end
+
+      protected
+      def _create_helpers(meth)
+        return if self.respond_to?(meth)
+        meta = class << self; self; end
+        meta.send(:define_method, meth) { self[meth] }
+        meta.send(:define_method, :"#{meth}=") { |v| self[meth] = v }
+      end
+    end
+  end
+end

data/lib/stomper/frames/message.rb

@@ -0,0 +1,44 @@
+module Stomper
+  module Frames
+    # Encapsulates a "MESSAGE" server side frame for the Stomp Protocol.
+    #
+    # See the {Stomp Protocol Specification}[http://stomp.codehaus.org/Protocol]
+    # for more details.
+    class Message < Stomper::Frames::ServerFrame
+      # This class is the factory for all MESSAGE frames received.
+      factory_for :message
+
+      # Creates a new message frame with the given +headers+ and +body+
+      def initialize(headers, body)
+        super('MESSAGE', headers, body)
+      end
+
+      # Returns the message id generated by the stomp broker.
+      #
+      # This is a convenience method for:
+      # frame.headers[:'message-id'] or frame.headers['message-id']
+      def id
+        @headers[:'message-id']
+      end
+
+      # Returns the destination from which this message was delivered.
+      #
+      # This is a convenience method for:
+      # frame.headers.destination, frame.headers['destination'], or
+      # frame.headers[:destination]
+      def destination
+        @headers.destination
+      end
+
+      # Returns the name of the subscription which is responsible for the
+      # client having received this message.
+      #
+      # This is a convenience method for:
+      # frame.headers.subscription, frame.headers['subscription'] or
+      # frame.headers[:subscription]
+      def subscription
+        @headers.subscription
+      end
+    end
+  end
+end

data/lib/stomper/frames/receipt.rb

@@ -0,0 +1,24 @@
+module Stomper
+  module Frames
+    # Encapsulates a "RECEIPT" server side frame for the Stomp Protocol.
+    #
+    # See the {Stomp Protocol Specification}[http://stomp.codehaus.org/Protocol]
+    # for more details.
+    class Receipt < Stomper::Frames::ServerFrame
+      # This class is a factory for all RECEIPT commands received.
+      factory_for :receipt
+
+      # Creates a new Receipt frame with the supplied +headers+ and +body+
+      def initialize(headers, body)
+        super('RECEIPT', headers, body)
+      end
+
+      # Returns the 'receipt-id' header of the frame, which
+      # will correspond to the 'receipt' header of the message
+      # that caused this receipt to be sent by the stomp broker.
+      def for
+        @headers[:'receipt-id']
+      end
+    end
+  end
+end

data/lib/stomper/frames/send.rb

@@ -0,0 +1,14 @@
+module Stomper
+  module Frames
+    # Encapsulates a "SEND" frame from the Stomp Protocol.
+    #
+    # See the {Stomp Protocol Specification}[http://stomp.codehaus.org/Protocol]
+    # for more details.
+    class Send < Stomper::Frames::ClientFrame
+      def initialize(destination, body, headers={})
+        super('SEND', headers, body)
+        @headers.destination = destination
+      end
+    end
+  end
+end

data/lib/stomper/frames/server_frame.rb

@@ -0,0 +1,48 @@
+module Stomper
+  module Frames
+    # Encapsulates a server side frame for the Stomp Protocol.
+    #
+    # See the {Stomp Protocol Specification}[http://stomp.codehaus.org/Protocol]
+    # for more details.
+    class ServerFrame
+      attr_reader :command, :headers, :body
+
+      # Creates a new server frame corresponding to the
+      # supplied +command+ with the given +headers+ and +body+.
+      def initialize(command, headers={}, body=nil)
+        @command = command
+        @headers = Headers.new(headers)
+        @body = body
+      end
+
+      class << self
+        # Provides a method for subclasses to register themselves
+        # as factories for particular stomp commands by passing a list
+        # of strings (or symbols) to this method.  Each element in
+        # the list is interpretted as the command for which we will
+        # defer to the calling subclass to build.
+        def factory_for(*args)
+          @@registered_commands ||= {}
+          args.each do |command|
+            @@registered_commands[command.to_s.upcase] = self
+          end
+        end
+
+        # Builds a new ServerFrame instance by first checking to
+        # see if some subclass of ServerFrame has registered itself
+        # as a builder of the particular command.  If so, a new
+        # instance of that subclass is created, otherwise a generic
+        # ServerFrame instance is created with its +command+ attribute
+        # set appropriately.
+        def build(command, headers, body)
+          command = command.to_s.upcase
+          if @@registered_commands.has_key?(command)
+            @@registered_commands[command].new(headers, body)
+          else
+            ServerFrame.new(command, headers, body)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stomper/frames/subscribe.rb

@@ -0,0 +1,47 @@
+module Stomper
+  module Frames
+    # Encapsulates a "SUBSCRIBE" frame from the Stomp Protocol.
+    #
+    # See the {Stomp Protocol Specification}[http://stomp.codehaus.org/Protocol]
+    # for more details.
+    class Subscribe < Stomper::Frames::ClientFrame
+      def initialize(destination, headers={})
+        super('SUBSCRIBE', headers)
+        @headers['destination'] = destination
+        @headers['ack'] ||= 'auto'
+      end
+
+      # Returns the ack mode of this subscription. (defaults to 'auto')
+      #
+      # This is a convenience method, and may also be accessed through
+      # frame.headers.ack or frame.headers[:ack] or frame.headers['ack']
+      def ack
+        @headers['ack']
+      end
+
+      # Returns the destination to which we are subscribing.
+      #
+      # This is a convenience method, and may also be accessed through
+      # frame.headers.destination or frame.headers[:destination] or frame.headers['destination']
+      def destination
+        @headers['destination']
+      end
+
+      # Returns the id of this subscription, if it has been set.
+      #
+      # This is a convenience method, and may also be accessed through
+      # frame.headers.id or frame.headers[:id] or frame.headers['id']
+      def id
+        @headers['id']
+      end
+
+      # Returns the selector header of this subscription, if it has been set.
+      #
+      # This is a convenience method, and may also be accessed through
+      # frame.headers.selector or frame.headers[:selector] or frame.headers['selector']
+      def selector
+        @headers['selector']
+      end
+    end
+  end
+end

data/lib/stomper/frames/unsubscribe.rb

@@ -0,0 +1,23 @@
+module Stomper
+  module Frames
+    # Encapsulates an "UNSUBSCRIBE" frame from the Stomp Protocol.
+    #
+    # See the {Stomp Protocol Specification}[http://stomp.codehaus.org/Protocol]
+    # for more details.
+    class Unsubscribe < Stomper::Frames::ClientFrame
+      def initialize(destination, headers={})
+        super('UNSUBSCRIBE', headers)
+        @headers['destination'] = destination
+      end
+
+      # Returns the id of the subscription being unsubscribed from, if it
+      # exists.
+      #
+      # This is a convenience method, and may also be accessed through
+      # frame.headers.id or frame.headers[:id] or frame.headers['id']
+      def id
+        @headers['id']
+      end
+    end
+  end
+end

data/lib/stomper/subscription.rb

@@ -0,0 +1,128 @@
+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 also: naive?, Stomper::Client#subscribe, Stomper::Client#unsubscribe,
+    # Stomper::Client#ack
+    #
+    def initialize(destination_or_options, subscription_id=nil, ack=nil, selector=nil, &block)
+      if destination_or_options.is_a?(Hash)
+        options = Stomper::Frames::Headers.new(destination_or_options)
+        destination = options.destination
+        subscription_id ||= options.id
+        ack ||= options.ack
+        selector ||= 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

@@ -0,0 +1,95 @@
+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