• Documentation
 
Fractal Tutorial : HelloWorld with Fraclet and Fractal ADL

Fractal Tutorial : HelloWorld with Fraclet and Fractal ADL


Chapter 1. Introduction

Let's go to program our first Fractal application. To facilitate the Fractal programming, Fraclet and Fractal ADL tools will be used.

Our application will just display a '->Helloworld !' message on the console. It is composed of :

  • a server component that provides an interface 's' to print messages on the console. It can be parameterized via a "header" attribute to configure the header printed in front of each message.
  • A client component provides an interface 'r' which displays the message '->Helloworld !'. To do this the client component uses the interface 's' of the component server to print some messages. Finally a client-server composite component which contains our client and server components. To display our message we will call the interface 'r' of the root component.

Chapter 2. The steps

To create our Fractal application, the steps are :

  • Create primitive components. To do this :
    • create Java interfaces that will be associated with our Fractal interfaces.
    • create a Java class which contains the business code of the component.
    • annotate our Java code with Fraclet annotations
  • Encapsulate primitives components that must be bound together in a common composite. This composite is described with Fractal ADL. It is not possible to create composite component with fraclet annotations.
  • call the Fractal ADL factory which will create an instance of our architecture.

2.1. The files that will be created

Summary of the five files that will be created:

  • Service.java that will be associated with the client and server Fractal interface 's'.
  • ClientImpl.java and ServerImpl.java that will be the content of our primitive components and the implementation of our Java interfaces
  • ClientServerImpl.fractal : a Fractal ADL file to describe the architecture of the client-server composite component.

Chapter 3. Implementation

So first, we need to define the Java interface that will be associated with our Fractal interfaces.

3.1. Interfaces


package helloworld;

public interface Service {
  void print (String msg);
}

Let's note that our "r" interface has a java.lang.Runnable as signature. It is not mandatory but it is usefull when we want to launch the application with the Fractal ADL launcher.

3.2. Components

The interfaces have been created, now we are going to create the primitive components

3.2.1. The server primitive component

The server component has a interface named 's' that allows to print some message to the screen. It also has a header attribute to display a header in front of all messages.

Let's write the Java code of our server.


package helloworld;

import helloworld.Service;

public class ServerImpl implements Service {

	private String header;
	
	public ServerImpl() {
		System.err.println("SERVER created");
	}

	public void print(final String msg) {
		System.out.println(header + msg);
	}
}

As you can see it is just pure Java. Now we would like to transform it to a Fractal component. To do so we need to add extra information. We can add these information with Fractal annotations.

Example 3.1. helloworld.ServerImpl.java


package helloworld;

import helloworld.Service;

import org.objectweb.fractal.fraclet.annotations.Attribute;
import org.objectweb.fractal.fraclet.annotations.Component;
import org.objectweb.fractal.fraclet.annotations.Interface;

@Component(provides = @Interface(name = "s", signature = helloworld.Service.class))
public class ServerImpl implements Service {
	
	@Attribute(value="->")
	private String header;
	
	public ServerImpl() {
		System.err.println("SERVER created");
	}

	public void print(final String msg) {
		System.out.println(header + msg);
	}
}



The annotations are parsed by a tool named Fraclet that will create automatically Fractal ADL definitions for our primitive components. Fractal ADL is an architecture description language. The architecture of our application is described by a collection of Fractal ADL files. These files are just xml files with a .fractal file extension and conform to Fractal ADL DTD.

@Component indicates that we want to create a new primitive component definition which will have as Java content the annotated Java class. Fractal definitions have a name. By default the name given to the Fractal ADL definition of our component is the same that the class so here "helloworld.ServerImpl".

provides = @Interface(name = "s", signature = helloworld.Service.class) indicates that our component provides a Fractal interface with a name 's' and a Java signature helloworld.Service.

@Attribute(value="->") indicates that our component has an attribute. The Fraclet tool generates automatically the attribute control interface for the annoted attributes. The implementation of the control interface is also generated. The default name of the Java signature of the attribute control interface is the name of the class + AttributeController, in our case helloworld.ServerImplAttributeController.

3.2.2. The client primitive component

The client component has a interface named 'r' that allows to print a '->Helloworld!' message to the screen. To print the message, the client component will use the 'print' service provided by the server that will be accessible with the Fractal interface 's' of our client

Example 3.2. helloworld.ClientImpl.java


package helloworld;

import helloworld.Service;

import org.objectweb.fractal.fraclet.annotations.Component;
import org.objectweb.fractal.fraclet.annotations.Interface;
import org.objectweb.fractal.fraclet.annotations.Requires;

