Types have a simple Name (e.g. String) and an optional namespace used to distingish between two types with the same name (e.g. my::metamodel). The delimiter for name space fragments is a double colon „::“. A fully qualified name looks like this:

my::fully::qualified::MetaType

The namespace and name used by a specific type is defined by the corresponding MetaModel implementation. The EmfMetaModel, for instance, maps EPackages to namespace and EClassifiers to names. Therefore, the name of the Ecore element EClassifier is called:

ecore::EClassifier

If you don't want to use namespaces (for whatever reason), you can always implement your own metamodel and map the names accordingly.

The built-in type system also contains the following collection types: Collection, List and Set. Because the expressions language is statically type checked and we don't like casts and ClassCastExceptions, we introduced the concept of parameterized types. The typesystem doesn't support full featured generics, because we don't need them.

The syntax is:

Collection[my::Type] 
List[my::Type] 
Set[my::Type] 

Each type offers features. The type (resp. the metamodel) is responsible for mapping the features. There are three different kinds of features:

Properties are straight forward: They have a name and a type. They can be invoked on instances of the corresponding type. The same is true for Operations. But in contrast to properties, they can have parameters. StaticProperties are the equivalent to enums or constants. They must be invoked statically and they don't have parameters.

Object defines a couple of basic operations, like equations. Every type has to extend Object!

The Void type can be specified as the return type for operations, although it's not recommended, because whenever possible expressions should be free of side effects whenever possible.

The type system doesn't have a concept data type. Data types are just types. As in OCL, we support the following types: String, Boolean, Integer, Real.

The type system has three different Collection types. Collection is the base type, it provides several operations known from java.util.Collection. The other two types (List, Set) correspond to their java.util equivalents, too.

