| <html> |
| <head> |
| <title>Using the backend</title> |
| <link href="book.css" rel="stylesheet" type="text/css"/> |
| <meta content="DocBook XSL Stylesheets V1.75.1" name="generator"/> |
| <link rel="home" href="index.html" title="Xpand Documentation"/> |
| <link rel="up" href="backend.html" title="Improve performance using the backend"/> |
| <link rel="prev" href="backend.html" title="Improve performance using the backend"/> |
| <link rel="next" href="call_functions_backend.html" title="Call functions registered at the backend from Java"/> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <h1 xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">Using the backend</h1> |
| <div class="section" title="Using the backend"> |
| <div class="titlepage"> |
| <div> |
| <div> |
| <h2 class="title" style="clear: both"> |
| <a name="backend_usage"/>Using the backend</h2> |
| </div> |
| </div> |
| </div> |
| <div class="section" title="A quickstart"> |
| <div class="titlepage"> |
| <div> |
| <div> |
| <h3 class="title"> |
| <a name="backend_quickstart"/>A quickstart</h3> |
| </div> |
| </div> |
| </div> |
| <p> |
| Before you can start, you need to install the following features: |
| </p> |
| <div class="itemizedlist"> |
| <ul class="itemizedlist" type="disc"> |
| <li class="listitem"> |
| Xtend Backend |
| </li> |
| <li class="listitem"> |
| Xtend Backend UML2Types |
| </li> |
| <li class="listitem"> |
| Xtend Backend XSDTypes |
| </li> |
| <li class="listitem"> |
| Xtend Backend Compiler |
| </li> |
| <li class="listitem"> |
| Xtend Backend UI (only required by the compiler) |
| </li> |
| <li class="listitem"> |
| Xpand Middleend |
| </li> |
| <li class="listitem"> |
| Xpand Middleend UI (only required by the compiler) |
| </li> |
| <li class="listitem"> |
| Xtend Middleend |
| </li> |
| <li class="listitem"> |
| Xtend Middleend UI (only required by the compiler) |
| </li> |
| </ul> |
| </div> |
| <p> |
| Altenatively you may install the<span class="emphasis"> |
| <em>Xtend Backend SDK</em> |
| </span> |
| and <span class="emphasis"> |
| <em>Xpand Middleend SDK</em> |
| </span> |
| </p> |
| <p> |
| As a quickstart you may use the <span class="emphasis"> |
| <em>Xpand Project</em> |
| </span> |
| wizard and select "Generate a sample EMF based Xpand project". After |
| completion of the wizard you will find the workflow file |
| "generatorWithBackend.mwe" in the "workflow"-folder. The workflow is |
| ready to use the backend for generation. |
| </p> |
| </div> |
| <div class="section" title="Compiling sources to Java"> |
| <div class="titlepage"> |
| <div> |
| <div> |
| <h3 class="title"> |
| <a name="backend_compiler"/>Compiling sources to Java</h3> |
| </div> |
| </div> |
| </div> |
| <p> |
| The compiler can be activated as a builder by adding M2T Backend Compiler nature to the project. This is |
| done selecting "Configure" > "Add M2T Backend Compiler" from the context menu of the Xpand project. All |
| Xpand/Xtend/Check resources will then be compiler to Java source files into the "backend-gen" folder of the |
| project. When selecting "Clean..." from the project menu the Backend Compiler will do a full build, |
| while changing a Xpand/Xtend/Check resource will compile this resource incrementally. |
| </p> |
| <p> |
| The compiler is still experimental. |
| </p> |
| </div> |
| <div class="section" title="Executing workflows using the backend"> |
| <div class="titlepage"> |
| <div> |
| <div> |
| <h3 class="title"> |
| <a name="backend_execution"/>Executing workflows using the backend</h3> |
| </div> |
| </div> |
| </div> |
| <p> |
| The backend can execute functions and templates that have been compiled to Java or other resources that |
| can be handled by one of the available middleends. It automatically recognizes compiled resources |
| if available on the build path and prefers them over native Xpand/Xtend/Check resources. |
| </p> |
| <p> |
| The best way to execute compiled functions/templates is to use the XpandComponent or XtendComponent. The |
| name of the function to be called is the same fully qualified name as defined in Xpand/Xtend/Check. |
| </p> |
| <div class="section" title="Setting up the backend languages"> |
| <div class="titlepage"> |
| <div> |
| <div> |
| <h4 class="title"> |
| <a name="backend_setup"/>Setting up the backend languages</h4> |
| </div> |
| </div> |
| </div> |
| <p> |
| Before you can use a language like Xpand with the backend, the |
| responsible middleend must be registered at the backend. This is done |
| with the <code class="classname">org.eclipse.xtend.middleend.LanguageSetup</code>. |
| Middleends are being called a <code class="classname">languageContributor</code> |
| here. You can register any language specific middleend. Language |
| specific middleend implement the interface |
| <code class="classname">org.eclipse.xtend.middleend.plugins.LanguageSpecificMiddleEnd |
| </code>. To register the Xpand, Xtend and Check middleends, do the |
| following in the workflow before invoking the middleend component of |
| any of the respective languages: |
| </p> |
| <pre class="programlisting"><component |
| class="org.eclipse.xtend.middleend.LanguageSetup"> |
| <languageContributor |
| value="org.eclipse.xtend.middleend.xtend.plugin.OldXtendRegistryFactory"/> |
| <languageContributor |
| value="org.eclipse.xtend.middleend.xtend.plugin.OldCheckRegistryFactory"/> |
| <languageContributor |
| value="org.eclipse.xtend.middleend.xpand.plugin.OldXpandRegistryFactory"/> |
| </component></pre> |
| <p> |
| Now that the middleends are registered, you can use the respective middleend |
| workflow components to use the backend in interpreted mode. |
| </p> |
| </div> |
| <div class="section" title="Calling Xpand templates - the generator"> |
| <div class="titlepage"> |
| <div> |
| <div> |
| <h4 class="title"> |
| <a name="xpand_middleend_usage"/>Calling Xpand templates - the generator</h4> |
| </div> |
| </div> |
| </div> |
| <p> |
| The Xpand middleend introduces a new component to be used instead of |
| <code class="classname">org.eclipse.xpand2.Generator</code> |
| to call Xpand templates from a workflow. The component has the same |
| parameters as the Xpand <code class="classname">Generator</code> |
| component. Hence, the following workflow fragment calls the template |
| <code class="classname">template::Template::main</code>: |
| </p> |
| <pre class="programlisting"><component class="org.eclipse.xtend.middleend.xpand.XpandComponent"> |
| <metaModel idRef="mm_emf"/> |
| <expand value="template::Template::main FOR model" /> |
| <outlet path="${src-gen}" > |
| <postprocessor class="org.eclipse.xpand2.output.JavaBeautifier" /> |
| </outlet> |
| </component></pre> |
| <p> |
| The component supports all properties of <code class="classname">Generator</code>, |
| except <code class="classname">collectProfileSummary</code> and |
| <code class="classname">verboseProfileFilename</code> |
| </p> |
| </div> |
| <div class="section" title="Executing Check on the backend"> |
| <div class="titlepage"> |
| <div> |
| <div> |
| <h4 class="title"> |
| <a name="check_middleend_usage"/>Executing Check on the backend</h4> |
| </div> |
| </div> |
| </div> |
| <p> |
| Just as the Xpand middleend, the Check middleend also provides a new component |
| to execute checks on the backend. The component |
| <code class="classname">org.eclipse.xtend.check.CheckComponent</code> |
| has to be replaced with <code class="classname">org.eclipse.xtend.middleend.xtend.CheckComponent |
| </code>. The new component uses the same properties as |
| <code class="classname">org.eclipse.xtend.check.CheckComponent</code>. |
| Hence calling checks using the backend would look like this: |
| </p> |
| <pre class="programlisting"><component class="org.eclipse.xtend.middleend.xtend.CheckComponent"> |
| <metaModel idRef="mm_emf"/> |
| <checkFile value="metamodel::Checks" /> |
| <emfAllChildrenSlot value="model"/> |
| </component> </pre> |
| </div> |
| <div class="section" title="Executing Xtend extensions on the backend"> |
| <div class="titlepage"> |
| <div> |
| <div> |
| <h4 class="title"> |
| <a name="xtend_middleend_usage"/>Executing Xtend extensions on the backend</h4> |
| </div> |
| </div> |
| </div> |
| <p> |
| To invoke Xtend extensions from the workflow, the Xtend middleend |
| introduces the new component |
| <code class="classname">org.eclipse.xtend.middleend.xtend.XtendComponent |
| </code>. The new component provides the same configuration |
| properties as the old one. Hence, you may invoke the extension |
| <code class="classname">extensions::modification::modify</code> |
| using the following workflow fragment: |
| </p> |
| <pre class="programlisting">>component class="org.eclipse.xtend.middleend.xtend.XtendComponent"> |
| <metaModel idRef="mm_emf"/> |
| <invoke value="extensions::modification::modify(model)"/> |
| </component> </pre> |
| </div> |
| </div> |
| <div class="section" title="Implementing functions in Java - the Java Annotations Middleend"> |
| <div class="titlepage"> |
| <div> |
| <div> |
| <h3 class="title"> |
| <a name="java_middleend"/>Implementing functions in Java - the Java Annotations |
| Middleend</h3> |
| </div> |
| </div> |
| </div> |
| <p> |
| Functions may also be contributed by the Java Annotations Middleend |
| to the M2T Backend. The middleend is implemented by |
| <code class="classname">org.eclipse.xtend.middleend.javaannotations.JavaFunctionClassContributor |
| </code>. Registration of Java classes is done by calling the method |
| <code class="classname">classAsResource</code> with a class. |
| </p> |
| <p> |
| Functions have qualified names in the backend represented by |
| <code class="classname">org.eclipse.xtend.backend.common.QualifiedName</code> |
| consisting of a namespace and a simple name. E.g. the Xpand |
| definition <code class="classname">template::Template::main</code> |
| has the namespace <code class="classname">template::Template</code> |
| and the simple name <code class="classname">main</code>. The String representation |
| of the QualifiedName would be <code class="classname">template::Template::main</code>. |
| When registering Java Defined Functions, normally only the simple |
| name of a function will be defined as it's name. The simple name is method name. |
| To set the qualified name of a function use the annotation |
| <code class="classname">@M2tQualifiedName</code>. The namespace will be |
| derived from the fully qualified class name. |
| </p> |
| <p> |
| Per default, all public methods will be registered as functions. To |
| prevent the registration of a method, annotate it with |
| <code class="classname">@M2tNoFunction</code>. |
| You may also use one of the following annotations: |
| </p> |
| <div class="itemizedlist"> |
| <ul class="itemizedlist" type="disc"> |
| <li class="listitem"> |
| <code class="classname">@M2tCached</code> - use caching |
| </li> |
| <li class="listitem"> |
| <code class="classname">@M2tPrivateFunction</code> - mark the function as private |
| </li> |
| <li class="listitem"> |
| <code class="classname">@M2tAroundAdvice(pointcut)</code> - use the method as around advice. The pointcut has the |
| parameters: |
| <div class="itemizedlist"> |
| <ul class="itemizedlist" type="circle"> |
| <li class="listitem"> |
| <code class="classname">namePattern</code> - a pattern for function names as in Xpand |
| <code class="classname">paramTypeNames</code> - an array with patterns of parameter type names |
| <code class="classname">hasVarArgs</code> - true, if the matching functions have any number of |
| parameters after <code class="classname">paramTypeNames</code> the specified in the pointcut |
| </li> |
| </ul> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <p> |
| </p> |
| <p> |
| Functions defined by methods of a Java class can be directly called |
| on the facade |
| <code class="classname">org.eclipse.xtend.middleend.javaannotations.JavaAnnotationBackendFacade |
| </code>. Call the method invoke to invoke functions defined in Java: |
| </p> |
| <pre class="programlisting">invokeFunction(String className, BackendTypesystem |
| ts, QualifiedName functionName, List<?> params) |
| </pre> |
| <p> |
| </p> |
| </div> |
| </div> |
| </body> |
| </html> |
