stomp 1.2.4 → 1.2.5

data/stomp.gemspec

@@ -5,17 +5,67 @@
 
 Gem::Specification.new do |s|
   s.name = %q{stomp}
-  s.version = "1.2.4"
+  s.version = "1.2.5"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Brian McCallister", "Marius Mathiesen", "Thiago Morello", "Guy M. Allard"]
-  s.date = %q{2012-06-25}
+  s.date = %q{2012-08-04}
   s.description = %q{Ruby client for the Stomp messaging protocol.  Note that this gem is no longer supported on rubyforge.}
   s.email = ["brianm@apache.org", "marius@stones.com", "morellon@gmail.com", "allard.guy.m@gmail.com"]
   s.executables = ["catstomp", "stompcat"]
   s.extra_rdoc_files = [
+    "CHANGELOG.rdoc",
     "LICENSE",
-    "README.rdoc"
+    "README.rdoc",
+    "examples/client11_ex1.rb",
+    "examples/client11_putget1.rb",
+    "examples/conn11_ex1.rb",
+    "examples/conn11_ex2.rb",
+    "examples/conn11_hb1.rb",
+    "examples/consumer.rb",
+    "examples/get11conn_ex1.rb",
+    "examples/get11conn_ex2.rb",
+    "examples/logexamp.rb",
+    "examples/logexamp_ssl.rb",
+    "examples/publisher.rb",
+    "examples/put11conn_ex1.rb",
+    "examples/putget11_rh1.rb",
+    "examples/slogger.rb",
+    "examples/ssl_uc1.rb",
+    "examples/ssl_uc1_ciphers.rb",
+    "examples/ssl_uc2.rb",
+    "examples/ssl_uc2_ciphers.rb",
+    "examples/ssl_uc3.rb",
+    "examples/ssl_uc3_ciphers.rb",
+    "examples/ssl_uc4.rb",
+    "examples/ssl_uc4_ciphers.rb",
+    "examples/ssl_ucx_default_ciphers.rb",
+    "examples/stomp11_common.rb",
+    "examples/topic_consumer.rb",
+    "examples/topic_publisher.rb",
+    "lib/client/utils.rb",
+    "lib/connection/heartbeats.rb",
+    "lib/connection/netio.rb",
+    "lib/connection/utf8.rb",
+    "lib/connection/utils.rb",
+    "lib/stomp.rb",
+    "lib/stomp/client.rb",
+    "lib/stomp/codec.rb",
+    "lib/stomp/connection.rb",
+    "lib/stomp/constants.rb",
+    "lib/stomp/errors.rb",
+    "lib/stomp/ext/hash.rb",
+    "lib/stomp/message.rb",
+    "lib/stomp/sslparams.rb",
+    "lib/stomp/version.rb",
+    "test/test_client.rb",
+    "test/test_codec.rb",
+    "test/test_connection.rb",
+    "test/test_connection1p.rb",
+    "test/test_helper.rb",
+    "test/test_message.rb",
+    "test/test_ssl.rb",
+    "test/tlogger.rb"
   ]
   s.files = [
     "CHANGELOG.rdoc",
@@ -50,6 +100,11 @@ Gem::Specification.new do |s|
     "examples/stomp11_common.rb",
     "examples/topic_consumer.rb",
     "examples/topic_publisher.rb",
+    "lib/client/utils.rb",
+    "lib/connection/heartbeats.rb",
+    "lib/connection/netio.rb",
+    "lib/connection/utf8.rb",
+    "lib/connection/utils.rb",
     "lib/stomp.rb",
     "lib/stomp/client.rb",
     "lib/stomp/codec.rb",

data/test/test_client.rb

@@ -4,6 +4,11 @@ $:.unshift(File.dirname(__FILE__))
 
 require 'test_helper'
 
+=begin
+
+  Main class for testing Stomp::Client instances.
+
+=end
 class TestClient < Test::Unit::TestCase
   include TestBase
   
@@ -18,12 +23,14 @@ class TestClient < Test::Unit::TestCase
     @client.close if @client.open? # allow tests to close
   end
 
+  # Test poll works.
   def test_poll_async
     # If the test 'hangs' here, Connection#poll is broken.
     m = @client.poll
     assert m.nil?
   end
 
+  # Test ACKs.
   def test_ack_api_works
     @client.publish make_destination, message_text, {:suppress_content_length => true}
 
@@ -41,6 +48,7 @@ class TestClient < Test::Unit::TestCase
     assert_not_nil receipt.headers['receipt-id']
   end unless ENV['STOMP_RABBIT']
 
+  # Test Client subscribe
   def test_asynch_subscribe
     received = false
     @client.subscribe(make_destination) {|msg| received = msg}
@@ -50,6 +58,7 @@ class TestClient < Test::Unit::TestCase
     assert_equal message_text, received.body
   end
 
+  # Test not ACKing messages.
   def test_noack
     @client.publish make_destination, message_text
 
@@ -71,17 +80,19 @@ class TestClient < Test::Unit::TestCase
     assert_equal received.headers['message-id'], received2.headers['message-id'] unless ENV['STOMP_RABBIT']
   end unless RUBY_ENGINE =~ /jruby/
 
+  # Test obtaining a RECEIPT via a listener.
   def test_receipts
     receipt = false
     @client.publish(make_destination, message_text) {|r| receipt = r}
     sleep 0.1 until receipt
-
+    assert_equal receipt.command, Stomp::CMD_RECEIPT
     message = nil
     @client.subscribe(make_destination) {|m| message = m}
     sleep 0.1 until message
     assert_equal message_text, message.body
   end
 
+  # Test requesting a receipt on disconnect.
   def test_disconnect_receipt
     @client.close :receipt => "xyz789"
     assert_nothing_raised {
@@ -91,6 +102,7 @@ class TestClient < Test::Unit::TestCase
     }
   end
 
+  # Test publish and immediate subscribe.
   def test_publish_then_sub
     @client.publish make_destination, message_text
     message = nil
@@ -100,12 +112,14 @@ class TestClient < Test::Unit::TestCase
     assert_equal message_text, message.body
   end
 
+  # Test that Client subscribe requires a block.
   def test_subscribe_requires_block
     assert_raise(RuntimeError) do
       @client.subscribe make_destination
     end
   end unless RUBY_ENGINE =~ /jruby/
 
+  # Test transaction publish.
   def test_transactional_publish
     @client.begin 'tx1'
     @client.publish make_destination, message_text, :transaction => 'tx1'
@@ -118,6 +132,7 @@ class TestClient < Test::Unit::TestCase
     assert_equal message_text, message.body
   end
 
+  # Test transaction publish and abort.
   def test_transaction_publish_then_rollback
     @client.begin 'tx1'
     @client.publish make_destination, "first_message", :transaction => 'tx1'
@@ -133,6 +148,7 @@ class TestClient < Test::Unit::TestCase
     assert_equal "second_message", message.body
   end unless RUBY_ENGINE =~ /jruby/
 
+  # Test transaction publish and abort, receive with new client.
   def test_transaction_ack_rollback_with_new_client
     @client.publish make_destination, message_text
 
@@ -185,6 +201,7 @@ class TestClient < Test::Unit::TestCase
     }
   end
 
