onstomp 1.0.0pre1

data/lib/onstomp/components/frame.rb

@@ -0,0 +1,108 @@
+# -*- encoding: utf-8 -*-
+
+# A generic encapsulation of a frame as specified by the Stomp protocol.
+class OnStomp::Components::Frame
+  # Regex to match content-type header value.
+  # Eg: given "text/plain; ... ;charset=ISO-8859-1 ...", then
+  # * $1 => type    ('text')
+  # * $2 => subtype ('plain')
+  # * $3 => charset ('ISO-8859-1')
+  CONTENT_TYPE_REG = /^([a-z0-9!\#$&.+\-^_]+)\/([a-z0-9!\#$&.+\-^_]+)(?:.*;\s*charset=\"?([a-z0-9!\#$&.+\-^_]+)\"?)?/i
+  
+  attr_accessor :command, :body
+  attr_reader :headers
+  
+  # Creates a new frame. The frame will be initialized with the optional
+  # +command+ name, a {OnStomp::Components::FrameHeaders headers} collection initialized
+  # with the optional +headers+ hash, and an optional body.
+  def initialize(command=nil, headers={}, body=nil)
+    @command = command
+    @headers = OnStomp::Components::FrameHeaders.new(headers)
+    @body = body
+  end
+  
+  # Gets the header value paired with the supplied name.  This is a convenient
+  # shortcut for `frame.headers[name]`.
+  #
+  # @param [Object] name the header name associated with the desired value
+  # @return [String] the value associated with the requested header name
+  # @see OnStomp::Headers#[]
+  # @example
+  #   frame['content-type'] #=> 'text/plain'
+  def [](name); @headers[name]; end
+  
+  # Sets the header value paired with the supplied name.  This is a convenient
+  # shortcut for `frame.headers[name] = val`.
+  #
+  # @param [Object] name the header name to associate with the supplied value
+  # @param [Object] val the value to associate with the supplied header name
+  # @return [String] the supplied value as a string, or `nil` if `nil` was supplied as the value.
+  # @see OnStomp::Headers#[]=
+  # @example
+  #   frame['content-type'] = 'text/plain' #=> 'text/plain'
+  #   frame['other header'] = 42 #=> '42'
+  def []=(name, val); @headers[name] = val; end
+  
+  # If a +content-length+ header is set, returns it after converting it to
+  # an integer.
+  # @return [Fixnum, nil]
+  def content_length
+    header?(:'content-length') ? @headers[:'content-length'].to_i : nil
+  end
+  
+  # If a +content-type+ header is set, splits it into three parts: type,
+  # subtype and charset. If any component of the +content-type+ is missing,
+  # its value will be +nil+ in the returned triple. If the +content-type+
+  # header is not set or does not match {OnStomp::Components::Frame::CONTENT_TYPE_REG}
+  # all values in the triple will be +nil+.
+  # @return [Array<String,nil>]
+  def content_type
+    @headers[:'content-type'] =~ CONTENT_TYPE_REG ? [$1, $2, $3] : [nil, nil, nil]
+  end
+  
+  # Returns true if the given header name exists and its value is not an
+  # empty string.
+  # @param [#to_sym] name
+  # @return [true,false]
+  # @see OnStomp::Components::FrameHeaders#present?
+  def header? name
+    @headers.present? name
+  end
+  
+  # Returns true if all given header names exist and none of their values are
+  # empty strings.
+  def all_headers? *names
+    names.all? { |name| @headers.present?(name) }
+  end
+  alias :headers? :all_headers?
+  
+  # Returns the heart-beat configuration specified in this frame's headers.
+  # If a +heart-beat+ header is not set, [0, 0] will be returned. Otherwise,
+  # the header value will be split on ',' and each component will be converted
+  # to a non-negative integer.
+  # @return [[Fixnum,Fixnum]] pair of non-negative integers that specify
+  #   connection heart-beat settings
+  def heart_beat
+    (@headers[:'heart-beat'] || '0,0').split(',').map do |v|
+      vi = v.to_i
+      vi > 0 ? vi : 0
+    end
+  end
+  
+  # Sets this frame's +content-length+ header to match the byte-length of
+  # its body, if the body has been set.
+  # @return <Fixnum,nil>
+  def force_content_length
+    @headers[:'content-length'] = body_length if body
+  end
+  
+  if RUBY_VERSION >= "1.9"
+    # Returns the byte-length of this frame's body
+    # @return [Fixnum]
+    def body_length; body.bytesize; end
+  else
+    # Returns the byte-length of this frame's body
+    # @return [Fixnum]
+    def body_length; body.length; end
+  end
+end

data/lib/onstomp/components/frame_headers.rb

@@ -0,0 +1,212 @@
+# -*- encoding: utf-8 -*-
+
+# A specialized container for storing header name / value pairs for a
+# {OnStomp::Components::Frame frame}.  This container behaves much like a +Hash+, but
+# is specialized for the Stomp protocol.  Header names are always converted
+# into +String+s through the use of +to_s+ and may have more than one value
+# associated with them.
+class OnStomp::Components::FrameHeaders
+  include Enumerable
+  
+  # Creates a new headers collection, initialized with the optional hash
+  # parameter.
+  # @param [Hash] headers
+  # @see #merge!
+  def initialize(headers={})
+    @values = {}
+    __initialize_names__
+    merge! headers
+  end
+  
+  # Merges a hash into this collection of headers. All of the keys used
+  # in the hash must be convertable to Symbols through +to_sym+.
+  # @note With Ruby 1.8.7, the order of hash keys may not be preserved
+  # @param [Hash] hash
+  def merge!(hash)
+    hash.each { |k, v| self[k]= v }
+  end
+  
+  # Reverse merges a hash into this collection of headers. The hash keys and
+  # values are included only if the headers collection does not already have
+  # a matching key. All of the keys used
+  # in the hash must be convertable to Symbols through +to_sym+.
+  # @note With Ruby 1.8.7, the order of hash keys may not be preserved
+  # @param [Hash] hash
+  def reverse_merge!(hash)
+    hash.each { |k, v|
+      self[k]= v unless set?(k)
+    }
+  end
+  
+  # Returns true if a header value has been set for the supplied header name.
+  # @param [#to_sym] name the header name to test
+  # @return [Boolean]
+  # @example
+  #   header.set? 'content-type' #=> true
+  def set?(name)
+    @values.key?(name.to_sym)
+  end
+  
+  # Returns true if a header value has been set for the supplied header, and
+  # the value is neither +nil+ nor an empty string.
+  # @param [#to_sym] name the header name to test
+  # @return [Boolean]
+  # @example
+  #   header[:test1] = 'set'
+  #   header[:test2] = ''
+  #   header.present? :test1 #=> true
+  #   header.present? :test2 #=> false
+  def present?(name)
+    val = self[name]
+    !(val.nil? || val.empty?)
+  end
+  
+  # Retrieves all header values associated with the supplied header name.
+  # In general, this will be an array containing only the principle header
+  # value; however, in the event a frame contained repeated header names,
+  # this method will return all of the associated values.  The first
+  # element of the array will be the principle value of the supplied
+  # header name.
+  #
+  # @param [#to_sym] name the header name associated with the desired values (will be converted using +to_sym+)
+  # @return [Array] the array of values associated with the header name.
+  # @example
+  #   headers.all_values('content-type') #=> [ 'text/plain' ]
+  #   headers.all_values(:repeated_header) #=> [ 'principle value', '13', 'other value']
+  #   headers['name'] == headers.all_values(:name).first #=> true
+  def all_values(name)
+    @values[name.to_sym] || []
+  end
+  
+  # Appends a header value to the specified header name.  If the specified
+  # header name is not known, the supplied value will also become the
+  # principle value.  This method is used internally when constructing
+  # frames sent by the broker to capture repeated header names.
+  #
+  # @param [#to_sym] name the header name to associate with the supplied value (will be converted using +to_s+)
+  # @param [#to_s] val the header value to associate with the supplied name (will be converted using +to_s+)
+  # @return [String] the supplied value as a string.
+  # @example
+  #   headers.append(:'new header', 'first value') #=> 'first value'
+  #   headers.append('new header', nil) #=> ''
+  #   headers.append('new header', 13) #=> '13'
+  #   headers['new header'] #=> 'first value'
+  #   headers.all('new header') #=> ['first value', '', '13']
+  def append(name, val)
+    name = name.to_sym
+    val = val.to_s
+    if @values.key?(name)
+      @values[name] << val
+    else
+      self[name]= val
+    end
+    val
+  end
+  
+  # Deletes all of the header values associated with the header name and
+  # removes the header name itself.  This is analogous to the +delete+
+  # method found in Hash objects.
+  #
+  # @param [#to_sym] name the header name to remove from this collection (will be converted using +to_sym+)
+  # @return [Array] the array of values associated with the deleted header, or +nil+ if the header name did not exist
+  # @example
+  #   headers.delete(:'content-type') #=> [ 'text/html' ]
+  #   headers.delete('no such header') #=> nil
+  def delete(name)
+    name = name.to_sym
+    if @values.key? name
+      __delete_name__ name
+      @values.delete name
+    end
+  end
+  
+  # Gets the principle header value paired with the supplied header name. The name will
+  # be converted to a Symbol, so must respond to the +to_sym+ method.  The
+  # Stomp 1.1 protocol specifies that in the event of a repeated header name,
+  # the first value encountered serves as the principle value.
+  #
+  # @param [#to_sym] name the header name paired with the desired value (will be converted using +to_sym+)
+  # @return [String] the value associated with the requested header name
+  # @return [nil] if no value has been set for the associated header name
+  # @example
+  #   headers['content-type'] #=> 'text/plain'
+  def [](name)
+    name = name.to_sym
+    @values[name] && @values[name].first
+  end
+  
+  # Sets the header value paired with the supplied header name.  The name 
+  # will be converted to a Symbol and must respond to +to_sym+; meanwhile,
+  # the value will be converted to a String so must respond to +to_s+.
+  # Setting a header value in this fashion will overwrite any repeated header values.
+  #
+  # @param [#to_sym] name the header name to associate with the supplied value (will be converted using +to_sym+)
+  # @param [#to_s] val the value to pair with the supplied name (will be converted using +to_s+)
+  # @return [String] the supplied value as a string.
+  # @example
+  #   headers['content-type'] = 'image/png' #=> 'image/png'
+  #   headers[:'content-type'] = nil #=> ''
+  #   headers['content-type'] #=> ''
+  def []=(name, val)
+    name = name.to_sym
+    val = val.to_s
+    __add_name__ name
+    @values[name] = [val]
+    val
+  end
+  
+  # Returns a new +Hash+ object associating symbolized header names and their
+  # principle values.
+  # @return [Hash]
+  def to_hash
+    @values.inject({}) { |h, (k,v)| h[k] = v.first; h }
+  end
+  
+  if RUBY_VERSION >= "1.9"
+    def names; @values.keys; end
+    
+    def each(&block)
+      if block_given?
+        @values.each do |name, vals|
+          name_str = name.to_s
+          vals.each do |val|
+            yield [name_str, val]
+          end
+        end
+        self
+      else
+        Enumerator.new(self)
+      end
+    end
+    
+    private
+    def __initialize_names__; end
+    def __delete_name__(name); end
+    def __add_name__(name); end
+  else
+    attr_reader :names
+    
+    # Iterates over header name / value pairs, yielding them as a pair
+    # of strings to the supplied block.
+    # @yield [header_name, header_value]
+    # @yieldparam [String] header_name
+    # @yieldparam [String] header_value
+    def each(&block)
+      if block_given?
+        @names.each do |name|
+          @values[name].each do |val|
+            yield [name.to_s, val]
+          end
+        end
+        self
+      else
+        Enumerable::Enumerator.new(self)
+      end
+    end
+
+    private
+    def __initialize_names__; @names = []; end
+    def __delete_name__(name); @names.delete name; end
+    def __add_name__(name); @names << name unless @values.key?(name); end
+  end
+end

data/lib/onstomp/components/nil_processor.rb

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+
+# A processor that does nothing, used in the event that
+# {OnStomp::Client client} +processor+ attribute is set to +nil+
+class OnStomp::Components::NilProcessor
+  # Creates a new processor
+  def initialize(client); end
+  # Always returns +false+
+  # @return [false]
+  def running?; false; end
+  # Does nothing
+  # @return [self]
+  def start; self; end
+  # Does nothing
+  # @return [self]
+  def join; self; end
+  # Does nothing
+  # @return [self]
+  def stop; self; end
+end

data/lib/onstomp/components/scopes/header_scope.rb

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+
+# Adds the a set of headers to all frames generated on the scope.
+class OnStomp::Components::Scopes::HeaderScope
+  include OnStomp::Interfaces::FrameMethods
+  
+  attr_reader :headers, :client, :connection
+  
+  def initialize headers, client
+    @headers = headers
+    @client = client
+    @connection = client.connection
+  end
+  
+  # Wraps {OnStomp::Client#transmit}, applying the set of {#headers} to
+  # all frames befor they are delivered to the broker.
+  # @param [OnStomp::Components::Frame] frame
+  # @param [{Symbol => Proc}] cbs
+  # @return [OnStomp::Components::Frame]
+  # @see OnStomp::Client#transmit
+  def transmit frame, cbs={}
+    frame.headers.reverse_merge!(headers)
+    client.transmit frame, cbs
+  end
+end

data/lib/onstomp/components/scopes/receipt_scope.rb

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+
+# Adds a receipt callback to all receipt-able frames generated on this scope
+class OnStomp::Components::Scopes::ReceiptScope
+  include OnStomp::Interfaces::FrameMethods
+  
+  attr_reader :callback, :client, :connection
+  
+  def initialize callback, client
+    @callback = callback
+    @client = client
+    @connectio = client.connection
+  end
+  
+  # Wraps {OnStomp::Client#transmit}, applying the {#callback} as a receipt
+  # handler for all frames before they are sent to the broker.
+  # @param [OnStomp::Components::Frame] frame
+  # @param [{Symbol => Proc}] cbs
+  # @return [OnStomp::Components::Frame]
+  # @see OnStomp::Client#transmit
+  def transmit frame, cbs={}
+    cbs[:receipt] ||= callback
+    client.transmit frame, cbs
+  end
+end

data/lib/onstomp/components/scopes/transaction_scope.rb

@@ -0,0 +1,191 @@
+# -*- encoding: utf-8 -*-
+
+# Bundles supported frames within a transaction. The transaction only applies
+# to SEND, BEGIN, COMMIT, ABORT, ACK, and NACK frames, all others are
+# passed on to the broker unmodified. A given transaction scope can be used
+# to wrap multiple transactions as once {#abort} or {#commit} has been called,
+# a call to {#begin} will generate a new transaction id.
+class OnStomp::Components::Scopes::TransactionScope
+  include OnStomp::Interfaces::FrameMethods
+  
+  # The id of the current transaction. This may be +nil+ if the transaction
+  # has not been started with {#begin} or if the transaction has been completed
+  # by a call to either {#abort} or {#commit}.
+  # @return [String,nil]
+  attr_reader :transaction
+  
+  # The client this transaction belongs to
+  # @return [OnStomp::Client]
+  attr_reader :client
+  
+  # A reference to +self+ to trick {OnStomp::Interfaces::FrameMethods} into
+  # creating frames on this object instead of the client's actual
+  # {OnStomp::Client#connection connection}.
+  # @return [self]
+  attr_reader :connection
+  
+  def initialize tx_id, client
+    @transaction = tx_id
+    @client = client
+    @connection = self
+    @started = false
+  end
+  
+  # Overrides the standard {OnStomp::Interfaces::FrameMethods#begin} method
+  # to maintain the state of the transaction. Unlike
+  # {OnStomp::Interfaces::FrameMethods#begin}, no transaction ID parameter is
+  # required when {#begin} is called on a
+  # {OnStomp::Components::Scopes::TransactionScope}. If a transaction ID is
+  # provided, it will be used, otherwise one will be automatically generated.
+  # @param [{#to_sym => #to_s}] headers optional headers to include in the frame
+  # @raise [OnStomp::TransactionError] if {#begin} has already been called and
+  #   neither {#abort} or {#commit} have been called to complete the transaction.
+  # @return [OnStomp::Components::Frame] BEGIN frame
+  def begin_with_transaction *args
+    raise OnStomp::TransactionError, 'transaction has already begun' if @started
+    headers = args.last.is_a?(Hash) ? args.pop : {}
+    next_transaction_id args.first
+    @started = true
+    begin_without_transaction @transaction, headers
+  end
+  alias :begin_without_transaction :begin
+  alias :begin :begin_with_transaction
+  
+  # Overrides the standard {OnStomp::Interfaces::FrameMethods#commit} method
+  # to maintain the state of the transaction. Unlike
+  # {OnStomp::Interfaces::FrameMethods#commit}, no transaction ID parameter is
+  # required when {#commit} is called on a
+  # {OnStomp::Components::Scopes::TransactionScope}. If a transaction ID is
+  # provided, it will be ignored.
+  # @param [{#to_sym => #to_s}] headers optional headers to include in the frame
+  # @return [OnStomp::Components::Frame] COMMIT frame
+  def commit_with_transaction *args
+    raise OnStomp::TransactionError, 'transaction has not begun' unless @started
+    headers = args.last.is_a?(Hash) ? args.pop : {}
+    commit_without_transaction(@transaction, headers).tap do
+      finalize_transaction
+    end
+  end
+  alias :commit_without_transaction :commit
+  alias :commit :commit_with_transaction
+
+  # Overrides the standard {OnStomp::Interfaces::FrameMethods#abort} method
+  # to maintain the state of the transaction. Unlike
+  # {OnStomp::Interfaces::FrameMethods#abort}, no transaction ID parameter is
+  # required when {#abort} is called on a
+  # {OnStomp::Components::Scopes::TransactionScope}. If a transaction ID is
+  # provided, it will be ignored.
+  # @param [{#to_sym => #to_s}] headers optional headers to include in the frame
+  # @return [OnStomp::Components::Frame] ABORT frame
+  def abort_with_transaction *args
+    raise OnStomp::TransactionError, 'transaction has not begun' unless @started
+    headers = args.last.is_a?(Hash) ? args.pop : {}
+    abort_without_transaction(@transaction, headers).tap do
+      finalize_transaction
+    end
+  end
+  alias :abort_without_transaction :abort
+  alias :abort :abort_with_transaction
+  
+  # Overrides the {OnStomp::Connections::Stomp_1#send_frame send_frame} method
+  # of the {OnStomp::Client#connection client's connection}, setting a
+  # +transaction+ header to match the current transaction if it has been
+  # started.
+  # @param [arg1, arg2, ...] args arguments to connection's +send_frame+ method
+  # @return [OnStomp::Components::Frame] SEND frame
+  def send_frame *args, &blk
+    client.connection.send_frame(*args,&blk).tap do |f|
+      f[:transaction] = @transaction if @started
+    end
+  end
+  
+  # Overrides the {OnStomp::Connections::Stomp_1_0#ack_frame ack_frame} method
+  # of the client's {OnStomp::Client#connection connection}, setting a
+  # +transaction+ header to match the current transaction if it has been
+  # started.
+  # @param [arg1, arg2, ...] args arguments to connection's +ack_frame+ method
+  # @return [OnStomp::Components::Frame] ACK frame
+  def ack_frame *args
+    client.connection.ack_frame(*args).tap do |f|
+      f[:transaction] = @transaction if @started
+    end
+  end
+  
+  # Overrides the {OnStomp::Connections::Stomp_1_1#nack_frame nack_frame} method
+  # of the {OnStomp::Client#connection client's connection}, setting a
+  # +transaction+ header to match the current transaction if it has been
+  # started.
+  # @param [arg1, arg2, ...] args arguments to connection's +nack_frame+ method
+  # @return [OnStomp::Components::Frame] NACK frame
+  def nack_frame *args
+    client.connection.ack_frame(*args).tap do |f|
+      f[:transaction] = @transaction if @started
+    end
+  end
+  
+  # If the name of the missing method ends with +_frame+, the method is passed
+  # along to the client's {OnStomp::Client#connection connection} so that it
+  # might build the appropriate (non-transactional) frame.
+  # @return [OnStomp::Components::Frame]
+  # @raise [OnStomp::UnsupportedCommandError] if the connection does not
+  #   support the requested frame command.
+  # @raise [NoMethodError] if the method name does not end in +_frame+
+  def method_missing meth, *args, &block
+    if meth.to_s =~ /^(.*)_frame$/
+      client.connection.__send__(meth, *args, &block)
+    else
+      super
+    end
+  end
+  
+  # Evaluates a block within this transaction scope. This method will transmit
+  # a BEGIN frame to start the transaction (unless it was manually begun prior
+  # to calling {#perform}), yield itself to the supplied block, and finally
+  # transmit a COMMIT frame to complete the transaction if no errors were
+  # raised within the block. If an error was raised within the block, an
+  # ABORT frame will be transmitted instead, rolling back the transaction and
+  # the exception will be re-raised.
+  # If a non-transactional frame is generated within the block, it will be
+  # transmitted as-is to the broker and will not be considered part of the
+  # transaction.
+  # Finally, if the {#abort} or {#commit} methods are called within the block,
+  # neither COMMIT nor ABORT frames will be automatically generated after
+  # the block's execution.
+  # @return [self]
+  # @raise [Exception] if supplied block raises an exception
+  # @yield [t] block of frames to transmit transactionally
+  # @yieldparam [OnStomp::Components::Scopes::TransactionScope] t +self+
+  def perform
+    begin
+      self.begin unless @started
+      yield self
+      self.commit if @started
+      self
+    rescue Exception
+      self.abort if @started
+      raise
+    end
+  end
+  
+  # Wraps {OnStomp::Client#transmit} to support the
+  # {OnStomp::Interfaces::FrameMethods} mixin. All arguments are directly
+  # passed on to the {#client}.
+  # @return [OnStomp::Components::Frame]
+  # @see OnStomp::Client#transmit
+  def transmit *args
+    client.transmit *args
+  end
+  
+  private
+  def finalize_transaction
+    @transaction = nil
+    @started = false
+  end
+  
+  def next_transaction_id maybe_tx
+    # find the first non-nil, non-empty value
+    tx_val = [maybe_tx, @transaction].detect { |t| !t.nil? && !t.empty? }
+    # If both are nil or empty, generate a new serial id
+    @transaction = tx_val || OnStomp.next_serial
+  end
+end

data/lib/onstomp/components/scopes.rb

@@ -0,0 +1,45 @@
+# -*- encoding: utf-8 -*-
+
+# Mixin for {OnStomp::Client clients} to create frame scopes.
+module OnStomp::Components::Scopes
+  # Creates a new {OnStomp::Components::Scopes::ReceiptScope}.
+  # Any receipt-able frame generated on this scope will automatically have
+  # the supplied callback attached as a RECEIPT handler.
+  # @yield [r] callback to be invoked when the RECEIPT frame is received
+  # @yieldparam [OnStomp::Components::Frame] r RECEIPT frame
+  # @return [OnStomp::Components::Scopes::ReceiptScope]
+  def with_receipt &block
+    OnStomp::Components::Scopes::ReceiptScope.new(block, self)
+  end
+  
+  # Creates a new {OnStomp::Components::Scopes::TransactionScope} and
+  # evaluates the block within that scope if one is given.
+  # @param [String] tx_id optional id for the transaction
+  # @yield [t] block of frames to generate within a transaction
+  # @yieldparam [OnStomp::Components::Scopes::TransactionScope] t
+  # @return [OnStomp::Components::Scopes::TransactionScope]
+  # @see OnStomp::Components::Scopes::TransactionScope#perform
+  def transaction tx_id=nil, &block
+    OnStomp::Components::Scopes::TransactionScope.new(tx_id, self).tap do |t|
+      t.perform(&block) if block
+    end
+  end
+  
+  # Creates a new {OnStomp::Components::Scopes::HeaderScope} that
+  # will apply the provided headers to all frames generated on the scope.
+  # If a block is given, it will be evaluated within this scope.
+  # @param [{#to_sym => #to_s}] headers
+  # @yield [h] block of frames to apply headers to
+  # @yieldparam [OnStomp::Components::Scopes::HeaderScope] h
+  # @return [OnStomp::Components::Scopes::HeaderScope]
+  # @see OnStomp::Components::Scopes::HeaderScope#perform
+  def with_headers headers
+    OnStomp::Components::Scopes::HeaderScope.new(headers, self).tap do |h|
+      yield h if block_given?
+    end
+  end
+end
+
+require 'onstomp/components/scopes/header_scope'
+require 'onstomp/components/scopes/receipt_scope'
+require 'onstomp/components/scopes/transaction_scope'

data/lib/onstomp/components/subscription.rb

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+
+# A simple encapsulation of a subscription. Instances of this class keep
+# track of the SUBSCRIBE frame they were generated for and the callback to
+# invoke when a MESSAGE frame is received for the subscription.
+class OnStomp::Components::Subscription
+  attr_reader :frame, :callback
+  # Creates a new subscription
+  # @param [OnStomp::Components::Frame] fr the subscription's SUBSCRIBE frame
+  # @param [Proc] cb the subscription's callback
+  def initialize(fr, cb)
+    @frame = fr
+    @callback = cb
+  end
+  # Returns the +id+ header of the associated SUBSCRIBE frame
+  # @return [String]
+  def id; frame[:id]; end
+  # Returns the +destination+ header of the associated SUBSCRIBE frame
+  # @return [String]
+  def destination; frame[:destination]; end
+  # Invokes the {#callback}, passing along the supplied MESSAGE frame
+  # @param [OnStomp::Componenets::Frame] m the associated MESSAGE frame
+  def call(m); callback.call(m); end
+  # Returns true if this message frame shares the same destination as this
+  # subscription, false otherwise.
+  # @return [true, false]
+  def include? m
+    self.destination == m[:destination]
+  end
+end