Technical Documentation

Technical Documentation

Chapter 1. Fractal ADL

Fractal ADL is a language based on XML. It allows to describe software architectures as a set of Fractal components.

The syntax of Fractal ADL is described by a DTD.

For further informations, go to:

Chapter 2. The kernel

2.1. The ecore model

In order to work with the EMF/GMF tools, the Fractal ADL language in F4E is represented by a ecore model. This ecore model is a extended description of the Fractal ADL language. The model has been created from the Fractal ADL description provided by the standard.dtd.

Some others concepts not present in the standard.dtd have been added in order to manage the merge between Fractal ADL files, to display merged elements, and to be able to deal with the Fractal ADL arguments.

Here, a simplified version of the model:

For lisibility reasons, all references to the Value element and all composition relationships to merged elements and to the Comment element have been removed. Many labels have been removed too.

All red elements are concepts that have been defined in the Fractal ADL description provided by the standard.dtd.

The AbstractComponent has been added to factorize the Component and Definition elements.

The System element has been added to play the root role. To Put the Definition element as the root element raises some problems, especially with GMF. By default the root element is mapped by the canevas and not by a shape, and it is a problem as we want to map the Definition element as a shape.

The red elements have been added to manage the inheritance concept of Fractal ADL. This is not described in the dtd of Fractal ADL, but it is implicitly defined by the syntax of the extends and definition attributes value.

Green elements have been added to manage the arguments concept of Fractal ADL. It is not described in the dtd but can be used in most of string values of the Fractal ADL attributes.

For each model element that maps a Fractal ADL element, the any and anyAttributes have been added. These attributes allow to deal with elements not present in the standard.dtd but described in Fractal ADL extensions.

An example to resume that have been said. Let's take as example the Fractal ADL Interface element.

Its description in the standard.dtd is

<!ELEMENT interface (comment*) > 
	<!ATTLIST interface 
  		role (client | server) #IMPLIED 
  		signature CDATA #IMPLIED 
  		contingency (mandatory | optional) #IMPLIED 
  		cardinality (singleton | collection) #IMPLIED 

To create attributes on the model element from the dtd description, we copy the attributs name, and we convert types.

CDATA -> EString
(client|server) -> Role
(mandatory | optional) -> Contingency
(singleton | collection) -> Cardinality

The #IMPLIED option is translated by setting to 0 Lower Bound attribute of the ecore role attribute.

The XML element


of Fractal ADL is not processed by F4E but we process XML comments described between

 <!--   --> 

. It means that all XML comments placed before the


element in our example, will be stored in a instance of the model element Comment that will be associated to the instance of the Interface element.

In order to manage the XML comments for the interface XML element, we add a composition relationship, that must be named comments, from the Interface to the Comment element.

As name and signature XML attributes can contain arguments, we add two composition relationships to the Value element. The convention for these relations is to set their name with the same name than the related attribute suffixed by AST, in our case nameAST and signatureAST.

After that, merged attributes must be added, in our example they store the state of the attributes once the Interface element is merged. The naming convetion for these attributes is to prefix the name of the non merged attribute by merged and to upcase the next character. Here mergedName, mergedSignature, mergedRole, mergedCardinality and mergedContingency. The type of these attributes is the same that the non merged attributes.

Finnally we add the any and anyAttributes attributes.

2.2. The Fractal ADL files management

2.3. serialisation

2.4. helpers

All model elements have a helper that can be accessed by the getHelper. This method is added automtically in the implementation of the element ( classes of the org.ow2.fractal.f4e.fractal.impl package) by modifications on the EMF JET templates scripts. These scripts are located into the template folder of the org.ow2.fractal.f4e.emf plugin.

This method getHelper returns a helper with IxxxHelper type. If a new element is added to the ecore model, a helper must be added too.

These helpers are eclipse Adapters. They are partialy created by the FractalFactoryImpl class. Elements creation methods have been manually modified to create a helper after the element creation.

Helpers that are not created during the creation of the element, are created when we try to get the helper by the adapt method of the HelperAdapterFactory class. This class is a singleton and it is used by the getHelper method.

Helpers are grouped in the org.ow2.fractal.f4e.fractal.adapter.helper package.

2.5. parsers

Some non-atomic concepts of Fractal ADL are described as simple XML attributes.

For example when we extend a component, we use the extends attribute which is set with the definitions we want to extend e.g: "definition1, definition2".

Here the two separate informations which are extend "definition1" and extend "definition2" are expressed in a atomic way by the syntax extends="definition1,definition2".

To extract the information, the string "definition1,definition2" must be parsed.