+  # Test that subscription destinations must be unique for a Client.
   def test_raise_on_multiple_subscriptions_to_same_make_destination
     subscribe_dest = make_destination
     @client.subscribe(subscribe_dest) {|m| nil }
@@ -193,6 +210,7 @@ class TestClient < Test::Unit::TestCase
     end
   end
 
+  # Test that subscription IDs must be unique for a Client.
   def test_raise_on_multiple_subscriptions_to_same_id
     subscribe_dest = make_destination
     @client.subscribe(subscribe_dest, {'id' => 'myid'}) {|m| nil }
@@ -201,6 +219,7 @@ class TestClient < Test::Unit::TestCase
     end
   end
 
+  # Test that subscription IDs must be unique for a Client, mixed id specification.
   def test_raise_on_multiple_subscriptions_to_same_id_mixed
     subscribe_dest = make_destination
     @client.subscribe(subscribe_dest, {'id' => 'myid'}) {|m| nil }
@@ -209,6 +228,7 @@ class TestClient < Test::Unit::TestCase
     end
   end
 
+  # Test wildcard subscribe.  Primarily for AMQ.
   def  test_asterisk_wildcard_subscribe
     queue_base_name = make_destination
     queue1 = queue_base_name + ".a"
@@ -239,6 +259,7 @@ class TestClient < Test::Unit::TestCase
 
   end unless ENV['STOMP_NOWILD']
 
