explainer-rmb-rails 0.0.8 → 0.0.10

data/README.rdoc

@@ -1,17 +1,76 @@
-= rmb-rails
-
-= RESTful Message Beans for Ruby on Rails
+
+= rmb-rails: RESTful Message Beans for Ruby on Rails
 
 = 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.
+
 == Copyright
 
 Copyright (c) 2009 Ken Burgett. See LICENSE for details.

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.8
+0.0.10

data/rmb-rails.gemspec

@@ -2,11 +2,12 @@
 
 Gem::Specification.new do |s|
   s.name = %q{rmb-rails}
-  s.version = "0.0.8"
+  s.version = "0.0.10"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Ken Burgett"]
   s.date = %q{2009-07-23}
+  s.description = %q{...something interesting here...}
   s.email = %q{keburgett@gmail.com}
   s.extra_rdoc_files = [
     "LICENSE",
@@ -49,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.8
+  version: 0.0.10
 platform: ruby
 authors: 
 - Ken Burgett
@@ -11,9 +11,38 @@ cert_chain: []
 
 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: []