Advanced topics

Exception handling

jBpm adds state management to the java programming language. Our motto : "do only one thing, but do it good". Hence we don't want to duplicate constructs that are defined properly in the java language itself. The next part explains how we succeeded in jBpm to reuse the java try-catch instead of duplicating this construct in jPdl.

When a process archive is deployed, a definition is produced in jBpm. At that time, the definition is validated. This validation makes sure that the nodes are properly interconnected with transitions. This check will guarantee that no exceptions can occur when passing a token from node to node over the transitions.

Errors only can occur inside delegation classes. So what we did was put the responsability of error-handling with the delegation implementor. The delegation methods do not declare to throw Exception's (this is merely guiding the developer instead of a strict enforcement). E.g. when you send an email in an action-handler and it fails, it is in the java catch clause that the implementor decides what to do. E.g. put a message in a message queue, write a file or turn on a flash light. The last part of this story is delegation configuration. Its possible to configure the delegation classes on a per-usage basis in the processdefinition.xml. This configuration can also be used to configure exception handling. This configuration is specified in the delegation-implementation. So it depends on the quality of the delegation-implementation which error-handling-configurations are offered.



Authentication is the part of security that determines *who* is running the code. Authentication is outside the scope of the jBpm core services. It should be a part of the environment in which jBpm is deployed : e.g. the web application or the j2ee container. In all of jBpm's API, the person or system that is running the code is denoted with 'actorId' (java.lang.String). jBpm needs to know who is running the code for 2 reasons :

  • in all the methods declared in ExecutionService, jBpm wants to know who is running the code for logging purposes. The invocation logs will remember who did what. Of course, if logging is not important to you you are not forced to provide a value for the actorId parameter.
  • If the jBpm configuration parameter '' is set to true, the method ExecutionService.endOfState, will verify if the actor that executes the method is the same actor then the one that was assigned to the state.


Authorization is the part of security that specifies and enforces who is allowed to execute the code. In only one situation, jBpm can be configured to check if the actor is allowed to execute the method : when calling ExecutionService.endOfState.

For other authorization requirements, two mechanisms can be used :

  • ActionHandlers : ActionHandler's can throw org.jbpm.AuthorizationException's. When that happens, the transaction is rolled back and the client of the ExecutionService gets the AuthorizationException (which is an ExecutionException). An example usage of this mechanism could be to specify an ActionHandler at the start of a process instance. The action handler could check if the actor is allowed to start that process. If not, the ActionHandler can throw an org.jbpm.AuthorizationException.
  • The decorator pattern : For the most flexible form of authorization the decorator pattern (Gof) can be used. This means that at deployment, the jBpm execution service will be wrapped in another service that delegates the calls to jBpm but prepending the authorization code.

Running the jBpm tests

For running the unit tests or the coverage tests, also perform the following installation task : 'ant install.ant.libs' in ${jbpm.home}. That target will copy the libs lib/junit/junit-3.8.1.jar and lib/clover/clover.jar into your ${ant.home}/lib directory.

if you're working in eclipse, set the ANT_HOME variable-in-eclipse. it is used in the classpath of the jbpm2 eclipse project.

Do 'ant clean test view.test' in the ${jbpm.home} directory. On windows a browser will popup with the test results. On other systems, Just open ${jbpm.home}/target/test-reports/index.html in your browser.

Do 'ant clean test.coverage' in the ${jbpm.home} directory. When that is done, do 'ant view.coverage' to see only the coverage test results or do 'ant view' to see both the test results and the coverage test results. Note that for the coverage test results you need to execute to separate ant targets. Its not possible to combine the targets in one execution.