stomper 1.0.0 → 2.0.0

data/lib/stomper/support.rb

@@ -0,0 +1,68 @@
+# -*- encoding: utf-8 -*-
+
+# Module that stores methods that add supporiting functionality to Stomper and
+# support for Ruby 1.9 and 1.8.7.
+module Stomper::Support
+  # Duplicates an existing hash while transforming its keys to symbols.
+  # The keys must implement the +to_sym+ method, otherwise an exception will
+  # be raised. This method is used internally to convert hashes keyed with
+  # Strings.
+  #
+  # @param [{Object => Object}] hsh The hash to convert. It's keys must respond to +to_sym+.
+  # @return [{Symbol => Object}]
+  # @example
+  #   hash = { '10' => nil, 'key2' => [3, 5, 8, 13, 21], :other => :value }
+  #   Stomper::Helpers::Hash.keys_to_sym(hash) #=> { :'10' => nil, :key2 => [3, 5, 8, 13, 21], :other => :value }
+  #   hash #=> { '10' => nil, 'key2' => [3, 5, 8, 13, 21], :other => :value }
+  def self.keys_to_sym(hsh)
+    hsh.inject({}) do |new_hash, (k,v)|
+      new_hash[k.to_sym] = v
+      new_hash
+    end
+  end
+  
+  # Replaces the keys of a hash with symbolized versions.
+  # The keys must implement the +to_sym+ method, otherwise an exception will
+  # be raised. This method is used internally to convert hashes keyed with
+  # Strings.
+  #
+  # @param [{Object => Object}] hsh The hash to convert. It's keys must respond to +to_sym+.
+  # @return [{Symbol => Object}]
+  # @example
+  #   hash = { '10' => nil, 'key2' => [3, 5, 8, 13, 21], :other => :value }
+  #   Stomper::Helpers::Hash.keys_to_sym!(hash) #=> { :'10' => nil, :key2 => [3, 5, 8, 13, 21], :other => :value }
+  #   hash #=> { :'10' => nil, :key2 => [3, 5, 8, 13, 21], :other => :value }
+  def self.keys_to_sym!(hsh)
+    hsh.replace(keys_to_sym(hsh))
+  end
+  
+  # Generates the next serial number in a thread-safe manner. This method
+  # merely initializes an instance variable to 0 if it has not been set,
+  # then increments this value and returns its string representation.
+  def self.next_serial(prefix=nil)
+    Thread.exclusive do
+      @next_serial_sequence ||= 0
+      @next_serial_sequence += 1
+      @next_serial_sequence.to_s
+    end
+  end
+  
+  # Converts a string to the Ruby constant it names. If the +klass+ parameter
+  # is a kind of +Module+, this method will return +klass+ directly.
+  # @param [String,Module] klass
+  # @return [Module]
+  # @example
+  #   Stomper::Support.constantize('Stomper::Frame') #=> Stomper::Frame
+  #   Stomper::Support.constantize('This::Constant::DoesNotExist) #=> raises NameError
+  #   Stomper::Support.constantize(Symbol) #=> Symbol 
+  def self.constantize(klass)
+    return klass if klass.is_a?(Module)
+    klass.to_s.split('::').inject(Object) do |const, named|
+      next const if named.empty?
+      const.const_defined?(named) ? const.const_get(named) :
+        const.const_missing(named)
+    end
+  end
+end
+
+require 'stomper/support/ruby'

data/lib/stomper/support/1.8/frame_serializer.rb

@@ -0,0 +1,53 @@
+# -*- encoding: utf-8 -*-
+
+# Implementation of {Stomper::FrameSerializer} methods for Ruby 1.8.7
+module Stomper::Support::Ruby1_8::FrameSerializer
+  # Return the body with the specified encoding applied. Ruby 1.8 does not
+  # have a native awareness of string encodings. As such, this method does
+  # not change the body in any way.
+  # @param [String] body body of message to encode
+  # @param [String] ct content-type header of frame
+  # @return [String]
+  def encode_body(body, ct_header)
+    body
+  end
+  
+  # Reads a single byte from the body portion of a frame. Returns +nil+ if
+  # the character read is a {::Stomper::FrameSerializer::FRAME_TERMINATOR frame terminator}.
+  # @return [String,nil] the byte read from the stream.
+  def get_body_byte
+    c = @io.getc.chr
+    c == ::Stomper::FrameSerializer::FRAME_TERMINATOR ? nil : c
+  end
+  
+  # Determines the content-type of a frame being sent to a broker. This
+  # version of the method is used by Ruby 1.8.7, which lacks native string
+  # encoding support. If the content-type matches 'text/*', and no charset
+  # parameter is set, a charset of UTF-8 will be assumed. In all other
+  # cases, the 'content-type' header is used directly.
+  # @return [String] content-type and possibly charset of frame's body
+  def determine_content_type(frame)
+    ct = frame[:'content-type']
+    if ct =~ /^text\//i && !(ct =~ /\;\s*charset=\"?[a-zA-Z0-9!\#$&.+\-^_]+\"?/i)
+      "#{ct};charset=UTF-8"
+    else
+      ct
+    end
+  end
+  
+  # Determines the content-length of a frame being sent to a broker. For
+  # Ruby 1.8.7, this is just the +size+ of the frame's body.
+  # @return [Fixnum] byte-length of frame's body
+  def determine_content_length(frame)
+    frame.body.size
+  end
+  
+  # Reads a line of text from the underlying IO. As per the Stomp 1.1
+  # specification, all header strings are encoded with UTF-8.
+  # @return [String] line of text read from IO, or '' if no text was read.
+  def get_header_line
+    @io.gets || ''
+  end
+end
+
+::Stomper::FrameSerializer.__send__(:include, ::Stomper::Support::Ruby1_8::FrameSerializer)

