stomp 1.4.4 → 1.4.5

data/examples/examplogger.rb

@@ -11,7 +11,7 @@ require 'logger'	# use the standard Ruby logger .....
 # *    on_connectfail: unsuccessful connect (will usually be retried)
 # *    on_disconnect: successful disconnect
 #
-# *    on_miscerr: on miscellaneous xmit/recv errors
+# *    on_miscerr: on miscellaneous transmit/receive errors
 #
 # *    on_publish: publish called
 # *    on_subscribe: subscribe called

data/examples/logexamp.rb

@@ -5,13 +5,19 @@ require 'stomp'
 require 'logger'  # for the 'local' logger
 #
 if Kernel.respond_to?(:require_relative)
+  require_relative("./stomp_common")  
   require_relative("./examplogger")
 else
   $LOAD_PATH << File.dirname(__FILE__)
   require "examplogger"
+  require("stomp_common")  
 end
+include Stomp1xCommon
 #
-# == A STOMP::Connection program which uses the callback logging facility.
+# == A program which demonstrates the callback logging facility.
+#
+# With appropriate specification of STOMP_PORT, this code should also
+# demonstrate failover.
 #
 class LoggerExample
   # Initialize.
@@ -25,18 +31,20 @@ class LoggerExample
 
     # //////////////////////////////////////////////////////////////////////////////
     mylog = Slogger::new  # The client provided STOMP callback logger
-
     # //////////////////////////////////////////////////////////////////////////////
     user =      ENV['STOMP_USER'] ? ENV['STOMP_USER'] : 'guest'
     password =  ENV['STOMP_PASSWORD'] ? ENV['STOMP_PASSWORD'] : 'guest'
     host =      ENV['STOMP_HOST'] ? ENV['STOMP_HOST'] : 'localhost'
     port =      ENV['STOMP_PORT'] ? ENV['STOMP_PORT'].to_i : 61613
