AM3/Ant Tasks

< To: ATL
< To: AM3

This page describes the obsolete ant tasks provided by the org.eclipse.gmt.am3.tools.ant plugin of AM3. The new ATL ant tasks are documented in the ATL user guide. Documentation for the standard ant tasks can be found in the ant manual.

Additional tasks are available from ant-contrib and documented in its manual. Using ant-contrib requires installing it.

About Ant

Ant is a software tool for automating software build processes. It is similar to make but is written in the Java language, requires the Java platform, and is best suited to building Java projects.

The most immediately noticeable difference between Ant and make is that Ant uses XML to describe the build process and its dependencies, whereas make has its Makefile format. By default the XML file is named build.xml.

Ant is an Apache project. It is open source software, and is released under the Apache Software License.

The root tag of any ANT file is project. It has two optional attributes: name and default:

• name is just for convenience,
• default specify the default target to execute.

The syntax is as follow:

<project name="myProjectName" default="all">
 ...
</project>

Each project defines one or more targets. A target is a set of tasks you want to be executed. When starting Ant, you can select which target(s) you want to have executed. When no target is given, the project's default is used.

A target can depend on other targets. You might have a target for loading models and metamodels, for example, and a target for executing the transformation. You can only execute the transformation when you have loaded models first, so the transformation execution depends on the loading target. It is often advised to create multiple targets for better visibility in you Ant file.

A target has name and can depends on other tasks (referring by name to other tasks). The syntax is as follow:

<target name="loadModels">
 ...
</target>

<target name="transform" depends="loadModels">
 ...
</target>

A target can define tasks. A task is a piece of code that can be executed. A task can have multiple attributes (or arguments, if you prefer). The value of an attribute might contain references to a property. These references will be resolved before the task is executed.

Tasks have a common structure:

<name attribute1="value1" attribute2="value2" ... />

