In this chapter we will show how to do software integration with JBoss jBPM. The standard mechanism to implement this is to wrap the functionality you want to integrate in a class that implements the ActionHandler interface. In order to demonstrate it let's specify Hello World action for our process.
Each Hello World process should integrate one or more Hello World actions, so this is what we will be doing. We can integrate custom code at different points in the process definition. To do this we have to specify an action handler, represented by an implementation of the ActionHandler interface, and attach this piece of code to a particular event. These events are amongst others, going over a transition, leaving or entering nodes, after and before signalling.
To make things a little bit more concrete, let's create a new class called HelloActionHandler. For that firstly we'll create a new package com.jbay.action in the src/java/main folder of our project. Then, we should call New Class Creation wizard as usual by right-clicking and navigating New > Class.
Notice that two first gaps have been filled automatically. Here, instead of Package option Enclose type option can be selected where a type in which to enclose a new class should be specified.
In our case, we leave everything as it is, just type HelloActionHandler as a name of new class and add org.jbpm.graph.ActionHendler interface as it's shown in the picture above.
Thus, our HelloActionHandler implements the ActionHandler interface including the execute method as shown in the next figure. Here, we add a variable named greeting to the collection of process variables and put a message in it : "Hello from ActionHandler".
Now, as we have HelloActionHandler class defined, let's explore how we can handle it.
The main purpose of this chapter is to provide you with the steps associating our Hello World action with a particular event and test the correctness of our actions as well.
As good Testcity citizens we will first create a Unit Test that proves the behaviour we want to achieve by adding the ActionHandler to the process. So we implement another test.
At first, let's return to the code we already saw in the previous chapter and add new test method testActionHendler to it.
We assert that no variable called greeting exist. Then we give the process a signal to move it to the auction state. We want to associate the execution of the action with the event of going over the transition from the start state to the auction state. So after the signal, the process should be in the auction state as in the previous scenario. But moreover, the greeting variable should exist and contain the string "Hello from ActionHandler". That's what we assert in the last lines of the test method.
Running the tests now results in a failure. The point is that we did not associate the action with any particular event in the process definition, so the process variable did not get set.
Let's do something about it and add an action to the first transition of our sample process. To do this you can use the Actions tab in the Properties Editor that is under the graphical canvas. Bring up the popup menu of the action element container and chose New Action as it's shown on the figure below. The other way to add an action to the transition is simply to use the dropdown menu that is available under the action icon in the right upper corner of the Properties View.
After adding the action a tabbed view with three pages will appear.
The first of these three pages allows you to give the Action a name. The last page contains some advanced attributes such as whether the Action is asynchronous. The Details page is the most important. It allows to choose and configure the actual action handler implementation.
Clicking on the Search... button brings us to a Choose Class dialog.
We choose our previously created 'HelloActionHandler' class and push the OK button. After the selection of the action handler for the action, we can run the test and observe it gives us a green light.
Tere we are. The above objective has been achieved.
The different integration points in a process definition are thoroughly documented in the JBoss jBPM User Guide. Instance nodes can contain many action elements. Each of these will appear in the Action element list of the Actions tab. But each Action also has a properties view of itself. You can navigate to this view by selecting the added Action in the outline view.