+  # Test wildcard subscribe with >.  Primarily for AMQ.
   def test_greater_than_wildcard_subscribe
     queue_base_name = make_destination + "."
     queue1 = queue_base_name + "foo.a"
@@ -272,6 +293,7 @@ class TestClient < Test::Unit::TestCase
     assert results.all?{|a| a == true }
   end unless ENV['STOMP_NOWILD'] || ENV['STOMP_DOTQUEUE']
 
+  # Test transaction with client side redilivery.
   def test_transaction_with_client_side_redelivery
     @client.publish make_destination, message_text
 
@@ -310,10 +332,12 @@ class TestClient < Test::Unit::TestCase
     @client.commit 'tx2'
   end
 
+  # Test that a connection frame is received.
   def test_connection_frame
   	assert_not_nil @client.connection_frame
   end unless RUBY_ENGINE =~ /jruby/
 
+  # Test basic unsubscribe.
   def test_unsubscribe
     message = nil
     dest = make_destination
@@ -353,6 +377,7 @@ class TestClient < Test::Unit::TestCase
     assert_equal message.headers['message-id'], message_copy.headers['message-id'], "header check" unless ENV['STOMP_RABBIT']
   end
 
+  # Test subscribe from a worker thread.
   def test_thread_one_subscribe
     msg = nil
     dest = make_destination
@@ -374,6 +399,7 @@ class TestClient < Test::Unit::TestCase
     assert_not_nil msg
   end unless RUBY_ENGINE =~ /jruby/
 
+  # Test subscribe from multiple worker threads.
   def test_thread_multi_subscribe
     #
     lock = Mutex.new
@@ -424,6 +450,7 @@ class TestClient < Test::Unit::TestCase
     assert_equal @max_msgs, msg_ctr
   end
 
+  # Test that methods detect no client connection is present.
   def test_closed_checks_client
     @client.close
     #

data/test/test_codec.rb

@@ -4,6 +4,11 @@ $:.unshift(File.dirname(__FILE__))
 
 require 'test_helper'
 
+=begin
+
+  Main class for testing Stomp::HeadreCodec methods.
+
+=end
 class TestCodec < Test::Unit::TestCase
   include TestBase
   
@@ -18,6 +23,7 @@ class TestCodec < Test::Unit::TestCase
     @conn.disconnect if @conn.open? # allow tests to disconnect
   end
 
