Skip to main content

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "ATL/User Guide"

< ATL
(Primitive data types)
 
(135 intermediate revisions by the same user not shown)
Line 1: Line 1:
= Introduction =
+
#REDIRECT [[ATL/User_Guide_-_Introduction]]
ATL, the Atlas Transformation Language, is the ATLAS INRIA & LINA research group’s answer to the [http://www.omg.org/docs/formal/02-04-03.pdf OMG MOF]/[http://www.omg.org/docs/ad/02-04-10.pdf QVT RFP].
+
It is a model transformation language specified as both a metamodel and a textual concrete syntax.
+
In the field of Model-Driven Engineering (MDE), ATL provides developers with a mean to specify the way to produce a number of target models from a set of source models.
+
 
+
The ATL language is a hybrid of declarative and imperative programming.
+
The preferred style of transformation writing is the declarative one: it enables to simply express mappings between the source and target model elements.
+
However, ATL also provides imperative constructs in order to ease the specification of mappings that can hardy be expressed declaratively.
+
 
+
An ATL transformation program is composed of rules that define how source model elements are matched and navigated to create and initialize the elements of the target models.
+
Besides basic model transformations, ATL defines an additional model querying facility that enables to specify requests onto models.
+
ATL also allows code factorization through the definition of ATL libraries.
+
 
+
Developed over the Eclipse platform, the [http://www.sciences.univ-nantes.fr/lina/atl/bibliography/AllilaireIdrissi0001 ATL Integrated Development Environment (IDE)] provides a number of standard development tools (syntax highlighting, debugger, etc.) that aim to ease the design of ATL transformations.
+
The ATL development environment also offers a number of additional facilities dedicated to models and metamodels handling.
+
These features include a simple textual notation dedicated to the specification of metamodels, but also a number of standard bridges between common textual syntaxes and their corresponding model representations.
+
 
+
The present manual aims at providing both an exhaustive reference of the ATL transformation language and a comprehensive guide for the users of the ATL IDE.
+
For this purpose, this manual is organized in three main parts: the first part ([[#An Introduction to Model Transformation|Section 2]] and [[#Overview of the Atlas Transformation Language|Section 3]]) introduces the main concepts of model transformation and provides an overview of the structure and the semantics of the ATL language.
+
The second part (corresponding to [[#The ATL Language|Section 4]]) focuses on the description of the ATL language while the last part ([[#The ATL Tools|Section 5]]) deals with the use of the ATL tools.
+
 
+
The detailed structure of the document looks as follows:
+
* [[#An Introduction to Model Transformation|Section 2]] provides a short introduction to the model transformation area;
+
* [[#Overview of the Atlas Transformation Language|Section 3]] offers an overview of the ATL capabilities;
+
* [[#The ATL Language|Section 4]] is dedicated to the description of the ATL language;
+
* [[#The ATL Tools|Section 5]] describes the IDE that has been developed around the ATL transformation language;
+
* [[#Additional ATL Resources|Section 6]] provides ATL programmers with a number of pointers to available ATL resources;
+
* Finally, [[#Conclusion|Section 7]] concludes the document.
+
 
+
= An Introduction to Model Transformation =
+
Models are now part of an increasing number of engineering processes (such as software engineering). However, in most cases, they are still confined to a simple documentation role instead of being actively integrated into the engineering process. As opposed to this passive approach, the field of Model-Driven Engineering (MDE) aims to consider models as first class entities. It also considers that the different kinds of handled items (such as the tools, the repositories, etc.) can be viewed and represented as models. The model-driven approach supposes to provide model designers and developers with a set of operations dedicated to the manipulation of models. In this context, model transformation appears to be a central operation for model handling: it aims to make it possible to specify the way to produce a number of target models based on a set of source models. In the scope of the model-driven engineering, it is assumed that model transformations, as any other model-based tool, can be modelled, which means that they have to be considered themselves as models.
+
This section aims to provide an overview of the main MDE concepts, with a particular focus on model transformation. To this end, it first presents [[#The Model-Driven Architecture|the organisation of the model-driven architecture]]. This first section addresses the model definition mechanisms that constitute the core of the MDE area: it introduces the notions of models, metamodels and metametamodels, as well as the conformance relation that relates these different artefacts. The second part of the section more particularly deals with model transformation. It provides an overview of the conceptual model transformation architecture and detailed the way this conceptual architecture is matched to the ATL language.
+
 
+
== The Model-Driven Architecture ==
+
Models constitute the basic pieces of the model-driven architecture. Indeed, in the field of model-driven engineering, a model is defined according to the semantics of a model of models, also called a ''metamodel''. A model that respects the semantics defined by a metamodel is said to ''conform'' to this metamodel. As an example, Figure 1 illustrates the conformance relation between a Petri net model and the Petri Nets metamodel.
+
 
+
TODO place figure1
+
 
+
TODO place figure2
+
 
+
TODO place figure3
+
 
+
As every model, the described Petri net model is composed of a number of distinct model elements. In the context of a Petri net, these model elements correspond to the places, the transitions and the arcs that compose the model. These different elements, as well as the way they are related, are defined in the scope of the Petri net metamodel. In the same way a model conforms to its metamodel, there exists a relation between the elements of a model and those of its metamodel. This relation, called ''meta'', associates each element of a model with the metamodel element it instantiates. Figure 2 illustrates some of the existing meta relations between elements of the Petri net model and those of the Petri net metamodel.
+
At this stage, it must be recalled that, before being a metamodel, a metamodel is a model. This implies for it to conform to its own metamodel. To this end, the model-driven architecture defines a third modelling level which corresponds to the ''metametamodel'', as illustrated in Figure 3.
+
A metametamodel aims to introduce the semantics that are required to specify metamodels. As a model with its metamodel, a metamodel conforms to the metametamodel. Note that a metametamodel is usually self-defined, which means that it can be specified by means of its own semantics. In such a case, a metametamodel conforms to itself.
+
Several metametamodel technologies are available. The ATL transformation engine currently provides support for two of these existing technologies: the Meta Object Facilities ([http://www.omg.org/docs/formal/02-04-03.pdf MOF 1.4]) defined by the OMG and the Ecore metametamodel (Budinsky, F., Steinberg, D., Ellersick, R., Grose, T. Eclipse Modeling Framework, Chapter 5 ”Ecore Modeling Concepts”. Addison Wesley Professional. ISBN: 0131425420, 2004.) defined by the [[EMF|Eclipse Modeling Framework (EMF)]]. This means that ATL is able to handle metamodels that have been specified according to either the MOF or the Ecore semantics.
+
 
+
== Model Transformation ==
+
In the scope of model-driven engineering, model transformation aims to provide a mean to specify the way to produce target models from a number of source models. For this purpose, it should enable developers to define the way source model elements must be matched and navigated in order to initialize the target model elements.
+
Formally, a simple model transformation has to define the way for generating a model Mb, conforming to a metamodel MMb, from a model Ma conforming to a metamodel MMa. As previously highlighted, a major feature in model engineering is to consider, as far as possible, all handled items as models. The model transformation itself therefore has to be defined as a model. This transformation model has to conform to a transformation metamodel that defines the model transformation semantics. As other metamodels, the transformation metamodel has, in turn, to conform to the considered metametamodel.
+
 
+
TODO place figure4
+
 
+
Figure 4 summarizes the full model transformation process. A model Ma, conforming to a metamodel MMa, is here transformed into a model Mb that conforms to a metamodel MMb. The transformation is defined by the model transformation model Mt which itself conforms to a model transformation metamodel MMt. This last metamodel, along with the MMa and MMb metamodels, has to conform to a metametamodel MMM (such as MOF or Ecore).
+
ATL is a model transformation language that enables to specify how one (or more) target model can be produced from a set of source models. In other word, ATL introduces a set of concepts that make it possible to describe model transformations.
+
 
+
TODO place figure5
+
 
+
Figure 5 provides an overview of the ATL transformation (Author2Person) that enables to generate a Person model, conforming to the metamodel MMPerson, from an Author model that conforms to the metamodel MMAuthor. The designed transformation, which is expressed by means of the ATL language, conforms to the ATL metamodel. In this example, the three metamodels (MMAuthor, MMPerson and ATL) are expressed using the semantics of the Ecore metametamodel.
+
 
+
= Overview of the Atlas Transformation Language =
+
The ATL language offers ATL developers to design different kinds of ATL units. An ATL unit, whatever its type, is defined in its own distinct ATL file. ATL files are characterized by the ''.atl'' extension.
+
 
+
As an answer to the [http://www.omg.org/docs/formal/02-04-03.pdf OMG MOF]/[http://www.omg.org/docs/ad/02-04-10.pdf QVT RFP], ATL mainly focus on the model to model transformations. Such model operations can be specified by means of ATL ''modules''. Besides modules, the ATL transformation language also enables developers to create model to primitive data type programs. These units are called ATL ''queries''. The aim of a query is to compute a [[#Primitive_data_types|primitive]] value, such as a string or an integer, from source models. Finally, the ATL language also offers the possibility to develop independent ATL ''libraries'' that can be imported from the different types of ATL units, including libraries themselves. This provides a convenient way to factorize ATL code that is used in multiple ATL units. Note that the three ATL unit kinds same the share ''.atl'' extension.
+
 
+
These different ATL units are detailed in the following subsections. This section explains what each kind of unit should be used for, and provides an overview of the content of these different units.
+
 
+
== ATL module ==
+
An ATL module corresponds to a model to model transformation. This kind of ATL unit enables ATL developers to specify the way to produce a set of target models from a set of source models. Both source and target models of an ATL module must be “typed” by their respective metamodels. Moreover, an ATL module accepts a fixed number of models as input, and returns a fixed number of target models. As a consequence, an ATL module can not generate an unknown number of similar target models (e.g. models that conform to a same metamodel).
+
 
+
[[#Structure of an ATL module|Section 3.1.1]] details the structure of an ATL module. [[#Module execution modes|Section 3.1.2]] presents the two available execution modes for ATL modules. Finally, the execution semantics of the ATL module are briefly introduced in [[#Module execution semantics|Section 3.1.3]].
+
 
+
=== Structure of an ATL module ===
+
An ATL module defines a model to model transformation. It is composed of the following elements:
+
*A header section that defines some attributes that are relative to the transformation module;
+
*An optional import section that enables to import some existing [[#ATL_Library|ATL libraries]];
+
*A set of helpers that can be viewed as an ATL equivalent to Java methods;
+
*A set of rules that defines the way target models are generated from source ones.
+
 
+
Helpers and rules do not belong to specific sections in an ATL transformation. They may be declared in any order with respect to certain conditions (see [[#ATL_Helpers|Section 4.4]] for further details). These four distinct element types are now detailed in the following subsections.
+
 
+
==== Header section ====
+
The header section defines the name of the transformation module and the name of the variables corresponding to the source and target models. It also encodes the execution mode of the module. The syntax for the header section is defined as follows:
+
module ''module_name'';
+
create ''output_models'' [from|refining] ''input_models'';
+
 
+
The keyword ''module'' introduces the name of the module. Note that the name of the ATL file containing the code of the module has to correspond to the name of this module. For instance, a ModelA2ModelB transformation module has to be defined into the ''ModelA2ModelB''.atl file.
+
The target models declaration is introduced by the ''create'' keyword, whereas the source models are introduced either by the keyword ''from'' (in normal mode) or ''refining'' (in case of refining transformation). The declaration of a model, either a source input or a target one, must conform the scheme ''model_name : metamodel_name''. It is possible to declare more than one input or output model by simply separating the declared models by a coma. Note that the name of the declared models will be used to identity them. As a consequence, each declared model name has to be unique within the set of declared models (both input and output ones).
+
The following ATL source code represents the header of the ''Book2Publication.atl'' file, e.g. the ATL header for the transformation from the Book to the Publication metamodel 8:
+
module Book2Publication;
+
create OUT : Publication from IN : Book;
+
 
+
TODO reference the metamodel
+
TODO Example with several models
+
 
+
==== Import section ====
+
The optional import section enables to declare which [[#ATL_Library|ATL libraries]] have to be imported. The declaration of an ATL library is achieved as follows:
+
uses ''extensionless_library_file_name'';
+
For instance, to import the strings library, one would write:
+
uses strings;
+
Note that it is possible to declare several distinct libraries by using several successive uses instructions.
+
 
+
==== Helpers ====
+
ATL helpers can be viewed as the ATL equivalent to Java methods. They make it possible to define factorized ATL code that can be called from different points of an ATL transformation.
+
An ATL helper is defined by the following elements:
+
*a name (which corresponds to the name of the method);
+
*a context type. The context type defines the context in which this attribute is defined (in the same way a method is defined in the context of given class in object-programming);
+
*a return value type. Note that, in ATL, each helper must have a return value;
+
*an ATL expression that represents the code of the ATL helper;
+
*an optional set of parameters, in which a parameter is identified by a couple (parameter name, parameter type).
+
 
+
As an example, it is possible to consider a helper that returns the maximum of two integer values: the contextual integer and an additional integer value which is passed as parameter. The declaration of such a helper will look like (detail of the helper code is not interesting at this stage, please refer to [[#ATL Helpers|Section 4.4]] for further details):
+
helper context Integer def : max(x : Integer) : Integer = ...;
+
It is also possible to declare a helper that accepts no parameter. This is, for instance, the case for a helper that just multiplies an integer value by two:
+
helper context Integer def : double() : Integer = self * 2;
+
In some cases, it may be interesting to be able to declare an ATL helper without any particular context. This is not possible in ATL since each helper must be associated with a given context. However, the ATL language allows ATL developers to declare helpers within a default context (which corresponds to the ATL module). This is achieved by simply omitting the context part of the helper definition. It is possible, by this mean, to provide a new version of the max helper defined above:
+
helper def : max(x1 : Integer, x2 : Integer) : Integer = ...;
+
Note that several helpers may have the same name in a single transformation. However, helpers with a same name must have distinct signatures to be distinguishable by the ATL engine (see [[#ATL Helpers|Section 4.4]] for further details).
+
The ATL language also makes it possible to define attributes. An attribute helper is a specific kind of helper that accepts no parameters, and that is defined either in the context of the ATL module or of a model element. In the remaining of the present document, the term ''attribute'' will be specifically used to refer to attribute helpers, whereas the generic term of ''helper'' will refer to a functional helper.
+
Thus, the attribute version of the double helper defined above will be declared as follows:
+
helper context Integer def : double : Integer = self * 2;
+
Declaring a functional helper with no parameter or an attribute may appear to be equivalent. It is therefore equivalent from a functional point of view. However, there exists a significant difference between these two approaches when considering the execution semantics. Indeed, compared to the result of a functional helper which is calculated each time the helper is called, the return value of an ATL attribute is computed only once when the value is required for the first time. As a consequence, declaring an ATL attribute is more efficient than defining an ATL helper that will be executed as many times as it is called.
+
Note that the ATL attributes that are defined in the context of the ATL module are initialized (during the [[#Default_mode_execution_semantics|initialization phase]]) in the order they have been declared in the ATL file. This implies that the order of declaration of this kind of attribute is of some importance: an attribute defined in the context of the ATL module has to be declared after the other ATL module attributes it depends on for its initialization. A wrong order in the declaration of the ATL module attributes will raise an error during the initialization phase of the ATL program execution.
+
 
+
==== Rules ====
+
In ATL, there exist two different kinds of rules that correspond to the two different programming modes provided by ATL (e.g. declarative and imperative programming): the matched rules (declarative programming) and the called rules (imperative programming).
+
 
+
'''Matched rules'''. The matched rules constitute the core of an ATL declarative transformation since they make it possible to specify:
+
 
+
1) for which kinds of source elements target elements must be generated,
+
 
+
2) the way the generated target elements have to be initialized.
+
 
+
A matched rule is identified by its name. It matches a given type of source model element, and generates one or more kinds of target model elements. The rule specifies the way generated target model elements must be initialized from each matched source model element.
+
A matched rule is introduced by the keyword ''rule''. It is composed of two mandatory (the source and the target patterns) and two optional (the local variables and the imperative) sections. When defined, the local variable section is introduced by the keyword ''using''. It enables to locally declare and initialize a number of local variables (that will only be visible in the scope of the current rule).
+
The source pattern of a matched rule is defined after the keyword ''from''. It enables to specify a model element variable that corresponds to the type of source elements the rule has to match. This type corresponds to an entity of a source metamodel of the transformation. This means that the rule will generate target elements for each source model element that conforms to this matching type. In many cases, the developer will be interested in matching only a subset of the source elements that conform to the matching type. This is simply achieved by specifying an optional condition (expressed as an ATL expression, see [[#OCL_Declarative_Expressions|Section 4.2]] for further details) within the rule source pattern. By this mean, the rule will only generate target elements for the source model elements that both conform to the matching type and verify the specified condition.
+
 
+
The target pattern of a matched rule is introduced by the keyword ''to''. It aims to specify the elements to be generated when the source pattern of the rule is matched, and how these generated elements are initialized. Thus, the target pattern of a matched rule specifies a distinct target pattern element for each target model element the rule has to generate when its source pattern is matched. A target pattern element corresponds to a model element variable declaration associated with its corresponding set of initialization bindings. This model element variable declaration has to correspond to an entity of the target metamodels of the transformation.
+
 
+
Finally, the optional imperative section, introduced by the keyword ''do'', makes it possible to specify some imperative code that will be executed after the initialization of the target elements generated by the rule.
+
As an example, consider the following simple ATL matched rule (MMAuthor and MMPerson metamodels are respectively detailed in 8 and 8):
+
TODO reference metamodels
+
rule Author {
+
from
+
a : MMAuthor!Author
+
to
+
p : MMPerson!Person (
+
name <- a.name,
+
surname <- a.surname
+
)
+
}
+
This rule, called Author, aims to transform Author source model elements (from the MMAuthor source model) to Person target model elements in the MMPerson target model. This rule only contains the mandatory source and target patterns. The source pattern defines no filter, which means that all Author classes of the source MMAuthor model will be matched by the rule. The rule target pattern contains a single simple target pattern element (called ''p''). This target pattern element aims to allocate a Person class of the MMPerson target model for each source model element matched by the source pattern. The features of the generated model element are initialized with the corresponding features of the matched source model element.
+
Note that a source model element of an ATL transformation should not be matched by more than one ATL matched rule. This implies the source pattern of matched rules to be designed carefully in order to respect this constraint. Moreover, an ATL matched rule can not generate ATL primitive type values.
+
 
+
 
+
'''Called rules'''. The called rules provide ATL developers with convenient imperative programming facilities. Called rules can be seen as a particular type of helpers: they have to be explicitly called to be executed and they can accept parameters. However, as opposed to helpers, called rules can generate target model elements as matched rules do. A called rule has to be called from an imperative code section, either from a match rule or another called rule.
+
 
+
As a matched rule, a called rule is introduced by the keyword rule. As matched ''rules'', called rules may include an optional local variables section. However, since it does not have to match source model elements, a called rule does not include a source pattern. Moreover, its target pattern, which makes it possible to generate target model elements, is also optional. Note that, since the called rule does not match any source model element, the initialization of the target model elements that are generated by the target pattern has to be based on a combination of local variables, parameters and module attributes. The target pattern of a called rule is defined in the same way the target pattern of a matched rule is. It is also introduced by the keyword ''to''.
+
A called rule can also have an imperative section, which is similar to the ones that can be defined within matched rules. Note that this imperative code section is not mandatory: it is possible to specify a called rule that only contains either a target pattern section or an imperative code section.
+
In order to illustrate the called rule structure, consider the following simple example:
+
rule NewPerson (na: String, s_na: String) {
+
to
+
p : MMPerson!Person (
+
name <- na
+
)
+
do {
+
p.surname <- s_na
+
}
+
}
+
This called rule, named NewPerson, aims to generate Person target model elements. The rule accepts two parameters that correspond to the name and the surname of the Person model element that will be created by the rule execution. The rule has both a target pattern (called ''p'') and an imperative code section. The target pattern allocates a Person class each time the rule is called, and initializes the ''name'' attribute of the allocated model element. The imperative code section is executed after the initialization of the allocated element (see [[#Default_mode_execution_semantics|Section 3.1.3.1]] for further details on execution semantics). In this example, the imperative code sets the ''surname'' attribute of the generated Person model element to the value of the parameter ''s_na''.
+
 
+
=== Module execution modes ===
+
The ATL execution engine defines two different execution modes for ATL modules. With the default execution mode, the ATL developer has to explicitly specify the way target model elements must be generated from source model elements.
+
In this scope, the design of a transformation which aims to copy its source model with only a few modifications may prove to be very tiresome. Designing this transformation in default execution mode therefore requires the developer to specify the rules that will generate the modified model elements, but also all the rules that will only copy, without any modification, source to target model elements. The refining execution mode has been designed for this kind of situation: it enables ATL developers to only specify the modifications that have to be performed between the transformation source and target models.
+
These two execution modes are described in the following subsections.
+
 
+
==== Normal execution mode ====
+
The normal execution mode is the ATL module default execution mode. It is associated with the keyword ''from'' in the module [[#Header_section|header]].
+
In default execution mode, the ATL developer has to specify, either by matched or called rules, the way to generate each of the expected target model elements. This execution mode suits to most ATL transformations where target models differ from the source ones.
+
 
+
==== Refining execution mode ====
+
The refining execution mode has been introduced to ease the programming of refining transformations between similar source and target models. With the refining mode, ATL developers can focus on the ATL code dedicated to the generation of modified target elements. Other model elements (e.g. those that remain unchanged between the source and the target model) are implicitly copied from the source to the target model by the ATL engine.
+
The refining mode is associated with the keyword ''refining'' in the [[#Header_section|header]] of the ATL module. Granularity of the refining mode is defined at the model element level. This means that the developer will have to specify how to generate a model element as soon as the transformation modifies one of its features (either an attribute or a reference). On the other side, the developer is not required to specify the ATL code that corresponds to the copy of unchanged model elements. This feature may result in important saving of ATL code, which, in the end, makes the programming of refining ATL transformations simpler and easier.
+
At current time, the refining mode can only be used to transform a single source model into a single target model. Both source and target models must conform to the same metamodel.
+
 
+
=== Module execution semantics ===
+
This section introduces the basics of the ATL execution semantics. Although designing ATL transformations does not require any particular knowledge on the ATL execution semantics, understanding the way an ATL transformation is processed by the ATL engine can prove to be helpful in certain cases (in particular, when debugging a transformation).
+
 
+
The semantics of the two available ATL execution modes, the normal and the refining modes, are introduced in the following subsections.
+
 
+
==== Default mode execution semantics ====
+
The execution of an ATL module is organized into three successive phases:
+
*a module initialization phase,
+
*a matching phase of the source model elements,
+
*a target model elements initialization phase.
+
 
+
The module initialization step corresponds to the first phase of the execution of an ATL module. In this phase, the attributes defined in the context of the transformation module are initialized. Note that the initialization of these module attributes may make use of attributes that are defined in the context of source model elements. This implies these new attributes to be also initialized during the module initialization phase. If an entry point [[#Called Rules|called rule]] has been defined in the scope of the ATL module, the code of this rule (including target model elements generation) is executed after the initialization of the ATL module attributes.
+
 
+
During the source model elements matching phase, the matching condition of the declared matched rules are tested with the model elements of the module source models. When the matching condition of a matched rule is fulfilled, the ATL engine allocates the set of target model elements that correspond to the target pattern elements declared in the rule. Note that, at this stage, the target model elements are simply allocated: they are initialized during the target model elements initialization phase.
+
 
+
The last phase of the execution of an ATL module corresponds to the initialization of the target model elements that have been generated during the previous step. At this stage, each allocated target model element is initialized by executing the code of the bindings that are associated with the target pattern element the element comes from. Note that this phase allows invocations of the [[#The_ATL_Module_data_type|''resolveTemp()'']] operation that is defined in the context of the ATL module.
+
The imperative code section that can be specified in the scope of a matched rule is executed once the rule initialization step has completed. This imperative code can trigger the execution of some of the called rules that have been defined in the scope of the ATL module.
+
 
+
==== Refining mode execution semantics ====
+
TODO update
+
 
+
== ATL Query ==
+
An ATL query consists in a model to [[#Primitive data types|primitive type]] value transformation. An ATL query can be viewed as an operation that computes a primitive value from a set of source models. The most common use of ATL queries is the generation of a textual output (encoded into a string value) from a set of source models. However, ATL queries are not limited to the computation of string values and can also return a numerical or a boolean value.
+
 
+
The following subsections respectively describe the structure and the execution semantics of an ATL query.
+
 
+
=== Structure of an ATL query ===
+
After an optional [[#Import_section|import section]], an ATL query must define a query instantiation. A query instantiation is introduced by the keyword query and specifies the way its result must be computed by means of an ATL expression:
+
query query_name = exp;
+
Beside the query instantiation, an ATL query may include a number of helper or attribute definitions. Note that, although an ATL query is not strictly a module, it defines its own kind of default module context. It is therefore possible, for ATL developers, to declare helpers and attributes defined in the context of the module in the scope of an ATL query.
+
 
+
=== Query execution semantics ===
+
As an ATL module, the execution of an ATL query is organized in several successive phases. The first phase is the initialization phase. It corresponds to the [[#Default_mode_execution_semantics|initialization phase]] of the ATL modules and is dedicated to the initialization of the attributes that are defined in the context of the ATL module.
+
 
+
The second phase of the execution of an ATL query is the computation phase. During this phase, the return value of the query is calculated by executing the declarative code of the query element of the ATL query. Note that the helpers that have been defined within the query file can be called at both the initialization and the computation phases.
+
 
+
== ATL Library ==
+
The last type of ATL unit is the ATL library. Developing an ATL library enables to define a set of ATL helpers that can be called from different ATL units (modules, but also queries and libraries).
+
 
+
As the other kinds of ATL units, an ATL library can include an optional [[#Import_section|import section]]. Besides this import section, an ATL library defines a number of ATL helpers that will be made available in the ATL units that will import the library.
+
 
+
Compared to an ATL module, there exists no default module element for ATL libraries. As a consequence, it is impossible, in libraries, to declare helpers that are defined in the default context of the module. This means that all the helpers defined within an ATL library must be explicitly associated with a given context.
+
 
+
Compared to both modules and queries, an ATL library cannot be executed independently. This currently means that a library is not associated with any initialization step at execution time (as described in [[#Module_execution_semantics|Section 3.1.3]]). Due to this lack of initialization step, attribute helpers cannot be defined within an ATL library.
+
 
+
= The ATL Language =
+
This section is dedicated to the description of the ATL language. As introduced in [[#Overview_of_the_Atlas_Transformation_Language|Section 3]], the language enables to define three kinds of ATL units: the ATL transformation modules, the ATL queries and the ATL libraries. According to their type, these different kinds of units may be composed of a combination of ATL helpers, attributes, matched and called rules. This section aims to detail the syntax of these different ATL elements. For this purpose, the ATL language is based on [http://www.omg.org/docs/ptc/03-10-14.pdf OMG OCL (Object Constraint Language) norm] for both its data types and its declarative expressions.
+
There exist a few differences between the OCL definition and the current ATL implementation. They will be specified in this section by specific remarks.
+
 
+
== Data types ==
+
The ATL data type scheme is very close, but not similar, to the one defined by OCL. Figure 7 provides an overview of the data type’s structure considered in ATL. The different data types presented in this schema represent the possible instances of the OclType class.
+
 
+
The root element of the OclType instances structure is the abstract OclAny type, from which all other considered types directly or indirectly inherit. ATL considers six main kinds of data types: the primitive data types, the collection data types, the tuple type, the map type, the enumeration type and the model element type. Note that the map data type is implemented by ATL as an additional facility, but does not appear in the OCL specification.
+
 
+
The class OclType can be considered as the definition of a type in the scope of the ATL language. The different elements appearing in Figure 7 represent the type instances that are defined by OCL (except the map and the ATL module data types), and implemented within the ATL engine.
+
 
+
The OCL primitive data types correspond to the basic data types of the language (the string, boolean and numerical types). The set of collection types introduced by OCL provides ATL developers with different semantics for the handling of collections of elements. Additional data types include the enumerations, a tuple and a mapping data type and the model element data type. This last corresponds to the type of the entities that may be declared within the models handled by the ATL engine. Finally, the ATL module data type, which is specific to the ATL language, is associated with the running ATL units (either modules or queries).
+
 
+
TODO insert Figure7
+
 
+
Before going further in the description of these data types, it must be noted that each OCL expression, including the operations associated with each kind of data type (that are presented along with their respective data type), is defined in the context of an instance of a specific type. In ATL as in OCL, the reserved keyword ''self'' is used to refer to this contextual instance.
+
 
+
=== OclType operations ===
+
The class OclType corresponds to the definition of the type instances specified by OCL. It is associated with a specific OCL operation: ''allInstances()''. This operation, which accepts no parameter, returns a set containing all the currently existing instances of the type ''self''.
+
 
+
The ATL implementation provides an additional operation that enables to get all the instances of a given type that belong to a given metamodel. Thus, the ''allInstancesFrom(metamodel : String)'' operation returns a set containing the instances of type self that are defined within the model namely identified by ''metamodel''.
+
 
+
=== OclAny operations ===
+
This section describes a set of operations that are common to all existing data types. The syntax used to call an operation from a variable in ATL follows the classical dot notation:
+
self.operation_name(parameters)
+
ATL currently provides support for the following OCL-defined operations:
+
*comparison operators: =, <>;
+
*''oclIsUndefined()'' returns a boolean value stating whether self is undefined;
+
*''oclIsKindOf(t : oclType)'' returns a boolean value stating whether self is an either an instance of t or of one of its subtypes;
+
*''oclIsTypeOf(t : oclType)'' returns a boolean value stating whether self is an instance of t.
+
The operations ''oclIsNew()'' and ''oclAsType()'' defined by OCL are currently not supported by the ATL engine. ATL however implements a number of additional operations:
+
*''toString()'' returns a string representation of self. Note that the operation may return irrelevant string values for a few remaining types;
+
*''oclType()'' returns the oclType of ''self'';
+
*''asSequence(), asSet(), asBag()'' respectively return a sequence, a set or a bag containing self. These operations are redefined for the collection types;
+
*''output(s : String)'' writes the string s to the Eclipse console. Since the operation has no return value, it shall only be used in ATL imperative blocks;
+
*''debug(s : String)'' returns the ''self'' value and writes the ''“s : self_value”'' string to the eclipse console;
+
*''refSetValue(name : String, val : oclAny)'' is a reflective operation that enables to set the ''self'' feature identified by ''name'' to value ''val''. It returns ''self'';
+
*''refGetValue(name : String)'' is a reflective operation that returns the value of the ''self'' feature identified by ''name'';
+
*''refImmediateComposite()'' is a reflective operation that returns the immediate composite (e.g. the immediate container) of ''self'';
+
*''refInvokeOperation(opName : String, args : Sequence)'' is a reflective operation that enables to invoke the ''self'' operation named ''opName'' with the sequence of parameter contained by ''args''.
+
 
+
=== The ATL Module data type ===
+
The ATL Module data type is specific to the ATL language. This internal data type aims to represent the ATL unit (either a module or a query) that is currently run by the ATL engine. There exists a single instance of this data type, and developers can refer to it (in their ATL code) using the variable ''thisModule''. The ''thisModule'' variable makes it possible to access the [[#Helpers_2|helpers]] and the [[#Attributes|attributes]] that have been declared in the context of the ATL module.
+
 
+
The ATL Module data type also provides the ''resolveTemp'' operation. This specific operation makes it possible to point, from an ATL rule, to any of the target model elements (including non-default ones) that will be generated from a given source model element by an ATL matched rule.
+
 
+
The operation ''resolveTemp'' has the following declaration:
+
resolveTemp(var, target_pattern_name)
+
The parameter var corresponds to an ATL variable that contains the source model element from which the searched target model element is produced. The parameter ''target_pattern_name'' is a string value that encodes the name of the [[#Matched_Rules|target pattern]] element that maps the provided source model element (contained by var) into the searched target model element.
+
 
+
Note that, as it is defined in the scope of the ATL module, this operation must be called from the variable ''thisModule''. The ''resolveTemp'' operation must not be called before the completion of the [[#Module_execution_semantics|matching phase]]. This means that the operation can be called from:
+
*the ''target pattern'' and ''do'' sections of any matched rule;
+
*the ''target pattern'' and ''do'' sections of a called rule, provided that this called rule is executed after the matching phase (e.g. is not called from a transformation entrypoint).
+
 
+
ATL developers may note that the operation call does not specify the matched rule from which the generated target model element comes from. However, as explained in [[#Rules|Section 3.1.1.4]], a source model element should not be matched by more than one matched rule. As a consequence, the concerned matched rule can be derived from the specified source model element.
+
 
+
=== Primitive data types ===
+
OCL defines four basic primitive data types:
+
*the '''Boolean''' data type, for which possible values are ''true'' or ''false'';
+
*the '''Integer''' data type which is associated with the integer numerical values (1, -5, 2, 34, 26524, ...);
+
*the '''Real''' data type which is associated with the floating numerical values (1.5, 3.14, ...);
+
*the '''String''' data type ('To be or not to be', …). A string is defined between '. The escape character ‘\’ enables to include ' characters within handled string variables. Note that, in OCL:
+
**a character is encoded as a one-character string;
+
**the characters composing a string are numbered from 1 to the size of the string.
+
 
+
According to the considered data type (string, numerical values and boolean values), OCL defines a number of specific operations. They are detailed in the following sections along with some additional functions provided by the ATL engine.
+
 
+
==== Boolean data type operations ====
+
 
+
==== String data type operations ====
+
 
+
==== Numerical data type operations ====
+
 
+
==== Examples ====
+
 
+
=== Collection data types ===
+
 
+
==== Operations on collections ====
+
 
+
==== Sequence data type operations ====
+
 
+
==== Set data type operations ====
+
 
+
==== OrderedSet data type operations ====
+
 
+
==== Bag data type operations ====
+
 
+
==== Iterating over collections ====
+
 
+
==== Examples ====
+
 
+
=== Enumeration data types ===
+
 
+
=== Tuple data type ===
+
 
+
=== Map data type ===
+
 
+
=== Model element data type ===
+
 
+
==== Examples ====
+
 
+
== ATL Comments ==
+
 
+
== OCL Declarative Expressions ==
+
 
+
=== If expression ===
+
 
+
=== Let expression ===
+
 
+
=== Other expressions ===
+
 
+
=== Expressions tips & tricks ===
+
 
+
== ATL Helpers ==
+
 
+
=== Helpers ===
+
 
+
=== Attributes ===
+
 
+
=== Limitations ===
+
 
+
== ATL Rules ==
+
 
+
=== ATL imperative code ===
+
 
+
==== The assignment statement ====
+
 
+
==== The if statement ====
+
 
+
==== The for statement ====
+
 
+
==== Current limitations ====
+
 
+
=== Matched Rules ===
+
 
+
==== Source pattern ====
+
 
+
==== Local variables section ====
+
 
+
==== Simple target pattern element ====
+
 
+
==== Iterative target pattern element ====
+
 
+
==== Imperative block section ====
+
 
+
=== Called Rules ===
+
 
+
== ATL Queries ==
+
 
+
== ATL Keywords ==
+
 
+
== ATL Tips & Tricks ==
+
 
+
= The ATL Tools =
+
 
+
== Installation ==
+
 
+
== Perspectives ==
+
 
+
=== ATL perspective ===
+
 
+
==== Navigator ====
+
 
+
==== Editors ====
+
 
+
==== Outline ====
+
 
+
==== Problems ====
+
 
+
==== Properties ====
+
 
+
==== Error Log ====
+
 
+
==== Console ====
+
 
+
=== ATL Debug perspective ===
+
 
+
==== Debug ====
+
 
+
==== Variables ====
+
 
+
==== Breakpoints ====
+
 
+
==== Editors ====
+
 
+
==== Outline ====
+
 
+
==== Console ====
+
 
+
==== Tasks ====
+
 
+
=== AM3 perspective ===
+
 
+
== Programming ATL ==
+
 
+
=== Creating an ATL project ===
+
 
+
=== Designing metamodels with KM3 ===
+
 
+
=== Creating an ATL file ===
+
 
+
==== The ATL File Wizard ====
+
 
+
==== Creating an ATL file from scratch ====
+
 
+
=== Compiling an ATL file ===
+
 
+
=== Setting up an ATL run launch configuration ===
+
 
+
==== The ATL Configuration tab ====
+
 
+
==== The Model Choice tab ====
+
 
+
==== The Common tab ====
+
 
+
=== Running an ATL launch configuration ===
+
 
+
== Debugging ATL ==
+
 
+
=== Managing breakpoints ===
+
 
+
==== Setting/Removing breakpoints ====
+
 
+
==== Activating/Deactivating breakpoints ====
+
 
+
==== Limitations ====
+
 
+
=== Creating an ATL Debug launch configuration ===
+
 
+
=== Running an ATL Debug launch configuration ===
+
 
+
=== Debugging actions ===
+
 
+
=== Displaying variables values ===
+
 
+
= Additional ATL Resources =
+
ATL developers, beginner as confirmed ones, should find in the present manual answers to most of the problems they may encounter while either programming ATL modules or interacting with the ATL development environment. However, there exist a number of additional ATL resources that provide detailed information on specific aspects of ATL. This section provides the ATL developers with a list of these available ATL resources.
+
 
+
Before starting using the ATL tools, developers are encouraged to consult the ATL Installation Guide [16]. This guide describes the step-by-step procedures corresponding to the different available installation modes (e.g., from source code or binaries).
+
 
+
After having installed ATL for the first time, beginner developers may feel a little bit confused with the different concepts and technologies on which ATL relies on. The ATL Starter’s Guide [12] has been designed for these beginner developers: it presents the step-by-step design of a very simple ATL transformation. It progressively introduces, in this scope, the different functionalities of the ATL IDE.
+
 
+
A number of ATL transformation examples, from varied fields (such as build tools, bug tracking systems, etc.), are available on the GMT web site [17]. This set of transformations illustrates the use of the different ATL capabilities. They can be executed as standalone transformations, but also be integrated in larger transformation chains. Also available from the GMT web site, the Atlantic Zoo provides a collection of more than one hundred metamodels specified by means of the KM3 textual notation. These metamodels can be used for the design of new ATL transformations.
+
 
+
Note that a specific template has been designed to provide a standard scheme for the description of transformations [20]. Developers sharing the transformations they develop are strongly encouraged to use this template to specify their transformations.
+
 
+
Available ATL documentation also includes the specification of the ATL virtual machine [21]. This specification details the set of instructions on which the ATL virtual machine implemented by the ATL IDE is based. It also describes the way the ATL compiler generates the ATL bytecode contained in ASM file from the code specified in .atl files. This specification can be used as a reference for developers that are interested in developing an alternative ATL engine.
+
 
+
The KM3 user manual [14] provides an overview of the Kernel MetaMetaModel language. KM3 is a textual notation dedicated to the specification of metamodels. This user manual describes both the language textual syntax and its semantics.
+
 
+
Finally, there exists an ATL discussion board [22] enabling the ATL community to share information about the ATL language and its dedicated development environment. This board is in particular used to announce the new ATL releases.
+
 
+
= Conclusion =
+
 
+
TODO check relevance
+
 
+
This manual introduces both the ATL transformation language and the development environment that was designed for it. In a first part, the document proposes a brief overview of the model transformation area in which it introduces the model transformation concepts that are used in the rest of the manual. In a second part, it provides the complete reference of the ATL language, describing the syntactic structure of the different types of ATL units (e.g., ATL modules, queries and libraries). It also provides a comprehensive overview of the execution semantics of these different units. The last part of this manual was dedicated to the description of the ATL development environment.
+
 
+
The reader may have note that both the ATL language and its associated development environment still suffer from some limitations. As an example, the ATL compiler does not enable developers to define helpers or attributes in the context of a collection type. In the same way, the provided debugger does not allow developers to navigate the content of the attributes defined in the context of the ATL module. There however exist some on-going development efforts that aim to correct know problems and limitations of both the language and its development environment. Further developments will also provide new functionalities, in particular by extending the capabilities of the AM3 (ATL MegaModel Management) component. ATL developers are therefore encouraged to keep aware of the ATL actuality by means of the ATL discussion board. New releases of versions, of resources (transformation examples, metamodels, etc.) and documentations are therefore prioritary announced onto this dedicated discussion board.
+
 
+
= References =
+
 
+
TODO replace in text by direct links if necessary
+
 
+
<span id="r1">[1]</span>
+
OMG/MOF Meta Object Facility (MOF) 1.4. Final Adopted Specification Document. formal/02-04-03, 2002.
+
 
+
<span id="r2">[2]</span>
+
OMG/RFP/QVT MOF 2.0 Query/Views/Transformations RFP. October 2002.
+
 
+
<span id="r3">[3]</span>
+
Allilaire, F., Idrissi, T. ADT: Eclipse Development Tools for ATL. EWMDA-2, Kent, September 2004.
+
 
+
<span id="r4">[4]</span>
+
Budinsky, F., Steinberg, D., Ellersick, R., Grose, T. Eclipse Modeling Framework, Chapter 5 ”Ecore Modeling Concepts”. Addison Wesley Professional. ISBN: 0131425420, 2004.
+
 
+
<span id="r5">[5]</span>
+
Budinsky, F., Steinberg, D., Ellersick, R., Grose, T. Eclipse Modeling Framework. Addison Wesley Professional. ISBN: 0131425420, 2004.
+
 
+
<span id="r6">[6]</span>
+
The ATL Book to Publication transformation. Available at http://www.eclipse.org/gmt/atl/atlTransformations/.
+
 
+
<span id="r7">[7]</span>
+
OMG/OCL Object Constraint Language (OCL) 2.0. OMG Final Adopted Specification. ptc/03-10-14, 2003.
+
 
+
<span id="r8">[8]</span>
+
Java regular expressions. Available at http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html#sum.
+
 
+
<span id="r9">[9]</span>
+
Java Map interface. Available at http://java.sun.com/j2se/1.4.2/docs/api/java/util/Map.html.
+
 
+
<span id="r10">[10]</span>
+
The ATL EMF to KM3 transformation. Available at http://www.eclipse.org/gmt/atl/atlTransformations/.
+
 
+
<span id="r11">[11]</span>
+
The Eclipse project. http://www.eclipse.org/.
+
 
+
<span id="r12">[12]</span>
+
The ATL Starter’s Guide. Available at http://www.eclipse.org/gmt/atl/doc/.
+
 
+
<span id="r13">[13]</span>
+
The netbeans Metadata Repository (MDR) project. http://mdr.netbeans.org/.
+
 
+
<span id="r14">[14]</span>
+
The Kernel MetaMetaModel (KM3) Manual. Available at http://www.eclipse.org/gmt/atl/doc/.
+
 
+
<span id="r15">[15]</span>
+
The Atlas MegaModel Management project. http://www.eclipse.org/gmt/am3/.
+
 
+
<span id="r16">[16]</span>
+
The ATL Installation Guide. Available at http://www.eclipse.org/gmt/atl/doc/.
+
 
+
<span id="r17">[17]</span>
+
The Generative Model Transformer (GMT) project. http://eclipse.org/gmt/.
+
 
+
<span id="r18">[18]</span>
+
Gentleware. Poseidon for UML. Available at http://gentleware.com/index.php.
+
 
+
<span id="r19">[19]</span>
+
OMG/XMI XML Model Interchange (XMI) OMG Document AD/98-10-05, October 1998.
+
 
+
<span id="r20">[20]</span>
+
The ATL transformation description template. Available at http://www.eclipse.org/gmt/atl/doc/.
+
 
+
<span id="r21">[21]</span>
+
Specification of the ATL Virtual Machine. Available at http://www.eclipse.org/gmt/atl/doc/.
+
 
+
<span id="r22">[22]</span>
+
The ATL mailing list. http://groups.yahoo.com/group/atl_discussion/.
+
 
+
 
+
= Appendix A - The MMAuthor metamodel =
+
 
+
= Appendix B - The MMPerson metamodel =
+
 
+
= Appendix C - The Biblio metamodel =
+
 
+
= Appendix D - The Table metamodel =
+

Latest revision as of 12:17, 10 February 2010

Back to the top