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 (mom) using a publish/subscribe pattern:
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.
Adaptation is highly inspired by Ruby on Rails web framework, so adaptors are built in a similar way that web apps are built using the RoR 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 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
-
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.
-
If no message oriented middleware has been already set, change directory into myadaptor and start the mom:
> mom
This will start a mom in localhost (default), listening on port 8080 (default).
-
Subscribe your adaptor to the mom, 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 localhost:8080, using port 8081 to subscribe (subscribing means starting a new server that listens for message publication notifications). These values can be changed editing config/mom.yml. In mom.yml you can also specify wich topics your adaptor is interested in.
-
Right now you should have a mom_ listening for messages on localhost:8080, and an adaptor subscribed to that mom and listening on localhost:8081, 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 <helloworld/> 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 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 myadaptor/app/adaptors/application.rb:
class ApplicationAdaptor < Adaptation::Adaptor def process logger.info "Received message #{}" end end
Now, if the previous <helloword/> message is published, that should be visible in log/development.log.
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 app/messages/helloworld.rb:
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 app/adaptors/helloworld_adaptor 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 a more stable solution like Xmlblaster should be chosen.
Different message brokers can be configured in config/mom.yml, and example configuration for supported moms are present in the same file when an adaptor is generated with the adaptation command.
When we want to publish/subscribe to a mom different than the default druby, we can do so by adding the MOM=mom_type 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.
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 calling the adaptor (contains dispatch.rb).
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.
Debugging
TODO: ruby script/console + ruby-debug
Testing
TODO