Deployment

Figure 2 : Architectural components related to jBpm

jBpm in a j2se environment

This is the simplest deployment. This applies to e.g. a simple java main program, a unit test, a swing application, ...

In its essence, jBpm can be used any plain java program. You need to include the jbpm.core.jar in the classpath and configure the database. In the java program you can then obtain the jbpm services with the org.jbpm.JbpmServiceLocator.

This gives jBpm the flexibility to be deployed in the following environments :

• in a webapp - that runs on a servlet container like e.g. Tomcat.
• in an ant-task - jBpm includes ant tasks for packaging process archives and deploying a process archive.
• in a JUnit test - The default configuration of jBpm is ideal for developing and testing process archives. It uses a transient, in-memory hypersonic database, which means you don't have to set-up a separate database and initialize it. jBpm detects that no jBpm tables are present and creates all the tables automatically. I have to give credit to the magnificent project 'Hibernate' for this last feature.
• in a custom app - When your application needs to incorporate workflow management, you can just use jBpm as a component of your application without the users of your system being aware.

The Getting Started instructions show you can automatically set up a project for developing and testing process archives.

jBpm in a web application

• install the jdbc driver on your webcontainer (or put it in the lib)
• put the jbpm.properties in the WEB-INF/classes
• • jbpm.core.jar
  • hibernate-2.1.1.jar
  • c3p0.jar
  • dom4j.jar
  • cglib2.jar
  • ehcache.jar
  • odmg.jar
  • commons-collections.jar
  • commons-logging.jar
  • commons-beanutils.jar
  • commons-lang.jar

jBpm on a j2ee server

For easy deployment inside of a J2EE container, we have written an EJB-wrapper around the jBpm API. This enables you to leverage one of the key features of J2EE servers for jBpm : Clustering. The jBpm download contains instructions (largely automated with ant) on how to install and configure JBoss and how to deploy jBpm on it. Also the instructions cover how to set up a JBoss cluster with jBpm on it.

Figure 3 : jBpm deployed in a J2EE server

Configuration

To configure jBpm properly choose one of following 4 configuration mechanisms :

• put a jbpm.properties in location where the classloader of this class can find it as a resource (with getResourceAsStream).
• call configure(Properties) before the the method getInstance() is called.
• call configure(ClassLoader,String) before the the method getInstance() is called.
• for creating multiple, differrent configured jbpm instances within the same JVM (same classloader), you can use the constructors of JbpmConfiguration and ServiceLocator yourself and don't do any static initializations or configurations.

Configuration parameters :

