Data source configuration in jBPM 3.2

Starting from version 3.2.4, jBPM is distributed as a Java-based installer for easy product setup. The installer lets you fill in the following parameters.

1. Installation directory
2. Components to be installed (see screenshot)

• Standalone
• JBoss integration
• Optional Eclipse / JBoss AS downloads

3. Target database
4. JBoss AS directory, if you already have one


The target database selection currently includes HSQLDB, MySQL and Sybase, with PostgreSQL, Oracle and MS SQL underway. Selecting a database is as simple as clicking your choice in the appropriate screen. Configuring jBPM with the appropriate parameters for your database is slightly trickier. This post will guide you though it.

The installer will put the jBPM enterprise components in the deploy/jbpm directory of your server profile. You will find a jbpm-database-ds.xml file there, where database corresponds to your selection in the installer, of course. Let us take MySQL as example. The contents of the installed file are listed below.

<xa-datasource>
<jndi-name>JbpmDS</jndi-name>

<xa-datasource-class>
com.mysql.jdbc.jdbc2.optional.MysqlXADataSource
</xa-datasource-class>
<xa-datasource-property name="ServerName">
localhost
</xa-datasource-property>
<xa-datasource-property name="PortNumber">
3306
</xa-datasource-property>
<xa-datasource-property name="DatabaseName">
jbpmtest
</xa-datasource-property>
<user-name>jbpmtest</user-name>
<password></password>
...
</xa-datasource>

You will probably want to edit the server name, database name, user name and password before launching JBoss AS, otherwise you will get database connectivity exceptions. The remaining settings have worked for us in our test environment and are our general recommendations. In case you want to further tune the data source, the available settings are documented in the JBoss AS configuration guide.

Apart from the data source, the installer places the JDBC driver of the target database in the deploy/jbpm/jbpm-service.sar directory, provided that the driver is freely distributable. Otherwise, you will need to obtain and install the driver yourself, according to the instructions provided in Appendix B of the aforementioned guide. Free open source database users have it easiest, which is only fair :-)

A new LAMP: Linux, Apache, (Java) Middleware and PostgreSQL

If you work in the software industry, particularly if you consume and/or provide free and open source software, you will undoubtedly have come across the LAMP acronym (otherwise, you just did). LAMP is an emblem of free software. Indeed, many web sites out there rely on this versatile software stack.

Nonetheless, for us Java devs, the P is excluding, be it PHP, Python or Perl, whereas the M generates mixed feelings. Of course, the Java platform was freed only recently, which accounts for its absence from the free software stage. Anyhow, Java is free nowadays. Wikipedia states the following about LAMP.

the combination has become popular because of its low acquisition cost and the ubiquity of its components, which come bundled with most current Linux distributions.

OpenJDK is available from the package repositories of Fedora 9 and Ubuntu 8.04. I have confirmed it can be installed as easily as Apache, MySQL or PostgreSQL in those Linux distributions and undoubtely in others as well.

What about the database? Like I said, mixed feelings there. MySQL claims to be the world's most popular open source database, whereas PostgreSQL is allegedly the world's most advanced open source database. 'Nuf said. No, really.

In recent experiences with jBPM testing, the easy setup and low maintenance requirements of MySQL have been a pleasant surprise. No doubt it is more popular. Conversely, the PostgreSQL community's ability to roll out new features (foreign keys, views, subselects, transactions and, more recently, two-phase commit) well in advance of its open source competence, makes it a distinctly compelling product.

Free software is about choice. Time for a new LAMP?

XA data sources and jBPM

One handy and often overlooked feature of jBPM 3.3 is the ability to customize the services provided by the jBPM context, and even add your own. The user guide documents the feature in Chapter 6: Configuration. Services are an abstraction layer from the operational environment and allow jBPM to run standalone or inside an EJB container.

When running inside an EJB container, the message service is bound to JMS and the scheduler service to EJB timers. Some supporting enterprise beans need to be deployed for the services to work. In the Hibernate configuration the JDBC connection properties are replaced by a server-provided data source.

When your process definition makes use of the message or the scheduler service, the JMS connection factory or the EJB timer service are enlisted as resource manager in the container-managed transaction, in addition to the jBPM data source. When more than one resource manager is enlisted in the same transaction, all resource managers are conceptually required to support XA (two-phase commit) unless the last resource commit optimization is in effect.

In JBoss AS, the JMS connection factory is XA capable and poses no problems. However, the EJB timer service relies on a data source to persist timer data. The data source is by default bound to DefaultDS, a local (as opposed to XA) data source. If the jBPM data source was also local, the transaction manager would reject the second local resource and roll back the transaction. There are at least three approaches to a solution to this problem.

1. Enable multiple resource manager enlistement
2. Associate both the EJB timer service and the jBPM persistence to a single data source
3. Make jBPM use an XA data source
   

The first two solutions require end users to modify their JBoss AS configuration. However, the aim of jBPM is to provide a seamless out-of-the-box experience. End users should not be required to alter their configuration just to get the product to work. Providing an XA data source is therefore the only viable option.

Whereas most databases provide working XA data sources, most are not as proven as the standalone JDBC driver is. All of them work in the absence of errors, but some of them do not recover properly in exceptional scenarios. The currently supported databases/drivers along with their known XA support are listed below.

HSQLDB
XA data source: no
EJB container integration not available.

MySQL
XA data source: yes
Backend does not support XA - coming in 6.0 with the Falcon storage engine.

PostgreSQL
XA data source: yes
Backend and driver support.

Sybase
XA data source: yes
Backend and driver support. Distributed transactions must be enabled in the backend.

Conclusion. EJB container integration is at the mercy of the target database. Choose carefully!

New year, new blog

After a long time of putting off blogging for next year (where next is always current plus one), I have finally came around to sit down and do it.

Rather than throwing subjective comments about technology, the software industry and everything, I want this blog to offer objective information about BPM, enterprise Java and related technologies. Of course, JBoss jBPM will be at the center.

Having the goal concisely phrased, I wish anyone reading this entry a succesful 2009.

* Xihumolpilli *