stomp 1.2.4 → 1.2.5

data/CHANGELOG.rdoc

@@ -1,3 +1,14 @@
+== 1.2.5 20120804
+
+* Issue #48 any forks with modifications will be affected!
+* Source code restructured into individual files
+* Common indentation used throughout the source
+* Many method comments have been added
+* See notes in source regarding making methods private in the next release
+* See notes in source regarding removal of methods in the next release
+* Include examples and tests in rdoc generated during install
+* Issue #47 socket is open during retries
+
 == 1.2.4 20120625
 
 * Add ability for client to request flush on write to the connection (Issue #45)

data/README.rdoc

@@ -10,35 +10,16 @@ An implementation of the Stomp protocol for Ruby. See:
 
 ===New
 
-* Gem version 1.2.2.  Stomp 1.1 heartbeat fix, autoflush capability, miscellaneous fixes
-* Gem version 1.2.3.  Miscellaneous fixes, see changelog for details.
-* Gem version 1.2.2.  Performance and more SSL enhancements.
+* Gem version 1.2.5. Restructure. Forks with modifcations will be affected. See _CHANGELOG.rdoc_ for details.
+* Gem version 1.2.4. Stomp 1.1 heartbeat fix, autoflush capability, miscellaneous fixes.
+* Gem version 1.2.3. Miscellaneous fixes, see changelog for details.
+* Gem version 1.2.2. Performance and more SSL enhancements.
 * Full support of SSL certificates is announced as of gem version 1.2.1.
 * Support of Stomp protocol level 1.1 is announced as of gem version 1.2.0.
 
-See the change log for details.
+See _CHANGELOG.rdoc_ for details.
 
-===Example Usage
-
-    client = Stomp::Client.new("test", "user", "localhost", 61613)
-    client.send("/queue/mine", "hello world!")
-    client.subscribe("/queue/mine") do |msg|
-      p msg
-    end
-
-===Failover + SSL Example URL Usage
-
-    options = "initialReconnectDelay=5000&randomize=false&useExponentialBackOff=false"
-    
-    # remotehost1 uses SSL, remotehost2 doesn't
-    client = Stomp::Client.new("failover:(stomp+ssl://login1:passcode1@remotehost1:61612,stomp://login2:passcode2@remotehost2:61613)?#{options}")
-    
-    client.publish("/queue/mine", "hello world!")
-    client.subscribe("/queue/mine") do |msg|
-      p msg
-    end
-
-===Hash Login Example Usage
+===Hash Login Example Usage (this is the recommended login technique)
 
   hash = {
       :hosts => [
@@ -67,8 +48,39 @@ See the change log for details.
     # for connection
     connection = Stomp::Connection.new(hash)
     
+===Positional Parameter Usage
+
+    client = Stomp::Client.new("test", "user", "localhost", 61613)
+    client.send("/queue/mine", "hello world!")
+    client.subscribe("/queue/mine") do |msg|
+      p msg
+    end
+
+===Stomp URL Usage
+
+    # Stomp URL :
+    A Stomp URL must begin with 'stomp://' and can be in one of the following forms:
+
+    stomp://host:port
+    stomp://host.domain.tld:port
+    stomp://login:passcode@host:port
+    stomp://login:passcode@host.domain.tld:port
+   
+    e.g. c = Stomp::Client.new(urlstring)
+
+===Failover + SSL Example URL Usage
+
+    options = "initialReconnectDelay=5000&randomize=false&useExponentialBackOff=false"
+    
+    # remotehost1 uses SSL, remotehost2 doesn't
+    client = Stomp::Client.new("failover:(stomp+ssl://login1:passcode1@remotehost1:61612,stomp://login2:passcode2@remotehost2:61613)?#{options}")
+    
+    client.publish("/queue/mine", "hello world!")
+    client.subscribe("/queue/mine") do |msg|
+      p msg
+    end
 
-===Hstorical Information
+===Historical Information
 
 Up until March 2009 the project was maintained and primarily developed by Brian McCallister. 
 

data/Rakefile

@@ -37,6 +37,9 @@ begin
     gem.authors = ["Brian McCallister", 'Marius Mathiesen', 'Thiago Morello',
         'Guy M. Allard']
     gem.add_development_dependency "rspec", '>= 2.3'
+    gem.extra_rdoc_files = [ "README.rdoc", "CHANGELOG.rdoc", "LICENSE",
+      "lib/**/*.rb", "examples/**/*.rb",
+      "test/**/*.rb" ]
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError

data/bin/catstomp

@@ -28,46 +28,46 @@ require 'stomp'
 #
 begin
 
-    if ARGV[0] == '-h' || ARGV[0] == '--help'
-      $stdout.puts
-      $stdout.puts 'Usage: catstomp DESTINATION'
-      $stdout.puts
-      $stdout.puts 'Publishes STDIN to the desired stomp destination'
-      $stdout.puts
-      $stdout.puts 'Example: ls | catstomp /topic/foo'
-      $stdout.puts
-      $stdout.puts 'Defaults:'
-      $stdout.puts "DESTINATION\t/topic/default"
-      $stdout.puts "STOMP_HOST\tlocalhost"
-      $stdout.puts "STOMP_PORT\t61613"
-      $stdout.puts "STOMP_USER"
-      $stdout.puts "STOMP_PASSWORD"
-      $stdout.puts
-      $stdout.puts 'You can override the stomp host, port, user, or password through environment variables'
-      exit 0
-    end
+  if ARGV[0] == '-h' || ARGV[0] == '--help'
+    $stdout.puts
+    $stdout.puts 'Usage: catstomp DESTINATION'
+    $stdout.puts
+    $stdout.puts 'Publishes STDIN to the desired stomp destination'
+    $stdout.puts
+    $stdout.puts 'Example: ls | catstomp /topic/foo'
+    $stdout.puts
+    $stdout.puts 'Defaults:'
+    $stdout.puts "DESTINATION\t/topic/default"
+    $stdout.puts "STOMP_HOST\tlocalhost"
+    $stdout.puts "STOMP_PORT\t61613"
+    $stdout.puts "STOMP_USER"
+    $stdout.puts "STOMP_PASSWORD"
+    $stdout.puts
+    $stdout.puts 'You can override the stomp host, port, user, or password through environment variables'
+    exit 0
+  end
 
-    @port = 61613
-    @host = "localhost"
-    @user = ENV["STOMP_USER"];
-    @password = ENV["STOMP_PASSWORD"]
+  @port = 61613
+  @host = "localhost"
+  @user = ENV["STOMP_USER"];
+  @password = ENV["STOMP_PASSWORD"]
 
-    @host = ENV["STOMP_HOST"] if ENV["STOMP_HOST"] != nil
-    @port = ENV["STOMP_PORT"] if ENV["STOMP_PORT"] != nil
+  @host = ENV["STOMP_HOST"] if ENV["STOMP_HOST"] != nil
+  @port = ENV["STOMP_PORT"] if ENV["STOMP_PORT"] != nil
 
-    @destination = "/topic/default"
-    @destination = $*[0] if $*[0] != nil
+  @destination = "/topic/default"
+  @destination = $*[0] if $*[0] != nil
 
-    $stderr.print "Connecting to stomp://#{@host}:#{@port} as #{@user}\n"
-    @conn = Stomp::Connection.open(@user, @password, @host, @port, true)
-    $stderr.print "Sending input to #{@destination}\n"
+  $stderr.print "Connecting to stomp://#{@host}:#{@port} as #{@user}\n"
+  @conn = Stomp::Connection.open(@user, @password, @host, @port, true)
+  $stderr.print "Sending input to #{@destination}\n"
 
-    @headers = {'persistent'=>'false'}
-    @headers['reply-to'] = $*[1] if $*[1] != nil
+  @headers = {'persistent'=>'false'}
+  @headers['reply-to'] = $*[1] if $*[1] != nil
 
-    STDIN.each_line { |line|
-        @conn.publish @destination, line, @headers
-    }
+  STDIN.each_line { |line|
+      @conn.publish @destination, line, @headers
+  }
 
 rescue
 end

data/bin/stompcat

@@ -28,47 +28,47 @@ require 'stomp'
 #
 begin
 
-   if ARGV[0] == '-h' || ARGV[0] == '--help'
-      $stdout.puts
-      $stdout.puts 'Usage: stompcat DESTINATION'
-      $stdout.puts
-      $stdout.puts 'Receives data from a stomp destination and outputs it to STDOUT'
-      $stdout.puts
-      $stdout.puts 'Example: stompcat /topic/foo'
-      $stdout.puts
-      $stdout.puts 'Defaults:'
-      $stdout.puts "DESTINATION\t/topic/default"
-      $stdout.puts "STOMP_HOST\tlocalhost"
-      $stdout.puts "STOMP_PORT\t61613"
-      $stdout.puts "STOMP_USER\t"
-      $stdout.puts "STOMP_PASSWORD\t"
-      $stdout.puts
-      $stdout.puts 'You can override the host, port, user, or password through environment variables'
-      exit 0
-    end
+ if ARGV[0] == '-h' || ARGV[0] == '--help'
+    $stdout.puts
+    $stdout.puts 'Usage: stompcat DESTINATION'
+    $stdout.puts
+    $stdout.puts 'Receives data from a stomp destination and outputs it to STDOUT'
+    $stdout.puts
+    $stdout.puts 'Example: stompcat /topic/foo'
+    $stdout.puts
+    $stdout.puts 'Defaults:'
+    $stdout.puts "DESTINATION\t/topic/default"
+    $stdout.puts "STOMP_HOST\tlocalhost"
+    $stdout.puts "STOMP_PORT\t61613"
+    $stdout.puts "STOMP_USER\t"
+    $stdout.puts "STOMP_PASSWORD\t"
+    $stdout.puts
+    $stdout.puts 'You can override the host, port, user, or password through environment variables'
+    exit 0
+  end
 
-    @port = 61613
-    @host = "localhost"
-    @user = ENV["STOMP_USER"];
-    @password = ENV["STOMP_PASSWORD"]
+  @port = 61613
+  @host = "localhost"
+  @user = ENV["STOMP_USER"];
+  @password = ENV["STOMP_PASSWORD"]
 
-    @host = ENV["STOMP_HOST"] if ENV["STOMP_HOST"] != nil
-    @port = ENV["STOMP_PORT"] if ENV["STOMP_PORT"] != nil
+  @host = ENV["STOMP_HOST"] if ENV["STOMP_HOST"] != nil
+  @port = ENV["STOMP_PORT"] if ENV["STOMP_PORT"] != nil
 
-    @destination = "/topic/default"
-    @destination = $*[0] if $*[0] != nil
+  @destination = "/topic/default"
+  @destination = $*[0] if $*[0] != nil
 
-    $stderr.print "Connecting to stomp://#{@host}:#{@port} as #{@user}\n"
-    @conn = Stomp::Connection.open(@user, @password, @host, @port, true)
-    $stderr.print "Getting output from #{@destination}\n"
+  $stderr.print "Connecting to stomp://#{@host}:#{@port} as #{@user}\n"
+  @conn = Stomp::Connection.open(@user, @password, @host, @port, true)
+  $stderr.print "Getting output from #{@destination}\n"
 
-    @conn.subscribe(@destination, { :ack =>"client" })
-    while true
-        @msg = @conn.receive
-        $stdout.print @msg.body
-        $stdout.flush
-        @conn.ack @msg.headers["message-id"]
-    end
+  @conn.subscribe(@destination, { :ack =>"client" })
+  while true
+      @msg = @conn.receive
+      $stdout.print @msg.body
+      $stdout.flush
+      @conn.ack @msg.headers["message-id"]
+  end
 
 rescue
 end

data/examples/client11_ex1.rb

@@ -11,70 +11,79 @@ else
   require "stomp11_common"
 end
 include Stomp11Common
+
 #
-# Stomp 1.1 Client Example 1
-# ==============================
+# == Stomp 1.1 Client Example 1
 #
 # Purpose: to demonstrate a connect and disconnect sequence using Stomp 1.1
 # with the Stomp#Client interface.
 #
-# Note: Stomp#Client does not provide a positional set of parameters that
-# contain a 'connect_headers' parameter.  To use the Stomp#Client interface
-# you _must_ use a 'hashed' set of parameters.
-#
-# Create connection headers
-# =========================
-#
-# The two headers used here are _required_ by the specification.
-#
-client_hdrs = {"accept-version" => "1.1",    # Demand a 1.1 connection (use a CSV list if you will consider multiple versions)
+class Client11Example1
+  # Initialize.
+  def initialize
+  end
+  # Run example.
+  def run
+    # Note: Stomp#Client does not provide a positional set of parameters that
+    # contain a 'connect_headers' parameter.  To use the Stomp#Client interface
+    # you _must_ use a 'hashed' set of parameters.
+    #
+    # Create connection headers
+    # =========================
+    #
+    # The two headers used here are _required_ by the specification.
+    #
+    client_hdrs = {"accept-version" => "1.1",    # Demand a 1.1 connection (use a CSV list if you will consider multiple versions)
       "host" => virt_host,                   # The 1.1 vhost (could be different than connection host)
     }                                        # No heartbeats here:  there will be none for this connection
-#
-# Create the connect hash.
-# ========================
-#
-client_hash = { :hosts => [ 
-      {:login => login, :passcode => passcode, :host => host, :port => port},
+    #
+    # Create the connect hash.
+    # ========================
+    #
+    client_hash = { :hosts => [
+        {:login => login, :passcode => passcode, :host => host, :port => port},
       ],
       :connect_headers => client_hdrs,
     }
+    #
+    # Get a connection
+    # ================
+    #
+    client = Stomp::Client.new(client_hash)
+    puts "Client Connect complete"
+    #
+    # Let's just do some sanity checks, and look around.
+    #
+    raise "Connection failed!!" unless client.open?
+    #
+    # Is this really a 1.1 conection? (For clients, 'protocol' is a public method.
+    # The value will be '1.0' for those types of connections.)
+    #
+    raise "Unexpected protocol level" if client.protocol() != Stomp::SPL_11
+    #
+    # The broker _could_ have returned an ERROR frame (unlikely).
+    # For clients, 'connection_frame' is a public method.
+    #
+    raise "Connect error: #{client.connection_frame().body}" if client.connection_frame().command == Stomp::CMD_ERROR
+    #
+    # Examine the CONNECT response (the connection_frame()).
+    #
+    puts "Connected Headers required to be present:"
+    puts "Connect version - \t#{client.connection_frame().headers['version']}"
+    puts
+    puts "Connected Headers that are optional:"
+    puts "Connect server - \t\t#{client.connection_frame().headers['server']}"
+    puts "Session ID - \t\t\t#{client.connection_frame().headers['session']}"
+    puts "Server requested heartbeats - \t#{client.connection_frame().headers['heart-beat']}"
+    #
+    # Finally close
+    # =============
+    #
+    client.close   # Business as usual, just like 1.0
+    puts "Client close complete"
+  end
+end
 #
-# Get a connection
-# ================
-#
-client = Stomp::Client.new(client_hash)
-puts "Client Connect complete"
-#
-# Let's just do some sanity checks, and look around.
-#
-raise "Connection failed!!" unless client.open?
-#
-# Is this really a 1.1 conection? (For clients, 'protocol' is a public method.
-# The value will be '1.0' for those types of connections.)
-#
-raise "Unexpected protocol level" if client.protocol() != Stomp::SPL_11
-#
-# The broker _could_ have returned an ERROR frame (unlikely).
-# For clients, 'connection_frame' is a public method.
-#
-raise "Connect error: #{client.connection_frame().body}" if client.connection_frame().command == Stomp::CMD_ERROR
-#
-# Examine the CONNECT response (the connection_frame()).
-#
-puts "Connected Headers required to be present:"
-puts "Connect version - \t#{client.connection_frame().headers['version']}"
-puts
-puts "Connected Headers that are optional:"
-puts "Connect broker - \t\t#{client.connection_frame().headers['broker']}"
-puts "Session ID - \t\t\t#{client.connection_frame().headers['session']}"
-puts "Server requested heartbeats - \t#{client.connection_frame().headers['heart-beat']}"
-#
-# Finally close
-# =============
-#
-client.close   # Business as usual, just like 1.0
-puts "Client close complete"
-
-
+e = Client11Example1.new
+e.run
 

data/examples/client11_putget1.rb

@@ -11,49 +11,61 @@ else
   require "stomp11_common"
 end
 include Stomp11Common
+
 #
-# Stomp 1.1 Client Putter/Getter Example 1
-# ========================================
+# == Stomp 1.1 Client Putter/Getter Example 1
 #
 # This is much like sending and receiving with a Stomp::Connection.
 #
-client_hdrs = {"accept-version" => "1.1",    # Demand a 1.1 connection (use a CSV list if you will consider multiple versions)
+class Client11PutGet1
+  # Initialize.
+  def initialize
+  end
+  # Run example.
+  def run
+    #
+    client_hdrs = {"accept-version" => "1.1",    # Demand a 1.1 connection (use a CSV list if you will consider multiple versions)
       "host" => virt_host,                 # The 1.1 vhost (could be different than connection host)
     }                                      # No heartbeats here:  there will be none for this connection
-#
-client_hash = { :hosts => [ 
-      {:login => login, :passcode => passcode, :host => host, :port => port},
+    #
+    client_hash = { :hosts => [
+        {:login => login, :passcode => passcode, :host => host, :port => port},
       ],
       :connect_headers => client_hdrs,
     }
+    #
+    client = Stomp::Client.new(client_hash)
+    puts "Client Connect complete"
+    #
+    raise "Unexpected protocol level" if client.protocol() != Stomp::SPL_11
+    #
+    qname = "/queue/client.nodea.nodeb.nodec"
+    data = "message payload: #{Time.now.to_f}"
+    headers = {}
+    # Send it
+    client.publish qname, data
+    puts "Publish complete"
+    # Receive
+    uuid = client.uuid() # uuid for Stomp::Client is a public method
+    message = nil
+    # Clients must pass a receive block.  This is business as usual, required for 1.0.
+    # For 1.1, a unique subscription id is required.
+    client.subscribe(qname, {'id' => uuid}) {|m|
+    message = m
+    }
+    sleep 0.1 until message # Wait for completion
+    puts "Subscribe and receive complete"
+    # Unsubscribe, with the unique id
+    client.unsubscribe qname,  {'id' => uuid}
+    # Sanity checks for this example ....
+    raise "Unexpected data" if data != message.body
+    raise "Bad subscription header" if uuid != message.headers['subscription']
+    #
+    client.close   # Business as usual, just like 1.0
+    puts "Client close complete"
+  end
+end
 #
-client = Stomp::Client.new(client_hash)
-puts "Client Connect complete"
-#
-raise "Unexpected protocol level" if client.protocol() != Stomp::SPL_11
-#
-qname = "/queue/client.nodea.nodeb.nodec"
-data = "message payload: #{Time.now.to_f}"
-headers = {}
-# Send it
-client.publish qname, data
-# Receive 
-uuid = client.uuid() # uuid for Stomp::Client is a public method
-message = nil
-# Clients must pass a receive block.  This is business as usual, required for 1.0.
-# For 1.1, a unique subscription id is required.
-client.subscribe(qname, {'id' => uuid}) {|m| 
-  message = m
-}
-sleep 0.1 until message # Wait for completion
-# Unsubscribe, with the unique id
-client.unsubscribe qname,  {'id' => uuid}
-# Sanity checks for this example ....
-raise "Unexpected data" if data != message.body
-raise "Bad subscription header" if uuid != message.headers['subscription']
-#
-client.close   # Business as usual, just like 1.0
-puts "Client close complete"
-
-
+e = Client11PutGet1.new
+e.run
 

data/examples/conn11_ex1.rb

@@ -11,13 +11,13 @@ else
   require "stomp11_common"
 end
 include Stomp11Common
+
 #
-# Stomp 1.1 Connection Example 1
-# ==============================
+# == Stomp 1.1 Connection Example 1
 #
 # Purpose: to demonstrate a connect and disconnect sequence using Stomp 1.1.
 #
-# Note: this example assumes that you have at least the 1.2.0 gem release 
+# Note: this example assumes that you have at least the 1.2.0 gem release
 # installed.
 #
 # When you:
@@ -48,57 +48,65 @@ include Stomp11Common
 # * heartbeat request
 #
 # Using the stomp gem, you can specify this data in the "connect_headers" Hash
-# parameter or a paramaterized connection request.  This example uses a 
+# parameter or a paramaterized connection request.  This example uses a
 # parameterized request.
 #
-# So .........
-#
-# Create connection headers
-# =========================
-#
-# The two headers used here are _required_ by the specification.
-#
-conn_hdrs = {"accept-version" => "1.1",    # Demand a 1.1 connection (use a CSV list if you will consider multiple versions)
+class Connection11Example1
+  # Initialize
+  def initialize
+  end
+  # Run example
+  def run
+    #
+    # Create connection headers
+    # =========================
+    #
+    # The two headers used here are _required_ by the specification.
+    #
+    conn_hdrs = {"accept-version" => "1.1",    # Demand a 1.1 connection (use a CSV list if you will consider multiple versions)
       "host" => virt_host,                 # The 1.1 vhost (could be different than connection host)
     }                                      # No heartbeats here:  there will be none for this connection
+    #
+    # Get a connection
+    # ================
+    #
+    conn = Stomp::Connection.new(login, passcode, host, port,   # Normal connect parms
+      false,      # Not reliable, the default for a parameter connection
+      5,          # Connect redelay, the default
+      conn_hdrs)  # The 1.1 connection parameters
+    puts "Connection connect complete"
+    #
+    # Let's just do some sanity checks, and look around.
+    #
+    raise "Connection failed!!" unless conn.open?
+    #
+    # Is this really a 1.1 conection? ('protocol' is a read only connection
+    # instance variable. The value will be '1.0' for those types of connections.)
+    #
+    raise "Unexpected protocol level" if conn.protocol != Stomp::SPL_11
+    #
+    # The broker _could_ have returned an ERROR frame (unlikely).
+    #
+    raise "Connect error: #{conn.connection_frame.body}" if conn.connection_frame.command == Stomp::CMD_ERROR
+    #
+    # Examine the CONNECT response (the connection_frame).
+    #
+    puts "Connected Headers required to be present:"
+    puts "Connect version - \t#{conn.connection_frame.headers['version']}"
+    puts
+    puts "Connected Headers that are optional:"
+    puts "Connect server - \t\t#{conn.connection_frame.headers['server']}"
+    puts "Session ID - \t\t\t#{conn.connection_frame.headers['session']}"
+    puts "Server requested heartbeats - \t#{conn.connection_frame.headers['heart-beat']}"
+    #
+    # Finally disconnect
+    # ==================
+    #
+    conn.disconnect   # Business as usual, just like 1.0
+    puts "Connection disconnect complete"
+  end
+end
 #
-# Get a connection
-# ================
-#
-conn = Stomp::Connection.new(login, passcode, host, port,   # Normal connect parms
-  false,      # Not reliable, the default for a parameter connection
-  5,          # Connect redelay, the default
-  conn_hdrs)  # The 1.1 connection parameters
-puts "Connection connect complete"
-#
-# Let's just do some sanity checks, and look around.
-#
-raise "Connection failed!!" unless conn.open?
-#
-# Is this really a 1.1 conection? ('protocol' is a read only connection
-# instance variable. The value will be '1.0' for those types of connections.)
-#
-raise "Unexpected protocol level" if conn.protocol != Stomp::SPL_11
-#
-# The broker _could_ have returned an ERROR frame (unlikely).
-#
-raise "Connect error: #{conn.connection_frame.body}" if conn.connection_frame.command == Stomp::CMD_ERROR
-#
-# Examine the CONNECT response (the connection_frame).
-#
-puts "Connected Headers required to be present:"
-puts "Connect version - \t#{conn.connection_frame.headers['version']}"
-puts
-puts "Connected Headers that are optional:"
-puts "Connect broker - \t\t#{conn.connection_frame.headers['broker']}"
-puts "Session ID - \t\t\t#{conn.connection_frame.headers['session']}"
-puts "Server requested heartbeats - \t#{conn.connection_frame.headers['heart-beat']}"
-#
-# Finally disconnect
-# ==================
-#
-conn.disconnect   # Business as usual, just like 1.0
-puts "Connection disconnect complete"
-
-
+e = Connection11Example1.new
+e.run