property	values	description	default value
hibernate.*	@see the hibernate docs	also the hiberate configs are done directly in the jbpm config file	jbpm's default hibernate configuration is an in-memory hsqldb database which is ideal for testing purposes
jbpm.create.tables	{ only-if-not-present | never }	If applicable, jbpm will create the the JBPM_ tables at startup if they are not present. The generated ddl starts with dropping the tables and contraints, then creates the tables, then adds the constraints.	only-if-not-present
jbpm.create.tables.log	{ true | false }	Specifies if the ddl that is generated for the creation of the tables is logged to standard out.	false
jbpm.create.tables.query	{ a plain SQL query }	is the plain sql query that checks wether the tables are present. this property is only used when property 'jbpm.create.tables' is set to value 'only-if-not-present' (=default!). if execution of this query results in an exception, jbpm will assume the jbpm-tables are not present.	SELECT ID FROM JBPM_DEFINITION WHERE ID = 1
jbpm.apply.transactions	{ yes | no }	Specifies how jbpm should handles transactions. 'yes' will apply a transaction on the jdbc connection for every method that performs a jbpm update. Methods that perform an update are all methods except those defined in *ReadService. 'no' means that jbpm will not apply any transactions. 'no' can be used inside a container or with user supplied jdbc connections.	yes
jbpm.file.mgr	{ database | filesystem | the class-name of a class that implements org. jbpm. persistence. FileMgr }	Specifies how jbpm should store files (e.g. the class-files in a process archive). This configuration is added because some database drivers (like e.g. oracle) aren't good at handling binary data.	database
jbpm.file.mgr.directory		is the name of the root directory where jbpm can store files. Use forward slashes. E.g. /usr/jbpm or C:/data/jbpm	-no default specified-
jbpm.validate.xml	{ true | false }	The process archive parser will not validate the processdefinition.xml file if this property is set to false.	true
jbpm.id.generator	{ default | the class-name of a class that implements org. jbpm. persistence. IdGenerator }	The IdGenerator will be used to create ids for the jbpm persistable objects.	org. jbpm. persistence. hibernate. SequenceBlockIdGenerator
jbpm.id.generator.node.id	{ an integer between 0 and 65535 }	The unique id of this node in the cluster.	0
jbpm.id.generator.bocksize	{ an integer }	The blocksize for the hilo id generation scheme.	100
jbpm.id.generator.configuration	{ same | the resource of the id generator hibernate properties }	Note that the id generator requires a session in a separate transaction. Therefor the session factory used by the id generator may not be obtained from a container managed DataSource. So if you are not using a DataSource within a which manages transactions, you can use the default value. 'same' means take the same properties for the id generator session factory as the ones in this configuration. Otherwise, the name of a .properties resource has to be specified in which contains the hibernate configuration for the id generator session factory.	same
jbpm.log.stdout	{on|off}	Configures commons logging to use standard output. When set to off, jbpm does not configure the commons logging.	on
jbpm.log.default	{ trace | debug | info | warn | error | fatal }	Specifies the default log level.	error
jbpm.log.package.* (whererepresents any package name)	{ trace | debug | info | warn | error | fatal }	overwrites the jbpm default log level with the given value	jbpm. log. package. org. jbpm= debug
jbpm.scheduler.wait.period	long	the number of milliseconds to wait between scheduler polls	5000
jbpm.execute.actions	{ true | false }	If set to true, jBpm will execute the specified action handlers. This could be set to false e.g. for testing purposes to avoid execution of business processes.	true

The jBpm database

Contents

jBpm stores all its information in the database :

• the process definitions
• the runtime information of process executions
• the process logs

Schema generation

By default, the first time that the database is accessed, jBpm will check if the jbpm database tables exist. If not the jbpm database tables will be created automatically. This behaviour can be switched off by setting the jbpm configuration property 'jbpm.create.tables' to 'never'.

The schema for a database can be created in a file with the following procedure :

• update the properties in the file ${jbpm.home}/core/schema.generation.properties to reflect the database of your choice. the default database is Hypersonic DB. See hibernate configuration properties and hibernate dialects on how to specify your database.
• in directory ${jbpm.home}/core generate the schema with 'ant generate.ddl'. The generated file should be located in ${jbpm.home}/target/sql/create-jbpm-database.sql

Changing DB

• update the hibernate properties in the file core/schema.generation.properties (including the hibernate dialect).
• put the library of the database driver somewhere in the directory lib (or in a subdirectory)
• open a console in directory core
• execute the ant target 'generate.ddl' with command 'ant generate.ddl'
• now, you have generated a DDL script that creates the database in file core/target/sql/create-jbpm-database.sql
• when running jBpm, make sure you provide the right hibernate configurations. see JbpmConfiguration on how to provide these configurations to jBpm.

• some databases like firebird and oracle require the following property in jbpm.properties: add hibernate.query.substitutions=true 1, false 0
• verify the column-lengths of text types for your database. by default a string field is 255 chars long. You can adjust it in one of 2 ways : by adding the parameter length like this in the hibernate mapping files: <property name="configuration" type="string" length="10000"/>, or by manually updating the ddl script generated by 'ant generate.ddl'

• MySQL

Appserver compatibility

Scheduler

jBpm includes a scheduler. ActionHandler implementations (and other delegation implementation classes) can schedule Jobs through the SchedulerService. The SchedulerService is accessible in the ExecutionContext with method getSchedulerService.

