adaptation 0.0.1

data/CHANGELOG

@@ -0,0 +1 @@
+* 0.0.1 (18 June 2007)

data/README

@@ -0,0 +1,90 @@
+== Welcome to Adaptation
+
+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:
+
+Application A publishes messages on topic A, and all applications interested 
+on reading messages from A subscribe to its 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 
+   you can also specify wich topics your adaptor is interested in.
+4. Start developing your adaptor, probably generating __Adaptors__, __Messages__ and __Models__.
+
+
+== 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
+a more stable solution like Xmlblaster should be chosen. 
+
+
+== Description of contents
+
+app
+  Holds all the code that's specific to this particular adaptor.
+
+app/adaptors
+  Holds adaptors that should be named like messagename_adaptor.rb for
+  automated mapping. All adaptors should descend from Adaptation::Adaptor.
+
+app/messages
+  Holds messages that should be named like messagename.rb.
+  Messages descend from Adaptation::Message.
+
+app/models
+  Holds models that should be named like post.rb.
+  Most models will descend from ActiveRecord::Base.
+
+config
+  Configuration files for the Adaptation environment, the mom, the adapted application, 
+  the database, and other dependencies.
+
+db
+  Contains database related scripts.
+
+doc
+  This directory is where your adaptor documentation will be stored.
+
+lib
+  Application specific libraries. Basically, any kind of custom code that doesn't
+  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. 
+
+script
+  Helper scripts for automation and generation.
+
+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.
+

data/bin/about

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

data/bin/adaptation

@@ -0,0 +1,19 @@
+require File.dirname(__FILE__) + '/../lib/ruby_version_check'
+Signal.trap("INT") { puts; exit }
+
+require File.dirname(__FILE__) + '/../lib/adaptation/version'
+if %w(--version -v).include? ARGV.first
+  puts "Adaptation #{Adaptation::VERSION::STRING}"
+  exit(0)
+end
+
+# freeze   = ARGV.any? { |option| %w(--freeze -f).include?(option) }
+app_path = ARGV.first
+
+require File.dirname(__FILE__) + '/../lib/rails_generator'
+
+require 'rails_generator/scripts/generate'
+Rails::Generator::Base.use_application_sources!
+Rails::Generator::Scripts::Generate.new.run(ARGV, :generator => 'app')
+
+# Dir.chdir(app_path) { `rake rails:freeze:gems`; puts "froze" } if freeze

data/bin/destroy

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

data/bin/generate

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

data/bin/mom

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

data/bin/subscribe

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

data/configs/boot.rb

@@ -0,0 +1,10 @@
+# Don't change this file. Configuration is done in config/environment.rb and config/environments/*.rb
+
+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

data/configs/databases/mysql.yml

@@ -0,0 +1,48 @@
+# MySQL (default setup).  Versions 4.1 and 5.0 are recommended.
+#
+# Install the MySQL driver:
+#   gem install mysql
+# On MacOS X:
+#   gem install mysql -- --include=/usr/local/lib
+# On Windows:
+#   gem install mysql
+#       Choose the win32 build.
+#       Install MySQL and put its /bin directory on your path.
+#
+# And be sure to use new-style password hashing:
+#   http://dev.mysql.com/doc/refman/5.0/en/old-client.html
+development:
+  adapter: mysql
+  database: <%= app_name %>_development
+  username: root
+  password:
+<% if socket -%>
+  socket: <%= socket %>
+<% else -%>
+  host: localhost
+<% end -%>
+
+# Warning: The database defined as 'test' will be erased and
+# re-generated from your development database when you run 'rake'.
+# Do not set this db to the same as development or production.
+test:
+  adapter: mysql
+  database: <%= app_name %>_test
+  username: root
+  password:
+<% if socket -%>
+  socket: <%= socket %>
+<% else -%>
+  host: localhost
+<% end -%>
+
+production:
+  adapter: mysql
+  database: <%= app_name %>_production
+  username: root
+  password: 
+<% if socket -%>
+  socket: <%= socket %>
+<% else -%>
+  host: localhost
+<% end -%>

data/configs/mom.yml

@@ -0,0 +1,8 @@
+mom:
+  type: druby 
+  port: 8080
+  host: 127.0.0.1
+subscriber:
+  port: 8081
+  host: 127.0.0.1
+  topics: all

data/dispatches/dispatch.rb

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

data/dispatches/publish.rb

@@ -0,0 +1,11 @@
+unless defined? ADAPTOR_ROOT
+  ADAPTOR_ROOT = File.expand_path(File.dirname(__FILE__) + '/..')
+end
+require 'drb'
+require 'yaml'
+
+config = YAML::load(File.open("#{ADAPTOR_ROOT}/config/mom.yml"))
+mom_uri = "druby://#{config["mom"]["host"]}:#{config["mom"]["port"]}"
+
+mom = DRbObject.new(nil, mom_uri)
+mom.publish ARGV[1], ARGV[0]

data/doc/README_FOR_APP

@@ -0,0 +1,2 @@
+Use this README file to introduce your application adaptor and point to useful places in the API for learning more.
+Run "rake appdoc" to generate API documentation for your adaptors and messages.

