Configuration

The Fornax Workflow M2-Plugin is highly configurable. So there are many items you can change or add to the runtime. This page documents these parameters.

Dependencies

One of the main features of this plugin is the loose coupling to the underlying workflow engine framework. Since multiple workflow engines (oAW/MWE/MWE2) are supported, the required runtime dependencies of the workflow must be configured. This can be either done with project dependencies or with dependencies within the plugin conifguration.

<plugin>
	<groupId>org.fornax.toolsupport</groupId>
	<artifactId>fornax-oaw-m2-plugin</artifactId>
	<dependencies>
		<dependency>
			<groupId>org.eclipse.emf.mwe</groupId>
			<artifactId>emf-mwe-utils</artifactId>
			<version>0.7.2</version>
		</dependency>
		<dependency>
			<groupId>org.eclipse.m2t.xpand</groupId>
			<artifactId>m2t-xpand-xpand</artifactId>
			<version>0.7.2</version>
		</dependency>
		<dependency>
			<groupId>org.eclipse.m2t.xpand</groupId>
			<artifactId>m2t-xpand-xtend-typesystem-emf</artifactId>
			<version>0.7.2</version>
		</dependency>
	</dependencies>
</plugin>

<dependencies>
	<dependency>
		<groupId>org.fornax.openarchitectureware</groupId>
		<artifactId>oaw-uml2</artifactId>
		<version>4.3.1</version>
		<type>pom</type>
		<scope>runtime</scope>
	</dependency>
</dependencies>

This has changed in 2.0.0. Before 2.0.0 you have to configure the dependencies at the plugin. Now you configure the dependencies as simple project dependencies. You can add the scope tag with setting runtime, because the dependencies aren't needed at compile time.

Configuration

The plugin is fully configurable. So there are many parameters you can add to the configuration of the plugin. 

<plugin>
 	<groupId>org.fornax.toolsupport</groupId>
	<artifactId>fornax-oaw-m2-plugin</artifactId>
	<version>3.4.0</version>
	<configuration>
		[ANY CONFIGURATION PARAMETER]
	</configuration>
</plugin>

Properties

You can add any property to the plugin. These properties will be directly relayed to the oAW Workflow component. A property contains a key and a value.

<plugin>
 	<groupId>org.fornax.toolsupport</groupId>
	<artifactId>fornax-oaw-m2-plugin</artifactId>
	<configuration>
		<properties>
			<keyname1>value1</keyname1>
			<keyname2>value2</keyname2>
			[...]
		</properties>
	</configuration>
 </plugin>

The defined properties are relayed directly to the workflow component. You can add properties to a Properties file, too, and add this file to the workflow file with

<property file="workflow.properties"/>

But this is only useful if the properties are static and not depending on the Build directly (e.g. data out of the settings or pom.xml)

Outlets

Outlets are properties holding information about output pathes. If you generate code you often want to write different generated artifacts to different output locations (e.g. always generated vs. only once generated). To beware you for long configurations for this outlets this plugin defines preconfigured outlets. This should be good for the common use cases. But every outlet can be reconfigured, of course.

Mapping outlet names to properties

To use the outlets as configuration parameters in the Maven configuration we don't use dots in the names. To map this to common used names in properties we build an internal property map and add the outlets (decribed above) to this. All additonally properties you define in the configuration will be added to this map, too.

 The property names you can use in your workflow file:

<component id="generator" class="org.openarchitectureware.xpand2.Generator">
	[...]
	<outlet>
		<path value="${outlet.src.dir}"/>
	</outlet>
	<outlet name="RES_DIR">
		<path value="${outlet.res.dir}"/>
	</outlet>
	<outlet name="SRC_ONCE_DIR">
		<path value="${outlet.src.once.dir}"/>
		<overwrite value="false"/>
	</outlet>
	<outlet name="RES_ONCE_DIR">
		<path value="${outlet.res.once.dir}"/>
		<overwrite value="false"/>
	</outlet>
	[...]
</component>

Of cource you can change the value of each outlet. This can be done in the configuration, too:

<plugin>
 	<groupId>org.fornax.toolsupport</groupId>
	<artifactId>fornax-oaw-m2-plugin</artifactId>
	<configuration>
		<outletSrcOnceDir>src/main/once/java</outletSrcOnceDir>
		[...]
	</configuration>
</plugin>

Detecting changes

Executing a workflow should only be triggered when necessary, since it usually consumes reasonable build time. Therefore the plugin has several configuration possibilities to decide if a workflow should be executed at all. A timestamp file is created after execution in the build output directory (target), against its timestamp changes can be compared.

checkFilesets

(since 3.0.2)

