== 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__[link:../rdoc/classes/Adaptation/Adaptor.html], __Messages__[link:../rdoc/classes/Adaptation/Message.html] 
   and __Models__[http://api.rubyonrails.org/classes/ActiveRecord/Base.html].


== 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[http://www.xmlblaster.org] 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.