Cilia/Getting Started Tutorial/Hello World

From Wiki Adele Team
Jump to: navigation, search

Hello World Sample

In this lesson, you will manipulate Cilia mediation chains. We will extend the Hello Mediator example to add other mediators to the chain. In addition, we will study other capabilities of mediators and bindings.

Overview

The goal of this section it to create a simple mediation chain with only one mediator i.e. the “Hello World” mediator. The mediator receives an input string from a GUI and displays and “Hello, …” message into the standard output console.


Hello-chain.png

Mediator Implementation

A mediator is composed of three elements: processor, scheduler and dispatcher (for an detailed explanation see the Cilia Overview). In this subsection, for the Hello World mediator we will present its elements, then the mediator description and finally the mediation build process.

Processor

The processor of the Hello Mediator takes the data received by the mediator, next it extracts the content of this data (a string in this case), then it adds the text “hello, ” to this string, and finally it sends the data to the next mediator. The Java class implementation corresponding to this processor is as follows:

package fr.liglab.adele.cilia.components.mediators;

import fr.liglab.adele.cilia.Data;

/**
 * The Hello World Processor Class
 * 
 */
public class HelloProcessor {

   /**
    * Method modifying the received data
    * 
    * @param data The processor received data
    * @return The data with "Hello, " prefix
    */
   public Data sayHello(Data data) {
      if (data != null) {
         data.setContent("Hello, " + data.getContent().toString());
      }
      return data;
   }
}

Each element in Cilia must be described using the Cilia DSL language. In this description is provided information about the class implementing the processor, the method used to treat the data, and the data type used to transport information (by default is fr.liglab.adele.cilia.Data).

This description is realized as follows:

   <processor name="HelloProcessor"
      classname="fr.liglab.adele.cilia.components.mediators.HelloProcessor">
      <cilia:method name="sayHello" data.type="fr.liglab.adele.cilia.Data" />
   </processor>

Scheduler and Dispatcher

A set of prebuilt Schedulers and Dispatchers are available into the Cilia compendium distribution. For this mediator we will use the Immediate Scheduler (the data is passed to the processor when they are received by the scheduler) and the Multicast Dispatcher (the data is passed to the all next mediators).

Mediator Description

The mediator is described into the Cilia DSL language. The description indicates each element forming the mediator (scheduler, processor and dispatcher). The description file is a follows:

   <mediator-component name="HelloMediator" category="samples">
      <cilia:processor name="HelloProcessor" />
      <cilia:scheduler name="immediate-scheduler" />
      <cilia:dispatcher name="multicast-dispatcher" />
       <ports>
          <in-port name="unique" type="*" />
          <out-port name="unique" type="*" />
       </ports>
   </mediator-component>

Build (Compilation and Packaging)

For build process we use Maven as presented in a prevoius lesson . To launch the build of this project the command “mvn clean install” must be executed in an OS console.

If the build process ends successfully the bundle "hello-mediator-1.0.0-SNAPSHOT.jar" must be in the target directory of the project.

Mediator Deployment

Mediator deployment is simple, it consists only in copying the file produced by maven (hello-mediator-1.0.0-SNAPSHOT.jar) into the load directory of the installed platform. Indeed, mediator bundles are compliant OSGi bundle, it can be installed using provided capabilities by the installed platform. In our case, we have installed a Felix platform with the FileInstall extension, it allows the automatic deployment of bundles only putting files into a specific directory (e.g. the load directory).

Hello World Chain

Chain Description

Once the mediators created a chain can be created using instances of these mediators. We will create a chain having only one instance of the Hello World mediator presented above.

A Cilia chain descriptor has three sections: adapters, mediators and bindings. Adapters section defines the entry and exit points of a mediation chain, these points are represented by adapters instances. In our Hello World example, we have utilized two existing adapters; the gui-adapter allowing take data from a GUI and the console-adapter allowing send data to the standard output (cilia console). In mediators section we define and configure the instance of our HelloWord mediator. Finally in bindings sections, the entryAdapter is bound to hello mediator (data taken by the GUI Adapter is sent to the mediator) and the hello mediator is bound to the console adapter (data produced by the hello mediator is sent to the console).

The Hello World chain is described as follows:

<cilia>
  <chain id="HelloWorldChain">

    <!-- Adapters instances definition -->
    <adapters>
      <adapter-instance type="gui-adapter" id="entryAdapter" />
      <adapter-instance type="console-adapter" id="exitAdapter" />
    </adapters>

    <!-- Mediators instances definition -->
    <mediators>
      <mediator-instance type="HelloMediator" id="hello" />
    </mediators>

    <!-- Bindings definition -->
    <bindings>
      <binding from="entryAdapter:unique" to="hello:unique" />
      <binding from="hello:unique" to="exitAdapter:unique" />
    </bindings>

  </chain>
</cilia>

In a chain description a unique id attributed must be defined to identify the chain, in our sample the chain id is HelloWorldChain. In mediators section an instance of the mediator HelloMediator has been described, the id attribute for each instance must be specified, our instance is called hello. The instance's ports must be also be defined, the hello instance has a input port in and an ouput port out.

A graphical representation of the Hello World chain is shown in the next figure:


Hello-chain.png

Chain Deployment

The deployment of the chain is similar to a mediator deployment. In this case, the file describing the chain (a XML document having as extension dscilia) is placed into the load directory of the platform. The Cilia runtime takes in account this kind of files, it processes the file creating the instance indicated into the file and finally the defined bindings. As result, the user have a GUI window used to enter text, and when it push the Send Data button the information is sent to the hello mediator that process them and next deliver the data to the standard console, that shows the greeting message.


Example Resources

Source code

Some examples are available in the github repository

https://github.com/AdeleResearchGroup/Cilia/tree/master/examples

Cilia source code

Get the Cilia code

  git clone git://github.com/AdeleResearchGroup/Cilia.git


List of repositories

<repositories>
  <repository>
    <id>maven-cilia-repository-release</id>
    <name>Cilia - Release</name>
    <url>http://repository-cilia.forge.cloudbees.com/release/</url>
    <layout>default</layout>
  </repository>
  <repository>
    <id>maven-cilia-repository-snapshot</id>
    <name>Cilia - Snapshot</name>
    <url>http://repository-cilia.forge.cloudbees.com/snapshot/</url>
    <layout>default</layout>
  </repository>
</repositories>