@Component(provides=@Interface(name="r",signature=java.lang.Runnable.class))
public class ClientImpl implements Main {

	public ClientImpl () {
		System.err.println("CLIENT created");
	}

	@Requires(name = "s")
	private Service service;

	public void run() {
		service.print("Hello World !");
	}
}



The client component class has a required Fractal interface with a signature helloworld.Service and a name 's'. In Java, required interfaces are implemented as fields. When you annotate the field private Service service; Fraclet will process the annotation and inject some code to implement the BindingController interface and will provide methods (bindFc, unbindFc, lookupFc, listFc) allowing the association between the Fractal interface and the associated Java field.

The Java type of the field must be a Java interface compatible with the signature of the provided interface that will be connected to. In our case, as we will use the interface 's' of the server component having a signature of type Service, our private private field service has the same Service type.

3.2.3. The root component

Now we can assemble our client and server components in a root component

Fraclet tool is used in order to create primitive components. The composite components description requires using Fractal ADL tool.

Example 3.3. ClientServerImpl.fractal


<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE definition PUBLIC "-//objectweb.org//DTD Fractal ADL 2.0//EN" 
"classpath://org/objectweb/fractal/adl/xml/basic.dtd">

<definition name="helloworld.ClientServerImpl">
  <interface name="r" role="server" signature="java.lang.Runnable"/>
  <component name="client" definition="helloworld.ClientImpl"/>
  <component name="server" definition="helloworld.ServerImpl"/>
  <binding client="this.r" server="client.r"/>
  <binding client="client.s" server="server.s"/>
</definition>



A Fractal definition of a component can be seen as its description. Let's note that the the Fractal ADL factory which creates the instance of the components, try to find ADL definitions in the classpath. It is that why the full definition name is helloworld.ClientServerImpl. This name specifies that the ClientServerImpl can be found in the helloworld Java package.


<definition name="helloworld.ClientServerImpl">

This describes an empty component.


<interface name="r" role="server" signature="java.lang.Runnable"/>

We indicate that our root component has a provided interface named 'r' with a signature java.lang.Runnable. You don't need to declare control, and internal interfaces. They will be created automatically.

Let's note that by default the cardinality and contingency of an interface is "singleton" and "mandatory", respectively. Other values can be specified like this:


<interface name="..." role="...." signature="..." cardinality="collection" contingency="optional"/>

We can't specify the visibility of a Fractal interface with Fractal ADL, by default the visibility is external. The internal interfaces of the composite component are automatically created. You can't provide a Java content for the composite component in Fractal ADL.

The root component has two subcomponents that will be named 'client' and 'server'. We don't have to describe these components as their fractal ADL definitions have been created by Fraclet from the annotations. We just have to make a link to the .fractal files that contain the definition of the components that we want to add.


<component name="client" definition="helloworld.ClientImpl"/>
<component name="server" definition="helloworld.ServerImpl"/>

We now have to describe the bindings of the assembly. First the binding between the subcomponents.

A binding needs client and server interfaces :


<binding client="..." server="..."/>

A component is referenced by its name, and a interface too. In our case we want to bind the client interface 's' of the component named client to the server interface 's' of the component named server


<binding client="client.s" server="server.s"/>

Now we want to bind the interface 'r' of the root component to the interface 'r' of the subcomponent named client. The root component can't be referenced by its name because it is the component we are defining , we can reference it by using the name this.


<binding client="this.r" server="client.r"/>

3.3. Build and run the application

To launch the application we will call a special class org.objectweb.fractal.adl.Launcher with helloworld.ClientServerImpl as argument which is the ADL definition of our root component. It will have as effect to create an instance of the architecture and the method run of the interface 'r' will be called.

3.3.1. Maven

To build and launch example with Maven is very easy just type :

mvn -Prun
		

3.3.2. Ant

To build and launch example with ant it is also very easy just type :

ant run
		

Alternatively you can just generate the helloworld.jar and call the fractal launcher script on the helloworld.ClientServerImpl

With ant, we first need to package the helloworld application in a jar :

ant dist
		

We can call the Fractal ADL factory on our Fractal ADL file

Linux :

bash $FRACTAL_HOME/bin/fractal.sh -cp dist/helloworld.jar -adl helloworld.ClientServerImpl
		

Windows :

%FRACTAL_HOME%\bin\fractal.bat -cp dist/helloworld.jar -adl helloworld.ClientServerImpl
		
 
1999-2009 © OW2 Consortium  | Last Published: 2009-02-03 18:29  | Version: 1.1.2-SNAPSHOT