The new (rock-solid) service API

When making the transition from jBPM3 to jBPM4, the most remarkable change is probably the new service API.

In jBPM3, it was not always clear  where to look for a certain operation. Some operations were found on the JbpmContext, or on the GraphSession, or on the TaskManagement interface, or yet some other class. So there definitely was an API, but the growth of jBPM both in Slocs and adoption in the past years have transformed it into a maze for many people who wanted to learn jBPM.

In jBPM4, the jBPM team has drastically moved away from these shackles of legacy and has chosen a simpler approach with a less steep learning curve: the service API. Every jBPM story (webapp, standalone, shared BPM server, etc.) starts with a ProcessEngine. As the name implies, the ProcessEngine is the key for doing the actual BPM stuff. But like the engine of your car, you need components to control and guide your engine (gears, brakes, etc) or the engine will do nothing. So basically what you’ll do is create a process engine from a given jBPM config (jbpm.cfg.xml) and acquire from it the services.

• RepositoryService: allows managing static process data: deploying process definitions, enable/disabling them, query them, etc.

• ExecutionService: exposes operations concerning the runtime executions (ie process instances and sub-executions): starting process instances, variable management, retrieving and deleting executions, etc.

• TaskService: this service will probably be used the most, since it gives access to the most crucial part of BPM, Human Interactions. Everything you ever wanted to do with human tasks is done through this service: creating tasks (ad-hoc is supported!), querying, assigning them, task completion, etc. You’ll notice that, in comparison with jBPM3, task management has been given a complete redesign which makes tasks easier to access, query and filter.

• HistoryService: in jBPM4, a clean separation has been made between the runtime and historical data. The previous services all had more or less something to do with active executions of a process, whereas the historyService is only concerned with things of the past. Through this service, historical data (such as completed process instances or executed activities) can be easily queried. This service also gives access to some statistical calculations which are done by the engine. There is no real prior component for this in jBPM3, so be sure to check it out!

• ManagementService: the last service is the one that’ll be used only by ‘management apps’ (eg the jBPM console). This services allows for example to query jobs and execute them (without the needing a job executor), but typically you’ll not use it in end-user software.

Note: the Query API which I discussed in part 2, is also accessible through these services.

The services are designed such that every practical jBPM use case is covered by it. All the API services are tested by us at our QA lab against several databases (HsqlDB, MySQL, PostgreSQL and Oracle for the moment, but we’ll expand this very soon), different Java versions (jdk 5 & 6) and JBoss AS versions. So when you use this new API, you can be sure it is stable as a mountain goat (is this a valid expression?).

But jBPM-power users shouln’t be afraid that this ‘easier’ jBPM API leads to less power. The service API is in fact an abstraction on top of the CommandService facade approach, which was already in the more recent versions of jBPM3. In fact, every service operations translates into a Command, which is executed in the well-known try-catch-finally block of jBPM. Take a look at the source of DefaultCommandService if you want to know more. You can easily retrieve the CommandService to get access to the full power of the jBPM engine:

processEngine.get(CommandService.class)

Power users will know what to do with it 😉

Stay tuned for the next post, where I’ll show you how easy it is to create a Hello World process with jBPM4 and the service API.