[jBPM] - jBPM4 Building from Source
by Administrator Administrator
Administrator Administrator [http://community.jboss.org/people/admin] modified the document:
"jBPM4 Building from Source"
To view the document, visit: http://community.jboss.org/docs/DOC-12867
--------------------------------------------------------------
This page explains how to get the jbpm 4 process engine sources, the various things you can build with it and how to set up your eclipse.
h1. Requirements
* JDK 5 or higher
* Maven 2.0.9 or higher
* Subversion
h1. Other build instructions
* http://community.jboss.org/docs/DOC-13343 Google Summer of Code 2010
* http://community.jboss.org/docs/DOC-13342 Jbpm4BuildConsoleFromSources
h1. Getting the sources
Perform anonymous checkout of the sources like this:
svn co http://anonsvn.jboss.org/repos/jbpm/jbpm4/trunk jbpm4
jBPM developers should check out the sources using the following url
svn co https://svn.jboss.org/repos/jbpm/jbpm4/trunk jbpm4
h1. Building the default modules
To build the default modules run:
[jbpm4]$ mvn clean install
Before you commit, first do an update and then this command should run OK with your updates.
A successfull build/test run ends like this:
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] ------------------------------------------------------------------------
[INFO] jBPM 4 ................................................ SUCCESS [7.812s]
[INFO] jBPM 4 - API .......................................... SUCCESS [11.844s]
[INFO] jBPM 4 - Log .......................................... SUCCESS [1.281s]
[INFO] jBPM 4 - Test Base .................................... SUCCESS [1.110s]
[INFO] jBPM 4 - PVM .......................................... SUCCESS [24.953s]
[INFO] jBPM 4 - Task ......................................... SUCCESS [6.937s]
[INFO] jBPM 4 - jPDL ......................................... SUCCESS [3.438s]
[INFO] jBPM 4 - Examples ..................................... SUCCESS [10.047s]
[INFO] jBPM 4 - Enterprise ................................... SUCCESS [6.359s]
[INFO] jBPM 4 - Test DB ...................................... SUCCESS [10.922s]
[INFO] jBPM 4 - Test POJO .................................... SUCCESS [3.109s]
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1 minute 28 seconds
[INFO] Finished at: Fri Jan 16 13:45:35 CET 2009
[INFO] Final Memory: 22M/45M
[INFO] ------------------------------------------------------------------------
h1. Building the distribution
If you're running outside the Red Hat VPN (only employees have it) you'll have to fetch the oracle driver yourself as we're not allowed to redistribute it in our public repositories.
Download the oracle ojdbc14.jar driver here: http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/htdocs/jdbc... http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/htdocs/jdbc...
Then install the oracle driver into your local repository like this
mvn install:install-file -DgroupId=com.oracle -DartifactId=ojdbc14 -Dversion=10.1.0.5 -Dpackaging=jar -Dfile=path/to/file
To build the distribution,
[jbpm4]$ mvn -Pdistro clean install
In case you are working outside the Red Hat VPN and downloaded a different version of the Oracle driver, build the distribution as follows.
[jbpm4]$ mvn -Pdistro -Doracle.version=10.1.0.5 clean install
After that finishes successfully, you'll find the distribution package in modules/distro/target/jbpm-{version}.zip
On windows you can add the schemadocs profile with *-Pschemadocs*. In other operating systems, the schema docs generation fails.
The distribution package is also published in the repository. (note that it's called jbpm-distro-{version}.zip in the repo)
h1. Build scripts
h4. Developer configuration
In the following build files, configurable properties can be customized in file *${user.home}/.jbpm4/build.properties*
As a developer, at least you need to specify *jbpm.parent.dir* Typically you also want to specify the *jboss.distro.dir* and the *eclipse.distro.dir*
jbpm.parent.dir=${user.home}/jbpm
jboss.distro.dir=${user.home}/downloads/jboss
eclipse.distro.dir=${user.home}/downloads/eclipse
JDBC properties can also be specified in files *${user.home}/.jbpm4/jdbc/${database}.properties*
Or properties can also be provided on the command line like:
ant -Djbpm.parent.dir=/usr/jbpmbuild reinstall.jbpm
h4. Default values
Here are the configurable properties and their default values as used throughout the scripts.
<property name="database" value="hsqldb" />
<property name="jbpm.version" value="4.0.0-SNAPSHOT" />
<property name="jbpm.home" value="${jbpm.parent.dir}/jbpm-${jbpm.version}" />
<property name="jbpm.filename" value="jbpm-distro-${jbpm.version}.zip" />
<property name="jbpm.distro.dir" value="../modules/distro/target" />
<property name="jbpm.distro.path" value="${jbpm.distro.dir}/jbpm-${jbpm.version}.zip" />
<property name="jboss.version" value="5.0.0.GA" />
<property name="jboss.distro.dir" value="${jbpm.home}/downloads" />
<property name="jboss.parent.dir" value="${jbpm.home}" />
<property name="jboss.version" value="5.0.0.GA" />
<property name="jboss.filename" value="jboss-${jboss.version}.zip" />
<property name="jboss.distro.dir" value="${jbpm.home}/downloads" />
<property name="jboss.distro.filename" value="jboss-${jboss.version}.zip" />
<property name="jboss.distro.path" value="${jboss.distro.dir}/${jboss.filename}" />
<property name="jboss.distro.url" value="http://downloads.sourceforge.net/jboss/${jboss.distro.filename}" />
<property name="jboss.home" value="${jboss.parent.dir}/jboss-${jboss.version}" />
<property name="jboss.server.configuration" value="default" />
<property name="jboss.server.config.dir" value="${jboss.home}/server/${jboss.server.configuration}" />
<property name="eclipse.filename" value="eclipse-jee-ganymede-SR2-win32.zip" />
<property name="eclipse.distro.url" value="http://mirror.cc.vt.edu/pub/eclipse/technology/epp/downloads/release/gany..." />
<property name="eclipse.distro.dir" value="${jbpm.home}/downloads" />
<property name="eclipse.parent.dir" value="${jbpm.home}" />
<property name="eclipse.distro.path" value="${eclipse.distro.dir}/${eclipse.filename}" />
h4. qa/build.xml
This is the build script to install jBPM and the helper scripts to drive the continuous integration. This script is only available in the sources. Other scripts will also be available in the distribution, but this script is not.
[jbpm4/qa]$ ant -p
Buildfile: build.xml
[echo] database.......... hsqldb
[echo] jbpm.version...... 4.4-SNAPSHOT
[echo] jbpm.home......... /home/aguizar/jbpm/jbpm-4.4-SNAPSHOT
[echo] jbpm.distro.path.. ../modules/distro/target/jbpm-4.4-SNAPSHOT.zip
Main targets:
internal.enterprise.test.setup.base reinstalls jbpm, reinstalls jboss, installs jbpm into jboss, starts jboss and then creates the jbpm schema
reinstall.jbpm deletes the jbpm installation and then reinstalls jbpm
testsuite.enterprise.setup reinstalls jbpm, reinstalls jboss, installs jbpm into jboss, starts jboss and then creates the jbpm schema
testsuite.enterprise.setup.for.debug reinstalls jbpm, reinstalls jboss, installs jbpm into jboss, starts jboss and then creates the jbpm schema
testsuite.enterprise.teardown drops the jbpm schema and stops jboss
testsuite.jboss.setup reinstalls jbpm, reinstalls jboss, installs jbpm into jboss, starts jboss and then creates the jbpm schema
testsuite.jboss.setup.for.debug reinstalls jbpm, reinstalls jboss, installs jbpm into jboss, starts jboss and then creates the jbpm schema
testsuite.jboss.teardown drops the jbpm schema and stops jboss
h4. distro/src/main/files/install/build.xml
This script contains the targets related to installing jboss, installing jbpm into jboss and starting and stopping jboss. It also contains the targets related to creating and dropping the db schema. This script will be part of the distro and also be usable by our users.
[modules/distro/src/main/files/install]$ ant -p
Buildfile: build.xml
Main targets:
clean.cfg.dir Deletes the ${cfg.dest.dir}
create.cfg Creates a configuration in ${cfg.dest.dir}
create.jbpm.schema creates the jbpm tables in the database
create.user.webapp Generates a configuration in dir /install/generated/user-webapp
delete.jboss Deletes jboss installation
delete.tomcat Deletes tomcat installation
demo.setup.jboss installs jboss and jbpm, starts jboss, creates the db schema, deploys examples, loads example identities, installs and starts eclipse
demo.setup.tomcat installs tomcat, installs jbpm into tomcat, starts tomcat, creates the jBPM DB schema, deploys examples, loads example identities, installs and starts eclipse
demo.teardown.jboss drops the db schema and stops jboss
demo.teardown.tomcat stops tomcat and then the hsqldb server if needed
drop.jbpm.schema drops the jbpm tables from the database
get.eclipse downloads eclipse to ${eclipse.distro.dir}
get.jboss Downloads jboss into ${jboss.distro.dir}
get.tomcat Downloads tomcat into ${tomcat.distro.dir} if it is not available
hsqldb.databasemanager start the hsqldb database manager
install.eclipse unzips eclipse, downloads eclipse if it is not available in ${eclipse.distro.dir}
install.examples.into.tomcat deploys all the example processes
install.jboss Downloads jboss to ${jboss.distro.dir} if its not available and then unzips jboss
install.jbpm.into.jboss Installs jBPM into JBoss
install.jbpm.into.tomcat Installs jBPM into tomcat
install.signavio.into.jboss installs signavio into jboss
install.signavio.into.tomcat installs signavio into tomcat
install.tomcat Downloads tomcat to ${tomcat.distro.dir} if its not available and then unzips tomcat
load.example.identities loads the example users and groups into the database
reinstall.jboss Deletes the previous jboss installation and re-installs jboss
reinstall.jboss.and.jbpm Deletes the previous jboss installation and re-installs jboss and installs jbpm in it
reinstall.tomcat Deletes the previous tomcat installation and re-installs tomcat
reinstall.tomcat.and.jbpm Deletes the previous tomcat installation and re-installs tomcat and installs jbpm in it
start.eclipse starts eclipse
start.jboss starts jboss and waits till jboss is booted, then lets jboss run in the background
start.tomcat Starts Tomcat and waits till it is booted, then lets Tomcat run in the background
stop.jboss signals jboss to stop, but doesn't wait till its finished
stop.tomcat Signals Tomcat to stop, but doesn't wait till its finished
upgrade.jbpm.schema Upgrades the jBPM tables in the database to the current version
h4. distro/src/main/files/examples/build.xml
This script contains the target for deploying the examples to the database. This script will be part of the distro and also be usable by our users.
[modules/distro/src/main/files/examples]$ ant -p
Buildfile: build.xml
Main targets:
Other targets:
create.and.deploy.examples
examples.jar
jbpm.libs.path
log.properties
h3. Testing against a particular database
[jbpm4]$ mvn -Ddatabase=mysql test
h3. Running the test suites on another JDK
To run the test suite on another JDK, make sure it is the default java in the path.
On windows, you can do this easily by a command like this:
*set PATH=C:\Software\jdk1.6.0_07\bin;%PATH%*
To see what the current configured JDK is, you can check the version like this
*java -version
*
h3. Running the enterprise test suite
[jbpm4]$ mvn -Djboss.bind.address=localhost test
h3. Useful maven command line options
*-DskipTests* will skip execution of the test suite.
*-o* will run the build offline. Maven will not check the snapshot repositories for updates. Saves time.
*-U* will force updates of libraries
h3. Setting up your eclipse
You'll need
* Eclipse 3.4, http://www.eclipse.org/downloads/download.php?file=/technology/epp/downlo... Eclipse IDE for Java EE Developers (163 MB)
* SVN plugin http://subclipse.tigris.org/update_1.4.x http://subclipse.tigris.org/update_1.4.x
* MVN plugin http://m2eclipse.sonatype.org/update/ http://m2eclipse.sonatype.org/update/
After you checked out the jbpm4/trunk, you do:
* *File* --> *Import...*
* *General* --> *Existing projects into Workspace*
* Select jbpm4/trunk/modules as the root directory
* All the modules with an eclipse project should now appear. By default, all the checkboxes are checked
* Click '*Finish*'
Eclipse will point to the libraries of your local mvn repository. To get the libraries there, activate '*Project*' --> '*Update All Maven Dependencies*'
Go to *Window* --> *Preferences* --> *Java* --> *Code Style* --> *Formatter* and import jbpm4/trunk/eclipse/jbpm.profile.xml
--------------------------------------------------------------
Comment by going to Community
[http://community.jboss.org/docs/DOC-12867]
Create a new document in jBPM at Community
[http://community.jboss.org/choose-container!input.jspa?contentType=102&co...]
13 years, 8 months
[jBPM] - JbpmProjects
by Administrator Administrator
Administrator Administrator [http://community.jboss.org/people/admin] modified the document:
"JbpmProjects"
To view the document, visit: http://community.jboss.org/docs/DOC-13299
--------------------------------------------------------------
If you're interested in one of these projects, contact kris -d0t- verlaenen -a*t- redhat -d0t- com
h3.
h2. Core Engine (Kris)
h3. Bring jBPM to Google App Engine (GAE)
Refactor persistence to work with JPA2 and investigate what else is necessary to get jBPM running on GAE.
h3.
h3. Groovy support
In jBPM 4 we currently have a way to configure and use multiple scripting languages. This challenge would include working out some cool examples of how groovy is used in a process. To add groovy support, we need to figure out library dependencies, find if the dependencies are available in public maven repositories. Then append the groovy configuration in our script-manager.
h3. Process instance migration
When a new version of a process is deployed, currently the existing executions are not migrated. This is because the process updates can be significant and it is not possible in the general case to migrate all the instances. But assuming a couple of reasonable limitations such a process instance migration is possible. As long as the structure of the activities remain the same, executions can be migrated to a new process definition. Optionally a mapping of old-to-new activity names could be given.
h3.
h3. Static process variables
Variables could be associated to process definitions. All executions would see the same static process definition variable. This would correspond to static variables in Java.
h2. Task Management & jBPM console (Heiko)
h3.
h3. XForms task management extensions
Using XForms for rendering task interfaces
h3.
h3. Social networking widgets for the GWT console
Integrate common social networking features into the new jBPM console.
Things like contact lists, messages, etc whatever seems useful with regard to task management.
h3.
h3. *http://www.jboss.org/jopr JOPR integration with the console*
Process engine monitoring and management through embedded http://www.jboss.org/jopr jopr.
--------------------------------------------------------------
Comment by going to Community
[http://community.jboss.org/docs/DOC-13299]
Create a new document in jBPM at Community
[http://community.jboss.org/choose-container!input.jspa?contentType=102&co...]
13 years, 8 months
[jBPM] - jBPM3 Hudson Setup
by Administrator Administrator
Administrator Administrator [http://community.jboss.org/people/admin] modified the document:
"jBPM3 Hudson Setup"
To view the document, visit: http://community.jboss.org/docs/DOC-12865
--------------------------------------------------------------
h2. Hudson QA Environment
The http://hudson.jboss.org/hudson/view/jBPM/ Hudson QA environment is an integral part of the jBPM3 code base. With every release we test the matrix of target http://community.jboss.org/docs/DOC-12859 containers, http://community.jboss.org/docs/DOC-12860 databases and supported JDKs.
h3. Set Hudson Properties
You need to set a few properties, especially these.
|| *Property*
|| *Value* ||
| java.home.* | Path to JDK installations |
| hudson.username | User name to log in to Hudson |
| hudson.password | Password to log in to Hudson |
| hudson.maven.path | Path to Maven 2 installation |
| hudson.root | Directory where the Hudson server will be installed |
| hudson.jboss*.zip | Path to JBoss AS distribution files |
cd hudson
cp ant.properties.example ant.properties
vi ant.properties
# JBoss remote repository
jboss.repository=http://repository.jboss.org
# The JBoss settings
jboss.server.instance=default
jboss.bind.address=127.0.0.1
# JDK settings
java.home.jdk14=/etc/alternatives/java_sdk_1.4.2
java.home.jdk15=/etc/alternatives/java_sdk_1.5.0
java.home.jdk16=/etc/alternatives/java_sdk_1.6.0
# Hudson QA Environment
hudson.username=changeme
hudson.password=changeme
hudson.maven.path=/usr/share/maven2
hudson.maven.profile=$JBPMDIR/hudson/profiles.local.qa.xml
hudson.root=/home/hudson/workspace
hudson.host=localhost
hudson.admin.port=8150
hudson.http.port=8180
#hudson.jboss405.zip=file:/home/hudson/download/java/jboss/jboss-4.0.5.GA.zip
#hudson.jboss423.zip=file:/home/hudson/download/java/jboss/jboss-4.2.3.GA.zip
#hudson.jboss501.zip=file:/home/hudson/download/java/jboss/jboss-5.0.1.GA.zip
#hudson.jboss510.zip=file:/home/hudson/download/java/jboss/jboss-5.1.0.GA-jdk6.zip
hudson.mail.recipients=
hudson.smtp.host=localhost
# Hudson (1.295)
apache-tomcat=5.5.20
sun-hudson=2402/131374
h3. Set Up Hudson
Run Ant target hudson-setup. Note that the hudson.root directory defined above must exist.
[aguizar@siankaan hudson]$ ant hudson-setup
Buildfile: build.xml
init:
[echo] version.id=3.2.10-SNAPSHOT
[echo] repository.id=3.2.10-SNAPSHOT
init-hudson:
[echo]
[echo] hudson.root = /home/aguizar/jbpm/hudson
[echo] hudson.home = /home/aguizar/jbpm/hudson/jbpm-hudson-3.2.10-SNAPSHOT/hudson-home
[echo]
init-thirdparty:
get-tomcat:
get-hudson:
get-jboss405:
get-jboss423:
get-jboss501:
get-jboss510:
thirdparty:
hudson-tomcat-setup:
hudson-setup:
[copy] Copying 2 files to /home/aguizar/jbpm/hudson/jbpm-hudson-3.2.10-SNAPSHOT/apache-tomcat
[copy] Copying 11 files to /home/aguizar/jbpm/hudson/jbpm-hudson-3.2.10-SNAPSHOT/hudson-home
[echo]
[echo] *************************************
[echo] * Hudson setup successfully *
[echo] * ant hudson-start *
[echo] *************************************
[echo]
BUILD SUCCESSFUL
Total time: 0 seconds
h3. Start Hudson
[aguizar@siankaan hudson]$ ant hudson-start
Buildfile: build.xml
init:
[echo] version.id=3.2.10-SNAPSHOT
[echo] repository.id=3.2.10-SNAPSHOT
init-hudson:
[echo]
[echo] hudson.root = /home/aguizar/jbpm/hudson
[echo] hudson.home = /home/aguizar/jbpm/hudson/jbpm-hudson-3.2.10-SNAPSHOT/hudson-home
[echo]
hudson-start:
[echo]
[echo] *************************************
[echo] * Hudson started successfully *
[echo] * http://localhost:8180/hudson *
[echo] *************************************
[echo]
BUILD SUCCESSFUL
Total time: 0 seconds
h3. Stop Hudson
[aguizar@siankaan hudson]$ ant hudson-stop
Buildfile: build.xml
init:
[echo] version.id=3.2.10-SNAPSHOT
[echo] repository.id=3.2.10-SNAPSHOT
init-hudson:
[echo]
[echo] hudson.root = /home/aguizar/jbpm/hudson
[echo] hudson.home = /home/aguizar/jbpm/hudson/jbpm-hudson-3.2.10-SNAPSHOT/hudson-home
[echo]
hudson-stop:
[exec] Using CATALINA_BASE: /home/aguizar/jbpm/hudson/jbpm-hudson-3.2.10-SNAPSHOT/apache-tomcat
[exec] Using CATALINA_HOME: /home/aguizar/jbpm/hudson/jbpm-hudson-3.2.10-SNAPSHOT/apache-tomcat
[exec] Using CATALINA_TMPDIR: /home/aguizar/jbpm/hudson/jbpm-hudson-3.2.10-SNAPSHOT/apache-tomcat/temp
[exec] Using JRE_HOME: /etc/alternatives/java_sdk
[echo]
[echo] *************************************
[echo] * Hudson stopped successfully *
[echo] * ant hudson-start *
[echo] *************************************
[echo]
BUILD SUCCESSFUL
Total time: 0 seconds
--------------------------------------------------------------
Comment by going to Community
[http://community.jboss.org/docs/DOC-12865]
Create a new document in jBPM at Community
[http://community.jboss.org/choose-container!input.jspa?contentType=102&co...]
13 years, 8 months
[jBPM] - jBPM3 Design Documentation
by Administrator Administrator
Administrator Administrator [http://community.jboss.org/people/admin] modified the document:
"jBPM3 Design Documentation"
To view the document, visit: http://community.jboss.org/docs/DOC-15934
--------------------------------------------------------------
The purpose of this article is to gather design documents and diagrams together.
***
#Design_Diagrams Design Diagrams
****
#Product_Components Product Components
****
#Process_definition_and_instance Process definition and instance
****
#Node_hierarchy Node hierarchy
****
#Asynchronous_node Asynchronous node
****
#Timer Timer
***
#Project_Modules Project Modules
***
#Tooling_Interfaces Tooling Interfaces
****
#Graphical_process_designer Graphical process designer
****
#Web_console Web console
***
#Database Database
****
#Compatibility Compatibility
****
#Schema Schema
*****
#Definition_data Definition data
*****
#Execution_data Execution data
***
#API_Usage API Usage
****
#Starting_a_process_instance Starting a process instance
****
#Signaling_a_token Signaling a token
****
#Retrieving_a_task_list Retrieving a task list
***
#Test_Coverage Test Coverage
****
#Continuous_integration Continuous integration
****
#Areas_of_attention Areas of attention
h3. Design Diagrams
h4. Product Components
http://community.jboss.org/servlet/JiveServlet/showImage/102-15934-3-9952... http://community.jboss.org/servlet/JiveServlet/downloadImage/102-15934-3-...
h4. Process definition and instance
http://community.jboss.org/servlet/JiveServlet/showImage/102-15934-3-9971... http://community.jboss.org/servlet/JiveServlet/downloadImage/102-15934-3-...
h4. Node hierarchy
http://community.jboss.org/servlet/JiveServlet/showImage/102-15934-3-9973... http://community.jboss.org/servlet/JiveServlet/downloadImage/102-15934-3-...
h4. Asynchronous node
http://community.jboss.org/servlet/JiveServlet/showImage/102-15934-3-9974... http://community.jboss.org/servlet/JiveServlet/downloadImage/102-15934-3-...
h4. Timer
http://community.jboss.org/servlet/JiveServlet/showImage/102-15934-3-9972... http://community.jboss.org/servlet/JiveServlet/downloadImage/102-15934-3-...
h3. Project Modules
|| Module || Description ||
| core | Process engine codebase and the project test suite. |
| db | Database schema scripts for every version (since 3.2.2), plus the scripts to generate the new jBPM DB schema scripts for every new version when it is being released. |
| distribution | Product installer. The idea was that this installer would be the interface between the project and the product. Instead, the SOA platform build does an automated installation and then a script cherry picks files from the installation. |
| enterprise | Message and scheduler services based on JMS and EJB timers respectively. Those services are not used in the product. Instead, the JCA inflow services are used. |
| examples | Sample processes that ship with the product. |
| identity | Identity component containing the classes for users, groups and memberships. |
| simulation | Process analysis and optimization tool donated by Camunda GmbH (http://www.camunda.com/). Not part of the product. |
| userguide | User guide in the docbook format. Note that these docs are decoupled from the product docs. Changes must be propagated to the docs team separately. |
h3.
h3. Tooling Interfaces
h4. Graphical process designer
GPD depends on the file src/main/etc/version.info.xml in the distribution module. This file contains the locations of the jar files that are needed to create a new project. The tooling expects the following folder layout:
|| Directory || Contents ||
| lib | binaries and dependencies |
| src | source jars |
| config | configuration resources |
| examples | sample processes |
For deployment, a servlet that accepts process archives with file upload has to be configured. This features was only added for usage during development. So after we found out that this imposed a security problem, then we proposed to remove the servlet. But the latest product decision was to secure the servlet.
h4. Web console
The console just uses the jBPM 3 API and libraries directly and it should be configured to connect to a data source.
h3. Database
h4. Compatibility
jBPM uses Hibernate as ORM framework. This means that, theoretically, jBPM is compatible with any Hibernate-compatible database (ie any database for which there exists a Hibernate dialect). However, extensive compatibility testing is done on the databases which are listed as certified databases for the SOA-P (and more).
jBPM is continuously evaluated with the relational database systems listed in http://community.jboss.org/docs/DOC-13763 jBPM3 Platform Support.
h4. Schema
The following sections will discuss the jBPM schema. Refer to http://community.jboss.org/docs/DOC-11086 Jbpm31DataModel for diagrams of the definition and execution data models.
h5. Definition data
* JBPM_PROCESSDEFINITION: general process definition data (name, description, etc).
* JBPM_NODE: data about one node in the process definition. All node types will store common data in this table.
* JBPM_TRANSITION: every record in this table represents one transition between two nodes of the process definition.
* JBPM_EVENT: static data about events that are triggered during process execution.
* JBPM_ACTION: user code related to the process definition.
* JBPM_DELEGATION: information about user code that uses delegation classes.
* JBPM_EXCEPTIONHANDLER: information about exception handlers attached to certain process definition scopes. Relates to JBPM_ACTION for the actual delegation to custom Java exception handlers.
* JBPM_VARIABLEACCESS: stores the read/write and mapping information for variables when variables are passed to for example subprocesses.
* JBPM_TASK: contains static information about tasks: task name, properties (blocking, duedate, etc.), assignee expression.
* JBPM_MODULEDEFINITION: generic table that stores for example (a part of) a task definition, a process definition start task, etc.
* JBPM_SWIMLANE: static description of a task swimlane. Contains an expression or a reference to a delegation class for the actual assignment at runtime.
* JBPM_TASKCONTROLLER: Stores the reference to a user code delegation class that implements task controller functionality.
* JBPM_ID_USER/GROUP/MEMBERSHIP: user/group data for the default identity component
h5. Execution data
* JBPM_PROCESSINSTANCE: general data about an execution of a process definition.
* JBPM_TOKEN: stores the actual pointers that indicate the current state of a process instance. The jBPM model is based on a hierarchical tree of tokens. The JBPM_PROCESSINSTANCE table refers to a so-called 'root-token' that is created when the process instance is created. The tree of tokens can be constructed using this token-rootToken-processInstance relationship.
* JBPM_VARIABLEINSTANCE: runtime data in the form of process variables are stored in this table. Multiple columns such as 'datevalue_', 'longvalue_', 'stringvalue_', etc are used to store the actual variables depending on the variable types.
* JBPM_BYTEARRAY/JBPM_BYTEBLOCK: tables used to store binary data (eg binary variables).
* JBPM_SWIMLANEINSTANCE: contains runtime evaluations of assignment expressions/delegations.
* JBPM_TASKINSTANCE: runtime tasks (ie with a runtime actor and token reference).
* JBPM_POOLEDACTOR/JBPM_TASKACTORPOOL: when task assignment expressions resolve to a group of actors (a so-called 'pool of actors'), the runtime evaluations are stored in these two tables.
* JBPM_JOB: stores runtime job information that is used to execute jobs, and in particular asynchronous continuations of process logic, by the job executor.
* JBPM_TIMER: timers are a specific type of jobs that are executable by the jBPM job executor. However, timers need additional information such as 'transitionName' (transition taken when te timer fires), the task to which the timer is attached to, etc. All this extra runtime information is stored in this table.
* JBPM_LOG: generic table that contains all historical/audit data generated by the jBPM engine. This table has quite some columns to store the different types of historical events. At runtime, this table can get seriously big, and maintenance scripts should be developed to keep performance decent.
h3. API Usage
h4. Starting a process instance
http://community.jboss.org/servlet/JiveServlet/showImage/102-15934-3-9968... http://community.jboss.org/servlet/JiveServlet/downloadImage/102-15934-3-...
h4. Signaling a token
http://community.jboss.org/servlet/JiveServlet/showImage/102-15934-3-9969... http://community.jboss.org/servlet/JiveServlet/downloadImage/102-15934-3-...
h4. Retrieving a task list
http://community.jboss.org/servlet/JiveServlet/showImage/102-15934-3-9970... http://community.jboss.org/servlet/JiveServlet/downloadImage/102-15934-3-...
h3. Test Coverage
h4. Continuous integration
The project leverages the http://http://hudson.jboss.org/hudson/view/jBPM/ Hudson installation maintained by JBoss QA. The codebase also provides scripts and configuration files to set up a local Hudson server useful for troubleshooting purposes. Visit http://community.jboss.org/docs/DOC-12865 jBPM3 Hudson Setup for a step-by-step guide.
h4. Areas of attention
>From support cases, our experience is that only one set of tests is lacking: Controlled concurrency testing. Though those are not easy to set up. This means that we need to simulate in a controlled fashion optimistic locking exceptions. One test thread should control multiple threads (at minimal 2), each performing some competing operation on jBPM. For example, a signal and a timer that are performed on the same token. Those then should lead to a hibernate optimistic locking exception and then a rollback of one of those transactions. Depending on the DB implementation of locking, deadlocks could arise as well. Analyzing which of those situations can occur and building controlled tests for those is the next effort that should be done for jBPM to be able to better support the product. Also the join behavior should get attention in this context. Then these tests should be executed on all databases so that those different behaviors can be analyzed and documented.
A significant amount of research is necessary to explore this path. One direction we've been thinking about is using the java debugger capabilities to achieve this. In that case, the unit test could pretend to be a debugging tool that puts breakpoints and steers the execution in a controlled fashion to optimistic locking exceptions.
--------------------------------------------------------------
Comment by going to Community
[http://community.jboss.org/docs/DOC-15934]
Create a new document in jBPM at Community
[http://community.jboss.org/choose-container!input.jspa?contentType=102&co...]
13 years, 8 months
[jBPM] - jBPM3 on Tomcat
by Administrator Administrator
Administrator Administrator [http://community.jboss.org/people/admin] modified the document:
"jBPM3 on Tomcat"
To view the document, visit: http://community.jboss.org/docs/DOC-16106
--------------------------------------------------------------
This article is a guide to deploying jBPM 3.2 to Tomcat 5.5 and 6.0.
**
#Tomcat_60 Tomcat 6.0
***
#Downloads Downloads
***
#Dependencies Dependencies
***
#Configuration Configuration
***
#Launch Launch
**
#Tomcat_55 Tomcat 5.5
***
#Downloads_362741 Downloads
***
#Dependencies_445215 Dependencies
**
#Other_Databases Other Databases
***
#Dependencies_211271 Dependencies
***
#Configuration_738970 Configuration
***
#Launch_849888 Launch
h2. Tomcat 6.0
The basic procedure gets the jBPM console to work against an HSQL in-process database. It is advisable to attempt this procedure against a clean Tomcat 6.0 installation before going for Tomcat 5.5 or other databases.
h3. Downloads
0. Download the http://sourceforge.net/projects/jbpm/files/jBPM%203/jbpm-jpdl-3.2.7/jbpm-... jBPM installer installer. Launch the installer with the following command. Select the +jBPM3 Standalone+ component only.
$ java -jar jbpm-installer-3.2.x.jar
1. Download the latest snapshot of https://repository.jboss.org/nexus/content/repositories/snapshots/org/jbp... jsf-console-tomcat.war, the web console based on JSF. Extract the contents to the tomcat-<version>/webapps/jbpm-console/ directory.
2. Download the latest snapshot of https://repository.jboss.org/nexus/content/repositories/snapshots/org/jbp... jbpm-tomcat.jar, the Tomcat integration bits, to tomcat-6.0.x/lib/
3. Download https://repository.jboss.org/nexus/content/groups/public/javax/transactio... jta.jar to jbpm-console/WEB-INF/lib/
h3. Dependencies
4. Copy all files from jbpm-3.2.x/lib/ +except+ hsqldb.jar, jbpm-console.war, junit.jar and log4j.jar to jbpm-console/WEB-INF/lib/
5. Copy hsqldb.jar from jbpm-3.2.x/lib/ to tomcat-6.0.x/lib/
h3. Configuration
6. Copy jbpm.cfg.xml and hibernate.cfg.xml from jbpm-3.2.x/config/ to jbpm-console/WEB-INF/classes.
7. Examine the data source preconfigured in jbpm-console/META-INF/context.xml. Open hibernate.cfg.xml and switch from JDBC connections to the data source as follows.
a) Uncomment the DataSource properties section.
<!-- DataSource properties (begin) -->
<property name="hibernate.connection.datasource">java:comp/env/jdbc/JbpmDataSource</property>
<!-- DataSource properties (end) -->
b) Comment out the JDBC connection properties section.
<!-- JDBC connection properties (begin) ===
<property name="hibernate.connection.driver_class">org.hsqldb.jdbcDriver</property>
<property name="hibernate.connection.url">jdbc:hsqldb:mem:jbpm</property>
<property name="hibernate.connection.username">sa</property>
<property name="hibernate.connection.password"></property>
==== JDBC connection properties (end) -->
c) Comment out the automatic schema creation property.
<!-- Automatic schema creation (begin) ===
<property name="hibernate.hbm2ddl.auto">create</property>
==== Automatic schema creation (end) -->
8. The configuration is correct and complete at this point. However, no user will be able to authenticate because the database is empty. To provide seed data, download the HSQLDB data files http://anonsvn.jboss.org/repos/jbpm/jbpm3/branches/jbpm-3.2-soa/distribut... jbpmDB.script and http://anonsvn.jboss.org/repos/jbpm/jbpm3/branches/jbpm-3.2-soa/distribut... jbpmDB.properties to tomcat-<version>/work/Catalina/localhost/jbpm-console/. Create the directory if necessary.
h3. Launch
All set! Go ahead and start Tomcat. Point your browser to the http://localhost:8080/jbpm-console jBPM web console. The login page should appear.
http://community.jboss.org/servlet/JiveServlet/showImage/10625/jbpm-conso... http://community.jboss.org/servlet/JiveServlet/downloadImage/10625/jbpm-c...
After logging in as one of the example users, the sample processes will be displayed. To deploy a new process definition, log in as a user in the +admin+ group and click the Deploy link in the Actions panel on the left side.
http://community.jboss.org/servlet/JiveServlet/showImage/10627/jbpm-conso... http://community.jboss.org/servlet/JiveServlet/downloadImage/10627/jbpm-c...
h2. Tomcat 5.5
Since the procedure is very similar to Tomcat 6.0, only the differences will be noted.
h3. Downloads
2. Download the latest snapshot of https://repository.jboss.org/nexus/content/repositories/snapshots/org/jbp... jbpm-tomcat.jar, the Tomcat integration bits, to tomcat-5.5.x/server/lib/
3. Download https://repository.jboss.org/nexus/content/groups/public/javax/transactio... jta.jar, https://repository.jboss.org/nexus/content/groups/public/javax/el/el-api/... el-api.jar and https://repository.jboss.org/nexus/content/groups/public/com/sun/el/el-ri... el-ri.jar to jbpm-console/WEB-INF/lib/
h3. Dependencies
4. Copy hsqldb.jar from jbpm-3.2.x/lib/ to tomcat-5.5.x/common/lib/
h2. Other Databases
Follow the base procedure for the selected Tomcat version, with the following changes depending on the target database.
h3. Dependencies
4. Copy the JDBC driver file to tomcat-6.0.x/lib or tomcat-5.5.x/common/lib depending on the target Tomcat version.
h3. Configuration
6. Copy jbpm.cfg.xml and hibernate.cfg.<database>.xml from jbpm-3.2.x/config/ to jbpm-console/WEB-INF/classes/
7. Edit the data source preconfigured in jbpm-console/META-INF/context.xml. Set the appropriate driverClassName, url, username and password attributes for the target database.
8. Create the database schema and load seed data as follows.
a) Execute the jbpm-3.2.x/database/jbpm.jpdl.<database>.sql script to create the required tables, indexes and constraints.
b) Run the following SQL statements to fill in the example users.
INSERT INTO JBPM_ID_USER VALUES(1,'U','user','user(a)sample.domain','user');
INSERT INTO JBPM_ID_USER VALUES(2,'U','manager','manager(a)sample.domain','manager');
INSERT INTO JBPM_ID_USER VALUES(3,'U','admin','admin(a)sample.domain','admin');
INSERT INTO JBPM_ID_USER VALUES(4,'U','shipper','shipper(a)sample.domain','shipper');
INSERT INTO JBPM_ID_GROUP VALUES(1,'G','sales','organisation',NULL);
INSERT INTO JBPM_ID_GROUP VALUES(2,'G','admin','security-role',NULL);
INSERT INTO JBPM_ID_GROUP VALUES(3,'G','hr','organisation',NULL);
INSERT INTO JBPM_ID_GROUP VALUES(4,'G','user','security-role',NULL);
INSERT INTO JBPM_ID_GROUP VALUES(5,'G','manager','security-role',NULL);
INSERT INTO JBPM_ID_MEMBERSHIP VALUES(1,'M',NULL,NULL,2,4);
INSERT INTO JBPM_ID_MEMBERSHIP VALUES(2,'M',NULL,NULL,3,4);
INSERT INTO JBPM_ID_MEMBERSHIP VALUES(3,'M',NULL,NULL,1,4);
INSERT INTO JBPM_ID_MEMBERSHIP VALUES(4,'M',NULL,NULL,4,4);
INSERT INTO JBPM_ID_MEMBERSHIP VALUES(5,'M',NULL,NULL,4,3);
INSERT INTO JBPM_ID_MEMBERSHIP VALUES(6,'M',NULL,NULL,2,3);
INSERT INTO JBPM_ID_MEMBERSHIP VALUES(7,'M',NULL,NULL,3,3);
INSERT INTO JBPM_ID_MEMBERSHIP VALUES(8,'M',NULL,NULL,3,2);
INSERT INTO JBPM_ID_MEMBERSHIP VALUES(9,'M',NULL,NULL,2,2);
INSERT INTO JBPM_ID_MEMBERSHIP VALUES(10,'M',NULL,NULL,2,5);
INSERT INTO JBPM_ID_MEMBERSHIP VALUES(11,'M',NULL,'boss',2,1);
INSERT INTO JBPM_ID_MEMBERSHIP VALUES(12,'M',NULL,NULL,1,1);
h3. Launch
Logins as example users will work, although no sample processes will be immediately available. You will have to deploy processes through the web console as indicated above.
--------------------------------------------------------------
Comment by going to Community
[http://community.jboss.org/docs/DOC-16106]
Create a new document in jBPM at Community
[http://community.jboss.org/choose-container!input.jspa?contentType=102&co...]
13 years, 8 months
[jBPM] - jBPM3 Join Lock Mode
by Administrator Administrator
Administrator Administrator [http://community.jboss.org/people/admin] modified the document:
"jBPM3 Join Lock Mode"
To view the document, visit: http://community.jboss.org/docs/DOC-13753
--------------------------------------------------------------
h3. Specify LockMode to prevent StaleObjectStateException
h4. Note:
This article applies to jBPM version 3.2.5.SP5 (and higher) and to certain databases, eg. PostgreSQL
h4. Problem:
Executing a process with multiple async nodes within a fork/join results in StaleObjectStateExceptions upon entering the join node.
h4. Sample process:
<fork name="fork1">
<transition to="node1" name="to node1"></transition>
<transition to="node2" name="to node2"></transition>
<transition to="node3" name="to node3"></transition>
</fork>
<node name="node1" async="true">
<action class="com.sample.ActionHandler"/>
<transition to="join"></transition>
</node>
<node name="node2" async="true">
<action class="com.sample.ActionHandler"/>
<transition to="join"></transition>
</node>
<node name="node3" async="true">
<action class="com.sample.ActionHandler"/>
<transition to="join"></transition>
</node>
<join name="join">
<transition to="node4"></transition>
</join>
Running this process with PostgreSQL set up for jBPM, a StaleObjectStateException might occur when the child tokens arrive in the join node.
h4. Solution:
Specify the lock attribute on the join node and set it to FORCE:
<join name="join" lock="FORCE"/>
For this to work, a few config as well as database schema changes have to be made:
1. An alternate mapping file for the Node element has to be used, which contains the column definition for the lock attribute. The alternate mapping is distributed in jbpm-jpdl.jar. To use the alternative, make a copy of the default Hibernate configuration file +hibernate.cfg.xml+ and replace:<mapping resource="org/jbpm/graph/node/Join.hbm.xml"/>
with<mapping resource="org/jbpm/graph/node/Join.lock.hbm.xml"/>
2. An additional column PARENTLOCKMODE_ has to be added to the JBPM_NODE table:ALTER TABLE jbpm_node ADD COLUMN parentlockmode_ character varying(255);
3. Finally, the process definition has to be changed and redeployed by changing the join node as outlined above.
h4. Background information:
In earlier jBPM versions, the FORCE lock mode has been the default in the Join node. This worked on most databases, but led to StaleObjectStateExceptions on others such as Oracle. Therefore, the idea of the additional PARENTLOCKMODE_ was to be able to configure the locking behavior so that it best fits the different environments. This schema change has been introduced with https://jira.jboss.org/jira/browse/JBPM-1755 JBPM-1755 (version 3.2.4). Later on it was discovered that the schema change would be problematic for some of our customers, therefore the change has been reverted in https://jira.jboss.org/jira/browse/JBPM-2119 JBPM-2119 (version 3.2.5.SP5). Also, the default behavior changed from LockMode.FORCE to LockMode.UPGRADE.
For PostgreSQL specific instructions see also http://community.jboss.org/docs/DOC-13270 InstallPostgreSQLonFedora.
--------------------------------------------------------------
Comment by going to Community
[http://community.jboss.org/docs/DOC-13753]
Create a new document in jBPM at Community
[http://community.jboss.org/choose-container!input.jspa?contentType=102&co...]
13 years, 8 months
[jBPM] - jBPM3 Building From Source
by Administrator Administrator
Administrator Administrator [http://community.jboss.org/people/admin] modified the document:
"jBPM3 Building From Source"
To view the document, visit: http://community.jboss.org/docs/DOC-12863
--------------------------------------------------------------
h3. Checkout from SVN
svn co http://anonsvn.jboss.org/repos/jbpm/jbpm3/branches/jbpm-3.2-soa
For more information, see http://community.jboss.org/docs/DOC-12864 jBPM3 Subversion
h3. Build with Maven
The command below builds the modules and runs the test suites. The build assumes maven-2.0.9 or higher.
[aguizar@siankaan jbpm-3.2-soa]$ mvn clean install
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Build Order:
[INFO]
[INFO] jBPM3
[INFO] jBPM3 - Core
[INFO] jBPM3 - Identity
[INFO] jBPM3 - Enterprise
[INFO] jBPM3 - Examples
[INFO] jBPM3 - Simulation
[INFO] jBPM3 - Tomcat
[INFO] jBPM3 - JEE5 Enterprise
...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] jBPM3 ............................................. SUCCESS [1.710s]
[INFO] jBPM3 - Core ...................................... SUCCESS [2:56.228s]
[INFO] jBPM3 - Identity .................................. SUCCESS [11.828s]
[INFO] jBPM3 - Enterprise ................................ SUCCESS [5.944s]
[INFO] jBPM3 - Examples .................................. SUCCESS [16.183s]
[INFO] jBPM3 - Simulation ................................ SUCCESS [8.342s]
[INFO] jBPM3 - Tomcat .................................... SUCCESS [0.680s]
[INFO] jBPM3 - JEE5 Enterprise ........................... SUCCESS [1.307s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
For setting up a local Hudson QA environment, have a look at http://community.jboss.org/docs/DOC-12865 jBPM3 Hudson Setup
--------------------------------------------------------------
Comment by going to Community
[http://community.jboss.org/docs/DOC-12863]
Create a new document in jBPM at Community
[http://community.jboss.org/choose-container!input.jspa?contentType=102&co...]
13 years, 8 months
[jBPM] - jBPM3 Text Columns
by Administrator Administrator
Administrator Administrator [http://community.jboss.org/people/admin] modified the document:
"jBPM3 Text Columns"
To view the document, visit: http://community.jboss.org/docs/DOC-16177
--------------------------------------------------------------
Because JDBC driver support for the CLOB and BLOB data types has long been patchy and inconsistent, jBPM3 mapped long string fields to VARCHAR(4000) columns. While this strategy yields portable mappings, databases with small page sizes (< 4K) do not gracefully accommodate such wide columns, refusing to create the tables, or reporting errors at runtime. Conversely, CLOB (TEXT in some databases) columns are usually stored in separate pages, offering a superior alternative provided driver support is good. The present document describes how to switch from VARCHAR(4000) to CLOB (TEXT) columns.
1. Locate the default type definitions for the target database. The type definitions are placed inside jbpm-jpdl.jar, in resources named org/jbpm/db/hibernate.types.<database>.xml. Databases without a specific type definition resource fall back to hibernate.types.xml.
2. The type definitions are longstring and ltdstring. The first is used to map string fields that cannot afford loss of information. The second is used to map string fields that, due to their informational nature, can be safely trimmed. The hibernate.types.xml resource defines longstring as StringType and ltdstring as LimitedStringType with a limit of 4000.
<hibernate-mapping>
<typedef name="longstring" class="org.hibernate.type.StringType"/>
<typedef name="ltdstring" class="org.jbpm.db.hibernate.LimitedStringType">
<param name="limit">4000</param>
</typedef>
</hibernate-mapping>
3. To redefine the types, place a custom resource containing the new type definitions in the class path. Open the jBPM hibernate.cfg.xml file and locate the mapping element shown below.
<!-- type mappings -->
<mapping resource="org/jbpm/db/hibernate.types.hbm.xml" />
Set the value of the resource attribute to the location of the custom type definition resource.
4. Examine the shipped type definitions for MySQL, DB2 and Sybase to better understand how they affect the database schema.
DB2 does not create tables whose row length exceeds the database page size, regardless of actual rows never coming close to crossing the limit at runtime. Because tables mapped to class hierarchies fairly lengthy rows (in excess of 16K in one case) a jBPM database in DB2 would require a 32K page. Such a large page hinders efficient space utilization. For DB2, longstring is thus defined as TextType, resulting in columns of type CLOB as opposed to VARCHAR.
<hibernate-mapping>
<typedef name="longstring" class="org.hibernate.type.TextType"/>
<typedef name="ltdstring" class="org.jbpm.db.hibernate.LimitedTextType">
<param name="limit">4000</param>
</typedef>
</hibernate-mapping>
Sybase, unlike DB2, will create a table whose row length exceeds the page size; it will simply emit a warning.
Warning: Row size (2389 bytes) could exceed row size limit, which is 1962 bytes.
For compatibility reasons, longstring is defined as StringType for Sybase. However, users requested ltdstring was defined as TEXT columns instead of VARCHAR(4000) to prevent truncation. Sybase does not enforce length constraints in TEXT columns apart from the maximum size of 2^31^ -1 (2,147,483,647) bytes.
<hibernate-mapping>
<typedef name="longstring" class="org.hibernate.type.StringType" />
<typedef name="ltdstring" class="org.jbpm.db.hibernate.SybaseTextType" />
</hibernate-mapping>
MySQLDialect, the Hibernate dialect for MySQL prior to version 5.x, maps string columns longer than 255 characters to type TEXT because VARCHAR columns used to be limited to 255 characters. Therefore, the jBPM database schema has always empoyed TEXT columns in MySQL. When MySQL5Dialect was introduced, it pushed the VARCHAR column limit to 65535, reflecting the extended VARCHAR capacity featured in MySQL 5. Switching to the new dialect brought a schema incompatibility, as columns of type TEXT suddenly changed to VARCHAR(4000). To correct the incompatibility, longstring is defined as TextType. MySQL does not observe length specifications in TEXT columns other than the maximum size of 65,535 bytes.
<hibernate-mapping>
<typedef name="longstring" class="org.hibernate.type.TextType"/>
<typedef name="ltdstring" class="org.jbpm.db.hibernate.LimitedTextType">
<!-- mysql text columns can store up to 2^16 - 1 bytes -->
<param name="limit">65535</param>
</typedef>
</hibernate-mapping>
--------------------------------------------------------------
Comment by going to Community
[http://community.jboss.org/docs/DOC-16177]
Create a new document in jBPM at Community
[http://community.jboss.org/choose-container!input.jspa?contentType=102&co...]
13 years, 8 months