File: README — Documentation for adaptation (0.1.8)

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 message
    logger.info "Received message #{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.

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