Cilia/Getting Started Tutorial/Using OGSi Service

From Wiki Adele Team
Jump to: navigation, search

Consuming an OSGi service in Cilia

Cilia is built on top of the OSGi platform, consequently it can profit of OSGi capabilities. In this trial, we show how Cilia can use available services in the OSGi platform.

Example Description

This chain will receive a number (integer) into the GUI window, then the mediator processor take this data to produce a text representation of this number, finally it passes the text to the console. The particularity of this example is the utilization of an external OSGi service in order to make this conversion. In other words, the processor will delegate the conversion to the NumberConverter OSGi service.

NumberToLetters.png

The Number Converter OSGi Service

An OSGi service is a java object instance, registered into an OSGi framework with a set of properties. Any java object can be registered as a service, but typically it implements a well-known interface.

In this lesson we will use an OSGi service that take a number and returns a text representation of this number. For example for the number 5 the string returned is “five”. This service is packaged in this bundle, deploy it into the platform and the service will be available.

The service interface is as follow:

package cilia.examples.converter.service;

/**
 * Interface (service specification) of the NumberConverter service
 */
public interface NumberConverter {

   /**
    * Transforms a number into text
    * @param number The number to be transformed
    * @return The text representation of the number
    */
   public String convert(long number);
   
}


Using the command ps in the Felix shell the deployed bundles are listed. Here in the image we can see that the Number Converter Service bundle is the bundle 15 called “Cilia TP3 - Number Converter Service (1.0.0)”

Tp3-ps.png

Using the command “inspect service capability 15” display all services published by the bundle 15. Note that two services providing the same interface (specification) are presents in bundle 15, the first one is the English version of the converter, the other the French implementation.

Tp3-services.png

Mediator Implementation

Processor Implementation

The processor’s implementation class has the field converter of type NumberConverter (interface of the above OSGi service), this field will be delegated to make the number conversion (see the method process). The implementation class is as follow:

package cilia.examples.mediator;

import cilia.examples.converter.service.NumberConverter;
import fr.liglab.adele.cilia.Data;

public class NumberConverterProcessor {
   
   /**
    * Field will be injected by the framework
    */
   private NumberConverter converter;

   /**
    * Transform the received number in text
    * 
    * @param data Data containing the number
    * @return a text representation of the number
    */
   public Data process(Data data) {
      String content = (String) data.getContent();
      Long number = null;
      number = Long.decode(content);
      String wordValue = converter.convert(number.longValue());
      data.setContent(wordValue);
      return data;
   }
}

The field will be set by the framework using a technique known as dependency injection (or inversion of control). In our example, the field converter is set using available service providing the adequate interface (i.e. service specification).

The Cilia framework must be informed about field to be injected, this information is added into the processor specification. The requires tag is used to indicate to Cilia the field to be inject and which properties must be fulfilled by the required service.

In the example the field converter is required, the filter attribute indicates that the implementation must transform number in English text representation.

   <processor name="NumberConverterProcessor" classname="cilia.examples.mediator.NumberConverterProcessor">
      <requires field="converter" filter="(language=english)" id="language" />
      <method name="process" data.type="fr.liglab.adele.cilia.Data" />
   </processor>

Mediator Description

This mediator will use the immediate scheduler and the multicast dispatcher as is indicated in its specification.

   <mediator-component name="NumberConverterMediator" category="samples">
      <cilia:processor name="NumberConverterProcessor" />
      <cilia:scheduler name="immediate-scheduler" />
      <cilia:dispatcher name="multicast-dispatcher" />
   </mediator-component>

Chain Description

Two possible chains are presented in this section, the fist one uses the default filter defined by the mediator (language must be English). The second chain overrides the filter in order to use a service providing the number conversion in French.

Number Converter Chain (English Version)

<cilia>
  <chain id="converterChain" type="type1">

    <!-- 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="NumberConverterMediator" id="numberConverter" >
        <ports>
          <in-port name="in" />
          <out-port name="out" />
        </ports>
      </mediator-instance>
    </mediators>

    <!-- Bindings definition -->
    <bindings>
      <binding from="entryAdapter" to="numberConverter:in" />
      <binding from="numberConverter:out" to="exitAdapter" />
    </bindings>

  </chain>
</cilia>

Number Converter Chain (French Version)

The former chain was modified to introduce a filter in order to lookup a French Number Converter implementation of the service. This information is included when the mediator instance is specified, a deeper explanation is available in the Cilia Reference Guide.


<cilia>
  <chain id="converterChain" type="type1">

    <!-- 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="NumberConverterMediator" id="numberConverter">
        <ports>
          <in-port name="in" />
          <out-port name="out" />
        </ports>
        <property name="requires.filters">
          <property name="language" value="(language=french)" /> <!-- French version of service is chosen -->
        </property>
      </mediator-instance>
    </mediators>

    <!-- Bindings definition -->
    <bindings>
      <binding from="entryAdapter" to="numberConverter:in" />
      <binding from="numberConverter:out" to="exitAdapter" />
    </bindings>

  </chain>
</cilia>

Chain Execution

Deploy the Number Converter chain bundle and the Number Converter Service (if you have not deployed it yet). Then, you must deploy the first chain (file tp3_1.dscilia, English version) of the chain, a window is shown enter a number and see the result in the console.

Tp3-execution-english.png

To test the other chain remove the tp3_1.dscilia and deploy the tp3_2.dscilia (the French version), the result looks like this:

Tp3-execution-french.png

Example Resources

Source code in the SVN repository

svn checkout svn://svn.ligforge.imag.fr/svnroot/cilia/trunk/examples/cilia-tp3-projects

svn checkout https://svn.ligforge.imag.fr/svnroot/cilia/trunk/examples/cilia-tp3-projects

Browse the SVN code here.

Snapshot of source code

Get a snapshot of the SVN project here.

List of compiled artefacts

Number Converter OSGi Service bundle

Number Converter Mediator bundle

Mediation chain English version

Mediation chain French version