The type system describes itself, hence, there are types for the different concepts. These types are needed for reflective programming. To avoid confusion with meta types with the same name (it's not unusual to have a meta type called Operation, for instance) we have prefixed all of the types with the namespace oaw. We have:

For instance, if you want to have the following JavaBean act as a Metatype (i.e. Your model contains instances of the type):

public class Attribute { 
   private String name; 
   private String type; 
   public String getName() { 
      return name; 
   } 
   public void setName(String name) { 
      this.name = name; 
   } 
   public String getType() { 
      return type; 
   }
   public void setType(String type) { 
      this.type = type; 
   } 
} 

You need to use the JavaMetaModel implementation which uses the ordinairy Java reflection layer in order to map access to the model.

So if you have the following expression in e.g. Xpand:

myattr.name.toFirstUpper()

and myattr is the name of a local variable pointing to an instance of Attribute. The oaw typesystem asks the metamodel implementations if they 'know' a type for the instance of Attribute. If you have the JavaMetaModel registered it will return an oaw::Type which maps to the underlying Java class. When the type is asked if it knows a property 'name', and it will inspect the Java class using the Java reflection API.

The JavaMetaModel implementation shipped with oaw can be configured with a strategy [GOF95-Pattern] in order to control or change the mapping. For instance, the JavaBeansStrategy maps getter and setter methods to simple properties, so we would use this strategy for the example above.

You should know that for each Metamodel implementation you use at runtime, you need to have a so called MetamodelContributor extension for the plugins to work with. If you just use one of the standard Metamodel implementations (EMF, UML2 or Java) you don't have to worry about it, since oaw is shipped with respective MetamodelContributors (see the corresponding docs for details). If you need to implement your own MetamodelContributor you should have a look at the Eclipse plug-in reference doc.

You need to configure your oaw language components with the respective metamodel implementations.

A possible configuation of the Xpand2 generator component looks like this:

<component class="oaw.xpand2.Generator"> 
   <metaModel class="oaw.type.emf.EmfMetaModel"> 
      <metaModelPackage value="my.generated.MetaModel1Package"/> 
   </metaModel> 
   <metaModel class="oaw.type.emf.EmfMetaModel"> 
      <metaModelFile value="my/java/package/metamodel2.ecore"/> 
   </metaModel> 
   ... 
</component> 

In this example the EmfMetaModel implementation is configured two times. This means that we want to use two metamodels at the same time, both based on EMF. The metaModelPackage property is a property that is specific to the EmfMetaModel (located in the core.emftools project). It points to the generated EPackage interface. The second metamodel is configured using the ecore file. You don't need to have a generated Ecore model for oaw in order to work. The EmfMetaModel works with dynamic EMF models just as it works with generated EMF models.

There are naturally no literals for object, but we have two operators:

equals:

obj1 == obj2

not equals:

obj1 != obj2

The only possible instance of Void is the null reference. Therefore, we have one literal:

null

The literal for types is just the name of the type (no '.class' suffix, etc.). Example:

String // the type string 
my::special::Type // evaluates to the type 'my::special::Type'

The literal for static properties (aka enum literals) is correlative to type literals:

my::Color::RED

There are two different literal syntaxes (with the same semantics):

S'a String literal' 
"a String literal" // both are okay

For Strings the expression sub-language supports the plus operator that is overloaded with concatenation:

'my element '+ ele.name +' is really cool!'

Note, that multi-line Strings are supported.

The boolean literals are:

true
false

Operators are:

true && false // AND 
true || false // OR 
! true        // NOT 

The syntax for integer literals is as expected:

// integer literals 
3 
57278 
// real literals 
3.0 
0.75 

Additionally, we have the common arithmetic operators:

3 + 4  // addition 
4 – 5  // subtraction 
2 * 6  // multiplication 
3 / 64 // divide 
// Unary minus operator 
- 42 
- 47.11 

Furthermore, the well known compare operators are defined:

4 > 5 // greater than 
4 < 5 // smaller than 
4 >= 23 // greater equals than 
4 <= 12 // smaller equals than

There is a literal for lists:

{1,2,3,4} // a list with four integers

There is no other special concrete syntax for collections. If you need a set, you have to call the toSet() operation on the list literal:

{1,2,4,4}.toSet() // a set with 3(!) integers

Sometimes an expression yields a large collection, but onje is only interested in a special subset of the collection. The expression sub-language has special constructs to specify a selection out of a specific collection. These are the select and reject operations. The select specifies a subset of a collection. A select is an operation on a collection and is specified as follows:

collection.select( v | boolean-expression-with-v ) 

Select returns a sublist of the specified collection. The list contains all elements for which the evaluation of boolean-expression-with-v results in true. Example:

{1,2,3,4}.select(i|i>=3) // returns {3,4}

A special version of a select expression is typeSelect. Rather than providing a boolean expression a class name is here provided.

collection.typeSelect( classname ) 

typeSelect returns that sublist of the specified collection, that contains only objects which are an instance of the specified class (also inherited).

The reject operation is similar to the select operation, but with reject we get the subset of all the elements of the collection for which the expression evaluates to false. The reject syntax is identical to the select syntax:

collection.reject( v | boolean-expression-with-v )

Example:

{1,2,3,4}.reject(i|i>=3) // returns {1,2}

As shown in the previous section, the select and reject operations always result in a sub- collection of the original collection. Sometimes one wants to specify a collection which is derived from another collection, but which contains objects not in the original collection (it is not a sub-collection), we can use a collect operation. The collect operation uses the same syntax as the select and reject and is written like this:

collection.collect( v | expression-with-v )

collect again iterates over the target collection and evaluates the given expression on each element. In contrast to select, the evaluation result is collected in a list. When an iteration is finished the list with all results is returned. Example:

namedElements.collect(ne|ne.name) // returns a list of strings 

As navigation through many objects is very common, there is a shorthand notation for collect that makes the expressions more readable. Instead of

self.employee.collect(e|e.birthdate) 

one can also write:

self.employee.birthdate

In general, when a property is applied to a collection of Objects, it will automatically be interpreted as a collect over the members of the collection with the specified property.

The syntax is a shorthand for collect, if the feature does not return a collection itself. But sometimes we have the following:

self.buildings.rooms.windows // returns a list of windows

This syntax works, but one cannot express it using the collect operation in an easy way.

Often a boolean expression has to be evaluated for all elements in a collection. The forAll operation allows specifying a Boolean expression, which must be true for all objects in a collection in order for the forAll operation to return true:

collection.forAll( v | boolean-expression-with-v )

The result of forAll is true if boolean-expression-with-v is true for all the elements contained in a collection. If boolean-expression-with-v is false for one or more of the elements in the collection, then the forAll expression evaluates to false.

Example:

{3,4,500}.forAll(i|i<10) // evaluates to false (500 < 5 is false)

Often you will need to know whether there is at least one element in a collection for which a boolean is true. The exists operation allows you to specify a Boolean expression which must be true for at least one object in a collection:

collection.exists( v | boolean-expression-with-v )

The result of the exists operation is true if boolean-expression-with-v is true for at least one element of collection. If the boolean-expression-with-v is false for all elements in collection, then the complete expression evaluates to false.

Example:

{3,4,500}.exists(i|i<10) // evaluates to true (e.g. 3 < 5 is true)

If you want to sort a list of elements, you can use the higher order function sortBy. The list you invoke the sortBy operation on is sorted by the results of the given expression.

Example:

myListOfEntity.sortBy(entity|entity.name)

In the example the list of entities is sorted by the name of the entities. Note that there is no such Comparable type in oaw. If the values returned from the expression are instances of java.util.Comparable the compareTo method is used, otherwise toString() is invoked and the the result is used.

More Examples - the following expression return true:

{'C','B','A'}.sortBy(e|e) == {'A','B','C'} 
{'AAA','BB','C'}.sortBy(e|e.length) == {'C','BB','AAA'} 
{5,3,1,2}.sortBy(e|e) == {1,2,3,5} 
{5,3,1,2}.sortBy(e|e-2*e) == {5,3,2,1} 
... 

Each workflow component using the expression framework (Xpand, Check and Xtend) can be configured with global variables. Here is an example:

<workflow> 
   .... stuff 
   <component class=“oaw.xpand2.Generator“> 
      ... usual stuff (see ref doc) 
      <globalVarDef name=“MyPSM“ value=“slotNameOfPSM“/> 
      <globalVarDef name=“ImplClassSuffix“ value=“'Impl'“/> 
   </component> 
</workflow>

If you have injected global variables into the respective component, you can call them using the following syntax:

GLOBALVAR ImplClassSuffix

Note, we don't have any static typeinformation. Therefore Object is assumed. So you have to down cast the global var to the intended type:

((String) GLOBALVAR ImplClassSuffix)

It is good practice to type it once, using an Extension and then always refer to that extension:

String implClassSuffix() : GLOBALVAR ImplClassSuffix; 
// usage of the typed global var extension 
ImplName(Class c) : 
   name+implClassSuffix();

If you want to export extensions from another extension file together with your local extensions, you can add the keyword 'reexport' to the end of the respective extension import statement.

extension fully::qualified::ExtensionFileName reexport;

There are two different ways of how to invoke an extension. It can be invoked like a function:

getterName(myNamedElement)

The other way to invoke an extension is through the "member syntax":

myNamedElement.getterName()

For any invocation in member syntax, the target expression (the member) is mapped to the first parameter. Therefore, both syntax forms do the same thing.

It's important to understand that extensions are not members of the type system, hence, they are not accessible through reflection and you cannot specialize or overwrite operations using them.

The expression evaluation engine first looks for an appropriate operation before looking for an extension, in other words operations have higher precedence.

For most extensions, you don't need to specify the return type, because it can be derived from the specified expression. The special thing is, that the static return type of such an extension depends on the context of use!

For instance, if you have the following extension

asList(Object o): {o};

the invocation of

asList('text')

has the static type List[String]. This means you can call

asList('text').get(0).toUpperCase()

The expression is statically type safe!

There is always a return value, whether you specify it or not, even if you specify explicitely 'Void'.

See the following example.

modelTarget.ownedElements.addAllNotNull(modelSource.contents.duplicate())

In this example duplicate() dispatches polymorphicly. Two of the extentions might look like:

Void duplicate(Realization realization):
   realization.Specifier().duplicate()->
   realization.Realizer().duplicate()
;

create target::Class duplicate(source::Class):
   ...
;

If a 'Realisation' is contained in the 'contents' list of 'modelSource', the 'Realizer' of the 'Realization' will be added to the 'ownedElements' list of the 'modelTarget'. If you do not want to add in the case that the contained element is a 'Realization' you might change the extention to:

Void duplicate(Realization realization):
   realization.Specifier().duplicate()->
   realization.Realizer().duplicate() ->
   {}
;

There is only one exception: For recursive extensions the return type cannot be inferred, therefore you need to specify it explicitely:

String fullyQualifiedName(NamedElement n) : n.parent == null ? n.name :
   fullyQualifiedName(n.parent)+'::'+n.name
;

Recursive extensions are non-deterministic in a static context, therefore it is necessary to specify a return type.

If you call an extension without side effects very often, you would like to cache the result for each set of parameters, in order improve the performance. You can just add the keyword 'cached' to the extension in order to acieve this:

cached String getterName(NamedElement ele) :
   'get'+ele.name.firstUpper()
;

The getterName will be computed only once for each NamedElement.

By default all extensions are public, i.e. they are visible from outside the extension file. If you want to hide extensions you can add the keyword 'private' in front of them:

private internalHelper(NamedElement ele) : 
   // implementation....
;

AOP is basically about weaving code into different points inside the call graph of a software module. Such points are called Join Points. In Xtend the join points are the extenion invocations (Note that Xpand offers a simliar feature, see the Xpand documentation).

One specifies on which join points the contributed code should be executed by specifying something like a 'query' on all available join points. Such a query is called a point cut.

around [pointcut] :
   expression;

A pointcut consists of a fully qualified name and a list of parameter declarations.

my::Extension::definition // extensions with the specified name
org::oaw::* //extensions prefixed with 'org::oaw::'
*Operation* // extensions containing the word 'Operation' in it.
* // all extensions

my::Templ::extension() // extension without parameters
my::Templ::extension(String s) // extension with exactly one parameter of type String
my::Templ::extension(String s,*) // templ def with one or more parameters, 
                                 // where the first parameter is of type String
my::Templ::extension(*) // templ def with any number of parameters

To weave the defined advices into the different join points you need to configure the XtendComponent with the qualified names of the Extension files containing the advices.

Example:

<component class="oaw.xtend.XtendComponent">
   <metaModel class="oaw.type.emf.EmfMetaModel">
      <metaModelFile value="metamodel1.ecore"/>
   </metamodel>
   <metaModel class="oaw.type.emf.EmfMetaModel">
      <metaModelFile value="metamodel2.ecore"/>
   </metaModel>

   <invoke value="my::example::Trafo::transform(inputSlot)"/>
      <outputSlot value="transformedModel"/>
   <value="my::Advices,my::Advices2"/>
</component>

This example uses Eclipse EMF as the basis for model-to-model transformations.It builds on the emfExample documented elsewhere. Please read and install the emfExample first.

The idea in this example is to transform the data model introduced in the EMF example into itself. This might seem boring, but the example is in fact quite illustrative.

By now you should know the role and structure of workflow files. Therefore, the interesting aspect of the workflow file below is the XtendComponent.

<workflow>
   <property file="workflow.properties"/>
      ...
   <component class="oaw.xtend.XtendComponent">
      <metaModel class="oaw.type.emf.EmfMetaModel">
         <metaModelPackage value="data.DataPackage"/>
      </metaModel>
      <invoke value="test::Trafo::duplicate(rootElement)"/>
      <outputSlot value="newModel"/>
   </component>
   ...
</workflow>

As usual, we have to define the metamodel that should be used, and since we want to transform a data model into a data model, we need to specify only the data.DataPackage as the metamodel.

We then specify which function to invoke for the transformation. The statement test::Trafo::duplicate(rootElement) means to invoke:

The transformation, as mentioned above, can be found in the Trafo.ext file in the test package in the src folder. Let's walk through the file.

So, first we import the metamodel.

import data;

The next function is a so-called create extension. Create extensions, as a sideeffect when called, create an instance of the type given after the create keyword. In our case, the duplicate function creates an instance of DataModel. This newly created object can be referrred to in the transformation by this (which is why this is specified behind the type). Since this can be ommitted, we don't have to mention it explicitly in the transformation.

The function also takes an instance of DataModel as its only parameter. That object is referred to in the transformation as s. So, this function sets the name of the newly created DataModel to be the name of the original one, and then adds duplicates of all entities of the original one to the new one. To create the duplicates of the entities, the duplicate() operation is called for each Entity. That is the next function in the transformation.

create DataModel this duplicate(DataModel s):
   entity.addAll( s.entity.duplicate() ) ->
   setName(s.name);

The duplication function for Entities is also a create Extension, this time it creates a new Entity for each old Entity passed in. Again, it copies the name and adds duplicates of the attributes and references to the new one.

create Entity this duplicate(Entity old):
   attribute.addAll( old.attribute.duplicate() ) ->
   reference.addAll( old.reference.duplicate() ) ->
   setName( old.name );

The function that copies the attribute is rather straight forward, .... but ...

create Attribute this duplicate(Attribute old):
   setName( old.name ) ->
   setType( old.type );

... the one for the references is more interesting. Note that a reference, while being owned by some Entity, also references another Entity as its target. So how do you make sure you don't duplicate the target twice? Xtend provides explicit support for this kind of situation. Create extensions are only executed once per tuple of parameters! So if, for example, the Entity behind the target reference had already been duplicated by calling the duplicate function with the respective parameter, the next time it will be called the exact same object will be returned. This is very useful for graph transformations.

create EntityReference this duplicate(EntityReference old):
   setName( old.name ) ->
   setTarget( old.target.duplicate() );

For more information about the Xtend language please see the Xtend Reference documentation.

If you are tired of always typing the fully qualified names of your types and definitions, you can import a namespace using the IMPORT statement.

«IMPORT meta::model»

This one imports the namespace meta::model. If your template contains such a statement, you can use the unqualified names of all types and template files contained in that namespace. This is similar to a Java import statement import meta.model.*.

Metamodels are typically described in a structural way (graphical, or hierarchical, etc.) . A shortcoming of this, is that it's difficult to specify additional behaviour (query operations, derived properties, etc.). Also, it's a good idea not to pollute the meta model, with target platform specific information (e.g. Java type names, packages, getter and setter names, etc.).

Extensions provide a flexible and convenient way of defining additional features of meta classes. You do this by using the Extend language. (See the corresponding reference documentation for details)

An EXTENSION import points to the Extend file containing the required extensions:

«EXTENSION my::ExtensionFile»

Note that extension files have to reside on the Java classpath, too. Therefore they use the same namespace mechanism (and syntax) as types and template files.

The central concept of Xpand is the DEFINE block, also called a template. This is the smallest identifiable unit in a template file. The tag consists of a name, an optional comma separated parameter list as well as the name of the meta model class for which the template is defined.

«DEFINE templateName(formalParameterList) FOR MetaClass»
   a sequence of statements
«ENDDEFINE»

To some extent templates can be seen as special methods of the meta class – there is always an implicit this parameter which can be used to address the "underlying" model element; in our example above, this model element is "MetaClass".

As in Java a formal parameter list entry consists of the type followed by the name of that parameter.

The body of a template can contain a sequence of other statements including any text.

A full parametric polymorphism is available for templates. If there are two templates with the same name that are defined for two meta classes which inherit from the same super class, Xpand will use the corresponding subclass template in case the template is called for the super class. Vice versa the super class’s template would be used in case a subclass template is not available. Note that this not only works for the target type, but for all parameters. Technically, the target type is handled as the first parameter.

So, assume you have the following metamodel:

Figure 43. Sample metamodel

Assume further, you'd have a model which contains a collection of A, B and C instances in the property listOfAs. You can then write the following template:

«DEFINE someOtherDefine FOR SomeMetaClass»
   «EXPAND implClass FOREACH listOfAs»
«ENDDEFINE»

«DEFINE implClass FOR A»
   // this is the code generated for the super class A
«ENDDEFINE»

«DEFINE implClass FOR B»
   // this is the code generated for the subclass B
«ENDDEFINE»

«DEFINE implClass FOR C»
   // this is the code generated for the subclass C
«ENDDEFINE»

So for each B in the list, the template defined for B is executed, for each C in the collection the template defined for C is invoked, and for all others (which are then instances of A) the default template is executed.

The FILE statement redirects the output generated from its body statements to the specified target.

«FILE expression [outletName]»
   a sequence of statements
«ENDFILE»

The target is a file in the file system whose name is specified by the expression (relative to the specified target directory for that generator run). The expression for the target specification can be a concatenation (using the + operator). Additionally you can specify an identifier (a legal Java identifier) for the name of the outlet. (See the configuration section for a description of outlets).

The body of a FILE statement can contain any other statements. Example:

«FILE InterfaceName + ".java"»
   package «InterfacePackageName»;

   /* generated class! Do not modify! */
   public interface «InterfaceName» {
      «EXPAND Operation::InterfaceImplementation FOREACH 	Operation»
   }
«ENDFILE»


«FILE ImplName + ".java" MY_OUTLET»
   package «ImplPackageName»;

   public class «ImplName» extends «ImplBaseName»
                           implements «InterfaceName» {
   //TODO: implement it		
   }
«ENDFILE»

The EXPAND statement "expands" another DEFINE block (in a separate variable context), inserts its output at the current location and continues with the next statement. This is similar in concept to a subroutine call.

«EXPAND definitionName [(parameterList)]
   [FOR expression | FOREACH expression [SEPARATOR expression] ]»

The various alternative syntaxes are explained below.

«EXPAND TemplateFile::definitionName FOR myModelElement»

«IMPORT my::templates»
...
«EXPAND TemplateFile::definitionName FOR myModelElement»

«EXPAND my::templates::TemplateFile::definitionName 
        FOR myModelElement»

If FOR or FOREACH is omitted the other template is called FOR this.

«EXPAND TemplateFile::definitionName»

equals

«EXPAND TemplateFile::definitionName FOR this»

If FOR is specified, the definition is executed for the result of the target expression.

«EXPAND myDef FOR entity»

If FOREACH is specified, the target expression must evaluate to a collection type. The other definition is executed for each element of that collection.

«EXPAND myDef FOREACH entity.allAttributes»	

«EXPAND paramTypeAndName FOREACH params SEPARATOR ”,”»

This statement expands the body of the FOREACH block for each element of the target collection that results from the expression. The current element is bound to a variable with the specified name in the current context.

«FOREACH expression AS variableName [ITERATOR iterName] [SEPARATOR expression]»
   a sequence of statements using variableName to access the 
   current element of the iteration
«ENDFOREACH»

The body of a FOREACH block can contain any other statements; specifically FOREACH statements may be nested. If ITERATOR name is specified, an object of the type xpand2::Iterator (see API doc for details) is accessible using the specified name. The SEPARATOR expression works in the same way as the one for EXPAND.

Example:

«FOREACH {'A','B','C'} AS c ITERATOR iter SEPARATOR ','»
   «iter.counter1» : «c»
«ENDFOREACH»

The evaluation of the above statement results in the following text:

1 : A,
2 : B,
3 : C

The IF statement supports conditional expansion. Any number of ELSEIF statements are allowed. The ELSE block is optional. Every IF statement must be closed with an ENDIF. The body of an IF block can contain any other statement, specifically, IF statements may be nested.

«IF expression»
   a sequence of statements
[ «ELSEIF expression» ]
   a sequence of statements ]