The jBpm scheduler exists of 4 parts :

1. the scheduler service : allows to schedule and cancel Jobs. In fact the scheduler service only inserts (schedule) and removes (cancel) Job-records in the jbpm database. At certain process execution events actions can be executed. Inside the actions, you can schedule and cancel Jobs.
2. the scheduler server : is the component that is able to check for Jobs that are due and execute them. The scheduler server should regularly (e.g. every 5 seconds) be called. To provide that call, jBpm includes a scheduler servlet and a scheduler client.
3. the scheduler servlet : is a servlet that upon request, notifies the scheduler server to check the jobs.
4. the scheduler client : is a very simple plain java program that sends a request to the scheduler servlet every few seconds.

For an example on how to use the scheduler in a process definition, see the scheduler test.

• core/src/java/org/jbpm/delegation/action/ScheduleJobActionHandler.java : is a configurable action that schedules a job.
• core/src/java/org/jbpm/delegation/action/CancelJobActionHandler.java : is a configurable action that cancels one or more jobs
• core/src/test/resources/process/schedulingprocess.xml : to see how the upper two are used

jBpm on a JBoss cluster

These instructions explain how to setup a JBoss cluster with the jbpm enterprise beans. Requirements : you'll need 2 or more computers with a decent JVM and ant installed. Alternatively you can run multiple JBoss instances on one computer but that setup is not described in this

Setup :

 +----------------+   
 | Node 1         |
 | +------------+ |
 | | Hypersonic |.|...................................... . . .
 | | Database   | |            :                    :
 | | for jBpm   | |  +---------:------+   +---------:------+
 | +------------+ |  | Node 2  :      |   | Node 3  :      |
 |       :        |  |         :      |   |         :      |
 | +------------+ |  | +------------+ |   | +------------+ |
 | | jBpm ejb   | |  | | jBpm ejb   | |   | | jBpm ejb   | |  
 | | module     | |  | | module     | |   | | module     | |
 | +------------+ |  | +------------+ |   | +------------+ |
 |       !        |  |         !      |   |         !      |
 +-------!--------+  +---------!------+   +---------!------+
         !                     !                    !       
         !                     !                    !       
       !!!!!!! remote application clients !!!!!!!!!!!!!!

On every node, do the following :

1. install jboss 3.2.3 (=unzip jboss-3.2.3 & set the JBOSS_HOME env var accordingly)
2. update the build.properties in directory ${jbpm.home} to your environment (properties jbpm.home and jboss.home)
3. run 'ant build' in directory ${jbpm.home}
4. run 'ant configure.jboss.3.2.3+' in directory ${jbpm.home}
5. in the file ${jboss.home}/server/jbpm/deploy/jbpm-ds.xml change 'localhost' in the line

     <connection-url>jdbc:hsqldb:hsql://localhost:1701</connection-url>
   

   to the ip address of node 1 (that's the node with the database) NOTE : do not leave this ip address to 'localhost' on Node 1 because it won't work. trust me, I know :-)

On node 1 perform the following tasks :

6. start jboss with with '{jboss.home}/bin/run.bat -c jbpm'
7. in directory ${jbpm.home}/ejb 'ant deploy' will create ${jbpm.home}/ejb/target/j2ee/jbpm.ejb.jar and copy it to ${jboss.home}/server/jbpm/farm (this will deploy the ejb module to all nodes in the cluster later on)
8. upload the process archives into the jbpm database with 'ant deploy.process.archives' in ${jbpm.home}/ejb

9. delete file ${jboss.home}/server/jbpm/deploy/jbpm-db-service.xml
10. remove the line '<depends>jboss:service=JbpmDatabase</depends>' from the file ${jboss.home}/server/jbpm/deploy/jbpm-ds.xml

Start all your nodes with '{jboss.home}/bin/run.bat -c jbpm'

11. in ${jbpm.home}/ejb run 'ant test'