Flow4J - Step by Step Guide

Prerequisites

make sure that the plugin is installed correctly. You can check this if you display the installed Plug-in details:

Help Menu - > About Eclipse Platform - > Plug-in Details button

The Flow4J plug-in should be listed with the installed release number.

Create a New Flow4J Project

In the first step create a new Flow4J project from scratch.

Open the "New Project" wizard like this

In the following image you can choose the type of the desired project.

Select "Flow4J" in the left frame and "Flow4J Project" in the right frame.

Click "Next > "

On the following page you can set the name of the new project. Let's name it "MyFlow4JProj".

You now have two possibilities:

Click "Finish" - creates a new Flow4J project with the default settings of ordinary java projects: source and output folder is the project folder itself.
Click "Next > " - then you can configure the projects java settings like source, output folder, libraries and dependant projects etc.

Click "Next > " to configure the java settings

On the java configuration pane we set the following:

Source folder and output folder for the binaries
Add the "flow4jruntime.jar" to the classpath so that Task Flowlets and Flows can be compiled by the JDT Plug-in

Configure the source and output folder as on the next image.

On the "Libraries" panel add the "flow4jruntime.jar" to the classpath. The external jar file resides in the Flow4J Plug-in folder. Click on the "Add External jars..." button to add the jar to the classpath.

Finally click "Finish" to create the project in the workbench.

The project is now created and you can begin with creating the tasks and modeling the flows.

Create Package Structure

In this step, sample packages are created where we'll put all the flows and the tasks. Create the following package structure.

my.f4jprj.flows - contains all flows
my.f4jprj.tasks - contains all tasks

Of course, the flows and the tasks package can contain sub packages. But in this example we will put files flat in the packages, without using sub packages.

Create HelloWorld Task

The order, what you create first, the tasks or the flows does not matter. But its better to create the tasks first and then build the flow model, that uses those tasks. So we will forst create a HelloWorld task, that simply prints "hello world!" to System.out.

We create the new task class in the my.f4jprj.tasks package.

All tasks have to implement the net.orthanc.flow4j.runtime.ITaskFlowlet interface. But it's more convenient to extend the class net.orthanc.flow4j.runtime.AbstractTaskFlowlet . The AbstractTaskFlowlet has default implementaions of some methods. These methods can be overridden to support information on:

task properties - configurable information for tasks of the same type. Improves task reusability.
task input/output parameters - provides information for the developer which values the repository has to contain, so that the task can execute correctly. And also parameters that the task puts into the dictionary.
task description - provides a useful description of the task's functionality.

The following two methods have to be overridden/implemented by the user:

public String getName();
public void execute(FlowDictionary dictionary);

Here is a simple task implementation:

package my.f4jprj.tasks;

import net.orthanc.flow4j.runtime.AbstractTaskFlowlet;
import net.orthanc.flow4j.runtime.FlowDictionary;


public class HelloWorldTask extends AbstractTaskFlowlet {

	public String getName() {
		return "Hello World";
	}

	public void execute(FlowDictionary dictionary) {
		System.out.println("hello world!");
		//	some complex functionality
	}
}

Create HelloFlow Flow

After the task, as the atomic working unit, exists, we can embed it in a flow with the "HelloFlow" flow.

Click on the "my.f4jprj.flows" package and open the "New" wizard to create a new flow model

Specify the flow file's name and click "Finish" to create the file in the right package in the workbench

My eclipse workbench was is configured the way that resource modifications force an automatic build process. The creation of the file "HeloFlow.f4j" was a resource modification for Eclipse, so the build process was triggered and the flow's java source code was created in the file "HelloFlow.java".

Now let's model the flow, that executes the helloWorld task.

First create the rough structure of the flow. It will contain a start-flowlet, a task-flowlet for the HelloWorld task, and a terminating end-flowlet. We will set the flowlet's properties later.

The task-flowlet's label contains the default task name "Task" that we will set later. It is written in red because in the projects classpath a task class with classname "task" cannot be found.

After you set the task flowlet's "Executable class" property, the flows name, that you specified in the HelloWorldTask.java file, is dispalyed in black. So you have an immediate feedback whether the task that you want to embed into the flow really exists or whether you made a mistake while typing the task class's fully qualified class name.

You can also rename the task-flowlet's label if you want. If you don't like the position of the task-flowlet's label then drag the label to another position. Moving the flowlet's symbol automatically moves the label, so the relative positions are preserved.

Only one step has to be done to finish the flow model, the flow needs a unique name. With this name the flow will be registered at the FlowManager and can be accessed later from other flows, or by the JSPDispatcherServlet.

Click on a free area in the designer and open the "Properties view". Now you see the properties of the whole flow model. Change the "Flow name" to "Hallo".

Flow Execution

Now that the flow is modelled and compiled successfully, we can integrate it in existing java code and execute it.

Create a "Main" java class in the "my.f4jprj" package with the following code. The methods run1() and run2() demonstrate two possibilities to execute flows.