To demonstrate use of each implementation, we start with a node that just prints out "Hello, World". We start with the process definition.

<?xml version="1.0"?>
<process-definition
  name="hello-world"
  xmlns="http://sarasvati.googlecode.com/ProcessDefinition">

  <node name="hello" type="helloWorld" isStart="true"/>

</process-definition>

package com.googlecode.sarasvati.example.mem;

import com.googlecode.sarasvati.Arc;
import com.googlecode.sarasvati.Engine;
import com.googlecode.sarasvati.NodeToken;
import com.googlecode.sarasvati.mem.MemNode;

public class HelloNode extends MemNode
{
  @Override
  public void execute (Engine engine, NodeToken token)
  {
    System.out.println( "Hello, world!" );
    engine.completeExecution( token, Arc.DEFAULT_ARC );
  }
}

import javax.persistence.DiscriminatorValue;
import javax.persistence.Entity;

import com.googlecode.sarasvati.Arc;
import com.googlecode.sarasvati.Engine;
import com.googlecode.sarasvati.NodeToken;
import com.googlecode.sarasvati.hib.HibNode;

@Entity
@DiscriminatorValue( "helloWorld" )
public class HelloNode extends HibNode
{
  @Override
  public void execute (Engine engine, NodeToken token)
  {
    System.out.println( "Hello, World!" );
    engine.completeExecution( token, Arc.DEFAULT_ARC );
  }
}

insert into wf_node_type (id, description, behaviour)
 values ( 'helloWorld', 'Says hello to the world', 'helloWorld' )

import com.googlecode.sarasvati.Arc;
import com.googlecode.sarasvati.CustomNode;
import com.googlecode.sarasvati.Engine;
import com.googlecode.sarasvati.NodeToken;

public class HelloNode extends CustomNode
{
  @Override
  public void execute (Engine engine, NodeToken token)
  {
    System.out.println( "Hello, World!" );
    engine.completeExecution( token, Arc.DEFAULT_ARC );
  }
}

insert into wf_node_type (id, description, behaviour)
 values ( 'helloWorld', 'Says hello to the world', 'custom' )

    MemEngine engine = new MemEngine();

    // Tell engine about our custom node type
    engine.addNodeType( "helloWorld", HelloNode.class );

    // Load the process definition (this can throw LoadException or JAXBException
    // The graph will be stored in the GraphRepository for this engine
    engine.getLoader().load( "/path/to/hello-world.wf.xml" );

    // Get the graph from the GraphRepository
    Graph graph = engine.getRepository().getLatestGraph( "hello-world" );

    // start a graph process
    GraphProcess process = engine.startProcess( graph );

    Session session = ...; // get hibernate session
    HibEngine engine = new HibEngine( session );

    // Tell engine about our custom node type
    engine.addNodeType( "helloWorld", HelloNode.class );

    // Load the process definition (this can throw LoadException or JAXBException
    // The graph will be stored in the GraphRepository for this engine
    engine.getLoader().load( "/path/to/hello-world.wf.xml" );

    // Get the graph from the GraphRepository
    Graph graph = engine.getRepository().getLatestGraph( "hello-world" );

    // start a graph process
    GraphProcess process = engine.startProcess( graph );

    MemEngine engine = new MemEngine();

    // We can either register the type with the Engine or with the DefaultNodeFactory
    // directly.
    // Either tell the engine about our custom node type
    engine.addGlobalCustomNodeType( "helloWorld", HelloNode.class );

    // or tell the DefaultNodeFactory about the node type directly
    DefaultNodeFactory.addGlobalCustomType( "helloWorld", HelloNode.class );

    // Load the process definition (this can throw LoadException or JAXBException
    // The graph will be stored in the GraphRepository for this engine
    engine.getLoader().load( "/path/to/hello-world.wf.xml" );

    // Get the graph from the GraphRepository
    Graph graph = engine.getRepository().getLatestGraph( "hello-world" );

    // start a graph process
    GraphProcess process = engine.startProcess( graph );

