Authors: | Laurent Goubet
Axel Richard Jonathan Musset |
---|---|
Contact: | laurent.goubet@obeo.fr, axel.richard@obeo.fr, jonathan.musset@obeo.fr |
Copyright © 2008, 2010 Obeo™.
The reader should have a minimal knowledge about MDA concepts, the eclipse platform, Android and the java language.
This tutorial is part of a set offered by Obeo. Each document of this set deals with a different aspect of mastering Acceleo:
This is a quick tutorial.
This tutorial is performed on the Eclipse 3.5 (Galileo) Modeling Bundle. This bundle contains all of the required components to follow through the whole tutorial (EMF, Acceleo, OCL, ...). You can download the appropriate Eclipse Bundle on the Eclipse Download Page .
Android works like Java. You need an Android Runtime in order to execute your Android applications.
You can download Android SDK and the Android Development Tool (ADT) Eclipse Plugin on the official download page.
For the installation, follow the official instructions.
For this tutorial, the Android SDK starter package version is the R05, and the SDK platform is the 2.1. The ADT Plugin version is the 0.9.6.
The last step of installation is to link Eclipse with the SDK:
To run an Android application, you have to create an Android Virtual Device (AVD). With Eclipse, select Window > Android SDK and AVD Manager.
Create a new AVD.
For more information about the AVDs : http://developer.android.com/guide/developing/tools/avd.html.
The example presented in this tutorial is the creation of a classic Android application : MyContacts. This application is a contact manager with a screen to edit people information.
You will see how you can create an Acceleo code generator in an Android context but it also works on other domains...
The Ecore meta-model describes what a simple Android application is with the Activity and Widget concepts. If you need more information about EMF and Ecore, visit : http://www.eclipse.org/modeling/emf/.
Construct the Ecore meta-model : ~~~~~~~~~~~~~~~~~~~~~~~~~~/images/android_tutorial/~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
An Android application is made up of a Project, Activities and Widgets. A Project contains activities. An Activity contains widgets. Several kind of widgets exist like TextFields, Spinners, Buttons... In our case, the meta-model only contains concepts we need for the application. Add more widgets or other concepts if needed.
The root package must contains a Namespace URI (i.e. a unique identification) :
A Project can contains 0 or an infinity of activities (represented by -1 in the Upper Bound) :
The Widget EClass is an interface for the different widget types :
The Text EClass is a subclass of Widget :
The EMF Generator model will generate the code representing the meta-model.
Once the meta-model created, you have to create a Run Configuration that will allow you to use the meta-model (as a plugin).
2. Right-Click on the Eclipse Application item and select New. Rename the configuration, choose a location, and run it.
Note that it's also possible to identify the ecore metamodel with its URI even though it is defined in the same eclipse workspace.
In the new Eclipse Runtime environment, you are going to create a new Android Project.
The source of the "MyContacts" android application can be retrieved here. It contains an Eclipse projects with the necessary classes and models.
We are going to create the model of our MyContacts application.
Now the Android project, the Android meta-model and the MyContacts model have been created, we are going to create the code generation project:
The new project will appear in the package browser and a small Acceleo decorator will indicate that it is a generation project.
The This will generate a file checkbox means that the file will generate text in a file. Concretely, a File Tag appears in the template. The first argument is the filepath.
As mentioned in the OMG specification, MTL files (modules) can call for templates or queries defined in other MTL modules.
There is another way to create automatically this main module file by following the different steps of the wizard : New > Other > Acceleo Model To Text > Acceleo Main Module File.
With Acceleo, you can select any part of a static text in a template and the completion will offer you to replace it by a dynamic Acceleo expression. It shows the number of occurrences that will be replaced along too. Here, we'll replace all the occurrences of the String MyContacts in the different modules by the [a.name.toUpperFirst()/] Acceleo expression. Take note that the default Acceleo Expression proposed is [name.toUpperFirst()] in this case, but you can write any expression you want.
The expressions are automatically updated as you change the selected one.
In the Android meta-model, you have different types of Widgets, like Text, Spinner, Button... Acceleo provides a way to customize quickly your code, and manage the different possibilities. With the combo For/If, you can apply a specific treatment to each kind of Widgets.
Each kind of Widget is isolated.
Be careful with the For Loop. Inside of it, use an explicit call for the name of the Activity.
You can also use the Extract Template tool by selecting a static text, right-click and run: Refactor > Extract Template....
Rename and edit your new template.
The Quick fixes allow you to create templates and queries easily. When you are in an Acceleo expression, write the name of the template/query you want to create and then right-click and run: Quick Fix. Then, you can choose the adapted operation you want, like Create template - after last member.
Fill in the template body.
Use this new template.
You are ready to run and test your own version of the application.
Your generation project is reusable with another model. In a few clicks, you can create a model of an application that will count the OlympicGames medals and generate it !
The incremental generation consist in defining specific zones with user tags [protected] in order to keep you own code between the generations.
User tags now surround your initial code selection.
From now on, the code inside the User tags will be kept by any subsequent generation. Manual code entered outside of the User tags will be ignored and overwritten on the next generation. In this example, the "BAD CODE" String will not be there after the next generation, because it has been written outside User tags in a generated file.
Acceleo provides tools to easily edit and maintain the code.
The Result View shows how the text, the templates, and the models are synchronized. After a generation, select any element in the Result View and the associated generated code will be highlighted. Likewise, select any piece of code in a generated file, and you will see the associated element in the Result View.
You can also right-click on an element in the Result View and run: Open declaration. This will open the Acceleo expression associated with the element.
The Patterns View is a tooling view where you can define you own completion proposal item for the Acceleo editor.
As an example, if you want to define a query for each kind of Widget, check [query] for all selected types and each kind of Widgets. Then, in a module, the completion will propose the pattern you defined.
Just rename the queries and add the return type.
The Overrides View is an entry point to easily override an existing template behavior.
In the Overrides View, select the template you want to override. Then, in a module, the completion will offer to override the template you selected.
Now you can make a complete Android code generator with more widgets...
The end result of this tutorial should be 5 projects; you can retrieve them in this zip if you wish to compare your result with the original.