+    so =        usessl()
     # //////////////////////////////////////////////////////////////////////////////
     # A hash type connect *MUST* be used to enable callback logging.
     # //////////////////////////////////////////////////////////////////////////////
     hash = { :hosts => [
-        {:login => user, :passcode => password, :host => 'noonehome', :port => 2525},
-        {:login => user, :passcode => password, :host => host, :port => port},
+        {:login => user, :passcode => password, :host => 'noonehome', :port => 2525,
+          :ssl => so},
+        {:login => user, :passcode => password, :host => host, :port => port,
+          :ssl => so},
       ],
       :logger => mylog,	# This enables callback logging!
       :max_reconnect_attempts => 5,
@@ -46,15 +54,17 @@ class LoggerExample
     # For a Connection:
     llog.debug "LE Connection processing starts"
     conn = Stomp::Connection.new(hash)
-    conn.disconnect
+    conn.disconnect()
+
     # //////////////////////////////////////////////////////////////////////////////
     llog.debug "LE Connection processing complete"
 
     # //////////////////////////////////////////////////////////////////////////////
     # For a Client:
     llog.debug "LE Client processing starts"
-    conn = Stomp::Client.new(hash)
-    conn.close
+    client = Stomp::Client.new(hash)
+    client.close()
+
     # //////////////////////////////////////////////////////////////////////////////
     llog.debug "LE Client processing complete"
 
@@ -65,9 +75,10 @@ class LoggerExample
     #
     dest = "/queue/loggerq1"
     conn.publish dest, "a logger message"
-    conn.subscribe dest
-    msg = conn.receive
-    conn.disconnect
+    conn.subscribe(dest)
+    msg = conn.receive()
+    conn.disconnect()
+
     # //////////////////////////////////////////////////////////////////////////////
     llog.debug "LE Connection Enhanced processing complete"
 
@@ -75,7 +86,5 @@ class LoggerExample
     llog.debug "LE Ending"
   end
 end
-e = LoggerExample.new
-e.run
-
-
+e = LoggerExample.new()
+e.run()

data/examples/putget_file.rb

@@ -0,0 +1,79 @@
+# -*- encoding: utf-8 -*-
+
+require 'rubygems'
+require 'stomp'
+
+if Kernel.respond_to?(:require_relative)
+  require_relative("./stomp_common")
+else
+  $LOAD_PATH << File.dirname(__FILE__)
+  require "stomp_common"
+end
+include Stomp1xCommon
+#
+# Used primarily for testing performance when sending/receiving "large" messages.
+# "large" => YMMV
+#
+class FilePutGet
+  # Initialize.
+  def initialize
+    @qname = dest()
+  end
+  # Run put part of example.
+  def doput()
+    puts
+    puts "pgf001 - put starts"
+    start_time = Time.now.to_f
+    fname = ARGV[0]
+    puts "pgf002: File Name: #{fname}"
+    file = open(fname, "r")
+    rs = Time.now.to_f
+    buff = file.read
+    re = Time.now.to_f
+    ppt = sprintf("%22.8f", re - rs)
+    puts "pgf003: File size: #{buff.respond_to?(:bytesize) ? buff.bytesize : buff.length} bytes"
+    puts "pgf004: File read time: #{ppt} seconds"
+    file.close
+    #
+    conn = get_connection()
+    puts "pgf005: Qname is: #{@qname}"
+    # Try to gracefully handle files that exceed broker size limits.
+    ph = {:presistent => true}
+    ph['suppress_content_length'] = 'yes' if suppresscl()
+    puts "pgf006: Headers are: #{ph.inspect}"
+    begin
+      conn.publish(@qname, buff, ph)
+    rescue
+      puts "pgf900: exception on publish: #{$!}"
+      raise
+    end
+    conn.disconnect()
+    end_time = Time.now.to_f
+    ppt = sprintf("%22.8f", end_time - start_time)
+    puts "pgf007: File publish time: #{ppt} seconds"
+  end
+  # Run get part of example.
+  def doget()
+    puts
+    puts "pgf101 - get starts"
+    start_time = Time.now.to_f
+    conn = get_connection()
+    uuid = conn.uuid() # uuid for Stomp::Connection is a public method
+    conn.subscribe(@qname, {'id' => uuid}) # Subscribe
+    msg = conn.receive()
+    puts "pgf102: Message Command: #{msg.command}"
+    puts "pgf103: Message Headers: #{msg.headers}"
+    body_length_bytes = msg.body.respond_to?(:bytesize) ? msg.body.bytesize : msg.body.length
+    puts "pgf104: Received: #{body_length_bytes} bytes"
+    #
+    end_time = Time.now.to_f
+    ppt = sprintf("%22.8f", end_time - start_time)
+    puts "pgf105: File receive time: #{ppt} seconds"
+    conn.disconnect()
+  end
+
+end
+#
+e = FilePutGet.new()
+e.doput()
+e.doget()

data/examples/{putget11_rh1.rb → putget_rephdrs.rb}

@@ -5,21 +5,22 @@
 # Change this to suit your requirements.
 #
 if Kernel.respond_to?(:require_relative)
-  require_relative("./stomp11_common")
+  require_relative("./stomp_common")
 else
   $LOAD_PATH << File.dirname(__FILE__)
-  require "stomp11_common"
+  require "stomp_common"
 end
-include Stomp11Common
+include Stomp1xCommon
 #
-# == Stomp 1.1 Send/Receive Example - Repeated Headers
+# == Stomp 1.1+ Send/Receive Example - Repeated Headers
 #
-# Purpose: to demonstrate sending and receiving using Stomp 1.1, and an unusual
+# Purpose: to demonstrate sending and receiving using Stomp 1.1+, and an unusual
 # aspect of the specification.  What is demonstrated here is the use of
 # 'repeated headers'. Note that brokers MAY support repeated headers as
-# demonstrated, but are not required to provide this support. This example
-# should run against the Apollo broker.  It will *not* currently run against
-# RabbitMQ.  YMMV depending on your broker.
+# demonstrated, but are not required to provide this support. 
+#
+# This example should run against the Apollo broker.  It will *not* currently run against
+# ActiveMQ or RabbitMQ.  YMMV depending on your broker.
 #
 # See: http://stomp.github.com/stomp-specification-1.1.html#Repeated_Header_Entries
 #
@@ -30,7 +31,8 @@ class RepeatedHeadersExample
   # Run example.
   def run
     conn = get_connection() # Use helper method to obtain a Stomp#connection
-    raise "Unexpected protocol level" if conn.protocol != Stomp::SPL_11
+    raise "Unexpected protocol level" if conn.protocol == Stomp::SPL_10
+    puts "Repeated headers example, host: #{host()}, port: #{port()}"
     #
     # The gem supports repeated headers by allowing the 'value' part of a header
     # to be an Array instance.
@@ -42,7 +44,7 @@ class RepeatedHeadersExample
     # to hold the repeated values.  This is presented the the calling client to
     # be processed per client requirements.
     #
-    qname = "/queue/nodea.nodeb.nodec"
+    qname = dest()
     data = "message payload: #{Time.now.to_f}"
     key2_repeats = ["key2val3", "key2val2", "key2val1" ]
     headers = {"key1" => "value1",  # A normal header
@@ -52,7 +54,7 @@ class RepeatedHeadersExample
     #
     # Ship it.
     #
-    conn.publish qname, data , headers
+    conn.publish(qname, data , headers)
     puts "Sent data: #{data}"
     #
     # Receive phase.
@@ -84,10 +86,9 @@ class RepeatedHeadersExample
     #
     # And finally, disconnect.
     #
-    conn.disconnect
+    conn.disconnect()
   end
 end
 #
-e = RepeatedHeadersExample.new
-e.run
-
+e = RepeatedHeadersExample.new()
+e.run()

data/examples/ssl/SSL.md

@@ -0,0 +1,189 @@
+# SSL Examples
+
+This is to provide additional documentation regarding the gem's
+SSL related examples.
+
+This documentation is based on experiments with OpenSSL.
+
+
+## Environment Variables
+
+You will likely need to use supported environment variables to
+define SSL related data locations on your system. See example
+ssl_common.rb for details of support of this functionality.
+
+<table border="2" style="width:100%;border: 2px solid black;">
+<tr>
+    <th style="border: 2px solid black;padding-left: 10px;" >
+    Environment Variable
+    </th>
+    <th style="border: 2px solid black;padding-left: 10px;" >
+    Description
+    </th>
+</tr>
+<!--                                                      -->
+<tr>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    CA_FLOC
+    </td>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    CA cert file location/directory.
+    </td>
+</tr>
+<!--                                                      -->
+<tr>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    CLI_FLOC
+    </td>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    Client cert file location/directory.
+    </td>
+</tr>
+<!--                                                      -->
+<tr>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    CLI_FILE
+    </td>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+        Clent cert file name.
+    </td>
+</tr>
+<!--                                                      -->
+<tr>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    CLI_KEY
+    </td>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    Client private key file name. This file should not be 
+    exposed to the outside world.
+    </td>
+</tr>
+<!--                                                      -->
+<tr>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    STOMP_HOST
+    </td>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    The host name of your SSL broker.
+    </td>
+</tr>
+<!--                                                      -->
+<tr>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    STOMP_PORT
+    </td>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    The the TCP port number used by your SSL broker.
+    </td>
+</tr>
+</table>
+
+## The Four Main SSL Use Cases
+
+There are four main SSL use cases.  Example code for each of these can be found
+in the 'examples/uc?' subdirectories.  Each individual use case is described below.
+
+Each 'sxamples/uc?' subdirectory contains two example programs:
+
+* A primary demonstration of the example
+* A secondary demonstration of the example where client code overrides the
+default list of ciphers that SSL considers.
+
+Note that each use case has two subcases:
+
+* Your broker does _not_ require client authentication
+* Your broker _does_ require client authentication
+
+### Use Case 1 - No Authentification by broker or client
+
+Subcase A - When your broker does _not_ require client authentication:
+
+
+* Expect connection success.
+* Expect a verify result of 20 becuase the client did not authenticate the
+server's certificate.
+
+
+Subcase B - When your broker _does_ require client authentication:
+
+* Expect connection failure (broker must be sent a valid client certificate).
+
+### Use Case 2 - No Authentification by broker, authentification by client
+
+Subcase A - When your broker does _not_ require client authentication:
+
+* Expect connection success
+* Expect a verify result of 0 becuase the client did authenticate the
+server's certificate.
+
+Subcase B - When your broker _does_ require client authentication:
+
+* Expect connection failure (broker must be sent a valid client certificate).
+
+### Use Case 3 - Authentification by broker, no authentification by  broker
+
+Subcase A - When your broker does _not_ require client authentication:
+
+* Expect connection success
+* Expect a verify result of 20 becuase the client did not authenticate the
+server's certificate.
+
+Subcase B - When your broker _does_ require client authentication:
+
+* Expect connection success if the server can authenticate the client certificate
+* Expect a verify result of 20 because the client did not authenticate the
+server's certificate.
+
+### Use Case 4 - Authentification by both broker and client
+
+Subcase A - When your broker does _not_ require client authentication:
+
+* Expect connection success
+* Expect a verify result of 0 becuase the client did authenticate the
+server's certificate.
+
+Subcase B - When your broker _does_ require client authentication:
+
+* Expect connection success if the server can authenticate the client certificate
+* Expect a verify result of 0 because the client did authenticate the
+server's certificate.
+
+## Miscellaneous SSL Examples
+
+The gem provides several other examples of using the built-in SSL
+functionality.  These examples are described below.
+
+### Override SSL Context Options
+
+This example is in 'examples/misc/ssl_ctxoptions.rb'.
+
+The gem provides the capability for the client to supply SSL context options
+to be used during an SSL connect.
+
+These options are passed to the gem in the `Stomp::SSLParams` instance.
+
+These options are then placed by the gem in the `OpenSSL::SSL::SSLContext` instance used during
+an SSL connect.
+
+### Specify Parameters When SSL Context Options Are Created
+
+This example is in 'examples/misc/ssl_newparm.rb'.
+
+The gem provides the capability of passing parameters to
+`OpenSSL::SSL::SSLContext.new(..)`.
+
+These options are passed to the gem in the connect hash used for open/new.
+
+### Override The Default Cipher List Used BY SSL
+
+This example is in 'examples/misc/ssl_ucx_default_ciphers.rb'.
+
+Note:  this example is _not_ for use in JRuby.
+
+The gem allows use of a default list of fairly well known and broker
+supported ciphers found in `Stomp::DEFAULT_CIPHERS`.
+
+However, the default list of Ruby ciphers can be requested.
+
+This is requested when `Stomp::SSLParams` is created by the client using the
+`:use_ruby_ciphers => true` parameter.

data/examples/{ssl_ctxoptions.rb → ssl/misc/ssl_ctxoptions.rb}

@@ -1,8 +1,16 @@
 # -*- encoding: utf-8 -*-
 
 #
-require "rubygems"
-require "stomp"
+if Kernel.respond_to?(:require_relative)
+  require_relative("../ssl_common")
+  require_relative("../../stomp_common")
+else
+  $LOAD_PATH << File.dirname(__FILE__)
+  require "../ssl_common"
+  require "../../stomp_common"
+end
+include SSLCommon
+include Stomp1xCommon
 #
 # == Demo User Control of SSLContext options contents
 #
@@ -14,12 +22,15 @@ require "stomp"
 class ExampleSSLCtxOptions
   # Initialize.
   def initialize
+    # It is very likely that you will have to specify your specific port number.
+    # 61611 is currently my AMQ local port number for ssl client auth not required.
+		@port = ENV['STOMP_PORT'] ? ENV['STOMP_PORT'].to_i : 61611
   end
 
   # Run example 1
-  def run1
+  def run1()
     require 'openssl' unless defined?(OpenSSL)
-    puts "run method ...."
+    puts "run1 method ...."
 		# Define SSL Options to be used.  This code is copied from the defaults
     # in later versions of Ruby V2.x (which has been backported to 1.9.3).
     #
@@ -43,9 +54,8 @@ class ExampleSSLCtxOptions
     ssl_opts = Stomp::SSLParams.new(:ssl_ctxopts => opts, # SSLContext options to set
       :use_ruby_ciphers => urc,
       :fsck => true)
-    sport = ENV["STOMP_PORT"].to_i
     hash = { :hosts => [
-        {:login => 'guest', :passcode => 'guest', :host => 'localhost', :port => sport, :ssl => ssl_opts},
+        {:login => login(), :passcode => passcode(), :host => host(), :port => @port, :ssl => ssl_opts},
       ],
       :reliable => false, # YMMV, to test this in a sane manner
     }
@@ -56,11 +66,11 @@ class ExampleSSLCtxOptions
     puts "SSL Verify Result: #{ssl_opts.verify_result}"
     # puts "SSL Peer Certificate:\n#{ssl_opts.peer_cert}"
     #
-    c.disconnect
+    c.disconnect()
   end
   
   # Run example 2
-  def run2
+  def run2()
     puts "run2 method ...."
     #
     # Connection / Example 2 of 2, gem supplied options.
@@ -73,9 +83,8 @@ class ExampleSSLCtxOptions
     ssl_opts = Stomp::SSLParams.new(:ssl_ctxopts => Stomp::Connection::ssl_v2xoptions(),
        :use_ruby_ciphers => urc,
        :fsck => true)
-    sport = ENV["STOMP_PORT"].to_i
     hash = { :hosts => [
-        {:login => 'guest', :passcode => 'guest', :host => 'localhost', :port => sport, :ssl => ssl_opts},
+        {:login => login(), :passcode => passcode(), :host => host(), :port => @port, :ssl => ssl_opts},
       ],
       :reliable => false, # YMMV, to test this in a sane manner
     }
@@ -86,11 +95,11 @@ class ExampleSSLCtxOptions
     puts "SSL Verify Result: #{ssl_opts.verify_result}"
     # puts "SSL Peer Certificate:\n#{ssl_opts.peer_cert}"
     #
-    c.disconnect
+    c.disconnect()
   end
 end
 #
-e = ExampleSSLCtxOptions.new
-e.run1
-e.run2
+e = ExampleSSLCtxOptions.new()
+e.run1()
+e.run2()