stomper 0.4 → 1.0.0

data/CHANGELOG

@@ -1,6 +1,13 @@
+== 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
 

data/README.rdoc

@@ -1,13 +1,62 @@
 =README
 
-Stomper is a library for connecting to and interacting with a message queue
-service that supports the {Stomp protocol}[http://stomp.codehaus.org/Protocol].
-Characteristics that distinguish it from other libraries, such the
-{stomp gem}[http://github.com/js/stomp], are:
+Stomper is a library for connecting to and interacting with a message broker
+service that supports the Stomp 1.0 Protocol
 
-* Transaction blocks with {transaction blocks}[link:classes/Stomper/Client.html#M000066]
-* Playing nice with Apache ActiveMQ by being able to {disable automatic content-length generation}[link:classes/Stomper/Frames/ClientFrame.html#M000014]
-* A receiver thread that can be bypassed by something else! (whatever that means)
+@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
 
@@ -46,6 +95,7 @@ Characteristics that distinguish it from other libraries, such the
     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.
@@ -56,13 +106,15 @@ Stomper is released under the Apache License 2.0
 
 == Pointless Backstory
 
-Stomper began its life as a mere fork of the {Stomp}[http://github.com/js/stomp]
-gem.  However, as changes were made and desires grew, the fork began breaking
+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:: 0.3.2
-Last Updated:: 2010-03-05
+Current Version:: 1.0.0
+Last Updated:: 2010-09-25

data/lib/stomper.rb

@@ -1,15 +1,27 @@
+require 'delegate'
 require 'uri'
 require 'io/wait'
 require 'socket'
 require 'thread'
 require 'monitor'
 require 'openssl'
+require 'stomper/uri'
 require 'stomper/frames'
+require 'stomper/frame_reader'
+require 'stomper/frame_writer'
+require 'stomper/sockets'
+require 'stomper/client'
+require 'stomper/transactor'
+require 'stomper/subscriber'
+require 'stomper/receiptor'
+require 'stomper/open_uri_interface'
+require 'stomper/threaded_receiver'
 require 'stomper/connection'
 require 'stomper/transaction'
 require 'stomper/subscription'
 require 'stomper/subscriptions'
-require 'stomper/client'
+require 'stomper/receipt_handlers'
 
 module Stomper
+  class MalformedFrameError < StandardError; end
 end

data/lib/stomper/client.rb

@@ -1,58 +1,5 @@
 module Stomper
-  # A high-level representation of a connection to a Stomp message broker.
-  # Instances of Client can be shared safely between threads, all mutating
-  # methods should be properly synchronized.  Interactions with the stomp
-  # message broker through instances of Client are generally simpler than
-  # doing so through instances of Connection.  Client instances do not require
-  # the use of Stomper::Frames::ClientFrame objects to transmit and receive
-  # information, instead relying on specific method calls to do so.
-  #
-  # === Example Usage
-  #   client = Stomper::Client.new("stomp://localhost:61613")
-  #   client.start
-  #
-  #   client.subscribe("/queue/target1") do |msg|
-  #     puts "Received Message: #{msg.body}"
-  #   end
-  #
-  #   client.send("/queue/target1", "this is a test")
-  #   client.send("/queue/target1", "this persists", { :persistent => true })
-  #
-  #   client.transaction do |t1|
-  #     t1.send("/queue/target1", "this will never be seen")
-  #     raise "Forced Exception"
-  #   end
-  #
-  #   client.unsubscribe("/queue/target1")
-  #
-  #   client.stop
-  #   client.close
-  #
-  class Client
-    attr_reader :connection, :subscriptions
-
-    # Creates a new Client instance that will connect to the stomp broker
-    # designated by the +uri+ parameter.  Additionally, +options+ may be
-    # specified as a hash, and are passed along to the underlying connection.
-    # For details on the format of +uri+ and the acceptable +options+, see
-    # Stomper::Connection.
-    def initialize(uri, options={})
-      # At this time we only bother with the BasicConnection.  We will need
-      # to write the ReliableConnection class to handle the particulars of reconnecting
-      # on a socket error.
-      #if options.has_key?(:max_retries) || options.delete(:reliable) { false }
-        #@connection = ReliableConnection.new(uri, options)
-      #else
-        @connection = Connection.new(uri, options)
-      #end
-      @subscriptions = Subscriptions.new
-      @send_lock = Mutex.new
-      @receive_lock = Mutex.new
-      @run_thread = nil
-      @receiving = false
-      @receiver_lock = Mutex.new
-    end
-
+  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
@@ -66,7 +13,7 @@ module Stomper
     #   client.send("/queue/some/destination", "hello world", { :persistent => true })
     #
     def send(destination, body, headers={})
-      transmit_frame(Stomper::Frames::Send.new(destination, body, headers))
+      transmit(Stomper::Frames::Send.new(destination, body, headers))
     end
 
     # Acknowledge to the stomp broker that a given message was received.
@@ -81,235 +28,7 @@ module Stomper
     #   client.ack("message-0001-00451-003031")
     #
     def ack(id_or_frame, headers={})
-      transmit_frame(Stomper::Frames::Ack.ack_for(id_or_frame, headers))
-    end
-
-    # Tells the stomp broker to commit a transaction named by the
-    # supplied +transaction_id+ parameter.  When used in conjunction with
-    # +begin+, and +abort+, a means for manually handling transactional
-    # message passing is provided.
-    #
-    # See Also: transaction
-    def commit(transaction_id)
-      transmit_frame(Stomper::Frames::Commit.new(transaction_id))
-    end
-
-    # Tells the stomp broker to abort a transaction named by the
-    # supplied +transaction_id+ parameter.  When used in conjunction with
-    # +begin+, and +commit+, a means for manually handling transactional
-    # message passing is provided.
-    #
-    # See Also: transaction
-    def abort(transaction_id)
-      transmit_frame(Stomper::Frames::Abort.new(transaction_id))
-    end
-
-    # Tells the stomp broker to begin a transaction named by the
-    # supplied +transaction_id+ parameter.  When used in conjunction with
-    # +commit+, and +abort+, a means for manually handling transactional
-    # message passing is provided.
-    #
-    # See also: transaction
-    def begin(transaction_id)
-      transmit_frame(Stomper::Frames::Begin.new(transaction_id))
-    end
-
-    # Creates a new Stomper::Transaction object and evaluates
-    # the supplied +block+ within a transactional context.  If
-    # the block executes successfully, the transaction is committed,
-    # otherwise it is aborted.  This method is meant to provide a less
-    # tedious approach to transactional messaging than the +begin+,
-    # +abort+ and +commit+ methods.
-    #
-    # See also: begin, commit, abort, Stomper::Transaction
-    def transaction(transaction_id=nil, &block)
-      begin
-        Stomper::Transaction.new(self, transaction_id, &block)
-      rescue Stomper::TransactionAborted
-        nil
-      end
-      self
-    end
-
-    # Subscribes to the specified +destination+, passing along
-    # the optional +headers+ inside the subscription frame.  When a message
-    # is received for this subscription, the supplied +block+ is
-    # called with the received message as its argument.
-    #
-    # Examples:
-    #
-    #   client.subscribe("/queue/test")  { |msg| puts "Got message: #{msg.body}" }
-    #
-    #   client.subscribe("/queue/test", :ack => 'client', 'id' => 'subscription-001') do |msg|
-    #     puts "Got message: #{msg.body}"
-    #   end
-    #
-    #   client.subscribe("/queue/test", :selector => 'cost > 5') do |msg|
-    #     puts "Got message: #{msg.body}"
-    #   end
-    #
-    # See also: unsubscribe, Stomper::Subscription
-    def subscribe(destination, headers={}, &block)
-      unless destination.is_a?(Subscription)
-        destination = Subscription.new(headers.merge(:destination => destination), &block)
-      end
-      @subscriptions << destination
-      transmit_frame(destination.to_subscribe)
-      self
-    end
-
-    # Unsubscribes from the specified +destination+.  The +destination+
-    # parameter may be either a string, such as "/queue/test", or Stomper::Subscription
-    # object.  If the optional +sub_id+ is supplied, the client will unsubscribe
-    # from the subscription with an id matching +sub_id+, regardless if the
-    # +destination+ parameter matches that of the registered subscription.  For
-    # this reason, it is vital that subscription ids, if manually specified, be
-    # unique.
-    #
-    # Examples:
-    #
-    #   client.unsubscribe("/queue/test")
-    #   # unsubscribes from all "naive" subscriptions for "/queue/test"
-    #
-    #   client.unsubscribe("/queue/does/not/matter", "sub-0013012031")
-    #   # unsubscribes from all subscriptions with id of "sub-0013012031"
-    #
-    #   client.unsubscribe(some_subscription)
-    #
-    # See also: subscribe, Stomper::Subscription
-    def unsubscribe(destination, sub_id=nil)
-      @subscriptions.remove(destination, sub_id).each do |unsub|
-        transmit_frame(unsub.to_unsubscribe)
-      end
-      self
-    end
-
-    # Starts the receiver for a Client instance.  This method
-    # must be manually invoked in order to receive frames sent
-    # by the stomp broker.  Be aware that a Client object's
-    # receiver runs in its own separate thread, and so may
-    # incur some performance penalties depending upon which
-    # Ruby environment this library is used with.  The receiver
-    # thread may be stopped by calling the +stop+ instance method.
-    # If the receiver is set to non-blocking (default behavior), the
-    # receiving thread will sleep for a number of seconds specified by the
-    # :receive_delay option between receive calls.
-    #
-    # The +opts+ parameter is a hash of options, and can include:
-    #
-    # [:block] Sets the receiver to either blocking if true (default: false)
-    # [:receive_delay] Sets the delay in seconds between receive calls when the receiver is non-blocking (default: 0.2)
-    #
-    # See also: stop, receiving?
-    def start(opts={})
-      @connection.connect unless connected?
-      do_start = false
-      @receiver_lock.synchronize do
-        do_start = !receiving?
-      end
-      if do_start
-        blocking = opts.delete(:block) { false }
-        sleep_time = opts.delete(:receive_delay) { 0.2 }
-        @receiving = true
-        @run_thread = Thread.new(blocking) do |block|
-          while receiving?
-            receive(block)
-            sleep(sleep_time) unless block
-          end
-        end
-      end
-      self
-    end
-
-    # Stops the receiver for a Client instance.  The methodology
-    # employed to stop the thread should be safe (it does not
-    # make use of Thread.kill)  It is also safe to +start+ and
-    # +stop+ the receiver thread multiple times, doing so does not
-    # interrupt the connection to the stomp broker under normal
-    # circumstances.  In the interest in proper performance, it is
-    # recommend that +stop+ be called when a Client instance is
-    # no longer needed (assuming the instance's receiver thread was
-    # started, of course.)
-    #
-    # See also: start, receiving?
-    def stop
-      do_stop = false
-      @receiver_lock.synchronize do
-        do_stop = receiving?
-      end
-      if do_stop
-        @receiving = false
-        @run_thread.join
-        @run_thread = nil
-      end
-      self
-    end
-
-    # Returns true if the receiver thread has been started
-    # by use of the +start+ command.  Otherwise, returns false.
-    #
-    # See also: start, stop
-    def receiving?
-      @receiving
-    end
-
-    # Receives the next available frame from the stomp broker, if
-    # one is available.  This method is regularly invoked by the
-    # receiver thread if it is created by the +start+ method; however,
-    # it may also be invoked manually if so desired, allowing one to
-    # by-pass the threaded implementation of receiving found in using
-    # +start+ and +stop+.  If the received frame is an instance of
-    # Stomper::Frames::Message, this method will invoke any subscriptions
-    # that are responsible for the message.
-    #
-    # Note: this method does not block under normal operation, as such
-    # +nil+ may be returned if there are no frames available from the
-    # stomp broker.
-    #
-    # See also: Stomper::Subscription
-    def receive(block=false)
-      msg = @receive_lock.synchronize { @connection.receive(block) }
-      @subscriptions.perform(msg) if msg.is_a?(Stomper::Frames::Message)
-      msg
-    end
-
-    # Returns true if the client is connected, false otherwise.
-    def connected?
-      @connection.connected?
-    end
-
-    # Establishes a socket connection to the stomp broker and transmits
-    # the initial "CONNECT" frame requred per the Stomp protocol.
-    def connect
-      @connection.connect
-    end
-
-    # Disconnects from the stomp broker politely by first transmitting
-    # a Stomper::Frames::Disconnect frame to the broker.
-    def disconnect
-      @connection.disconnect
-    end
-
-    alias close disconnect
-
-    protected
-    # We need to synchronize frame tranmissions to one at a time.
-    # My suspicion is that write/puts socket methods are not atomic, so if a message
-    # is started then interrupted and a new message is attempted, it will
-    # result in either a broken connection or an inconsistent state of our
-    # system.
-    def transmit_frame(frame)
-      @send_lock.synchronize do
-        @connection.transmit(frame)
-      end
-    end
-
-    private
-    # Toying with an idea, probably a very bad one!
-    def each # :nodoc:
-      while connected?
-        yield receive
-      end
+      transmit(Stomper::Frames::Ack.ack_for(id_or_frame, headers))
     end
   end
 end

data/lib/stomper/connection.rb

@@ -1,12 +1,24 @@
 module Stomper
-  # A low level connection to a Stomp message broker.
-  # Instances of Connection are not synchronized and thus not
-  # directly thread safe.  This is a deliberate decision as instances of
-  # Stomper::Client are the preferred way of communicating with
-  # Stomp message broker services.
+  # A connection to a Stomp message broker. This class includes the Client,
+  # Transactor, Subscriber, Receiptor and, in most cases, the ThreadedReceiver
+  # modules.
+  #
+  # @see Client
+  # @see Transactor
+  # @see Subscriber
+  # @see Receiptor
+  # @see ThreadedReceiver
   class Connection
     attr_reader :uri
-    attr_reader :socket
+
+    class << self
+      def connect(uri, opts={})
+        connex = new(uri, opts)
+        connex.connect
+        connex
+      end
+      alias_method :open, :connect
+    end
 
     # Creates a new connection to the Stomp broker specified by +uri+.
     # The +uri+ parameter may be either a URI object, or something that can
@@ -22,25 +34,14 @@ module Stomper
     # however, if SSL is not required, the schema is essentially ignored.
     # The default port for the 'stomp+ssl' schema is 61612, all other schemas
     # default to port 61613.
-    #
-    # The +opts+ parameter is a hash of options, and can include:
-    #
-    # [:connect_now] Immediately connect to the broker when a new instance is created (default: true)
-    def initialize(uri, opts = {})
-      connect_now = opts.delete(:connect_now) { true }
-      @uri = (uri.is_a?(URI) && uri) || URI.parse(uri)
-      @use_ssl = (@uri.scheme == "stomp+ssl")
-      @uri.host ||= 'localhost'
-      if @use_ssl
-        @uri.port ||= 61612
-        @ssl_context = OpenSSL::SSL::SSLContext.new
-        @ssl_context.verify_mode = OpenSSL::SSL::VERIFY_NONE
-      else
-        @uri.port ||= 61613
+    def initialize(uri, opts={})
+      if opts.delete(:threaded_receiver) { true }
+        extend ::Stomper::ThreadedReceiver
       end
-      @uri.freeze
+      @uri = (uri.is_a?(URI) && uri) || URI.parse(uri)
+      raise ArgumentError, 'Expected URI schema to be one of stomp or stomp+ssl' unless @uri.respond_to?(:create_socket)
       @connected = false
-      connect if connect_now
+      @writer = @reader = nil
     end
 
 
@@ -50,118 +51,70 @@ module Stomper
     #
     # See also: new
     def connect
-      stomp_socket = TCPSocket.open(@uri.host, @uri.port)
-      if @use_ssl
-        stomp_socket = OpenSSL::SSL::SSLSocket.new(stomp_socket, @ssl_context)
-        stomp_socket.sync_close = true
-        stomp_socket.connect
-      end
-      @socket = stomp_socket
+      @connected = false
+      @socket = @uri.create_socket
       transmit Stomper::Frames::Connect.new(@uri.user, @uri.password)
-      # Block until the first frame is received
-      connect_frame = receive(true)
-      @connected = connect_frame.instance_of?(Stomper::Frames::Connected)
+      @connected = receive.instance_of?(Stomper::Frames::Connected)
     end
 
     # Returns true when there is an open connection
     # established to the broker.
     def connected?
-      # FIXME: @socket.eof? appears to block or otherwise "wonk out", not sure
-      # why yet.
-      #!(@socket.closed? || @socket.eof?)
       @connected && @socket && !@socket.closed?
     end
 
-    # Immediately closes the connection to the broker.
-    #
-    # See also: disconnect
-    def close
-      @socket.close if @socket
-    ensure
-      @connected = false
-    end
-
     # Transmits a Stomper::Frames::Disconnect frame to the broker
     # then terminates the connection by invoking +close+.
-    #
-    # See also: close
     def disconnect
-      transmit(Stomper::Frames::Disconnect.new)
-    ensure
-      close
+      begin
+        @connected = false
+        transmit(Stomper::Frames::Disconnect.new)
+      ensure
+        close_socket
+      end
     end
 
-    # Converts an instance of Stomper::Frames::ClientFrame into
-    # a string conforming to the Stomp protocol and sends it
-    # to the broker.
-    def transmit(frame)
-      @socket.write(frame.to_stomp)
-    end
+    alias_method :close, :disconnect
 
-    # Receives a single Stomper::Frames::ServerFrame from the broker.
-    # If the frame received is known to the Stomper library, an instance of
-    # the appropriate subclass will be returned (eg: Stomper::Frames::Message),
-    # otherwise an instance of Stomper::Frames::ServerFrame is returned with
-    # the +command+ attribute set to the frame type.
-    # If the +blocking+ parameter is set to true, +receive+ will
-    # block until there is a frame available from the server, otherwise if no frame
-    # is currently available, +nil+ is returned.
-    #
-    # If an incoming message is malformed (not terminated with a NULL (\0)
-    # character, or has an incorrectly specified +content+-+length+ header,
-    # this method will raise an exception. [Type the exception, don't rely on
-    # a basic RuntimeError or whatever the default is.]
-    def receive(blocking=false)
-      command = ''
-      while (ready? || blocking) && (command = @socket.gets)
-        command.chomp!
-        break if command.size > 0
-      end
-      # If we got a command, continue on, potentially blocking until
-      # the entire message is received, otherwise we bail out now.
-      return nil if command.nil? || command.size == 0
-      headers = {}
-      while (line = @socket.gets)
-        line.chomp!
-        break if line.size == 0
-        delim = line.index(':')
-        if delim
-          key = line[0..(delim-1)]
-          val = line[(delim+1)..-1]
-          headers[key] = val
-        end
-      end
-      body = nil
-      # Have we been given a content length?
-      if headers['content-length']
-        body = @socket.read(headers['content-length'].to_i)
-        raise "Invalid message terminator or content-length header" if socket_c_to_i(@socket.getc) != 0
-      else
-        body = ''
-        # We read until we find the first nil character
-        while (c = @socket.getc)
-          # Both Ruby 1.8 and 1.9 should support this even though the behavior
-          # of getc is different between the two.  However, jruby is particular
-          # about this.  And that sucks.
-          break if socket_c_to_i(c) == 0
-          body << socket_c_to_chr(c)
-        end
+    # Transmits the a Stomp Frame to the connected Stomp broker by
+    # way of an internal FrameWriter.  If an exception is raised
+    # during the transmission, the connection will be forcibly closed
+    # and the exception will be propegated.
+    def transmit(frame)
+      begin
+        @socket.transmit_frame(frame)
+        frame
+      rescue Exception => ioerr
+        close_socket :lost_connection
+        raise ioerr
       end
-      # Messages should be forever immutable.
-      Stomper::Frames::ServerFrame.build(command, headers, body).freeze
     end
 
-    private
-    def ready?
-      (@use_ssl) ? @socket.io.ready? : @socket.ready?
+    # Receives the next Stomp Frame from an internal FrameReader that
+    # wraps the underlying Stomp broker connection.  If an exception is raised
+    # during the fetch, the connection will be forcibly closed and the exception
+    # will be propegated.
+    def receive()
+      begin
+        @socket.receive_frame
+      rescue Exception => ioerr
+        close_socket :lost_connection
+        raise ioerr
+      end
     end
 
-    def socket_c_to_i(c)
-      (c.respond_to?(:ord)) ? c.ord : c
+    # Immediately closes the connection to the broker, without the
+    # formality of sending a Disconnect frame.
+    #
+    # See also: disconnect
+    def close_socket(conx_state = :disconnected)
+      @socket.shutdown(2)
+      @socket.close if @socket
     end
 
-    def socket_c_to_chr(c)
-      (c.respond_to?(:chr)) ? c.chr : c
-    end
+    include ::Stomper::Client
+    include ::Stomper::Transactor
+    include ::Stomper::Subscriber
+    include ::Stomper::Receiptor
   end
 end