stomp 1.4.4 → 1.4.5

data/examples/EXAMPLES.md

@@ -0,0 +1,251 @@
+# stomp gem examples
+
+This is to describe the existing stomp gem examples.
+
+## Environment Variables
+
+You will likely need to use supported environment variables to
+define example related data elements for your system. See example
+stomp_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;" >
+    STOMP_LOGIN
+    </td>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    The user ID when connecting to a broker.<br/>
+    Default: guest.
+    </td>
+</tr>
+<!--                                                      -->
+<tr>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    STOMP_PASSCODE
+    </td>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    The user password when connecting to a broker.<br/>
+    Deault: guest.
+    </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 broker host name.<br/>
+    Default: localhost.
+    </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 broker port number.<br/>
+    Default: 61613.
+    </td>
+</tr>
+<!--                                                      -->
+<tr>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    STOMP_VHOST
+    </td>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    The name of the broker's virtual host for 1.1+ connections.<br/>
+    Default: localhost.
+    </td>
+</tr>
+<!--                                                      -->
+<tr>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    STOMP_PROTOCOL
+    </td>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    The Stomp protocol level to use.<br/>
+    Default: 1.2.
+    </td>
+</tr>
+<!--                                                      -->
+<tr>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    STOMP_HEARTBEATS
+    </td>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    The Stomp heart beat parameters to use.<br/>
+    Default: nil/none.
+    </td>
+</tr>
+<!--                                                      -->
+<tr>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    STOMP_NMSGS
+    </td>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    The number of messages to put and/or get.<br/>
+    Default: 1.
+    </td>
+</tr>
+<!--                                                      -->
+<tr>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    STOMP_DEST
+    </td>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    The default name of a Stomp destination.<br/>
+    Default: /queue/(time-stamp).
+    </td>
+</tr>
+<!--                                                      -->
+<tr>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    STOMP_SUPPRESS_CL
+    </td>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    Whether to include a 'suppress_content_length' header in a message.<br/>
+    Default: false.
+    </td>
+</tr>
+<!--                                                      -->
+<tr>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    STOMP_SSL
+    </td>
+    <td style="border: 2px solid black;padding-left: 10px;" >
+    Whether to use an SSL connection.<br/>
+    Default: false.
+    </td>
+</tr>
+</table>
+
+## General Examples
+
+Note: you will need a running broker to use these examples.
+
+### examples/client_conndisc.rb
+
+A plain example of using a `Stomp#Client` to:
+
+* Connect to a broker
+* Disconnect from the broker
+
+### examples/client_putget.rb
+
+An example of using a `Stomp#Client` to:
+
+* Connect to a broker
+* Send and receive some message(s)
+* Disconnect from the broker
+
+### examples/conn_conndisc.rb
+
+A plain example of using a `Stomp#Connection` to connect to:
+
+* Connect to a broker
+* Disconnect from the broker
+
+### examples/conn_putget.rb
+
+An example of using a `Stomp#Connection` to:
+
+* Connect to a broker
+* Send and receive some message(s)
+* Disconnect from the broker
+
+### examples/examplogger.rb
+
+This example shows how to write a Stomp gem callback logger.
+
+A callback logger can be used to greatly enhance understanding of
+application flow, and the gem actions resulting from that flow.
+
+### examples/logexamp.rb
+
+This example shows how to use the example callback logger in
+'examples/examplogger.rb'.
+
+### examples/putget_file.rb
+
+This example is primarily meant to measure performance when sending
+ (possibly) large messages.
+
+This example show how to:
+
+* Open a file
+* Read the entire file into a buffer
+* Close the file
+* Connect to a broker
+* Send the entire file as a single message
+* Disconnect from the broker
+
+### examples/putget_rephdrs.rb
+
+The Stomp 1.1+ specifications describe functionality for supporting multiple user supplied
+headers with the same header key.
+
+Experience shows that various real world brokers support this functionality
+in a variety of ways.
+
+The gem supports multiple headers with the same key.  This example
+demonstrates that support.
+
+However, given the variety of broker support, this example works only with the
+(now defunct?) Apache Apollo broker.
+
+You should modify the example to work with other brokers.
+
+## Artemis Specific Examples
+
+The Apache Artemis broker exhibits some behavior that is unusual for a
+Stomp broker.
+
+This behavior is to sever connections fairly quickly if there is no
+activity on the connection.  The current default is 1 minute of
+inactivity.
+
+There are several approaches that a client can use to 'bypass' this
+behavior.
+
+### examples/artemis/cliwaiter_not_reliable.rb
+
+This example uses a `Stomp#Client` that specifies `:reliable => false` in the
+connection parameters.
+
+### examples/artemis/cliwaiter_reliable_hb.rb
+
+This example uses a `Stomp#Client` that specifies `:reliable => true` in the
+connection parameters and also uses Stomp heart beats to help keep a connection
+alive.
+
+
+## Historical Examples
+
+These are examples that are bing kept for historical reasons.  They
+have been part of the gem's history since very early days of development.
+
+### examples/historical/consumer.rb
+
+The classical message consumer.
+
+### examples/historical/producer.rb
+
+The classical message producer.
+
+### examples/historical/topic_consumer.rb
+
+The classical message consumer (from a topic).
+
+### examples/historical/topic_producer.rb
+
+The classical message producer (to a topic).