Here we examine a more complicated example, which uses custom attributes.

<?xml version="1.0"?>

<process-definition
  name="example1"
  xmlns="http://sarasvati.googlecode.com/ProcessDefinition">

  <node name="start" isStart="true">
    <arc to="1"/>
  </node>

  <node name="1" type="task">
    <arc to="2"/>
    <arc to="3"/>

    <custom>
      <taskName>Enter order</taskName>
      <taskDesc>
        Enter order and billing info
      </taskDesc>
    </custom>
  </node>

  <node type="task" name="2">
    <arc to="4"/>

    <custom>
      <taskName>Bill Customer</taskName>
      <taskDesc>
        Bill the Customer
      </taskDesc>
    </custom>
  </node>

  <node type="task" name="3">
    <arc to="4"/>

    <custom>
      <taskName>Ship product</taskName>
      <taskDesc>
        Package and ship product
      </taskDesc>
    </custom>
  </node>

  <node type="task" name="4" joinType="labelAnd">

    <custom>
      <taskName>Market to Customer</taskName>
      <taskDesc>
        Send marketing material to customer
      </taskDesc>
    </custom>

  </node>

</process-definition>

We will need a couple of classes to represent tasks and their state. First we look at the memory based implementation.

First we have an enum for task states.

public enum TaskState { Open, Completed, Rejected }

Next is the Task class.

public class Task
{
  protected NodeToken nodeToken;
  protected String name;
  protected String description;
  protected TaskState state;

  public Task (NodeToken nodeToken, String name, String description, TaskState state)
  {
    this.nodeToken = nodeToken;
    this.name = name;
    this.description = description;
    this.state = state;
  }

  public NodeToken getNodeToken ()
  {
    return nodeToken;
  }

  public void setNodeToken (NodeToken nodeToken)
  {
    this.nodeToken = nodeToken;
  }

  public String getName ()
  {
    return name;
  }

  public String getDescription ()
  {
    return description;
  }

  public TaskState getState ()
  {
    return state;
  }

  public void setState (TaskState state )
  {
    this.state = state;
  }

  public boolean isRejectable ()
  {
    Node node = getNodeToken().getNode();
    return !node.getGraph().getOutputArcs( node, "reject" ).isEmpty();
  }
}

In our simple example, we need some way of tracking which tasks have been created.

public class TaskList
{
  protected static List<Task> tasks = new LinkedList<Task>();

  public static List<Task> getTasks ()
  {
    return tasks;
  }
}

Finally, the custom node for generating tasks

public class TaskNode extends MemNode
{
  protected String taskName;
  protected String taskDesc;

  public String getTaskName ()
  {
    return taskName;
  }

  public void setTaskName (String taskName)
  {
    this.taskName = taskName;
  }

  public String getTaskDesc ()
  {
    return taskDesc;
  }

  public void setTaskDesc (String taskDesc)
  {
    this.taskDesc = taskDesc;
  }

  @Override
  public void execute (Engine engine, NodeToken token)
  {
    Task newTask = new Task( token, getTaskName(), getTaskDesc(), TaskState.Open );
    TaskList.getTasks().add( newTask );
  }
}

When a task node is executed, it will create new Task instance and add it to a task list. A task can be completed or rejected as seen in the following code snippet:

      Task t = ...;

      if ( isCompletion )
      {
        t.setState( TaskState.Completed );
        engine.completeExecution( t.getNodeToken(), Arc.DEFAULT_ARC );
      }
      else if ( isReject && t.isRejectable() )
      {
        t.setState( TaskState.Rejected );
        engine.completeExecution( t.getNodeToken(), "reject" );
      }

The primary difference with the database/Hibernate version, is that the node and tasks will require database backing. Let us look at the TaskNode class.

