adaptation 0.1.6 → 0.1.7

data/CHANGELOG

@@ -52,3 +52,9 @@
     - added deprecated method Adaptation::Message#check for backwards compatibility
     - corrected path in base.rb to find settings.yml using ADAPTOR_ROOT
     - forced ActiveRecord versions 2.2.2 (2.3.x breaks tests)
+* 0.1.7
+    - improved documentation (README)
+    - console options, ruby-debug optional
+    - console options: environment  
+    - boot is (usually) done using config/boot.rb, except when forcing the
+      environment

data/README

@@ -2,52 +2,148 @@
 
 Adaptation is a framework that tries to facilitate data interchange
 between applications. Applications send and receive xml messages through
-a message oriented middleware using a publish/subscribe pattern:
+a message oriented middleware (<b>mom</b>) using a <b>publish/subscribe</b> pattern:
 
-Application A publishes messages on topic A, and all applications interested 
-on reading messages from A subscribe to its topic.
+Example:
+
+ Application A publishes messages on topic "messages from A", and all 
+ applications interested on reading messages from A subscribe to that topic.
 
 Adaptation focuses on facilitate building _adaptors_. _adaptors_ are programs
 that are executed for an application subscribed to a topic, when a message is 
 received on that topic.
 
-_adaptors_ are built in a similar way that web apps are built using
-the Ruby on Rails framework. This way adaptation uses a nice pattern
-of separation between data input/output and logic. When building an
-_adaptor_, logic will be stored under __Adaptors__ (in Rails these would
-be Controllers) , and xml data interaction with the middleware will be
-performed by a __Message__. __adaptors__ also can use ActiveRecord based
-models for data interaction with applications database, like Rails does, if
-adapting a database-backed application.
-
-
-== Getting started
-
-1. At the command prompt, start a new adaptation adaptor using the adaptation command
-   and your adaptor name. Ex: adaptation myadaptor
-   This will generate a an adaptor file tree.
-2. If no message oriented middleware has been alreay set, change directory into myadaptor 
-   and start the mom (message oriented middleware):
-   <tt>script/mom</tt>
-   This will start a mom in localhost (default), listening on port 8080 (default).
-3. Subscribe your adaptor to the mom, so it will be executed when a message is received on
-   a topic your adaaptor is interested in:
-   <tt>script/subscribe</tt>
-   By default this will try to subscribe to a mom listening on localhost:8080, using port
-   8081 to subscribe. These values can be changed editing <tt>config/mom.yml</tt>. In mom.yml 
+Adaptation is highly inspired by {Ruby on Rails}[http://rubyonrails.org] web
+framework, so _adaptors_ are built in a similar way that web apps are built
+using the RoR[http://rubyonrails.org] framework. 
+
+When building an _adaptor_, logic will be stored into Adaptation::Adaptor objects, and 
+mapping of xml data messages will be performed by Adaptation::Message objects.
+
+Adaptation can use ActiveRecord[http://api.rubyonrails.org/classes/ActiveRecord/Base.html]
+based models for data interaction with databases.
+
+
+== Installation
+
+Adaptation is available as a ruby gem, so the easiest way should be:
+
+  > gem install adaptation
+
+
+== Usage
+
+1. At the command prompt, start a new adaptation adaptor using the _adaptation_ command
+   and your adaptor name: 
+   
+     > adaptation myadaptor
+   
+   This will generate a an adaptor file tree under folder _myadaptor_.
+
+2. If no message oriented middleware has been already set, change directory into _myadaptor_ 
+   and start the <b>mom</b>:
+
+     > mom
+
+   This will start a <b>mom</b> in _localhost_ (default), listening on port <em>8080</em> (default).
+
+3. Subscribe your adaptor to the <b>mom</b>, so it will be executed when a message is received on
+   a topic your adaptor is interested in:
+
+     > script/subscribe
+
+   By default this will try to subscribe to a *mom* listening on <em>localhost:8080</em>, using port
+   <em>8081</em> to subscribe (subscribing means starting a new server that listens for 
+   message publication notifications). These values can be changed editing <em>config/mom.yml</em>. In <em>mom.yml</em> 
    you can also specify wich topics your adaptor is interested in.
-4. Start developing your adaptor, probably generating __Adaptors__[link:../rdoc/classes/Adaptation/Adaptor.html], __Messages__[link:../rdoc/classes/Adaptation/Message.html] 
-   and __Models__[http://api.rubyonrails.org/classes/ActiveRecord/Base.html].
 
+4. Right now you should have a <b>mom</b>_ listening for messages on <em>localhost:8080</em>, and an _adaptor_
+   subscribed to that *mom* and listening on <em>localhost:8081</em>, and interested in all topics available.
+
+   This environment can be tested by executing the following from _myadaptor_ folder:
+
+     > ruby script/publish NEWS '<helloworld/>'
+
+   The previous command should publish de xml <em><helloworld/></em> message into topic _NEWS_ from the *mom*.
+   This message should be displayed in the subscriber terminal when delivered by the *mom*.
+   Nothing would be executed, because a _Helloworld_ message[link:../rdoc/classes/Adaptation/Message.html] to 
+   map this xml message and a _HelloworldAdaptor_[link:../rdoc/classes/Adaptation/Adaptor.html] to process it don't 
+   exist yet. Since these classes aren't implemented, Adaptation will pass the  message as a xml _String_ to the 
+   default _ApplicationAdaptor_ adaptor, but its _process_ method is  still empty, so nothing will happen. 
+
+   To see something happening the _process_ method in the default _ApplicationAdaptor_ could be implemented, 
+   editing file <em>myadaptor/app/adaptors/application.rb</em>:
+
+     class ApplicationAdaptor < Adaptation::Adaptor
+
+       def process message
+         logger.info "Received message #{message}"
+       end
+
+     end
+  
+   Now, if the previous <em><helloword/></em> message is published, that should be visible
+   in <em>log/development.log</em>.
+     
+   The other way this can be done is by creating _Helloworld_ Adaptation::Message class to
+   map the xml data:
+   
+     > ruby script/generate message helloworld
+         exists  app/messages/
+         exists  test/unit/
+         exists  test/fixtures/
+         create  app/messages/helloworld.rb
+         create  test/unit/helloworld_test.rb
+         create  test/fixtures/helloworld.xml
+
+   The file we care about right now is <em>app/messages/helloworld.rb</em>:
+
+     class Helloworld < Adaptation::Message
+     end
+
+   We can leave it like this by now, and proceed to generate the _HelloworldAdaptor_ Adaptation::Adaptor class:
+   
+     > ruby script/generate adaptor helloworld
+         exists  app/adaptors/
+         exists  test/functional/
+         create  app/adaptors/helloworld_adaptor.rb
+         create  test/functional/helloworld_adaptor_test.rb
+
+   and to edit <em>app/adaptors/helloworld_adaptor</em> to make something happen
+   when a message is received:
+
+     class HelloworldAdaptor < ApplicationAdaptor
+
+       def process helloworld
+         logger.info "Received message: #{helloworld.to_xml.to_s}"
+       end
+
+     end
+
+   We can notice that _helloworld_ variable is not a _String_ now, because Adaptation
+   has been able to map it to a Adaptation::Message object, and that the _HelloworldAdaptor_
+   inherits from _ApplicationAdaptor_, so functionality repeated in different _Adaptors_[link:../rdoc/classes/Adaptation/Adaptor.html]
+   can be placed in _ApplicationAdaptor_.
+   
 
 == Moms
 
-By default, Adaptation will try to use druby to execute the built-in Ruby mom. This
-mom is suitable for development, but not for production. For a production environment
+By default, Adaptation will try to use druby to execute the built-in Ruby *mom*. This
+*mom* is suitable for development, but not for production. For a production environment
 a more stable solution like Xmlblaster[http://www.xmlblaster.org] should be chosen. 
 
+Different message brokers can be configured in <em>config/mom.yml</em>, and example
+configuration for supported *moms* are present in the same file when an _adaptor_ is 
+generated with the <em>adaptation</em> command.
 
-== Description of contents
+When we want to publish/subscribe to a *mom* different than the default druby, we
+can do so by adding the <em>MOM=mom_type</em> option:
+  
+  > ruby script/subscribe MOM=xmlblaster
+  > ruby script/publish MOM=xmlblaster topic message
+
+
+== Description of an _adaptor_ file tree:
 
 app
   Holds all the code that's specific to this particular adaptor.
@@ -79,8 +175,7 @@ lib
   belong under adaptors, models, or messages. 
 
 public
-  The directory available for the calling the adaptor and for utilities the adaptaed
-  application must be aware of, like a tool for publishing messages to the mom. 
+  The directory available for calling the adaptor (contains dispatch.rb). 
 
 script
   Helper scripts for automation and generation.
@@ -89,3 +184,9 @@ test
   Unit and functional tests along with fixtures. When using the script/generate scripts, template
   test files will be generated for you and placed in this directory.
 
+
+== Debugging 
+<em>TODO: ruby script/console + ruby-debug</em>
+
+== Testing 
+<em>TODO</em>

data/bin/about

@@ -1,5 +1,3 @@
 #!/usr/bin/env ruby
 require File.dirname(__FILE__) + '/../config/boot'
-require 'rubygems'
-gem 'adaptation'
 require 'commands/about'

data/bin/console

@@ -1,9 +1,8 @@
 #!/usr/bin/env ruby
-unless defined? ADAPTOR_ROOT
-  ADAPTOR_ROOT = File.expand_path(File.dirname(__FILE__) + '/..')
-end
-require "#{ADAPTOR_ROOT}/config/boot"
+
+ADAPTOR_ROOT = "#{File.dirname(__FILE__)}/.." unless defined?(ADAPTOR_ROOT)
 require 'rubygems'
-gem 'adaptation'
+require 'adaptation'
+
 require 'commands/console'
 

data/bin/destroy

@@ -1,5 +1,15 @@
 #!/usr/bin/env ruby
-require File.dirname(__FILE__) + '/../config/boot'
+
+unless defined?(RAILS_ROOT)
+  root_path = File.join(File.dirname(__FILE__), '..')
+  unless RUBY_PLATFORM =~ /mswin32/
+    require 'pathname'
+    root_path = Pathname.new(root_path).cleanpath(true).to_s
+  end
+  RAILS_ROOT = root_path
+end
+
 require 'rubygems'
 gem 'adaptation'
+
 require 'commands/destroy'

data/bin/generate

@@ -1,5 +1,15 @@
 #!/usr/bin/env ruby
-require File.dirname(__FILE__) + '/../config/boot'
+
+unless defined?(RAILS_ROOT)
+  root_path = File.join(File.dirname(__FILE__), '..')
+  unless RUBY_PLATFORM =~ /mswin32/
+    require 'pathname'
+    root_path = Pathname.new(root_path).cleanpath(true).to_s
+  end
+  RAILS_ROOT = root_path
+end
+
 require 'rubygems'
 gem 'adaptation'
+
 require 'commands/generate'

data/bin/publish

@@ -1,8 +1,3 @@
 #!/usr/bin/env ruby
-unless defined? ADAPTOR_ROOT
-  ADAPTOR_ROOT = File.expand_path(File.dirname(__FILE__) + '/..')
-end
-require 'rubygems'
-require 'adaptation'
-
+require File.dirname(__FILE__) + '/../config/boot'
 require 'commands/publish'

data/bin/subscribe

@@ -1,8 +1,3 @@
 #!/usr/bin/env ruby
-unless defined? ADAPTOR_ROOT
-  ADAPTOR_ROOT = File.expand_path(File.dirname(__FILE__) + '/..')
-end
-require 'rubygems'
-require 'adaptation'
-
+require File.dirname(__FILE__) + '/../config/boot'
 require 'commands/subscribe'

data/configs/boot.rb

@@ -1,10 +1,12 @@
-# Don't change this file. Configuration is done in config/environment.rb and config/environments/*.rb
+# Don't change this file. Configuration is done in config/environment.rb, config/environments/*.rb and settings.yml.
 
-unless defined?(RAILS_ROOT)
-  root_path = File.join(File.dirname(__FILE__), '..')
-  unless RUBY_PLATFORM =~ /mswin32/
-    require 'pathname'
-    root_path = Pathname.new(root_path).cleanpath(true).to_s
-  end
-  RAILS_ROOT = root_path
+ADAPTOR_ROOT = "#{File.dirname(__FILE__)}/.." unless defined?(ADAPTOR_ROOT)
+
+require 'rubygems'
+require 'adaptation'
+
+if defined? ADAPTOR_ENV
+  require ADAPTOR_ROOT + '/config/environments/' + ADAPTOR_ENV + '.rb'
 end
+ 
+require ADAPTOR_ROOT + '/config/environment'

data/dispatches/dispatch.rb

@@ -1,8 +1,4 @@
-unless defined? ADAPTOR_ROOT
-  ADAPTOR_ROOT = File.expand_path(File.dirname(__FILE__) + '/..')
-end
-require 'rubygems'
-require 'adaptation'
+require File.dirname(__FILE__) + '/../config/boot'
 
 a =  Adaptation::Base.new
 a.process ARGV[0] 

data/environments/development.rb

@@ -0,0 +1 @@
+ADAPTOR_ENV="development" unless defined? ADAPTOR_ENV

data/environments/environment.rb

@@ -0,0 +1,3 @@
+ADAPTOR_ENV="development" unless defined? ADAPTOR_ENV
+
+Adaptation::Initializer.run

data/environments/test.rb

@@ -0,0 +1 @@
+ADAPTOR_ENV="test" unless defined? ADAPTOR_ENV

data/lib/adaptation/base.rb

@@ -1,22 +1,20 @@
 module Adaptation
 
+  ADAPTOR_ENV = 'development' unless defined? ADAPTOR_ENV
+
   class Initializer
 
     def self.run
        
-      unless defined? $environment
-        $environment = "development"
-      end
-
       if File.exists?("#{ADAPTOR_ROOT}/config/settings.yml")
-        $config = YAML::load(File.open("#{ADAPTOR_ROOT}/config/settings.yml"))[$environment]
+        $config = YAML::load(File.open("#{ADAPTOR_ROOT}/config/settings.yml"))[ADAPTOR_ENV]
       end
 
       # connect with database -> this could also be avoided?
       if File.exists?("#{ADAPTOR_ROOT}/config/database.yml")
-        environment_configurations = YAML::load(File.open("#{ADAPTOR_ROOT}/config/database.yml"))[$environment]
-        ActiveRecord::Base.configurations.update($environment => environment_configurations)
-        ActiveRecord::Base.establish_connection(ActiveRecord::Base.configurations[$environment])
+        environment_configurations = YAML::load(File.open("#{ADAPTOR_ROOT}/config/database.yml"))[ADAPTOR_ENV]
+        ActiveRecord::Base.configurations.update(ADAPTOR_ENV => environment_configurations)
+        ActiveRecord::Base.establish_connection(ActiveRecord::Base.configurations[ADAPTOR_ENV])
       end
 
       # require all adaptors
@@ -46,7 +44,7 @@ module Adaptation
       
       Initializer.run
 
-      @@logger = Logger.new("#{ADAPTOR_ROOT}/log/#{$environment}.log")
+      @@logger = Logger.new("#{ADAPTOR_ROOT}/log/#{ADAPTOR_ENV}.log")
       ActiveRecord::Base.logger = @@logger
       
     end

data/lib/adaptation/test/test_help.rb

@@ -1,5 +1,5 @@
 #set environment
-$environment = "test"
+ADAPTOR_ENV = "test"
 
 Adaptation::Initializer.run
 
@@ -143,7 +143,7 @@ class Test::Unit::TestCase
 
     ActiveRecord::Base.remove_connection
     
-    ActiveRecord::Base.establish_connection(ActiveRecord::Base.configurations[$environment])
+    ActiveRecord::Base.establish_connection(ActiveRecord::Base.configurations[ADAPTOR_ENV])
 
     database_exists = true
     begin
@@ -154,7 +154,7 @@ class Test::Unit::TestCase
 
     error = build_message error,
             "? database not found",
-            ActiveRecord::Base.configurations[$environment][:database]
+            ActiveRecord::Base.configurations[ADAPTOR_ENV][:database]
     assert_block error do
       database_exists
     end
@@ -178,7 +178,7 @@ class Test::Unit::TestCase
 
     ActiveRecord::Base.remove_connection
 
-    ActiveRecord::Base.establish_connection(ActiveRecord::Base.configurations[$environment])
+    ActiveRecord::Base.establish_connection(ActiveRecord::Base.configurations[ADAPTOR_ENV])
 
     database_exists = true
     begin
@@ -189,7 +189,7 @@ class Test::Unit::TestCase
 
     error = build_message error,
             "? database shouldn't exist",
-            ActiveRecord::Base.configurations[$environment][:database]
+            ActiveRecord::Base.configurations[ADAPTOR_ENV][:database]
     assert_block error do
       !database_exists
     end

data/lib/adaptation/version.rb

@@ -1,8 +1,8 @@
 module Adaptation
   module VERSION #:nodoc:
     MAJOR = 0
-    MINOR = 0
-    TINY  = 1
+    MINOR = 1
+    TINY  = 7
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

data/lib/commands/console.rb

@@ -1,32 +1,43 @@
 irb = RUBY_PLATFORM =~ /(:?mswin|mingw)/ ? 'irb.bat' : 'irb'
 
+require 'optparse'
+
+options = { :irb => irb }
+OptionParser.new do |opt|
+  opt.banner = "Usage: console [environment] [options]"
+  opt.on("--irb=[#{irb}]", 'Invoke a different irb.') { |v| options[:irb] = v }
+  opt.on("--debugger", 'Enable ruby-debugging for the console.') { |v| options[:debugger] = v }
+  opt.parse!(ARGV)
+end
+
 libs =  " -r irb/completion"
 libs << " -r readline"
-libs << " -r rubygems"
-require 'rubygems'
 
-begin
-  exists_debug_lib = require 'ruby-debug'
-  if !exists_debug_lib.nil? && exists_debug_lib == true
+if options[:debugger]
+  begin
+    require 'rubygems'
+    require 'ruby-debug'
     libs << " -r ruby-debug"
+    puts "=> Debugger enabled"
+  rescue Exception
+    puts "You need to install ruby-debug to run the console in debugging mode. With gems, use 'gem install ruby-debug'"
+    exit
   end
-rescue
 end
 
-libs << " -r adaptation"
-
-if RUBY_PLATFORM =~ /(:?mswin|mingw)/
-  ENV_PATH = "/windows/temp"
-else
-  ENV_PATH = "/tmp"
+ADAPTOR_ENV = case ARGV.first
+  when "d"; "development"
+  when "t"; "test"
+  else
+    ARGV.first || 'development'
 end
 
-f = File.new("#{ENV_PATH}/adaptor_path.rb", "w")
-path="ADAPTOR_ROOT = \"" + "#{ADAPTOR_ROOT}\""
-f.write("#{path}")
-f.close
+# set console environment
+libs << " -r #{ADAPTOR_ROOT}/config/environments/#{ADAPTOR_ENV}.rb"
+
+libs << " -r #{ADAPTOR_ROOT}/config/boot"
+
+puts "Loading #{ADAPTOR_ENV} environment (Adaptation #{Adaptation::VERSION::STRING})"
 
-libs << " -r #{ENV_PATH}/adaptor_path.rb"
-libs << " -r adaptation/console/environment"
 exec "#{irb} #{libs} --simple-prompt"
 

data/lib/commands/subscribe.rb

@@ -1,5 +1,3 @@
-require 'adaptation'
-
 args = ARGV
 mom = "druby"
 ARGV.each do |arg|

data/lib/rails_generator/generators/applications/app/app_generator.rb

@@ -47,18 +47,19 @@ class AppGenerator < Rails::Generator::Base
       # settings.yml
       m.template "configs/settings.yml", "config/settings.yml"
 
-      # boot.rb, needed by some scripts
+      # boot.rb
       m.file "configs/boot.rb", "config/boot.rb"
 
       # Environments
       #m.file "environments/boot.rb",    "config/boot.rb"
       #m.template "environments/environment.rb", "config/environment.rb", :assigns => { :freeze => options[:freeze] }
+      m.file "environments/environment.rb", "config/environment.rb"
       #m.file "environments/production.rb",  "config/environments/production.rb"
-      #m.file "environments/development.rb", "config/environments/development.rb"
-      #m.file "environments/test.rb",        "config/environments/test.rb"
+      m.file "environments/development.rb", "config/environments/development.rb"
+      m.file "environments/test.rb",        "config/environments/test.rb"
 
       # Scripts
-      %w( generate destroy about publish subscribe breakpointer console ).each do |file|
+      %w( generate destroy about publish subscribe console ).each do |file|
         m.file "bin/#{file}", "script/#{file}", script_options
       end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: adaptation
 version: !ruby/object:Gem::Version 
-  version: 0.1.6
+  version: 0.1.7
 platform: ruby
 authors: 
 - Xavi Vila Morell
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-03-11 00:00:00 +01:00
+date: 2009-04-01 00:00:00 +02:00
 default_executable: adaptation
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -44,7 +44,6 @@ extra_rdoc_files:
 files: 
 - bin/subscribe
 - bin/destroy
-- bin/breakpointer
 - bin/about
 - bin/adaptation
 - bin/publish
@@ -54,7 +53,6 @@ files:
 - lib/adaptation
 - lib/adaptation/base.rb
 - lib/adaptation/console
-- lib/adaptation/console/environment.rb
 - lib/adaptation/version.rb
 - lib/adaptation/mom.rb
 - lib/adaptation/message.rb
@@ -119,7 +117,6 @@ files:
 - lib/commands/breakpointer.rb
 - lib/commands/console.rb
 - lib/commands/about.rb
-- lib/commands/adaptor_path.rb
 - lib/commands/subscribe.rb
 - lib/commands/destroy.rb
 - lib/commands/generate.rb
@@ -135,6 +132,9 @@ files:
 - configs/settings.yml
 - configs/empty.log
 - configs/boot.rb
+- environments/environment.rb
+- environments/development.rb
+- environments/test.rb
 - dispatches/dispatch.rb
 - README
 - CHANGELOG

data/bin/breakpointer

@@ -1,3 +0,0 @@
-#!/usr/bin/env ruby
-require File.dirname(__FILE__) + '/../config/boot'
-require 'commands/breakpointer'

data/lib/adaptation/console/environment.rb

@@ -1,42 +0,0 @@
-require 'yaml'
-$environment = "development"
-$config = YAML::load(File.open("#{ADAPTOR_ROOT}/config/settings.yml"))[$environment]
-Adaptation::Base.new
-# connect to test database
-require 'active_record'
-
-if File.exists?("#{ADAPTOR_ROOT}/config/database.yml") 
-  configurations = YAML::load(File.open("#{ADAPTOR_ROOT}/config/database.yml"))[$environment]
-  ActiveRecord::Base.configurations.update($environment => configurations)
-  ActiveRecord::Base.establish_connection(ActiveRecord::Base.configurations[$environment])
-end
-
-if File.exists?("log")
-  ActiveRecord::Base.logger = Logger.new("#{ADAPTOR_ROOT}/log/"+$environment+".log")
-end
-
-def get_xml_from_file xml_file
-    contents = new Array
-    File.open(xml_file).each { |line|
-      unless line =~ /^ {0,}#/
-        contents << line.strip.chomp
-      end
-    }
-    "#{contents.chomp}"
-end
-
-def xml_to_object xml_message
-  class_name = xml_message[1..(xml_message.index(/(>| )/) - 1)]
-  message_class = Object.const_get(class_name.capitalize)
-  message_object = message_class.to_object(xml_message)
-  message_object
-end
-
-def xmlfile_to_object xml_file
-  xml_message = get_xml_from_file(xml_file.to_s)
-  message_object = xml_to_object xml_message
-  message_object
-end
-
-
-

data/lib/commands/adaptor_path.rb

@@ -1 +0,0 @@
-ADAPTOR_ROOT = "/usr/share/oademand/sugarcrm4.5/installer"