Difference between revisions of "ATL/Howtos"

From Eclipsepedia

< ATL
Jump to: navigation, search
(Examples)
(How can I handle arbitrary XML documents?)
(44 intermediate revisions by 8 users not shown)
Line 1: Line 1:
{{Backlink|ATL}}
+
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.
This page contains a list of problems related to [[ATL]] usage.
+
It gives hints towards solutions and links to examples.
+
  
 
__TOC__
 
__TOC__
 
==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 [http://www.eclipse.org/gmt/atl/atlTransformations/#UML2Java UML2Java] transformation.
 
 
The [http://www.eclipse.org/gmt/am3/zoos/atlanticRasterZoo/ atlanticRaster zoo] is also using this technique.
 
It first transforms KM3 metamodels into DOT models with the [http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.gmt/AM3/org.eclipse.am3.zoos.atlanticRaster/build/KM32DOT.atl?rev=HEAD&content-type=text/vnd.viewcvs-markup KM32DOT.atl] transformation.
 
It then uses [http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.gmt/AM3/org.eclipse.am3.zoos.atlanticRaster/build/DOT2Text.atl?rev=HEAD&content-type=text/vnd.viewcvs-markup DOT2Text.atl] to query a String from the DOT model.
 
This string corresponds to the generated DOT code.
 
Then, the [http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.gmt/AM3/org.eclipse.am3.zoos.atlanticRaster/build/build.xml?rev=HEAD&content-type=text/vnd.viewcvs-markup build.xml] ant scripts makes use of the [[AM3_Ant_Tasks#am3.saveModel|am3.saveModel]] task with an ATL extractor pointing to the [http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.gmt/AM3/org.eclipse.am3.zoos.atlanticRaster/build/DOT2Text.atl?rev=HEAD&content-type=text/vnd.viewcvs-markup DOT2Text.atl] transformation.
 
 
===Using TCS===
 
 
[[TCS]] (Textual Concrete Syntax) is a tool enabling the specification of textual syntaxes for metamodels.
 
Once such a syntax has been specified, models can be serialized to text files.
 
 
One advantage of TCS is that text can also be parsed into models.
 
It is therefore possible to use the same specification to enable the definition of models with any text editor.
 
  
 
==How do I launch transformations programmatically?==
 
==How do I launch transformations programmatically?==
  
===Description===
+
=== ATL-specific launch configurations and ANT tasks ===
  
The ATL development environment (ATL Development Tools, or ADT) provides several means to launch transformations:
+
The ATL development environment provides several base ways of launching transformations:
* by specifying a launch configuration,
+
* by specifying a [http://wiki.eclipse.org/ATL/User_Guide_-_The_ATL_Tools#Setting_up_an_ATL_run_launch_configuration launch configuration],
* by writing an ant script using the [[AM3 Ant Tasks]].
+
* by writing an ant script using the [http://wiki.eclipse.org/ATL/User_Guide_-_The_ATL_Tools#ATL_ant_tasks ATL-specific ANT tasks].
  
However, in some cases, it is necessary to launch an ATL transformation programmatically (e.g., from Java code).
+
=== ATL API & Services ===
  
===Solution===
+
However, notably for integration purposes in Eclipse solutions, it is necessary to launch transformations by mean of Java code.
  
The [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.m2m/org.eclipse.m2m.atl/plugins/org.eclipse.m2m.atl.engine/src/org/eclipse/m2m/atl/engine/AtlLauncher.java?root=Modeling_Project&view=markup AtlLauncher] class can be used for this purpose. Complete [http://milan.milanovic.org/download/atl.zip Milan Milanovic's ATL template bundle] is basic solution for integration of ATL engine and for transformation execution in Java applications.
+
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.
  
Remark 1: the [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.m2m/org.eclipse.m2m.atl/plugins/org.eclipse.m2m.atl.engine/src/org/eclipse/m2m/atl/engine/AtlCompiler.java?root=Modeling_Project&view=markup AtlCompiler] class may be used to compile ATL transformations into .asm files executable on the ATL Virtual Machine.
+
==How do I generate text from models?==
  
Remark 2: There may be problems when using MDR as model handler, as it shown in [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.gmt/AM3/org.eclipse.gmt.am3.dsls.km3/src/org/eclipse/gmt/am3/dsls/km3/KM3Projector.java?root=Technology_Project&view=markup  KM3Projector] class. Call to initMDR() method should be done only once when your class is constructed. This is because if you load your model in this way: getMDRModelHandler().loadModel("model.xmi", getSomeMetamodel(), mod.openStream()); method getSomeMetamodel() will return reference to metamodel which is initialized in initMDR(). If some of your methods later call initMDR() your initial metamodel reference will be lost and someMetamodel variable will get reference to new metamodel. Result of your transformation will be output model file, because input model has lost his metamodel reference.
+
There are several possibilies.
 +
We only detail some of them here.
  
===Libraries and Prequesites===
+
===Using ATL===
  
To to launch ATL transformations programmaticallly from Java, you will need some libraries. These libraries should be copied from eclipse/plugins folder to folder where libs are stored for Java application, and with they you have complete support for MDR and EMF. They should be also added to the classpath. Files in case are of Eclipse 3.3.x and emf 2.1.0 version. If you have other versions, just copy the same files with those versions.
+
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.
  
Here is a description of what is required for all kind of use :
+
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.
 +
These two ATL transformation/query can be found from [http://www.eclipse.org/m2m/atl/atlTransformations/#KM32DOT here].
  
====ATL====
+
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.
* ATL libraries
+
** antlr-runtime-3.0.jar, ATL-parser.jar, org.eclipse.gmt.tcs.extractor_1.0.0.jar, org.eclipse.gmt.tcs.injector_1.0.0.jar : those are located on the CVS, [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.m2m/org.eclipse.m2m.atl/plugins/org.eclipse.m2m.atl.engine/lib/?root=Modeling_Project here]
+
** emf4atl.jar, vm.jar, engine.jar : those are not exported at this time, so you must get the last ATL version on the CVS and then export these plugins into jar libraries (right-click on the project-> export->JAR file). The real plugin names are [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.m2m/org.eclipse.m2m.atl/plugins/org.eclipse.m2m.atl.drivers.emf4atl/?root=Modeling_Project org.eclipse.m2m.atl.drivers.emf4atl], [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.m2m/org.eclipse.m2m.atl/plugins/org.eclipse.m2m.atl.engine.vm/?root=Modeling_Project org.eclipse.m2m.atl.engine.vm] and [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.m2m/org.eclipse.m2m.atl/plugins/org.eclipse.m2m.atl.engine/?root=Modeling_Project org.eclipse.m2m.atl.engine].
+
* Eclipse libraries
+
** org.eclipse.equinox.common_3.3.*.jar
+
** org.eclipse.core.jobs_3.3.*.jar
+
** org.eclipse.core.runtime.compatibility_3.*.jar
+
** org.eclipse.core.runtime_3.3.*.jar
+
** org.eclipse.core.resources_3.3.*.jar
+
** org.eclipse.osgi_3.3.*.jar
+
* EMF libraries
+
** org.eclipse.emf.common_2.3.*.jar
+
** org.eclipse.emf.ecore.xmi_2.3.*.jar
+
** org.eclipse.emf.ecore_2.3.*.jar
+
  
====ATL - MDR use====
+
===Using other tools===
''The following libraries are only required for the use of MDR.''
+
* jmi.jar
+
* jmiutils.jar
+
* mdr4atl.jar
+
* mdrapi.jar
+
* mof.jar
+
* nbmdr.jar
+
* openide-util.jar
+
  
====ATL - KM3 use====
+
The [http://www.eclipse.org/Xtext/ Xtext] framework in Eclipse Modeling is dedicated to this kind of tasks.
''The following libraries are only required for the use of KM3.''
+
* org.eclipse.gmt.am3.dsls.km3.jar
+
  
===Examples===
+
[[TCS]] (Textual Concrete Syntax) is also a tool enabling the specification of textual syntaxes for metamodels.
  
A very simple working example, involving the invocation of an ATL transformation from a plug-in can be seen at [[JWT_Transformations#About_ATL JWT to BPMN and vice versa]], using regular .ecore metamodels.
+
==How do I declare/use external parameters in ATL transformations?==
  
The [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.gmt/AM3/org.eclipse.gmt.am3.dsls.km3/src/org/eclipse/gmt/am3/dsls/km3/KM3Projector.java?root=Technology_Project&view=markup KM3Projector] class of the [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.gmt/AM3/org.eclipse.gmt.am3.dsls.km3/src/org/eclipse/gmt/am3/dsls/km3/?root=Technology_Project KM3 plugin] contains example usages of the AtlLauncher class (e.g. the getEcoreFromKM3 method).
+
===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.
  
Another illustration is given in [http://ssel.vub.ac.be/viewvc/UML1CaseStudies/uml1cs-atlcommandline/ Dennis Wagelaar's ATL command line tool] (here is a [http://ssel.vub.ac.be/viewvc/UML1CaseStudies/uml1cs-atlcommandline/src/org/atl/commandline/Main.java direct link to the Java class]). This tool was discussed on the ATL mailing list (see the "Related threads" section below).
+
To inject and/or extract XML models (and to get the simple XML metamodel in Ecore), you can check out and install 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 with your ATL Eclipse install.
 
+
===Related threads===
+
 
+
Here is a list of discussion threads related to this issue that occured on the old ATL mailing list [http://tech.groups.yahoo.com/group/atl_discussion/ atl_discussion], or on the Eclipse M2M newsgroup:
+
* [http://www.sciences.univ-nantes.fr/lina/atl/www/atl_discussion_archive/#1924 Run ATL-Transformation from command line]
+
* [http://www.sciences.univ-nantes.fr/lina/atl/www/atl_discussion_archive/#1790 Running ATL transformations programmatically [with MDR&#93;!]
+
* [http://www.sciences.univ-nantes.fr/lina/atl/www/atl_discussion_archive/#182 Running from command line]
+
* Libraries and Prequesites to launch ATL transformations programmatically from Java: [http://dev.eclipse.org/newslists/news.eclipse.modeling.m2m/msg00774.html archive] (read-only), [http://www.eclipse.org/newsportal/article.php?id=779&group=eclipse.modeling.m2m#779 newsportal] (requires [http://www.eclipse.org/newsgroups/register.php password])
+
* [http://dev.eclipse.org/newslists/news.eclipse.modeling.m2m/msg00956.html ATL transformations on UML2 models - including profiles - outside Eclipse]
+
 
+
==How do I use extern 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. The wanted parameters model will be chosen in the transformation launch configuration or in the [[AM3 Ant Tasks]].
+
  
 
The following code is a simple parameters XML file:
 
The following code is a simple parameters XML file:
 
<pre>
 
<pre>
 
<parameters>
 
<parameters>
<param name="source" value="KM3"/>
+
<param name="param1" value="valueX"/>
<param name="target" value="ATL"/>
+
<param name="param2" value="valueY"/>
 
</parameters>
 
</parameters>
 
</pre>
 
</pre>
  
In the transformation header, you add the ''parameters'' model and its metamodel
+
In the transformation header, you add the ''parameters'' model and its [https://dev.eclipse.org/svnroot/modeling/org.eclipse.mdt.modisco/incubation/trunk/am3/plugins/trunk/org.eclipse.m2m.atl.projectors.xml/model/ XML metamodel]:
[http://dev.eclipse.org/viewcvs/indextech.cgi/~checkout~/org.eclipse.gmt/AM3/org.eclipse.am3.zoos.atlantic/XML.km3?rev=1.1&only_with_tag=HEAD&content-type=text/vnd.viewcvs-markup XML.km3] :
+
 
<pre>
 
<pre>
 
module AMW2ATL;
 
module AMW2ATL;
create OUT : ATL from source : MOF, target : MOF, parameters : XML;
+
create OUT : XXX from IN : YYY, parameters : XML;
 
</pre>
 
</pre>
  
Line 131: Line 71:
 
</pre>
 
</pre>
  
To used the previous helper (due to the ''getAttrVal'' call), you need to used [http://dev.eclipse.org/viewcvs/indextech.cgi/~checkout~/org.eclipse.gmt/AM3/org.eclipse.am3.zoos.atlanticRaster/build/XMLHelpers.asm?rev=1.1&content-type=text/vnd.viewcvs-markup XMLHelpers.asm] ATL Library and add in the transformation:
+
To use the previous helper (due to the ''getAttrVal'' call), you need to use [https://gforge.inria.fr/scm/viewvc.php/*checkout*/AtlanticRaster/build/XMLHelpers.asm?revision=6&root=atlantic-zoos XMLHelpers.asm] ATL Library and add in the transformation:
 
<pre>
 
<pre>
 
uses XMLHelpers;
 
uses XMLHelpers;
 
</pre>
 
</pre>
  
The following code, it is a simple example to show how to used ''getParameter'' helper:
+
The following code is a simple example to show how to use the ''getParameter'' helper:
 
<pre>
 
<pre>
 
helper def : sourceValue  : String = thisModule.getParameter('source');
 
helper def : sourceValue  : String = thisModule.getParameter('source');
 
</pre>
 
</pre>
  
In [[AM3 Ant Tasks]], you need to add the ''parameters'' model, the [http://dev.eclipse.org/viewcvs/indextech.cgi/~checkout~/org.eclipse.gmt/AM3/org.eclipse.am3.zoos.atlantic/XML.km3?rev=1.1&only_with_tag=HEAD&content-type=text/vnd.viewcvs-markup XML.km3] metamodel and the [http://dev.eclipse.org/viewcvs/indextech.cgi/~checkout~/org.eclipse.gmt/AM3/org.eclipse.am3.zoos.atlanticRaster/build/XMLHelpers.asm?rev=1.1&content-type=text/vnd.viewcvs-markup XMLHelpers.asm] library. For this you need parameters.xml model in ecore.
+
==How can I handle arbitrary XML documents?==
See the following example:
+
<pre>
+
<am3.loadModel modelHandler="EMF" name="KM3" metamodel="MOF" path="uri:http://www.eclipse.org/gmt/2005/KM3"/>
+
  
<am3.loadModel modelHandler="EMF" name="XML" metamodel="KM3" path="XML.km3">
+
Arbitrary XML documents can be used as source or target of ATL transformations.
<injector name="ebnf">
+
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.
<param name="name" value="KM3" />
+
</injector>
+
</am3.loadModel>
+
  
<am3.loadModel modelHandler="EMF" name="Parameters" metamodel="XML" path="Parameters.xml">
+
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].
<injector name="xml"/>
+
</am3.loadModel>
+
  
<am3.atl path="myTransformation.atl">
+
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.
<inModel name="source" model="left"/>
+
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).
<inModel name="target" model="right"/>
+
<inModel name="MOF" model="%EMF"/>
+
 
+
<inModel name="parameters" model="Parameters"/>
+
<inModel name="XML" model="XML"/>
+
<library name="XMLHelpers" path="XMLHelpers.asm"/>
+
 
+
<inModel name="ATL" model="ATL"/>
+
<outModel name="OUT" model="ATLmodel" metamodel="ATL"/>
+
</am3.atl>
+
 
+
<am3.saveModel model="ATLmodel" path="ATLmodel.ecore"/>
+
</pre>
+
 
+
Instead of [[AM3 Ant Tasks]], if you use ATL launch configuration then you need to inject
+
[http://dev.eclipse.org/viewcvs/indextech.cgi/~checkout~/org.eclipse.gmt/AM3/org.eclipse.am3.zoos.atlantic/XML.km3?rev=1.1&only_with_tag=HEAD&content-type=text/vnd.viewcvs-markup XML.km3] metamodel and parameters.xml into ecore model. Moreover, you need to add
+
[http://dev.eclipse.org/viewcvs/indextech.cgi/~checkout~/org.eclipse.gmt/AM3/org.eclipse.am3.zoos.atlanticRaster/build/XMLHelpers.asm?rev=1.1&content-type=text/vnd.viewcvs-markup XMLHelpers.asm] ATL library.
+
 
+
==How can I specify a Virtual Machine operation in Java?==
+
 
+
It is possible to add new Java operations to the ATL Virtual Machine (VM).
+
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.
+
 
+
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.
+
The process to register operations on OCL primitive types (e.g. Boolean, Integer, String) is similar.
+
  
 
==How can I tune the XML output of ATL?==
 
==How can I tune the XML output of ATL?==
  
 
The ATL Virtual Machine can write target models to XML files in two different ways:
 
The ATL Virtual Machine can write target models to XML files in two different ways:
* XMI writing is delegated to the [[ATL_Model_Handlers|model handler]] used to handle the model (e.g., EMF, MDR).
+
* XMI writing is delegated to EMF.
It is usually not possible to change the target format in this case because XMI support in each model handler implements a precise mapping from a metamodel to an XML Schema.
+
However, different model handlers may produce different XMI files (e.g., XMI 2.0 with EMF, XMI 1.2 with MDR).
+
 
* Target models can be extracted into XML files using custom XML Schemas.
 
* 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 [http://www.eclipse.org/gmt/am3/zoos/atlanticZoo/#XML 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/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).
The process of transforming a model to XML then extracting it can be automated using [[AM3_Ant_Tasks|ant tasks]].
+
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 ''org.eclipse.m2m.atl.projectors.xml'' plugin (see [[ATL/Howtos#How_can_I_handle_arbitrary_XML_documents|previous section]]).
This is also illustrated by the Table2SVGPieChart scenario (see build.xml in the zip file of Table2SVGPieChart for directions).
+
  
So to obtain a custom XML file (e.g. WS-BPEL, WSDL etc) you must write an ATL transformation from your target meta-model to an XML meta-model. The model outputted from this transformation can be serialised to custom XML using the AM3 "XML extractor" feature. Details of how to manually perform this function in your eclipse setup are as follows:
+
==How can I implement my own injector or extractor?==
  
* Install AM3 into your eclipse environment
+
An injection/extraction is a transformation from/to another Technical Space (e.g., XML, Grammarware) to/from the Model Engineering Technical Space.
* Restart eclipse
+
An injector/extractor is a component implementing an injection/extraction.
* Change to the new AM3 perspective
+
* Right click on the model instance to be extracted into XML and select "Extract XML model to XML file"
+
  
Remarks:
+
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].
* You always obtain XMI files (and thus non-customizable XML output) after running a launch configuration.
+
  
==How can I handle arbitrary XML documents?==
+
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.
 +
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].
  
Arbitrary XML documents can be used as source or target of ATL transformations.
+
==How can I transform UML models?==
However, this cannot be done directly (see [[ATL_Howtos#How_can_I_tune_the_XML_output_of_ATL.3F|previous section]]) but rather through injectors and extractors.
+
  
The XML injector can be executed from the contextual menu on files with the .xml extension, or from the [[AM3_Ant_Tasks#am3.loadModel|am3.loadModel]] ant task. An example of using the XML injector is given in the [[ATL_Howtos#How_do_I_use_extern_parameters_in_ATL_transformations.3F|how to use external parameter]] section.
+
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 XML extractor can be executed from the contextual menu on files with the .ecore extension, or from the [[AM3_Ant_Tasks#am3.saveModel|am3.saveModel]] ant task.
+
ATL allows to transform such UML models as any other EMF models.
  
The XML injector is implemented in [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.m2m/org.eclipse.m2m.atl/plugins/org.eclipse.m2m.atl.engine.vm/src/org/eclipse/m2m/atl/engine/injectors/xml/XMLInjector.java?root=Modeling_Project&view=markup XMLInjector] ([http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.gmt/ATL/org.atl.engine.vm/src/org/atl/engine/injectors/xml/XMLInjector.java?view=markup old version]), which extends [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.m2m/org.eclipse.m2m.atl/plugins/org.eclipse.m2m.atl.engine.vm/src/org/eclipse/m2m/atl/engine/injectors/Injector.java?root=Modeling_Project&view=markup Injector] ([http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.gmt/ATL/org.atl.engine.vm/src/org/atl/engine/injectors/Injector.java?view=markup old version]).
+
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.
  
The XML extractor is implemented in
+
Usage of [[ATL_Editor_content_assist|content assist]] (i.e., code completion) is especially useful with big metamodels like UML2.
[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.m2m/org.eclipse.m2m.atl/plugins/org.eclipse.m2m.atl.engine.vm/src/org/eclipse/m2m/atl/engine/extractors/xml/XMLExtractor.java?root=Modeling_Project&view=markup XMLExtractor] ([http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.gmt/ATL/org.atl.engine.vm/src/org/atl/engine/extractors/xml/XMLExtractor.java?view=markup old version]), which extends [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.m2m/org.eclipse.m2m.atl/plugins/org.eclipse.m2m.atl.engine.vm/src/org/eclipse/m2m/atl/engine/extractors/Extractor.java?root=Modeling_Project&view=markup Extractor] ([http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.gmt/ATL/org.atl.engine.vm/src/org/atl/engine/extractors/Extractor.java?view=markup old version]).
+
  
==How can I implement my own injector or extractor?==
+
==How can I retrieve tagged values from stereotyped UML model elements?==
  
An injection (resp. extraction) is a transformation from (resp. to) another Technical Space (e.g., XML, Grammarware) to (resp. from) the Model Engineering Technical Space.
+
In ATL, a profiled UML model used as source model is viewed like any other UML model.
An injector (resp. extractor) is a tool implementing an injection (resp. extraction).
+
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:
  
Injectors and extractors may be used when respectively [[AM3_Ant_Tasks#Task_am3.loadModel|loading]] and [[AM3_Ant_Tasks#Task_am3.saveModel|saving]] models using the [[AM3 Ant Tasks]].
+
module uml2something;
 +
create OUT : targetMetamodel from IN : UML;
  
To be usable from the AM3 Ant Tasks an injector (resp. extractor) must implement the [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.m2m/org.eclipse.m2m.atl/plugins/org.eclipse.m2m.atl.engine.vm/src/org/eclipse/m2m/atl/engine/injectors/Injector.java?root=Modeling_Project&view=markup Injector] (resp. [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.m2m/org.eclipse.m2m.atl/plugins/org.eclipse.m2m.atl.engine.vm/src/org/eclipse/m2m/atl/engine/extractors/Extractor.java?revision=1.2&root=Modeling_Project&view=markup extractor]) interface.
+
If atl seems to ignore your stereotypes, you can add your profile as source model. You obtain the following header:
  
Some injectors and extractors are already available: [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.m2m/org.eclipse.m2m.atl/plugins/org.eclipse.m2m.atl.engine.vm/src/org/eclipse/m2m/atl/engine/injectors/xml/XMLInjector.java?root=Modeling_Project&view=markup XMLInjector], [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.m2m/org.eclipse.m2m.atl/plugins/org.eclipse.m2m.atl.engine.vm/src/org/eclipse/m2m/atl/engine/extractors/xml/XMLExtractor.java?root=Modeling_Project&view=markup XMLExtractor], [http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.gmt/org.eclipse.gmt.tcs/plugins/org.eclipse.gmt.tcs.injector/src/org/eclipse/gmt/tcs/injector/TCSInjector.java?view=markup TCSInjector], and [http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.gmt/org.eclipse.gmt.tcs/plugins/org.eclipse.gmt.tcs.extractor/src/org/eclipse/gmt/tcs/extractor/TCSExtractor.java?view=markup TCSExtractor].
+
module uml2something;
 +
create OUT : targetMetamodel from IN : UML, INPROFILE : profile;
  
The injector extension point of the [http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.gmt/AM3/org.eclipse.am3.core/plugin.xml?view=markup AM3 Core plugin] enables plugins to contribute injectors.
+
After that you can use operations like:
There is no such extension point for extractors yet.
+
* 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).
  
==How can I transform UML models?==
+
A helper like:
  
There are several implementations of UML.
+
helper context UML!Element def: hasStereotype(name : String) : Boolean =
The one we consider here is [http://www.eclipse.org/modeling/mdt/?project=uml2 MDT/UML2].
+
not self.getAppliedStereotype(name).oclIsUndefined();
  
To transform UML2 models with ATL from Eclipse the UML2 plugins must be installed.
+
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.
The UML2 metamodel must be loaded from the EMF registry (i.e., by namespace URI).
+
As it uses getAppliedStereotype, it needs the fully qualified name of the stereotype (e.g., profileName::sterotypeName).
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/AM3_Ant_Tasks#Task_am3.loadModel|am3.loadModel]] task.
+
  
Usage of [[ATL_Editor_content_assist|content assist]] (i.e., code completion) is especially useful with big metamodels like UML2.
+
==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 [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.
 +
 
 +
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.
 +
The process to register operations on OCL primitive types (e.g. Boolean, Integer, String) is similar.
  
 
[[Category:ATL]]
 
[[Category:ATL]]

Revision as of 08:56, 31 August 2012

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.

Contents


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.