summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorpschonbac2008-01-21 18:58:49 (EST)
committerpschonbac2008-01-21 18:58:49 (EST)
commit926823f27920e20a5dcc41a04f1210f669411df0 (patch)
treedbe6927ced847e251cbf6c8efcd85e863306adf9
parented2fc09343359880794d9f4c1c44ca2806aecb2d (diff)
downloadorg.eclipse.xpand-926823f27920e20a5dcc41a04f1210f669411df0.zip
org.eclipse.xpand-926823f27920e20a5dcc41a04f1210f669411df0.tar.gz
org.eclipse.xpand-926823f27920e20a5dcc41a04f1210f669411df0.tar.bz2
DocBook sources of Xpand / Xtend / Check documentation added
-rw-r--r--doc/org.eclipse.xpand.doc/.cvsignore2
-rw-r--r--doc/org.eclipse.xpand.doc/.project11
-rw-r--r--doc/org.eclipse.xpand.doc/build-docbook.properties90
-rw-r--r--doc/org.eclipse.xpand.doc/build-docbook.xml159
-rw-r--r--doc/org.eclipse.xpand.doc/src/5.0/content/builtin_api.xml2111
-rw-r--r--doc/org.eclipse.xpand.doc/src/5.0/content/images/Xpand/metamodelexample.gifbin0 -> 2407 bytes
-rw-r--r--doc/org.eclipse.xpand.doc/src/5.0/content/xpand_reference.xml2845
-rw-r--r--doc/org.eclipse.xpand.doc/src/5.0/index.xml18
-rw-r--r--doc/org.eclipse.xpand.doc/src/5.0/structure/xpand_reference_structure.xml4
9 files changed, 5240 insertions, 0 deletions
diff --git a/doc/org.eclipse.xpand.doc/.cvsignore b/doc/org.eclipse.xpand.doc/.cvsignore
new file mode 100644
index 0000000..76f4628
--- /dev/null
+++ b/doc/org.eclipse.xpand.doc/.cvsignore
@@ -0,0 +1,2 @@
+build
+output
diff --git a/doc/org.eclipse.xpand.doc/.project b/doc/org.eclipse.xpand.doc/.project
index f057233..d556a23 100644
--- a/doc/org.eclipse.xpand.doc/.project
+++ b/doc/org.eclipse.xpand.doc/.project
@@ -5,7 +5,18 @@
<projects>
</projects>
<buildSpec>
+ <buildCommand>
+ <name>org.eclipse.pde.ManifestBuilder</name>
+ <arguments>
+ </arguments>
+ </buildCommand>
+ <buildCommand>
+ <name>org.eclipse.pde.SchemaBuilder</name>
+ <arguments>
+ </arguments>
+ </buildCommand>
</buildSpec>
<natures>
+ <nature>org.eclipse.pde.PluginNature</nature>
</natures>
</projectDescription>
diff --git a/doc/org.eclipse.xpand.doc/build-docbook.properties b/doc/org.eclipse.xpand.doc/build-docbook.properties
new file mode 100644
index 0000000..0db88bb
--- /dev/null
+++ b/doc/org.eclipse.xpand.doc/build-docbook.properties
@@ -0,0 +1,90 @@
+############### Adaptable properties ###############
+
+# Product information
+product.name=Xpand
+product.provider=openarchitectureware.org
+product.version=5.0
+
+# Directories
+tools.basedir=${basedir}/../org.openarchitectureware.documentation
+
+# Style files
+custom-css.file=book.css
+custom.pdf-xsl.file=fopdf.xsl
+custom.html-xsl.file=html.xsl
+custom.eclipse-xsl.file=eclipse.xsl
+
+# Flags
+custom = true
+
+# Document type
+document.type=individual
+
+# DocBook version
+docbook.version = 4.5
+
+
+############### Do not change below ###############
+
+# Directories
+tools.basedir.build = ${tools.basedir}
+tools.dir=${tools.basedir}/lib/tools
+tools.dir.build = ${tools.basedir.build}/lib/tools
+version.dir=${product.version}
+docbook.dir=${tools.dir.build}/docbook
+docbook-src.dir=${basedir}/src
+docbook-lib.dir=${docbook.dir}
+src.dir=${docbook-src.dir}/${version.dir}
+content.dir=${src.dir}/content
+structure.dir=${src.dir}/structure
+images.dir=${content.dir}/images
+build.dir=${basedir}/build
+output.dir=${basedir}/output
+html.dir=${output.dir}/html
+pdf.dir=${output.dir}/pdf
+style.dir=${tools.basedir}/styles
+css.style.dir=${style.dir}/css
+xsl.style.dir=${style.dir}/xslt
+shared.dir=${tools.basedir.build}/shared
+shared.src.dir=${tools.basedir.build}/src/${version.dir}
+shared.content.dir=${shared.src.dir}/content
+shared.images.dir=${shared.content.dir}/images
+
+# Title of documentation
+doc.title=${product.name} User Guide
+
+# Files
+css.file.path=${css.style.dir}/${custom-css.file}
+css.file=${custom-css.file}
+
+# PDF
+pdf.output.dir=${pdf.dir}/${version.dir}
+pdf.stylesheet.path=${xsl.style.dir}/${custom.pdf-xsl.file}
+pdf.stylesheet=${custom.pdf-xsl.file}
+
+# HTML
+html.output.dir=${html.dir}/${version.dir}
+html.stylesheet.path=${xsl.style.dir}/${custom.html-xsl.file}
+html.stylesheet=${custom.html-xsl.file}
+
+# Eclipse help
+eclipse.plugin.id=org.openarchitectureware.help.userguide
+eclipse.output.dir=../${eclipse.plugin.id}
+eclipse.plugin.name=$[product.name} User Guide
+eclipse.plugin.provider=$[product.provider}
+eclipse.stylesheet.path=${xsl.style.dir}/${custom.eclipse-xsl.file}
+eclipse.stylesheet=${custom.eclipse-xsl.file}
+
+# docbook
+docbook-xsl.dir=${docbook.dir}/xsl
+docbook-xsl.eclipse-xsl.file=${docbook-xsl.dir}/eclipse/eclipse.xsl
+docbook-xsl.html-xsl.file=${docbook-xsl.dir}/html/chunk.xsl
+docbook-xsl.pdf-xsl.file=${docbook-xsl.dir}/fo/fo.xsl
+
+# saxon
+saxon.dir = ${tools.dir}/saxon
+saxon.lib.path = ${saxon.dir}/saxon.jar
+
+# xerces
+xerces.dir = ${tools.dir}/fop
+xerces.lib.path = ${xerces.dir}/xercesImpl-2.7.1.jar \ No newline at end of file
diff --git a/doc/org.eclipse.xpand.doc/build-docbook.xml b/doc/org.eclipse.xpand.doc/build-docbook.xml
new file mode 100644
index 0000000..9c41947
--- /dev/null
+++ b/doc/org.eclipse.xpand.doc/build-docbook.xml
@@ -0,0 +1,159 @@
+<?xml version="1.0"?>
+<project name="Xpand documentation" default="build.all">
+
+ <property file="build-docbook.properties" />
+
+ <path id="fop">
+ <pathelement location="${tools.dir}/fop/fop.jar" />
+ <pathelement location="${tools.dir}/fop/avalon-framework-4.2.0.jar" />
+ <pathelement location="${tools.dir}/fop/batik-all-1.6.jar" />
+ </path>
+
+ <path id="saxon">
+ <pathelement location="${xerces.lib.path}" />
+ <pathelement location="${saxon.lib.path}" />
+ </path>
+
+ <tstamp>
+ <format property="date" pattern="yyyy-MM-dd" />
+ <format property="year" pattern="yyyy" />
+ </tstamp>
+
+ <taskdef name="fop" classname="org.apache.fop.tools.anttasks.Fop" classpathref="fop" />
+
+ <target name="build.all" depends="stage, build.doc.html, build.doc.eclipsehelp, build.doc.pdf, unstage" />
+
+ <target name="build.doc.html" depends="stage.html">
+ <delete dir="${html.output.dir}/contents" failonerror="false" />
+ <copy todir="${html.output.dir}/contents/images">
+ <fileset dir="${images.dir}">
+ <include name="**/*" />
+ </fileset>
+ </copy>
+ <copy file="${css.file.path}" todir="${html.output.dir}" />
+ <java fork="true" dir="${html.output.dir}" failonerror="true" classname="com.icl.saxon.StyleSheet">
+ <classpath refid="saxon" />
+ <sysproperty key="javax.xml.parsers.DocumentBuilderFactory" value="org.apache.xerces.jaxp.DocumentBuilderFactoryImpl"/>
+ <sysproperty key="javax.xml.parsers.SAXParserFactory" value="org.apache.xerces.jaxp.SAXParserFactoryImpl"/>
+ <sysproperty key="org.apache.xerces.xni.parser.XMLParserConfiguration" value="org.apache.xerces.parsers.XIncludeParserConfiguration"/>
+ <arg value="${build.dir}/index.xml" />
+ <arg value="${build.dir}/${html.stylesheet}" />
+ <arg value='profile.condition="${document.type}"'>
+ </arg>
+ </java>
+ </target>
+
+ <target name="build.doc.eclipsehelp" depends="stage.eclipse">
+ <delete dir="${eclipse.output.dir}/contents" failonerror="false" />
+ <copy todir="${eclipse.output.dir}/contents/images">
+ <fileset dir="${images.dir}">
+ <include name="**/*" />
+ </fileset>
+ </copy>
+ <copy file="${css.file.path}" todir="${eclipse.output.dir}" />
+ <java fork="true" dir="${eclipse.output.dir}" failonerror="true" classname="com.icl.saxon.StyleSheet">
+ <classpath refid="saxon" />
+ <sysproperty key="javax.xml.parsers.DocumentBuilderFactory" value="org.apache.xerces.jaxp.DocumentBuilderFactoryImpl"/>
+ <sysproperty key="javax.xml.parsers.SAXParserFactory" value="org.apache.xerces.jaxp.SAXParserFactoryImpl"/>
+ <sysproperty key="org.apache.xerces.xni.parser.XMLParserConfiguration" value="org.apache.xerces.parsers.XIncludeParserConfiguration"/>
+ <arg value="${build.dir}/index.xml" />
+ <arg value="${build.dir}/${eclipse.stylesheet}" />
+ <arg value="eclipse.plugin.id=${eclipse.plugin.id}" />
+ <arg value="eclipse.plugin.name=${eclipse.plugin.name}" />
+ <arg value="eclipse.plugin.provider=${eclipse.plugin.provider}" />
+ <arg value='profile.condition="${document.type}"'>
+ </arg>
+ </java>
+ </target>
+
+ <target name="build.doc.pdf" depends="stage.pdf">
+ <java fork="true" dir="${build.dir}" failonerror="true" classname="com.icl.saxon.StyleSheet">
+ <classpath refid="saxon" />
+ <sysproperty key="javax.xml.parsers.DocumentBuilderFactory" value="org.apache.xerces.jaxp.DocumentBuilderFactoryImpl"/>
+ <sysproperty key="javax.xml.parsers.SAXParserFactory" value="org.apache.xerces.jaxp.SAXParserFactoryImpl"/>
+ <sysproperty key="org.apache.xerces.xni.parser.XMLParserConfiguration" value="org.apache.xerces.parsers.XIncludeParserConfiguration"/>
+ <arg value="-o" />
+ <arg value="${build.dir}/${product.name}_documentation.fo" />
+ <arg value="${build.dir}/index.xml" />
+ <arg value="${pdf.stylesheet}" />
+ <arg value="draft.mode=no" />
+ <arg value="paper.type=A4" />
+ <arg value="l10n.gentext.language=en" />
+ <arg value='profile.condition="${document.type}"'>
+ </arg>
+ </java>
+
+ <mkdir dir="${pdf.output.dir}" />
+
+ <fop format="application/pdf" outdir="${pdf.output.dir}" basedir="${build.dir}" messagelevel="debug">
+ <fileset dir="${build.dir}">
+ <include name="**/*.fo" />
+ </fileset>
+ </fop>
+ </target>
+
+ <target name="stage" depends="unstage">
+ <copy todir="${build.dir}">
+ <fileset dir="${src.dir}">
+ <include name="**/*.xml" />
+ </fileset>
+ </copy>
+ <copy todir="${build.dir}/structure">
+ <fileset dir="${structure.dir}">
+ <include name="**/*.xml" />
+ </fileset>
+ </copy>
+ <copy todir="${build.dir}/content">
+ <fileset dir="${content.dir}">
+ <include name="**/*.xml" />
+ </fileset>
+ </copy>
+ <copy todir="${build.dir}/content/images">
+ <fileset dir="${images.dir}">
+ <include name="**/*" />
+ </fileset>
+ </copy>
+ <copy file="${tools.basedir}/shared/bookinfo.xml" todir="${build.dir}" />
+ <replace file="${build.dir}/index.xml" token="@DOCBOOKVERSION@"
+ value="${docbook.version}" casesensitive="true"/>
+ <replace file="${build.dir}/index.xml" token="@TITLE@"
+ value="${doc.title}" casesensitive="true"/>
+ <replace file="${build.dir}/bookinfo.xml" token="@VERSION@"
+ value="${product.version}" casesensitive="true"/>
+ <replace file="${build.dir}/bookinfo.xml" token="@DATE@"
+ value="${date}" casesensitive="true"/>
+ </target>
+
+ <target name="stage.pdf" depends="stage">
+ <copy file="${pdf.stylesheet.path}" todir="${build.dir}" />
+ <replace file="${build.dir}/${pdf.stylesheet}" token="@SHAREDIMAGESDIR@"
+ value="${shared.images.dir}" casesensitive="true"/>
+ <replace file="${build.dir}/${pdf.stylesheet}" token="@DOCBOOKDIR@"
+ value="${docbook.dir}" casesensitive="true" />
+ <replace file="${build.dir}/${pdf.stylesheet}" token="@TOOLSDIR@"
+ value="${tools.dir}" casesensitive="true"/>
+ <replace file="${build.dir}/${pdf.stylesheet}" token="@YEAR@"
+ value="${year}" casesensitive="true"/>
+ </target>
+
+ <target name="stage.html" depends="stage">
+ <copy file="${html.stylesheet.path}" todir="${build.dir}" />
+ <replace file="${build.dir}/${html.stylesheet}" token="@DOCBOOKDIR@"
+ value="${docbook.dir}" casesensitive="true" />
+ </target>
+
+ <target name="stage.eclipse" depends="stage">
+ <copy file="${eclipse.stylesheet.path}" todir="${build.dir}" />
+ <replace file="${build.dir}/${eclipse.stylesheet}" token="@DOCBOOKDIR@"
+ value="${docbook.dir}" casesensitive="true" />
+ </target>
+
+ <target name="unstage">
+ <delete dir="${build.dir}" />
+ </target>
+
+ <target name="clean" depends="unstage">
+ <delete dir="${output.dir}" />
+ </target>
+
+</project>
diff --git a/doc/org.eclipse.xpand.doc/src/5.0/content/builtin_api.xml b/doc/org.eclipse.xpand.doc/src/5.0/content/builtin_api.xml
new file mode 100644
index 0000000..649d851
--- /dev/null
+++ b/doc/org.eclipse.xpand.doc/src/5.0/content/builtin_api.xml
@@ -0,0 +1,2111 @@
+
+<section id="builtin_api">
+ <title>Built-in types API documentation</title>
+
+
+ <section id="builtin_api_Object">
+ <title><classname>Object</classname></title>
+ <para>
+ <?dbfo keep-with-next="always" ?>
+ Supertype:
+none
+ </para>
+ <para>
+
+
+ <table frame='all' id="builtin_api_Object_Properties">
+ <title>Properties of <classname>Object</classname></title>
+ <?dbfo keep-together.within-column="auto" ?>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_oaw::Type'>oaw::Type</link></classname>
+ </entry>
+ <entry>
+ <methodname>metaType</methodname>
+ </entry>
+ <entry>
+ returns this object's meta type.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ </para>
+ <para>
+
+
+ <table frame='all' id="builtin_api_Object_Operations">
+ <title>Operations of <classname>Object</classname></title>
+ <?dbfo keep-together.within-column="auto" ?>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Return type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>==</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>&lt;</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_String'>String</link></classname>
+ </entry>
+ <entry>
+ <methodname>toString</methodname>
+ ()
+ </entry>
+ <entry>
+ returns the String representation of this object. (Calling Java's toString() method)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>&lt;=</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>!=</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>&gt;</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Integer'>Integer</link></classname>
+ </entry>
+ <entry>
+ <methodname>compareTo</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+ Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>&gt;=</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ </para>
+ </section>
+
+
+ <section id="builtin_api_String">
+ <title><classname>String</classname></title>
+ <para>
+ <?dbfo keep-with-next="always" ?>
+ Supertype:
+<classname><link linkend='builtin_api_Object'>Object</link></classname>
+ </para>
+ <para>
+
+
+ <table frame='all' id="builtin_api_String_Properties">
+ <title>Properties of <classname>String</classname></title>
+ <?dbfo keep-together.within-column="auto" ?>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Integer'>Integer</link></classname>
+ </entry>
+ <entry>
+ <methodname>length</methodname>
+ </entry>
+ <entry>
+ the length of this string
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ </para>
+ <para>
+
+
+ <table frame='all' id="builtin_api_String_Operations">
+ <title>Operations of <classname>String</classname></title>
+ <?dbfo keep-together.within-column="auto" ?>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Return type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_String'>String</link></classname>
+ </entry>
+ <entry>
+ <methodname>toLowerCase</methodname>
+ ()
+ </entry>
+ <entry>
+ Converts all of the characters in this String to lower case using the rules of the default locale (from Java)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_String'>String</link></classname>
+ </entry>
+ <entry>
+ <methodname>+</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+ concatenates two strings
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_List'>List</link></classname>
+ </entry>
+ <entry>
+ <methodname>toCharList</methodname>
+ ()
+ </entry>
+ <entry>
+ splits this String into a List[String] containing Strings of length 1
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_String'>String</link></classname>
+ </entry>
+ <entry>
+ <methodname>toFirstUpper</methodname>
+ ()
+ </entry>
+ <entry>
+ Converts the first character in this String to upper case using the rules of the default locale (from Java)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_String'>String</link></classname>
+ </entry>
+ <entry>
+ <methodname>subString</methodname>
+ (<classname><link linkend='builtin_api_Integer'>Integer</link></classname>, <classname><link linkend='builtin_api_Integer'>Integer</link></classname>)
+ </entry>
+ <entry>
+ Tests if this string ends with the specified prefix.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_String'>String</link></classname>
+ </entry>
+ <entry>
+ <methodname>trim</methodname>
+ ()
+ </entry>
+ <entry>
+ Returns a copy of the string, with leading and trailing whitespace omitted. (from Java 1.4)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_String'>String</link></classname>
+ </entry>
+ <entry>
+ <methodname>toFirstLower</methodname>
+ ()
+ </entry>
+ <entry>
+ Converts the first character in this String to lower case using the rules of the default locale (from Java)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_String'>String</link></classname>
+ </entry>
+ <entry>
+ <methodname>toUpperCase</methodname>
+ ()
+ </entry>
+ <entry>
+ Converts all of the characters in this String to upper case using the rules of the default locale (from Java)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_List'>List</link></classname>
+ </entry>
+ <entry>
+ <methodname>split</methodname>
+ (<classname><link linkend='builtin_api_String'>String</link></classname>)
+ </entry>
+ <entry>
+ Splits this string around matches of the given regular expression (from Java 1.4)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>startsWith</methodname>
+ (<classname><link linkend='builtin_api_String'>String</link></classname>)
+ </entry>
+ <entry>
+ Tests if this string starts with the specified prefix.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>matches</methodname>
+ (<classname><link linkend='builtin_api_String'>String</link></classname>)
+ </entry>
+ <entry>
+ Tells whether or not this string matches the given regular expression. (from Java 1.4)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Integer'>Integer</link></classname>
+ </entry>
+ <entry>
+ <methodname>asInteger</methodname>
+ ()
+ </entry>
+ <entry>
+ Returns an Integer object holding the value of the specified String (from Java 1.5)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>contains</methodname>
+ (<classname><link linkend='builtin_api_String'>String</link></classname>)
+ </entry>
+ <entry>
+ Tests if this string contains substring.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>endsWith</methodname>
+ (<classname><link linkend='builtin_api_String'>String</link></classname>)
+ </entry>
+ <entry>
+ Tests if this string ends with the specified prefix.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_String'>String</link></classname>
+ </entry>
+ <entry>
+ <methodname>replaceFirst</methodname>
+ (<classname><link linkend='builtin_api_String'>String</link></classname>, <classname><link linkend='builtin_api_String'>String</link></classname>)
+ </entry>
+ <entry>
+ Replaces the first substring of this string that matches the given regular expression with the given replacement.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_String'>String</link></classname>
+ </entry>
+ <entry>
+ <methodname>replaceAll</methodname>
+ (<classname><link linkend='builtin_api_String'>String</link></classname>, <classname><link linkend='builtin_api_String'>String</link></classname>)
+ </entry>
+ <entry>
+ Replaces each substring of this string that matches the given regular expression with the given replacement.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ </para>
+ </section>
+
+
+ <section id="builtin_api_Integer">
+ <title><classname>Integer</classname></title>
+ <para>
+ <?dbfo keep-with-next="always" ?>
+ Supertype:
+<classname><link linkend='builtin_api_Real'>Real</link></classname>
+ </para>
+ <para>
+
+
+ This type does not define any properties.
+
+
+ </para>
+ <para>
+
+
+ <table frame='all' id="builtin_api_Integer_Operations">
+ <title>Operations of <classname>Integer</classname></title>
+ <?dbfo keep-together.within-column="auto" ?>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Return type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_List'>List</link></classname>
+ </entry>
+ <entry>
+ <methodname>upTo</methodname>
+ (<classname><link linkend='builtin_api_Integer'>Integer</link></classname>)
+ </entry>
+ <entry>
+ returns a List of Integers starting with the value of the target expression, up to the value of the specified Integer, incremented by one.e.g. '1.upTo(5)' evaluates to {1,2,3,4,5}
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>&gt;=</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_List'>List</link></classname>
+ </entry>
+ <entry>
+ <methodname>upTo</methodname>
+ (<classname><link linkend='builtin_api_Integer'>Integer</link></classname>, <classname><link linkend='builtin_api_Integer'>Integer</link></classname>)
+ </entry>
+ <entry>
+ returns a List of Integers starting with the value of the target expression, up to the value of the first paramter, incremented by the second parameter.e.g. '1.upTo(10, 2)' evaluates to {1,3,5,7,9}
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Integer'>Integer</link></classname>
+ </entry>
+ <entry>
+ <methodname>-</methodname>
+ (<classname><link linkend='builtin_api_Integer'>Integer</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Integer'>Integer</link></classname>
+ </entry>
+ <entry>
+ <methodname>+</methodname>
+ (<classname><link linkend='builtin_api_Integer'>Integer</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>&lt;=</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>==</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Integer'>Integer</link></classname>
+ </entry>
+ <entry>
+ <methodname>*</methodname>
+ (<classname><link linkend='builtin_api_Integer'>Integer</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>!=</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>&gt;</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Integer'>Integer</link></classname>
+ </entry>
+ <entry>
+ <methodname>-</methodname>
+ ()
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>&lt;</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Integer'>Integer</link></classname>
+ </entry>
+ <entry>
+ <methodname>/</methodname>
+ (<classname><link linkend='builtin_api_Integer'>Integer</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ </para>
+ </section>
+
+
+ <section id="builtin_api_Boolean">
+ <title><classname>Boolean</classname></title>
+ <para>
+ <?dbfo keep-with-next="always" ?>
+ Supertype:
+<classname><link linkend='builtin_api_Object'>Object</link></classname>
+ </para>
+ <para>
+
+
+ This type does not define any properties.
+
+
+ </para>
+ <para>
+
+
+ <table frame='all' id="builtin_api_Boolean_Operations">
+ <title>Operations of <classname>Boolean</classname></title>
+ <?dbfo keep-together.within-column="auto" ?>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Return type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>!</methodname>
+ ()
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ </para>
+ </section>
+
+
+ <section id="builtin_api_Real">
+ <title><classname>Real</classname></title>
+ <para>
+ <?dbfo keep-with-next="always" ?>
+ Supertype:
+<classname><link linkend='builtin_api_Object'>Object</link></classname>
+ </para>
+ <para>
+
+
+ This type does not define any properties.
+
+
+ </para>
+ <para>
+
+
+ <table frame='all' id="builtin_api_Real_Operations">
+ <title>Operations of <classname>Real</classname></title>
+ <?dbfo keep-together.within-column="auto" ?>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Return type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Real'>Real</link></classname>
+ </entry>
+ <entry>
+ <methodname>*</methodname>
+ (<classname><link linkend='builtin_api_Real'>Real</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>&gt;=</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>&lt;=</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Real'>Real</link></classname>
+ </entry>
+ <entry>
+ <methodname>-</methodname>
+ ()
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>==</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>!=</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>&lt;</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Real'>Real</link></classname>
+ </entry>
+ <entry>
+ <methodname>-</methodname>
+ (<classname><link linkend='builtin_api_Real'>Real</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Real'>Real</link></classname>
+ </entry>
+ <entry>
+ <methodname>/</methodname>
+ (<classname><link linkend='builtin_api_Real'>Real</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>&gt;</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Real'>Real</link></classname>
+ </entry>
+ <entry>
+ <methodname>+</methodname>
+ (<classname><link linkend='builtin_api_Real'>Real</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ </para>
+ </section>
+
+
+ <section id="builtin_api_Collection">
+ <title><classname>Collection</classname></title>
+ <para>
+ <?dbfo keep-with-next="always" ?>
+ Supertype:
+<classname><link linkend='builtin_api_Object'>Object</link></classname>
+ </para>
+ <para>
+
+
+ <table frame='all' id="builtin_api_Collection_Properties">
+ <title>Properties of <classname>Collection</classname></title>
+ <?dbfo keep-together.within-column="auto" ?>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>isEmpty</methodname>
+ </entry>
+ <entry>
+ returns true if this Collection is empty
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Integer'>Integer</link></classname>
+ </entry>
+ <entry>
+ <methodname>size</methodname>
+ </entry>
+ <entry>
+ returns the size of this Collection
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ </para>
+ <para>
+
+
+ <table frame='all' id="builtin_api_Collection_Operations">
+ <title>Operations of <classname>Collection</classname></title>
+ <?dbfo keep-together.within-column="auto" ?>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Return type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>contains</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+ returns true if this collection contains the specified object. otherwise false. returns this Collection.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_List'>List</link></classname>
+ </entry>
+ <entry>
+ <methodname>toList</methodname>
+ ()
+ </entry>
+ <entry>
+ converts this collection to List
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Set'>Set</link></classname>
+ </entry>
+ <entry>
+ <methodname>toSet</methodname>
+ ()
+ </entry>
+ <entry>
+ converts this collection to Set
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_List'>List</link></classname>
+ </entry>
+ <entry>
+ <methodname>flatten</methodname>
+ ()
+ </entry>
+ <entry>
+ returns a flatten List.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Set'>Set</link></classname>
+ </entry>
+ <entry>
+ <methodname>intersect</methodname>
+ (<classname><link linkend='builtin_api_Collection'>Collection</link></classname>)
+ </entry>
+ <entry>
+ returns a new Set, containing only the elements contained in this and the specified Collection
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_String'>String</link></classname>
+ </entry>
+ <entry>
+ <methodname>toString</methodname>
+ (<classname><link linkend='builtin_api_String'>String</link></classname>)
+ </entry>
+ <entry>
+ concatenates each contained element (using toString()), separated by the specified String.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Collection'>Collection</link></classname>
+ </entry>
+ <entry>
+ <methodname>removeAll</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+ removes all elements contained in the specified collection from this Collection if contained (modifies it!). returns this Collection.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Collection'>Collection</link></classname>
+ </entry>
+ <entry>
+ <methodname>remove</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+ removes the specified element from this Collection if contained (modifies it!). returns this Collection.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Set'>Set</link></classname>
+ </entry>
+ <entry>
+ <methodname>without</methodname>
+ (<classname><link linkend='builtin_api_Collection'>Collection</link></classname>)
+ </entry>
+ <entry>
+ returns a new Set, containing all elements from this Collection without the elements from specified Collection
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Collection'>Collection</link></classname>
+ </entry>
+ <entry>
+ <methodname>addAll</methodname>
+ (<classname><link linkend='builtin_api_Collection'>Collection</link></classname>)
+ </entry>
+ <entry>
+ adds all elements to the Collection (modifies it!). returns this Collection.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Collection'>Collection</link></classname>
+ </entry>
+ <entry>
+ <methodname>add</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+ adds an element to the Collection (modifies it!). returns this Collection.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Set'>Set</link></classname>
+ </entry>
+ <entry>
+ <methodname>union</methodname>
+ (<classname><link linkend='builtin_api_Collection'>Collection</link></classname>)
+ </entry>
+ <entry>
+ returns a new Set, containing all elements from this and the specified Collection
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>containsAll</methodname>
+ (<classname><link linkend='builtin_api_Collection'>Collection</link></classname>)
+ </entry>
+ <entry>
+ returns true if this collection contains each element contained in the specified collection. otherwise false. returns this Collection.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ </para>
+ </section>
+
+
+ <section id="builtin_api_List">
+ <title><classname>List</classname></title>
+ <para>
+ <?dbfo keep-with-next="always" ?>
+ Supertype:
+<classname><link linkend='builtin_api_Collection'>Collection</link></classname>
+ </para>
+ <para>
+
+
+ This type does not define any properties.
+
+
+ </para>
+ <para>
+
+
+ <table frame='all' id="builtin_api_List_Operations">
+ <title>Operations of <classname>List</classname></title>
+ <?dbfo keep-together.within-column="auto" ?>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Return type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_List'>List</link></classname>
+ </entry>
+ <entry>
+ <methodname>withoutFirst</methodname>
+ ()
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Object'>Object</link></classname>
+ </entry>
+ <entry>
+ <methodname>last</methodname>
+ ()
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Integer'>Integer</link></classname>
+ </entry>
+ <entry>
+ <methodname>indexOf</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_List'>List</link></classname>
+ </entry>
+ <entry>
+ <methodname>withoutLast</methodname>
+ ()
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Object'>Object</link></classname>
+ </entry>
+ <entry>
+ <methodname>reverse</methodname>
+ ()
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Object'>Object</link></classname>
+ </entry>
+ <entry>
+ <methodname>first</methodname>
+ ()
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Object'>Object</link></classname>
+ </entry>
+ <entry>
+ <methodname>get</methodname>
+ (<classname><link linkend='builtin_api_Integer'>Integer</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ </para>
+ </section>
+
+
+ <section id="builtin_api_Set">
+ <title><classname>Set</classname></title>
+ <para>
+ <?dbfo keep-with-next="always" ?>
+ Supertype:
+<classname><link linkend='builtin_api_Collection'>Collection</link></classname>
+ </para>
+ <para>
+
+
+ This type does not define any properties.
+
+
+ </para>
+ <para>
+
+
+ This type does not define any operations.
+
+
+ </para>
+ </section>
+
+
+ <section id="builtin_api_oaw::Type">
+ <title><classname>oaw::Type</classname></title>
+ <para>
+ <?dbfo keep-with-next="always" ?>
+ Supertype:
+<classname><link linkend='builtin_api_Object'>Object</link></classname>
+ </para>
+ <para>
+
+
+ <table frame='all' id="builtin_api_oaw::Type_Properties">
+ <title>Properties of <classname>oaw::Type</classname></title>
+ <?dbfo keep-together.within-column="auto" ?>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_String'>String</link></classname>
+ </entry>
+ <entry>
+ <methodname>name</methodname>
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Set'>Set</link></classname>
+ </entry>
+ <entry>
+ <methodname>allStaticProperties</methodname>
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_String'>String</link></classname>
+ </entry>
+ <entry>
+ <methodname>documentation</methodname>
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Set'>Set</link></classname>
+ </entry>
+ <entry>
+ <methodname>superTypes</methodname>
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Set'>Set</link></classname>
+ </entry>
+ <entry>
+ <methodname>allProperties</methodname>
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Set'>Set</link></classname>
+ </entry>
+ <entry>
+ <methodname>allFeatures</methodname>
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Set'>Set</link></classname>
+ </entry>
+ <entry>
+ <methodname>allOperations</methodname>
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ </para>
+ <para>
+
+
+ <table frame='all' id="builtin_api_oaw::Type_Operations">
+ <title>Operations of <classname>oaw::Type</classname></title>
+ <?dbfo keep-together.within-column="auto" ?>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Return type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_oaw::Operation'>oaw::Operation</link></classname>
+ </entry>
+ <entry>
+ <methodname>getOperation</methodname>
+ (<classname><link linkend='builtin_api_String'>String</link></classname>, <classname><link linkend='builtin_api_List'>List</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_oaw::Feature'>oaw::Feature</link></classname>
+ </entry>
+ <entry>
+ <methodname>getFeature</methodname>
+ (<classname><link linkend='builtin_api_String'>String</link></classname>, <classname><link linkend='builtin_api_List'>List</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Object'>Object</link></classname>
+ </entry>
+ <entry>
+ <methodname>newInstance</methodname>
+ ()
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_oaw::StaticProperty'>oaw::StaticProperty</link></classname>
+ </entry>
+ <entry>
+ <methodname>getStaticProperty</methodname>
+ (<classname><link linkend='builtin_api_String'>String</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_oaw::Property'>oaw::Property</link></classname>
+ </entry>
+ <entry>
+ <methodname>getProperty</methodname>
+ (<classname><link linkend='builtin_api_String'>String</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>isAssignableFrom</methodname>
+ (<classname><link linkend='builtin_api_oaw::Type'>oaw::Type</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>isInstance</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ </para>
+ </section>
+
+
+ <section id="builtin_api_oaw::Feature">
+ <title><classname>oaw::Feature</classname></title>
+ <para>
+ <?dbfo keep-with-next="always" ?>
+ Supertype:
+<classname><link linkend='builtin_api_Object'>Object</link></classname>
+ </para>
+ <para>
+
+
+ <table frame='all' id="builtin_api_oaw::Feature_Properties">
+ <title>Properties of <classname>oaw::Feature</classname></title>
+ <?dbfo keep-together.within-column="auto" ?>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_String'>String</link></classname>
+ </entry>
+ <entry>
+ <methodname>name</methodname>
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_oaw::Type'>oaw::Type</link></classname>
+ </entry>
+ <entry>
+ <methodname>owner</methodname>
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_String'>String</link></classname>
+ </entry>
+ <entry>
+ <methodname>documentation</methodname>
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_oaw::Type'>oaw::Type</link></classname>
+ </entry>
+ <entry>
+ <methodname>returnType</methodname>
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ </para>
+ <para>
+
+
+ This type does not define any operations.
+
+
+ </para>
+ </section>
+
+
+ <section id="builtin_api_oaw::Property">
+ <title><classname>oaw::Property</classname></title>
+ <para>
+ <?dbfo keep-with-next="always" ?>
+ Supertype:
+<classname><link linkend='builtin_api_oaw::Feature'>oaw::Feature</link></classname>
+ </para>
+ <para>
+
+
+ This type does not define any properties.
+
+
+ </para>
+ <para>
+
+
+ <table frame='all' id="builtin_api_oaw::Property_Operations">
+ <title>Operations of <classname>oaw::Property</classname></title>
+ <?dbfo keep-together.within-column="auto" ?>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Return type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Object'>Object</link></classname>
+ </entry>
+ <entry>
+ <methodname>get</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Void'>Void</link></classname>
+ </entry>
+ <entry>
+ <methodname>set</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>, <classname><link linkend='builtin_api_Object'>Object</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ </para>
+ </section>
+
+
+ <section id="builtin_api_oaw::Operation">
+ <title><classname>oaw::Operation</classname></title>
+ <para>
+ <?dbfo keep-with-next="always" ?>
+ Supertype:
+<classname><link linkend='builtin_api_oaw::Feature'>oaw::Feature</link></classname>
+ </para>
+ <para>
+
+
+ This type does not define any properties.
+
+
+ </para>
+ <para>
+
+
+ <table frame='all' id="builtin_api_oaw::Operation_Operations">
+ <title>Operations of <classname>oaw::Operation</classname></title>
+ <?dbfo keep-together.within-column="auto" ?>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Return type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Object'>Object</link></classname>
+ </entry>
+ <entry>
+ <methodname>evaluate</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>, <classname><link linkend='builtin_api_List'>List</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_List'>List</link></classname>
+ </entry>
+ <entry>
+ <methodname>getParameterTypes</methodname>
+ ()
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ </para>
+ </section>
+
+
+ <section id="builtin_api_oaw::StaticProperty">
+ <title><classname>oaw::StaticProperty</classname></title>
+ <para>
+ <?dbfo keep-with-next="always" ?>
+ Supertype:
+<classname><link linkend='builtin_api_oaw::Feature'>oaw::Feature</link></classname>
+ </para>
+ <para>
+
+
+ This type does not define any properties.
+
+
+ </para>
+ <para>
+
+
+ <table frame='all' id="builtin_api_oaw::StaticProperty_Operations">
+ <title>Operations of <classname>oaw::StaticProperty</classname></title>
+ <?dbfo keep-together.within-column="auto" ?>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Return type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Object'>Object</link></classname>
+ </entry>
+ <entry>
+ <methodname>get</methodname>
+ ()
+ </entry>
+ <entry>
+ returns the static value
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ </para>
+ </section>
+
+
+ <section id="builtin_api_Void">
+ <title><classname>Void</classname></title>
+ <para>
+ <?dbfo keep-with-next="always" ?>
+ Supertype:
+<classname><link linkend='builtin_api_Object'>Object</link></classname>
+ </para>
+ <para>
+
+
+ This type does not define any properties.
+
+
+ </para>
+ <para>
+
+
+ This type does not define any operations.
+
+
+ </para>
+ </section>
+
+
+ <section id="builtin_api_xtend::AdviceContext">
+ <title><classname>xtend::AdviceContext</classname></title>
+ <para>
+ <?dbfo keep-with-next="always" ?>
+ Supertype:
+<classname><link linkend='builtin_api_Object'>Object</link></classname>
+ </para>
+ <para>
+
+
+ <table frame='all' id="builtin_api_xtend::AdviceContext_Properties">
+ <title>Properties of <classname>xtend::AdviceContext</classname></title>
+ <?dbfo keep-together.within-column="auto" ?>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_List'>List</link></classname>
+ </entry>
+ <entry>
+ <methodname>paramTypes</methodname>
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_String'>String</link></classname>
+ </entry>
+ <entry>
+ <methodname>name</methodname>
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_List'>List</link></classname>
+ </entry>
+ <entry>
+ <methodname>paramNames</methodname>
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_List'>List</link></classname>
+ </entry>
+ <entry>
+ <methodname>paramValues</methodname>
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ </para>
+ <para>
+
+
+ <table frame='all' id="builtin_api_xtend::AdviceContext_Operations">
+ <title>Operations of <classname>xtend::AdviceContext</classname></title>
+ <?dbfo keep-together.within-column="auto" ?>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Return type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Object'>Object</link></classname>
+ </entry>
+ <entry>
+ <methodname>proceed</methodname>
+ (<classname><link linkend='builtin_api_List'>List</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Object'>Object</link></classname>
+ </entry>
+ <entry>
+ <methodname>proceed</methodname>
+ ()
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ </para>
+ </section>
+
+
+ <section id="builtin_api_xpand2::Definition">
+ <title><classname>xpand2::Definition</classname></title>
+ <para>
+ <?dbfo keep-with-next="always" ?>
+ Supertype:
+<classname><link linkend='builtin_api_Object'>Object</link></classname>
+ </para>
+ <para>
+
+
+ <table frame='all' id="builtin_api_xpand2::Definition_Properties">
+ <title>Properties of <classname>xpand2::Definition</classname></title>
+ <?dbfo keep-together.within-column="auto" ?>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_List'>List</link></classname>
+ </entry>
+ <entry>
+ <methodname>paramTypes</methodname>
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_String'>String</link></classname>
+ </entry>
+ <entry>
+ <methodname>name</methodname>
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_List'>List</link></classname>
+ </entry>
+ <entry>
+ <methodname>paramNames</methodname>
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_oaw::Type'>oaw::Type</link></classname>
+ </entry>
+ <entry>
+ <methodname>targetType</methodname>
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ </para>
+ <para>
+
+
+ <table frame='all' id="builtin_api_xpand2::Definition_Operations">
+ <title>Operations of <classname>xpand2::Definition</classname></title>
+ <?dbfo keep-together.within-column="auto" ?>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Return type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Void'>Void</link></classname>
+ </entry>
+ <entry>
+ <methodname>proceed</methodname>
+ ()
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_String'>String</link></classname>
+ </entry>
+ <entry>
+ <methodname>toString</methodname>
+ ()
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Void'>Void</link></classname>
+ </entry>
+ <entry>
+ <methodname>proceed</methodname>
+ (<classname><link linkend='builtin_api_Object'>Object</link></classname>, <classname><link linkend='builtin_api_List'>List</link></classname>)
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ </para>
+ </section>
+
+
+ <section id="builtin_api_xpand2::Iterator">
+ <title><classname>xpand2::Iterator</classname></title>
+ <para>
+ <?dbfo keep-with-next="always" ?>
+ Supertype:
+<classname><link linkend='builtin_api_Object'>Object</link></classname>
+ </para>
+ <para>
+
+
+ <table frame='all' id="builtin_api_xpand2::Iterator_Properties">
+ <title>Properties of <classname>xpand2::Iterator</classname></title>
+ <?dbfo keep-together.within-column="auto" ?>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>lastIteration</methodname>
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Boolean'>Boolean</link></classname>
+ </entry>
+ <entry>
+ <methodname>firstIteration</methodname>
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Integer'>Integer</link></classname>
+ </entry>
+ <entry>
+ <methodname>elements</methodname>
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Integer'>Integer</link></classname>
+ </entry>
+ <entry>
+ <methodname>counter0</methodname>
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <classname><link linkend='builtin_api_Integer'>Integer</link></classname>
+ </entry>
+ <entry>
+ <methodname>counter1</methodname>
+ </entry>
+ <entry>
+
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ </para>
+ <para>
+
+
+ This type does not define any operations.
+
+
+ </para>
+ </section>
+
+
+</section>
diff --git a/doc/org.eclipse.xpand.doc/src/5.0/content/images/Xpand/metamodelexample.gif b/doc/org.eclipse.xpand.doc/src/5.0/content/images/Xpand/metamodelexample.gif
new file mode 100644
index 0000000..177c0f8
--- /dev/null
+++ b/doc/org.eclipse.xpand.doc/src/5.0/content/images/Xpand/metamodelexample.gif
Binary files differ
diff --git a/doc/org.eclipse.xpand.doc/src/5.0/content/xpand_reference.xml b/doc/org.eclipse.xpand.doc/src/5.0/content/xpand_reference.xml
new file mode 100644
index 0000000..d7680a9
--- /dev/null
+++ b/doc/org.eclipse.xpand.doc/src/5.0/content/xpand_reference.xml
@@ -0,0 +1,2845 @@
+<?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/xPandReference/metamodelexample.gif"
+ scale="80"/>
+ </imageobject>
+
+ <imageobject role="html">
+ <imagedata
+ fileref="images/xPandReference/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. <phrase conditon="main">(see <emphasis> <xref
+ linkend="workflow_reference"/> </emphasis>).</phrase> 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> \ No newline at end of file
diff --git a/doc/org.eclipse.xpand.doc/src/5.0/index.xml b/doc/org.eclipse.xpand.doc/src/5.0/index.xml
new file mode 100644
index 0000000..b6892c2
--- /dev/null
+++ b/doc/org.eclipse.xpand.doc/src/5.0/index.xml
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<book xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xmlns:xi="http://www.w3.org/2001/XInclude" >
+ <title>@TITLE@</title>
+
+ <xi:include href="bookinfo.xml" />
+
+ <toc />
+
+ <part id="reference">
+ <title>Reference</title>
+ <xi:include href="structure/xpand_reference_structure.xml" />
+ </part>
+
+ <index />
+</book>
+
diff --git a/doc/org.eclipse.xpand.doc/src/5.0/structure/xpand_reference_structure.xml b/doc/org.eclipse.xpand.doc/src/5.0/structure/xpand_reference_structure.xml
new file mode 100644
index 0000000..aca0ee1
--- /dev/null
+++ b/doc/org.eclipse.xpand.doc/src/5.0/structure/xpand_reference_structure.xml
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+ href="../content/xpand_reference.xml"/>