Difference between revisions of "ATL/Howtos"

Revision as of 03:38, 20 September 2006

< To: ATL

This page contains a list of problems related to ATL usage. It gives hints towards solutions and links to examples.

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 launch transformations programmatically?

The ATL development environment (ATL Development Tools, or ADT) provides several means to launch transformations:

• by specifying a launch configuration,
• by writing an ant script using the AM3 Ant Tasks.

However, in some cases, it is necessary to launch an ATL transformation from Java code. The AtlLauncher class can be used for this purpose. The KM3Projector class of the KM3 plugin contains example usages of the AtlLauncher class (e.g. the getEcoreFromKM3 method).

Remark 1: the AtlCompiler class may be used to compile ATL transformations into .asm files executable on the ATL Virtual Machine.

Remark 2: There may be problem when using MDR as model handler, as it shown in 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.

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:

<parameters>
	<param name="source" value="KM3"/>
	<param name="target" value="ATL"/>
</parameters>

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

module AMW2ATL;
create OUT : ATL from source : MOF, target : MOF, 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 used the previous helper (due to the getAttrVal call), you need to used XMLHelpers.asm ATL Library and add in the transformation:

uses XMLHelpers;

The following code, it is a simple example to show how to used getParameter helper:

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

In AM3 Ant Tasks, you need to add the parameters model, the XML.km3 metamodel and the XMLHelpers.asm library. For this you need parameters.xml model in ecore. See the following example:

<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">
	<injector name="ebnf">
		<param name="name" value="KM3" />
	</injector>
</am3.loadModel>

<am3.loadModel modelHandler="EMF" name="Parameters" metamodel="XML" path="Parameters.xml">
	<injector name="xml"/>
</am3.loadModel>

<am3.atl path="myTransformation.atl">
	<inModel name="source" model="left"/>
	<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"/>	

Instead of AM3 Ant Tasks, if you use ATL launch configuration then you need to inject XML.km3 metamodel and parameters.xml into ecore model. Moreover, you need to add XMLHelpers.asm ATL library.