@Entity
@DiscriminatorValue( "task" )
@SecondaryTable( name="wf_node_task", pkJoinColumns=@PrimaryKeyJoinColumn(name="id"))
public class TaskNode extends HibNode
{
  @Column (name="name", table="wf_node_task")
  protected String taskName;

  @Column (name="description", table="wf_node_task")
  protected String taskDesc;

  public TaskNode() { /* Default constructor for Hibernate */ }

  public String getTaskName ()
  {
    return taskName;
  }

  public void setTaskName (String taskName)
  {
    this.taskName = taskName;
  }

  public String getTaskDesc ()
  {
    return taskDesc;
  }

  public void setTaskDesc (String taskDesc)
  {
    this.taskDesc = taskDesc;
  }

  @Override
  public void execute (Engine engine, NodeToken token)
  {
    HibEngine hibEngine = (HibEngine)engine;

    Session session = hibEngine.getSession();

    TaskState open = (TaskState)session.load( TaskState.class, 0 );
    Task newTask = new Task( (HibNodeToken)token, getTaskName(), getTaskDesc(), open );
    session.save( newTask );
  }
}

A process environment is read-write and is shared across an entire process.

  GraphProcess p = ...;
  Env env = p.getEnv();
  env.setAttribute( "foo", "test" );
  env.setAttribute( "bar", 5 );
  String foo = env.getAttribute( "foo" );
  int bar = env.getAttribute( "foo", Integer.class );
           
         

The node token environment is read-write. Node token state is only visible to the given token, however tokens inherit the environment of their parents. Token state is initialized using the following rules:

  NodeToken t = ...;
  Env env = t.getEnv();
  env.setAttribute( "foo", "test" );
  env.setAttribute( "bar", 5 );
  String foo = env.getAttribute( "foo" );
  int bar = env.getAttribute( "foo", Integer.class );

         

To read from both the process and node token environments, use the NodeToken#getFullEnv() method. It will return an Env which will read first from node token environment and, if no attribute is defined there, read from the process environment. All writes will affect the node token environment.

This is implemented using NestedEnv, which can be used to stack any combination of environments.

When working with token sets, there are two environments available.

To see how token set environments are used, take as an example an approval process. The token set is generated as follows:

Map<String,List<?>> initialMemberEnv = new HashMap<String, List<?>>();
String[] groups = new String[] { "Accounting",
                                 "Security",
                                 "Operations" };
initialMemberEnv.put( "group", Arrays.asList( groups ) );

Env tokenSetEnv = new MapEnv();
tokenSetEnv.setAttribute( "deadline", 3 );

engine.completeWithNewTokenSet(
    token,           // the token being completed
    Arc.DEFAULT_ARC, // the name of the arc(s) to exit on
    "approvals",     // name to give the new token set
    3,               // number of tokens to generate on each arc
                     // with the given name
    true,            // completing asynchronously
    tokenSetEnv,     // initial token set env
    initialMemberEnv // token set member env
  );

         

This generates a token set with three tokens in it. They all share a common deadline attribute, but each will see a different value for the group attribute. These attributes can be access from the tokens in the token set as follows:

// Access the token set environment
Env setEnv = token.getTokenSet( "approvals" ).getEnv();
int deadline = setEnv.getAttribute( "deadline", Integer.class );

// Access the environment specific to this token within the token set
Env env = token.getTokenSetMember( "approvals" ).getEnv();
String group = env.getAttribute( "group" );

         

When defining an external in a process definition, attributes may be defined for that external. Those attributes will be visible to nodes in the referenced external. In the following process definition, when node A is executed, it will print out the values defined for attributes named foo and bar. If the process definition were executed directly, both values would be undefined.

<process-definition
  name="external-env-one"
  xmlns="http://sarasvati.googlecode.com/ProcessDefinition">

  <node name="A" type="script">
    <custom>
      <execute type="js">
        var env = token.getNode().getExternalEnv();
        System.out.println( "foo: " + env.getAttribute( "foo" ) );
        System.out.println( "bar: " + env.getAttribute( "bar" ) );
      </execute>
    </custom>
  </node>