This configuration parameter allows a more flexible configuration of resources to be checked against the last generator run timestamp. If all resources are up-to-date then the generator is not executed. This is useful to check if the models, templates or platform files are changes since the last run. This shortens the build time.

 <plugin>
  <groupId>org.fornax.toolsupport</groupId>
  <artifactId>fornax-oaw-m2-plugin</artifactId>
  <configuration>
    ...
    <checkFilesets>
      <checkFileset>
        <directory>${basedir}</directory>
        <includes>
          <include>src/**/*.java</include>
        </includes>
        <excludes>
          <exclude>.svn</exclude>
        </excludes>
      </checkFileset>
    </checkFilesets>
    ...
  </configuration>

checkDependencies

(since 3.4.0)

When set, the Jar artifacts on the execution classpath are compared against the timestamp file. This is typically useful if the generator should be executed due to changes on depending artifacts, like a generator module or dependent models deployed in another artifact.

 <plugin>
  <groupId>org.fornax.toolsupport</groupId>
  <artifactId>fornax-oaw-m2-plugin</artifactId>
  <configuration>
    ...
    <checkDependencies>true</checkDependencies>
    ...
  </configuration>

changedFiles System property

(since 3.4.0)

By setting the System Property fornax-oaw-m2-plugin.changedFiles a comma seperated list of files can be passed to the plugin which are examined for changes against the timestamp file.

checkResources

This feature is deprecated and will be removed in the future. Use the checkFilesets configuration instead.

With this configuration parameter you can declare resources that will be checked if they are newer than the last generator run. If not, no new generation is needed, otherwise the generator will be started. This is useful to check if the model(s) are changes since the last run. This shortens the build time.

<plugin>
 	<groupId>org.fornax.toolsupport</groupId>
	<artifactId>fornax-oaw-m2-plugin</artifactId>
	<configuration>
		<checkResources>
			<checkResource>src/main/resources/models/mymodel.uml2</checkResource>
		</checkResources>
	</configuration>
</plugin>

This sample defines one checkResource. If the mymodel.uml2 is older than the last generation run the generator does not run.
The generator is creating a timestamp file in the target directory. This file can be configured with the parameter timestampFileName.

<plugin>
 	<groupId>org.fornax.toolsupport</groupId>
	<artifactId>fornax-oaw-m2-plugin</artifactId>
	<configuration>
		<timestampFileName>mytimestampfile.tmp</timestampFileName>
	</configuration>
</plugin>

Configuring the workflow

Selecting workflow engine

Since version 3.1.0 the plugin supports also the Eclipse MWE2 workflow engine, the successor of the workflow engine used by openArchitectureWare 4. The used engine can be switched with the 'workflowEngine' parameter. Valid values are

• mwe2: Eclipse MWE2 (default)
• mwe : Eclipse MWE 
• oaw : openArchitectureWare 4

• <plugin>
          <groupId>org.fornax.toolsupport</groupId>
  	<artifactId>fornax-oaw-m2-plugin</artifactId>
  	<version>3.1.0</version>
  	<configuration>
  		<workflowEngine>mwe</workflowEngine>
  	</configuration>
  </plugin>
  

workflowDescriptor

With this parameter you can define the workflow file that will be used during the generation phase. 

 <plugin>
 	<groupId>org.fornax.toolsupport</groupId>
	<artifactId>fornax-oaw-m2-plugin</artifactId>
	<configuration>
		<workflowDescriptor>src/org/xtext/example/mydsl/GenerateMyDsl.mwe2</workflowDescriptor>
	</configuration>
</plugin>

Remember that any resource you want to use must be located inside the classpath in order to be findable for the classloader! Usually resources are located in src/main/resources.
For further information how to handle resources inside your project, refer to the Structure of Cartridges article.

Forcing / skipping workfow execution

Omitting the execution of the generator

In some cases it is useful to execute the generation phase without  the execution of the generator.

Execution can be omitted by setting the 'skip' parameter:

<plugin>
<groupId>org.fornax.toolsupport</groupId>
<artifactId>fornax-oaw-m2-plugin</artifactId>
<configuration>
<skip>true</skip>
</configuration>
</plugin>

Execution can also be omitted by setting the System Property

fornax.generator.omit.execution

 This property you can add to the Maven call:

> mvn -Dfornax.generator.omit.execution=true generate-sources

Force the execution of the generator

In the other case sometimes you want force the execution of the generator.

Execution can be forced by setting the 'force' parameter:

<plugin>
<groupId>org.fornax.toolsupport</groupId>
<artifactId>fornax-oaw-m2-plugin</artifactId>
<configuration>
<force>true</force>
</configuration>
</plugin>

There is a System property, too:

fornax.generator.force.execution

 You can add this property to the Maven call:

>mvn -Dfornax.generator.force.execution=true generate-sources

 If this property is set the up-to-date check doesn't matter.

JVM Configuration

Since: 3.2.0

For execution of a workflow the JVM can be configured using the <jvmSettings> configuration parameter.