where name is the name of the task, attributeN is the attribute name, and valueN is the value for this attribute. Ant defines a set of built-in tasks (http://ant.apache.org/manual/coretasklist.html), along with a number of optional tasks (http://ant.apache.org/manual/optionaltasklist.html).

For more information on Ant itself, please consult its manual: http://ant.apache.org/manual/index.html.

Task am3.loadModel

Description

This task (implemented in class LoadModelTask) is used to load a model either by modlel handler facilities or with injectors. This model may be a terminal model or a metamodel. The metametamodels are typically not loaded with this task since they come bundled with a model handler. These metametamodels are available under the special name strings %EMF for the Ecore metametamodel and %MDR for NetBeans/MDR MOF 1.4 metametamodel. MOF special name is contextually the metametamodel  %EMF or %MDR depending on the model handler.

Parameters specified as attributes

The am3.loadModel can have the following parameters:

Attribute	Description	Required	Default value
name	The name of the model in the Ant project.	Yes	None
metamodel	The name of the metamodel. This name must be equal to a previous model name loaded by am3.loadModel or to metametamodel special name %EMF or %MDR. If this name equals MOF, the modelHandler specific metametamodel is taken.	Yes	None
path	The path to the file of the model to load. It can be relative to the current directory (the one containing the Ant file). If absolute, the ‘/’ root directory is the current workspace.	Yes (only one of path and nsUri)	None
nsUri	The namespace URI of a metamodel to load from the EMF package registry.		None
modelHandler	The model handler name to use for loading the model (EMF or MDR).	No	EMF

Parameters specified as nested elements

Loading of a metamodel with EMF (and Ecore as metametamodel):

<am3.loadModel modelHandler="EMF" name="News" metamodel="MOF" path="metamodel/News.ecore" />

Equivalent to

<am3.loadModel modelHandler="EMF" name="News" metamodel="%EMF" path="metamodels/News.ecore" />

Loading of a terminal model conforming to the previously loaded metamodel:

<am3.loadModel modelHandler="EMF" name="SampleNews" metamodel="News" path="models/MyInput-News.xmi" />

By default, am3.loadModel is able to load file that the modelHandler can read. Sometimes, it is interesting to be able to load a model through an injector, for instance with the XML injector or reading a .km3 file and having its model conforming to KM3. This is possible with AM3 by using the nested parameter injector. For instance, if you want to inject an XML file to an XML model:

<am3.loadModel modelHandler="EMF" name="XML" metamodel="MOF" path="metamodels/XML.ecore" />

<am3.loadModel name="myXML" metamodel="XML" path="inputs/MySample.xml">
 <injector name="xml" />
</am3.loadModel>

Examples

<am3.loadModel modelHandler="EMF" name="News" metamodel="MOF" path="/org.eclipse.am3.zoos.atlantic/News.ecore" />

<am3.loadModel modelHandler="EMF" name="IN" metamodel="KM3" path="/org.eclipse.am3.zoos.atlantic/Amble.km3">
 <injector name="ebnf">
  <param name="name" value="KM3" />
 </injector>
</am3.loadModel>

<am3.loadModel name="myXML" metamodel="XML" path="/test/testQuery.xml">
 <injector name="xml" />
</am3.loadModel>

Task am3.saveModel

Description

This task (implemented in class SaveModelTask) is used to save a model using model handler facilities or with extractors. It is possible to save any model: terminal models, metamodels or metametamodels.

The am3.saveModel can have the following parameters:

Attribute	Description	Required	Default value
model	The name of the model in the Ant project.	Yes	None
path	The path to the file of the model to save. It can be relative to the current directory (the one containing the Ant file). If absolute, the ‘/’ root directory is the current workspace.	Yes	None

Saving of the previously loaded News metamodel:

<am3.saveModel model="News" path="outputs/NewsMM.ecore" />

You can see that the model attribute is the same as the name attribute of the previous am3.loadModel tasks. Once they are loaded, models are identified by this attribute name. Thus, you should avoid giving the same name for two different models. Each time it occurs, your previous model is overwritten.

By default, am3.saveModel is able to save model with modelHandler facilities (this model handler have been provided in the load model task). Sometimes, it is interesting to save a model with an extractor. For instance, if you have a model conforming to KM3, it can be interesting to use the KM3 extractor to save it as a .km3 file. Another example, if you have a model conforming to XML, you may want to get an XML document rather than the XML model. This can be done by specifying an extractor nested parameter. For instance, to extract a model conforming to the XML metamodel (in this case, the previously loaded XML model with XML injector):

<am3.saveModel model="myXML" path="outputs/SavingMySample.xml">
 <extractor name="xml"/>
</am3.saveModel>

Alternately, you can use a query to save your model. It is usefull if you have multiple models as inputs (using a model to store parameters for instance). See am3.query ...

Examples

<am3.saveModel model="myXML" path="/test/opop.xml">
 <extractor name="xml" />
</am3.saveModel>

<am3.saveModel model="news_model" path="/test/news.ecore" />

<am3.saveModel model="IN" path="/test/MyKM3.km3">
 <extractor name="ebnf">
  <param name="format" value="KM3.tcs"/>
  <param name="indentString" value=" "/>
  <param name="serializeComments" value="false"/>
 </extractor>
</am3.saveModel>

Example using an ATL extractor, executing query to generate a text file (from the build folder of the Atlantic Raster Zoo):

<am3.saveModel model="target" path="${targetModel}">
 <extractor name="atl">
  <param name="queryPath" value="${targetPath}build/DOT2Text.atl"/>
 </extractor>
</am3.saveModel>

Task am3.atl

Description

The purpose of this task (implemented in class ATLModelTransformationTask) is to execute an ATL transformation. The models used by a transformation are referenced by their name as defined at with the AM3_Ant_Tasks#am3.loadModel am3.loadModel task (name attribute).

There is an exception for metametamodels, which are typically already available from the model handler. A metametamodel is referenced by a string composed of a percent character (i.e. '%') followed by the name of the model handler. For instance: '%EMF' refers to Ecore and '%MDR' refers to MOF 1.4.

Parameters specified as attributes

Attribute	Description	Required
path	Path of ATL transformation to run	Yes
allowInterModelReferences	Boolean value that determines whether or not references between different EMF models are possible	No

Within this task, you have to bind every model from the header of your ATL module. There is three kinds of nested parameters: inModel, outModel and library. The inModel kind is for source models; outModel for target models and library for helpers library.

For instance, if you have this module header:

module Families2Persons;
create OUT : Persons from IN : Families;
uses myLib;

You have to create three inModel parameters (for IN, Families and Persons), one outModel (for OUT) and one library (for myLib). For instance, completing the previous sample of am3.atl task:

<am3.atl path="ATLFiles/MyTransformation.atl">
 <inmodel name="Families" model="..."/>
 <inmodel name="IN" model="..."/>			
 <inmodel name="Persons" model="..."/>
 <outmodel name="OUT" model="..." metamodel="Persons"/>
 <library name="strings" path="lib/mylib.atl" />
</am3.atl>

Each parameter has a name that MUST be exactly the same as in the module header (case sensitive). For inModel parameters, model attribute refers to a name of a previously loaded model with am3.loadModel for instance. The attribute model of outModel do NOT refer a loaded model as it has not been yet created. The value of this attribute should be used latter as an identifier for the am3.saveModel task.

Every attributes for each nested parameters are summed here:

Parameters specified as nested elements

inModel

Attribute	Description	Required
name	The name of the model in ATL module header.	Yes
model	The name of a model previously loaded.	Yes

outModel

Attribute	Description	Required
name	The name of the model in ATL module header.	Yes
model	The name of a model previously loaded.	Yes
metamodel	The name of the metamodel of the current model as it has been specified when loading	Yes
path	Name of the output file (mainly needed for filename extension and EMF uses this to determine the correct factory).	No

library

Attribute	Description	Required
name	The name of the library in ATL module header.	Yes
path	The path to the ATL library file.	Yes

option

Attribute	Description	Required
name	The option name.	Yes
value	The value of the option of which the name is specified in the name attribute.	Yes

Options are passed to the ATL Virtual Machine. Available options are defined in the AtlLauncherTools class. Field additionalParamIds contains the option names. Field additionalParamLabels contains the option labels that is used in the Advanced panel of the ATL launch configuration.

Making ATL transformations chains without intermediate serialization

Suppose you have two transformations A2B and B2C to chain. A2B transforms a model conforming to A to a model conforming to B. B2C transforms a model conforming to B to a model conforming to C. We want to only serialized the model conforming to C but no the intermediate model conforming to B. The solution is that it can be passed directly as an input to the B2C transformation like this:

Loading metamodels:

<am3.loadModel metamodel="%EMF" name="A" path="..."/> 
<am3.loadModel metamodel="%EMF" name="B" path="..."/>
<am3.loadModel metamodel="%EMF" name="C" path="..."/>

Loading source model:

<am3.loadModel metamodel="A" name="myModel-A" path="..."/> <!-- "-A" is  here not to forget that myModel is conforming to metamodel "A", but you can give any name -->

First transformation:

<am3.atl path="...">
 <!--
 the header of the executed transformation is:
 module myModule1;
 create TargetM : TargetMM from SourceM : SourceMM;
 -->
 <inmodel name="SourceMM" model="A"/>
 <inmodel name="SourceM" model="myModel-A"/>			
 <inmodel name="TargetMM" model="B"/>
 <outmodel name="TargetM" model="myModel-B" metamodel="B"/>
</am3.atl>

Second transformation:

<am3.atl path="...">
 <!--
 the header of the executed transformation is:
 module myModule2;
 create TargetM : TargetMM from SourceM : SourceMM;
 -->
 <inmodel name="SourceMM" model="B"/>
 <inmodel name="SourceM" model="myModel-B"/>			
 <inmodel name="TargetMM" model="C"/>
 <outmodel name="TargetM" model="myModel-C" metamodel="C"/>
</am3.atl>

Note that myModel-B is available to the second transformation as if it has been loaded by an am3.loadModel call.

Serializing the output of the second transformation only (model myModel-C)

<am3.saveModel model="myModel-C" path="..." />

Examples

<am3.atl path="/AMMA-Tools/TCS2Problem.atl">
 <inModel name="IN" model="metamodel.tcs"/>
 <inModel name="TCS" model="TCS"/>
 <inModel name="MM" model="metamodel.km3"/>
 <inModel name="KM3" model="KM3"/>
 <inModel name="Problem" model="Problem"/>
 <library name="KM3Helpers" path="/AMMA-Tools/KM3Helpers.asm" />
 <library name="strings" path="/AMMA-Tools/strings.asm" />
 <outModel name="OUT" model="metamodel.pbs" metamodel="Problem"/>
</am3.atl>

<am3.atl path="UML2UML" allowintermodelreferences="true">
 <inModel name="UML2" model="UML2"/>
 <inModel name="IN" model="IN-UML"/>
 <outModel name="OUT" model="OUT-UML" metamodel="UML2" path="xxx.uml" />
</am3.atl>

Task am3.query

Description

This task (implemented in class QueryTask) is used to execute an OCL query on a model (or a metamodel) previously loaded or created by a model transformation. The property in parameter is setted with the query result.

Parameters specified as attributes

The am3.query can have the following parameters:

Attribute	Description	Required	Default value
body	The OCL query to execute.	Yes	None
property	The name of a property to set the result of the query.	Yes	None

Parameters specified as nested elements

inModel

Attribute	Description	Required
name	The name of the model in the ATL Query.	Yes
model	The name of a model previously loaded.	Yes

library

Attribute	Description	Required
name	The name of the library in the ATL query.	Yes
path	The path to the ATL library file.	Yes

Examples

<am3.query body="Problem!Problem.allInstances()->select(e | e.severity = #error)->size() > 0" property="thereAreErrors">
 <inModel name="Problem" model="Problem"/>
 <inModel name="IN" model="${metamodel}.pbs"/>
</am3.query>

<echo message="${thereAreErrors}"/>
<fail message="There are errors in ${metamodel}.tcs" if="thereAreErrors"/>

To save a model using an ATL query, when you have multiple models as input, you should store your helpers in a library, write the query in the body and store the result in an intermediate property. Then, write this property to a file using echo.

<am3.query body="GAO!GAO.allInstances()->iterate(e; acc : String =  | acc + e.toString()) + 
                 CPAR!CPAR.allInstances()->iterate(e; acc : String =  | acc + e.toString())" property="mset">
	<inModel name="IN1" model="gao"/>
	<inModel name="IN2" model="cpar"/> 
	<inModel name="GAO" model="GAO"/>
	<inModel name="CPAR" model="CPAR"/>
	<library name="GAO2MSET" path="/GAO/GAO2MSET/GAO2MSET.asm"/>
</am3.query>

<echo message="${mset}" file="test.mset"/>

Launching an Ant file with AM3 tasks in an Eclipse workbench

Once you have defined your Ant file, right click on the file:

• Select Run As > Ant Build…

• Go to the JRE tab

• Select "Run in the same JRE as the workspace"