explainer-rmb-rails 0.0.5 → 0.0.6

data/README.rdoc

@@ -1,6 +1,80 @@
-= rmb-rails
+
+= rmb-rails: RESTful Message Beans for Ruby on Rails
 
-Description goes here.
+= Introduction
+
+During a lengthy career in software development, and later as an enterprise architect, I saw a lot of message broker deployments in many 
+large corporations.  These systems were used primarily to knit together disparate computing 'silos' into a single fabric, as primarily 
+an integration tool.  The implementations varied significantly,  some were well engineered and managed, others were basket cases of 
+poor planning.  One significant problem that was common in many of these deployments was the requirement to add broker subscriber 
+behavior inside existing applications.  Many of these applications were single threaded (often written in COBOL) and had no real 
+ability to construct a thread to wait on some subscriber.receive method.  This issue was resolved by a variety of means, many of 
+which involved polling the subscriber queue periodically, picking up some or all of the messages waiting, and processing them 
+through the application.  Polling does not scale well.  If the application had many worker instances, they all tended to compete 
+with one another and together, consumed a lot of CPU time in polling loops.  If you slowed down the polling frequency, then you 
+got latency problems where messages sat in the queue when the readers were sleeping.  The real solution was to construct some form 
+of subscriber adapter that could inject messages into the applications' standard incoming data stream.  The Enterprise Java Message 
+Bean is a good example of this kind of adapter.  Message arrival on a designated queue or topic caused the activation of a Message Bean 
+within the EJB  container, allowing full participation in transactions within the container.  
+
+There is a real parallel between a Java EJB application and a Ruby-on-Rails application, and the Rails environment needs a method to 
+get incoming message broker subscriptions injected directly into the main Rails data stream.  So, how can we convert an MQ message 
+into an http request? The rubygem rmb-rails addresses this issue.
+
+= Theory of Operation
+
+As stated above, experience shows that polling a queue to pick up messages waiting there does not scale well.  I decided to create an 
+infrastructure where daemon processes, called listeners, can connect to a specified message broker, receive messages from that broker, 
+and then forward them on to a standard Rails controller using a standard Rails protocol.  In other words, the daemon listener processes 
+act as browsers doing a form of file upload.  The receiving rails controller is built on standard REST principles, and fits easily into 
+any Rails application.
+
+= Component classes
+
+* module RMB
+The rmb-rails gem is packaged within a single module, called RMB.  The component classes are described below.  See the rdoc for each class for a full description.
+* class RMB::Properties
+The primary interface between the gem and the calling rails app consists of a multilevel hash.  The hash is partially complete, but requires that several key value pairs be supplied.  
+* class RMB::ListenerClient
+This class implements the interface between the calling application and the daemon listeners.
+* class RMB::ListenerMain
+This class, along with concrete Subscriber and Submitter subclasses, makes up the daemon listener process.
+* class RMB::Subscriber
+This is an abstract superclass for all Subscriber classes. Every daemon has an instance of a Subscriber class acting as the 'front end' 
+of the daemon, listening and blocking on the broker.
+* class RMB::Submitter
+This is an abstract superclass for all Submitter classes.  Every daemon has an instance of a Submitter class acting as the 
+forwarding agent, taking messages received by the subscriber, packaging the message as an http request, and posts it to the specified controller/action pair.
+* class RMB::StompSubscriber
+This is a concrete subclass of Subscriber, which uses the Stomp protocol to listen to an ActiveMQ message  broker.
+* class RMB::MechanizeSubmitter
+This is a concrete subclass of Submitter, which uses the WWW:Mechanize gem to package the message as a document and submit it to the controller.
+
+= Installation
+ 
+You will need an ActiveMQ message broker to use this gem.  See http://activemq.apache.org/ for download and configuration instructions.
+
+$ gem sources -a http://gems.github.com (you only have to do this once)
+$ sudo gem install explainer-rmb-rails
+
+  or
+  
+$ sudo gem install rmb-rails (to get the same gem from rubyforge)
+
+= Usage
+
+Add the following require statement to your code to get access to this gem:
+
+require 'rmb-rails'
+
+Create an instance of RMB:ListenerClient to start/stop each listener daemon used.  Get the 
+RESTful-Message-Beans(http://github.com/explainer/RESTful-Message-Beans/tree/master) rails app, which provides a complete 
+demo rails application using this gem.
+
+== Credits
+{ActiveMQ}[http://activemq.apache.org/]
+{Enterprise Recipes with Ruby and Rails}[http://www.pragprog.com/titles/msenr/enterprise-recipes-with-ruby-and-rails]
+{Jeweler gem}[http://technicalpickles.github.com/jeweler/]
 
 == Copyright
 

data/Rakefile

@@ -4,13 +4,53 @@ require 'rake'
 begin
   require 'jeweler'
   Jeweler::Tasks.new do |gem|
+  
+    gem.description = <<-EOF
+      ...something interesting here...
+    EOF
+
     gem.name = "rmb-rails"
     gem.summary = %Q{RESTful Message Beans for Rails}
-    gem.email = "keburgett@gmail.com"
-    gem.homepage = "http://github.com/explainer/rmb-rails"
+    gem.email = %Q{keburgett@gmail.com}
     gem.authors = ["Ken Burgett"]
-    gem.rubyforge_project = "rmb-rails"
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+
+    gem.has_rdoc = true
+    gem.homepage = %q{http://github.com/explainer/rmb-rails}
+    gem.rdoc_options = ["--charset=UTF-8"]
+    gem.require_paths = ["lib"]
+    gem.rubyforge_project = %q{rmb-rails}
+    gem.rubygems_version = %q{1.3.1}
+  
+    gem.add_dependency(%q<stomp>, [">= 1.1"])
+    gem.add_dependency(%q<mechanize>, ["= 0.9.2"])
+    gem.add_dependency(%q<daemons>, [">= 1.1.10"])
+    
+    gem.files = [
+      ".document",
+       ".gitignore",
+       "LICENSE",
+       "README.rdoc",
+       "Rakefile",
+       "VERSION",
+       "lib/listener_client.rb",
+       "lib/listener_daemon.rb",
+       "lib/listener_daemon_control.rb",
+       "lib/listener_main.rb",
+       "lib/mechanize_submitter.rb",
+       "lib/rmb-rails.rb",
+       "lib/stomp_subscriber.rb",
+       "lib/submitter.rb",
+       "lib/subscriber.rb",
+       "rmb-rails.gemspec",
+       "test/rmb-rails_test.rb",
+       "test/test_helper.rb"
+    ]
+    
+    gem.extra_rdoc_files = [
+      "LICENSE",
+      "README.rdoc"
+    ]
   end
 
   Jeweler::RubyforgeTasks.new

data/VERSION

@@ -1 +1 @@
-0.0.3
+0.0.6

data/lib/listener_client.rb

@@ -1,7 +1,7 @@
 module RMB
 
   #
-  # This code is called from the client application.  It starts/stops the daemon controller script
+  # This code is called from the client application.  It starts/stops the daemon via a control script
   #
   class ListenerClient
   
@@ -19,7 +19,7 @@ module RMB
     
     def control(action)
       setup
-      control_script = "ruby #{File.dirname(__FILE__)}/#{LD}control.rb #{action}"
+      control_script = "ruby #{File.dirname(__FILE__)}/#{RMB::Properties.daemon_prefix}control.rb #{action}"
       control_params = "#{@hash[:working_dir]} #{@hash[:key]}"
       system("#{control_script} #{control_params} -- #{control_params}")
     end
@@ -40,7 +40,7 @@ private
 
     def setup
       # add derived values to the daemon_options hash
-      @hash[:daemon_options][:app_name] = "#{LD}#{@hash[:key]}"
+      @hash[:daemon_options][:app_name] = "#{RMB::Properties.daemon_prefix}#{@hash[:key]}"
       @hash[:daemon_options][:dir] = File.join("#{@hash[:working_dir]}", "tmp", "pids")
       # Ensure the properties folder is present
       properties_dir = File.join("#{@hash[:working_dir]}", "tmp", "properties")

data/lib/listener_daemon.rb

@@ -7,7 +7,8 @@
 
 require 'rubygems'
 require 'logger'
-require 'rmb'
+require 'rmb-rails'
+include RMB
 
 
 #

data/lib/listener_daemon_control.rb

@@ -4,7 +4,8 @@ require 'rubygems'
 #
 require 'logger'
 require 'daemons'
-require 'rmb'
+require 'rmb-rails'
+include RMB
 
 
 #

data/lib/listener_main.rb

@@ -76,7 +76,7 @@ particular Listener instance), the initialize method sets up the entire daemon.
     end
     
     def app_name
-      "#{LD}#{@key}"
+      "#{RMB::Properties.daemon_prefix}#{@key}"
     end
   end
 

data/lib/mechanize_submitter.rb

@@ -11,7 +11,7 @@ module RMB
     def properties=(hash)
       super
       @hash = hash
-      @daemon_name = "#{LD}#{hash[:key]}"
+      @daemon_name = "#{RMB::Properties.daemon_prefix}#{hash[:key]}"
       submitter = hash[:submitter]
       @user = submitter[:user] || ""
       @password = submitter[:password] || ""

data/lib/rmb-rails.rb

@@ -12,58 +12,49 @@ require 'submitter'
 require 'subscriber'
 
 module RMB
-# This multi-level hash contains the initial set of properties needed to launch a Listener daemon.  
-#* Make a writable copy of this hash
-#* Fill in the areas denoted by <<fill>> with your values
-#* Add additional properties required by the Subscriber and Submitter classes used
-#* Pass this has as the sole parameter in listener_client = ListenerClient.new(hash) to set up the daemon
-#* Call listener_client.start to start the daemon.
-  RMB_Properties = {
-                      :key => "<<fill>>",                               
-                      :subscriber => {
-                                       :class_name => "<<fill>>"   #set this to selected subclass of Subscriber
-                                                                   # <== add more properties for your Subscriber here
-                                     },
-                      :submitter  => {
-                                       :class_name => "<<fill>>"   #set this to selected subclass of Submitter
-                                                                   # <== add more properties for your Submitter here
-                                     },
-                      :working_dir => "<<fill>>",                  #set this to the RAILS_ROOT directory
-                      
-                      :daemon_options => { #these options are passed directly to the class method Daemons.run(target, options)
-                                              :app_name       => "",             #custom name for this daemon, set by ListenerClient#setup
-                                              :ARGV           => nil,            #use the program defaults
-                                              :dir_mode       => :normal,        #requires absolute path
-                                              :dir            => "<<fill>>",     #this is set to "#{working_dir}/tmp/pids" by ListenerClient#setup
-                                              :multiple       => false,          #this will allow multiple daemons to run
-                                              :ontop          => false,          #
-                                              :mode           => :load,
-                                              :backtrace      => false,
-                                              :monitor        => false,
-                                              :log_output     => true,
-                                              :keep_pid_files => true,
-                                              :hard_exit      => true
-                                            }
-                   }
+
+  class Properties
+  
+    # This multi-level hash contains the initial set of properties needed to launch a Listener daemon.  
+    #* Use this class method to get writable copy of this hash
+    #* Fill in the areas denoted by <<fill>> with your values
+    #* Add additional properties required by the Subscriber and Submitter classes used
+    #* Pass this has as the sole parameter in listener_client = ListenerClient.new(hash) to set up the daemon
+    #* Call listener_client.start to start the daemon, and listener_client.stop to stop the daemon
+    #
+    def self.properties
+      hash = {
+                :key => "<<fill>>",                               
+                :subscriber => {
+                                 :class_name => "<<fill>>"   #set this to selected subclass of Subscriber
+                                                             # <== add more properties for your Subscriber here
+                               },
+                :submitter  => {
+                                 :class_name => "<<fill>>"   #set this to selected subclass of Submitter
+                                                             # <== add more properties for your Submitter here
+                               },
+                :working_dir => "<<fill>>",                  #set this to the RAILS_ROOT directory
+                
+                :daemon_options => { #these options are passed directly to the class method Daemons.run(target, options)
+                                        :app_name       => "",             #custom name for this daemon, set by ListenerClient#setup
+                                        :ARGV           => nil,            #use the program defaults
+                                        :dir_mode       => :normal,        #requires absolute path
+                                        :dir            => "<<fill>>",     #this is set to "#{working_dir}/tmp/pids" by ListenerClient#setup
+                                        :multiple       => false,          #this will allow multiple daemons to run
+                                        :ontop          => false,          #
+                                        :mode           => :load,
+                                        :backtrace      => false,
+                                        :monitor        => false,
+                                        :log_output     => true,
+                                        :keep_pid_files => true,
+                                        :hard_exit      => true
+                                      }
+             }
+    end
                 
-  LD = "listener_daemon_"   #prefix for all listener_daemon artifacts produced: pids, log files, property files, and message files
-    
+    def self.daemon_prefix
+      "listener_daemon_"   #prefix for all listener_daemon artifacts produced: pids, log files, property files, and message files
+    end
+  end
 end  
 
-if __FILE__ == $0
-  hash = RMB::ListenerClient.properties('inventory', RAILS_ROOT, 'StompSubscriber', 'MechanizeSubmitter')
-  hash[:daemon_options][:dir] = File.join("#{hash[:working_dir]}", "tmp", "pids")
-  front = hash[:subscriber]
-  front[:url] = '/topic/inventory'
-  front[:host] = 'localhost'
-  front[:port] = 61613
-  front[:user] = nil
-  front[:password] = nil
-
-  back = hash[:submitter]
-  back[:login_url] = 'http://localhost:3000/login'
-  back[:delivery_url] = 'http://localhost:3000/documents/new'
-  lc = RMB::ListenerClient.new(hash)
-  puts lc.inspect
-  lc.start
-end

data/lib/submitter.rb

@@ -1,3 +1,5 @@
+
+
 module RMB
 
   class Submitter

data/lib/subscriber.rb

@@ -1,3 +1,4 @@
+
 module RMB
 
 class Subscriber

data/rmb-rails.gemspec

@@ -2,11 +2,12 @@
 
 Gem::Specification.new do |s|
   s.name = %q{rmb-rails}
-  s.version = "0.0.5"
+  s.version = "0.0.6"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Ken Burgett"]
-  s.date = %q{2009-07-22}
+  s.date = %q{2009-07-23}
+  s.description = %q{...something interesting here...}
   s.email = %q{keburgett@gmail.com}
   s.extra_rdoc_files = [
     "LICENSE",
@@ -19,8 +20,6 @@ Gem::Specification.new do |s|
      "README.rdoc",
      "Rakefile",
      "VERSION",
-     "VERSION.yml",
-     "bounce-gem.sh",
      "lib/listener_client.rb",
      "lib/listener_daemon.rb",
      "lib/listener_daemon_control.rb",
@@ -51,8 +50,17 @@ Gem::Specification.new do |s|
     s.specification_version = 2
 
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<stomp>, [">= 1.1"])
+      s.add_runtime_dependency(%q<mechanize>, ["= 0.9.2"])
+      s.add_runtime_dependency(%q<daemons>, [">= 1.1.10"])
     else
+      s.add_dependency(%q<stomp>, [">= 1.1"])
+      s.add_dependency(%q<mechanize>, ["= 0.9.2"])
+      s.add_dependency(%q<daemons>, [">= 1.1.10"])
     end
   else
+    s.add_dependency(%q<stomp>, [">= 1.1"])
+    s.add_dependency(%q<mechanize>, ["= 0.9.2"])
+    s.add_dependency(%q<daemons>, [">= 1.1.10"])
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: explainer-rmb-rails
 version: !ruby/object:Gem::Version 
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors: 
 - Ken Burgett
@@ -9,11 +9,40 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-07-22 00:00:00 -07:00
+date: 2009-07-23 00:00:00 -07:00
 default_executable: 
-dependencies: []
-
-description: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: stomp
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "1.1"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: mechanize
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        version: 0.9.2
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: daemons
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.1.10
+    version: 
+description: ...something interesting here...
 email: keburgett@gmail.com
 executables: []
 
@@ -29,8 +58,6 @@ files:
 - README.rdoc
 - Rakefile
 - VERSION
-- VERSION.yml
-- bounce-gem.sh
 - lib/listener_client.rb
 - lib/listener_daemon.rb
 - lib/listener_daemon_control.rb

data/VERSION.yml

@@ -1,4 +0,0 @@
---- 
-:major: 0
-:minor: 0
-:patch: 5

data/bounce-gem.sh

@@ -1,4 +0,0 @@
-cd /home/kenb/development/rmb-rails
-rake build
-cd pkg
-gem install rmb-rails