CALICO Tutorial

Antonio de Almeida Souza Neto

November 2011

Contents

1.Introduction......................................................................................................................................3 2.Developing the Hello World example..............................................................................................3

2.1.Getting started............................................................................................................................32.2.Configuring Preferences............................................................................................................52.3.Modeling....................................................................................................................................6

Types...........................................................................................................................................7Properties....................................................................................................................................8Defining Interfaces......................................................................................................................9Parameters...................................................................................................................................9Defining Communication Elements..........................................................................................10

2.4.Model Verification...................................................................................................................112.5.Code Generation and Manipulation.........................................................................................112.6.Deployment..............................................................................................................................13

3.Incremental Development..............................................................................................................14 4.Remarks..........................................................................................................................................18

2

1. Introduction

CALICO (Component Assembly Interaction Control Framework) is a development environment for Java SCA/SOA applications integrated with Eclipse that aims to support design and validation of component-based assemblies.

It enables software architects to design their architecture and to analyze it accordingly to the constraints defined by architects or specific to the component platform (such as FraSCAti, Fractal, OpenCCM or OpenCom).

Currently, CALICO supports these tasks:

• Design of component-based architecture and their properties

• Analysis to identify incompatibilities between component interactions

• Code generation

• Deployment (remote deployment available on FraSCAti)

• Incremental development and Dynamic reconfiguration (a model change is identified automatically and can be deployed without stopping the application execution)

CALICO can be downloaded in http://calico.gforge.inria.fr/CALICO/Download . The requirements list is available in the site.

This tutorial aims to guide the architect/developer to construct his/her applications, step by step, making a simple Hello World program as example.

2. Developing the Hello World example

The example consists of all necessary steps to build an application SCA/SOA with CALICO. A generic Client component calls a Server component that generates a String “Hello World”, both having compatible interfaces.

This example requires a FraSCAti installation. To download and use FraSCAti see http://wiki.ow2.org/frascati/Wiki.jsp?page=FraSCAti .

2.1. Getting started