</process-definition>

           

Process definition external-env-one can be included in external-env-two, as demonstrated below. If executed, foo would now have the value hello and bar would have the value world.

<process-definition
  name="external-env-two"
  xmlns="http://sarasvati.googlecode.com/ProcessDefinition">

  <node name="B">
    <arc external="one" to="A"/>
  </node>

  <external name="one" processDefinition="external-env-one">
    <custom>
      <foo>hello</foo>
      <bar>world</bar>
    </custom>
  </external>

</process-definition>

          

The values defined for externals can be overriden. This can happen when the proces definition which defines the external is itself references as an external, as below. Now, foo will have the value goodbye, while bar will retain the value world.

<process-definition
  name="external-env-three"
  xmlns="http://sarasvati.googlecode.com/ProcessDefinition">

  <node name="C" isStart="true">
    <arc external="two" to="B"/>
  </node>

  <external name="two" processDefinition="external-env-two">
    <custom>
      <foo>goodbye</foo>
    </custom>
  </external>

</process-definition>

          

Here is a simple, linear workflow:

Figure 4.1. Linear Process Definition

In this case, there is only one progression that can be made. Using squares for node tokens and triangles for arc tokens, the resulting execution looks like:

Figure 4.2. 

What if we wish to let a user choose to send the workflow backwards, instead of forwards, say to fix a mistake made earlier. If we wanted to be able to go back, we'd have to set up arcs going backwards. Assuming, we want maximum flexibility, we'd end up with a process definition that looked like:

Figure 4.3. Manual Linear Backtracking

Now we could go from A to B to C, back to B to C to D, back to B to C to D and done. The execution would look like:

Figure 4.4. Manual Linear Backtracking: Execution

Note that the arc tokens now display the arc name.

We have gained flexibility, but at the cost of making the workflow much more complex. The number of arcs has tripled. What if instead, we could use the existing arcs? After all we know where we've been, and we just wish to go back to a previous good state. So, rather than having to make explicit arcs that go back to all conceivable previous states, we can just backtrack. In other words we can just trace our footsteps backwards to where we were.

So, lets says we've gotten up to C. At this point, the process execution history looks like:

Figure 4.5. 

Now we wish to backtrack to B. If we retrace our steps, the process history will now look like:

Figure 4.6. 

Note that when we traverse arc 2 backward, it's marked in red. This is to mark that we've gone backwards along that arc. The node tokens on B and C, as well as the forward moving arc token on 2 are also marked, but in blue. This is to note that these actions have been backtracked. When node tokens are backtracked, they are given the opportunity to undo whatever work they did, send out notifications, or do whatever else is required.

We can now move forward again, this time going up to D, where the process execution history looks like:

Figure 4.7. 

If from here, we once again wish to return to B, the execution history will look like:

Figure 4.8. 

Note that since we are somewhat literally retracing our steps, to get from D to B we created backwards tokens at arc 3, node C and arc 2. The corresponding forward tokens have been marked as backtracked.

From here we now finish, and go to the end.

Figure 4.9. 

Let us now examine a process definition which has splits and joins.

Figure 4.10. 

These complicate manual backtracking a great deal.

If one has multiple, concurrent node tokens active after a split, backtracking one of them means that all must be backtracked. The one which has been backtracked must out and find all incomplete concurrent tokens and complete them. It must also set a marker indicating that backtracking should occur. All the tokens must then first be collected by an intermediary node, which will test to see if a backtrack is required. It will then send execution forward or back based on this test.

If all tokens which were generated from the split aren't collected and sent back as a single token then each token sent back to the split will generate a new set of tokens from the split. This could cause many duplicates to be generated.

Here is an example of a graph which would be roughly equivalent to the previous graph, but allows manual backtracking.

Figure 4.11. Manual Backtracking Split/Join

It has a great deal many more arcs, as well as a more complicated structure, to accommodate backtracking to the split.

