stomper 1.0.0 → 2.0.0

data/CHANGELOG

@@ -1,20 +0,0 @@
-== 1.0 2010-09-24
-
-* Major additions to api including open-uri style interface.
-
-
-== 0.4 2010-04-23
-
-* Incremented minor version, beginning expansion.
-* Need to make a list of changes I want to make.
-
-
-== 0.3 2010-03-04
-
-* Added sleep to receive loop to prevent it from running "too tightly", not ideal.
-* Bit of cleanup in response to reek report.
-
-
-== 0.2 2009-11-20
-
-* Officially moved to "stomper" library.

data/README.rdoc

@@ -1,120 +0,0 @@
-=README
-
-Stomper is a library for connecting to and interacting with a message broker
-service that supports the Stomp 1.0 Protocol
-
-@see http://stomp.github.com/stomp-specification-1-0.html Stomp 1.0 Specification
-
-
-== OpenURI Example Usage
-
-    # A contrived example: Send two messages, receive them back
-    open("stomp://localhost/queue/testing") do |s|
-      s.puts "Hello World"
-      s.write "You may disagree, but I find this useful!"
-      messages = s.first(2) # => [ Message("Hello World"), Message("You may disagree...") ]
-    end
-
-    # Another example: connect, send a message to a destination and disconnect
-    open("stomp://localhost/topic/whatever") do |s|
-      s.put "PING!"
-    end
-
-    # Another example: connect, subscribe and process indefinitely
-    open("stomp://localhost/queue/worker") do |s|
-      s.each do |m|
-        logger.info "Received a message: #{m.body}"
-        # Do important work based on message
-      end
-    end
-
-    # Final example: connect, get a single message, and disconnect
-    open("stomp+ssl://localhost/queue/odd_jobs") do |s|
-      # you can use get, gets, read or first, they're all the same at
-      # this time and for the foreseeable future.
-      incoming_message = s.get
-      # Do some work on incoming_message
-    end
-
-This interface has been a goal of mine for this library for some time now.  I
-understand the value in a more typical socket object approach, and to that end
-the client interface still exists (albeit there's been quite a lot of refractoring.)
-However,
-
-    stomp = Stomper::Connection.new("stomp://localhost/")
-    stomp.subscribe("/queue/blather") do |m|
-      # ...
-    end
-    stomp.send("/topic/other", "Hello")
-
-just doesn't feel very Ruby-esque to me.  While the two methods for interacting with
-Stomper connections appear very different, +s+ in the OpenURI examples above
-really is a Stomper::Connection, but with some added extensions for handling
-+put+, +get+, +each+, and so forth.  One note: +read+, +get+ and +gets+ are
-all aliases for +first+.  Similarly, +puts+ is an alias for +put+.  However,
-+write+ is slightly different.  The message broker I most often use the
-STOMP protocol with is Apache ActiveMQ which, at the time of this writing, uses
-the absence or presence of a `content-length` header to discriminate between a
-JMS TextMessage and a BytesMessage.  The +put+ and +puts+ methods will force
-Stomper to omit that header, while +write+ will force its presence.
-
-== Example Usage
-
-    client = Stomper::Client.new("stomp://my_username:s3cr3tz@localhost:61613")
-    # Clients must be explicitly started to automatically receive incoming
-    # messages.
-    client.start
-
-    client.subscribe("/queue/hello") do |msg|
-      puts msg.body
-    end
-
-    # Send a simple message
-    client.send("/queue/hello", "hello world!")
-
-    # Send a message within a transaction.  This usage is new to stomper
-    # however, one can manually manage transactions as well.
-    client.transaction do |t|
-      t.send("/queue/hello", "a transactioned message")
-    end
-
-    # If the block provided to #transaction accepts a single parameter,
-    # the client yields the Transaction object to the block, otherwise
-    # the block is instance_eval'd within the Transaction object.
-    client.transaction do
-      send("/queue/hello", "a message you will never receive")
-      # Nested transactions, failures percolate up to parent transactions.
-      transaction do
-        send("/queue/hello", "because I am about to fail!")
-        raise "by forcing an error in a nested transaction"
-      end
-    end
-
-    # Later ...
-    client.stop
-    client.close
-
-== To-Do
-* Provide other methods for handling the receiver.
-* Provide the `pipe` method on Stomper::Client
-* Allow SSL verification if requested (option :verify_ssl?)
-* Re-evaluate how to handle a 'reliable' connection.
-
-== License
-
-Stomper is released under the Apache License 2.0
-
-== Pointless Backstory
-
-Stomper began its life as a mere fork of the stomp gem.
-However, as changes were made and desires grew, the fork began breaking
-API compatibility with the original gem, and thus Stomper was conceived.
-
-@see http://github.com/js/stomp Stomp
-
-== Other Stuff
-
-Primary Author:: Ian D. Eccles
-Source Repository:: http://github.com/iande/stomper
-Current Version:: 1.0.0
-Last Updated:: 2010-09-25

data/lib/stomper/client.rb

@@ -1,34 +0,0 @@
-module Stomper
-  module Client
-    # Sends a string message specified by +body+ to the appropriate stomp
-    # broker destination given by +destination+.  Additional headers for the
-    # message may be specified by the +headers+ hash where the key is the header
-    # property and the value is the corresponding property's value.  The
-    # keys of +headers+ may be symbols or strings.
-    #
-    # Examples:
-    #
-    #   client.send("/topic/whatever", "hello world")
-    #
-    #   client.send("/queue/some/destination", "hello world", { :persistent => true })
-    #
-    def send(destination, body, headers={})
-      transmit(Stomper::Frames::Send.new(destination, body, headers))
-    end
-
-    # Acknowledge to the stomp broker that a given message was received.
-    # The +id_or_frame+ parameter may be either the message-id header of
-    # the received message, or an actual instance of Stomper::Frames::Message.
-    # Additional headers may be specified through the +headers+ hash.
-    #
-    # Examples:
-    #
-    #   client.ack(received_message)
-    #
-    #   client.ack("message-0001-00451-003031")
-    #
-    def ack(id_or_frame, headers={})
-      transmit(Stomper::Frames::Ack.ack_for(id_or_frame, headers))
-    end
-  end
-end

data/lib/stomper/frame_reader.rb

@@ -1,73 +0,0 @@
-module Stomper
-  # Deserializes Stomp Frames from an input stream.
-  # Any object that responds appropriately to +getc+, +gets+
-  # and +read+ can be used as the input stream.
-  module FrameReader
-    # Receives the next Stomp Frame from the socket stream
-    def receive_frame
-      command = read_command
-      headers = read_headers
-      body = read_body(headers[:'content-length'])
-      Stomper::Frames::ServerFrame.build(command, headers, body)
-    end
-
-    private
-    def read_command
-      command = ''
-      while(command.size == 0)
-        command = gets(Stomper::Frames::LINE_DELIMITER).chomp!
-      end
-      command
-    end
-
-    def read_headers
-      headers = {}
-      loop do
-        line = gets(Stomper::Frames::LINE_DELIMITER).chomp!
-        break if line.size == 0
-        if (delim = line.index(':'))
-          headers[ line[0..(delim-1)].to_sym ] = line[(delim+1)..-1]
-        end
-      end
-      headers
-    end
-
-    def read_body(body_len)
-      body_len &&= body_len.strip.to_i
-      if body_len
-        read_fixed_body(body_len)
-      else
-        read_null_terminated_body
-      end
-    end
-
-    def read_null_terminated_body
-      body = ''
-      while next_byte = get_body_byte
-        body << next_byte.chr
-      end
-      body
-    end
-
-    def read_fixed_body(num_bytes)
-      body = read(num_bytes)
-      raise MalformedFrameError if get_body_byte
-      body
-    end
-
-    def get_body_byte
-      next_byte = get_ord
-      (next_byte == Stomper::Frames::TERMINATOR) ? nil : next_byte
-    end
-    
-    if String.method_defined?(:ord)
-      def get_ord
-        getc.ord
-      end
-    else
-      def get_ord
-        getc
-      end
-    end
-  end
-end

data/lib/stomper/frame_writer.rb

@@ -1,21 +0,0 @@
-module Stomper
-  # Serializes Stomp Frames to an output stream.
-  # Any object that responds appropriately to +write+
-  # can be used as the input stream.
-  module FrameWriter
-    # Writes a Stomp Frame to the underlying output stream.
-    def transmit_frame(frame)
-      write([ frame.command, Stomper::Frames::LINE_DELIMITER,
-        serialize_headers(frame.headers), Stomper::Frames::LINE_DELIMITER,
-        frame.body, Stomper::Frames::TERMINATOR.chr].join)
-    end
-
-    private
-    def serialize_headers(headers)
-      headers.inject("") do |acc, (key, val)|
-        acc << "#{key}#{Stomper::Frames::HEADER_DELIMITER}#{val}#{Stomper::Frames::LINE_DELIMITER}"
-        acc
-      end
-    end
-  end
-end

data/lib/stomper/frames.rb

@@ -1,39 +0,0 @@
-module Stomper
-  # This module holds all known encapsulations of
-  # frames that are part of the Stomp Protocol specification.
-  module Frames
-    HEADER_DELIMITER = ':'
-    TERMINATOR = 0
-    LINE_DELIMITER = "\n"
-
-    class IndirectFrame #:nodoc:
-      attr_reader :headers, :body
-
-      def initialize(headers={}, body=nil, command=nil)
-        @command = command && command.to_s.upcase
-        @headers = headers.dup
-        @body = body
-      end
-
-      def command
-        @command ||= self.class.name.split("::").last.upcase
-      end
-    end
-  end
-end
-
-require 'stomper/frames/client_frame'
-require 'stomper/frames/server_frame'
-require 'stomper/frames/abort'
-require 'stomper/frames/ack'
-require 'stomper/frames/begin'
-require 'stomper/frames/commit'
-require 'stomper/frames/connect'
-require 'stomper/frames/connected'
-require 'stomper/frames/disconnect'
-require 'stomper/frames/error'
-require 'stomper/frames/message'
-require 'stomper/frames/receipt'
-require 'stomper/frames/send'
-require 'stomper/frames/subscribe'
-require 'stomper/frames/unsubscribe'

data/lib/stomper/frames/abort.rb

@@ -1,10 +0,0 @@
-module Stomper
-  module Frames
-    # Encapsulates an "ABORT" frame from the Stomp Protocol.
-    class Abort < Stomper::Frames::ClientFrame
-      def initialize(transaction_id, headers={})
-        super(headers.merge(:transaction => transaction_id))
-      end
-    end
-  end
-end

data/lib/stomper/frames/ack.rb

@@ -1,25 +0,0 @@
-module Stomper
-  module Frames
-    # Encapsulates an "ACK" frame from the Stomp Protocol.
-    class Ack < Stomper::Frames::ClientFrame
-      def initialize(message_id, headers={})
-        super(headers.merge({ :'message-id' => message_id }))
-      end
-
-      # Creates a new Ack instance that corresponds to an acknowledgement
-      # of the supplied +message+, with any additional +headers+.  The
-      # +message+ parameter may be an instance of Stomper::Frames::Message, or
-      # a message id.  If +message+ is an instance of Stomper::Frames::Message
-      # and was exchanged as part of a transaction, the transaction header from
-      # +message+ will be injected into the newly created Ack object's headers.
-      def self.ack_for(message, headers = {})
-        if message.is_a?(Message)
-          headers[:transaction] = message.headers[:transaction] if message.headers[:transaction]
-          new(message.id, headers)
-        else
-          new(message.to_s)
-        end
-      end
-    end
-  end
-end

data/lib/stomper/frames/begin.rb

@@ -1,11 +0,0 @@
-module Stomper
-  module Frames
-    # Encapsulates a "BEGIN" frame from the Stomp Protocol.
-    class Begin < Stomper::Frames::ClientFrame
-      def initialize(transaction_id, headers={})
-        super(headers.merge(:transaction => transaction_id))
-        @headers[:transaction] = transaction_id
-      end
-    end
-  end
-end

data/lib/stomper/frames/client_frame.rb

@@ -1,89 +0,0 @@
-module Stomper
-  module Frames
-    # Encapsulates a client side frame for the Stomp Protocol.
-    class ClientFrame < IndirectFrame
-
-      # Creates a new ClientFrame instance with the specified +command+,
-      # +headers+ and +body+.
-      # If +headers+ includes a key of :generate_content_length, the
-      # associated value will determine if a 'content-length' header is automatically
-      # generated for this particular frame instance.  This key can be
-      # specified in the +headers+ parameter of any of the subclasses of ClientFrame,
-      # and it will be interpretted in the same fashion.
-      def initialize(headers={}, body=nil, command = nil)
-        @generate_content_length = headers.delete(:generate_content_length)
-        super(headers, body, command)
-      end
-
-      # If +bool+ is false or nil, this frame instance will not attempt to
-      # automatically generate a content-length header.  This is useful when
-      # dealing with ActiveMQ as a stomp message broker, which will treat incoming
-      # messages lacking a content-length header as +TextMessage+s and
-      # +BytesMessage+s if the header is present.  For more information see:
-      # {Apache ActiveMQ - Stomp}[http://activemq.apache.org/stomp.html]
-      def generate_content_length=(bool)
-        @generate_content_length=bool
-      end
-
-      # If generate_content_length= has been called on this instance, then the
-      # value supplied there is returned here.  Otherwise, we defer to the
-      # class method of the same name.
-      def generate_content_length?
-        @generate_content_length.nil? ? self.class.generate_content_length? : @generate_content_length
-      end
-
-
-      # Returns the headers for this frame, including a +content-length+ header
-      # set to the size of the current body, if +generate_content_length?+ is
-      # not false.
-      def headers
-        if generate_content_length? && @body && !@body.empty?
-          @headers[:'content-length'] ||= body_size
-        end
-        @headers
-      end
-
-      class << self
-        # Sets a class level setting for determining if a content-length header
-        # should automatically be generated.
-        def generate_content_length=(bool)
-          @generate_content_length = bool
-        end
-
-        # Returns the value passed to the class level generate_content_length=
-        # method, or true if no value has been set (thus, defaults to true.)
-        #
-        # The precedence for resolving whether or not a content-length header
-        # is generated by the +headers+ method is:
-        # check the instance setting,
-        # if it has not been set, defer to the class setting, if it hasn't
-        # been set, default to true.
-        def generate_content_length?
-          if @generate_content_length.nil?
-            @generate_content_length = true
-          end
-          @generate_content_length
-        end
-
-        def inherited(client_frame) #:nodoc:
-          declared_frames << { :class => client_frame, :command => client_frame.name.split("::").last.downcase.to_sym }
-        end
-
-        def declared_frames
-          @declared_frames ||= []
-        end
-      end
-
-      private
-      if String.method_defined?(:bytesize)
-        def body_size
-          @body.bytesize
-        end
-      else
-        def body_size
-          @body.size
-        end
-      end
-    end
-  end
-end