doc/org.eclipse.epsilon.book/tasks/EpsilonExecutableModule.tex

\subsection{The Abstract Executable Module Task}
\label{sec:ExecutableModuleTask}

This task is the base of all the model management tasks presented in Section \ref{sec:Workflow.ModelManagementTasks}. Its aim is to encapsulate the commonalities of Epsilon tasks in order to reduce duplication among them. As already discussed, in Epsilon, specifications of model management tasks are organized in executable modules. While modules can be stored anywhere, in the case of the workflow it is assumed that they are either stored as separate files in the file-system or they are provided inline within the worfklow. Thus, this abstract task defines an \textit{src} attribute that specifies the path of the source file in which the Epsilon module is stored, but also supports inline specification of the source of the module. The two alternatives are demonstrated in Listings \ref{lst:External} and \ref{lst:Inline} respectively.

\begin{lstlisting}[basicstyle=\ttfamily\footnotesize, flexiblecolumns=true, numbers=none, nolol=true, caption=External Module Specification, label=lst:External, numbers=left, language=XML, tabsize=2]
<project default="main">
	<target name="main">
		<epsilon.eol src="HelloWorld.eol"/>
	</target>
</project>
\end{lstlisting}

\begin{lstlisting}[basicstyle=\ttfamily\footnotesize, flexiblecolumns=true, numbers=none, nolol=true, caption=Inline Module Specification, label=lst:Inline, numbers=left, language=XML, tabsize=2]
<project default="main">
	<target name="main">
		<epsilon.eol>
			<![CDATA[
				"Hello world".println();
			]]>
		</epsilon.eol>
	</target>
</project>
\end{lstlisting}

Optionally, users can enable debugging for the module to be run by setting the \textit{debug} attribute to \textit{true}. An example is shown in Listing~\ref{lst:workflow-debug}. If the module reaches a breakpoint, users will be able to run the code step by step and inspect the stack trace and its variables.

\begin{lstlisting}[basicstyle=\ttfamily\footnotesize, flexiblecolumns=true, numbers=none, nolol=true, caption=Inline Module Specification, label=lst:workflow-debug, numbers=left, language=XML, tabsize=2]
<project default="main">
	<target name="main">
        	<epsilon.eol src="HelloWorld.eol" debug="true"/>
        </target>
</project>
\end{lstlisting}

The task also defines the following nested elements:

\paragraph{0..n $model$ nested elements}

Through the \emph{model} nested elements, each task can define which of the models, loaded in the project repository it needs to access. Each \emph{model} element defines three attributes. The \emph{ref} attribute specifies the name of the model that the task needs to access, the \emph{as} attribute defines the name by which the model will be accessible in the context of the task, and the \emph{aliases} defines a comma-delimited sequence of aliases for the model in the context of the task.

\paragraph{0..n $parameter$ nested elements}

The \emph{parameter} nested elements enable users to communicate String parameters to tasks. Each \emph{parameter} element defines a \emph{name} and a \emph{value} attribute. Before executing the module, each \emph{parameter} element is transformed into a String variable with the respective name and value which is then made accessible to the module.

\paragraph{0..n $exports$ nested elements}

To facilitate low-level integration between different Epsilon tasks, each task can export a number of variables to the project context, so that subsequent tasks can access them later. Each \emph{export} nested element defines the three attributes. The \emph{ref} attribute specifies the name of the variable to be exported, the \emph{as} string attribute defines the name by which the variable is stored in the project context and the \emph{optional} boolean attribute specifies whether the variable is mandatory. If \emph{optional} is set to \emph{false} and the module does not specify such a variable, an ANT \emph{BuildException} is raised.

\paragraph{0..n $uses$ nested elements}

The \emph{uses} nested elements enable tasks to import variables exported by previous Epsilon tasks. Each use element supports three attributes. The \emph{ref} attribute specifies the name of the variable to be used. If there is no variable with this name in the project context, the ANT project properties are queried. This enables Epsilon modules to access ANT parameters (e.g. provided using command-line arguments). The \emph{as} attribute specifies the name by which the variable is accessible in the context of the task. Finally, the \emph{optional} boolean paramter specifies if the variable must exist in the project context.

To better illustrate the runtime communication mechanism, a minimal example is provided in Listings \ref{lst:Exporter} - \ref{lst:ExporterUserWorkflow}. In Listing \ref{lst:Exporter}, \emph{Exporter.eol} defines a String variable named \emph{x} and assigns a value to it. The workflow of Listing \ref{lst:ExporterUserWorkflow} specifies that after executing \emph{Exporter.eol}, it must export a variable named \emph{x} with the new name \emph{y} to the project context. Finally, it defines that before executing \emph{User.eol} (Listing \ref{lst:User}), it must query the project context for a variable named \emph{y} and in case this is available, add the variable to the module's context and then execute it. Thus, the result of executing the workflow is \emph{Some String} printed in the output console.

\begin{lstlisting}[basicstyle=\ttfamily\footnotesize, nolol=true, flexiblecolumns=true, caption=Source code of the Exporter.eol module, label=lst:Exporter, language=EOL]
var x : String = "Some string";
\end{lstlisting}

\begin{lstlisting}[basicstyle=\ttfamily\footnotesize, nolol=true, flexiblecolumns=true, caption=Source code of the User.eol module, label=lst:User, language=EOL]
z.println();
\end{lstlisting}

\begin{lstlisting}[basicstyle=\ttfamily\footnotesize, nolol=true, flexiblecolumns=true, caption=ANT Workflow connecting modules  \ref{lst:Exporter} and \ref{lst:User} using the epsilon.eol task, label=lst:ExporterUserWorkflow , language=XML]
<epsilon.eol src="Exporter.eol">
	<exports ref="x" as="y"/>
</epsilon.eol>

<epsilon.eol src="User.eol">
	<uses ref="y" as="z"/>
</epsilon.eol>
\end{lstlisting}