data/fresh_rakefile

@@ -0,0 +1,10 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require(File.join(File.dirname(__FILE__), 'config', 'boot'))
+
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+require 'tasks/rails'

data/helpers/publish.rb

@@ -0,0 +1,24 @@
+class Adaptation::Adaptor
+
+  def publish *options
+
+    message_object = nil
+    if options.first.is_a?(Adaptation::Message)
+      message_object = options.first
+    elsif options.first.is_a?(String)
+      xml_message = options.first
+      message_type = xml_message[1..(xml_message.index(/(>| )/) - 1)]
+      message_class = get_class_object(message_type.capitalize)
+      message_object = message_class.to_object(xml_message)
+    end
+
+    mom = File.new(File.dirname(__FILE__) + '/mom.txt', "a")
+    mom.write("#{message_object.to_xml.to_s}\n")
+    mom.close
+    
+    #   configuration = {}
+    #   configuration.update(options.pop) if options.last.is_a?(Hash)
+
+  end
+
+end

data/helpers/test_helper.rb

@@ -0,0 +1,6 @@
+unless defined? ADAPTOR_ROOT
+  ADAPTOR_ROOT = File.expand_path(File.dirname(__FILE__) + '/..')
+end
+require 'rubygems'
+require 'adaptation'
+require "adaptation/test/test_help"

data/lib/adaptation/adaptor.rb

@@ -0,0 +1,32 @@
+module Adaptation
+#= Adaptation::Adaptor -- The message processor
+#
+#Adaptation::Adaptor is the base class for those classes containing the logic to be executed when a message is read through the mom. 
+#
+#Each class extending Adaptation::Adaptor must implement the _process_ function, using it as the main entry point for the logic to be executed when a message arrives. The name of the class extending Adaptation::Message associates the class with the one to be executed when a message arrives. Ie. if a message is received with a root element named _<hello>_, adaptation will search for a class extending Adaptation::Adaptor named _HelloAdaptor_. 
+#
+#<i>Adaptation::Adaptors</i> (classes extending Adaptation::Adaptor) must be stored under <i>app/adaptors_name</i> in the adaptation file tree. This is done automatically when an adaptor is generated using adaptation built-in generator:
+#  script/generate adaptor hello
+# 
+  class Adaptor
+    
+    def publish *options
+      message_object = nil
+      if options.first.is_a?(Message)
+        message_object = options.first
+      elsif options.first.is_a?(String)
+        xml_message = options.first
+        message_type = xml_message[1..(xml_message.index(/(>| )/) - 1)]
+        message_class = get_class_object(message_type.capitalize)
+        message_object = message_class.to_object(xml_message)
+      end
+      
+      xml = message_object.to_xml
+      unless system("oappublish '#{$config["application"]}' '#{xml}'")
+        puts "Problem publishing: #{xml}"
+      end
+    end
+
+  end
+
+end

data/lib/adaptation/base.rb

@@ -0,0 +1,70 @@
+module Adaptation
+
+  class Base
+
+    def initialize
+      $environment = "development"
+      $config = YAML::load(File.open("config/settings.yml"))[$environment]
+
+      # require all adaptors
+      Dir["#{ADAPTOR_ROOT}/app/adaptors/*.rb"].each do |f|
+        require f
+      end
+
+      # require all messages
+      Dir["#{ADAPTOR_ROOT}/app/messages/*.rb"].reject{|f| f =~ /\/_/}.each do |f|
+        require f
+      end
+
+      # require all models
+      Dir["#{ADAPTOR_ROOT}/app/models/*.rb"].each do |f|
+        require f
+      end
+
+      # connect with database -> this could also be avoided?
+      if File.exists?("config/database.yml")
+        development_configurations = YAML::load(File.open("config/database.yml"))[$environment]
+        ActiveRecord::Base.configurations.update("development" => development_configurations)
+        ActiveRecord::Base.establish_connection(ActiveRecord::Base.configurations[$environment])
+      end
+    end
+
+    def process(xml_message)
+      # dirty method to discover the message type
+      message_type = xml_message[1..(xml_message.index(/(>| )/) - 1)]
+      
+      begin
+        message_class = get_class_object(message_type.capitalize)
+        message = message_class.to_object(xml_message)
+     
+        adaptor_class = get_class_object("#{message_type.capitalize}Adaptor")    
+        adaptor = adaptor_class.new
+      rescue Exception => e
+        # message no implemented in this adaptor
+        return
+      end
+ 
+      unless message.check
+        puts "WARNING:Message doesn't validate!" 
+        return
+      end
+      
+      adaptor.process message
+    end
+
+    def get_class_object(searched_class)
+      class_object = nil
+      ObjectSpace.each_object(Class){|aClass|
+        class_object = aClass if aClass.to_s == searched_class
+      }
+      if class_object.nil?
+        #puts "Unknown class #{searched_class}."
+        raise Exception.new("Unknown class #{searched_class}.")
+      else
+        return class_object
+      end
+    end
+
+  end
+
+end