Jump to: navigation, search

Difference between revisions of "ATL/Howtos"

< ATL
(Using other tools)
m (corrected a wiki link)
 
(11 intermediate revisions by 2 users not shown)
Line 1: Line 1:
This page contains a list of common questions related to the [[ATL]] usage.
+
This page contains a list of common questions related to the use of [[ATL]].
 
It gives hints towards solutions as well as links to some concrete examples.
 
It gives hints towards solutions as well as links to some concrete examples.
  
Line 9: Line 9:
  
 
The ATL development environment provides several base ways of launching transformations:
 
The ATL development environment provides several base ways of launching transformations:
* by specifying a [http://wiki.eclipse.org/ATL/User_Guide_-_The_ATL_Tools#Setting_up_an_ATL_run_launch_configuration launch configuration],
+
* by specifying a [[ATL/User_Guide - The ATL Tools#Setting up an ATL run launch configuration|launch configuration]],
* by writing an ant script using the [http://wiki.eclipse.org/ATL/User_Guide_-_The_ATL_Tools#ATL_ant_tasks ATL-specific ANT tasks].
+
* by writing an ant script using the [[ATL/User Guide - The ATL Tools#ATL ant tasks|ATL-specific ANT tasks]].
  
 
=== ATL API & Services ===
 
=== ATL API & Services ===
Line 16: Line 16:
 
However, notably for integration purposes in Eclipse solutions, it is necessary to launch transformations by mean of Java code.
 
However, notably for integration purposes in Eclipse solutions, it is necessary to launch transformations by mean of Java code.
  
This is why ATL directly provides in addition a [http://wiki.eclipse.org/ATL/Developer_Guide#Core_API dedicated API and core services] enabling to run ATL transformations programmatically, including the loading (injection) and saving (extraction) of corresponding required metamodels and models.
+
This is why ATL directly provides in addition a [[ATL/Developer Guide#Core API|dedicated API and core services]] enabling to run ATL transformations programmatically, including the loading (injection) and saving (extraction) of corresponding required metamodels and models.
  
 
==How do I generate text from models?==
 
==How do I generate text from models?==
Line 26: Line 26:
  
 
You can specify a query over your model in ATL.
 
You can specify a query over your model in ATL.
An example of this is available in the [http://www.eclipse.org/gmt/atl/atlTransformations/#UML2Java UML-to-JavaCode] transformation.
+
An example of this is available in the [http://www.eclipse.org/atl/atlTransformations/#UML2Java UML-to-JavaCode] transformation.
  
 
The [http://www.emn.fr/z-info/atlanmod/index.php/Raster atlanticRaster zoo] is also using this technique.
 
The [http://www.emn.fr/z-info/atlanmod/index.php/Raster atlanticRaster zoo] is also using this technique.
 
It first transforms KM3 metamodels into DOT models with a KM32DOT.atl transformation. It then uses DOT2Text.atl to query a string, corresponding to the generated DOT code, from the DOT model.
 
It first transforms KM3 metamodels into DOT models with a KM32DOT.atl transformation. It then uses DOT2Text.atl to query a string, corresponding to the generated DOT code, from the DOT model.
These two ATL transformation/query can be found from [http://www.eclipse.org/m2m/atl/atlTransformations/#KM32DOT here].
+
These two ATL transformation/query can be found from [http://www.eclipse.org/atl/atlTransformations/#KM32DOT here].
  
Then, an ANT script makes use of the [http://wiki.eclipse.org/ATL/User_Guide_-_The_ATL_Tools#Task_atl.saveModel atl.saveModel] task with an ATL extractor pointing to the DOT2Text.atl transformation.
+
Then, an ANT script makes use of the [[ATL/User Guide - The ATL Tools#Task atl.saveModel|atl.saveModel]] task with an ATL extractor pointing to the DOT2Text.atl transformation.
  
 
===Using other tools===
 
===Using other tools===
  
The [http://www.eclipse.org/Xtext/ Xtext] framework is dedicated to this kind of tasks.
+
The [http://www.eclipse.org/Xtext/ Xtext] framework in Eclipse Modeling is dedicated to this kind of tasks.
  
 
[[TCS]] (Textual Concrete Syntax) is also a tool enabling the specification of textual syntaxes for metamodels.
 
[[TCS]] (Textual Concrete Syntax) is also a tool enabling the specification of textual syntaxes for metamodels.
Line 80: Line 80:
 
helper def : sourceValue  : String = thisModule.getParameter('source');
 
helper def : sourceValue  : String = thisModule.getParameter('source');
 
</pre>
 
</pre>
 +
 +
==How can I handle arbitrary XML documents?==
 +
 +
Arbitrary XML documents can be used as source or target of ATL transformations.
 +
However, this cannot be done directly (see [[ATL_Howtos#How can I tune the XML output of ATL?|next section]]) but rather through specific injectors and extractors.
 +
 +
Injecting XML files as XML models or extracting XML models as XML files can be performed thanks to the the [https://dev.eclipse.org/svnroot/modeling/org.eclipse.mdt.modisco/incubation/trunk/am3/plugins/trunk/org.eclipse.m2m.atl.projectors.xml/ org.eclipse.m2m.atl.projectors.xml] plugin and [[ATL/User Guide - The ATL Tools#ATL ant tasks|ATL-specific ANT tasks]].
 +
 +
A version of this plugin built for the Juno ATL version can be downloaded from [http://docatlanmod.emn.fr/ATL/Plugins/org.eclipse.m2m.atl.projectors.xml_0.4.0.jar here] and has to be copied to the ''dropins'' folder of your Eclipse install before starting.
 +
For other ATL versions, the plugin sources first have to be checked out into your workspace in order to re-export the plugin as a compatible deployable one (to be then copied to the ''dropins'' folder similarly as mentioned before).
  
 
==How can I tune the XML output of ATL?==
 
==How can I tune the XML output of ATL?==
Line 89: Line 99:
 
To do this, the target model is first transformed into a model conforming to a [https://dev.eclipse.org/svnroot/modeling/org.eclipse.mdt.modisco/incubation/trunk/am3/plugins/trunk/org.eclipse.m2m.atl.projectors.xml/model/ specific XML metamodel].
 
To do this, the target model is first transformed into a model conforming to a [https://dev.eclipse.org/svnroot/modeling/org.eclipse.mdt.modisco/incubation/trunk/am3/plugins/trunk/org.eclipse.m2m.atl.projectors.xml/model/ specific XML metamodel].
 
The resulting XML model can then be extracted into an XML document.
 
The resulting XML model can then be extracted into an XML document.
An example can be found in the [http://www.eclipse.org/gmt/atl/atlTransformations/#Table2SVGPieChart Table2SVGPieChart] transformation scenario: the target SVG model is transformed into an XML model that can then be extracted (see documentation of scenario for more details and README.txt in zip file for directions).
+
An example can be found in the [http://www.eclipse.org/atl/atlTransformations/#Table2SVGPieChart Table2SVGPieChart] transformation scenario: the target SVG model is transformed into an XML model that can then be extracted (see documentation of scenario for more details and README.txt in zip file for directions).
The process of transforming a model to XML then extracting it can be automated using [http://wiki.eclipse.org/ATL/User_Guide_-_The_ATL_Tools#ATL_ant_tasks ATL-specific ANT tasks] and the [https://dev.eclipse.org/svnroot/modeling/org.eclipse.mdt.modisco/incubation/trunk/am3/plugins/trunk/org.eclipse.m2m.atl.projectors.xml/ org.eclipse.m2m.atl.projectors.xml] plugin.
+
The process of transforming a model to XML then extracting it can be automated using [[ATL/User Guide - The ATL Tools#ATL ant tasks|ATL-specific ANT tasks]] and the ''org.eclipse.m2m.atl.projectors.xml'' plugin (see [[ATL/Howtos#How can I handle arbitrary XML documents?|previous section]]).
 
+
==How can I handle arbitrary XML documents?==
+
 
+
Arbitrary XML documents can be used as source or target of ATL transformations.
+
However, this cannot be done directly (see [[ATL_Howtos#How_can_I_tune_the_XML_output_of_ATL.3F|previous section]]) but rather through specific injectors and extractors.
+
 
+
Injecting XML files as XML models or extracting XML models as XML files can be performed thanks to the the [https://dev.eclipse.org/svnroot/modeling/org.eclipse.mdt.modisco/incubation/trunk/am3/plugins/trunk/org.eclipse.m2m.atl.projectors.xml/ org.eclipse.m2m.atl.projectors.xml] plugin and [http://wiki.eclipse.org/ATL/User_Guide_-_The_ATL_Tools#ATL_ant_tasks ATL-specific ANT tasks].
+
  
 
==How can I implement my own injector or extractor?==
 
==How can I implement my own injector or extractor?==
Line 104: Line 107:
 
An injector/extractor is a component implementing an injection/extraction.
 
An injector/extractor is a component implementing an injection/extraction.
  
Injectors and extractors may be then used programmatically or via ATL-specific ANT tasks [http://wiki.eclipse.org/ATL/User_Guide_-_The_ATL_Tools#Task_atl.loadModel atl.loadModel] and [http://wiki.eclipse.org/ATL/User_Guide_-_The_ATL_Tools#Task_atl.saveModel atl.saveModel].
+
Injectors and extractors may be then used programmatically or via ATL-specific ANT tasks [[ATL/User Guide - The ATL Tools#Task atl.loadModel|atl.loadModel]] and [[ATL/User Guide - The ATL Tools#Task atl.saveModel|atl.saveModel]].
  
To be usable in practice, an injector/extractor must implement the IInjector/IExtractor interface (cf. [http://wiki.eclipse.org/ATL/Developer_Guide#Core_API ATL Core API documentation]), as shown by the [https://dev.eclipse.org/svnroot/modeling/org.eclipse.mdt.modisco/incubation/trunk/am3/plugins/trunk/org.eclipse.m2m.atl.projectors.xml/src/org/eclipse/m2m/atl/projectors/xml/ XML injector/extractor example] for instance.
+
To be usable in practice, an injector/extractor must implement the IInjector/IExtractor interface (cf. [[ATL/Developer Guide#Core API|ATL Core API documentation]]), as shown by the [https://dev.eclipse.org/svnroot/modeling/org.eclipse.mdt.modisco/incubation/trunk/am3/plugins/trunk/org.eclipse.m2m.atl.projectors.xml/src/org/eclipse/m2m/atl/projectors/xml/ XML injector/extractor example] for instance.
 
It must also declare explicitly the use of the specific org.eclipse.m2m.atl.core.injector/extractor extension points, as shown by the [https://dev.eclipse.org/svnroot/modeling/org.eclipse.mdt.modisco/incubation/trunk/am3/plugins/trunk/org.eclipse.m2m.atl.projectors.xml/plugin.xml same example than before].
 
It must also declare explicitly the use of the specific org.eclipse.m2m.atl.core.injector/extractor extension points, as shown by the [https://dev.eclipse.org/svnroot/modeling/org.eclipse.mdt.modisco/incubation/trunk/am3/plugins/trunk/org.eclipse.m2m.atl.projectors.xml/plugin.xml same example than before].
  
Line 112: Line 115:
  
 
There are several implementations of UML.
 
There are several implementations of UML.
The one we consider here is the de-facto standard implementation from Eclipse: [http://wiki.eclipse.org/UML2 the UML2 project].
+
The one we consider here is the de-facto standard implementation from Eclipse: [[MDT-UML2|the UML2 project]].
  
 
ATL allows to transform such UML models as any other EMF models.
 
ATL allows to transform such UML models as any other EMF models.
  
 
The UML2 metamodel must be loaded from the EMF registry (i.e., by namespace URI).
 
The UML2 metamodel must be loaded from the EMF registry (i.e., by namespace URI).
This can be done using the "EMF Registry..." button of the ATL launch configuration, or using the nsURI attribute of the [http://wiki.eclipse.org/ATL/User_Guide_-_The_ATL_Tools#Task_atl.loadModel atl.loadModel] task.
+
This can be done using the "EMF Registry..." button of the ATL launch configuration, or using the nsURI attribute of the [[ATL/User Guide - The ATL Tools#Task atl.loadModel|atl.loadModel]] task.
  
Usage of [[ATL_Editor_content_assist|content assist]] (i.e., code completion) is especially useful with big metamodels like UML2.
+
Usage of [[ATL/User Guide - The ATL Tools#Content assist|content assist]] (i.e., code completion) is especially useful with big metamodels like UML2.
  
 
==How can I retrieve tagged values from stereotyped UML model elements?==
 
==How can I retrieve tagged values from stereotyped UML model elements?==
Line 152: Line 155:
 
These operations can then be called like helpers.
 
These operations can then be called like helpers.
  
The [http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.gmt/ATL/org.eclipse.gmt.atl.oclquery.core/ org.eclipse.gmt.atl.oclquery.core] plugin offers the [http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.gmt/ATL/org.eclipse.gmt.atl.oclquery.core/src/org/eclipse/gmt/atl/oclquery/core/ATLVMTools.java?rev=HEAD&only_with_tag=HEAD&content-type=text/vnd.viewcvs-markup org.eclipse.gmt.atl.oclquery.core.ATLVMTools] class to create instances of [http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.gmt/ATL/org.atl.engine.vm/src/org/atl/engine/vm/Operation.java?rev=HEAD&content-type=text/vnd.viewcvs-markup org.atl.engine.vm.Operation] and to register them in the ATL VM.
+
The {{ATLRepositoryLink|deprecated/org.eclipse.gmt.atl.oclquery.core/|org.eclipse.gmt.atl.oclquery.core}} plugin offers the {{ATLRepositoryLink|deprecated/org.eclipse.gmt.atl.oclquery.core/src/org/eclipse/gmt/atl/oclquery/core/ATLVMTools.java|org.eclipse.gmt.atl.oclquery.core.ATLVMTools}} class to create instances of {{ATLRepositoryLink|deprecated/org.atl.engine.vm/src/org/atl/engine/vm/Operation.java|org.atl.engine.vm.Operation}} and to register them in the ATL VM.
  
This is used in [http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.gmt/ATL/org.eclipse.gmt.atl.oclquery.core/src/org/eclipse/gmt/atl/oclquery/core/OclEvaluator.java?rev=HEAD&content-type=text/vnd.viewcvs-markup org.eclipse.gmt.atl.oclquery.core.OclEvaluator] to redefine the dumpASM method of ASMEmitter.
+
This is used in {{ATLRepositoryLink|deprecated/org.eclipse.gmt.atl.oclquery.core/src/org/eclipse/gmt/atl/oclquery/core/OclEvaluator.java|org.eclipse.gmt.atl.oclquery.core.OclEvaluator}} to redefine the dumpASM method of ASMEmitter.
 
The process to register operations on OCL primitive types (e.g. Boolean, Integer, String) is similar.
 
The process to register operations on OCL primitive types (e.g. Boolean, Integer, String) is similar.
  
 
[[Category:ATL]]
 
[[Category:ATL]]

Latest revision as of 07:38, 4 June 2013

This page contains a list of common questions related to the use of ATL. It gives hints towards solutions as well as links to some concrete examples.

How do I launch transformations programmatically?

ATL-specific launch configurations and ANT tasks

The ATL development environment provides several base ways of launching transformations:

ATL API & Services

However, notably for integration purposes in Eclipse solutions, it is necessary to launch transformations by mean of Java code.

This is why ATL directly provides in addition a dedicated API and core services enabling to run ATL transformations programmatically, including the loading (injection) and saving (extraction) of corresponding required metamodels and models.

How do I generate text from models?

There are several possibilies. We only detail some of them here.

Using ATL

You can specify a query over your model in ATL. An example of this is available in the UML-to-JavaCode transformation.

The atlanticRaster zoo is also using this technique. It first transforms KM3 metamodels into DOT models with a KM32DOT.atl transformation. It then uses DOT2Text.atl to query a string, corresponding to the generated DOT code, from the DOT model. These two ATL transformation/query can be found from here.

Then, an ANT script makes use of the atl.saveModel task with an ATL extractor pointing to the DOT2Text.atl transformation.

Using other tools

The Xtext framework in Eclipse Modeling is dedicated to this kind of tasks.

TCS (Textual Concrete Syntax) is also a tool enabling the specification of textual syntaxes for metamodels.

How do I declare/use external parameters in ATL transformations?

Using an XML file

A solution is to save transformation parameters in a extern XML model. In the transformation, you will use an helper to get parameters from your model.

To inject and/or extract XML models (and to get the simple XML metamodel in Ecore), you can check out and install the org.eclipse.m2m.atl.projectors.xml plugin with your ATL Eclipse install.

The following code is a simple parameters XML file:

<parameters>
	<param name="param1" value="valueX"/>
	<param name="param2" value="valueY"/>
</parameters>

In the transformation header, you add the parameters model and its XML metamodel:

module AMW2ATL;
create OUT : XXX from IN : YYY, parameters : XML;

From parameters model, the following helper is used to get value attribute select in the param entities according to the given name:

helper def : getParameter(name : String) : String =
	XML!Element.allInstancesFrom('parameters')->select(e |
		e.name = 'param'
	)->select(e |
		e.getAttrVal('name') = name
	)->first().getAttrVal('value');

To use the previous helper (due to the getAttrVal call), you need to use XMLHelpers.asm ATL Library and add in the transformation:

uses XMLHelpers;

The following code is a simple example to show how to use the getParameter helper:

helper def : sourceValue  : String = thisModule.getParameter('source');

How can I handle arbitrary XML documents?

Arbitrary XML documents can be used as source or target of ATL transformations. However, this cannot be done directly (see next section) but rather through specific injectors and extractors.

Injecting XML files as XML models or extracting XML models as XML files can be performed thanks to the the org.eclipse.m2m.atl.projectors.xml plugin and ATL-specific ANT tasks.

A version of this plugin built for the Juno ATL version can be downloaded from here and has to be copied to the dropins folder of your Eclipse install before starting. For other ATL versions, the plugin sources first have to be checked out into your workspace in order to re-export the plugin as a compatible deployable one (to be then copied to the dropins folder similarly as mentioned before).

How can I tune the XML output of ATL?

The ATL Virtual Machine can write target models to XML files in two different ways:

  • XMI writing is delegated to EMF.
  • Target models can be extracted into XML files using custom XML Schemas.

To do this, the target model is first transformed into a model conforming to a specific XML metamodel. The resulting XML model can then be extracted into an XML document. An example can be found in the Table2SVGPieChart transformation scenario: the target SVG model is transformed into an XML model that can then be extracted (see documentation of scenario for more details and README.txt in zip file for directions). The process of transforming a model to XML then extracting it can be automated using ATL-specific ANT tasks and the org.eclipse.m2m.atl.projectors.xml plugin (see previous section).

How can I implement my own injector or extractor?

An injection/extraction is a transformation from/to another Technical Space (e.g., XML, Grammarware) to/from the Model Engineering Technical Space. An injector/extractor is a component implementing an injection/extraction.

Injectors and extractors may be then used programmatically or via ATL-specific ANT tasks atl.loadModel and atl.saveModel.

To be usable in practice, an injector/extractor must implement the IInjector/IExtractor interface (cf. ATL Core API documentation), as shown by the XML injector/extractor example for instance. It must also declare explicitly the use of the specific org.eclipse.m2m.atl.core.injector/extractor extension points, as shown by the same example than before.

How can I transform UML models?

There are several implementations of UML. The one we consider here is the de-facto standard implementation from Eclipse: the UML2 project.

ATL allows to transform such UML models as any other EMF models.

The UML2 metamodel must be loaded from the EMF registry (i.e., by namespace URI). This can be done using the "EMF Registry..." button of the ATL launch configuration, or using the nsURI attribute of the atl.loadModel task.

Usage of content assist (i.e., code completion) is especially useful with big metamodels like UML2.

How can I retrieve tagged values from stereotyped UML model elements?

In ATL, a profiled UML model used as source model is viewed like any other UML model. You generally (i.e., when the profile is referenced with a valid relative path) do not have to specify the profile used with the model. So, in the header of the ATL module you just have:

module uml2something;
create OUT : targetMetamodel from IN : UML;

If atl seems to ignore your stereotypes, you can add your profile as source model. You obtain the following header:

module uml2something;
create OUT : targetMetamodel from IN : UML, INPROFILE : profile;

After that you can use operations like:

  • getAppliedStereotype(sterotypeName : String) on a UML element to get the stereotype with the name "stereotypeName" applied on this element. This operation needs the fully qualifed name of the stereotype so it looks like: profileName::sterotypeName.
  • getValue(stereotype : Stereotype, propertyName : String) to get the Value of the tagged value with name "propertyName" on the stereotype "stereotype" (the sterotype can be retrieved by getAppliedStereotype).

A helper like:

helper context UML!Element def: hasStereotype(name : String) : Boolean =
	not self.getAppliedStereotype(name).oclIsUndefined();

can also be useful to check if a stereotype is applied on the UML element before trying to retrieve it or to get a tagged value from it. As it uses getAppliedStereotype, it needs the fully qualified name of the stereotype (e.g., profileName::sterotypeName).

How can I specify a Virtual Machine operation in Java? (Deprecated)

It is possible to add new Java operations to the ATL Virtual Machine (VM). These operations can then be called like helpers.

The org.eclipse.gmt.atl.oclquery.core plugin offers the org.eclipse.gmt.atl.oclquery.core.ATLVMTools class to create instances of org.atl.engine.vm.Operation and to register them in the ATL VM.

This is used in org.eclipse.gmt.atl.oclquery.core.OclEvaluator to redefine the dumpASM method of ASMEmitter. The process to register operations on OCL primitive types (e.g. Boolean, Integer, String) is similar.