Workflow Configuration

The wired up object graph consists of so called components (A workflow component is a special kind of a component). A component is declared by an XML element. The name represents the property of the parent component holding this component.

Example:

<component class='MyBean'>
	<bean class='MyBean'/>
</component>

The Java class MyBean needs to have a corresponding property accessor. E.g.:

public class MyBean {
	...
	public void setBean(MyBean b) {
		bean = b;
	}
	...
}

There are currently the following possibilities for declaring the property accessors:

The corresponding Java class (specified using the class attribute) needs to have a default constructor declared. If the class attribute is omitted, the Java class determined from the accessor method will be used. For the preceding example we could write

<component class='MyBean'>
	<bean/>
</component>

because the setter method uses the MyBean type as its parameter type. This is especially useful for more complex configurations of workflow components.

Note that we will probably add factory support in the future.

A component can have an attribute id. If this is the case, we can refer to this component throughout the following workflow configuration.

Example:

<workflow>
	<component class='my.Checker'>
		<metaModel id='mm' class='my.MetaModel'
			metaModelPackage='org.eclipse.emf.mwe.metamodel'/>
	</component>
	<component class='my.Generator'>
		<metaModel idRef='mm'/>
	</component>
	...
</workflow>

In this example, an object with the id mm (an instance of my.MetaModel ), is first declared and then referenced using the attribute idRef. Note that this object will only be instantiated once and then reused. It is not allowed to specify any other attributes besides idRef for object references.

Elements with only one attribute value are simple parameters. Simple parameters may not have any child elements.

Example:

<workflow>
	<component class='my.Checker' myParam='foo'>
		<anotherParam value='bar'/>
	</component>

As you can see, there are two ways to specify a simple paramter.

Both methods are equivalent, although declaring an attribute way saves a few keystrokes. However, the attributes class, id, and file are reserved so they cannot be used.

Parameters are injected using the same accessor methods as described for components. The only difference is, that they are not instantiated using a default constructor, but instead, they are using a so-called converter.

If an element has a property file, it is handled as an inclusion. Using an inclusion, one can inject a graph described in another workflow file. Here is an example:

file 1: mybean.mwe

<anyname class='MyClass'/>

file 2: workflow.mwe

<comp class='MyBean'>
	<bean file='mybean.mwe'/>
</comp>

One can pass properties and components into the included file in the usual way.

file 1: mybean.mwe

<anyname class='MyClass' aProp='${myParam}'>
	<bean idRef='myComponent'/>
</anyname>

file 2: workflow.mwe

<comp class='MyBean'>
	<bean file='mybean.mwe'>
		<myParam value='foo'/>
		<myComponent class='MyBean'/>
	</bean>
</comp>

As you can see, simple parameters are mapped to properties in the included workflow file, and components can be accessed using the idRef attribute.

Properties defined in the included workflow description will be overwritten by the passed properties.

The root element of a workflow description can have any name, because there is no parent defining an accessor method. Additionally, you have to specify the attribute class for a root element. There is only one exception: If the root element is named workflow the engine knows that it has to instantiate the type org.eclipse.mwe.runtime.Workflow. Of course you can specify your own subtype of org.eclipse.mwe.runtime.Workflow using the class attribute (if you need to for any reason).

If you do not want to explicitely pass the parameters to an included workflow description, you can use the inheritAll attribute. This will make all the properties and beans that are visible to the actual workflow file also visible to the included workflow file.

<component file="my/included/workflow.mwe" inheritAll="true"/>

Workflow components have to communicate among each other. For example, if an XMIReader component reads a model that a constraint checker component wants to check, the model must be passed from the reader to the checker. The way this happens is as follows: In the invoke operation, a workflow component has access to the so-called workflow context . This context contains any number of named slots. In order to communicate, two components agree on a slot name, the first component puts an object into that slot and the second component takes it from there. Basically, slots are named variables global to the workflow. The slot names are configured from the workflow file. Here is an example:

<?xml version="1.0" encoding="windows-1252"?>
<workflow>
	<property file="workflow.properties"/>

	<component id="xmiParser"
		class="org.eclipse.xtend.typesystem.emf.XmiReader">
		<outputSlot value="model"/>
	</component>

	<component id="checker" class="datamodel.generator.Checker">
		<modelSlot value="model"/>
	</component>
</workflow>

As you can see, both these workflow components use the slot named model . Below is the (abbreviated) implementation of the XmiReader. It stores the model data structure into the workflow context in the slot whose name was configured in the workflow file.

public class XmiReader implements WorkflowComponent {

	private String outputSlot = null;

	public void setOutputSlot(String outputSlot) {
		this.outputSlot = outputSlot;
	}

	public void invoke(WorkflowContext ctx, ProgressMonitor monitor,
		Issues issues) {
		Object theModel = readModel();
		ctx.put( outputSlot, theModel );
	}

}

The checker component reads the model from that slot:

public class Checker implements WorkflowComponent {

	private String modelSlot;

	public final void setModelSlot( String ms ) {
		this.modelSlot = ms;
	}

	public final void invoke(WorkflowContext ctx,
		ProgressMonitor monitor, Issues issues) {

		Object model = ctx.get(modelSlot);
		check(model);
	}
}

Issues provide a way to report errors and warnings. There are two places, where issues are used in component implementations:

The Issues API is pretty straightforward: you can call addError and addWarning. The operations have three parameters: the reporting component, a message as well as the model element that caused the problem, if there is one. The operations are also available in a two-parameter version, omitting the first (reporting component) parameter.

There is an implicit way of controlling the workflow: if there are errors reported from any of the checkConfiguration operations of any workflow component, the workflow will not start running.

There is also an explicit way of terminating the execution of the workflow: if any invoke operation throws a WorkflowInterruptedException (a runtime exception) the workflow will terminate immediately.

The class org.eclipse.emf.mwe.core.WorkflowRunner is the main entry point if you want to run the workflow from the command line. Take a look at the following example:

java org.eclipse.emf.mwe.core.WorkflowRunner path/workflow.mwe

You can override properties using the -p option:

java org.eclipse.emf.mwe.core.WorkflowRunner -pbasedir=/base/ path/workflow.mwe

We also have an Ant task. Here is an example:

	<target name='generate'>
		<taskdef name="workflow" classname="org.eclipse.emf.mwe.core.ant.WorkflowAntTask"/>
			<workflow file='path/workflow.mwe'>
				<param name='baseDir' value='/base/'/>
			</workflow>
			...
		</target>

The Workflow ant task extends the Java ant task. Therefore, you have all the properties known from that task (classpath, etc.).

You can also run the generator from your own application code. Two things to note:

	String wfFile = "somePath\\workflow.mwe";
	Map properties = new HashMap();
	Map slotContents = new HashMap();
	new WorkflowRunner().run(wfFile ,
		new NullProgressMonitor(), properties, slotContents)