Flow4J
 Flow4j.RunFlows News
 
Project Info
Documentation
Download
Status
License
SourceForge Logo
  

Running A Flow

Prerequisites

you need the library flow4j-runtime.-xxx.jar in order to access the FlowManager and flows.

General

A flow is an ordinary java class as many others. The Flow class implements the IFlow interface that has one method:
  start(String startFlowletName, Map dictionary)
Theoretically you can create an instance of a flow and call its start-method. A better way is to use the FlowManager, that caches singleton instances of already used flows. Instantiating a class is not cheep, so accessing flows through the FlowManager increates the apllications performance.

A Flow can have more than one StartFlowlet, which act as entry points of the flow. The second parameter is a Map that holds read/write information while the flow is executed. For example the dictionary can be populated with data before the flow is started, then some floelets change the dictionary's data and when the flow execution is finished, the calling application can retrieve the expected data from the map.

A flow is a collection of flowlets which are connected individually together. The comparison to process steps is not fully correct, because a StartFlowlet or a DecisionFlowlet fullfills no task. The TaskFlowlet on the other hand executes code, eg. java bytecode, and can be called a process step

Saved Flow Format

If you save a flow in the FlowDesigner a file with prefix ".flow" will be created in the specified directory. Every flow file is a jar-file. For example the flow "PutInBasket" contains the following:
  • package "flows"
    • PutInBasket.java
    • PutInBasket.class
  • package "loader"
    • PutInBasket.java

The "flows" package contains the class file that is needed for runtime execution. Every flow is in the package "flows". The java file in the flows package is currently only for debugging reasons.

The "loader" package contains a java file that is compiled and executed , on the fly, when the flow is opened in the FlowDesigner.

Since the flow file is a jar file that contains the flow's bytecode, it can be used as any ordinary jar file and can be put in the classpath or in the ./WEB_INF/lib directory.
ALERT! In some application servers, like resin, you have to rename the flow file with the extension ".jar" if you put the flow file in the ./WEB_INF/lib folder so that the app server recognizes it as a archive file.

Java Application Environment

In a runtime environment all flows are started by the flow manager. The flow manager is a singleton class that implements some static start(...) methods to run a flow. While flow execution a Map is passed around between the linked flowlets thats content can be populated/updated by the various flowlets. The following code snippet shows the possible ways to run a flow in a java application. 

import flow4j.flow.FlowMgr;
import flow4j.flow.FlowDictionary;

static public main(String[] args) {
  FlowMgr.start("MyFlow-Start");
  FlowMgr.start("MyFlow", "Start");

  FlowDictionary dictionary = new FlowDictionary();
  dictionary.put("name", "Alex");
  FlowMgr.start("MyFlow-Start", dictionary);
  FlowMgr.start("MyFlow", "Start", dictionary);
}

After the flow executed, the dictionary may contain key-value-pairs that was placed there by some flowlets. This information can be used by the calling application for further processes. Another way to use the dictionary is to provide the contents for a JSP page.

Web Application Environment

To run flows in an application server environment you need a J2EE capable app server like tomcat, jetty or resin.
Do the following steps to trigger a flow by your browser:
  • write the needed tasks and compile them
  • move the task class files to ./WEB-INF/classes
  • design the needed flows with the FlowDesigner
  • append ".jar" to the flow names. E.g. OrderBasket.flow becomes OrderBasket.flow.jar.
  • move the flow jar files to ./WEB_INF/lib
  • move runtime.jar to ./WEB_INF/lib
  • update web.xml with the following entry 
   <servlet>
      <servlet-name>FlowServlet</servlet-name>
      <display-name>Flow4J Servlet</display-name>
      <servlet-class>flow4j.servlet.FlowServlet</servlet-class>
   </servlet>

   <servlet-mapping>
         <servlet-name>FlowServlet</servlet-name>
         <url-pattern>*/FlowServlet/*</url-pattern>
   </servlet-mapping>
  • call the following url on your browser: http://127.0.0.1:8080/somewebapp/FlowServlet/SomeFlow-Start

Flow URL's have the following syntax:

{protocol}://{ip or domain}:{port}/{webapp-context}/{servlet-url-pattern}/{flowname}-{startname}?{key-value-pair}&...

Here you see some examples:

  • http://127.0.0.1:8080/somecontext/FlowServlet/Login-Success
  • http://127.0.0.1:8080/myshop/FlowServlet/PutInBasket-Start?uuid=234565678&someBool=true

The most interesting part is the URI extension "flowname-startname" that appears after the the servlet declaration but before the ? sign. The hyphen is necessary to separate the flow name from the name of the start flowlet. Every flow may have more than one start flowlet, so valid syntax is for example:

  • MyFlow-Start
  • Login-Success
  • Login-Failed

  v0.5.1 released
minor changes

v0.5 released
FlowServlet implemented
Flowlet interface changed
new Flowlets: Call, Jump, Join

v0.4.5 released
Bugfix release

v0.4.4 released
EndFlowlet introduced.
DecisionFlowlet implemented.
TemplateFlowlet implemented.

v0.4.3 released
Using Kopi compiler instead of InstantJ.
Checking some Flow errors.

v0.4.2 released
TaskFlowlet properties implemented
Ant buildfile redesigned. Avaliable for windows too.
many samples!

v0.4.1 released
Bugfixes and designer improvements.

v0.4 released
Designer is written in Nice. Compiles the flow while saving in jar file.
Missing Flowlets will follow soon.

Designer relaunch
The Designer will be completely rewritten without JHotDraw. The saved flow format will change!!!