[ «ELSE»
   a sequence of statements ]
«ENDIF»

Protected Regions are used to mark sections in the generated code that shall not be overridden again by the subsequent generator run. These sections typically contain manually written code.

«PROTECT CSTART expression CEND expression ID expression (DISABLE)?»
   a sequence of statements
«ENDPROTECT»

The values of CSTART and CEND expressions are used to enclose the protected regions marker in the output. They should build valid comment beginning and end strings corresponding to the generated target language (e.g. "/*" and "*/" for Java). The following is an example for Java:

«PROTECT CSTART „/*“ CEND „*/“ ID ElementsUniqueID»
   here goes some content
«ENDPROTECT»

The ID is set by the ID expression and must be globally unique (at least for one complete pass of the generator).

Generated target code looks like this:

public class Person {
/*PROTECTED REGION ID(Person) ENABLED START*/
   this pr is enabled, therefore the contents will always be
   preserved. If you want to get the default contents from the
   template you must remove the ENABLED keyword (or even remove 
   the whole file :-))
/*PROTECTED REGION END*/
}

Protected regions are generated in enabled state by default. Unless you manually disable them, by removing the ENABLED keyword, they will always be preserved.

If you want the generator to generate disabled protected regions, you need to add the DISABLE keyword inside the declaration:

«PROTECT CSTART '/*' CEND '*/' ID this.name DISABLE»

LET lets you specify local variables. :-)

«LET expression AS variableName»
   a sequence of statements
«ENDLET»

During the expansion of the body of the LET block, the value of the expression is bound to the specified variable. Note that the expression will only be evaluated once, independent from the number of usages of the variable within the LET block. Example:

«LET packageName + "." + className AS fqn»
   the fully qualified name is: «fqn»;
«ENDLET»

The ERROR statement aborts the evaluation of the templates by throwing an XpandException with the specified message.

«ERROR expression»

Note that you should use this facility very sparingly, since it is better practice to check for invalid models using constraints on the metamodel, and not in the templates.

Comments are only allowed outside of tags.

«REM»
   text comment
«ENDREM»

Comments may not contain a REM tag, this implies that comments are not nestable. A comment may not have a white space between the REM keyword and its brackets. Example:

«REM»«LET expression AS variableName»«ENDREM»
   a sequence of statements
«REM»  «variableName.stuff»
«ENDLET»«ENDREM»

Expressions support processing of the information provided by the instantiated meta model. Xpand provides powerful expressions for selection, aggregation, and navigation. Xpand uses the expressions sub language in almost any statement that we have seen so far. The expression statement just evaluates the contained expression and writes the result to the output (using java.lang.Object's toString() method). Example:

public class «this.name» {

All expressions defined by the oAW expressions sub language are also available in Xpand. You can invoke imported extensions. (See the Expressions and Extend Language Reference for more details).

If you want to omit the output of superfluous whitespace you can add a minus sign just before any closing bracket. Example:

«FILE InterfaceName + ".java"-»
«IF hasPackage-»
package «InterfacePackageName»;
«ENDIF-»
...
«ENDFILE»

The generated file would start with two new lines (one after the FILE and one after the IF statement) if the minus characters had not been set.

In general: If a statement (or comment) ends with such a minus all preceding whitespace up to the newline character (excluded!) is removed. Additionally all following whitespace including the first newline character (\r\n is handled as one character) is also removed.

AOP is basically about weaving code into different points inside the call graph of a software module. Such points are called Join Points. In Xpand there is only one join point so far: a call to a definition.

You specify on which join points the contributed code should be executed by specifying something like a 'query' on all available join points. Such a query is called a point cut.

«AROUND [pointcut]»
   do stuff
«ENDAROUND»

A pointcut consists of a fully qualified name, parameter types and the target type.

my::Template::definition // definitions with the specified name
org::oaw::* // definitions prefixed with 'org::oaw::'
*Operation* // definitions containing the word 'Operation' in it.
*           // all definitions

my::Templ::def() // templ def without parameters
my::Templ::def(String s) // templ def with exactly one parameter
                         // of type String
my::Templ::def(String s,*) // templ def with one or more parameters,
                           // where the first parameter is of type String
my::Templ::def(*) // templ def with any number of parameters

my::Templ::def() FOR Object// templ def for any target type
my::Templ::def() FOR Entity// templ def objects of type Entity

Inside an advice you might want to call the underlying definition. This can be done using the implicit variable targetDef, which is of the type xpand2::Definition and provides an operation proceed() which invokes the underlying definition with the original parameters (Note that you might have changed any mutable object in the advice before).

If you want to control what parameters are to be passed to the definition you can use the operation proceed(Object target, List params). There is no type checking here!

Additionally there are some inspection properties (like name, paramTypes, etc.) available.

The first thing to note, is that the qualified Java name of the component is org.openarchitectureware.xpand2.Generator2. One can use the shortcut oaw instead of a preceding org.openarchitectureware. The workflow engine will resolve it.

For Xpand it's important to have the file encoding in mind, because of the guillemet characters used to delimit keywords and property access. The fileEncoding property specifies the file encoding to use for reading the templates, reading the protected regions and writing the generated files. This property defaults to the default file encoding of your JVM.

The property metaModel is used to tell the generator engine on which metamodels the xpand templates should be evaluated. One can specify more than one metamodel here. Metamodel implementations are required by the expression framework (see Expression Language Reference) used by Xpand2. In the example above we configured the Ecore metamodel using the EMFMetaModel implementation shipped with the core part of the openArchitectureWare 4 release.

A mandatory configuration is the expand property. It expects a syntax similar to that of the EXPAND statement (described above). The only difference is that we omit the EXPAND keyword because we write it as the property's name. Examples:

<expand value="Template::define FOR mySlot"/>

or:

<expand value="Template::define('foo') FOREACH {mySlot1,mySlot2}"/>

The expressions are evaluated using the workflow context. Each slot is mapped to a variable. For the examples above the workflow context needs to contain elements in the slots 'mySlot', 'mySlot1' and 'mySlot2'. It's also possible to specify some complex expressions here. If, for instance, the slot myModel contains a collection of model elements one could write:

<expand value="Template::define FOREACH myModel.typeSelect(Entity)"/>

This selects all elements of type Entity contained in the collection stored in the myModel slot.

The second mandatory configuration is the specification of so called outlets (a concept borrowed from AndroMDA). Outlets are responsible for writing the generated files to disk . Example:

<component class="oaw.xpand2.Generator2">
   ...
   <outlet path='main/src-gen'/>
   <outlet name='TO_SRC' path='main/src' overwrite='false'/>
   ...
</component>

In the example there are two outlets configured. The first one has no name and is therefore handled as the default outlet. Default outlets are triggered by omitting an outlet name:

«FILE 'test/note.txt'»
# this goes to the default outlet
«ENDFILE»

The configured base path is 'main/src-gen', so the file from above would go to 'main/src-gen/test/note.txt'.

The second outlet has a name ('TO_SRC') specified. Additionally the flag overwrite is set to false (defaults to true). The following Xpand fragment

«FILE 'test/note.txt' TO_SRC»
# this goes to the TO_SRC outlet
«ENDFILE»

would cause the generator to write the contents to 'main/src/test/note.txt' if the file does not already exist (the overwrite flag).

Another option called append (defaults to false) causes the generator to append the generated text to an existing file. If overwrite is set to false this flag has no effect.

Beautifying the generated code is a good idea. It's very important, that generated code look good, because developers should be able to understand it. On the other hand template files should look good, too. It is thus best practice to write nice looking template files and not to care how the generated code looks – and then you run a beautifier over the generated code to fix that problem. Of course, if a beautifier is not available, or if white space has syntactical meaning (as in Python), you would have to write your templates with that in mind (using the minus character before closing brackets as described in a preceding section).

The Xpand workflow component can be configured with multiple beautifiers:

<beautifier
   class="org.openarchitectureware.xpand2.output.JavaBeautifier"/>
<beautifier
   class="org.openarchitectureware.xpand2.output.XmlBeautifier"/>

These are the two beautifiers delivered with Xpand. If you want to use your own beautifier, you would just need to implement the following Java interface:

package org.openarchitectureware.xpand2.output;

public interface PostProcessor {
   public void beforeWriteAndClose(FileHandle handle);
   public void afterClose(FileHandle handle);
}

The beforeWriteAndClose method is called for each ENDFILE statement.

Finally you need to configure the protected region resolver, if you want to use protected regions.

<prSrcPaths value="main/src"/>
<prDefaultExcludes value="false"/>
<prExcludes value="*.xml"/>

The prSrcPaths property points to a comma-separated list of directories. The protected region resolver will scan these directories for files containing activated protected regions.

There are several file names which are excluded by default:

RCS, SCCS, CVS, CVS.adm, RCSLOG, cvslog.*, tags, TAGS, .make.state, .nse_depinfo, *~, #*,
.#*, ',*', _$*,*$, *.old, *.bak, *.BAK, *.orig, *.rej, .del-*, *.a, *.olb, *.o, *.obj,
 *.so, *.exe, *.Z,* .elc, *.ln, core, .svn

If you don't want to exclude any of these, you must set prDefaultExcludes to false.

<prDefaultExcludes value="false"/>

If you want to add additional excludes, you should use the prExcludes property.

<prExcludes value="*.xml,*.hbm"/>

Note: It's bad practice to mix generated and non-generated code in one artifact... Instead of using protected regions, you should try to leverage the target language's extension features (inheritance, inclusion, references, etc.) wherever possible. It is very rare that the use of protected regions is an appropriate solution.

An AO system always needs to define a joinpoint model; this is, you have to define, at which locations of a (template) program you can add additional (template) code. In Xpand, the joinpoints are simply templates (i.e. DEFINE .. ENDDEFINE) blocks. An "aspect template" can be declared AROUND previously existing templates. If you take a look at the oaw4.demo.emf.datamodel.generator project's source folder, you can find the Root.xpt template file. Inside, you can find a template called Impl that generates the implementation of the Java Bean.

«DEFINE Entity FOR data::Entity»
   «FILE baseClassFileName() »
      // generated at «timestamp()»
      public abstract class «baseClassName()» {
         «EXPAND Impl»
      }
   «ENDFILE»
«ENDDEFINE»

«DEFINE Impl FOR data::Entity»
   «EXPAND GettersAndSetters»
«ENDDEFINE»

«DEFINE Impl FOR data::PersistentEntity»
   «EXPAND GettersAndSetters»
    public void save() {

   }
«ENDDEFINE»

What we now want to do is as follows: Whenever the Impl template is executed, we want to run an additional template that generates additional code (for example, some kind of meta information for frameworks ... the specific code is not important for the example here).

So, in our new project, we define the following template file:

«AROUND Impl FOR data::Entity»
   «FOREACH attribute AS a»
      public static final AttrInfo «a.name»Info = new AttrInfo(
         "«a.name»", «a.type».class );
   «ENDFOREACH»
   «targetDef.proceed()»
«ENDAROUND»

So, this new template "wraps around" the exiting template called Impl It first generates additional code and then forwards the execution to the original template using targetDef.proceed(). So, in effect, this is a BEFORE advice. Moving the proceed statement to the beginning makes it an AFTER advice, ommitting it makes it an override.

Let's take a look at the workflow file to run this generator.

<workflow>
   <cartridge file="workflow.oaw"/>
   <component adviceTarget="generator"
              id="reflectionAdvice"
              class="oaw.xpand2.GeneratorAdvice">
      <advices value="templates::Advices"/>
   </component>
</workflow>

Mainly what we do here is to call the original workflow file. It is available from the classpath. After this cartridge call, we define an additional workflow component, a socalled advice component. It specifies generator as it's adviceTarget. That means that all the properties we define inside this advice component will instead be added to the component referenced by name in the adviceTarget, in our case the generator. So, in effect, we add the <advices value="templates::Advices" /> to the original generator component (without invasively modifying its own definition! This contributes the advice templates to the generator.

Running the generator produces the following code:

public abstract class PersonImplBase {
   public static final AttrInfo
      nameInfo = new AttrInfo("name", String.class);
   public static final AttrInfo
      name2Info = new AttrInfo("name2", String.class);
   private String name;
   private String name2;

   public void setName(String value) {
      this.name = value;
   }

   public String getName() {
      return this.name;
   }

   public void setName2(String value) {
      this.name2 = value;
   }

   public String getName2() {
      return this.name2;
   }
}