This choice, may be, has been done for usability reasons. It is quicker to write extends="definition1,definition2" rather than, for instance:

	<definition name="definition1"/>
	<definition name="definition2"/>

The problem with this choice is that all informations are not longer easily provided by standard XML parsers. To extract these implicit information and represent it into the model instance, some parsers have been created with ANTLR.

Remember the model:

These parsers are:

  • ArgumentsADL.g3: parses the string value of the arguments attribute of definition XML element. It take as parameter an element of type Definition , create model elements of type FormalParameter and add them to the argumentsAST relationship of the given definition.

    Example: parsing attribute arguments="arg1,arg2" creates two FormalParameter

    FormalParameter(name=Value(Constant(constant=arg1)), value=null)

  • DefinitionsADL.g3: parses the definition attribute string of the component XML element. It take as parameter an model element of type Component, create elements of type DefinitionCall and add them to the extendsAST relationship of the component passed as parameter.

    Example: parsing attribute definition="definition1(arg1),definition2(arg${b}=${c})" creates two elememnts of type DefinitionCall


  • ExtendsADL.g3: parses the string value of the extends attribute of the definition XML element. It takes as parameter a model element of type Definition and creates elements of type DefinitionCall, adds them to the extendsAST relationship of the definition passed as parameter.

    To find the Fractal ADL definitions files that a definition or a component extends, the singleton SDefinitionLoadLocator is used. It allows to get the absolute URL of a Fractal ADL file from a definition name.

  • InterfaceADL.g3: parses the string value of the client and server attributes of the binding XML element. It takes as parameter a model element of type Binding, creates elements of type Value and set them as value of the clientAST and serverAST attributes of the binding passed as parameter.

    Example: parsing the attribute value definition="c1.itf1" creates a model element of type Value:


  • ValueADL.g3: parses the string value of all XML attributes except : the name attribute of the definition XML element, the mandatory, role, cardinality and contingency of the interface XML element.

    Example: parsing the string value component${b} creates a Value element:


    The parsing update is done via listeners associated to each model element. When attributes are modified the listeners launch the parsing.

    These listeners are contained in the package: org.ow2.fractal.f4e.fractal.adapter

2.6. The merge

The merge support is mandatory to have the complete architecture represented by a Fractal ADL file.

Various solutions have been thought.

The chosen solution has been to reimplement a merge algorithm that is directly performed on the EMF model instance of the Fractal ADL files.

Each model element of the F4E model that can be merge has a helper which implements the IMerge interface. The merge is done with the help of the UpdateMergeVisitor class which visit the components tree and call the updateMerge method of their helper adapter.

The merge algorithm consists for one given component to get all the others components from which it can inherit. These others components (parents nodes) are placed in a list in sort by inheritance priority order and then merged with the component. This piece of code is located in the AbstractComponentHelper, see the getNodesToMerge and the mergeFeature methods.

2.7. OCL constraints

A weak point of the current Fractal ADL factory is its errors management. It often hard to find out the syntaxic and semantic error we've done in the Fractal ADL file.

With the OCL constraints system, we can point out elements concerned by errors directly on the editors.

The OCL constraints set are stored in the constraints.ocl file that is located in the org.ow2.fractal.f4e.fractal.ocl package.

The standard way to express OCL constraints with EMF is to use extension points, or adding OCL constraints as meta-data in the ecore model.

For lisibility, and maintainability reasons, we didn't choose standard ways and we've choosed to store OCL constraints in one file.

During the F4E plug-in loading, the org.ow2.fractal.f4e.fractal.ocl.adapter.ValidatorAdapter singleton is associated to the Fractal ADL ecore model. This is done in the start method of the class file. When a validation command is performed on a model element, the validate method of the ValidatorAdapter is called. This method visit all defined constraints, and constraints that can applied to the checked model element, are applied.

The OCL file is loaded during the plug-in loading by the OCLConstraintLoader class. After the loading, the file is given to the OCL environment contained by the ValidatorAdapter singleton. The ValidatorAdapter parses the OCL file and loads the constraints.

When a constraint is violated a diagnostic is created and associated to the model element that doesn't respect the constraint. To be able to provide a human understandable message, we need to associate descriptions to constraints. These descriptions are meta-data stored in the comments of the OCL file. As the OCL parser suppress all comments, we can't simply handle them. To work around this limitation, we've created a simple OCLComments.g3 parser that allows to get the OCL file meta-data. This meta-data management is very primitive, and we need to respect some conventions like the fact that each constraint must have a description.

To add a new constraint in the file, we have:

  • to specify the OCL constraint context with the keyword context followed by the element type on which the constraint is applied
  • to define potential functions the the keyword def
  • to define invariant with the keyword inv
  • to add a comment -- description: ' followed by the constraint description message. It is possible to define a second line to define the severity level -- severity: ' followed by WARNING or ERROR.


-- description: The specified client and server interfaces must be found 
-- severity: WARNING
context Binding 
inv : if self.oclAsType(ecore::EObject).eContainingFeature().name = 'bindings' 
      self.clientInterface <> null and self.server <> self.serverInterface <> null 

When the user verifies a Fractal ADL instance model with the validate method, icons markers are added on elements that are concerned by the errors raised by constraints, and on the Fractal ADL file element.

These markers are managed in the followed files :

  • org.ow2.fractal.f4e.fractal.util.FractalResourcesUtil
  • org.ow2.fractal.f4e.fractal.ocl.adapter.ValidatorAdapter
  • IMarkerHelper
  • MarkerHelper
  • FractalDecorator

OCL constraints validations management in the graphical editor:

  • org.ow2.fractal.f4e.diagram.custom.decorators.AttributesMaskerContrainerDecorator
  • org.ow2.fractal.f4e.diagram.custom.part.ValidateAction
  • org.ow2.fractal.f4e.diagram.custom.providers.AttributesMaskerDecoratorProvider
  • org.ow2.fractal.f4e.diagram.custom.providers.FractalMarkerNavigationProvider
  • org.ow2.fractal.f4e.diagram.custom.providers.FractalValidationDecoratorProvider
  • org.ow2.fractal.f4e.diagram.custom.providers.FractalValidationProvider

Chapter 3. The tree editor (EMF)

3.1. The merged elements support

The requirement for merged elements are :
  • the inherited elements, comming from the merge between a Fractal ADL definition and its parent, must be displayed in gray, and can't be edited.
  • Merged elements do not have to be in conflict with the non merged elements and attributs.
  • For a relationship with a cardinality equal to 1, the merged element must not be displayed simultaneously with the non merged element.

    For example if the user defines a content in a Fractal Definition, the model Content model element contained in the mergedContent relationship must not be displayed.

    To do this, the generated ItemProviders have been modified and new NonEditableItemProviders have been created. When a item provider has to be created, the ExtendedFractalItemProviderAdapterFactory processes the creation demand and if the model element on which the item provider will be associated is a merged element (it means if the model element is contained in a relationship with a name prefixed by merged) then a NonEditableItemProvider is created, else it is a conventional ItemProvider. This NonEditableItemProvider allows to the merged elements to be non editable and displayed in gray in the tree.

  • For relationships with a multiple cardinality, an element uniquely identified by its keys (generaly the name attribute) can't be contained simultaneously in a merged relationship and the related non-merged relationship. For example a interface of name 'a' is contained in the interfaces or in the mergedInterfaces, but not in both.
  • In the property sheet, an entry which is related to an attribute that is not initialized (in the unset state), must display the value of the merged attribute. If the user modify the value, the new value and not the one of the merged attribute must be displayed. The MergedItemPropertyDescriptor class solves this issue and chooses to display the merged attribute or the non-merged attribute.

    For example if a interface of name n has its attribute signature unset, and that the definition inherits an interface name n with a signature="MyJavaClass" from its parent, then the value display in the property sheet entry of the unset property will be MyJavaClass with a gray background.

3.2. Completion

3.2.1. Completion in the property view

The solution used to support the completion, has been to modify the cells of the properties view. The cells have now a little button that opens a dialog box allowing to select the wanted value(s).

Each Fractal ADL attribute, that needs a completion feature, defines a Descriptor class, a CellEditor class, and a Dialog class. The CellEditor class defines the graphical cell that displays the value attribute in the properties view entry. The Dialog class defines the window that will be opened when user clicks on the completion button defined in the graphical cell. The Descriptor class allows to define the relationship between the attribut and its cell.

Package and classes involved in the completion management are:

  • org.ow2.fractal.f4e.diagram.custom.ui
  • org.ow2.fractal.f4e.diagram.custom.providers.FractalExtendPropertyDescriptor
  • org.ow2.fractal.f4e.diagram.custom.providers.FractalJavaClassPropertyDescriptor
  • org.ow2.fractal.f4e.diagram.custom.providers.FractalJavaSignaturePropertyDescriptor
  • org.ow2.fractal.f4e.diagram.custom.providers.FractalPropertyDescriptor
  • org.ow2.fractal.f4e.diagram.custom.providers.FractalPropertySource
  • org.ow2.fractal.f4e.fractal.diagram.sheet.FractalPropertySection

3.2.2. Completion in the graphical view

In the graphical view, the completion is allowed for the label of the AttributesController signature and for the <empĥasis>Content</empĥasis> signature.

The customized parsers extends the ISemanticParser, without what the getCompletionProcessor method is never call. Parsers are by in the FractalParserProvider class.

Package and classes involved in the graphical label completion management are:

  • org.ow2.fractal.f4e.fractal.diagram.custom.parers

3.3. Other customizations

  • The color background modification for attributes in the properties view.

    By default the attributes color is alterned (white/gray). In our case, attributes must be in white, and merged attributes in gray.

    See class: org.ow2.fractal.f4e.fractal.diagram.sheet.FractalPropertySection

  • Navigation between Fractal ADL and Java.

    When a double click is performed on an interface Signature or on a component Content , the related java file, if found, is displayed.

    See the org.ow2.fractal.f4e.fractal.presentation.DoubleClickListener class.

  • Create a merged Fractal ADL file.

    It is possible to generate a merged Fractal ADL file from the the current edited Fractal ADL definition. The merged file creation suppress the extends, and the extends attributes, and copy the merged model elements as a non merged model elements.

    See the org.ow2.fractal.f4e.fractal.presentation.action.CreateMergedFractalFile

  • Unset properties

    In the properties view, when a atttribute value is set, the value is serialized. For example the Role attribute can be client or server, if the user selects one of these values, client for example, then role="client" is serialized in the Fractal ADL file. As the user can only choose between client and server, one of these values is serialized. The problem is that sometime we want to set a value in a non initialized to say that we don't want to serialize the attribute. To do this, the Reset to default value of the contextual menu of the property sheet entry has been modified.

    See the org.ow2.fractal.f4e.fractal.diagram.sheet.FractalPropertySection

Chapter 4. The graphical editor (GMF)

4.1. Models

After the creation of the Fractal ADL semantic model, we need to create a three other models in order to use GMF:

  • the notational model which describes the graphical elements that will be used in the graphical editor.
  • the mapping model which describes the relations between the semantic model and the graphical model.
  • the tooling model which describes the palette structure.

From these three models, GMF tools allow to create the generation model which is used to generate the graphical editor code.

The graphical editor generated code can't be deeply extended manually without loosing the code consistency when the code is regenerated after models modifications. For this reasons, the generated code is now, only modified manually.

The notation, mapping and tooling models are in the org.ow2.fractal.f4e.gmf project.

The generated source code of the graphical editor is in the org.ow2.fractal.f4e.emf.diagram plug-in. The java classes written manually are located in the custom-src folder. Most of manual modifications done on the generated source code are associated to a comment containing 'hand modifs', modified generated methods are annotated @generated NOT, methods created manually doesn't have the @generated annotation.

Let's note that the eclipse outline of a java displays in red the methods with the @generated NOT annotation , in blue the ones with the @generated annotation, and in black methods without the @generated annotation.

4.2. Graphical figures customization

Figures defined in the notational model are described as customizable figures. It means that figures is implemented by a custom java classes. All the customized figures are located in the org.ow2.fractal.f4e.diagram.custom.figures.

4.3. EditParts customizations

EditParts have been customized :

  • to update Fractal interfaces when their role are modified. We have then to change the figure and the position. See the class.
  • to expose the interface label visibility in order to show/hide them by filtering methods. See the java classes :

4.4. EditPolicies customizations

EditPolices have been modified :

  • to manage remove the drag and drop for merged elements
  • to avoid the delete method on merged elements
  • to add custom handles to show/hide compartments
  • to manage the requests comming from the customized handles
  • to suppress scrollbars of the compartments which doesn't have the mouse focus
  • to manage the requests comming from the filtrating command.
  • to restrict the interface move around components and definitions

See packages:

  • org.ow2.fractal.diagram.custom.edit.policies
  • org.ow2.fractal.diagram.custom.edit.policies.compartments

4.5. Layouts customizations

Layouts have been customized :

  • to display correctly the interfaces labels. See the InterfaceConstrainedTolbarLayout class.
  • to display correctly interfaces that depend on their role (client to the left, server to the right). See the InterfaceBorderItemLocator class.
  • to display the bindings anchors to the correct location on the interfaces. See the classes :
    • org.ow2.fractal.diagram.custom.edit.policies
    • BindingConnectionAnchorSource

See package org.ow2.fractal.diagram.custom.layouts

4.6. Compartments customizations

To improve the lisibility of architecture, two mechanisms have been added. One based on custom handles to show or hide the differents compartments of the component and definition graphical figures, the second one constists on filtering actions that have been added to the graphical editor toolbar.

