Skip to main content
Jump to: navigation, search


Revision as of 05:29, 31 August 2012 by (Talk | contribs) (How can I tune the XML output of ATL?)

This page contains a list of problems related to ATL usage. It gives hints towards solutions and links to 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 UML2Java transformation.

The atlanticRaster zoo is also using this technique. It first transforms KM3 metamodels into DOT models with the KM32DOT.atl transformation. It then uses DOT2Text.atl to query a String from the DOT model. This string corresponds to the generated DOT code. Then, the build.xml ant scripts makes use of the am3.saveModel task with an ATL extractor pointing to the 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 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.

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:

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

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

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 | = 'param'
	)->select(e |
		e.getAttrVal('name') = name

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 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 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.

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

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 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.loadModel ant task. An example of using the XML injector is given in the how to use external parameter section.

The XML extractor can be executed from the contextual menu on files with the .ecore extension, or from the am3.saveModel ant task.

The XML injector is implemented in XMLInjector (old version), which extends Injector (old version).

The XML extractor is implemented in XMLExtractor (old version), which extends Extractor (old version).

How can I implement my own injector or extractor?

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. An injector (resp. extractor) is a tool implementing an injection (resp. extraction).

Injectors and extractors may be used when respectively loading and saving models using the AM3 Ant Tasks.

To be usable from the AM3 Ant Tasks an injector (resp. extractor) must implement the Injector (resp. extractor) interface.

Some injectors and extractors are already available: XMLInjector, XMLExtractor, TCSInjector, and TCSExtractor.

The injector extension point of the AM3 Core plugin enables plugins to contribute injectors. There is no such extension point for extractors yet.

How can I transform UML models?

There are several implementations of UML. The one we consider here is MDT/UML2.

To transform UML2 models with ATL from Eclipse the UML2 plugins must be installed. 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 [[1]] 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).

Copyright © Eclipse Foundation, Inc. All Rights Reserved.