data/lib/stomper/support/1.8/headers.rb

@@ -0,0 +1,183 @@
+# -*- encoding: utf-8 -*-
+
+# The implementation of the {Stomper::Headers} class for Ruby 1.8.7
+module Stomper::Support::Ruby1_8::Headers
+  # An array of header names ordered by when they were set.
+  # @return [Array<String>]
+  attr_reader :names
+  
+  # Creates a new headers collection, initialized with the optional hash
+  # parameter.
+  # @note With Ruby 1.8.7, the order of hash keys may not be preserved
+  # @param [Hash] headers
+  # @see #merge!
+  def initialize(headers={})
+    @values = {}
+    @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 has?(k)
+    }
+  end
+  
+  # Returns true if a header value has been set for the supplied header name.
+  # @param [Object] name the header name to test (will be converted using +to_sym+)
+  # @return [Boolean] true if the specified header name has been set, otherwise false.
+  # @example
+  #   header.has? 'content-type' #=> true
+  #   header.key? 'unset header' #=> false
+  #   header.include? 'content-length' #=> true
+  def has?(name)
+    @values.key?(name.to_sym)
+  end
+  alias :key? :has?
+  alias :include? :has?
+  
+  # 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 [Object] 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(:repeated_header) #=> [ 'principle value', '13', 'other value']
+  #   headers['name'] == headers.all(:name).first #=> true
+  def all_values(name)
+    @values[name.to_sym] || []
+  end
+  alias :all :all_values
+  
+  # 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 [Object] 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
+      @names.delete(name)
+      @values.delete(name)
+    end
+  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 [Object] name the header name to associate with the supplied value (will be converted using +to_s+)
+  # @param [Object] 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
+  
+  # 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 [Object] 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)
+    vals = @values[name.to_sym]
+    vals && vals.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 [Object] name the header name to associate with the supplied value (will be converted using +to_sym+)
+  # @param [Object] 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
+    @names << name unless @values.key?(name)
+    @values[name] = [val]
+    val
+  end
+
+  # Iterates over each header name / value pair in the order in which the
+  # headers names were set.  If this collection contains repeated header names,
+  # the supplied block will receive those header names repeatedly, once
+  # for each value. If no block is supplied, then an +Enumerator+ is returned.
+  # All header names yielded through this method will be Strings and not
+  # the Symbol keys used internally.
+  #
+  # @yield [name, value] a header name and an associated value
+  # @yieldparam [String] name a header name
+  # @yieldparam [String] value a value associated with the header
+  # @return [Headers] +self+ if a block was supplied
+  # @return [Enumerable::Enumerator] a collection enumerator if no block was supplied
+  # @example
+  #   headers['name 1'] = 'value 1'
+  #   headers.append('name_2', 'value 2')
+  #   headers.append(:name_2, 42)
+  #   headers.each { |name, val| p "#{name} - #{v}" }
+  #   # name 1 - value 1
+  #   # name_2 - value 2
+  #   # name_2 - 42
+  #   #=> #<Stomper::Components::Headers:0x0000010289d6d8>
+  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
+end
+
+::Stomper::Headers.__send__(:include, ::Stomper::Support::Ruby1_8::Headers)

data/lib/stomper/support/1.9/frame_serializer.rb