Once installed (follow the steps shown in the download page http://calico.gforge.inria.fr/CALICO/Download ) you are ready to start using CALICO.

Start your CALICO Server by executing calico.sh (Unix) or calico.bat (Windows) in the CALICO directory.

Start Eclipse containing your CALICO plugin. You will use CALICO directly in your Eclipse environment.

3

CALICO Plugin (Client) is responsible for the diagram design and CALICO Server is responsible for the actions executed on the model as model checking, code generation and deployment.

Now we will start the development with the CALICO environment.

Create a new Java Project accessing the menu File➝New➝Java Project.

Create a new folder (models for example) in your project.

Create a CALICO model accessible in the menu File➝New➝Example and then choose CALICO Diagram as shown below, Choose the name of your diagram (extension .calico_diagram) and your model (extension .calico) and put it in your models folder. Both files work together, so they need to have the same name.

Open the file with extension .calico_diagram to start modeling.

Now you must to see the Eclipse canvas more or less like that:

4

2.2. Configuring Preferences

Before starting your application, make sure that your preferences are well set. You can access the preferences window in the menu CALICO Tools➝Configure the preferences. CALICO will show this window:

By default, CALICO set the Source output path as '/src' and the Binary files path as '/bin' ('/target/classes' for maven projects). Normally, these configurations must have the same parameters that your project. To make simple, we recommend to preserve the default configurations set by Eclipse in your project.

Server Name and Server Port parameters configure the communication between the Eclipse Plugin

5

and CALICO Server. If you are using a normal CALICO release you must not modify these parameters.

FraSCAti Path is the URI where the FraSCAti introspection and reconfiguration service (using Fscript) is available. It uses the Rest protocol. CALICO will deploy applications on FraSCAti using this service. Check if the provided port is configured correctly on FraSCAti.

2.3. Modeling

Clicking on the canvas background you will see the application properties in the properties bar at the bottom of your Eclipse. Set the platform value to Platform Frascati. You can change this property value at any time.

In the right side, you have the palette containing all the elements you need to construct your model. To add an element just click on one of its items.

Click on CompositeEntity to start constructing your model. The root Composite is always needed.

Here we will name the composite as “helloworld”.

Now, click on PrimitiveEntity and place the component in “helloworld” composite.

Name the component “server”.

Following the same steps, add a “client” component in “helloworld” composite.

Add a ProvidedCommunicationPoint on the server, named “provServer”. It will be a service provided by the server component.

6

Add a RequiredCommunicationPoint on the client, named “reqClient”. It will be the port that requires a specific service.

Add a ProvidedCommunicationPoint on the client, named “run”. It will be the access point to run your application.

Add a Connector between the two components, named “c1” for example.

Add a link between c1 and provServer. To create a link, you have to draw the line from a Connector to a Communication Point.

Add a link between c1 and reqClient.

Now, you must have a model like that:

Types

Your design is ready, but you need to set some properties and parameters in the model elements.

Right click on the model background and then choose the option Configure Types. In the Data Types tab, you have to add all classes you will use in your application. All the types must be object types. To use primitive types, add Java classes like Integer, Boolean, Double etc. In your application you need to add just the type String.

7

Change to Communication Point Types tab. There, you will declare the Communication Point Types that generates the interfaces implemented by your components.

Add the value “java.lang.Runnable”.

Add the value “calico.examples.helloworld.InterfaceHW”.

Click OK to continue.

Properties

Right click on the server component and choose the option Configure Properties.

Add the property with name = “implementationType” and value = “java”. This property allows to generate Java code to the related component.

Add the property with name = “impl-class” and value = “calico.examples.helloworld.Server”. This property defines the full name of the class (with the package) that will be implemented for this component.

You have to do similar steps to configure the client.

Right click on the client component and choose the option Configure Properties.

8

Add the property with name = “implementationType” and value = “java”.

Add the property with name = “impl-class” and value = “calico.examples.helloworld.Client”.

Now, add the property with name = “implementationType” and value = “java” in all Communication Points.

All elements that will be implemented require this property.

Defining Interfaces

Linked components must implement the same interface to be compatibles.

To define this, click on the Communication Point provServer. You will see the properties corresponding to this Communication Point in the bottom bar. Set the type “Communication Point Type calico.examples.helloworld.InterfaceHW”.

Set the same Type to the Communication Point reqClient.

For the Communication Point run set the Type “Communication Point Type java.lang.Runnable”. It will force the developer to implement the method run() that will be used by FraSCAti as entry point.

Parameters

CALICO allows to define parameters in components. Parameters are equivalents to properties in FraSCAti. The parameters must have the type String, Boolean, or a Number like Integer, Float etc.

In this tutorial we will exemplify the use of parameters adding a parameter salutation in the server component.

To do that, right click on the server component then click on Configure Parameters.

Add a parameter having name = “salutation”, value = “Hello World” and type = “String”.

9

Defining Communication Elements

You now need to define the service contract, i. e. operations (or methods) you can call on the service. These operations are called Communication Elements in CALICO. You will need to implement business logic of defined Communication Elements after code generation.

To define a Communication Element of a Communication Point, you have just to do a double click on a Communication Point. In our example, do a double click on provServer or reqClient (any of them, because both have the same type/interface). A new void tab will be opened to design the structure of your methods.

A different palette can be seen.

Add a CommunicationElement in the model named “call”.

Add an argument named “result” in call Communication Element. Set the value false for the Input property and String for the Type property. The arguments in CALICO can be Input or Output. An input argument generates a parameter in the method while an output argument generates return of a method.

10

You don't need to define Communication Elements in the Communication Point run because its type defined previously (Communication Point Type java.lang.Runnable) is not a user type,

2.4. Model Verification

To assure the correctness of the model elements interaction, CALICO allows checking the model. To do that, just access the menu item CALICO Tools➝Check All. CALICO will show a message saying if all is OK or not.

Always check this after changing your model.

2.5. Code Generation and Manipulation

Now, CALICO is able to generate the source code skeleton from the informations defined in the model.

Click on the menu item CALICO Tools➝Generate Code.

Check the source path. You will see all the source files and packages generated and also the file helloworld.composite. Composite files describe the application architecture.

Note: Verify if the preference Source Output Path is defined correctly. If you have already add business code in previous generated files, CALICO will generate new classes in the configured Source Output Path+“gen”, for example “…/workspace/helloworld/srcgen”.

CALICO generates the code skeleton to deploy on FraSCAti containing SCA annotations such as @Reference or others. These annotations are useful in the FraSCAti development context, but you must add the library osoa-java-api-VERSION.jar in the project. This library is available in CALICO folder. If you are sure that you don't need these annotations you can remove them manually.

Delete the generated source java.lang.Runnable, we will implement the default java.lang.Runnable provided by Java.

Now you must to implement the code inside of the methods skeleton.

11

Here, we exemplify the code implemented in server and client components:

Server:

package calico.examples.helloworld;

/** * Implementation class of the component 'server'. * (Other components can share this implementation class.)*/public class Server implements calico.examples.helloworld.InterfaceHW {

private String salutation = "Hello world"; /** * Set the property 'salutation'. */ public void setSalutation(String salutation) { this.salutation = salutation; } /** * Implement the operation 'call' of the server port 'provServer'. */

public String call() { //we currently support object-based types (Integer, Boolean etc.) String result = null;

result = salutation; return result;

}

}

Client:

package calico.examples.helloworld;

import javax.swing.JFrame;import javax.swing.JLabel;

/** * Implementation class of the component 'client'. * (Other components can share this implementation class.)*/public class Client implements java.lang.Runnable {

private calico.examples.helloworld.InterfaceHW reqClient;

/** * Set the client port 'reqClient'. */public void setReqClient(calico.examples.helloworld.InterfaceHW reqClient)

{

12

this.reqClient = reqClient;}

@Overridepublic void run() {

System.out.println(reqClient.call() );

JFrame frame = new JFrame("Client");frame.setSize(150, 100);frame.setDefaultCloseOperation(JFrame.HIDE_ON_CLOSE);

JLabel label = new JLabel(reqClient.call());

frame.setLocationRelativeTo(null);frame.add(label);

frame.setVisible(true);}

}

2.6. Deployment

Finished all steps, you can deploy and use your application.

Firstly, make sure that you have started FraSCAti using the profile -Pexplorer,remote-fscript and the remote port are the same in FraSCAti and CALICO sides (8090 by default).

You just have to click on the menu item CALICO Tools➝Deploy.

Having a success message, you can go to FraSCAti explorer and, making a refresh, you will can see your components.

To execute the application, click on run then click on the run button. You will see a window containing the result “Hello world”.

13

You can change the parameters (properties in FraSCAti) at any time. To test this feature, we have changed the salutation value to “Hi World”.

Running the service another time, you can see the result of this change.

3. Incremental Development

After the first deployment, it is natural that the architect needs to change and add features to his application. Sometimes, stopping an application can be a problem to people using these services.

Trying to solve this problem, CALICO supports incremental deployment, i. e. the

14

architect/developer can continue to develop his application and to deploy new items while the application is running. CALICO calculates the difference between the previous and the new model and reconfigures the application deployed on FraSCAti dynamically.

To test this feature, we will add a pseudo translator component English-French in our application.

Add a new PrimitiveEntity named “translatorEnToFr”.

Add a new ProvidedCommunicationPoint named “provFr” on translatorEntoFr.

Add a new RequiredCommunicationPoint named “reqEn” on translatorEnToFr.

Set the type of both Communication Types to “Communication Point Type calico.examples.helloworld.InterfaceHW”.

Add the property with name = “implementationType” and value = “java” in the 3 new elements added.

Add the property with name = “impl-class” and value “calico.examples.helloworld.TranslatorEnToFr” in the translatorEnToFr component.

Add a Connector named “c2”.

Delete the link between c1 and reqClient.

Add a new link between c1 and reqEn.

Add a new link between c2 and reqClient.

Add a new link between c2 and provFr.

After complete all these steps you must have a model like that:

Click on the menu item CALICO Tools➝Check All to verify if all is OK.

15

Click on the menu item CALICO Tools➝Generate Code to generate the source code skeleton.

Replace the code of TranslatorEnToFr by the following code:

TranslatorEnToFr:

package calico.examples.helloworld;

/** * Implementation class of the component 'translatorEnToFr'. * (Other components can share this implementation class.) */public class TranslatorEnToFr implements calico.examples.helloworld.InterfaceHW {

private calico.examples.helloworld.InterfaceHW reqEn;

/** * Set the client port 'reqEn'. */public void setReqEn(calico.examples.helloworld.InterfaceHW reqEn) {

this.reqEn = reqEn;}

/** * Implement the operation 'call' of the server port 'provFr'. */public String call() {

//we currently support object-based types (Integer, Boolean etc.)String result = null;

result = reqEn.call();

if (result.equals("Hello world")) {result = "Bonjour monde";

}

return result;}

}

Deploy the application clicking on the menu item CALICO Tools➝Deploy.

Returning to FraSCAti Explorer window and clicking on refresh you can see the new component and links.

16

Click on the service run on the client component. If the property salutation is set to “Hello world”, you will see a window with the result “Bonjour monde”.

The reconfiguration was possible with the help of a reconfiguration script written in the FScript language generated automatically by CALICO (below) and sent to FraSCAti via the path specified previously.

action calico-update() {root = $domain/scachild::helloworld;new = $domain/scachild::new;set-state($root/scachild::server, 'STOPPED');

17

set-state($root/scachild::client, 'STOPPED');remove-scawire($root/scachild::client/scareference::reqClient,

$root/scachild::server/scaservice::provServer);set-state($root/scachild::server, 'STARTED');set-state($root/scachild::client, 'STARTED');set-state($root, 'STOPPED');add-scachild($root, $new/scachild::translatorEnToFr);set-state($root, 'STARTED');add-scawire($root/scachild::client/scareference::reqClient,

$root/scachild::translatorEnToFr/scaservice::provFr);add-scawire($root/scachild::translatorEnToFr/scareference::reqEn,

$root/scachild::server/scaservice::provServer);sca-remove('new');set-state($root, 'STARTED');

}

4. Remarks

The address of the official CALICO web site is http://calico.gforge.inria.fr.

The complete video of this example is available on http://calico.gforge.inria.fr/CALICO/Demo. Other videos are available in this site.

The entire CALICO source code is available in http://gforge.inria.fr/scm/viewvc.php/?root=calico with the source code of 3 examples including the Hello World example.

CALICO is a project developed by ADAM Team, to know the team and other team projects visit http://adam.lille.inria.fr.

18