<jvmSettings>
    <fork>true</fork>
    <jvmArgs>
        <jvmArg>-Xms100m</jvmArg>
        <jvmArg>-Xmx500m</jvmArg>
    </jvmArgs>
    <sysProperties>
        <property>
            <name>someKey</name>
            <value>someValue</value>
        </property>
    </sysProperties>
    <envProperties>
        <property>
            <name>envprop</name>
            <value>envprop-someValue</value>
        </property>
    </envProperties>
</jvmSettings>

• fork: if true the workflow will be executed in a forked JVM process (required for MWE2)
• jvmArgs: A set of VM arguments
• sysProperties: Definition of system properties
• envProperties: Definition of environment variables

Security Manager Configuration

Since 3.2.0

You can activate access to your resources by configuring Java Security permissions in a <securitySettings> section. If you don't provide this section the plugin will run without specialized settings.

 <securitySettings>
  <grantedPermissions>
    <permission>
      <class>java.util.PropertyPermission</class>
      <name>user.dir</name>
      <actions>read,write</actions>
    </permission>
    ...permission
  </grantedPermissions>
  <revokedPermissions>
    <permission>
      <class>java.lang.RuntimePermission</class>
      <name>exitVM</name>
    </permission>
    ...permission
  </revokedPermission>
</securitySettings>

If a <securitySection> is provided the plugin will grant some default permissions:

 // add default permissions
// these are the minimal permissions required to execute the workflow
if (fork) {
	permissions.addConfiguredGrant(createPermission(RuntimePermission.class, "exitVM", null));
	permissions.addConfiguredGrant(createPermission(RuntimePermission.class, "shutdownHooks", null));
}
permissions.addConfiguredGrant(createPermission(RuntimePermission.class, "setContextClassLoader", null));
permissions.addConfiguredGrant(createPermission(RuntimePermission.class, "getClassLoader", null));
permissions.addConfiguredGrant(createPermission(RuntimePermission.class, "readFileDescriptor", null));
permissions.addConfiguredGrant(createPermission(RuntimePermission.class, "writeFileDescriptor", null));
permissions.addConfiguredGrant(createPermission(RuntimePermission.class, "accessDeclaredMembers", null));
permissions.addConfiguredGrant(createPermission(PropertyPermission.class, "user.dir", "read, write"));
permissions.addConfiguredGrant(createPermission(PropertyPermission.class, "ant.build.clonevm", "read"));

permissions.addConfiguredGrant(createPermission(FilePermission.class, mvnProject.getBasedir().getAbsolutePath()+"/-", "read, write"));
// see Execute#getProcEnvCommand()
permissions.addConfiguredGrant(createPermission(FilePermission.class, "/bin/env", "read"));
permissions.addConfiguredGrant(createPermission(FilePermission.class, "/usr/bin/env", "read, execute"));
for (URL constituent : realm.getConstituents()) {
	permissions.addConfiguredGrant(createPermission(FilePermission.class, constituent.getFile(), "read"));
}
permissions.addConfiguredGrant(createPermission(FilePermission.class, javaTask.getCommandLine().getVmCommand().getExecutable(), "read, execute"));

Mapping log levels in forked mode

Since 3.4.0

Executing workflows in a forked JVM (MWE2 or jvmSettings/forked=true) raises a problems detecting error conditions: The executed Java task returns without error code even when the workflow execution fails. This makes it problematic to terminate the invoking Maven process with failure. The plugin allows to work around this problem by detecting log levels depending on patterns the workflow writes to stdout. Usually log statements that are written to stdout in the forked VM contain the log level, depending on log4j configuration. The log level detection can be done with the <logDetectionPatterns> configuration.

<configuration>
<logDetectionPatterns>
	<logDetectionPattern>
		<level>2</level>
		<detectionString>WARNING</detectionString>
		<regexp>false</regexp>
	</logDetectionPattern>
</logDetectionPatterns>
</configuration>

level

The following log levels can be set, alternatively using the levelAsString property.

detectionPattern

detectionPattern can be either a simple string to search for in a line (with String.contains()), or a regular expression. In this case the property <regexp> must be set to true. When using a regular expression a regexp group can be defined which contains the message itself. This can be used to exclude message prefixes like repeating the log level message.

<configuration>
<logDetectionPatterns>
	<logDetectionPattern>
		<level>2</level>
		<detectionString>.*\[WARNING\]\s+(.*)</detectionString>
		<regexp>true</regexp>
	</logDetectionPattern>
</logDetectionPatterns>
</configuration>

multiline

The multiline parameter can be set to true when the last detected log level should be kept until the next level is detected. This can be useful when e.g. searching for an error pattern in front of a stack trace (which does not contain an ERROR string) until a line is detected after the stack trace which contains another detection pattern.

Other

Encoding

The plugin does not delegate the Maven property project.build.sourceEncoding to the Xpand engine. It is vital for Xpand to read templates in the correct encoding. To do so there are 2 alternatives:

• set fileEncoding property for the Xpand Generator component (recommended; see Xpand reference)
• set MAVEN_OPTS=-Dfile.encoding=UTF-8