stomper 0.4 → 1.0.0

data/lib/stomper/threaded_receiver.rb

@@ -0,0 +1,59 @@
+module Stomper
+  module ThreadedReceiver
+    def self.extended(base)
+      base.instance_eval do
+        @receiver_mutex = Mutex.new
+      end
+    end
+
+    # Starts the threaded receiver on a connection, calling receive
+    # on the connection repeatedly in a separate thread until the receiver
+    # is stopped or the connection is closed.
+    #
+    # @return self
+    # @see ThreadedReceiver#stop
+    # @see Connection#receive
+    # @see Connection#connected?
+    def start(opts={})
+      connect unless connected?
+      do_start = false
+      @receiver_mutex.synchronize do
+        do_start = !started?
+      end
+      if do_start
+        @started = true
+        @run_thread = Thread.new() do
+          while started? && connected?
+            receive
+          end
+        end
+      end
+      self
+    end
+
+    # Stops the threaded receiver on a connection thereby stopping further
+    # calls to receive.
+    #
+    # @return self
+    # @see ThreadedReceiver#start
+    # @see Connection#receive
+    # @see Connection#connected?
+    def stop
+      do_stop = false
+      @receiver_mutex.synchronize do
+        do_stop = started?
+      end
+      if do_stop
+        @started = false
+        @run_thread.join
+        @run_thread = nil
+      end
+      self
+    end
+
+    private
+    def started?
+      @started
+    end
+  end
+end

data/lib/stomper/transaction.rb

@@ -61,7 +61,7 @@ module Stomper
     # is an instance of Stomper::Client and is required so that the Transaction
     # instance has somewhere to forward +begin+, +ack+ and +abort+ methods
     # to.  If the +trans_id+ parameter is not specified, an id is automatically
-    # generated of the form "tx-{Time.now.to_f}".  This name can be accessed
+    # generated of the form +tx-<Time.now.to_f>+.  This name can be accessed
     # through the +id+ attribute and is used in naming the transaction to
     # the stomp broker.  If +block+ is given, the Transaction instance immediately
     # calls its perform method with the supplied +block+.
@@ -94,6 +94,9 @@ module Stomper
     # will raise a TransactionAborted exception if the +block+ evaluation fails.
     # This behavior allows for nesting transactions and ensuring that if a nested
     # transaction fails, so do all of its ancestors.
+    #
+    # @param [Proc] block A block of code that is evaluated as part of the transaction.
+    # @raise [TransactionAborted] raises an exception if the given block raises an exception
     def perform(&block) #:yields: transaction
       begin
         @client.begin(@id)
@@ -124,7 +127,7 @@ module Stomper
     # Similar to Stomper::Client#transaction, this method creates a new
     # Transaction object, nested inside of this one.  To prevent name
     # collisions, this method automatically generates a transaction id,
-    # if one is not specified, of the form "#{parent_transaction_id}-#{Time.now.to_f}.
+    # if one is not specified, of the form +<parent_transaction_id>-<Time.now.to_f>+.
     def transaction(transaction_id=nil,&block)
       # To get a transaction name guaranteed to not collide with this one
       # we will supply an explicit id to the constructor unless an id was
@@ -137,30 +140,32 @@ module Stomper
     # into the +headers+ hash, thus informing the stomp broker that the message
     # generated here is part of this transaction.
     def send(destination, body, headers={})
-      headers['transaction'] = @id
-      @client.send(destination, body, headers)
+      @client.send(destination, body, headers.merge({:transaction => @id }))
     end
 
     # Wraps the Stomper::Client#ack method, injecting a "transaction" header
     # into the +headers+ hash, thus informing the stomp broker that the message
     # acknowledgement is part of this transaction.
     def ack(message_or_id, headers={})
-      headers['transaction'] = @id
-      @client.ack(message_or_id, headers)
+      @client.ack(message_or_id, headers.merge({ :transaction => @id }))
     end
 
     # Aborts this transaction if it has not already been committed or aborted.
     # Note that it does so by raising a TransactionAborted exception, allowing
     # the +abort+ call to force any ancestral transactions to also fail.
     #
