path: root/doc/org.eclipse.xpand.doc/src/5.0/content/xpand_reference.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE chapter [
<!ENTITY % isopub SYSTEM "http://www.w3.org/2003/entities/iso8879/isopub.ent">
%isopub;
]>

<chapter id="core_reference" xreflabel="Core reference">
  <title><emphasis>Check</emphasis> / <emphasis>Xtend</emphasis> /
    <emphasis>Xpand</emphasis> Reference</title>
  
  <section id="r10_introduction">
    <title>Introduction</title>
    
    <para>The oAW4 generator framework provides textual languages, that are useful in
      different contexts in the MDSD process (e.g. checks, extensions, code generation,
      model transformation). Each oAW language ( <emphasis>Check</emphasis>,
      <emphasis>Xtend</emphasis>, and <emphasis>Xpand</emphasis>) is built up on a
      common expression language and type system. Therefore, they can operate on the same
      models, metamodels and meta-metamodels and you do not need to learn the syntax again
      and again, because it is always the same.</para>
    
    <para>The expressions framework provides a uniform abstraction layer over different
      meta-meta-models (e.g. EMF Ecore, Eclipse UML, JavaBeans, XML Schema etc.).
      Additionally, it offers a powerful, statically typed expressions language, which
      is used in the various textual languages.</para>
  </section>
  
  <section id="r10_typesystem">
    <title>Type System</title>
    
    <para>The abstraction layer on API basis is called a type system. It provides access to
      built-in types and different registered metamodel implementations. These
      registered metamodel implementations offer access to the types they provide. The
      first part of this documentation describes the type system. The expression
      sub-language is described afterwards in the second part of this documentation. This
      differentiation is necessary because the type system and the expression language
      are two different things. The type system is a kind of reflection layer, that can be
      extended with metamodel implementations. The expression language defines a
      concrete syntax for executable expressions, using the type system.</para>
    
    <para>The Java API described here is located in the
      <package>org.openarchitectureware.type</package> package and is a part of the
      subproject
      <package>core-expressions</package>.</para>
    
    <section id="r10_typesystem_types">
      <title>Types</title>
      
      <para>Every object (e.g. model elements, values, etc.) has a type. A type contains
        properties and operations. In addition it might inherit from other types
        (multiple inheritance).</para>
      
      <section id="r10_typesystem_typenames">
        <title>Type Names</title>
        
        <para>Types have a simple Name (e.g. <classname>String</classname>) and an
          optional namespace used to distingish between two types with the same name (e.g.
          <classname>my::metamodel</classname>). The delimiter for name space
          fragments is a double colon " <classname>::</classname>". A fully qualified
          name looks like this:
          <programlisting language="xtend">
          
          
          my::fully::qualified::MetaType</programlisting></para>
        
        <para>The namespace and name used by a specific type is defined by the
          corresponding <classname>MetaModel</classname> implementation. The
          <classname>EmfMetaModel</classname>, for instance, maps
          <classname>EPackages</classname> to namespace and
          <classname>EClassifiers</classname> to names. Therefore, the name of the
          Ecore element <classname>EClassifier</classname> is called:</para>
        
        <programlisting>ecore::EClassifier</programlisting>
        
        <para>If you do not want to use namespaces (for whatever reason), you can always
          implement your own metamodel and map the names accordingly.</para>
      </section>
      
      <section id="r10_typesystem_collection_typenames">
        <title>Collection Type Names</title>
        
        <para>The built-in type system also contains the following collection types:
          <classname>Collection</classname>, <classname>List</classname> and
          <classname>Set</classname>. Because the expressions language is statically
          type checked and we do not like casts and
          <classname>ClassCastExceptions</classname>, we introduced the concept of
          <emphasis>parameterized types</emphasis>. The type system does not support
          full featured generics, because we do not need them.</para>
        
        <para>The syntax is:</para>
        
        
        <programlisting>Collection[my::Type] List[my::Type] Set[my::Type]
        </programlisting>
      </section>
      
      <section id="r10_typesystem_features">
        <title>Features</title>
        
        <para>Each type offers features. The type (resp. the metamodel) is responsible
          for mapping the features. There are three different kinds of features:
          <itemizedlist>
            <listitem> Properties </listitem>
            
            <listitem> Operations </listitem>
            
            <listitem> Static properties </listitem>
          </itemizedlist></para>
        
        <para> <emphasis>Properties</emphasis> 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 <emphasis>Operations</emphasis>. But in contrast to properties,
          they can have parameters. <emphasis>Static properties</emphasis> are the
          equivalent to enums or constants. They must be invoked statically and they do not
          have parameters.</para>
      </section>
    </section>
    
    <section id="r10_builtintypes">
      <title>Built-In Types</title>
      
      <para>As mentioned before, the expressions framework has several built-in types
        that define operations and properties. In the following, we will give a rough
        overview of the types and their features. We will not document all of the operations
        here, because the built-.in types will evolve over time and we want to derive the
        documentation from the implementation (model-driven, of course). For a complete
        reference, consult the generated API documentation ( <ulink
          url="http://www.openarchitectureware.org/api/built-ins/"></ulink>
        ).</para>
      
      <section id="r10_builtintypes_object">
        <title> <classname>Object</classname>
        </title>
        
        <para> <classname>Object</classname> defines a couple of basic operations,
          like <methodname>equals()</methodname>. Every type has to extend
          <classname>Object</classname>.</para>
      </section>
      
      <section id="r10_builtintypes_void">
        <title> <classname>Void</classname>
        </title>
        
        <para>The <classname>Void</classname> type can be specified as the return type
          for operations, although it is not recommended, because whenever possible
          expressions should be free of side effects whenever possible.</para>
      </section>
      
      <section id="r10_builtintypes_simple">
        <title>Simple types (Data types)</title>
        
        <para>The type system doesn't have a concept data type. Data types are just types.
          As in OCL, we support the following types: <classname>String</classname>,
          <classname>Boolean</classname>, <classname>Integer</classname>,
          <classname>Real</classname>.
          <itemizedlist>
            <listitem> <classname>String</classname> : A rich and convenient
              <classname>String</classname> library is especially important for code
              generation. The type system supports the '+' operator for concatenation,
              the usual <classname>java.lang.String</classname> operations (
              <methodname>length()</methodname> , etc.) and some special operations
              (like <methodname>toFirstUpper()</methodname> ,
              <methodname>toFirstLower()</methodname> , regular expressions, etc.
              often needed in code generation templates). </listitem>
            
            <listitem> <classname>Boolean</classname> :
              <classname>Boolean</classname> offers the usual operators (Java
              syntax): &amp;&amp;, ||, !, etc. </listitem>
            
            <listitem> <classname>Integer</classname> and
              <classname>Real</classname> : <classname>Integer</classname> and
              <classname>Real</classname> offer the usual compare operators
              (&lt;,&gt;,&lt;=,&gt;=) and simple arithmetics (+,-,*,/). Note that
              <emphasis> <classname>Integer</classname> extends
              <classname>Real</classname></emphasis> ! </listitem>
          </itemizedlist></para>
      </section>
      
      <section id="r10_builtintypes_collections">
        <title>Collection types</title>
        
        <para>The type system has three different Collection types.
          <classname>Collection</classname> is the base type, it provides several
          operations known from <classname>java.util.Collection</classname>. The
          other two types ( <classname>List</classname>, <classname>Set</classname>
          ) correspond to their
          <package>java.util</package> equivalents, too.</para>
      </section>
      
      <section id="r10_builtintypes_typesystem_types">
        <title>Type system types</title>
        
        <para>The type system describes itself, hence, there are types for the different
          concepts. These types are needed for reflective programming. To avoid
          confusion with metatypes with the same name (it is not unusual to have a metatype
          called <classname>Operation</classname>, for instance) we have prefixed all
          of the types with the namespace <classname>oaw</classname>. We have:</para>
        
        <itemizedlist>
          <listitem> <classname>oaw::Type</classname>
          </listitem>
          
          <listitem> <classname>oaw::Feature</classname>
          </listitem>
          
          <listitem> <classname>oaw::Property</classname>
          </listitem>
          
          <listitem> <classname>oaw::StaticProperty</classname>
          </listitem>
          
          <listitem> <classname>oaw::Operation</classname>
          </listitem>
        </itemizedlist>
      </section>
    </section>
    
    <section id="r10_metamodel_implementations">
      <title>Metamodel Implementations (also known as Meta-Metamodels)</title>
      
      <para>By default, the type system only knows the built-in types. In order to register
        your own metatypes (e.g. <classname>Entity</classname> or
        <classname>State</classname>), you need to register a respective metamodel
        implementation with the type system. Within a metamodel implementation the oAW
        type system elements (Type, Property, Operation) are mapped to an arbitrary other
        type system (Java reflections, Ecore or XML Schema).</para>
      
      <section id="r10_metamodel_example_java">
        <title>Example JavaMetaModel</title>
        
        <para>For instance, if you want to have the following JavaBean act as a metatype
          (i.e. your model contains instances of the type):</para>
        
        <programlisting language="java">
        
        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; } } </programlisting>
        
        <para>You need to use the <classname>JavaMetaModel</classname>
          implementation which uses the ordinary Java reflection layer in order to map
          access to the model.</para>
        
        <para>So, if you have the following expression in e.g.
          <emphasis>Xpand</emphasis>:</para>
        
        <programlisting>myattr.name.toFirstUpper()</programlisting>
        
        <para>and <varname>myattr</varname> is the name of a local variable pointing to
          an instance of <classname>Attribute</classname>. The oAW type system asks the
          metamodel implementations, if they 'know' a type for the instance of Attribute.
          If you have the <classname>JavaMetaModel</classname> registered it will
          return an <classname>oaw::Type</classname> which maps to the underlying Java
          class. When the type is asked if it knows a property ' <varname>name</varname>',
          it will inspect the Java class using the Java reflection API.</para>
        
        <para>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.</para>
      </section>
      
      <section id="r10_metamodel_contributors">
        <title>Eclipse IDE MetaModelContributors</title>
        
        <para>You should know that for each <classname>Metamodel</classname>
          implementation you use at runtime, you need to have a so called
          <classname>MetamodelContributor</classname> 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
          <classname>MetamodelContributor</classname> you should have a look at the
          Eclipse plug-in reference doc.</para>
      </section>
      
      <section id="r10_metamodel_workflow">
        <title>Configuring Metamodel implementations with the workflow</title>
        
        <para>You need to configure your oAW language components with the respective
          metamodel implementations.</para>
        
        <para>A possible configuration of the <classname>Xpand2</classname>
          generator component looks like this:</para>
        
        <programlisting language="xml">
        
        &lt;component
        class="oaw.xpand2.Generator"&gt;
        &lt;metaModel class="oaw.type.emf.EmfMetaModel"&gt;
        &lt;metaModelPackage value="my.generated.MetaModel1Package"/&gt;
        &lt;/metaModel&gt;
        &lt;metaModel class="oaw.type.emf.EmfMetaModel"&gt;
        &lt;metaModelFile value="my/java/package/metamodel2.ecore"/&gt;
        &lt;/metaModel&gt; ...
        &lt;/component&gt; </programlisting>
        
        <para>In this example the <classname>EmfMetaModel</classname>
          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 <classname>EmfMetaModel</classname>
          (located in the <filename>core.emftools</filename> project). It points to
          the generated <classname>EPackages</classname> interface. The second meta
          model is configured using the Ecore file. You do no need to have a generated Ecore
          model for oAW in order to work. The <classname>EmfMetaModel</classname> works
          with dynamic EMF models just as it works with generated EMF models.</para>
      </section>
    </section>
    
    <section id="r10_using_different_metamodels">
      <title>Using different Metamodel implementations (also known as
        Meta-Metamodels)</title>
      
      <para>With oAW you can work on different kinds of Model representations at the same
        time in a transparent manner. One can work with EMF models, XML DOM models, and
        simple JavaBeans in the same Xpand-Template. You just need to configure the
        respective MetaModel implementations.</para>
      
      <para>If you want to do so you need to know how the type lookup works. Let us assume that
        we have an EMF metamodel and a model based on some Java classes. Then the following
        would be a possible configuration:</para>
      
      <programlisting language="xml">
      
      &lt;component
      class="oaw.xpand2.Generator"&gt;
      &lt;metaModel class="oaw.type.impl.java.JavaMetaModel"/&gt;
      &lt;metaModel class="oaw.type.emf.EmfMetaModel"&gt;
      &lt;metaModelFile value="my/java/package/metamodel.ecore"/&gt;
      &lt;/metaModel&gt;
      ...
      &lt;/component&gt; </programlisting>
      
      <para>When the oAW runtime needs to access a property of a given object, it asks the
        metamodels in the configured order. Let us assume that our model element is an
        instance of the Java type
        <classname>org.eclipse.emf.ecore.EObject</classname> and it is a dynamic
        instance of an EMF EClass <classname>MyType</classname>.</para>
      
      <para>We have <emphasis>three</emphasis> Metamodels:
        <orderedlist>
          <listitem> Built-Ins (always the first one) </listitem>
          
          <listitem> JavaMetaModel </listitem>
          
          <listitem> EMFMetaModel &ndash; metamodel.ecore </listitem>
        </orderedlist></para>
      
      <para>The first one will return the type <classname>Object</classname> (not
        <classname>java.lang.Object</classname> but
        <classname>Object</classname> of oAW). At this point the type
        <classname>Object</classname> best fits the request, so it will act as the
        desired type.</para>
      
      <para>The second metamodel returns an oAW type called
        <classname>oaw::eclipse::emf::ecore::EObject</classname> The type system
        will check if the returned type is a specialization of the current 'best-fit' type (
        <classname>Object</classname>). It is, because it extends
        <classname>Object</classname> (Every metatype has to extend
        <classname>Object</classname>). At this time the type system assumes
        <classname>oaw::eclipse::emf::ecore::EObject</classname> to be the desired
        type.</para>
      
      <para>The third metamodel will return
        <classname>metamodel::MyType</classname> which is the desired type. But
        unfortunately it doesn't extend
        <classname>org::eclipse::emf::ecore::EObject</classname> as it has nothing
        to do with those Java types. Instead it extends
        <classname>emf::EObject</classname> which extends
        <classname>Object</classname>.</para>
      
      <para>We need to swap the configuration of the two metamodels to get the desired
        type.</para>
      
      <programlisting language="xml">
      
      &lt;component
      class="oaw.xpand2.Generator"&gt;
      &lt;metaModel class="oaw.type.emf.EmfMetaModel"&gt;
      &lt;metaModelFile value="my/java/package/metamodel.ecore"/&gt;
      &lt;/metaModel&gt;
      &lt;metaModel class="oaw.type.impl.java.JavaMetaModel"/&gt;
      ...
      &lt;/component&gt;</programlisting>
    </section>
  </section>
  
  <section id="r10_expressions_language" xreflabel="Expressions">
    <title>Expressions</title>
    
    <para>The oAW expression sub-language is a syntactical mixture of Java and OCL. This
      documentation provides a detailed description of each available expression. Let us
      start with some simple examples.</para>
    
    <para>Accessing a property:</para>
    
    <programlisting>myModelElement.name</programlisting>
    
    <para>Accessing an operation:</para>
    
    <programlisting>myModelElement.doStuff()</programlisting>
    
    <para>simple arithmetic:</para>
    
    <programlisting>1 + 1 * 2</programlisting>
    
    <para>boolean expressions (just an example:-)):</para>
    
    
    <programlisting>!('text'.startsWith('t') &amp;&amp; ! false)</programlisting>
    
    <section id="r10_expressions_builtin">
      <title>Literals and special operators for built-in types</title>
      
      <para>There are several literals for built-in types:</para>
      
      <section id="r10_expressions_builtin_object">
        <title> <classname>Object</classname>
        </title>
        
        <para>There are naturally no literals for object, but we have two
          operators:</para>
        
        <para>equals:</para>
        
        <programlisting>obj1 == obj2</programlisting>
        
        <para>not equals:</para>
        
        <programlisting>obj1 != obj2</programlisting>
      </section>
      
      <section id="r10_expressions_builtin_void">
        <title> <classname>Void</classname>
        </title>
        
        <para>The only possible instance of <classname>Void</classname> is the
          <varname>null</varname> reference. Therefore, we have one literal:</para>
        
        <programlisting>null</programlisting>
      </section>
      
      <section id="r10_expressions_builtin_typeliterals">
        <title>Type literals</title>
        
        <para>The literal for types is just the name of the type (no '.class' suffix, etc.).
          Example:</para>
        
        
        <programlisting>String // the type string my::special::Type // evaluates to the
        type 'my::special::Type'</programlisting>
      </section>
      
      <section id="r10_expressions_builtin_staticproperties">
        <title>StaticProperty literals</title>
        
        <para>The literal for static properties (aka enum literals) is correlative to
          type literals:</para>
        
        <programlisting>my::Color::RED</programlisting>
      </section>
      
      <section id="r10_expressions_builtin_string">
        <title> <classname>String</classname>
        </title>
        
        <para>There are two different literal syntaxes (with the same
          semantics):</para>
        
        
        <programlisting>S'a String literal' "a String literal" // both are
        okay</programlisting>
        
        <para>For Strings the expression sub-language supports the plus operator that is
          overloaded with concatenation:</para>
        
        
        <programlisting>'my element '+ ele.name +' is really cool!'</programlisting>
        
        <para>Note, that multi-line Strings are supported.</para>
      </section>
      
      <section id="r10_expressions_builtin_boolean">
        <title> <classname>Boolean</classname>
        </title>
        
        <para>The boolean literals are:</para>
        
        <programlisting>true false</programlisting>
        
        <para>Operators are:</para>
        
        
        <programlisting>true &amp;&amp; false // AND true || false // OR ! true //
        NOT</programlisting>
      </section>
      
      <section id="r10_expressions_builtin_numeric">
        <title> <classname>Integer</classname> and <classname>Real</classname>
          </title>
        
        <para>The syntax for integer literals is as expected:</para>
        
        
        <programlisting>// integer literals 3 57278 // real literals 3.0 0.75
        </programlisting>
        
        <para>Additionally, we have the common arithmetic operators:</para>
        
        
        <programlisting>3 + 4 // addition 4 - 5 // subtraction 2 * 6 // multiplication 3 / 64 //
        divide // Unary minus operator - 42 - 47.11 </programlisting>
        
        <para>Furthermore, the well known compare operators are defined:</para>
        
        
        <programlisting>4 &gt; 5 // greater than 4 &lt; 5 // smaller than 4 &gt;= 23 // greater
        equals than 4 &lt;= 12 // smaller equals than </programlisting>
      </section>
      
      <section id="r10_expressions_builtin_collections">
        <title>Collections</title>
        
        <para>There is a literal for lists:</para>
        
        
        <programlisting>{1,2,3,4} // a list with four integers</programlisting>
        
        <para>There is no other special concrete syntax for collections. If you need a set,
          you have to call the <methodname>toSet()</methodname> operation on the list
          literal:</para>
        
        
        <programlisting>{1,2,4,4}.toSet() // a set with 3(!) integers</programlisting>
      </section>
    </section>
    
    <section id="r10_expressions_collection_operations">
      <title>Special Collection operations</title>
      
      <para>Like OCL, the oAW expression sub-language defines several special
        operations on collections. However, those operations are not members of the type
        system, therefore you cannot use them in a reflective manner.</para>
      
      <section id="r10_expressions_collection_select">
        <title> <methodname>select</methodname>
        </title>
        
        <para>Sometimes, an expression yields a large collection, but one 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 <methodname>select</methodname> and
          <methodname>reject</methodname> operations. The select specifies a subset
          of a collection. A <methodname>select</methodname> is an operation on a
          collection and is specified as follows:</para>
        
        
        <programlisting>collection.select(v |
        boolean-expression-with-v)</programlisting>
        
        <para> <methodname>select</methodname> returns a sublist of the specified
          collection. The list contains all elements for which the evaluation of
          boolean-expression-with-v results is <varname>true</varname>.
          Example:</para>
        
        
        <programlisting>{1,2,3,4}.select(i | i &gt;= 3) // returns
        {3,4}</programlisting>
      </section>
      
      <section id="r10_expressions_collection_typeselect">
        <title> <methodname>typeSelect</methodname>
        </title>
        
        <para>A special version of a select expression is
          <methodname>typeSelect</methodname>. Rather than providing a boolean
          expression a class name is here provided.</para>
        
        <programlisting>collection.typeSelect(classname) </programlisting>
        
        <para> <methodname>typeSelect</methodname> returns that sublist of the
          specified collection, that contains only objects which are an instance of the
          specified class (also inherited).</para>
      </section>
      
      <section id="r10_expressions_collection_reject">
        <title> <methodname>reject</methodname>
        </title>
        
        <para>The <methodname>reject</methodname> operation is similar to the
          <methodname>select</methodname> operation, but with
          <methodname>reject</methodname> we get the subset of all the elements of the
          collection for which the expression evaluates to <varname>false</varname>.
          The <methodname>reject</methodname> syntax is identical to the
          <methodname>select</methodname> syntax:</para>
        
        
        <programlisting>collection.reject(v |
        boolean-expression-with-v)</programlisting>
        
        <para>Example:</para>
        
        
        <programlisting>{1,2,3,4}.reject(i | i &gt;= 3) // returns
        {1,2}</programlisting>
      </section>
      
      <section id="r10_expressions_collection_collect">
        <title> <methodname>collect</methodname>
        </title>
        
        <para>As shown in the previous section, the <methodname>select</methodname>
          and <methodname>reject</methodname> 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 that are not in the original collection (it is not a sub-collection). In
          such cases, we can use a <methodname>collect</methodname> operation. The
          <methodname>collect</methodname> operation uses the same syntax as the
          <methodname>select</methodname> and <methodname>reject</methodname> and
          is written like this:</para>
        
        
        <programlisting>collection.collect(v | expression-with-v)</programlisting>
        
        <para> <methodname>collect</methodname> again iterates over the target
          collection and evaluates the given expression on each element. In contrast to
          <methodname>select</methodname>, the evaluation result is collected in a
          list. When an iteration is finished the list with all results is returned.
          Example:</para>
        
        
        <programlisting>namedElements.collect(ne | ne.name) // returns a list of strings
        </programlisting>
      </section>
      
      <section id="r10_expressions_collection_collect_shorthand">
        <title>Shorthand for <methodname>collect</methodname> (and more than
          that)</title>
        
        <para>As navigation through many objects is very common, there is a shorthand
          notation for collect that makes the expressions more readable. Instead
          of</para>
        
        
        <programlisting>self.employee.collect(e | e.birthdate) </programlisting>
        
        <para>one can also write:</para>
        
        <programlisting>self.employee.birthdate</programlisting>
        
        <para>In general, when a property is applied to a collection of Objects, it will
          automatically be interpreted as a <methodname>collect</methodname> over the
          members of the collection with the specified property.</para>
        
        <para>The syntax is a shorthand for <methodname>collect</methodname>, if the
          feature does not return a collection itself. But sometimes we have the
          following:</para>
        
        
        <programlisting>self.buildings.rooms.windows // returns a list of
        windows</programlisting>
        
        <para>This syntax works, but one cannot express it using the
          <methodname>collect</methodname> operation in an easy way.</para>
      </section>
      
      <section id="r10_expressions_collection_forall">
        <title> <methodname>forAll</methodname>
        </title>
        
        <para>Often a boolean expression has to be evaluated for all elements in a
          collection. The <methodname>forAll</methodname> operation allows
          specifying a Boolean expression, which must be <varname>true</varname> for
          all objects in a collection in order for the <methodname>forAll</methodname>
          operation to return <varname>true</varname>:</para>
        
        
        <programlisting>collection.forAll(v |
        boolean-expression-with-v)</programlisting>
        
        <para>The result of <methodname>forAll</methodname> is
          <varname>true</varname> if
          <varname>boolean-expression-with-v</varname> is <varname>true
          </varname>for all the elements contained in a collection. If
          <varname>boolean-expression-with-v</varname> is
          <varname>false</varname> for one or more of the elements in the collection,
          then the <methodname>forAll</methodname> expression evaluates to
          <varname>false</varname>.</para>
        
        <para>Example:</para>
        
        
        <programlisting>{3,4,500}.forAll(i | i &lt; 10) // evaluates to false (500 &lt; 10
        is false)</programlisting>
      </section>
      
      <section id="r10_expressions_collection_exists">
        <title> <methodname>exists</methodname>
        </title>
        
        <para>Often you will need to know whether there is at least one element in a
          collection for which a boolean is <varname>true</varname>. The exists
          operation allows you to specify a Boolean expression which must be
          <varname>true</varname> for at least one object in a collection:</para>
        
        
        <programlisting>collection.exists(v |
        boolean-expression-with-v)</programlisting>
        
        <para>The result of the exists operation is <varname>true</varname> if
          <varname>boolean-expression-with-v</varname> is
          <varname>true</varname> for at least one element of collection. If the
          <varname>boolean-expression-with-v</varname> is
          <varname>false</varname> for all elements in collection, then the complete
          expression evaluates to <varname>false</varname>.</para>
        
        <para>Example:</para>
        
        
        <programlisting>{3,4,500}.exists(i | i &lt; 10) // evaluates to true (e.g. 3 &lt; 10
        is true)</programlisting>
      </section>
      
      <section id="r10_expressions_collection_sortby">
        <title> <methodname>sortBy</methodname> <footnote>
          <para>since 4.1.2</para> </footnote>
        </title>
        
        <para>If you want to sort a list of elements, you can use the higher order function
          <methodname>sortBy</methodname>. The list you invoke the
          <methodname>sortBy</methodname> operation on, is sorted by the results of the
          given expression.</para>
        
        <para>Example:</para>
        
        
        <programlisting>myListOfEntity.sortBy(entity |
        entity.name)</programlisting>
        
        <para>In the example the list of entities is sorted by the name of the entities. Note
          that there is no such <classname>Comparable</classname> type in oaw. If the
          values returned from the expression are instances of
          <classname>java.util.Comparable</classname> the
          <methodname>compareTo</methodname> method is used, otherwise
          <methodname>toString()</methodname> is invoked and the the result is
          used.</para>
        
        <para>More Examples &ndash; all the following expressions return
          <varname>true</varname>:</para>
        
        
        <programlisting>{'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}
        ...</programlisting>
      </section>
    </section>
    
    <section id="r10_expressions_if">
      <title> <methodname>if</methodname> expression</title>
      
      <para>There are two different forms of conditional expressions. The first one is the
        so-called <emphasis>if expression</emphasis>. Syntax:</para>
      
      
      <programlisting>condition ? thenExpression : elseExpression</programlisting>
      
      <para>Example:</para>
      
      <programlisting>name != null ? name : 'unknown'</programlisting>
    </section>
    
    <section id="r10_expressions_switch">
      <title> <methodname>switch</methodname> expression</title>
      
      <para>The other one is called <emphasis>switch expression</emphasis>.
        Syntax:</para>
      
      
      <programlisting>switch (expression) { (case expression : thenExpression)* default
      : catchAllExpression }</programlisting>
      
      <para>The default part is mandatory, because <methodname>switch</methodname> is
        an expression, therefore it needs to evaluate to something in any case.
        Example:</para>
      
      
      <programlisting>switch (person.name) { case 'Hansen' : 'Du kanns platt schnacken'
      default : 'Du kanns mi nech verstohn!' }</programlisting>
      
      <para>There is an abbreviation for <emphasis>Boolean</emphasis>
        expressions:</para>
      
      
      <programlisting>switch { case booleanExpression : thenExpression default :
      catchAllExpression } </programlisting>
    </section>
    
    <section id="r10_expressions_chain">
      <title>Chain expression</title>
      
      <para>Expressions and functional languages should be free of side effects as far as
        possible. But sometimes there you need invocations that do have side effects. In
        some cases expressions even don not have a return type (i.e. the return type is
        <classname>Void</classname>). If you need to call such operations, you can use
        the chain expression. Syntax:</para>
      
      
      <programlisting>anExpr -&gt; anotherExpr -&gt; lastExpr </programlisting>
      
      <para>Each expression is evaluated in sequence, but only the result of the last
        expression is returned. Example:</para>
      
      <programlisting>pers.setName('test') -&gt; pers</programlisting>
      
      <para>This chain expression will set the <varname>name</varname> of the person
        first, before it returns the person object itself.</para>
    </section>
    
    <section id="r10_expressions_create">
      <title> <methodname>create</methodname> expression</title>
      
      <para>The <methodname>create</methodname> expression is used to instantiate new
        objects of a given type:</para>
      
      <programlisting>new TypeName</programlisting>
    </section>
    
    <section id="r10_expressions_let">
      <title> <methodname>let</methodname> expression</title>
      
      <para>The <methodname>let</methodname> expression lets you define local
        variables. Syntax is as follows:</para>
      
      
      <programlisting>let v = expression in expression-with-v </programlisting>
      
      <para>This is especially useful together with a chain- and a create expressions.
        Example:</para>
      
      
      <programlisting>let p = new Person in p.name('John Doe') -&gt; p.age(42) -&gt;
      p.city('New York') -&gt; p</programlisting>
    </section>
    
    <section id="r10_expressions_globalvar">
      <title>'GLOBALVAR' expression</title>
      
      <para>Sometimes you don't want to pass everything down the call stack by parameter.
        Therefore, we have the <methodname>GLOBALVAR</methodname> expression. There
        are two things you need to do, to use global variables within one of the
        openArchitectureWare languages ( <emphasis>Check</emphasis>,
        <emphasis>Xtend</emphasis> or <emphasis>Xpand</emphasis>).</para>
      
      <section id="r10_expressions_globalvar_workflow">
        <title>Using GLOBALVARS to configure workflows</title>
        
        <para>Each workflow component using the expression framework (
          <emphasis>Xpand</emphasis>, <emphasis>Check</emphasis> and
          <emphasis>Xtend</emphasis>) can be configured with global variables. Here is
          an example:</para>
        
        <programlisting language="xml">
        
        &lt;workflow&gt; .... stuff
        &lt;component class="oaw.xpand2.Generator"&gt; ... usual stuff (see ref doc)
        &lt;globalVarDef name="MyPSM" value="slotNameOfPSM"/&gt;
        &lt;globalVarDef name="ImplClassSuffix" value="'Impl'"/&gt;
        &lt;/component&gt;
        &lt;/workflow&gt;</programlisting>
        
        <para>If you have injected global variables into the respective component, you
          can call them using the following syntax:</para>
        
        <programlisting>GLOBALVAR ImplClassSuffix</programlisting>
        
        <para>Note, we don't have any static type information. Therefore
          <classname>Object</classname> is assumed. So, you have to down cast the global
          variable to the intended type:</para>
        
        <programlisting>((String) GLOBALVAR ImplClassSuffix)</programlisting>
        
        <para>It is good practice to type it once, using an Extension and then always refer
          to that extension:</para>
        
        <programlisting language="xtend">
        
        String implClassSuffix() : GLOBALVAR
        ImplClassSuffix; // usage of the typed global var extension ImplName(Class c) :
        name+implClassSuffix();</programlisting>
      </section>
    </section>
    
    <section id="r10_expressions_multidispatch">
      <title>Multi methods (multiple dispatch)</title>
      
      <para>The expressions language supports multiple dispatching. This means that
        when there is a bunch of overloaded operations, the decision which operation has to
        be resolved is based on the dynamic type of all parameters (the implicit '
        <varname>this</varname>' included).</para>
      
      <para>In Java only the dynamic type of the ' <varname>this</varname>' element is
        considered, for parameters the static type is used. (this is called single
        dispatch)</para>
      
      <para>Here is a Java example:</para>
      
      <programlisting language="xtend">
      
      class MyClass { boolean equals(Object o) { if (o
      instanceof MyClass) { return equals((MyClass)o); } return super.equals(o); }
      boolean equals(MyType mt) { //implementation... } } </programlisting>
      
      <para>The method <methodname>equals(Object o)</methodname> would not have to be
        overwritten, if Java would support multiple dispatch.</para>
    </section>
    
    <section id="r10_expressions_casting">
      <title>Casting</title>
      
      <para>The expression language is statically type checked. Although there are many
        concepts that help the programmer to have really good static type information,
        sometimes. one knows more about the real type than the system. To explicitly give
        the system such an information casts are available. <emphasis>Casts are 100%
        static, so you do not need them, if you never statically typecheck your
        expressions! </emphasis></para>
      
      <para>The syntax for casts is very Java-like:</para>
      
      
      <programlisting>
      ((String)unTypedList.get(0)).toUpperCase()</programlisting>
    </section>
  </section>
  
  <section id="Check_language" xreflabel="Check language">
    <title> <emphasis>Check</emphasis>
    </title>
    
    <para>openArchitectureWare also provides a language to specify constraints that the
      model has to fulfill in order to be correct. This language is very easy to understand
      and use. Basically, it is built around the expression syntax that has been discussed
      in detail in the previous section. Constraints specified in the
      <emphasis>Check</emphasis> language have to be stored in files with the file
      extension <filename>.chk</filename>. Furthermore, these files have to be on the
      Java classpath, of course, in order to be found. Let us look at an example, in order to
      understand, what these constraints look like and what they do:
      <programlisting language="check">
      
      import data; context Attribute ERROR "Names have
      to be more than one character long." : name.length &gt; 1;</programlisting>Now,
      let us look at the example line by line:
      <orderedlist>
        <listitem>
          <para>First, the metamodel has to be imported.</para>
        </listitem>
        
        <listitem>
          <para>Then, the context is specified for which the constraint applies. In other
            words, after the
            <code>context</code> keyword, we put the name of the metaclass that is going
            to be checked by the constraint. Then, there follows either
            <code>ERROR</code> or
            <code>WARNING</code>, These keywords specify what kind of action will be
            taken in case the constraint fails:
            <table frame="all">
              <title>Types of action for <emphasis>Check</emphasis>
                constraints</title>
              
              <tgroup cols="2" colsep="1" rowsep="1">
                <colspec colnum="2" colwidth="7*"/>
                
                <tbody>
                  <row>
                    <entry>
                      <code>WARNING</code>
                    </entry>
                    
                    <entry>If the constraint fails, the specified message is printed,
                      but the workflow execution is not stopped.</entry>
                  </row>
                  
                  <row>
                    <entry>
                      <code>ERROR</code>
                    </entry>
                    
                    <entry>If the constraint fails, the specified message is printed
                      and all further processing is stopped.</entry>
                  </row>
                </tbody>
              </tgroup>
            </table></para>
        </listitem>
        
        <listitem>
          <para>Now, the message that is put in case that the constraint fails is specified
            as a string. It is possible to include the value of attributes or the return
            value of functions into the message in order to make the message more clear. For
            example, it would be possible to improve the above example by rewriting it like
            this:</para>
          
          <programlisting language="check">
          
          import data; context Attribute ERROR "Name
          of '" + name + "too short. Names have to be more than one character long." :
          name.length &gt; 1;</programlisting>
        </listitem>
        
        <listitem>
          <para>Finally, there is the condition itself, which is specified by an
            expression, which has been discussed in detail in the previous section. If
            this expression is <varname>true</varname>, the constraint is
            fulfilled.</para>
        </listitem>
      </orderedlist></para>
    
    <para> <important>
      <para>Please always keep in mind that the message that is associated with the
        constraint is printed, if the condition of the constraint is
        <varname>false</varname>! Thus, if the specified constraint condition is
        <varname>true</varname>, nothing will be printed out and the constraint will be
        fulfilled.</para> </important> </para>
  </section>
  
  <section id="Xtend_language" xreflabel="Xtend">
    <title> <emphasis>Xtend</emphasis>
    </title>
    
    <para>Like the expressions sublanguage that summarizes the syntax of expressions for
      all the other textual languages delivered with the openArchitectureWare
      framework, there is another commonly used language called
      <emphasis>Xtend</emphasis>.</para>
    
    <para>This language provides the possibility to define rich libraries of independent
      operations and no-invasive metamodel extensions based on either Java methods or oAW
      expressions. Those libraries can be referenced from all other textual languages,
      that are based on the expressions framework.</para>
    
    <section>
      <title>Extend files</title>
      
      <para>An extend file must reside in the Java class path of the used execution context.
        Additionally it is file extension must be <filename>*.ext</filename>. Let us
        have a look at an extend file.</para>
      
      
      <programlisting>import my::metamodel;extension other::ExtensionFile;
      /** * Documentation */ anExpressionExtension(String stringParam) :
      doingStuff(with(stringParam)) ;
      /** * java extensions are just mappings */ String aJavaExtension(String param) :
      JAVA my.JavaClass.staticMethod(java.lang.String) ; </programlisting>
      
      <para>The example shows the following statements:</para>
      
      <orderedlist>
        <listitem>
          <para>import statements</para>
        </listitem>
        
        <listitem>
          <para>extension import statements</para>
        </listitem>
        
        <listitem>
          <para>expression or java extensions</para>
        </listitem>
      </orderedlist>
    </section>
    
    <section>
      <title>Comments</title>
      
      <para>We have single- and multi-line comments. The syntax for single line comments
        is:</para>
      
      <programlisting>// my comment</programlisting>
      
      <para>Multi line comments are written like this:</para>
      
      <programlisting>/* My multi line comment */</programlisting>
    </section>
    
    <section>
      <title>Import Statements</title>
      
      <para>Using the import statement one can import name spaces of different types.(see
        expressions framework reference documentation).</para>
      
      <para>Syntax is:</para>
      
      <programlisting>import my::imported::namespace;</programlisting>
      
      <para>Extend does not support static imports or any similar concept. Therefore, the
        following is incorrect syntax:</para>
      
      
      <programlisting>import my::imported::namespace::*; // WRONG! import my::Type; //
      WRONG!</programlisting>
    </section>
    
    <section>
      <title>Extension Import Statement</title>
      
      <para>You can import another extend file using the extension statement. The syntax
        is:</para>
      
      
      <programlisting>extension
      fully::qualified::ExtensionFileName;</programlisting>
      
      <para>Note, that no file extension ( <filename>*.ext</filename>) is
        specified.</para>
      
      <section>
        <title>Reexporting Extensions</title>
        
        <para>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.</para>
        
        
        <programlisting>extension fully::qualified::ExtensionFileName
        reexport;</programlisting>
      </section>
    </section>
    
    <section>
      <title>Extensions</title>
      
      <para>The syntax of a simple expression extension is as follows:</para>
      
      
      <programlisting>ReturnType extensionName(ParamType1 paramName1,
      ParamType2...): expression-using-params;</programlisting>
      
      <para>Example:</para>
      
      
      <programlisting>String getterName(NamedElement ele) :
      'get'+ele.name.firstUpper();</programlisting>
      
      <section>
        <title>Extension Invocation</title>
        
        <para>There are two different ways of how to invoke an extension. It can be invoked
          like a function:</para>
        
        <programlisting>getterName(myNamedElement)</programlisting>
        
        <para>The other way to invoke an extension is through the "member syntax":</para>
        
        <programlisting>myNamedElement.getterName()</programlisting>
        
        <para>For any invocation in member syntax, the target expression (the member) is
          mapped to the first parameter. Therefore, both syntactical forms do the same
          thing.</para>
        
        <para>It is 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.</para>
        
        <para>The expression evaluation engine first looks for an appropriate operation
          before looking for an extension, in other words operations have higher
          precedence.</para>
      </section>
      
      <section>
        <title>Type Inference</title>
        
        <para>For most extensions, you do not 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.</para>
        
        <para>For instance, if you have the following extension</para>
        
        <programlisting>asList(Object o): {o};</programlisting>
        
        <para>the invocation of</para>
        
        <programlisting>asList('text')</programlisting>
        
        <para>has the static type List[String]. This means you can call</para>
        
        <programlisting>asList('text').get(0).toUpperCase()</programlisting>
        
        <para>The expression is statically type safe, because its return type is derived
          automatically.</para>
        
        <para>There is always a return value, whether you specify it or not, even if you
          specify explicitly ' <classname>Void</classname>'.</para>
        
        <para>See the following example.</para>
        
        
        <programlisting>
        modelTarget.ownedElements.addAllNotNull(modelSource.contents.duplicate())</programlisting>
        
        <para>In this example duplicate() dispatches polymorphically. Two of the
          extensions might look like:</para>
        
        
        <programlisting>Void duplicate(Realization realization):
        realization.Specifier().duplicate()-&gt;
        realization.Realizer().duplicate() ;
        create target::Class duplicate(source::Class): ... ;</programlisting>
        
        <para>If a ' <classname>Realization</classname>' is contained in the '
          <methodname>contents</methodname>' list of '
          <varname>modelSource</varname>', the '
          <methodname>Realizer</methodname>' of the '
          <classname>Realization</classname>' will be added to the '
          <varname>ownedElements</varname>' list of the '
          <varname>modelTarget</varname>'. If you do not want to add in the case that the
          contained element is a 'Realization' you might change the extension to:</para>
        
        
        <programlisting>Void duplicate(Realization realization):
        realization.Specifier().duplicate()-&gt;
        realization.Realizer().duplicate() -&gt; {} ;</programlisting>
      </section>
      
      <section>
        <title>Recursion</title>
        
        <para>There is only one exception: For recursive extensions the return type
          cannot be inferred, therefore you need to specify it explicitly:</para>
        
        
        <programlisting>String fullyQualifiedName(NamedElement n) : n.parent == null ?
        n.name : fullyQualifiedName(n.parent)+'::'+n.name ;</programlisting>
        
        <para>Recursive extensions are non-deterministic in a static context,
          therefore, it is necessary to specify a return type.</para>
      </section>
      
      <section>
        <title>Cached Extensions</title>
        
        <para>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 '
          <code>cached</code>' to the extension in order to achieve this:</para>
        
        
        <programlisting>cached String getterName(NamedElement ele) :
        'get'+ele.name.firstUpper() ;</programlisting>
        
        <para>The <methodname>getterName</methodname> will be computed only once for
          each <classname>NamedElement</classname>.</para>
      </section>
      
      <section>
        <title>Private Extensions</title>
        
        <para>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:</para>
        
        
        <programlisting>private internalHelper(NamedElement ele) : //
        implementation.... ;</programlisting>
      </section>
    </section>
    
    <section>
      <title>Java Extensions</title>
      
      <para>In some rare cases one does want to call a Java method from inside an expression.
        This can be done by providing a Java extension:</para>
      
      
      <programlisting>Void myJavaExtension(String param) : JAVA
      my.Type.staticMethod(java.lang.String) ;</programlisting>
      
      <para>The signature is the same as for any other extension. The implementation is
        redirected to a public static method in a Java class.</para>
      
      <para>Its syntax is:</para>
      
      
      <programlisting>JAVA fully.qualified.Type.staticMethod(my.ParamType1,
      my.ParamType2, ...) ;</programlisting>
      
      <para>Note that you cannot use any imported namespaces. You have to specify the type,
        its method and the parameter types in a fully qualified way.</para>
      
      <para>Example:</para>
      
      <para>If you have defined the following Java extension:</para>
      
      
      <programlisting>Void dump(String s) : JAVA my.Helper.dump(java.lang.String)
      ;</programlisting>
      
      <para>and you have the following Java class:</para>
      
      
      <programlisting>package my;
      public class Helper { public final static void dump(String aString) {
      System.out.println(aString); } }</programlisting>
      
      <para>the expressions</para>
      
      
      <programlisting>dump('Hello world!') 'Hello World'.dump()</programlisting>
      
      <para>both result are invoking the Java method void dump(String aString)</para>
    </section>
    
    <section>
      <title>Create Extensions (Model Transformation)</title>
      
      <para>Since Version 4.1 the <emphasis>Xtend</emphasis> language supports
        additional support for model transformation. The new concept is called
        <emphasis>create extension</emphasis> and it is explained a bit more
        comprehensive as usual.</para>
      
      <para>Elements contained in a model are usually referenced multiple times.
        Consider the following model structure:</para>
      
      <programlisting> P / \ C1 C2 \ / R </programlisting>
      
      <para>A package P contains two classes C1 and C2. C1 contains a reference R of type C2 (P
        also references C2).</para>
      
      <para>We could write the following extensions in order to transform an Ecore (EMF)
        model to our metamodel (Package, Class, Reference).</para>
      
      
      <programlisting>toPackage(EPackage x) : let p = new Package :
      p.ownedMember.addAll(x.eClassifiers.toClass()) -&gt; p;
      toClass(EClass x) : let c = new Class :
      c.attributes.addAll(x.eReferences.toReference()) -&gt; c;
      toReference(EReference x) : let r = new Reference : r.setType(x.eType.toClass())
      -&gt; r; </programlisting>
      
      <para>For an Ecore model with the above structure, the result would be:</para>
      
      <programlisting> P / \ C1 C2 | R - C2 </programlisting>
      
      <para>What happened? The C2 class has been created 2 times (one time for the package
        containment and another time for the reference R that also refers to C2). We can
        solve the problem by adding the 'cached' keyword to the second extension:</para>
      
      
      <programlisting>cached toClass(EClass x) : let c = new Class :
      c.attributes.addAll(c.eAttributes.toAttribute()) -&gt; c; </programlisting>
      
      <para>The process goes like this:</para>
      
      <orderedlist>
        <listitem>
          <para>start create P</para>
          
          <orderedlist>
            <listitem>
              <para>start create C1 (contained in P)</para>
              
              <orderedlist>
                <listitem>
                  <para>start create R (contained in C1)</para>
                  
                  <orderedlist>
                    <listitem>
                      <para>start create C2 (referenced from R)</para>
                    </listitem>
                    
                    <listitem>
                      <para>end (result C2 is cached)</para>
                    </listitem>
                  </orderedlist>
                </listitem>
                
                <listitem>
                  <para>end R</para>
                </listitem>
              </orderedlist>
            </listitem>
            
            <listitem>
              <para>end C1</para>
            </listitem>
            
            <listitem>
              <para>start get cached C2 (contained in P)</para>
            </listitem>
          </orderedlist>
        </listitem>
        
        <listitem>
          <para>end P</para>
        </listitem>
      </orderedlist>
      
      <para>So this works very well. We will get the intended structure. But what about
        circular dependencies? For instance, C2 could contain a Reference R2 of type C1
        (bidirectional references):</para>
      
      <para>The transformation would occur like this:</para>
      
      <orderedlist>
        <listitem>
          <para>start create P</para>
          
          <orderedlist>
            <listitem>
              <para>start create C1 (contained in P)</para>
              
              <orderedlist>
                <listitem>
                  <para>start create R (contained in C1)</para>
                  
                  <orderedlist>
                    <listitem>
                      <para>start create C2 (referenced from R)</para>
                      
                      <orderedlist>
                        <listitem>
                          <para>start create R2 (contained in C2)</para>
                          
                          <orderedlist>
                            <listitem>
                              <para>start create C1 (referenced from R1)...
                                OOPS!</para>
                            </listitem>
                          </orderedlist>
                        </listitem>
                      </orderedlist>
                    </listitem>
                  </orderedlist>
                </listitem>
              </orderedlist>
            </listitem>
          </orderedlist>
        </listitem>
      </orderedlist>
      
      <para>C1 is already in creation and will not complete until the stack is reduced.
        Deadlock! The problem is that the cache caches the return value, but C1 was not
        returned so far, because it is still in construction. The solution: create
        extensions</para>
      
      <para>The syntax is as follows:</para>
      
      
      <programlisting>create Package toPackage(EPackage x) :
      this.classifiers.addAll(x.eClassifiers.toClass());
      create Class toClass(EClass x) :
      this.attributes.addAll(x.eReferences.toReference());
      create Reference toReference(EReference x) : this.setType(x.eType.toClass());
      </programlisting>
      
      <para>This is not only a shorter syntax, but it also has the needed semantics: The
        created model element will be added to the cache before evaluating the body. The
        return value is always the reference to the created and maybe not completely
        initialized element.</para>
    </section>
    
    <section>
      <title>Calling Extensions From Java</title>
      
      <para>The previous section showed how to implement Extensions in Java. This section
        shows how to call Extensions from Java.</para>
      
      
      <programlisting>// setup XtendFacade f =
      XtendFacade.create("my::path::MyExtensionFile");
      // use f.call("sayHello",new Object[]{"World"}); </programlisting>
      
      <para>The called extension file looks like this:</para>
      
      <programlisting>sayHello(String s) : "Hello " + s;</programlisting>
      
      <para>This example uses only features of the BuiltinMetaModel, in this case the "
        <methodname>+</methodname>" feature from the StringTypeImpl.</para>
      
      <para>Here is another example, that uses the JavaBeansMetaModel strategy. This
        strategy provides as additional feature: the access to properties using the
        getter and setter methods.</para>
      
      <para>For more information about type systems, see the <emphasis> <xref
          linkend="r10_expressions_language"/> </emphasis> reference
        documentation.</para>
      
      <para>We have one JavaBean-like metamodel class:</para>
      
      
      <programlisting>package mypackage; public class MyBeanMetaClass { private String
      myProp; public String getMyProp() { return myProp; } public void setMyProp(String
      s) { myProp = s;} }</programlisting>
      
      <para>in addition to the built-in metamodel type system, we register the
        JavaMetaModel with the JavaBeansStrategy for our facade. Now, we can use also this
        strategy in our extension:</para>
      
      
      <programlisting>// setup facade
      XtendFacade f = XtendFacade.create("myext::JavaBeanExtension");
      // setup additional type system JavaMetaModel jmm = new JavaMetaModel("JavaMM",
      new JavaBeansStrategy());
      f.registerMetaModel(jmm);
      // use the facade MyBeanMetaClass jb = MyBeanMetaClass(); jb.setMyProp("test");
      f.call("readMyProp", new Object[]{jb}));</programlisting>
      
      <para>The called extension file looks like this:</para>
      
      
      <programlisting>import mypackage;
      readMyProp(MyBeanMetaClass jb) : jb.myProp ; </programlisting>
    </section>
    
    <section>
      <title>WorkflowComponent</title>
      
      <para>With the additional support for model transformation, it makes sense to
        invoke <emphasis>Xtend</emphasis> within a workflow. A typical workflow
        configuration of the <emphasis>Xtend</emphasis> component looks like
        this:</para>
      
      <programlisting language="xml">
      
      &lt;component
      class="oaw.xtend.XtendComponent"&gt;
      &lt;metaModel class="oaw.type.emf.EmfMetaModel"&gt;
      &lt;metaModelFile value="metamodel1.ecore"/&gt;
      &lt;/metamodel&gt;
      &lt;metaModel class="oaw.type.emf.EmfMetaModel"&gt;
      &lt;metaModelFile value="metamodel2.ecore"/&gt;
      &lt;/metaModel&gt;
      &lt;invoke value="my::example::Trafo::transform(inputSlot)"/&gt;
      &lt;outputSlot value="transformedModel"/&gt;
      &lt;/component&gt; </programlisting>
      
      <para>Note that you can mix and use any kinds of metamodels (not only EMF
        metamodels).</para>
    </section>
    
    <section>
      <title>Aspect-Oriented Programming in <emphasis>Xtend</emphasis> (since
        4.2)</title>
      
      <para>Using the workflow engine, it is now possible to package (e.g. zip) a written
        generator and deliver it as a kind of black box. If you want to use such a generator but
        need to change some things without modifying any code, you can make use of around
        advices that are supported by <emphasis>Xtend</emphasis>.</para>
      
      <para>The following advice is weaved around every invocation of an extension whose
        name starts with 'my::generator::':</para>
      
      
      <programlisting>around my::generator::*(*) : log('Invoking ' + ctx.name) -&gt;
      ctx.proceed() ; </programlisting>
      
      <para>Around advices let you change behaviour in an non-invasive way (you do not need
        to touch the packaged extensions).</para>
      
      <section>
        <title>Join Point and Point Cut Syntax</title>
        
        <para>Aspect orientaton is basically about weaving code into different points
          inside the call graph of a software module. Such points are called
          <emphasis>join points</emphasis>. In <emphasis>Xtend</emphasis> the join
          points are the extension invocations (Note that <emphasis>Xpand</emphasis>
          offers a similar feature, see the <emphasis>Xpand</emphasis>
          documentation).</para>
        
        <para>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.</para>
        
        <programlisting>around [pointcut] : expression;</programlisting>
        
        <para>A point cut consists of a fully qualified name and a list of parameter
          declarations.</para>
        
        <section>
          <title>Extensions Name</title>
          
          <para>The extension name part of a point cut must match the fully qualified name
            of the definition of the join point. Such expressions are case sensitive. The
            asterisk character is used to specify wildcards. Some examples:</para>
          
          
          <programlisting>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</programlisting>
          <warning>
          <para>Be careful when using wildcards, because you will get an endless
            recursion, in case you weave an extension, which is called inside the
            advice.</para> </warning>
        </section>
        
        <section>
          <title>Parameter Types</title>
          
          <para>The parameters of the extensions that we want to add our advice to, can also
            be specified in the point cut. The rule is, that the type of the specified
            parameter must be the same or a supertype of the corresponding parameter type
            (the dynamic type at runtime) of the definition to be called.</para>
          
          <para>Additionally, one can set the wildcard at the end of the parameter list, to
            specify that there might be none or more parameters of any kind.</para>
          
          <para>Some examples:</para>
          
          
          <programlisting>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
          </programlisting>
        </section>
        
        <section>
          <title>Proceeding</title>
          
          <para>Inside an advice, you might want to call the underlying definition. This
            can be done using the implicit variable <varname>ctx</varname>, which is of
            the type <type>xtend::AdviceContext</type> and provides an operation
            <methodname>proceed()</methodname> which invokes the underlying
            definition with the original parameters (Note that you might have changed any
            mutable object in the advice before).</para>
          
          <para>If you want to control what parameters are to be passed to the definition,
            you can use the operation <methodname>proceed(List[Object]
            params)</methodname>. You should be aware, that in advices, no type checking
            is done.</para>
          
          <para>Additionally, there are some inspection properties (like
            <varname>name</varname>, <varname>paramTypes</varname>, etc.)
            available.</para>
        </section>
      </section>
      
      <section>
        <title>Workflow configuration</title>
        
        <para>To weave the defined advices into the different join points, you need to
          configure the <classname>XtendComponent</classname> with the qualified
          names of the Extension files containing the advices.</para>
        
        <para>Example:</para>
        
        <programlisting language="xml">
        
        &lt;component
        class="oaw.xtend.XtendComponent"&gt;
        &lt;metaModel class="oaw.type.emf.EmfMetaModel"&gt;
        &lt;metaModelFile value="metamodel1.ecore"/&gt;
        &lt;/metamodel&gt;
        &lt;metaModel class="oaw.type.emf.EmfMetaModel"&gt;
        &lt;metaModelFile value="metamodel2.ecore"/&gt;
        &lt;/metaModel&gt;
        
        &lt;invoke value="my::example::Trafo::transform(inputSlot)"/&gt;
        &lt;outputSlot value="transformedModel"/&gt;
        &lt;value="my::Advices,my::Advices2"/&gt;
        &lt;/component&gt; </programlisting>
      </section>
      
      <section id="xtend_example_introduction">
        <title>Model-to-Model transformation with <emphasis>Xtend</emphasis>
          </title>
        
        <para>This example uses Eclipse EMF as the basis for model-to-model
          transformations. It builds on the <emphasis>emfExample</emphasis>
          documented elsewhere. Please read and install the
          <emphasis>emfExample</emphasis> first.</para>
        
        <para>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.</para>
      </section>
      
      <section id="xtend_example_workflow">
        <title>Workflow</title>
        
        <para>By now, you should know the role and structure of workflow files. Therefore,
          the interesting aspect of the workflow file below is the <emphasis>
          <classname>XtendComponent</classname> </emphasis>.</para>
        
        <programlisting language="xml">
        
        &lt;workflow&gt;
        &lt;property file="workflow.properties"/&gt; ...
        &lt;component class="oaw.xtend.XtendComponent"&gt;
        &lt;metaModel class="oaw.type.emf.EmfMetaModel"&gt;
        &lt;metaModelPackage value="data.DataPackage"/&gt;
        &lt;/metaModel&gt;
        &lt;invoke value="test::Trafo::duplicate(rootElement)"/&gt;
        &lt;outputSlot value="newModel"/&gt;
        &lt;/component&gt; ...
        &lt;/workflow&gt;</programlisting>
        
        <para>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
          <classname>data.DataPackage</classname> as the metamodel.</para>
        
        <para>We then specify which function to invoke for the transformation. The
          statement <classname>test::Trafo::duplicate(rootElement)</classname>
          means to invoke:
          <itemizedlist>
            <listitem> the <classname>duplicate</classname> function taking the
              contents of the <classname>rootElement</classname> slot as a parameter
              </listitem>
            
            <listitem> the function can be found in the <filename>Trafo.ext</filename>
              file </listitem>
            
            <listitem> and that in turn is in the classpath, in the
              <classname>test</classname> package </listitem>
          </itemizedlist></para>
      </section>
      
      <section id="xtend_example_the_transformation">
        <title>The Transformation</title>
        
        <para>The transformation, as mentioned above, can be found in the
          <filename>Trafo.ext</filename> file in the <classname>test</classname>
          package in the <classname>src</classname> folder. Let us walk through the
          file.</para>
        
        <para>So, first we import the metamodel.</para>
        
        <programlisting language="xtend">import data;</programlisting>
        
        <para>The next function is a so-called <classname>create</classname>
          extension. Create extensions, as a side effect when called, create an instance
          of the type given after the <classname>create</classname> keyword. In our
          case, the <classname>duplicate</classname> function creates an instance of
          <classname>DataModel</classname>. This newly created object can be referred
          to in the transformation by <classname>this</classname> (which is why
          <classname>this</classname> is specified behind the type). Since
          <classname>this</classname> can be omitted, we do not have to mention it
          explicitly in the transformation.</para>
        
        <para>The function also takes an instance of <classname>DataModel</classname>
          as its only parameter. That object is referred to in the transformation as
          <varname>s</varname>. So, this function sets the name of the newly created
          <classname>DataModel</classname> 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 <classname>duplicate()</classname>
          operation is called for each <classname>Entity</classname>. This is the next
          function in the transformation.</para>
        
        <programlisting language="xtend">
        
        create DataModel this duplicate(DataModel
        s): entity.addAll(s.entity.duplicate()) -&gt;
        setName(s.name);</programlisting>
        
        <para>The duplication function for entities is also a create extension. This
          time, it creates a new <classname>Entity</classname> for each old
          <classname>Entity</classname> passed in. Again, it copies the name and adds
          duplicates of the attributes and references to the new one.</para>
        
        <programlisting language="xtend">
        
        create Entity this duplicate(Entity old):
        attribute.addAll(old.attribute.duplicate()) -&gt;
        reference.addAll(old.reference.duplicate()) -&gt;
        setName(old.name);</programlisting>
        
        <para>The function that copies the attribute is rather straight forward, but
          ...</para>
        
        <programlisting language="xtend">
        
        create Attribute this duplicate(Attribute
        old): setName(old.name) -&gt; setType(old.type);</programlisting>
        
        <para>... the one for the references is more interesting. Note that a reference,
          while being owned by some <classname>Entity</classname>, also references
          another Entity as its target. So, how do you make sure you do not duplicate the
          target twice? <emphasis>Xtend</emphasis> provides explicit support for this
          kind of situation. <emphasis>Create extensions are only executed once per
          tuple of parameters!</emphasis> So if, for example, the
          <emphasis>Entity</emphasis> behind the target reference had already been
          duplicated by calling the <methodname>duplicate</methodname> function with
          the respective parameter, the next time it will be called <emphasis>the exact
          same object will be returned</emphasis>. This is very useful for graph
          transformations.</para>
        
        <programlisting language="xtend">
        
        create EntityReference this
        duplicate(EntityReference old): setName( old.name ) -&gt; setTarget(
        old.target.duplicate() );</programlisting>
        
        <para>For more information about the <emphasis>Xtend</emphasis> language
          please see the <emphasis> <xref linkend="Xtend_language"/> </emphasis>
          reference documentation.</para>
      </section>
    </section>
  </section>
  
  <section id="xpand_reference_introduction">
    <title> <emphasis>Xpand2</emphasis>
    </title>
    
    <para>The openArchitectureWare framework contains a special language called
      <emphasis>Xpand</emphasis> <indexterm>
      <primary>Xpand</primary> </indexterm> that is used in templates to control the
      output generation. This documentation describes the general syntax and semantics
      of the <emphasis>Xpand</emphasis> language.</para>
    
    <para>Typing the <foreignphrase>guillemets</foreignphrase> <indexterm>
      <primary>guillemets</primary> </indexterm> (« and ») used in the templates is
      supported by the Eclipse editor: which provides keyboard shortcuts with <keycombo
        action="simul"> <keycap>Ctrl</keycap> <keycap>&lt; </keycap> </keycombo>
      and <keycombo action="simul"> <keycap>Ctrl</keycap> <keycap>&gt; </keycap>
      </keycombo>.</para>
    
    <section id="xpand_reference_template_files_and_ecoding">
      <title>Template files and encoding</title>
      
      <para>Templates are stored in files with the extension <filename>.xpt</filename>
        <indexterm>
        <primary>.xpt file extension</primary> </indexterm>. Template files must
        reside on the Java classpath of the generator process.</para>
      
      <para>Almost all characters used in the standard syntax are part of
        <emphasis>ASCII</emphasis> and should therefore be available in any encoding.
        The only limitation are the tag brackets ( <emphasis>guillemets</emphasis>),
        for which the characters "«" (Unicode <varname>00AB</varname>) and "»" (Unicode
        <varname>00BB</varname>) are used. So for reading templates, an encoding should
        be used that supports these characters (e.g. <varname>ISO-8859-1</varname> or
        <varname>UTF-8</varname>).</para>
      
      <para>Names of properties, templates, namespaces etc. must only contain letters,
        numbers and underscores.</para>
    </section>
    
    <section id="xpand_reference_general_structure_of_template_files">
      <title>General structure of template files</title>
      
      <para>Here is a first example of a template:
        
        
        <programlisting>«IMPORT meta::model» «EXTENSION my::ExtensionFile»
        «DEFINE javaClass FOR Entity» «FILE fileName()» package «javaPackage()»;
        public class «name» { // implementation } «ENDFILE»
        «ENDDEFINE»</programlisting>
        A template file consists of any number of IMPORT statements, followed by any number
        of EXTENSION statements, followed by one or more DEFINE blocks (called
        definitions).</para>
    </section>
    
    <section id="xpand_reference_statements_of_the_expand_language">
      <title>Statements of the <emphasis>Xpand</emphasis> language</title>
      
      <section id="xpand_reference_import">
        <title>IMPORT <indexterm>
          <primary>IMPORT</primary> </indexterm></title>
        
        <para>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.
          <programlisting>«IMPORT meta::model»</programlisting>This one imports
          the namespace <varname>meta::model</varname>. 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
          <varname>import meta.model.*</varname>.</para>
      </section>
      
      <section id="xpand_reference_extension">
        <title>EXTENSION <indexterm>
          <primary>EXTENSION</primary> </indexterm></title>
        
        <para>Metamodels are typically described in a structural way (graphical, or
          hierarchical, etc.) . A shortcoming of this is that it is difficult to specify
          additional behaviour (query operations, derived properties, etc.). Also, it
          is a good idea not to pollute the metamodel with target platform specific
          information (e.g. Java type names, packages, getter and setter names,
          etc.).</para>
        
        <para>Extensions provide a flexible and convenient way of defining additional
          features of metaclasses. You do this by using the <emphasis>Extend</emphasis>
          <indexterm>
          <primary>Extend</primary> </indexterm> language. (See the corresponding
          reference documentation for details)</para>
        
        <para>An EXTENSION import points to the <emphasis>Xtend</emphasis> file
          containing the required extensions:
          <programlisting>«EXTENSION my::ExtensionFile»</programlisting> Note
          that extension files have to reside on the Java classpath <indexterm>
          <primary>classpath</primary> </indexterm>, too. Therefore, they use the
          same namespace mechanism (and syntax) as types and template files.</para>
      </section>
      
      <section id="xpand_reference_define">
        <title>DEFINE <indexterm>
          <primary>DEFINE</primary> </indexterm></title>
        
        <para>The central concept of <emphasis>Xpand</emphasis> is the
          <code>DEFINE</code> block, also called a template. This is the smallest
          identifiable unit in a template file <indexterm>
          <primary>template file</primary> </indexterm>. The tag consists of a name, an
          optional comma-separated parameter list, as well as the name of the metamodel
          class for which the template is defined.
          
          
          <programlisting>«DEFINE templateName(formalParameterList) FOR MetaClass» a
          sequence of statements «ENDDEFINE»</programlisting>To
          some extent, templates can be seen as special methods of the metaclass &ndash;
          there is always an implicit <emphasis>this</emphasis> parameter which can be
          used to address the "underlying" model element; in our example above, this model
          element is "MetaClass".</para>
        
        <para>As in Java, a formal parameter list entry consists of the type followed by the
          name of that parameter.</para>
        
        <para>The body of a template can contain a sequence of other statements including
          any text.</para>
        
        <para>A full parametric polymorphism <indexterm>
          <primary>polymorphism</primary> </indexterm> <indexterm>
          <primary>template</primary>
          
          <secondary>polymorphism</secondary> </indexterm> is available for
          templates. If there are two templates with the same name that are defined for two
          metaclasses which inherit from the same superclass,
          <emphasis>Xpand</emphasis> will use the corresponding subclass template, in
          case the template is called for the superclass. Vice versa, the template of the
          superclass 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.</para>
        
        <para>So, let us assume you have the following metamodel:
          <figure>
            <title>Sample metamodel</title>
            
            <mediaobject>
              <imageobject role="fo">
                <imagedata fileref="images/Xpand/metamodelexample.gif"
                  scale="80"/>
              </imageobject>
              
              <imageobject role="html">
                <imagedata
                  fileref="images/Xpand/metamodelexample.gif"/>
              </imageobject>
            </mediaobject>
          </figure></para>
        
        <para>Assume further, you would have a model which contains a collection of
          <classname>A</classname>, <classname>B</classname> and
          <classname>C</classname> instances in the property
          <methodname>listOfAs</methodname>. Then, you can write the following
          template:
          
          
          <programlisting>«DEFINE someOtherDefine FOR SomeMetaClass» «EXPAND
          implClass FOREACH listOfAs» «ENDDEFINE»
          «DEFINE implClass FOR A» // this is the code generated for the superclass 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»</programlisting>So
          for each <classname>B</classname> in the list, the template defined for
          <classname>B</classname> is executed, for each <classname>C</classname> in
          the collection the template defined for <emphasis> <classname>C</classname>
          </emphasis> is invoked, and for all others (which are then instances of
          <classname>A</classname>) the default template is executed.</para>
      </section>
      
      <section id="xpand_reference_file">
        <title>FILE <indexterm>
          <primary>FILE</primary> </indexterm></title>
        
        <para>The <varname>FILE</varname> statement redirects the output generated
          from its body statements to the specified target.
          
          
          <programlisting>«FILE expression [outletName]» a sequence of statements
          «ENDFILE»</programlisting>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 <indexterm>
          <primary>outlet</primary> </indexterm>. (See the configuration section for
          a description of outlets).</para>
        
        <para>The body of a <varname>FILE</varname> statement can contain any other
          statements. Example:
          
          
          <programlisting>«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»</programlisting></para>
      </section>
      
      <section id="xpand_reference_expand">
        <title>EXPAND <indexterm>
          <primary>EXPAND</primary> </indexterm></title>
        
        <para>The <varname>EXPAND</varname> statement "expands" another
          <varname>DEFINE</varname> 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.
          
          
          <programlisting>«EXPAND definitionName [(parameterList)] [FOR expression |
          FOREACH expression [SEPARATOR expression] ]»</programlisting>The
          various alternative syntaxes are explained below.</para>
        
        <section id="xpand_reference_names">
          <title>Names</title>
          
          <para>If the <emphasis>definitionName</emphasis> is a simple unqualified
            name, the corresponding <varname>DEFINE</varname> block must be in the same
            template file.</para>
          
          <para>If the called definition is not contained in the same template file, the
            name of the template file must be specified. As usual, the double colon is used
            to delimit namespaces.
            
            
            <programlisting>«EXPAND TemplateFile::definitionName FOR
            myModelElement»</programlisting>Note
            that you would need to import the namespace <indexterm>
            <primary>namespace</primary>
            
            <secondary>import</secondary> </indexterm> of the template file (if there
            is one). For instance, if the template file resides in the java package
            <varname>my.templates</varname>, there are two alternatives. You could
            either write
            
            
            <programlisting>«IMPORT my::templates» ... «EXPAND
            TemplateFile::definitionName FOR myModelElement»</programlisting>
            or
            
            
            <programlisting>«EXPAND my::templates::TemplateFile::definitionName
            FOR myModelElement»</programlisting></para>
        </section>
      </section>
      
      <section id="xpand_reference_for_vs_foreach">
        <title>FOR vs. FOREACH <indexterm>
          <primary>FOR</primary> </indexterm> <indexterm>
          <primary>FOREACH</primary> </indexterm></title>
        
        <para>If <varname>FOR</varname> or <varname>FOREACH</varname> is omitted the
          other template is called <varname>FOR this</varname>.
          
          
          <programlisting>«EXPAND TemplateFile::definitionName»</programlisting>
          equals
          
          
          <programlisting>«EXPAND TemplateFile::definitionName FOR
          this»</programlisting>
          If <varname>FOR</varname> is specified, the definition is executed for the
          result of the target expression.
          <programlisting>«EXPAND myDef FOR entity»</programlisting>If
          <varname>FOREACH</varname> is specified, the target expression must
          evaluate to a collection type <indexterm>
          <primary>collection type</primary> </indexterm>. In this case, the
          specified definition is executed for each element of that collection.
          
          
          <programlisting>«EXPAND myDef FOREACH entity.allAttributes»
          </programlisting></para>
        
        <section id="xpand_reference_specifying_a_separator">
          <title>Specifying a Separator <indexterm>
            <primary>separator</primary> </indexterm></title>
          
          <para>If a definition is to be expanded <varname>FOREACH</varname> element of
            the target expression it is possible to specify a
            <varname>SEPARATOR</varname> expression:
            
            
            <programlisting>«EXPAND paramTypeAndName FOREACH params SEPARATOR
            ','»</programlisting>The
            result of the separator expression <indexterm>
            <primary>separator</primary>
            
            <secondary>expression</secondary> </indexterm> will be written to the
            output between each evaluation of the target definition (not
            <emphasis>after</emphasis> each one, but rather only in
            <emphasis>between</emphasis> two elements. This comes in handy for things
            such as comma-separated parameter lists).</para>
          
          <para>An <varname>EvaluationException</varname> will be thrown if the
            specified target expression cannot be evaluated to an existing element of the
            instantiated model or no suitable <varname>DEFINE</varname> block can be
            found.</para>
        </section>
      </section>
      
      <section id="xpand_reference_foreach">
        <title>FOREACH <indexterm>
          <primary>FOREACH</primary> </indexterm></title>
        
        <para>This statement expands the body of the <varname>FOREACH</varname> block
          for each element of the target collection <indexterm>
          <primary>collection</primary> </indexterm> that results from the
          expression. The current element is bound to a variable with the specified name in
          the current context.
          
          
          <programlisting>«FOREACH expression AS variableName [ITERATOR iterName]
          [SEPARATOR expression]» a sequence of statements using variableName to access
          the current element of the iteration «ENDFOREACH»</programlisting>The
          body of a <varname>FOREACH</varname> block can contain any other statements;
          specifically <varname>FOREACH</varname> statements may be nested. If
          <varname>ITERATOR</varname> <indexterm>
          <primary>ITERATOR</primary> </indexterm> name is specified, an object of the
          type <emphasis>xpand2::Iterator</emphasis> (see API doc for details) is
          accessible using the specified name. The <varname>SEPARATOR</varname>
          expression works in the same way as the one for <varname>EXPAND</varname>
          .</para>
        
        <para>Example:
          
          
          <programlisting>«FOREACH {'A','B','C'} AS c ITERATOR iter SEPARATOR ','»
          «iter.counter1» : «c» «ENDFOREACH»</programlisting>The
          evaluation of the above statement results in the following text:
          <programlisting>1 : A, 2 : B, 3 : C</programlisting></para>
      </section>
      
      <section id="xpand_reference_if">
        <title>IF <indexterm>
          <primary>IF</primary> </indexterm></title>
        
        <para>The <varname>IF</varname> statement supports conditional expansion.
          Any number of <varname>ELSEIF</varname> <indexterm>
          <primary>ELSEIF</primary> </indexterm> statements are allowed. The
          <varname>ELSE</varname> block is optional. Every <varname>IF</varname>
          statement must be closed with an <varname>ENDIF</varname> <indexterm>
          <primary>ENDIF</primary> </indexterm>. The body of an
          <varname>IF</varname> block can contain any other statement, specifically,
          <varname>IF</varname> statements may be nested.
          
          
          <programlisting>«IF expression» a sequence of statements [ «ELSEIF expression»
          ] a sequence of statements ] [ «ELSE» a sequence of statements ]
          «ENDIF»</programlisting></para>
      </section>
      
      <section id="xpand_reference_protect">
        <title>PROTECT <indexterm>
          <primary>PROTECT</primary> </indexterm></title>
        
        <para>Protected Regions <indexterm>
          <primary>protected regions</primary> </indexterm> 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.
          
          
          <programlisting>«PROTECT CSTART expression CEND expression ID expression
          (DISABLE)?» a sequence of statements «ENDPROTECT»</programlisting>
          The values of CSTART <indexterm>
          <primary>CSTART</primary> </indexterm> and CEND <indexterm>
          <primary>CEND</primary> </indexterm> 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.
          <emphasis>"/*"</emphasis> and <emphasis>"*/"</emphasis> for Java). The
          following is an example for Java:
          
          
          <programlisting>«PROTECT CSTART "/*" CEND "*/" ID ElementsUniqueID» here goes
          some content «ENDPROTECT»</programlisting>The
          ID is set by the <varname>ID</varname> expression and must be globally unique
          (at least for one complete pass of the generator).</para>
        
        <para>Generated target code looks like this:
          
          
          <programlisting>public class Person { /*PROTECTED REGION ID(Person) ENABLED
          START*/ This protected region 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*/ }</programlisting>
          Protected regions are generated in enabled state <indexterm>
          <primary>protected regions</primary>
          
          <secondary>enable</secondary> </indexterm> by default. Unless you manually
          disable <indexterm>
          <primary>protected regions</primary>
          
          <secondary>disable</secondary> </indexterm> them, by removing the
          <varname>ENABLED</varname> keyword, they will always be preserved.</para>
        
        <para>If you want the generator to generate disabled protected regions, you need
          to add the <varname>DISABLE</varname> keyword inside the declaration:
          
          
          <programlisting>«PROTECT CSTART '/*' CEND '*/' ID this.name
          DISABLE»</programlisting></para>
      </section>
      
      <section id="xpand_reference_let">
        <title>LET</title>
        
        <para> <varname>LET</varname> lets you specify local variables:
          
          
          <programlisting>«LET expression AS variableName» a sequence of statements
          «ENDLET»</programlisting>During
          the expansion of the body of the <varname>LET</varname> <indexterm>
          <primary>LET</primary> </indexterm> 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
          <varname>LET</varname> block. Example:
          
          
          <programlisting>«LET packageName + "." + className AS fqn» the fully qualified
          name is: «fqn»; «ENDLET»</programlisting></para>
      </section>
      
      <section id="xpand_reference_error">
        <title>ERROR <indexterm>
          <primary>ERROR</primary> </indexterm></title>
        
        <para>The <varname>ERROR</varname> statement aborts the evaluation of the
          templates by throwing an <varname>XpandException</varname> <indexterm>
          <primary>XpandException</primary> </indexterm> with the specified
          message.
          <programlisting>«ERROR expression»</programlisting>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.</para>
      </section>
      
      <section id="xpand_reference_comments">
        <title>Comments <indexterm>
          <primary>comments</primary> </indexterm></title>
        
        <para>Comments are only allowed outside of tags.
          <programlisting>«REM» text comment «ENDREM»</programlisting>Comments
          may not contain a REM <indexterm>
          <primary>REM</primary> </indexterm> tag, this implies that comments are not
          nestable. A comment may not have a white space between the REM keyword and its
          brackets. Example:
          
          
          <programlisting>«REM»«LET expression AS variableName»«ENDREM» a sequence of
          statements «REM» «variableName.stuff» «ENDLET»«ENDREM»</programlisting>
          </para>
      </section>
      
      <section id="xpand_reference_expression_statement">
        <title>Expression Statement <indexterm>
          <primary>expression statements</primary> </indexterm></title>
        
        <para>Expressions support processing of the information provided by the
          instantiated metamodel. Xpand provides powerful expressions for selection,
          aggregation, and navigation. Xpand uses the expressions sublanguage 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 the
          <varname>toString()</varname> method of
          <varname>java.lang.Object</varname>). Example:
          <programlisting>public class «this.name» {</programlisting> All
          expressions defined by the oArchitectureWare expressions sublanguage are
          also available in Xpand. You can invoke imported extensions. (See the
          <emphasis> <xref linkend="r10_expressions_language"/> </emphasis> and
          <emphasis> <xref linkend="Xtend_language"/> language
          reference</emphasis> for more details).</para>
      </section>
      
      <section id="xpand_reference_controlling_generation_of_white_space">
        <title>Controlling generation of white space</title>
        
        <para>If you want to omit the output of superfluous whitespace <indexterm>
          <primary>whitespace</primary>
          
          <secondary>omit</secondary> </indexterm> you can add a minus sign just before
          any closing bracket. Example:
          
          
          <programlisting>«FILE InterfaceName + ".java"-» «IF hasPackage-» package
          «InterfacePackageName»; «ENDIF-» ... «ENDFILE»</programlisting>The
          generated file would start with two new lines (one after the
          <varname>FILE</varname> and one after the <varname>IF</varname> statement)
          if the minus characters had not been set.</para>
        
        <para>In general, this mechanism works as follows: If a statement (or comment)
          ends with such a minus all preceding whitespace up to the newline <indexterm>
          <primary>newline</primary> </indexterm> character (excluded!) is removed.
          Additionally all following whitespace including the first newline character
          (\r\n is handled as one character) is also removed.</para>
      </section>
    </section>
    
    <section id="xpand_reference_aspect-oriented_programming_in_xpand">
      <title>Aspect-Oriented Programming in <emphasis>Xpand</emphasis> <indexterm>
        <primary>AOP</primary> </indexterm></title>
      
      <para>Using the workflow engine it is now possible to package (
        <emphasis>e.g.</emphasis> zip) a written generator and deliver it as a kind of
        black box. If you want to use such a generator but need to change some small
        generation stuff, you can make use of the <varname>AROUND</varname> <indexterm>
        <primary>AROUND</primary> </indexterm> aspects.
        
        
        <programlisting>«AROUND qualifiedDefinitionName(parameterList)? FOR type» a
        sequence of statements «ENDAROUND» </programlisting>
        <varname>AROUND</varname> lets you add templates in an non-invasive way (you do
        not need to touch the generator templates). Because aspects are invasive, a
        template file containing <varname>AROUND</varname> aspects must be wrapped by
        configuration (see next section).</para>
      
      <section id="xpand_reference_join_point_and_cut_syntax">
        <title>Join Point <indexterm>
          <primary>join point</primary> </indexterm> <indexterm>
          <primary>AOP</primary>
          
          <secondary>join point</secondary> </indexterm> and Point Cut <indexterm>
          <primary>point cut</primary> </indexterm> <indexterm>
          <primary>AOP</primary>
          
          <secondary>point cut</secondary> </indexterm> Syntax</title>
        
        <para>AOP is basically about weaving code into different points inside the call
          graph of a software module. Such points are called <emphasis>Join
          Points</emphasis>. In <emphasis>Xpand</emphasis>, there is only one join
          point so far: a call to a definition.</para>
        
        <para>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 <emphasis>point cut</emphasis>.
          
          
          <programlisting>«AROUND [pointcut]» do stuff «ENDAROUND»</programlisting>
          A pointcut consists of a fully qualified name, parameter types and the target
          type.</para>
        
        <section id="xpand_reference_definition_name">
          <title>Definition Name</title>
          
          <para>The definition name part of a point cut must match the fully qualified name
            of the join point definition. Such expressions are case sensitive. The
            asterisk character is used to specify wildcards.</para>
          
          <para>Some examples:
            
            
            <programlisting>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</programlisting></para>
        </section>
        
        <section id="xpand_reference_parameter_types">
          <title>Parameter Types</title>
          
          <para>The parameters of the definitions we want to add our advice to, can also be
            specified in the point cut. The rule is that the type of the specified parameter
            must be the same or a supertype of the corresponding parameter type (the
            dynamic type at runtime!) of the definition to be called.</para>
          
          <para>Additionally, one can set a wildcard at the end of the parameter list, to
            specify that there might be an arbitrary number of parameters of any
            kind.</para>
          
          <para>Some examples:
            
            
            <programlisting>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</programlisting></para>
        </section>
        
        <section id="xpand_reference_target_type">
          <title>Target Type</title>
          
          <para>Finally, we have to specify the target type. This is straightforward:
            
            
            <programlisting>my::Templ::def() FOR Object// templ def for any target type
            my::Templ::def() FOR Entity// templ def objects of type
            Entity</programlisting></para>
        </section>
      </section>
      
      <section id="xpand_reference_proceeding">
        <title>Proceeding</title>
        
        <para>Inside an advice, you might want to call the underlying definition. This can
          be done using the implicit variable <varname>targetDef</varname>, which is of
          the type <type>xpand2::Definition</type> and which provides an operation
          <methodname>proceed()</methodname>that invokes the underlying definition
          with the original parameters (Note that you might have changed any mutable
          object in the advice before).</para>
        
        <para>If you want to control, what parameters are to be passed to the definition,
          you can use the operation <methodname>proceed</methodname>(
          <classname>Object</classname> <varname>target</varname>,
          <classname>List</classname> <varname>params</varname>). Please keep in
          mind that no type checking is done in this context.</para>
        
        <para>Additionally, there are some inspection properties (like
          <varname>name</varname>, <varname>paramTypes</varname>, etc.)
          available.</para>
      </section>
    </section>
    
    <section id="xpand_reference_generator_workflow_component">
      <title>Generator Workflow Component</title>
      
      <para>This section describes the workflow component that is provided to perform the
        code generation, i.e. run the templates. You should have a basic idea of how the
        workflow engine works. (see <emphasis> <phrase condition="main"> <xref
          linkend="workflow_reference"/></phrase><phrase
          condition="individual">Workflow reference</phrase></emphasis>). A
        simple generator component configuration could look as follows:
        
        
        <programlisting>&lt;component class="oaw.xpand2.Generator"&gt;
        &lt;fileEncoding value="ISO-8859-1"/&gt;
        &lt;metaModel class="oaw.type.emf.EmfMetaModel"&gt;
        &lt;metaModelPackage value="org.eclipse.emf.ecore.EcorePackage"/&gt;
        &lt;/metaModel&gt;
        &lt;expand value="example::Java::all FOR myModel"/&gt;
        
        &lt;!-- aop configuration --&gt;
        &lt;advices value='example::Advices1, example::Advices2'/&gt;
        
        &lt;!-- output configuration --&gt;
        &lt;outlet path='main/src-gen'/&gt;
        &lt;outlet name='TO_SRC' path='main/src' overwrite='false'/&gt;
        &lt;beautifier class="oaw.xpand2.output.JavaBeautifier"/&gt;
        &lt;beautifier class="oaw.xpand2.output.XmlBeautifier"/&gt;
        
        &lt;!-- protected regions configuration --&gt;
        &lt;prSrcPaths value="main/src"/&gt;
        &lt;prDefaultExcludes value="false"/&gt;
        &lt;prExcludes value="*.xml"/&gt;
        &lt;/component&gt;</programlisting>Now,
        let us go through the different properties one by one.</para>
      
      <section id="xpand_reference_main_configuration">
        <title>Main configuration</title>
        
        <para>The first thing to note is that the qualified Java name of the component is
          <varname>org.openarchitectureware.xpand2.Generator2</varname>. One can
          use the shortcut <varname>oaw</varname> instead of a preceding
          <varname>org.openarchitectureware</varname>. The workflow engine will
          resolve it.</para>
      </section>
      
      <section id="xpand_reference_encoding">
        <title>Encoding</title>
        
        <para>For <emphasis>Xpand</emphasis>, it is important to have the file encoding
          in mind because of the <foreignphrase>guillemet</foreignphrase> characters
          used to delimit keywords and property access. The
          <varname>fileEncoding</varname> 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.</para>
      </section>
      
      <section id="xpand_reference_metamodel">
        <title>Metamodel</title>
        
        <para>The property <varname>metaModel</varname> is used to tell the generator
          engine on which metamodels the <emphasis>Xpand</emphasis> templates should
          be evaluated. One can specify more than one metamodel here. Metamodel
          implementations are required by the expression framework (see <emphasis>
            <xref linkend="r10_expressions_language"/> </emphasis>) used by
          <emphasis>Xpand2</emphasis>. In the example above we configured the Ecore
          metamodel using the <emphasis>EMFMetaModel</emphasis> implementation
          shipped with the core part of the openArchitectureWare 4 release.</para>
        
        <para>A mandatory configuration is the <varname>expand</varname> property. It
          expects a syntax similar to that of the <varname>EXPAND</varname> statement
          (described above). The only difference is that we omit the
          <varname>EXPAND</varname> keyword. Instead, we specify the name of the
          property. Examples:
          
          
          <programlisting>&lt;expand value="Template::define FOR
          mySlot"/&gt;</programlisting>
          or:
          
          
          <programlisting>&lt;expand value="Template::define('foo') FOREACH
          {mySlot1,mySlot2}"/&gt;</programlisting>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 <varname>'mySlot'</varname>, <varname>'mySlot1'</varname>
          and <varname>'mySlot2'</varname>. It is also possible to specify some complex
          expressions here. If, for instance, the slot <varname>myModel</varname>
          contains a collection of model elements one could write:
          
          
          <programlisting>&lt;expand value="Template::define FOREACH
          myModel.typeSelect(Entity)"/&gt;</programlisting>This
          selects all elements of type <emphasis>Entity</emphasis> contained in the
          collection stored in the <varname>myModel</varname> slot.</para>
      </section>
      
      <section id="xpand_reference_output_configuration">
        <title>Output configuration</title>
        
        <para>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:
          
          
          <programlisting>&lt;component class="oaw.xpand2.Generator2"&gt; ...
          &lt;outlet path='main/src-gen'/&gt;
          &lt;outlet name='TO_SRC' path='main/src' overwrite='false'/&gt; ...
          &lt;/component&gt;</programlisting>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:
          
          
          <programlisting>«FILE 'test/note.txt'» # this goes to the default outlet
          «ENDFILE»</programlisting>The
          configured base path is ' <filename>main/src-gen</filename>', so the file
          from above would go to ' <filename>main/src-gen/test/note.txt</filename>
          '.</para>
        
        <para>The second outlet has a <varname>name</varname> ('TO_SRC') specified.
          Additionally the flag <varname>overwrite</varname> is set to
          <varname>false</varname> (defaults to <varname>true</varname>). The
          following <emphasis>Xpand</emphasis> fragment
          
          
          <programlisting>«FILE 'test/note.txt' TO_SRC» # this goes to the TO_SRC outlet
          «ENDFILE»</programlisting>would
          cause the generator to write the contents to '
          <filename>main/src/test/note.txt</filename>' if the file does not already
          exist (the <varname>overwrite</varname> flag).</para>
        
        <para>Another option called <varname>append</varname> (defaults to
          <varname>false</varname>) causes the generator to append the generated text
          to an existing file. If <varname>overwrite</varname> is set to
          <varname>false</varname> this flag has no effect.</para>
      </section>
      
      <section id="xpand_reference_beautifier">
        <title>Beautifier</title>
        
        <para>Beautifying the generated code is a good idea. It is very important that
          generated code looks 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
          &ndash; 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).</para>
        
        <para>The <emphasis>Xpand</emphasis> workflow component can be configured
          with multiple beautifiers:
          
          
          <programlisting>&lt;beautifier
          class="org.openarchitectureware.xpand2.output.JavaBeautifier"/&gt;
          &lt;beautifier
          class="org.openarchitectureware.xpand2.output.XmlBeautifier"/&gt;</programlisting>
          These are the two beautifiers delivered with <emphasis>Xpand</emphasis>. If
          you want to use your own beautifier, you would just need to implement the
          following Java interface:
          
          
          <programlisting>package org.openarchitectureware.xpand2.output;
          public interface PostProcessor { public void
          beforeWriteAndClose(FileHandle handle); public void
          afterClose(FileHandle handle); }</programlisting>The
          <varname>beforeWriteAndClose</varname> method is called for each
          <varname>ENDFILE</varname> statement.</para>
        
        <section id="xpand_reference_javabeautifier">
          <title>JavaBeautifier</title>
          
          <para>The JavaBeautifier is based on the Eclipse Java formatter provides base
            beautifying for Java files.</para>
        </section>
        
        <section id="xpand_reference_xmlbeautifier">
          <title>XmlBeautifier</title>
          
          <para>The XmlBeautifier is based on <emphasis>dom4j</emphasis> and provides
            a single option <varname>fileExtensions</varname> (defaults to "
            <filename>.xml</filename>, <filename>.xsl</filename>,
            <filename>.wsdd</filename>, <filename>.wsdl</filename>") used to
            specify which files should be pretty-printed.</para>
        </section>
      </section>
      
      <section id="xpand_reference_protected_region_configuration">
        <title>Protected Region Configuration</title>
        
        <para>Finally, you need to configure the protected region resolver, if you want to
          use protected regions.
          
          
          <programlisting>&lt;prSrcPaths value="main/src"/&gt;
          &lt;prDefaultExcludes value="false"/&gt;
          &lt;prExcludes value="*.xml"/&gt;</programlisting>The
          <emphasis>prSrcPaths</emphasis> property points to a comma-separated list
          of directories. The protected region resolver will scan these directories for
          files containing activated protected regions.</para>
        
        <para>There are several file names which are excluded by default:
          
          
          <programlisting>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</programlisting>
          If you do not want to exclude any of these, you must set
          <varname>prDefaultExcludes</varname> to false.
          
          
          <programlisting>&lt;prDefaultExcludes
          value="false"/&gt;</programlisting>
          If you want to add additional excludes, you should use the prExcludes property.
          
          
          <programlisting>&lt;prExcludes
          value="*.xml,*.hbm"/&gt;</programlisting></para>
        <note>
        <para>It is bad practice to mix generated and non-generated code in one artifact.
          Instead of using protected regions, you should try to leverage the extension
          features of the used target language (inheritance, inclusion, references,
          etc.) wherever possible. It is very rare that the use of protected regions is an
          appropriate solution.</para> </note>
      </section>
    </section>
    
    <section id="aop_template_introduction">
      <title>Example for using Aspect-Oriented Programming in
        <emphasis>Xpand</emphasis></title>
      
      <para>This example shows how to use aspect-oriented programming techniques in
        <emphasis>Xpand</emphasis> templates. It is applicable to EMF based and
        <emphasis>Classic</emphasis> systems. However, we explain the idea based on the
        <emphasis>emfExample</emphasis> &ndash; hence you should read that
        before.</para>
    </section>
    
    <section id="aop_template_the_problem">
      <title>The Problem</title>
      
      <para>There are many circumstances when template-AOP is useful. Here are two
        examples:</para>
      
      <para> <emphasis role="bold">Scenario 1:</emphasis> Assume you have a nice
        generator that generates certain artifacts. The generator (or cartridge) might
        be a third party product, delivered in a single JAR file. Still you might want to
        adapt certain aspects of the generation process &ndash; <emphasis>without
        modifying the original generator</emphasis>.</para>
      
      <para> <emphasis role="bold">Scenario 2:</emphasis> You are building a family of
        generators that can generate variations of the generate code, e.g.
        Implementations for different embedded platforms. In such a scenario, you need to
        be able to express those differences (variabilities) sensibly without creating a
        non-understandable chaos of <emphasis>if</emphasis> statements in the
        templates.</para>
    </section>
    
    <section id="aop_template_example">
      <title>Example</title>
      
      <para>To illustrate the idea of extending a generator without "touching" it, let us
        create a new project called
        <classname>oaw4.demo.emf.datamodel.generator-aop</classname>. The idea is
        that it will "extend" the original
        <classname>oaw4.demo.emf.datamodel.generator</classname> project
        introduced in the <emphasis>emfExample</emphasis>. So this new projects needs
        to have a project dependency to the former one.</para>
      
      <section id="aop_template_example_templates">
        <title>Templates</title>
        
        <para>An AOP system always needs to define a join point model; this is, you have to
          define, at which locations of a (template) program you can add additional
          (template) code. In Xpand, the join points are simply templates (i.e.
          <emphasis>DEFINE .. ENDDEFINE</emphasis>) blocks. An "aspect template" can
          be declared <emphasis>AROUND</emphasis> previously existing templates. If
          you take a look at the
          <classname>oaw4.demo.emf.datamodel.generator</classname> source folder
          of the project, you can find the <filename>Root.xpt</filename> template file.
          Inside, you can find a template called <classname>Impl</classname> that
          generates the implementation of the JavaBean.</para>
        
        <programlisting language="Xpand">
        
        «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»</programlisting>
        
        <para>What we now want to do is as follows: Whenever the
          <emphasis>Impl</emphasis> template is executed, we want to run an additional
          template that generates additional code (for example, some kind of meta
          information for frameworks &ndash; the specific code is not important for the
          example here).</para>
        
        <para>So, in our new project, we define the following template file:</para>
        
        <programlisting language="Xpand">
        
        «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»</programlisting>
        
        <para>So, this new template wraps around the existing template called
          <classname>Impl</classname> It first generates additional code and then
          forwards the execution to the original template using
          <methodname>targetDef.proceed()</methodname>. So, in effect, this is a
          <varname>BEFORE</varname> advice. Moving the
          <methodname>proceed</methodname> statement to the beginning makes it an
          <varname>AFTER</varname> advice, omitting it, makes it an override.</para>
      </section>
      
      <section id="aop_template_example_workflow_file">
        <title>Workflow File</title>
        
        <para>Let us take a look at the workflow file to run this generator:</para>
        
        <programlisting language="xml">
        
        &lt;workflow&gt;
        &lt;cartridge file="workflow.oaw"/&gt;
        &lt;component adviceTarget="generator" id="reflectionAdvice"
        class="oaw.xpand2.GeneratorAdvice"&gt;
        &lt;advices value="templates::Advices"/&gt;
        &lt;/component&gt;
        &lt;/workflow&gt;</programlisting>
        
        <para>Mainly, what we do here, is to call the original workflow file. It has to be
          available from the classpath. After this cartridge call, we define an
          additional workflow component, a so called <emphasis>advice
          component</emphasis>. It specifies <emphasis>generator</emphasis> as its
          <emphasis>adviceTarget</emphasis>. That means, that all the properties we
          define inside this advice component will be added to the component referenced by
          name in the <emphasis>adviceTarget</emphasis> instead. In our case, this is
          the generator. So, in effect, we add the
          &lt;advices value="templates::Advices" /&gt; to the original generator
          component (without invasively modifying its own definition). This
          contributes the advice templates to the generator.</para>
      </section>
      
      <section id="aop_template_example_running_the_new_generator">
        <title>Running the new generator</title>
        
        <para>Running the generator produces the following code:</para>
        
        <programlisting language="Java">
        
        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; } }</programlisting>
      </section>
    </section>
    
    <section id="aop_template_more_ao">
      <title>More Aspect Orientation</title>
      
      <para>In general, the syntax for the <emphasis>AROUND</emphasis> construct is as
        follows:</para>
      
      <programlisting language="Expand">
      
      &lt;&lt;AROUND
      fullyQualifiedDefinitionNameWithWildcards (Paramlist (*)?) FOR
      TypeName&gt;&gt; do Stuff
      &lt;&lt;ENDAROUND&gt;&gt;</programlisting>
      
      <para>Here are some examples:</para>
      
      <programlisting>&lt;&lt;AROUND *(*) FOR Object&gt;&gt;</programlisting>
      
      <para>matches all templates</para>
      
      
      <programlisting>&lt;&lt;AROUND *define(*) FOR Object&gt;&gt;</programlisting>
      
      <para>matches all templates with <emphasis>define</emphasis> at the end of its
        name and any number of parameters</para>
      
      
      <programlisting>&lt;&lt;AROUND org::oaw::* FOR
      Entity&gt;&gt;</programlisting>
      
      <para>matches all templates with namespace <emphasis>org::oaw::</emphasis>
        that do not have any parameters and whose type is Entity or a subclass</para>
      
      
      <programlisting>&lt;&lt;AROUND *(String s) FOR Object&gt;&gt;</programlisting>
      
      <para>matches all templates that have exactly one <classname>String</classname>
        parameter</para>
      
      
      <programlisting>&lt;&lt;AROUND *(String s,*) FOR
      Object&gt;&gt;</programlisting>
      
      <para>matches all templates that have at least one <classname>String</classname>
        parameter</para>
      
      
      <programlisting>&lt;&lt;AROUND my::Template::definition(String s) FOR
      Entity&gt;&gt;</programlisting>
      
      <para>matches exactly this single definition</para>
      
      <para>Inside an <varname>AROUND</varname>, there is the variable
        <varname>targetDef</varname>, which has the type
        <classname>xpand2::Definition</classname>. On this variable, you can call
        <methodname>proceed</methodname>, and also query a number of other
        things:</para>
      
      
      <programlisting>&lt;&lt;AROUND my::Template::definition(String s) FOR
      String&gt;&gt; log('invoking '+&lt;&lt;targetDef.name&gt;&gt;+' with '+this)
      &lt;&lt;targetDef.proceed()&gt;&gt;
      &lt;&lt;ENDAROUND&gt;&gt;</programlisting>
    </section>
  </section>
  
  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
    href="../content/builtin_api.xml"/>
</chapter>