@@ -0,0 +1,64 @@
+# -*- encoding: utf-8 -*-
+
+# Implementation of {Stomper::FrameSerializer} methods for Ruby 1.9
+module Stomper::Support::Ruby1_9::FrameSerializer
+  # Return the body with the specified encoding applied. An encoding
+  # is specified in the 'content-type' header of a frame by the +charset+
+  # parameter. If no encoding was explicitly specified, a UTF-8 encoding
+  # is used when the frame's content type begins with +text/+, otherwise
+  # an encoding of US-ASCII is used.
+  # @param [String] body body of message to encode
+  # @param [String] ct content-type header of frame
+  # @return [String] body with the appropriate encoding applied
+  def encode_body(body, ct_header)
+    body.tap do |b|
+      charset = ct_header ?
+        (ct_header =~ /\;\s*charset=\"?([\w\-]+)\"?/i) ? $1 :
+          (ct_header =~ /^text\//) ? 'UTF-8' : 'ASCII-8BIT' :
+        'ASCII-8BIT'
+      b.force_encoding(charset)
+    end
+  end
+  
+  # Reads a single byte from the body portion of a frame. Returns +nil+ if
+  # the character read is a {::Stomper::FrameSerializer::FRAME_TERMINATOR frame terminator}.
+  # @return [String,nil] the byte read from the stream.
+  def get_body_byte
+    #raise "Implementation varies by Ruby version"
+    c = @io.getc
+    c == ::Stomper::FrameSerializer::FRAME_TERMINATOR ? nil : c
+  end
+  
+  # Determines the content-type of a frame being sent to a broker. This
+  # version of the method is used by Ruby 1.9, and will use the encoding
+  # of the frame's body to help determine the appropriate charset. If the
+  # body's encoding is binary, no charset parameter will be included (even
+  # if one was manually set.) Otherwise, if the content-type is ommitted,
+  # a value of 'text/plain' is assumed and the encoding of the body is
+  # used as the charset parameter.
+  # @return [String] content-type and possibly charset of frame's body
+  def determine_content_type(frame)
+    ct = frame[:'content-type']
+    ct &&= ct.gsub(/\;\s*charset=\"?[a-zA-Z0-9!\#$&.+\-^_]+\"?/i, '')
+    enc = frame.body.encoding.name
+    text = (enc != 'ASCII-8BIT') || ct =~ /^text\//
+    ct = 'text/plain' if ct.nil? && text
+    ct && text ? "#{ct};charset=#{enc}" : ct
+  end
+  
+  # Determines the content-length of a frame being sent to a broker. For
+  # Ruby 1.9, this is the +bytesize+ of the frame's body.
+  # @return [Fixnum] byte-length of frame's body
+  def determine_content_length(frame)
+    frame.body.bytesize
+  end
+  
+  # Reads a line of text from the underlying IO. As per the Stomp 1.1
+  # specification, all header strings are encoded with UTF-8.
+  # @return [String] line of text read from IO, or '' if no text was read.
+  def get_header_line
+    (@io.gets || '').tap { |line| line.force_encoding('UTF-8') }
+  end
+end
+
+::Stomper::FrameSerializer.__send__(:include, ::Stomper::Support::Ruby1_9::FrameSerializer)

data/lib/stomper/support/1.9/headers.rb

@@ -0,0 +1,172 @@
+# -*- encoding: utf-8 -*-
+
+# The implementation of the {Stomper::Headers} class for Ruby 1.9
+module Stomper::Support::Ruby1_9::Headers
+  # Creates a new headers collection, initialized with the optional hash
+  # parameter.
+  # @param [Hash] headers
+  # @see #merge!
+  def initialize(headers={})
+    @values = {}
+    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+.
+  # @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+.
+  # @param [Hash] hash
+  def reverse_merge!(hash)
+    hash.each { |k, v|
+      self[k]= v unless has?(k)
+    }
+  end
+  
+  # Returns true if a header value has been set for the supplied header name.
+  # @param [Object] name the header name to test (will be converted using +to_sym+)
+  # @return [Boolean] true if the specified header name has been set, otherwise false.
+  # @example
+  #   header.has? 'content-type' #=> true
+  #   header.key? 'unset header' #=> false
+  #   header.include? 'content-length' #=> true
+  def has?(name)
+    @values.key? name.to_sym
+  end
+  alias :key? :has?
+  alias :include? :has?
+  
+  # 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 [Object] 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(:repeated_header) #=> [ 'principle value', '13', 'other value']
+  #   headers['name'] == headers.all(:name).first #=> true
+  def all_values(name)
+    @values[name.to_sym] || []
+  end
+  alias :all :all_values
+  
+  # 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 [Object] 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)
+    @values.delete 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 [Object] name the header name to associate with the supplied value (will be converted using +to_s+)
+  # @param [Object] 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
+    @values[name] ||= []
+    @values[name] << val
+    val
+  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 [Object] 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 [Object] name the header name to associate with the supplied value (will be converted using +to_sym+)
+  # @param [Object] 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
+    @values[name] = [val]
+    val
+  end
+  
+  # Iterates over each header name / value pair in the order in which the
+  # headers names were set.  If this collection contains repeated header names,
+  # the supplied block will receive those header names repeatedly, once
+  # for each value. If no block is supplied, then an +Enumerator+ is returned.
+  # All header names yielded through this method will be Strings and not
+  # the Symbol keys used internally.
+  #
+  # @yield [name, value] a header name and an associated value
+  # @yieldparam [String] name a header name
+  # @yieldparam [String] value a value associated with the header
+  # @return [Headers] +self+ if a block was supplied
+  # @return [Enumerator] a collection enumerator if no block was supplied
+  # @example
+  #   headers['name 1'] = 'value 1'
+  #   headers.append('name_2', 'value 2')
+  #   headers.append(:name_2, 42)
+  #   headers.each { |name, val| p "#{name} - #{v}" }
+  #   # name 1 - value 1
+  #   # name_2 - value 2
+  #   # name_2 - 42
+  #   #=> #<Stomper::Components::Headers:0x0000010289d6d8>
+  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
+  
+  # An array of header names ordered by when they were set.
+  # @return [Array<String>]
+  def names; @values.keys; end
+end
+
+::Stomper::Headers.__send__(:include, ::Stomper::Support::Ruby1_9::Headers)