data/examples/amqdurasub.rb

@@ -5,12 +5,12 @@
 # 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 Stomp1xCommon
 =begin
 
   A recent experience suggested that we might provide an example of how
@@ -34,18 +34,19 @@ end
     subscription(s).
     Done by providing a "cilent-id" CONNECT header.
 
-  2) On SUBSCRIBE, indicate an AMQ specific (uniqie) subscription ID.  Done
+  2) On SUBSCRIBE, indicate an AMQ specific (unique) subscription ID.  Done
     by providing a "activemq.subscriptionName" header to SUBSCRIBE.
 
 =end
 
 # login hash
 hash = { :hosts => [ 
-       {:login => 'guest', :passcode => 'guest', :host => 'localhost', :port => 61613, :ssl => false}, # AMQ
+       {:login => login(), :passcode => passcode(), :host => host(), :port => port(),
+          :ssl => usessl()}, #
       ],
       :reliable => true,
 			:closed_check => false, 
-      :connect_headers => {:host => "localhost", :"accept-version" => "1.0",
+      :connect_headers => {:host => "localhost", :"accept-version" => "1.2",
         # Requirement 1, name should be unique.
         :"client-id" => "dursubcli01",  # REF the 1st AMQ link above
 			} 
@@ -61,21 +62,17 @@ sh = { "activemq.subscriptionName" => "subname01" } # REF the 1st AMQ link above
 cli.subscribe(topic, sh) do |msg|
   puts "msg: #{msg}"
 end
-# Wait for a very long time, usually exit via ^C
-puts "Press ^C to exit"
-sleep 1000000
-puts "Done yet?"
-
 =begin
   At this point open your AMQ admin console (port 8161 usually), and examine 
   the 'subscribers' section.  You should see an instance of this client 
   displayed in the "Active Durable Topic Subscribers" section.
-
-  When you press ^C to exit this program, return to the AMQ console and
+=end
+# Wait for a very long time, usually exit via ^C
+puts "Open AMQ console and examing the 'subscribers' section"
+puts "Wne done, press ^C to exit, and reexamine the 'subscribers' section"
+sleep 1000000
+=begin
+  After you press ^C to exit this program, return to the AMQ console and
   refresh the display.  (Do not restart AMQ).  You should see this client in the
   "Offline Durable Topic Subscribers" section.
 =end
-
-
-
-

data/examples/artemis/cliwaiter_not_reliable.rb

@@ -2,6 +2,11 @@
 #
 require 'stomp'
 #
+# Artemis will summarily close down connections if there is no traffic for some
+# time.  This code demonstrates running with a gem connetion parameter of
+# :reliable => false (the gem will not retry).  The code demonstrates handling
+# your own retries a certain number of times (3 to be axact).
+#
 class CliWaiter
 
   @@retry_num = 0
@@ -14,7 +19,7 @@ class CliWaiter
 	@port = ENV['STOMP_PORT'] ? ENV['STOMP_PORT'].to_i : 31613 # Artemis here
 	@slt = 75
 	@ver = ENV['STOMP_PROTOCOL'] ? ENV['STOMP_PROTOCOL'] : "1.2"
-	@hbdata = ENV['STOMP_HEARTBEATS'] ? ENV['STOMP_HEARTBEATS'] : "0,0"
+	@hbdata = "0,0" # Force no heartbeats for this example
 	@conn_hdrs = {"accept-version" => @ver, # version
 		"host" => "localhost",              # vhost
 		"heart-beat" => @hbdata,            # heartbeats
@@ -27,10 +32,10 @@ class CliWaiter
 		:connect_headers => @conn_hdrs,
 	}
 	p [ "DB1", @hash ]
-	@do_retry=true    # Retry ourself, gem code will not because of :reliable =>
+	@do_retry=true    # Retry ourself, gem code will not because of :reliable => false
   end
   # Run example.
-  def run
+  def run()
 	begin
 		@@retry_num += 1
 		puts "Try Number: #{@@retry_num}"
@@ -52,8 +57,10 @@ class CliWaiter
 		puts "The gory details:"
 		print ex.backtrace.join("\n")
 		if @do_retry && @@retry_num < @@max_retries
+			puts "Will retry"
 			retry
 		else
+			puts "Will re-raise"
 			raise
 		end
 	end            
@@ -62,5 +69,5 @@ end
 #
 
 #
-e = CliWaiter.new
-e.run
+e = CliWaiter.new()
+e.run()

data/examples/artemis/{cliwaiter_reliable.rb → cliwaiter_reliable_hb.rb}

@@ -1,61 +1,62 @@
 # -*- encoding: utf-8 -*-
 #
 require 'stomp'
-#
 if Kernel.respond_to?(:require_relative)
-  require_relative("artlogger")
-else
-  $LOAD_PATH << File.dirname(__FILE__)
-  require "artlogger"
-end
+	require_relative("../examplogger")
+  else
+	$LOAD_PATH << File.dirname(__FILE__)
+	require "../examplogger"
+  end
+#
+# Artemis will summarily close down connections if there is no traffic for some
+# time.  This code demonstrates running with a gem connetion parameter using
+# heartbeats to totally avoid this Artemis behavior.
 #
 class CliWaiter
 
   # Initialize.
   def initialize        # Change the following as needed.
-	#
-	mylog = Slogger::new  # a stomp callback logger
-	#
 	@gem_retries = true
 	@host = ENV['STOMP_HOST'] ? ENV['STOMP_HOST'] : "localhost"
 	@port = ENV['STOMP_PORT'] ? ENV['STOMP_PORT'].to_i : 31613 # Artemis here
 	@slt = 75
 	@ver = ENV['STOMP_PROTOCOL'] ? ENV['STOMP_PROTOCOL'] : "1.2"
-	@hbdata = ENV['STOMP_HEARTBEATS'] ? ENV['STOMP_HEARTBEATS'] : "0,0"
+	# The Artemis artificial default is to sever after 1 minute of inactivity.
+	# The default heart-beat parameters here are chosen just to avoid this
+	# Artemis specific behavior.  YMMV.
+	@hbdata = ENV['STOMP_HEARTBEATS'] ? ENV['STOMP_HEARTBEATS'] : "59000,59000"
 	@conn_hdrs = {"accept-version" => @ver, # version
 		"host" => "localhost",              # vhost
-		"heart-beat" => @hbdata,            # heartbeats		
+		"heart-beat" => @hbdata,            # heartbeats
 	}
+	mylog = Slogger::new()  # The client provided STOMP callback logger
 	@hash = { :hosts => [
 				{:login => 'guest', :passcode => 'guest', :host => @host, :port => @port},
 		],
 		:reliable => @gem_retries, # reliable controls retries by the gem
-	    :logger => mylog,	# This enables callback logging!
 		:autoflush => true,
 		:connect_headers => @conn_hdrs,
-		:initial_reconnect_delay => 1.0,    # initial delay before reconnect (secs)
-		:use_exponential_back_off => false, # don't backoff
-		:max_reconnect_attempts => 3,       # retry 3 times
+		:logger => mylog,	# This enables callback logging!
 	}
   end
   # Run example.
-  def run
-	puts "Connect host: #{@host}, port: #{@port}"
-	puts "Connect hash: #{@hash}"
-	#
+  def run()
 	puts "CliWaiter Starts"
+	puts "Connect Hash is: #{@hash}"
 	c = Stomp::Client.new(@hash)
 	#
-	while true 
+	while true
+		# This should run forever.
 		puts "CliWaiter Sleeps: #{@slt} seconds"
 		sleep @slt
 	end
 	#
-	c.close
+	c.close()
+	puts "CliWaiter Ends"
   end
 end
 #
 
 #
-e = CliWaiter.new
-e.run
+e = CliWaiter.new()
+e.run()