JBoss jBPM : Java Business Process Management on Tomcat with MySQL or HSQLDB

Fabricio Garcia Imbrizi, MURAH Technologies, www.murah.com.br

03/18/2005

1. CONSIDERATIONS

Many people have difficulties to install jBPM in the Tomcat with Mysql or HSQLDB database. I wrote this manual based in this difficulties and Users and Developers forums.

All information describes in this document can be found in the JBoss jBPM official web site, Users and Developers Forums and JBoss official web site.

I would like to thanks Tom Baeyens, Jan-Philipp Bolle, Stephane Carrez and all persons that contributed with questions. All credits goes to the authors.

2. TEST ENVIRONMENT

2.1. Systems

• Operation System Windows XP
  
• JBoss jBPM 2.0 : http://sourceforge.net/project/showfiles.php?group_id=70542&package_id=117680
  
• Tomcat 5.0.18 : http://jakarta.apache.org/site/downloads/downloads_tomcat-5.cgi
  
• MySQL 4.1.8 : http://dev.mysql.com/downloads/mysql/4.1.html
  

2.2. Libraries

• MySQL Connector/J : http://dev.mysql.com/downloads/connector/j/3.1.html
  
• Commons Digester : http://jakarta.apache.org/site/downloads/downloads_commons-digester.cgi

2.3. Environment Variables

These are the variable that must be set on operations system:

• ANT_HOME - Root Ant Directory
• JAVA_HOME - Root Java SDK Directory
• Include the follow on variable PATH:
• JAVA_HOME/bin

3. JBoss jBPM, Tomcat and MySQL

To use the JBoss jBPM example, follow the steps:

3.1. Root Directory

Unzip the jboss-jbpm-2.zip in the folder of your choice. I considered this folder as <JBPM_HOME>.

3.2. Alter <JBPM_HOME>/build.properties

Remove all code and insert:

• jbpm.home=<JBPM_HOME>
• ant.home=<ANT_HOME>
• jboss.home=
• jbpm.pde=

, than:

jboss.home and jbpm.pde can be empty.

3.3. Alter <JBPM_HOME>/core/schema.generation.properties

Remove all code and insert:

hibernate.dialect=net.sf.hibernate.dialect.MySQLDialect?
hibernate.connection.driver_class=com.mysql.jdbc.Driver
hibernate.query.substitutions=true=1, false=0
hibernate.connection.url=jdbc:mysql://localhost:3306/jbpm
hibernate.connection.username=<USER_NAME>
hibernate.connection.password=<PASSWORD>

, than:

<USER_NAME> is the user of database and <PASSWORD> is the password of that user on database.

3.4. Alter <JBPM_HOME>/web/src/jbpm.war/WEB-INF/classes/jbpm.properties

Remove all code and insert:

jbpm.log.stdout=off

hibernate.dialect=net.sf.hibernate.dialect.MySQLDialect?
hibernate.connection.driver_class=com.mysql.jdbc.Driver
hibernate.query.substitutions=true=1, false=0
hibernate.connection.url=jdbc:mysql://localhost:3306/jbpm
hibernate.connection.username=<USER_NAME>
hibernate.connection.password=<PASSWORD>

, than:

<USER_NAME> is the user of database and <PASSWORD> is the password of that user on database.

3.5. Alter <JBPM_HOME>/core/src/java/org/jbpm/model/definition/impl/DelegationImpl.hbm.xml

Replace
<property name="configuration" type="string" length="4000" />
to
<property name="configuration" type="text" length="65535" />

3.6. Alter <JBPM_HOME>/core/src/java/org/jbpm/model/definition/impl/FileImpl.hbm.xml

Replace
<property name="bytes" type="binary" />
to
<property name="bytes" type="binary" length="65535" />

3.7. Alter <JBPM_HOME>/core/src/java/org/jbpm/persistence/hibernate/HibernateSession.java

Replace

private static final String latestDefinitionQuery = "select d "
+ "from d in class org.jbpm.model.definition.impl.DefinitionImpl? "
+ "where d.name = ? "
+ " and d.version = ( "
+ " select max(d2.version) "
+ " from d2 in class org.jbpm.model.definition.impl.DefinitionImpl? "
+ " where d2.name = d.name )";

to private static final String latestDefinitionQuery = "select d "
+ "from d in class org.jbpm.model.definition.impl.DefinitionImpl? "
+ "where d.name = ? "
+ " order by d.version desc ";

3.8. Alter <JBPM_HOME>/core/src/java/org/jbpm/model/execution/impl/VariableInstanceImpl.hbm.xml

Replace
<property name="serializedValue" type="String" />
to
<property name="serializedValue" type="text" length="65535" />

3.9. Alter <JBPM_HOME>/core/src/java/org/jbpm/model/log/impl/ExecutionLog.hbm.xml

Replace

<subclass name="org.jbpm.model.log.impl.VariableUpdateLogImpl?" discriminator-value="VarUpdate?">
<property name="oldValueText" type="String" column="text1" />
<property name="newValueText" type="String" column="text2" />
<many-to-one name="variableInstance" class="org.jbpm.model.execution.impl.VariableInstanceImpl?" cascade="none" column="varinst2" />
</subclass>

