Acceleo 2.6 User Tutorial

ACCELEO

User Tutorial

This handbook is the exclusive ownership of its authors and was conceded to the profit of Obeo SARL. This handbook is protected by intellectual ownership rights.

It deals with a software product called ACCELEO, currently distributed under the open source Eclipse Public License (EPL). The distribution of this handbook is however not free.

This handbook makes it possible to fully take advantage of the many advanced functionalities of ACCELEO software and required on behalf of its authors and of OBEO an important compilation and synthesis work, as well as consequent financial and time investments. Nevertheless, there may still be mistakes left in this document, OBEO shall not be held responsible for any resulting inconvenience. ACCELEO as well as the content of this document may be altered without prior notice.

This document is not under Free license. This document can be downloaded without any fee from the OBEO website after proper registering. You may read and use it for any activity, commercial or not, related to ACCELEO. Yet permission of copying, translating or distributing freely or commercially this manual is subject to prior approval by OBEO.

____________________

OBEO, ACCELEO, as well as OBEO and ACCELEO logos are registered trademarks of Obeo in France and in other countries.

All other names, titles, drawings, and logos are the exclusive ownership of their authors and are protected by intellectual ownership rights.

This handbook was written with the following tools: OpenOffice

____________________

Authors: Jonathan MUSSET, tienne JULIOT, Stphane LACRAMPE

With the participation of: Goulwen LE FUR, Julien DUPONT, Guillaume RAIMBAULT, Nathalie LEPINE, William PIERS, Cdric BRUN, and Laurent GOUBET

Copyright 2006 2008 Obeo. All rights reserved.

Summary1 - Introduction.......................................................................................................................1

1.1 - Minimum knowledge required...................................................................................11.2 - Documentation for Acceleo.......................................................................................1

2 - Installation.........................................................................................................................23 - Quick Startup....................................................................................................................3

3.1 - Import a Project into Eclipse.....................................................................................33.2 - Launch the Generation Chain...................................................................................5

4 - Modeling...........................................................................................................................74.1 - Definition....................................................................................................................74.2 - The Modelers.............................................................................................................8

4.2.1 - The UML2 Meta-Model with the EMF Modeler..................................................84.2.1.1 - Creating a Project.......................................................................................94.2.1.2 - Creating a UML2 Model............................................................................10

4.2.1.2.a - Creating a Package...........................................................................114.2.1.2.b - Creating a Class................................................................................124.2.1.2.c - Creating an Attribute..........................................................................124.2.1.2.d - Adding a Profile to a Model...............................................................134.2.1.2.e - Create an Association.......................................................................144.2.1.2.f - Validate the Model..............................................................................16

4.2.2 - Using the Example...........................................................................................164.2.2.1 - Importing a Project into Eclipse................................................................174.2.2.2 - Creating a Project Dynamic Web Project ............................................194.2.2.3 - The model WebLog_fr.uml.......................................................................224.2.2.4 - Creating a Model......................................................................................23

5 - Initializing a Project.........................................................................................................265.1 - Importing Generation Modules................................................................................265.2 - Code Generation Files............................................................................................27

5.2.1 - Previewing the Results.....................................................................................275.2.1.1 - Synchronizing the Model Code.................................................................29

5.3 - Creating the Generation Chain...............................................................................305.3.1 - Creating a Generation Chain Using the Assistant...........................................305.3.2 - Creating a Generation Chain without the Assistant.........................................34

5.3.2.1 - Adding a Model.........................................................................................355.3.2.2 - Adding a Target Folder.............................................................................375.3.2.3 - Adding a Log.............................................................................................375.3.2.4 - Adding a Meta-Model...............................................................................385.3.2.5 - Adding the Generation File.......................................................................38

6 - Generation......................................................................................................................416.1 - Running a Generation Chain...................................................................................416.2 - Importing a Tomcat server......................................................................................42

6.2.1 - Importing the Tomcat Libraries........................................................................456.3 - Testing the Application............................................................................................47

7 - Parameters.....................................................................................................................497.1 - The Generation Chains...........................................................................................49

7.1.1 - Modifying a Generation Chain.........................................................................497.2 - The logs ..............................................................................................................507.3 - The Properties Files............................................................................................51

7.3.1 - Creating a Properties File............................................................................518 - Update Management......................................................................................................54

8.1 - Manual Development..............................................................................................548.1.1 - Adding code to the servlets.............................................................................54

8.2 - Functional Updates.................................................................................................558.2.1 - Modification of the Input Model........................................................................55

8.2.1.1 - Modification of an Attribute.......................................................................558.2.1.2 - Adding a Class..........................................................................................568.2.1.3 - Deleting a Class........................................................................................578.2.1.4 - Renaming a class.....................................................................................588.2.1.5 - Adding/Modifying a Relationship (association / inheritance)...................58

8.3 - The Lost Files.....................................................................................................588.4 - Acceleo Traceability................................................................................................60

9 - Advanced Use................................................................................................................619.1 - Launching a Generation Chain Automatically from within Eclipse.........................61

10 - Additional Environments ..............................................................................................6210.1 - Managing Different Versions.................................................................................62

10.1.1 - Sharing a New Project...................................................................................6210.1.2 - Sharing Modifications.....................................................................................6310.1.3 - Loading the Modifications from Another User...............................................63

Acceleo 2.6: User Tutorial Page 1/62

1 - In t roduct ionThis document is a detailed tutorial aimed at allowing users to master the code generator Acceleo, a product developed by Obeo.

The functions dealt with will permit the creation of generation modules within projects, as well as management of products created using Acceleo over their life cycle.

Acceleo is designed for people willing to profit from MDA technologies to increase their software development productivity. It allows the generation of files using UML, MOF, and EMF modules.

This plug-in features:

Complete integration with both the Eclipse environment and the EMF framework

Code/model Synchronization

Incremental generation

Smooth adaptation for any industrial projects

Ease of update and management of templates

Syntax coloring, auto-completion and error detection

1.1 - Minimum knowledge requiredThe present guide does not intend to provide a training course for all of the issues addressed by the MDA or Acceleo. This guide assumes the readers has some knowledge in the fields of :

Java

modeling (for example: UML)

Eclipse

Knowledge of the following concepts would also be an advantage, but none is essential for the understanding of this document:

meta-models

UML2 meta-model

development of Eclipse Plug-Ins

MDA or MDD

1.2 - Documentation for AcceleoThis tutorial is part of a set offered by Obeo. Each document of this set deals with a different aspect of mastering Acceleo:

Reference: description and explanation of each keyword of the Acceleo script syntax

User Guide: documentation of Acceleo's functions

Architectural Tutorial: guide for creating and personalizing generation modules.


2 - Ins ta l la t ionAcceleo is an open source project, licensed under the Eclipse Public License (EPL), it can be downloaded and used free of charge.

The first step in installing Acceleo is then to download and install the Eclipse platform along with EMF. It is then possible to download and install Acceleo.

Acceleo can be installed in a number of distinct ways. Each is specific to the manner your Eclipse platform has been installed.

The recommended installation method is to make use of the following update site : http://www.acceleo.org/update/.

Each type of installation is detailed step-by-step in the User's Guide.


3 - Quick Star tupThis section of the tutorial is designed for those who wish to directly execute the example provided on the Acceleo site: http://www.acceleo.org/pages/download-sample-modules/en.

Extract the contents of the archive into the directory of your choice.

The archive should contain three sub directories:

free.demo.weblog

free.uml2.gen.java

free.uml14.gen.java

3.1 - Import a Project into EclipseImport free.demo.weblog into Eclipse :

Select "File" => Import... (cf. Figure 1).

Select the assistant Existing Project Into Workspace (cf. Figure 2).

Click Next .

Figure 1: Import a project (1)Figure 2: Import a project (2)


Click Browse... (cf. Figure 3) in order to open a window which contains all the files on the disk

Select the location that contains free.demo.weblog (cf. Figure 4).

Click OK .

free.demo.weblog is added to the list (cf. Figure 5). Once the list contains all the desired files Click Finish to add the project to Eclipse.

The project free.demo.weblog is a Dynamic Web Project (cf. 4.2.2.2 Creating a project Dynamic Web Project ).

Repeat the above-described procedure to import the project free.uml2.gen.java .


Figure 5: Import a Project (5)


Please note that the directory src is empty (cf. Figure 6). The generation will fill this directory.

3.2 - Launch the Generation Chain

Once both projects are imported, the free.demo.weblog>weblog.chain>Launch generation chain must be launched (cf. Figure 7).

Note : The files generated are based on the UML model WebLog_fr.uml, which has been designed in

Figure 6: Tree for both projects

Figure 7: Launch the generation chain

Figure 8: The generated files


French. An English version of the model is also provided with the example. The following pages of this guide shows pictures using the French version of the model, but it would work the same with the English version.

After clicking Launch , a progress bar shows up and once finished, the subdirectory src will contain three packages with the generated Java files. (cf. Figure 8).


4 - Model ing

The Acceleo tool offers different modeling possibilities:

UML1.x

UML2

Ecore

DSL

Others (Merise, SADT, OMT, proprietary tools..)

4.1 - DefinitionThe following is a reminder of some UML specific definitions which could be helpful to

understand the tutorial.

Profile:A profile is a standard extension mechanism for the UML language that allows the specialization of a UML scheme for a particular domain.

It consists of a coherent set of stereotypes, tagged-values and constraints

NOTE: We do not add meta-classes, but rather annotations to existing UML meta-classes .

Standard profiles do exist: profile CORBA (OMG), profile EJB 1.0 (JCP), etc.

Stereotypes:The stereotype concept enables elements to be classified (annotated) and acts as a new meta-model element.

A stereotype is a GeneralizableElement . An inherited relation is therefore possible for stereotypes. It is also possible to define abstract stereotypes in order to avoid duplications when stereotypes have common properties.

Tagged-value: The concept of tagged-values enables information to be added to classes. A tagged-value can be considered as a new meta-attribute.

Constraints: The concept of constraints is used to express the relationship between stereotypes and tagged-values.


4.2 - The Modelers

The models produced by numerous modelers are compatible with Acceleo because of its use of standard and open formats.

Acceleo is natively based on EMF, and is thus directly compatible with tools created around this framework. Examples include RSM, Together, and Omondo. Not all modelers are integrated with Eclipse, but most of them offer an XMI-type export function to ensure compatibility with other tools.

Acceleo has been successfully tested with export tools using models UML 1.4 with XMI 1.x: Poseidon, Objecteering, Sparx, ArgoUML, etc.

In order to read an XMI that is different from EMF, right-click on the XMI file and choose Convert XMI .

The procedure is always the same:

Either the modeler is integrated with Eclipse and Acceleo can directly use the XMI files, or the modeler is external, and in this case, the XMI file must be exported to a sub-directory in the workspace, and the file must be updated in Eclipse.

The following is a cinematic diagram in a DSM created via GMF :

This model is directly compatible with Acceleo because it is based on EMF.

4.2.1 - The UML2 Meta-Model with the EMF Modeler

Acceleo uses the EMF editor to open models based on UML2. This modeler is present in the Example EMF Model Creation Wizards section.

A project must have been created before creating a UML2 model.

Figure 9: Cinematic diagram in a DSM


4.2.1.1 - Creating a Project

To create a project, simply select the new project creation wizard:

File>New>Other>General>Project (Figure 11).

Enter fr.obeo.pim.demo.tutorial as the Project Name field.

Click Finish to add the project to Eclipse (figure 12).

Figure 11: Creating a project (1)




We will now create a model folder (cf. Figure 14) in this new project.

To do so :

Right-click on the project root and select the folder creation assistant New>Folder (cf. Figure 13).

Fill in the field Folder name

Click Finish to add the folder to Eclipse. An empty folder will then be created in the project.

4.2.1.2 - Creating a UML2 Model

To create a UML2 model:

Right-click on the model folder

Select the EMF model creation assistant New>Other>Example EMF Model Creation Wizards>UML2 Model (cf. Figure 15).

Click Next .

Enter the model name Tutorial.uml in the File name field. (cf. Figure 16).

Click Next .

Figure 13: Creating a folder Figure 14: Naming a folder


In the Model Object field, choose Model (cf. Figure 17).

Click Finish for the model to be created.

An empty model has been created. Now we can create the desired model.

4.2.1.2.a - Creating a Package

The first step consists of creating a package:

Right-click on the root element named Model

From the Child list, select the Package element. (Figure 18)

Figure 15: Creation of a model

Figure 16: Naming a model

Figure 17: Selecting a model object


The properties of this new Package element can be found in the Properties view. If this view is not currently displayed by Eclipse, right-click on your new package and select ShowProperties View (cf. Figure 19).

Filling in the name field is required. Let's call this package myFirstPackage (Figure 20).

Clicking on a model element allows its properties to be modified in the Properties view.

4.2.1.2.b - Creating a Class

Now that the package has been created, let's add a class "MyClass" within it. The following operations will help you do so:

Right-click on the myFirstPackage package, select the menu item " New Child>Class

Fill in the name field of the new class with as myClass.

4.2.1.2.c - Creating an Attribute

Now, to add an attribute to this class, complete the following operations:

Right-click on the class myClass, select the New Child>Property menu item.

Fill in the name field with myAttribute.

Try and fill in the type of the attribute myAttribute. The type of an attribute is modified via the corresponding property. Yet in this case, clicking on the field "type" will not allow you to use primitive types (such as String).

Figure 18: Creating a package

Figure 20: Property name

Figure 19: Displaying the property view


To use primitive types, UML2 profiles must be employed.

4.2.1.2.d - Adding a Profile to a Model

In order to set a UML2 profile, simply right-click on one of the model elements and select Load Resource... (cf. Figure 21)

In the dialog that just appeared, the URI of the profile to load must be entered. The profile containing the primitive types (integer, character string, boolean...) has the URI:

pathmap://UML_PROFILES/Standard.profile.uml. (cf. Figure 22)

Figure 21: Add a profile(1)

Figure 22: Add a profile (2)


Two new resources are then loaded within the model (cf. Figure 23).

It is now possible to select "String" as the type of myAttribute: select it in the modeler and modify the "type" property (cf. Figure 24).

To add a little something to the model, create a second class MySecondClass (cf. 3.2.1.2.b Create a class) with a single attribute mySecondAttribute (cf. 3.2.1.2.c Create an attribute).

4.2.1.2.e - Create an Association

This new attribute mySecondAttribute will be of type MyClass: simply select MyClass in the type field of the Properties view (cf. figure 25). An association between the two classes has just been created.

A second method to create an association between two classes is to add the association manually: right-click on the package and select the New Child>Association menu item.

The new association is added at the end of the model (cf. figure 26).

Figure 23: New profile

Figure 25: Create an association

Figure 24: Choosing the String primitive type


Fill in the memberEnd field of this association in the Properties view: you must make use of the selector (circled on figure 27).

A window is now opened:

Select myAttribute and click Add

Select mySecondAttribute and click Add .

Validate via OK (cf. Figure 28).

The memberEnd field is now made up of two attributes (cf. Figure 29).

Figure 26: Adding an association between two classes

Figure 27: The selector

Figure 28: Creating an association


4.2.1.2.f - Validate the Model

The model has been created. To ensure its validity, right-click on the root element, Model , and select Validate (cf. Figure 30).

4.2.2 - Using the Example

This part explains the way the example works.

An example of both a model and a script can be downloaded from the Acceleo website at the following URL:

http://www.acceleo.org/pages/download-sample-modules/en.

Extract the contents of the archive into the directory of your choice.

The archive should contain three sub directories:

free.demo.weblog

free.uml2.gen.java

free.uml14.gen.java

Figure 29: Filled in the memberEnd field

Figure 30: Validation of the model

Figure 31: Validation completed


4.2.2.1 - Importing a Project into Eclipse

Import free.demo.weblog into Eclipse.

Select "File" => Import... (cf. Figure 32)

Then select the Existing Project Into WorkSpace project import assistant (cf. Figure 33).

Click Next to import the project into Eclipse.

Click Browse... (cf. Figure 34) in order to open a window which contains all the files on the disk

Select the location that contains free.demo.weblog (cf. Figure 35).

Click OK .



The project free.demo.weblog is added to the list (cf. Figure 36). Once the list contains all the desired files Click Finish to add the project to Eclipse (cf. Figure 37).

free.demo.weblog is a Dynamic Web Project project.

Figure 34: Import a project (3)





4.2.2.2 - Creating a Project Dynamic Web Project

This section explains how the project free.demo.weblog was createdThis section will explain how the example was created and how to create it once again.

Eclipse WTP must be installed prior to following these instructions.

Select the dynamic Web project creation assistant: File>New>Other>Web>Dynamic Web Project (cf. Figure 38 & 39), then click Next .

NOTE: if "Dynamic Web Project" does not appear in your Eclipse, WTP is not what you installed.

Figure 39: Creation of a project (2)

Figure 38: Creation of a project (1)


Fill in the Project Name field with the desired name for the project and click Next (cf. Figure 40).

Click Next (cf. figure 41).






When the Open associated Perspective view (cf. figure 43) is displayed,

click Yes to obtain a J2EE perspective (cf. Figure 44)

or

No to preserve the Java perspective (cf. Figure 45).

To change the perspective manually later on, simply click the Open Perspective icon (circled on Figure 45).

Figure 44: J2EE perspective

Figure 45: Java perspective


4.2.2.3 - The model WebLog_fr.uml

In order to better understand the Weblog project, here is a UML representation of the class diagram.

The first representation is of WebLog GUI (cf. Figure 46); the second models WebLog business project (cf. Figure 47).

Figure 47: Class diagram of Weblog business project

Figure 46: Class diagram of Weblog GUI


4.2.2.4 - Creating a ModelThroughout this section the reference model will be the model WebLog_fr.uml . WebLog_en.uml is the same UML2 model, in English.

Weblog_en.uml14 is this same model, described in UML 1.4 and in English

Once the project has been created (cf: 4.2.1.1 My First Project or 4.2.2.2 Creating a Project Dynamic Web Project ), create a directory model within it.

Right-click on this new directory and select File>New>Other>Example EMF Model Creation Wizards for the EMF model creation assistant (cf. Figure 48).

Name the new model in the following dialog then continue to the model object selection.

In the Model Object section, choose Model (cf. Figure 49).

Next click Finish for the model to be created.

Figure 48: Creating a model

Figure 49: Creating a model (2)


Open this new model, right-click on its root element and select the menu item New Child . A list of the elements that can be added appears. (cf. Figure 50).

The following list describes the type of elements that can be added as children (presented above):

Profiles

Packages

Classes

Properties

Operations

Operation parameters

The attributes of these elements may be modified in the "properties" view (cf. figure 52).

If this view does not appear in Eclipse, right-click on the model (in the Reflective Editor ) and select the Show Properties View menu item (cf. Figure 51).

Figure 50: Possible children nodes


The properties will not be described in detail in this tutorial; however a few points will be addressed.

The cardinalities: Lower : Minimal cardinalities

Upper : Maximum cardinalities

Infinity is represented by -1 for the upper cardinality

Types: Type modifies the attribute type.

The name: Name changes the name of the element. This property is mandatory.

The WebLog example does not use stereotypes but keywords . The three models provided in the directory model were created with a modeler that replaced stereotypes with keywords . keywords can be considered the same as stereotypes.

Figure 52: Properties view

Figure 51: Displaying the Properties view


5 - In i t ia l iz ing a Pro jec t

The WebLog_fr.uml model will be used for this section.

5.1 - Importing Generation Modules

Because we are using WebLog_fr.uml as the reference model, the generation module corresponding to this model must be imported. The reference module which need to be imported is:

free.uml2.gen.java

This directory can be found in the archive downloaded in part 3 (cf. 3.2.2).

To import this project, refer to part 4.2.2.1 Importing a Project into Eclipse.

The two projects should appear in Eclipse (cf. Figure 53).

For the remainder of the tutorial, it is recommended that the Acceleo perspective be open. If it needs to be opened, simply click on the Open Perspective icon (cf. Figure 45), and choose Acceleo if it appears in the list. If it is not present in the presented list, select Other... , Acceleo, then confirm via Ok (cf. Figure 54).

Figure 54: Acceleo perspective

Figure 53: Projects in Eclipse


5.2 - Code Generation FilesThe free.uml2.gen.java project contains the generator files.

These files can be found in the directory src : they use the extension .mt .

These files are generation scripts and allow the generation of the desired code.

5.2.1 - Previewing the ResultsIn order to preview the generation results, you first need to open a model (in this example, WebLog_en.uml). Afterwards, right-click on either one of the model elements (does not matter which) and select the menu item Acceleo>Select Generator (cf: Figure 56).

Next, select the generator which result needs to be previewed. This example will use the template jdbc.mt , located in src>org>acceleo>modules>uml2>gen>java>dao as described on Figure 57.

Figure 55: Code generation files

Figure 56: Select a code generator


The model classes of defined with a keywords value of Entity are decorated with an arrow added (cf. Figure 58)

Previewing the code that would be generated via this template can be done through the Source tab with one of the decorated element selected (both circled on Figure 58).

Text in black is the code that has been dynamically generated and is related to the previously selected model elements. In this example, the class "User".

Likewise, the purple text is the code that has been statically generated. (cf. Figure 59).

Figure 57: Selection of the file to preview

Figure 58: Class with keywords having a value of "Entity"


5.2.1.1 - Synchronizing the Model Code

The model and the generated code are synchronized. It is thus possible to find the model element that generated a particular portion of the code, and vice versa. Simply double-click on a dynamically generated element (one that is in black), in order for its corresponding element to be selected in the model. (cf. Figure 60).

Likewise, a single click on a model element selects the corresponding generated code. (cf. Figure 61). A second click in the model selects the second occurrence of generated text, and so on.

Figure 59: Preview of the generated code

Figure 60: Synchronization of the model code


5.3 - Creating the Generation Chain

There are two possible ways to create a generation chain. Either use the available assistant or create it manually.

5.3.1 - Creating a Generation Chain Using the Assistant

In this example, the generation chains (.chain) are in the free.demo.weblog project. The location of the chain is of no importance.

To create a generation chain, it is advisable to use the Acceleo perspective (cf. Figure 45 and 54).

In the example, the generation chains have already been created. The purpose of this section is to recreate a generation chain identical to the weblog.chain generation chain.

To create a new generation chain:

Right-click on the free.demo.weblog project.

Select New>chain (cf. Figure 62).

Figure 61: Synchronization of the model code


Select the appropriate meta-model. For the purpose of this example, select the UML2 meta-model "http://www.eclipse.org/uml2/2.0.0/UML" (cf. Figure 63), then click on Next .

Select the WebLog_en.uml model (cf. Figure 64), then carry on with Next .

Figure 62: Creating a new generation chain

Figure 63: Selection of the meta-model

Figure 64: Selecting the model


Now the desired generation templates should be selected; here, all of the templates contained within the dto , dao , and ui directories (cf. Figure: 65). Continue via Next .

Finally, select the location and the name of this new generation chain (cf. Figure 66). This example chain should be located in the free.demo.weblog directory and named MyWebLog_en.chain

Figure 65: Selecting the scripts

Figure 66: Finalizing the generation chain


This new generation chain consists of the following (cf. Figure 67):

It lists the set of resources used and the actions that must take place. The specialized editor helps the user and allows for the validation of the tasks. There are two types elements: resources and the actions.

The resources part, also called "Repository", contains the whole set of resources used by the actions. There are seven types of resources:

Model: Models to which the generator will be applied

Model Set : Sets of models on which the generators will be applied

Folder: Directories in which the generation will take place

Log: Logs available to record generation errors

Meta-Model: The high level meta-models describing the input models

Script: The generators that need to be applied

Custom File : Other files that could be used by actions ( Custom Action )

The actions part, also called "ActionSet", contains all the tasks that must be launched. There are seven types of actions:

Generate: applies a generator to a model, and places the whole hierarchy of the generated files the specified target directory. The required meta-model is the one that describes the input model.

Convert Xmi: Converts an XMI 1.x file that has been exported by a non EMF modeler into an XMI 2.0 file based on EMF. This conversion can handle UML13 and UML14 meta-models defined for EMF with either the http://www.obeo.fr/acceleo/uml13 URI or the http://www.obeo.fr/acceleo/uml14 URI. This action is often used before a generation action which will be applied on the resulting converted model.

Backup: Saves all the resources from one directory to another. Several levels of backup may be defined. The backup of a target generation directory is especially useful during the template fine-tuning phase, when the risk of getting errors is greater. However, this action may be redundant and does not always work well with version management tools such as CVS or SVN. It should be used with moderation!

Clear: Empties the content of each file in a selected directory, including its subdirectories. This action does not delete the resources; it simply empties their content and produces empty files.

Remove: Permanently deletes the selected files and directories.

Call : Launches the chains with the given path ( Chain Path ), substituting the declared parameters of the sub chain by the given arguments. A double click on the new "Call" will allow the selection of the chain to call.

Figure 67: Contents of a generation chain


Custom Action : Launch a custom action on the selected resources. To specify an action you have to put the ID property.

5.3.2 - Creating a Generation Chain without the Assistant

To create a generation chain without the assistant, place the cursor over the free.demo.weblog directory and right-click. Select New>Other>Acceleo>Empty Chain (cf. Figure 68).

Click Next and name the chain, webLog_en_sa.chain (cf. Figure 69) and click Finish to add the chain to Eclipse.

The chain is created, but is empty. The required element for its operation must be added.

Figure 68: Creation of a generation chain without the assistant

Figure 69: Naming the generation chain


5.3.2.1 - Adding a Model

Open the generation chain and right-click on "Repository"

Select New Child>Model (cf. Figure 70).

There are then two possibilities to select the desired model :

The first is to enter the URI of the model in the Path field of the properties view:

/free.demo.weblog/model/WebLog_fr.uml (cf. Figure 71).

This solution is fastidious and complicated. The second is an easier way of choosing a model in the Eclipse workspace:

Double-click on the "Model" element in the editor. This action opens a dialog box to allow a selection to be made from among the available models. (cf. Figure 72).

Figure 70: Selection of a model

Figure 71: URI of the model

Figure 72: Double click on the model


Select the model directory (on the left). This selection displays the models that are present in the directory on the right-hand side. To select a model, simply check the box at its side and click OK (cf. Figure 73).

5.3.2.2 - Adding a Target Folder Open the generation chain and right-click on "Repository".

Select New Child>Folder

Then select Folder and fill the Path feature in the properties view with the path /free.demo.weblog for the target directory,

or

Double click on the Folder element,

Choose the desired location (cf. Figure 74).

Figure 73: Select a model


Click OK to validate the target directory selection.

5.3.2.3 - Adding a Log Open the generation chain and right-click on "Repository".

Select New Child>Log

Then select the Log that has just been created, and complete the Path field of the properties view as: /free.demo.weblog/WebLog_fr.log.txt ,

or

Double-click the Log element that has just been added to the generation chain.

Select the file that should be the generation's Error Log (cf. Figure 75).

Figure 74: Select the target folder

Figure 75: Select the error log


5.3.2.4 - Adding a Meta-Model

Open the generation chain and right-click on "Repository".

Select New Child>Emf Meta-model

Then select Emf Meta-model and fill in the Path property with:

http://www.eclipse.org/uml2/1.0.0/UML

or

Double-click on the meta-model that has just been created in the chain.

Select the desired meta-model URI from the list (cf. Figure 76).

5.3.2.5 - Adding the Generation File

Open the generation chain and right-click on "Repository".

Select New Child>Generator

Complete the Path field with the location of the desired generation file (.mt):

/free.uml2.gen.java/src/org/acceleo/modules/uml2/gen/java/dao/jdbc.mt.

or

Double-click the file to choose the generation file (.mt) (cf. Figure 77).

Figure 76: Choose the desired meta-model

Figure 77: Choose a generation file


It is possible to add as many Generators as desired, as demonstrated in Figure 67 above.

Now let's define the generation actions:

Right-click Action Set and Select New Child>Generate .

In the Properties view, six fields must be completed.

Documentation: Name that will be displayed by the editor for this action. The generator's file name may be used, in order to locate it easily.

Folder: Folder in which to generate the files.

Generator: Path of the generation file (.mt) to use.

Log: The error file (log) path.

Meta-model: The meta-model URI.

Model: The model path.

For each generation file (.mt) to launch, a corresponding Generate action must be defined. An example is shown on Figure 79, that Generate corresponds to the template jdbc.mt .

For the other files, the manipulation is identical except for the Documentation property since it is a name chosen by the user, which can be distinct for each file. (cf Figure 79).

Figure 78: The six property fields of a "Generate" action

Figure 79: The six propriety fields of a Generate action


6 - Generat ion

6.1 - Running a Generation Chain

Now that the generation chain has been created, it is possible to generate the files. Right-click the generation chain weblog.chain and select Launch to launch the generation (cf. Figure 80).

The src directory, which up to now had been empty, now contains three packages:

free.demo.weblog/src/org/acceleo/sample/dto

free.demo.weblog/src/org/acceleo/sample/ihm

free.demo.weblog/src/org/acceleo/sample/jdbc

These three packages contain the Java files that have just been generated.

One of the three packages (free.demo.weblog/src/org/acceleo/sample/ihm) presents errors though. These can be resolved by importing a Tomcat server into the project.

Figure 80: Launcher for the generation chain


6.2 - Importing a Tomcat server

A version of Tomcat server must first be installed on the machine. If necessary, it may be downloaded from the following address:

http://tomcat.apache.org/

If you did not install Eclipse WTP, its plug-ins are also required before testing this new application : http://www.eclipse.org/webtools/main.php.

Once the server version is installed on the machine, import it so Eclipse will recognize it:

Click the Window>Show View>Other (cf. Figure 81).

Select Server>Servers (cf. Figure 82)

Figure 81: Import a Server

Figure 82: Open Servers view


The Servers view is added to Eclipse (cf.:Figure 83).

Right-click in the Servers view, and Select New>Server (cf. Figure 84).

Select the Apache server installed on the machine. We installed Tomcat Server 5.5 for this example (cf. Figure 85).

Figure 83: The view Server

Figure 84: Select Server

Figure 85: Selection of the server


Click Next then Select the server installation directory via Browse (cf. Figure 86).

Click Next .

Select the "free.demo.weblog" project and add it to the server by clicking on Add > (cf. Figure 87).

You're done, click on Finish .

Figure 86: Select the installation directory

Figure 88: Select the project Figure 87: The project is now added


6.2.1 - Importing the Tomcat Libraries

Even though the server is installed, the errors will still appear in the second package. To finally fix these errors you need to import the Tomcat server libraries in the project. Right-click on the project, then select Properties>Java Build Path (cf. Figure 89).

Select Add Externals JARs , find the installation directory for the Apache Software Foundation/Tomcat 5.5/common/lib server, select the servlet-api.jar file and click Open(cf. Figure 90).

Figure 89: Adding the libraries from Tomcat

Figure 90: Select the corresponding library


Close this dialog box via OK (cf. Figure 91).

The library is added to the project build path , and the error are all cleared.

The WebContent directory has also been modified by the generation. It now contains a jsp directory containing the JSP files and a WEB-INF directory with, notably, the web.xml file.

Figure 92: Contents of the various folders

Figure 91: Adding the libraries to the project build path


6.3 - Testing the Application

Once the server has been installed, the application can be tested. In order to do so, you must first launch the server.

Right-click on the server displayed on the Servers view.

Select Start (cf. Figure 93).

Once the server has been launched, the Started icon appears for it in the Servers view (cf. Figure 94).

The Console view can also be consulted to check that the server has been properly launched (cf. Figure 95).

The next step is to open a Web Browser and go to the following URL: http://localhost:8080/free.demo.weblog/

Figure 93: Launch the Tomcat server

Figure 94: The server is launched

Figure 95: Console view


A menu is then displayed on the browser. This page is the Index.html file (cf. Figure 96).

The link Screen AccountEdition allows you to create a new account (cf. Figure 97).

*NOTE* The functions are not implemented only the GUI is.

Figure 96: Menu for free.demo.weblog

Figure 97: Creating an account


7 - Parameters

7.1 - The Generation Chains

In section 5.3 we detailed step-by-step how to create a generation chain. Yet the needs can change once the generation chain has been created and it may happen that the generation chain no longer meets the its needs.

It isn't necessary to create a new generation chain. Indeed, Acceleo allows the modification of an existing generation chain.

7.1.1 - Modifying a Generation Chain

Open the generation chain that need be modified. (cf. Figure 98).

To modify an element, simply double-click on it. For example, if a generation file is to be modified, the file extension (.mt) should be double-clicked, and a new file may then be selected. To select the new file:

Uncheck the previously selected template by clicking on it (cf. Figure 99). The file's check box will then be cleared:

Figure 98: The generation chain weblog.chain


Now check the new template (cf. Figure 100). The check box shows the selection.

To validate the change, click OK .

7.2 - The logs

The logs will allow the events that prevented the generation to be recorded in when errors occur during the execution of a generation chain.

The specified error log is displayed when an error arises during the generation. (cf. Figure 101).

Figure 99: Deselect the file

Figure 100: Select the new file


Simply double-click on this file to open it in Eclipse (cf. Figure 102).

Erasing the content of the log before a generation makes it easier to check whether the generation chain now runs normally or if there are still anomalies.

7.3 - The Properties Files

It's been mentioned earlier that the packages for different Java classes were parameterized according to the script. Even though they are modular, modifying the naming standards within a company requires all of the generators to be refactored.Acceleo incorporated a properties mechanism that establishes generation parameters; for example, the folder names, or package names where the files have to be generated.

This mechanism will be demonstrated by providing parameters for the package names in Weblog project.

7.3.1 - Creating a Properties File

Create a new org.acceleo.modules.uml2.utils package in the src directory for the free.demo.weblog project.

Right-click on this new package and select the New > File menu item.

In the file creation assistant enter the name config.properties (cf. Figure 103).

Figure 101: Error file

Figure 102: Content of the error file


The new config.properties file is created in the specified package (cf : Figure 104).

Type in the following two lines (both of which hereafter referred to as "keys"):package.format=com.enterpriseproject.name=weblog

Launch the weblog.chain chain. The files are now generated in the com.enterprise.weblog package instead of org.acceleo.sample (cf figure 105).

If it is later decided to change the naming standard for the packages, simply add a new_config.properties

Figure 103: Creating the config.properties file

Figure 104: The file "properties"

Figure 105: Packages generated wit parameterization


file alongside the weblog.chain file, and place within it a new value for the project.name key, such as web.weblog (supposing that the type of the product is web for the weblog). The next generation will now include the type of product "web" in the name of the packages (cf figure 106).

Figure 106: New Properties file enables the packages to have new names


8 - Update Management

8.1 - Manual Development

8.1.1 - Adding code to the servlets

It is possible to insert manual code into the generated code. Portions of the code where it is possible to insert user code are surrounded by the tags://Start of user code and//End of user code

For example, the init(HttpServletRequest req, HttpServletResponse resp) procedure in the free.demo.weblog/src/org/acceleo/sample/ihm/CreationCompteServland.java file can be personalized as follows:

Within the section reserved for user code, enter://Start of user code initif (nom.equals("Julien")){

returnCode = PAGE_CONNECTION;}//End of user code

Then the application must be restarted:

Right-click on the server in the "servers" view

Select Restart>Start (cf. Figure 107).

Refresh the current Web Browser page (F5). The action has been recognized.

If the generation chain is launched anew, the code surrounded by user tags is preserved.

The same test may be executed by adding code outside the Start of user code tags.

The modification is recognized when the server is restarted; however the code which was added outside the

Figure 107: Restarting the server


tags will be deleted with the next generation.

It is therefore very important to not write code outside of the tags intended for this use.

8.2 - Functional Updates

8.2.1 - Modification of the Input Model

Modifications can of course be made to the input model.

8.2.1.1 - Modification of an Attribute

It is possible to modify an attribute. To do this:

Select the login attribute for the User class in the Business.blog package (cf. Figure 108).

Change its name property in the Properties view: change login in identifier.

This example will be based on the /free.demo.weblog/src/org/acceleo/sample/dto/UserDto.java generated file.

Figure 108: The model


Before the modification, the attributes were generated as follows: public class UtilisateurDto implements Serializable {

// serialVersionUID is used for serialization.private static final long serialVersionUID = 1L;

protected String email;protected String prenom;protected String nom;protected String login;protected String motDePasse;

In order for the modifications to be recognized, the files must be regenerated. Simply launch the generation chain once again (cf. 6.1 Launching a Generation Chain).

The attributes are now generated as follows:public class UtilisateurDto implements Serializable {

// serialVersionUID is used for serialization.private static final long serialVersionUID = 1L;

protected String email;protected String prenom;protected String nom;protected String identifier;protected String motDePasse;

When an attribute is deleted, it is also removed from the generated files. For example, if the email attribute is deleted from the model, it will no longer appear in the generated Java files.

8.2.1.2 - Adding a ClassIt is possible to add a class to the model:

Add a new class in the blog package.

Name it Administrator.

Create two String type attributes to it; name them surname and name .

Also add to it a keywords with the value Entity . Copy Paste it from one of the existing classes. (cf. Figure 109).

Figure 109: Adding a class


Now that the class has been added to the model, the model must be saved and the generation chain must be launch again. The new Java files have been created. (cf. Figure 110).

If a class with a Screen stereotype (keyword Screen ) has been created, then the generation will also have modified the web.xml file.

Likewise, if the class had not been stereotyped, Entity (keyword Entity ), no new Java files would have been created.

8.2.1.3 - Deleting a Class

It is also possible to delete a model class.

To delete the Administrator class, right-click Administrator and select Delete .

Save the model and relaunch the generation chain.

The files corresponding to the class have not been deleted. They must be deleted manually or use chainweblog.clean.chain. Be careful, the code that was manually inserted between the two Start of user code tags (cf: 8.1.1 Adding Code in the Servlets) will be deleted. This generation chain should only be used if no code was manually inserted between the guides.

8.2.1.4 - Renaming a class

It is possible to rename a class. The procedure is identical to that used to rename an attribute. (cf. 8.2.1.1 Modifying an attribute).

Once the class has been renamed and the model has been saved, you must launch the generation chain.

The result will be identical to that observed during the deletion of a class (cf. 8.2.1.3 Deletion of a class). That is , the new Java files will have been created; yet the old ones will still exist. (cf. Figure 111). In the example below, the class User has been renamed Blogger .

Figure 110: New files have been created


8.2.1.5 - Adding/Modifying a Relationship (association / inheritance)

It is possible to add or to modify a relationship (association, inheritance). To do so, simply modify the relationship in the model, save this modification and launch the generation chain. The modification that was made will appear in the newly generated files.

8.3 - The Lost Files

If a modification is made to a generation file or a model that involves modifying the code generated between the Start of user code tags, a ".lost" file will be generated.

For example if a model attribute is deleted, and this attribute was called within "user code" tags, then when the generation chain is relaunched, the old code is placed in a file with the extension .lost .

The .lost files preserve the user code that is no longer valid due to a modification.

Figure 112: Example of a lost file

Figure 111: The new files and the old ones


8.4 - Acceleo Traceability

As a complement to Acceleo, Obeo offers the Acceleo Traceability software. Acceleo Traceability is designed towards model/code synchronization.

Here is an example usage of Acceleo Pro Traceability which warns the user when a modification is made to the code outside user tags, as this code would be lost on the next generation (cf. Figure 115).


9 - Advanced Use

9.1 - Launching a Generation Chain Automatically from within EclipseIt is possible to launch a generation chain from the application launch icon within Eclipse.

Click the drop-down list of the run tab.

Select Run... .

Double-click Chain .

Fill in the Name field with the desired name for the launching configuration.

Select the launching chain by clicking Browse (cf. Figure 113).

It is possible to select several launching chains.

To launch the generation chain, it can then be selected in the drop-down list on the Run tab. (cf. Figure 114).

Figure 113: Select a launching chain.

Figure 114: Launching the generation chain


10 - Addi t iona l Env i ronments

10.1 - Managing Different VersionsIn order to manage the different file versions, a version management tool such as CVS or SVN must be used.

These free software programs may be downloaded at http://www.nongnu.org/cvs/ (CVS) or http://subversion.tigris.org/ (SVN). Once this software is installed, the easiest way to make use of them is to install the corresponding Eclipse plug-ins. The CVS plug-in for Eclipse is installed by default. One of the SVN

plug-ins for Eclipse, Subclipse, can be found at http://subclipse.tigris.org/. Once one of these plug-ins has been installed, the version management functions may be found in the Team menu located in the pop-up menu (right-click on a resource: project, file, folder, ...).

10.1.1 - Sharing a New ProjectIf a project has not already been shared, it may be shared on a server.

To do so, right-click on the project to share. From the Team menu, select Share Project... .

If more than a single version management software have been installed (CVS is installed by default), select the one that is to be used (cf. Figure 116).

Figure 115: Acceleo Pro Traceability : example of the tool


Fill in the required fields: the host, the repository, the login and the password. Click Finish ; the data may now be used by other users.

Figure 116: Choosing the version management tool


10.1.2 - Sharing Modifications

To share modifications to a project, right-click on the project. From the Team menu, click Commit . Enter the commit message that will explain the modifications that have been made, and click OK (cf. Figure 117). The modifications are now available on the server.

10.1.3 - Loading the Modifications from Another UserTo load modifications from another user, click Team > Update. The version management tool will even manage possible conflicts, and asks the user what to do if it cannot resolve the conflict with no human intervention. Once this operation has finished, the other user's modifications are displayed.

Figure 117: Commentary window with SVN

1 - Introduction1.1 - Minimum knowledge required1.2 - Documentation for Acceleo

2 - Installation3 - Quick Startup3.1 - Import a Project into Eclipse3.2 - Launch the Generation Chain

4 - Modeling4.1 - Definition4.2 - The Modelers4.2.1 - The UML2 Meta-Model with the EMF Modeler4.2.1.1 - Creating a Project4.2.1.2 - Creating a UML2 Model4.2.1.2.a - Creating a Package4.2.1.2.b - Creating a Class4.2.1.2.c - Creating an Attribute4.2.1.2.d - Adding a Profile to a Model4.2.1.2.e - Create an Association4.2.1.2.f - Validate the Model

4.2.2 - Using the Example4.2.2.1 - Importing a Project into Eclipse4.2.2.2 - Creating a Project Dynamic Web Project4.2.2.3 - The model WebLog_fr.uml4.2.2.4 - Creating a Model

5 - Initializing a Project5.1 - Importing Generation Modules5.2 - Code Generation Files5.2.1 - Previewing the Results5.2.1.1 - Synchronizing the Model Code

5.3 - Creating the Generation Chain5.3.1 - Creating a Generation Chain Using the Assistant5.3.2 - Creating a Generation Chain without the Assistant5.3.2.1 - Adding a Model5.3.2.2 - Adding a Target Folder5.3.2.3 - Adding a Log5.3.2.4 - Adding a Meta-Model5.3.2.5 - Adding the Generation File

6 - Generation6.1 - Running a Generation Chain6.2 - Importing a Tomcat server6.2.1 - Importing the Tomcat Libraries

6.3 - Testing the Application

7 - Parameters7.1 - The Generation Chains7.1.1 - Modifying a Generation Chain

7.2 - The logs7.3 - The Properties Files7.3.1 - Creating a Properties File

8 - Update Management8.1 - Manual Development8.1.1 - Adding code to the servlets

8.2 - Functional Updates8.2.1 - Modification of the Input Model8.2.1.1 - Modification of an Attribute8.2.1.2 - Adding a Class8.2.1.3 - Deleting a Class8.2.1.4 - Renaming a class8.2.1.5 - Adding/Modifying a Relationship (association / inheritance)

8.3 - The Lost Files8.4 - Acceleo Traceability

9 - Advanced Use9.1 - Launching a Generation Chain Automatically from within Eclipse

10 - Additional Environments 10.1 - Managing Different Versions10.1.1 - Sharing a New Project10.1.2 - Sharing Modifications10.1.3 - Loading the Modifications from Another User

Documents

Acceleo 2.6 User Tutorial