+  # Test that the codec does nothing to strings that do not need encoding.
   def test_1000_check_notneeded
     test_data = [
       "a",
@@ -39,7 +45,7 @@ class TestCodec < Test::Unit::TestCase
     end
   end
 
-  #
+  # Test the basic encoding / decoding requirements.
   def test_1010_basic_encode_decode
     test_data = [
     	[ "\\\\", "\\" ],
@@ -62,7 +68,7 @@ class TestCodec < Test::Unit::TestCase
     end
   end
 
-  #
+  # Test more complex strings with the codec.
   def test_1020_fancier
     test_data = [
     	[ "a\\\\b", "a\\b" ],

data/test/test_connection.rb

@@ -4,6 +4,11 @@ $:.unshift(File.dirname(__FILE__))
 
 require 'test_helper'
 
+=begin
+
+  Main class for testing Stomp::Connection instances.
+
+=end
 class TestConnection < Test::Unit::TestCase
   include TestBase
   
@@ -18,10 +23,12 @@ class TestConnection < Test::Unit::TestCase
     @conn.disconnect if @conn.open? # allow tests to disconnect
   end
 
+  # Test basic connection creation.
   def test_connection_exists
     assert_not_nil @conn
   end
 
+  # Test asynchronous polling.
   def test_poll_async
     @conn.subscribe("/queue/do.not.put.messages.on.this.queue", :id => "a.no.messages.queue")
     # If the test 'hangs' here, Connection#poll is broken.
@@ -29,6 +36,7 @@ class TestConnection < Test::Unit::TestCase
     assert m.nil?
   end
 
+  # Test suppression of content length header.
   def test_no_length
     conn_subscribe make_destination
     #
@@ -47,6 +55,7 @@ class TestConnection < Test::Unit::TestCase
     end
   end unless ENV['STOMP_RABBIT']
 
+  # Test direct / explicit receive.
   def test_explicit_receive
     conn_subscribe make_destination
     @conn.publish make_destination, "test_stomp#test_explicit_receive"
@@ -54,12 +63,14 @@ class TestConnection < Test::Unit::TestCase
     assert_equal "test_stomp#test_explicit_receive", msg.body
   end
 
+  # Test asking for a receipt.
   def test_receipt
     conn_subscribe make_destination, :receipt => "abc"
     msg = @conn.receive
     assert_equal "abc", msg.headers['receipt-id']
   end
 
+  # Test asking for a receipt on disconnect.
   def test_disconnect_receipt
     @conn.disconnect :receipt => "abc123"
     assert_nothing_raised {
@@ -69,6 +80,7 @@ class TestConnection < Test::Unit::TestCase
     }
   end
 
+  # Test ACKs using symbols for header keys.
   def test_client_ack_with_symbol
     if @conn.protocol == Stomp::SPL_10
       @conn.subscribe make_destination, :ack => :client
@@ -87,6 +99,7 @@ class TestConnection < Test::Unit::TestCase
     }
   end
 
+  # Test a message with 0x00 embedded in the body.
   def test_embedded_null
     conn_subscribe make_destination
     @conn.publish make_destination, "a\0"
@@ -94,18 +107,21 @@ class TestConnection < Test::Unit::TestCase
     assert_equal "a\0" , msg.body
   end
 
+  # Test connection open checking.
   def test_connection_open?
     assert_equal true , @conn.open?
     @conn.disconnect
     assert_equal false, @conn.open?
   end
 
+  # Test connection closed checking.
   def test_connection_closed?
     assert_equal false, @conn.closed?
     @conn.disconnect
     assert_equal true, @conn.closed?
   end
 
+  # Test that methods detect a closed connection.
   def test_closed_checks_conn
     @conn.disconnect
     #
@@ -154,6 +170,7 @@ class TestConnection < Test::Unit::TestCase
     end
   end
 
+  # Test that we receive a Stomp::Message.
   def test_response_is_instance_of_message_class
     conn_subscribe make_destination
     @conn.publish make_destination, "a\0"
@@ -161,6 +178,7 @@ class TestConnection < Test::Unit::TestCase
     assert_instance_of Stomp::Message , msg
   end
 
+  # Test converting a Message to a string.
   def test_message_to_s
     conn_subscribe make_destination
     @conn.publish make_destination, "a\0"
@@ -168,10 +186,12 @@ class TestConnection < Test::Unit::TestCase
     assert_match /^<Stomp::Message headers=/ , msg.to_s
   end
   
+  # Test that a connection frame is present.
   def test_connection_frame
   	assert_not_nil @conn.connection_frame
   end
   
+  # Test messages with multiple line ends.
   def test_messages_with_multipleLine_ends
     conn_subscribe make_destination
     @conn.publish make_destination, "a\n\n"
@@ -184,6 +204,7 @@ class TestConnection < Test::Unit::TestCase
     assert_equal "b\n\na\n\n", msg_b.body
   end
 
+  # Test publishing multiple messages.
   def test_publish_two_messages
     conn_subscribe make_destination
     @conn.publish make_destination, "a\0"
@@ -211,6 +232,7 @@ class TestConnection < Test::Unit::TestCase
     assert_equal message, received.body
   end
 
+  # Test polling with a single thread.
   def test_thread_poll_one
     received = nil
     max_sleep = (RUBY_VERSION =~ /1\.8/) ? 10 : 1
@@ -231,6 +253,7 @@ class TestConnection < Test::Unit::TestCase
     assert_equal message, received.body
   end
 
+  # Test receiving with multiple threads.
   def test_multi_thread_receive
     lock = Mutex.new
     msg_ctr = 0
@@ -268,6 +291,7 @@ class TestConnection < Test::Unit::TestCase
     assert_equal @max_msgs, msg_ctr
   end unless RUBY_ENGINE =~ /jruby/
 
+  # Test polling with multiple threads.
   def test_multi_thread_poll
     #
     lock = Mutex.new
@@ -311,6 +335,7 @@ class TestConnection < Test::Unit::TestCase
     assert_equal @max_msgs, msg_ctr
   end unless RUBY_ENGINE =~ /jruby/
 
+  # Test using a nil body.
   def test_nil_body
     dest = make_destination
     assert_nothing_raised {
@@ -321,6 +346,7 @@ class TestConnection < Test::Unit::TestCase
     assert_equal "", msg.body    
   end
 
+  # Test transaction message sequencing.
   def test_transaction
     conn_subscribe make_destination
 
@@ -337,6 +363,7 @@ class TestConnection < Test::Unit::TestCase
     assert_equal "txn message", msg.body
   end
 
+  # Test duplicate subscriptions.
   def test_duplicate_subscription
     @conn.disconnect # not reliable
     @conn = Stomp::Connection.open(user, passcode, host, port, true) # reliable
@@ -348,6 +375,7 @@ class TestConnection < Test::Unit::TestCase
     end
   end
 
+  # Test nil 1.1 connection parameters.
   def test_nil_connparms
     @conn.disconnect
     #
@@ -356,6 +384,7 @@ class TestConnection < Test::Unit::TestCase
     end
   end
 
+  # Basic NAK test.
   def test_nack11p_0010
     if @conn.protocol == Stomp::SPL_10
       assert_raise Stomp::Error::UnsupportedProtocolError do

data/test/test_connection1p.rb

@@ -4,6 +4,11 @@ $:.unshift(File.dirname(__FILE__))
 
 require 'test_helper'
 
+=begin
+
+  Main class for testing Stomp::Connection instances, protocol level 1.1+.
+
+=end
 class TestConnection1P < Test::Unit::TestCase
   include TestBase
   
@@ -14,11 +19,13 @@ class TestConnection1P < Test::Unit::TestCase
   def teardown
     @conn.disconnect if @conn.open? # allow tests to disconnect
   end
-  #
+
+  # Test basic connection open.
   def test_conn_1p_0000
     assert @conn.open?
   end
-  #
+
+  # Test missing connect headers.
   def test_conn_1p_0010
     #
     cha = {:host => "localhost"}
@@ -31,7 +38,8 @@ class TestConnection1P < Test::Unit::TestCase
       conn = Stomp::Connection.open(user, passcode, host, port, false, 5, chb)
     end    
   end
-  #
+
+  # Test requesting only a 1.0 connection.
   def test_conn_1p_0020
     #
     cha = {:host => "localhost", "accept-version" => "1.0"}
@@ -43,7 +51,8 @@ class TestConnection1P < Test::Unit::TestCase
     end
     assert_equal conn.protocol, Stomp::SPL_10
   end
-  #
+
+  # Test requesting only a 1.1 connection.
   def test_conn_1p_0030
     #
     cha = {:host => "localhost", "accept-version" => "1.1"}
@@ -55,7 +64,8 @@ class TestConnection1P < Test::Unit::TestCase
     end
     assert_equal conn.protocol, Stomp::SPL_11
   end
-  #
+
+  # Test basic request for no heartbeats.
   def test_conn_1p_0040
     #
     cha = {:host => "localhost", "accept-version" => "1.1"}
@@ -68,8 +78,8 @@ class TestConnection1P < Test::Unit::TestCase
     end
     assert_equal conn.protocol, Stomp::SPL_11
   end
-  #
 
+  # Test malformed heartbeat header.
   def test_conn_1p_0050
     #
     cha = {:host => "localhost", "accept-version" => "1.1"}
@@ -80,7 +90,8 @@ class TestConnection1P < Test::Unit::TestCase
       conn = Stomp::Connection.open(user, passcode, host, port, false, 5, cha)
     end
   end
-  #
+
+  # Test malformed heartbeat header.
   def test_conn_11h_0060
     #
     cha = {:host => "localhost", "accept-version" => "1.1"}
@@ -91,7 +102,8 @@ class TestConnection1P < Test::Unit::TestCase
       conn = Stomp::Connection.open(user, passcode, host, port, false, 5, cha)
     end
   end
-  #
+
+  # Test a valid heartbeat header.
   def test_conn_1p_0070
     #
     cha = {:host => "localhost", "accept-version" => "1.1"}
@@ -106,7 +118,7 @@ class TestConnection1P < Test::Unit::TestCase
     assert conn.hbrecv_interval > 0
   end
 
-  #
+  # Test only sending heartbeats.
   def test_conn_1p_0080
     #
     cha = {:host => "localhost", "accept-version" => "1.1"}
@@ -124,7 +136,7 @@ class TestConnection1P < Test::Unit::TestCase
     hb_asserts_send(conn)
   end if ENV['STOMP_HB11LONG']
 
-  #
+  # Test only receiving heartbeats.
   def test_conn_1p_0090
     #
     cha = {:host => "localhost", "accept-version" => "1.1"}
@@ -143,7 +155,7 @@ class TestConnection1P < Test::Unit::TestCase
     hb_asserts_recv(conn)
   end if ENV['STOMP_HB11LONG']
 
-  #
+  # Test sending and receiving heartbeats.
   def test_conn_1p_0100
     #
     cha = {:host => "localhost", "accept-version" => "1.1"}
@@ -162,7 +174,7 @@ class TestConnection1P < Test::Unit::TestCase
     hb_asserts_both(conn)
   end if ENV['STOMP_HB11LONG']
 
-  #
+  # Test valid UTF8 data.
   def test_conn_1p_0110
     #
     cha = {:host => "localhost", "accept-version" => "1.1"}
@@ -193,7 +205,7 @@ class TestConnection1P < Test::Unit::TestCase
     conn.disconnect
   end
 
-  #
+  # Test invalid UTF8 data.
   def test_conn_1p_0120
     #
     cha = {:host => "localhost", "accept-version" => "1.1"}
@@ -230,6 +242,8 @@ class TestConnection1P < Test::Unit::TestCase
   # Repeated headers test. Currently:
   # - Apollo emits repeated headers for a 1.1 connection only
   # - RabbitMQ does not emit repeated headers under any circumstances
+  # - AMQ 5.6 does not emit repeated headers under any circumstances
+  # Pure luck that this runs against AMQ at present.
   def test_conn_1p_0120
     dest = make_destination
     msg = "payload: #{Time.now.to_f}"
@@ -253,6 +267,7 @@ class TestConnection1P < Test::Unit::TestCase
     @conn.unsubscribe dest, :id => sid
   end
 
+  # Test frozen headers.
   def test_conn_1p_0120
     dest = make_destination
     sid = @conn.uuid()
@@ -262,7 +277,7 @@ class TestConnection1P < Test::Unit::TestCase
     }
   end
 
-  #
+  # Test heartbeats with send and receive.
   def test_conn_1p_0130
     #
     cha = {:host => "localhost", "accept-version" => "1.1"}
@@ -281,7 +296,7 @@ class TestConnection1P < Test::Unit::TestCase
     hb_asserts_both(conn)
   end if ENV['STOMP_HB11LONG']
 
-  #
+  # Test heartbeats with send and receive.
   def test_conn_1p_0130
     #
     cha = {:host => "localhost", "accept-version" => "1.1"}
@@ -300,7 +315,7 @@ class TestConnection1P < Test::Unit::TestCase
     hb_asserts_both(conn)
   end if ENV['STOMP_HB11LONG']
 
-  #
+  # Test heartbeats with send and receive.
   def test_conn_1p_0140
     #
     cha = {:host => "localhost", "accept-version" => "1.1"}