The code which deals with handles is principally located in the packages :

  • org.ow2.fractal.f4e.diagram.custom.ui.handles
  • org.ow2.fractal.f4e.diagram.custom.ui.requests

The org.ow2.fractal.f4e.notation extends the notation model to be able to save the state of the customized handles.

Filtering actions allow to show or hide compartements by type and interfaces labels.

See :

  • org.ow2.fractal.f4e.diagram.custom.ui.actions
  • org.ow2.fractal.f4e.diagram.custom.edit.policies.compartments
  • org.ow2.fractal.f4e.diagram.custom.ui.providers.FractalDiagramContributionItemProvider
  • org.ow2.fractal.f4e.diagram.custom.ui.actions.l10n.FractalDiagramUIActionsPluginImages

Chapter 5. Editors synchronization

By default there is no synchronization between the EMF editor and the GMF editor.

It means that the same file opened simultaneously in both editors implies two model instances in memory.

The synchronization allows to work on the same model instance.

The synchronization raise a number of problems:

  • edition must be done on the same model
  • the do/undo management must be shared
  • the saving state must be synchronized
  • editors should use the same properties view
  • the selection should be shared (has not be done)

For further informations see:

Chapter 6. Fractal ADL launchers

The Fractal ADL launchers are based on the same one used to launch java files. The differences are that the java class to run, and the program and JVM arguments are predefined. In our case the java class to run is the Fractal ADL launcher class, the JVM arguments are -Dfractal.provider and the program argument is the Fractal definition name of the Fractal ADL file to launch.

Icon, and actions in the Run As menu have also been added.

All is done in the org.ow2.fractal.f4e.adl.launcher

To support Fraclet, special launchers have been added. From an source folder, there are two commands in the Fractal contextual menu allowing to run the spoon processor on all contained Java files to generate the Java and Fractal ADL files associated to the Fraclet Java annotations. The generated Java source files are placed in the created spooned directory to avoid clash with the Java source files located in the source folder having the same name. The generated Java class files are directly put in the bin folder overwritting the class files of the related Java files located in the source directory. It allows to launch the Fractal ADL files with the correct Java class implementation. The limitation is that when the JDT automatic builder recompile the Java source files (when the user modify a Java file for example), the class files of the generated Java files are overwritted and then the user needs to regenerated manually the Java files when he wants to launch his application.

The best solution will be to have a automatic builder that detect changes on the Java files and apply the spoon processor in the background. This builder exists, it is named spoon-jdt, but it is not longer supported. Eclipse and the JDT on which spoon-jdt is based have evolved and are not longer compatible with the current eclipse and JDT version. Updating spoon-jdt is not trivial and the time needed without previous spoon/jdt knowledge is hard to evaluate. I've spent more than 1 week on it without success in having a stable version.

For further information :

Chapter 7. Fractal libraries integration

In order to be able to launch the Fractal ADL factory, Fractal explorer, etc... we need to embedded a number of libraries.

These libraries are the set of jar files located in the libraries directory of fractal-distribution project. These jars are simply copied in the fractal/lib folder of the org.ow2.fractal.distribution.libraries plug-in.

In the org.ow2.fractal.f4e.feature plug-in file, the unpack option has to be specified to true for libraries plug-in.

With this unpack option set, the libraries plug-in is unpacked in the default installation directory of eclipse. The plugins org.ow2.fractal.adl.launcher and org.ow2.fractal.eclipse.plugin can then used the Fractal libraries to launch Fractal ADL files, or initialize the classpath of a Fractal project for example.

Chapter 8. Fractal tutorials integration

The embedded Fractal tutorials came from the fractal-distribution project. The .tar.gz archives are copied at the root directory of the org.ow2.fractal.distribution.tutorials plug-in.

The unpack option in the feature plug-in must be set to true.

The code that create tutorials creation wizards is located in the org.ow2.fractal.eclipse.plugin.

A extension point has been created in order to simplify the integration of new tutorials.

To add a new tutorial, we just have to copy the tutorial archive at the root folder of the tutorials plug-in and to add an extension point in the org.ow2.fractal.eclipse.plugin:

            name="Tutorial name">

You also have to add the archive name in the of the org.ow2.fractal.distribution.tutorials plugin.

Chapter 9. Bibliography

Synchronization between the EMF and GMF editors:

Various eclipse articles on the IBM website:

The IBM EMF/GEF redbook:

2001-2009 © ObjectWeb Consortium  | Last Published: 2009-08-26 10:35  | Version: 1.0.0