A very basic JBPM tutorial - Hello World

According to the documentation
a minimal deployment of JBPM needs the following jars:

• jbpm-jpdl-3.3.0.GA.jar
• commons-logging.jar
• dom4j.jar
  

To start off we create the process definition. It consists of a start and end state and an additional intermediate state.

<process-definition xmlns="urn:jbpm.org:jpdl-3.2" name="simple">

 <start-state name="Start">
  <transition name="trHelloWorld" to="HelloWorld"></transition>
 </start-state>

 <state name="HelloWorld">
  <event type="node-enter">
   <action class="HelloWorldActionHandler" name="recharge"></action>
  </event>
  <transition name="trEnd" to="End"></transition>
 </state>

 <end-state name="End"></end-state>

</process-definition>

The state with name HelloWorld executes an action when the node-enter event is fired by the process executuion engine. The Action is implemented as Java code:

import org.jbpm.graph.def.ActionHandler;
import org.jbpm.graph.exe.ExecutionContext;

public class HelloWorldActionHandler implements ActionHandler {
 private static final long serialVersionUID = 1L;

 public void execute(ExecutionContext context) throws Exception {
  System.out.println("Hello World!");
 }
}

For the definition of the process nothing more is needed. It can be run outside of containers and does not need a database for non persistent processes. To start the process you have to load the definition and create a concrete ProcessInstance:

import org.jbpm.graph.def.ProcessDefinition;
import org.jbpm.graph.exe.ProcessInstance;

public class SimpleProcess {
 public static void main(String[] args) {
  ProcessDefinition processDefinition = ProcessDefinition.parseXmlResource("process-def.xml");
  ProcessInstance instance = new ProcessInstance(processDefinition);
  displayStatus(instance);
  instance.signal();
  displayStatus(instance);
  instance.signal();
  displayStatus(instance);
 } 

 private static void displayStatus(ProcessInstance instance) {
  String nodeName = instance.getRootToken().getNode().getName();
  System.out.println("You are now in node: " + nodeName);
 }
}

To trigger a transition the method signal() is called on the process instance. An action handler can leave the state by calling context.leaveNode().

Avoiding Java generics verbosity

public class GenericsTest { 
 static class Model<T> {
  public Model(T value) {
  }  
 }
 
 static class TextField<T> {
  public TextField(Model<T> model) {
  }  
 }
 
 static <T> TextField<T> createTextField(Model<T> model) {
  return new TextField<T>(model);
 }
 
 static <T> Model<T> createModel(T value) {
  return new Model<T>(value);
 }
 
 public static void main(String[] args) {
  TextField<String> tf1 = createTextField(createModel("tf1"));
  TextField<String> tf2 = createTextField(new Model<String>("tf1"));
  TextField<String> tf3 = new TextField<String>(new Model<String>("tf2"));
 }
}

Update: Inter-type declarations with implicit conversions

With some closure magic it's possible to shorten the code to build a class extension aka. to add some inter type members.

class ClassExtension[S, T](createExtendedObject: => T) {
    
  val extendedObjects = new HashMap[S, T]

  implicit def extendObject(o : S) : T = {
    if (!extendedObjects.contains(o)) {
      extendedObjects += o -> createExtendedObject;
    }
    extendedObjects(o);
  }
}

Instead of making the class abstract and using a factory method on the concrete class, we can use a closure for the construction of the extended / alternative object.

The class can be used like this:

def main(args : Array[String]) : Unit = {
    object PositionVertexExtension extends ClassExtension[Vertex, Position](new Position);
    import PositionVertexExtension._;
    val v = new Vertex("v1");   
    v.x = 2.3;
    println(v.x)
  }

This code shows another nice feature of scala. It is possible to have imports scoped to blocks. So in this case the extension is only visible in this local context. This is comparable to Groovy where categories are applied by the use controll structure.

Inter-type declarations with implicit conversions

AspectJ has a feature called inter-type declarations. With this feature you can add methods to an existing class without touching the class itself. (Similar to categories in Groovy) Actually it is even possible to add fields to classes with AspectJ. This is especially useful if you don't want to add the field to the class itself because it is used only by a small subset of all users.

I missed such a feature in Scala. But in fact it is possible to add methods and fields on a class with Scalas implicit conversions. Debasish Ghosh explains how to add methods on existing classes.

But how do we add new fields to a class? E.g. we have a class Vertex. This class is used in severall packages. Now we want to layout some vertices in an euclidean plane. In the context of the layouting algortihm every vertex has a position.

def main(args : Array[String]) : Unit = {
    val v = new Vertex();   
    v.x = 2.3;
    println(v.x)
  }

It would be nice to use a vertex like this without the need to access a map manually to get the additional fields. In this piece of code object creation is in our control, but we assume that the layouting algorithm does not have control over the vertex creation.

The extension Position would look like this:

class Position {
  var x = 0.0;
  var y = 0.0;  
}

The last missing piece is how to delegate the call to x.

object EuclideanExtension {  
  val extendedVertices = new HashMap[Vertex, Position]

  implicit def extendVertex(v : Vertex) : Position = {
    if (!extendedVertices.contains(v)) {
      extendedVertices += v -> new Position;
    }
    extendedVertices(v);
  }
}

The implicit conversion enables us to use all methods and fields of Position whenever we import the EuclideanExtension. (import graph.EuclideanExtension._;)

It is possible to extract most of the code to an abstract, generic class. So you can reuse this extension mechanism.

abstract class ClassExtension[S, T] {  
  val extendedObjects = new HashMap[S, T]

  implicit def extendObject(o : S) : T = {
    if (!extendedObjects.contains(o)) {
      extendedObjects += o -> createExtendedObject;
    }
    extendedObjects(o);
  }
  
  def createExtendedObject : T;
}

Using the abstract class reduces the code:

object EuclideanExtension extends ClassExtension[Vertex, Position] {  
  def createExtendedObject = new Position;
}