-    # See also: commit, committed?, aborted?
+    # @see Transaction#commit
+    # @see Transaction#committed?
+    # @see Transaction#aborted?
     def abort
       raise TransactionAborted, "transaction '#{@id}' aborted explicitly" if _abort
     end
 
     # Commits this transaction unless it has already been committed or aborted.
     #
-    # See also: abort, committed?, aborted?
+    # @see Transaction#abort
+    # @see Transaction#committed?
+    # @see Transaction#aborted?
     def commit
       # Guard against sending multiple commit messages to the server for a
       # single transaction.

data/lib/stomper/transactor.rb

@@ -0,0 +1,50 @@
+module Stomper
+  module Transactor
+    # 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: Stomper::ClientInterface::begin, Stomper::ClientInterface::commit,
+    # Stomper::ClientInterface::abort, Stomper::Transaction
+    def transaction(transaction_id=nil, &block)
+      begin
+        Stomper::Transaction.new(self, transaction_id, &block)
+      rescue Stomper::TransactionAborted
+        nil
+      end
+    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(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(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(Stomper::Frames::Begin.new(transaction_id))
+    end
+  end
+end

data/lib/stomper/uri.rb

@@ -0,0 +1,55 @@
+module URI
+  class STOMP < ::URI::Generic
+    # Got to love the magic of URI::Generic.
+    # By setting this constant, you ensure that all
+    # Stomp URI's have this port if one isn't specified.
+    DEFAULT_PORT = 61613
+
+    def initialize(*args)
+      super
+    end
+
+    def create_socket
+      ::Stomper::Sockets::TCP.new(self.host||'localhost', self.port)
+    end
+
+    def open(*args)
+      conx = Stomper::Connection.open(self, :threaded_receiver => false)
+      conx.extend Stomper::OpenUriInterface
+      if block_given?
+        begin
+          yield conx
+        ensure
+          conx.disconnect
+        end
+      end
+      conx
+    end
+  end
+
+  class STOMP_SSL < STOMP
+    DEFAULT_PORT = 61612
+
+    def initialize(*args)
+      super
+    end
+
+    # Creates a socket from the URI
+    def create_socket
+      ::Stomper::Sockets::SSL.new(self.host||'localhost', self.port)
+    end
+
+    # The +uri+ standard library resolves string URI's to concrete classes
+    # by matching the string's schema to the name of a subclass of URI::Generic.
+    # Ruby doesn't support '+' symbols in a class name, so the only way to handle
+    # schemas with odd characters is to override the "to_s" function of the class.
+    #
+    # Why do I get the feeling this might be a bad idea?
+    def self.to_s
+      "URI::STOMP+SSL"
+    end
+  end
+
+  @@schemes['STOMP'] = STOMP
+  @@schemes['STOMP+SSL'] = STOMP_SSL
+end

data/spec/client_spec.rb

@@ -2,179 +2,28 @@ require File.expand_path(File.join(File.dirname(__FILE__), 'spec_helper'))
 
 module Stomper
   describe Client do
+    class MockConcreteClient
+      include Stomper::Client
+    end
+
     before(:each) do
-      # For the client, we want to mock the underlying connection
-      @mock_connection = mock("connection")
-      @mock_connection.should_receive(:disconnect).with(no_args()).at_most(:once).and_return(nil)
-      Stomper::Connection.stub!(:new).and_return(@mock_connection)
-      @client = Client.new("stomp:///")
+      @client = MockConcreteClient.new
     end
     
     describe "expected interface" do
       it "should provide a send method" do
         @client.should respond_to(:send)
-        @mock_connection.should_receive(:transmit).with(an_instance_of(Stomper::Frames::Send)).twice.and_return(nil)
+        @client.should_receive(:transmit).with(an_instance_of(Stomper::Frames::Send)).twice.and_return(nil)
         @client.send("/queue/to", "message body", {:additional => 'header'})
         @client.send("/queue/to", "message body")
       end
-      it "should provide a subscribe method" do
-        @client.should respond_to(:subscribe)
-        @mock_connection.should_receive(:transmit).with(an_instance_of(Stomper::Frames::Subscribe)).twice.and_return(nil)
-        @client.subscribe("/queue/to", {:additional => 'header'})
-        @client.subscribe("/queue/to")
-      end
-      it "should provide an unsubscribe method" do
-        @client.should respond_to(:unsubscribe)
-        @mock_connection.should_receive(:transmit).with(an_instance_of(Stomper::Frames::Subscribe)).twice.and_return(nil)
-        @client.subscribe("/queue/to", {:id => 'subscription-id'})
-        @client.subscribe("/queue/to")
-        @mock_connection.should_receive(:transmit).with(an_instance_of(Stomper::Frames::Unsubscribe)).twice.and_return(nil)
-        @client.unsubscribe("/queue/to", 'subscription-id')
-        @client.unsubscribe("/queue/to")
-      end
       it "should provide an ack method" do
         @client.should respond_to(:ack)
-        @mock_connection.should_receive(:transmit).with(an_instance_of(Stomper::Frames::Ack)).exactly(3).times.and_return(nil)
+        @client.should_receive(:transmit).with(an_instance_of(Stomper::Frames::Ack)).exactly(3).times.and_return(nil)
         @client.ack("message-id", {:additional => "header"})
         @client.ack("message-id")
         @client.ack(Stomper::Frames::Message.new({:'message-id' => 'msg-001'}, "body"))
       end
-      it "should provide a begin method" do
-        @client.should respond_to(:begin)
-        @mock_connection.should_receive(:transmit).with(an_instance_of(Stomper::Frames::Begin)).once.and_return(nil)
-        @client.begin("tx-001")
-      end
-      it "should proivde an abort method" do
-        @client.should respond_to(:abort)
-        @mock_connection.should_receive(:transmit).with(an_instance_of(Stomper::Frames::Abort)).once.and_return(nil)
-        @client.abort("tx-001")
-      end
-      it "should provide a commit method" do
-        @client.should respond_to(:commit)
-        @mock_connection.should_receive(:transmit).with(an_instance_of(Stomper::Frames::Commit)).once.and_return(nil)
-        @client.commit("tx-001")
-      end
-      it "should provide a recieve method" do
-        @client.should respond_to(:receive)
-      end
-      it "should provide a disconnect method" do
-        @client.should respond_to(:disconnect)
-      end
-      it "should provide a close method" do
-        @client.should respond_to(:close)
-      end
-      it "should provide a connectivity test" do
-        @client.should respond_to(:connected?)
-      end
-      it "should provide a connect method" do
-        @client.should respond_to(:connect)
-      end
-    end
-
-    describe "threaded receiver" do
-      it "should respond to start and stop" do
-        @client.should respond_to(:start)
-        @client.should respond_to(:stop)
-        @client.should respond_to(:receiving?)
-      end
-      it "should only be receiving when it is started" do
-        @mock_connection.stub!(:receive).and_return(nil)
-        @mock_connection.should_receive(:connected?).any_number_of_times.and_return(true)
-        @client.receiving?.should be_false
-        @client.start
-        @client.receiving?.should be_true
-        @client.stop
-        @client.receiving?.should be_false
-      end
-      it "should allow for a blocking threaded receiver" do
-        @mock_connection.should_receive(:receive).with(true).at_least(:once).and_return(nil)
-        @mock_connection.should_receive(:connected?).any_number_of_times.and_return(true)
-        @client.receiving?.should be_false
-        @client.start(:block => true)
-        @client.receiving?.should be_true
-        @client.stop
-        @client.receiving?.should be_false
-      end
-
-    end
-
-    describe "subscribing to queue" do
-      before(:each) do
-        @message_sent = Stomper::Frames::Message.new({'destination' => "/queue/test"}, "test message")
-        @mock_connection.should_receive(:connected?).any_number_of_times.and_return(true)
-        @mock_connection.should_receive(:transmit).with(duck_type(:to_stomp)).at_least(:once).and_return(nil)
-        @mock_connection.should_receive(:receive).any_number_of_times.and_return(@message_sent)
-      end
-
-      it "should subscribe to a destination with a block" do
-        wait_for_message = true
-        @message_received = nil
-        @client.start
-        @client.subscribe("/queue/test") do |msg|
-          @message_received = msg
-          wait_for_message = false
-        end
-        true while wait_for_message
-        @client.stop
-        @message_received.should == @message_sent
-      end
-
-      it "should not unsubscribe from all destinations when a subscription id is provided" do
-        @client.subscribe("/queue/test", { 'id' => 'subscription-1' }) do |msg|
-          @message_received = msg
-        end
-        @client.subscribe("/queue/test") do |msg|
-          @message_received = msg
-        end
-        @client.subscribe("/queue/test", :id => 'subscription-2') do |msg|
-          @message_received = msg
-        end
-        @client.unsubscribe("/queue/test", 'subscription-1')
-        @client.subscriptions.size.should == 2
-      end
-
-      it "should not unsubscribe from non-naive subscriptions when only a destination is supplied" do
-        @client.subscribe("/queue/test", { 'id' => 'subscription-1' }) do |msg|
-          @message_received = msg
-        end
-        @client.subscribe("/queue/test") do |msg|
-          @message_received = msg
-        end
-        @client.subscribe("/queue/test") do |msg|
-          @message_received = msg
-        end
-        @client.unsubscribe("/queue/test")
-        @client.subscriptions.size.should == 1
-      end
-
-      # Due to the receiver running in a separate thread, this may not be correct?
-      it "should unsubscribe from a destination and receive no more messages" do
-        @mutex = Mutex.new
-        @last_message_received = nil
-        @client.start
-        @client.subscribe("/queue/test") do |msg|
-          @last_message_received = Time.now
-        end
-        true until @last_message_received
-        @client.unsubscribe("/queue/test")
-        @unsubscribed_at = Time.now
-        @client.stop
-        (@last_message_received < @unsubscribed_at).should be_true
-      end
-    end
-
-    describe "transactions" do
-      before(:each) do
-        @mock_connection.should_receive(:transmit).with(duck_type(:to_stomp)).at_least(:once).and_return(nil)
-      end
-
-      it "should provide a transaction method that generates a new Transaction" do
-        @evaluated = false
-        @client.transaction do |t|
-          @evaluated = true
-        end
-        @evaluated.should be_true
-      end
     end
   end
 end

data/spec/connection_spec.rb

@@ -3,10 +3,20 @@ require File.expand_path(File.join(File.dirname(__FILE__), 'shared_connection_ex
 
 module Stomper
   describe Connection do
-    before(:each) do
-      @connection = Connection.new("stomp:///", :connect_now => false)
+    describe "standard connection" do
+      before(:each) do
+        @connection = Connection.new("stomp:///")
+      end
+    
+      it_should_behave_like "All Client Connections"
     end
     
-    it_should_behave_like "All Client Connections"
+    describe "ssl connection" do
+      before(:each) do
+        @connection = Connection.new("stomp+ssl:///")
+      end
+      
+      it_should_behave_like "All Client Connections"
+    end
   end
 end

data/spec/frame_reader_spec.rb

@@ -0,0 +1,37 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+module Stomper
+  describe FrameReader do
+    before(:each) do
+      @input_stream = StringIO.new("", "w+")
+      @input_stream.send(:extend, Stomper::FrameReader)
+    end
+
+    it "should produce a stomper frame" do
+      @input_stream.string = "CONNECTED\n\n\0"
+      @input_stream.receive_frame.should be_an_instance_of(Stomper::Frames::Connected)
+    end
+
+    it "should read headers appropriately" do
+      @input_stream.string = "CONNECTED\nheader_1:a test value\nheader_2:another test value\nblather:47\n\nthe frame body\0"
+      @frame = @input_stream.receive_frame
+      @frame.headers.map { |(k,v)|
+        [k,v]
+      }.sort { |a, b| a.first.to_s <=> b.first.to_s }.should == [ [:blather, '47'], [:header_1, 'a test value'], [:header_2, 'another test value'] ]
+    end
+
+    it "should raise an exception when an invalid content-length is specified" do
+      @input_stream.string = "CONNECTED\ncontent-length:3\n\nsomething more than 3 bytes long\0"
+      lambda { @input_stream.receive_frame }.should raise_error(Stomper::MalformedFrameError)
+    end
+
+    it "should read the body of a message when a content length is specified" do
+      @input_stream.string = "CONNECTED\ncontent-length:6\n\na test\0followed by trailing nonsense"
+      @input_stream.receive_frame.body.should == "a test"
+    end
+    it "should read the body of a message when no content length is specified" do
+      @input_stream.string = "CONNECTED\n\na bit more text and no direction\0followed by trailing nonsense"
+      @input_stream.receive_frame.body.should == "a bit more text and no direction"
+    end
+  end
+end