Jump to: navigation, search

Difference between revisions of "ATL/Howtos"

< ATL
(Examples)
(Using an XML file)
Line 131: Line 131:
 
</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 [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:
 
<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');
Line 173: Line 173:
  
 
Instead of [[AM3 Ant Tasks]], if you use ATL launch configuration then you need to inject
 
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.atlantic/XML.km3?rev=1.1&only_with_tag=HEAD&content-type=text/vnd.viewcvs-markup XML.km3] metamodel and parameters.xml into an 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.
 
[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.
  

Revision as of 14:00, 25 June 2008

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

Description

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 programmatically (e.g., from Java code).

Solution

The AtlLauncher class can be used for this purpose. Complete Milan Milanovic's ATL template bundle is basic solution for integration of ATL engine and for transformation execution in Java applications.

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

Libraries and Prequesites

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.

Here is a description of what is required for all kind of use :

ATL

  • 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, 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 org.eclipse.m2m.atl.drivers.emf4atl, org.eclipse.m2m.atl.engine.vm and 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

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 following libraries are only required for the use of KM3.

  • org.eclipse.gmt.am3.dsls.km3.jar

Examples

A very simple working example, involving the invocation of an ATL transformation from a plug-in can be seen at JWT to BPMN and vice versa, using regular .ecore metamodels.

The KM3Projector class of the KM3 plugin contains example usages of the AtlLauncher class (e.g. the getEcoreFromKM3 method).

Another illustration is given in Dennis Wagelaar's ATL command line tool (here is a direct link to the Java class). This tool was discussed on the ATL mailing list (see the "Related threads" section below).

Related threads

Here is a list of discussion threads related to this issue that occured on the old ATL mailing list atl_discussion, or on the Eclipse M2M newsgroup:

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 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');

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 an ecore model. Moreover, you need to add 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 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 the model handler used to handle the model (e.g., EMF, MDR).

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.

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 ant tasks. 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:

  • Install AM3 into your eclipse environment
  • Restart eclipse
  • 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:

  • You always obtain XMI files (and thus non-customizable XML output) after running a launch configuration.

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.