To see how automated backtracking would work, let us first progress from A to B to where both C and D are open.

Figure 4.12. 

We can now attempt to backtrack to B.

Figure 4.13. 

The engine will follow all execution history which emanated from B and attempt to reverse it. So we can see that it flows backwards from C and D backwards to B.

If we now attempt to backtrack one more step to A, the execution history will look like:

Figure 4.14. 

Though this appears to be a simple linear backtrack, it's actually slightly complicated. The history starting from A includes the backtracking we just did. So the engine must traverse this to get to the current active tokens and backtrack them.

If instead, we were to backtrack directly from when C and D were open, back to A, the execution history would look as follows:

Figure 4.15. 

It looks almost the same, except that the second B is marked as a backwards execution, since this time, we went straight across it, instead of stopping there, and then continuing backwards.

We'll use the same process definition as we used for demonstrating splits.

Figure 4.16. 

Going back from a join is both more and less problematic than a split. A join can act as a split and send tokens back all of its inputs. However, it is very difficult to go back to just one of the inputs. If only one of the join inputs is reactivated, then the join will never fire, since it won't have all the required inputs available.

To start off with, assume execution has proceeded to E and the execution history looks like:

Figure 4.17. 

If we then want to go back to when C was open, the process will now look like:

Figure 4.18. 

As expected, C is now open. To do so, we backtracked across arc 4. However, D is not open but there is an open arc token on 5. We only wanted C open, not D. However, when C completes, we want E to execute again. However, E will only execute if there are arc tokens waiting on arcs 4 and 5. So, we backtrack arc 5, but the arc token we create on 5 is left active. Now when C completes, E will execute as it will have arc tokens on all inputs.

The arc token on 5, marked in yellow, is called a u-turn since this is what it does. It backtracks onto an arc, but then turns around and goes right back.

If we complete C the process will look like:

Figure 4.19. 

If instead of completing C we backtracked to D as well, the process would now look like:

Figure 4.20. 

The u-turn arc token is now marked as backtracked and a node token is now active on D .

Backtracking is very easy to use in Sarasvati.

To backtrack, invoke the backtrack(NodeToken token) method on your Engine instance.

  /**
   * Backtracks execution to the point where the given
   * node token was active. The token must be complete
   * and must not have been backtracked before. If it's
   * not complete, there isn't any point in backtracking
   * to it. If it has already been backtracked, the
   * execution has either returned to a point previous
   * to that token, or there is a newer, non-backtracked
   * token at that node now.
   *
   * @param token The destination token to backtrack to.
   */
  void backtrack (NodeToken token);

          

Your custom node classes may override the isBacktrackable and backtrack methods on Node .

Node#isBacktrackable will control whether a given invocation of Engine#backtrack will succeed. Sometimes, business logic may require that certain actions not be repeated.

Node#backtrack gives a place to to undo the the results of your custom node logic, and/or send notifications. This method will not be invoked until after isBacktrackable has returned true for all nodes needing to be backtracked.

  /**
   * Returns true if the specific execution of
   * this Node by the given NodeToken can be
   * backtracked.
   *
   * @param engine The engine doing the backtracking
   * @param token The token being backtracked
   * @return True if the node can be backtracked, false otherwise.
   */
  boolean isBacktrackable (Engine engine, NodeToken token);

  /**
   * Does whatever work is necessary to backtrack
   * this execution. For example, a task node may
   * send a notification that the task has been
   * backtracked.
   *
   * @param engine The engine doing the backtracking
   * @param token The specific token being backtracked.
   */
  void backtrack (Engine engine, NodeToken token);

          

Here is an example of how backtracking might be invoked. This example assumes we want to backtrack to an ancestor of the current token located at a node named Check Inventory.

  String name = "Check Inventory";
  NodeToken ancestor =
    FindNodeNamedVisitor.findFirstNamedParent( token, name );
  engine.backtrack( ancestor );