to

<subclass name="org.jbpm.model.log.impl.VariableUpdateLogImpl?" discriminator-value="VarUpdate?">
<property name="oldValueText" type="text" column="text1" length="65535"/>
<property name="newValueText" type="text" column="text2" length="65535"/>
<many-to-one name="variableInstance" class="org.jbpm.model.execution.impl.VariableInstanceImpl?" cascade="none" column="varinst2" />
</subclass>

3.10. Alter <JBPM_HOME>/core/build.xml

In target <target name="generate.ddl" �ƒ¢�‚�€�‚¦>, replace:

<mkdir dir="../target/sql" />

to

<mkdir dir="target/sql" />

3.11. Terminal

Open a console in directory <JBPM_HOME>/core

3.12. Generate DDL SQL script

Execute the ant target �ƒ¢�‚�€�‚�˜generate.ddl�ƒ¢�‚�€�‚�™ with command 'ant generate.ddl' in <JBPM_HOME>/core

Now, you have generated a DDL script that creates the database in file <JBPM_HOME>/core/target/sql/create-jbpm-database.sql

3.13. MySQL Connector/J to deploy

Add MySQL Connector/J on <JBPM_HOME>/lib

3.14. Database Creation

Create a new database with the name jbpm on MySQL.

3.15. Deploying JBoss jBPM

Execute the ant target �ƒ¢�‚�€�‚�œdeploy�ƒ¢�‚�€�‚ with command ant deploy in <JBPM_HOME>/web

3.16. Deploying a process archive

Verify if your database is running. If not, start it. Execute the ant target �ƒ¢�‚�€�‚�œdeploy.process.archives�ƒ¢�‚�€�‚ with command ant deploy.process.archives in <JBPM_HOME>/web

3.17. Deploying JBoss jBPM on Tomcat

Copy <JBPM_HOME>/web/target/jbpm.war to <TOMCAT>/webapps The directory created on Tomcat of jBpm is refereed as <JBPM_HOME_TOMCAT>

3.18. MySQL Connector/J on Tomcat

Add MySQL Connector/J on <TOMCAT>/webapps/<JBPM_HOME_TOMCAT>/WEB-INF/lib

3.19. Commons Digester

Add the jar file commons-digester.jar on <TOMCAT>/webapps/<JBPM_HOME_TOMCAT>/WEB-INF/lib

JBoss jBPM, Tomcat and HSQLDB

To use the JBoss jBPM example, follow the steps:

4.1. Root Directory

Unzip the jboss-jbpm-2.zip in the folder of your choice. I considered this folder as <JBPM_HOME>.

4.2. Alter <JBPM_HOME>/build.properties

jbpm.home=<JBPM_HOME>
ant.home=<ANT_HOME>
jboss.home=
jbpm.pde=

, than:

jboss.home and jbpm.pde can stay empty.

4.3. Alter <JBPM_HOME>/web/src/jbpm.war/WEB-INF/classes/jbpm.properties

Replace the port of database:

hibernate.connection.url=jdbc:hsqldb:hsql://localhost:<PORTA>

, than:

<PORTA> is the number of port where HSQLDB is running. Normally is 9001.

4.4. Terminal

Open a console in directory <JBPM_HOME>/web

4.5. Deploying JBoss jBPM

Execute the ant target �ƒ¢�‚�€�‚�œdeploy�ƒ¢�‚�€�‚ with command ant deploy in <JBPM_HOME>/web

4.6. Deploying a process archive

Verify if your database is running. If not, start it.

Execute the ant target �ƒ¢�‚�€�‚�œdeploy.process.archives�ƒ¢�‚�€�‚ with command ant deploy.process.archives in <JBPM_HOME>/web

4.7. Deploying JBoss jBPM on Tomcat

Copy <JBPM_HOME>/web/target/jbpm.war to <TOMCAT>/webapps

The directory created on Tomcat of jBpm is refereed as <JBPM_HOME_TOMCAT>

4.8. HSQLDB Drives

Copy the jar files <JBPM_HOME>/lib/hsqldb/hsqldb.jar and <JBPM_HOME>/lib/hsqldb/pg73jdbc3.jar to <TOMCAT>/webapps/<JBPM_HOME_TOMCAT>/WEB-INF/lib

4.9. Commons Digester

Add the jar file commons-digester.jar on <TOMCAT>/webapps/<JBPM_HOME_TOMCAT>/WEB-INF/lib

References

Commons Digester - http://jakarta.apache.org/site/downloads/downloads_commons-digester.cgi
Developers forum - http://sourceforge.net/forum/forum.php?forum_id=240086
JBoss jBPM - http://www.jbpm.org or http://www.jboss.com/products/overview/jbpm
JBoss jBPM 2.0 - http://sourceforge.net/project/showfiles.php?group_id=70542&package_id=117680
MySQL 4.1.8 - http://dev.mysql.com/downloads/mysql/4.1.html
MySQL Connector/J - http://dev.mysql.com/downloads/connector/j/3.1.html
Tomcat 5.0.18 - http://jakarta.apache.org/site/downloads/downloads_tomcat-5.cgi
Users forum - http://sourceforge.net/forum/forum.php?forum_id=240085

Other languages: