<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<body link="#355491" alink="#4262a1" vlink="#355491" style="background: #e2e2e2; margin: 0; padding: 20px;">
<div>
<table cellpadding="0" bgcolor="#FFFFFF" border="0" cellspacing="0" style="border: 1px solid #dadada; margin-bottom: 30px; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
<tbody>
<tr>
<td>
<table border="0" cellpadding="0" cellspacing="0" bgcolor="#FFFFFF" style="border: solid 2px #ccc; background: #dadada; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
<tbody>
<tr>
<td bgcolor="#000000" valign="middle" height="58px" style="border-bottom: 1px solid #ccc; padding: 20px; -moz-border-radius-topleft: 3px; -moz-border-radius-topright: 3px; -webkit-border-top-right-radius: 5px; -webkit-border-top-left-radius: 5px;">
<h1 style="color: #333333; font: bold 22px Arial, Helvetica, sans-serif; margin: 0; display: block !important;">
<!-- To have a header image/logo replace the name below with your img tag -->
<!-- Email clients will render the images when the message is read so any image -->
<!-- must be made available on a public server, so that all recipients can load the image. -->
<a href="http://community.jboss.org/index.jspa" style="text-decoration: none; color: #E1E1E1">JBoss Community</a></h1>
</td>
</tr>
<tr>
<td bgcolor="#FFFFFF" style="font: normal 12px Arial, Helvetica, sans-serif; color:#333333; padding: 20px; -moz-border-radius-bottomleft: 4px; -moz-border-radius-bottomright: 4px; -webkit-border-bottom-right-radius: 5px; -webkit-border-bottom-left-radius: 5px;"><h3 style="margin: 10px 0 5px; font-size: 17px; font-weight: normal;">
jBPM3 Design Documentation
</h3>
<span style="margin-bottom: 10px;">
modified by <a href="http://community.jboss.org/people/admin">Administrator Administrator</a> in <i>jBPM</i> - <a href="http://community.jboss.org/docs/DOC-15934">View the full document</a>
</span>
<hr style="margin: 20px 0; border: none; background-color: #dadada; height: 1px;">
<div class="jive-rendered-content"><p>The purpose of this article is to gather design documents and diagrams together.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><div class="toc" style="border: 1px dashed black; padding: 10px;"><ul><ul><ul><li>
<a class="jive-link-anchor-small" href="#Design_Diagrams">Design Diagrams</a>
</li>
<ul><li>
<a class="jive-link-anchor-small" href="#Product_Components">Product Components</a>
</li>
<li>
<a class="jive-link-anchor-small" href="#Process_definition_and_instance">Process definition and instance</a>
</li>
<li>
<a class="jive-link-anchor-small" href="#Node_hierarchy">Node hierarchy</a>
</li>
<li>
<a class="jive-link-anchor-small" href="#Asynchronous_node">Asynchronous node</a>
</li>
<li>
<a class="jive-link-anchor-small" href="#Timer">Timer</a>
</li>
</ul><li>
<a class="jive-link-anchor-small" href="#Project_Modules">Project Modules</a>
</li>
<li>
<a class="jive-link-anchor-small" href="#Tooling_Interfaces">Tooling Interfaces</a>
</li>
<ul><li>
<a class="jive-link-anchor-small" href="#Graphical_process_designer">Graphical process designer</a>
</li>
<li>
<a class="jive-link-anchor-small" href="#Web_console">Web console</a>
</li>
</ul><li>
<a class="jive-link-anchor-small" href="#Database">Database</a>
</li>
<ul><li>
<a class="jive-link-anchor-small" href="#Compatibility">Compatibility</a>
</li>
<li>
<a class="jive-link-anchor-small" href="#Schema">Schema</a>
</li>
<ul><li>
<a class="jive-link-anchor-small" href="#Definition_data">Definition data</a>
</li>
<li>
<a class="jive-link-anchor-small" href="#Execution_data">Execution data</a>
</li>
</ul></ul><li>
<a class="jive-link-anchor-small" href="#API_Usage">API Usage</a>
</li>
<ul><li>
<a class="jive-link-anchor-small" href="#Starting_a_process_instance">Starting a process instance</a>
</li>
<li>
<a class="jive-link-anchor-small" href="#Signaling_a_token">Signaling a token</a>
</li>
<li>
<a class="jive-link-anchor-small" href="#Retrieving_a_task_list">Retrieving a task list</a>
</li>
</ul><li>
<a class="jive-link-anchor-small" href="#Test_Coverage">Test Coverage</a>
</li>
<ul><li>
<a class="jive-link-anchor-small" href="#Continuous_integration">Continuous integration</a>
</li>
<li>
<a class="jive-link-anchor-small" href="#Areas_of_attention">Areas of attention</a>
</li>
</ul></ul></ul></ul></div></p><h3 id="Design_Diagrams">Design Diagrams</h3><h4 id="Product_Components">Product Components</h4><p><a href="http://community.jboss.org/servlet/JiveServlet/showImage/102-15934-3-9952/jbpm3.components.png"><span> http://community.jboss.org/servlet/JiveServlet/downloadImage/102-15934-3-9952/450-287/jbpm3.components.png </span></a></p><h4 id="Process_definition_and_instance">Process definition and instance</h4><p><a href="http://community.jboss.org/servlet/JiveServlet/showImage/102-15934-3-9971/procdef_procinst.png"><span> http://community.jboss.org/servlet/JiveServlet/downloadImage/102-15934-3-9971/450-159/procdef_procinst.png </span></a></p><h4 id="Node_hierarchy">Node hierarchy</h4><p><a href="http://community.jboss.org/servlet/JiveServlet/showImage/102-15934-3-9973/nodetypes.png"><span> http://community.jboss.org/servlet/JiveServlet/downloadImage/102-15934-3-9973/450-203/nodetypes.png </span></a></p><h4 id="Asynchronous_node">Asynchronous node</h4><p><a href="http://community.jboss.org/servlet/JiveServlet/showImage/102-15934-3-9974/async_node.png"><span> http://community.jboss.org/servlet/JiveServlet/downloadImage/102-15934-3-9974/450-355/async_node.png </span></a></p><h4 id="Timer">Timer</h4><p><a href="http://community.jboss.org/servlet/JiveServlet/showImage/102-15934-3-9972/job_executor.png"><span> http://community.jboss.org/servlet/JiveServlet/downloadImage/102-15934-3-9972/450-215/job_executor.png </span></a></p><h3 id="Project_Modules">Project Modules</h3><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><table cellpadding="3" class="jiveBorder" style="border: 1px solid #000000;"><tbody><tr align="center" style="color: #ffffff; background-color: #6690bc;"><th style="border: 1px solid #000000;">Module</th><th style="border: 1px solid #000000;">Description</th></tr><tr><td style="border: 1px solid #000000;">core</td><td style="border: 1px solid #000000;">Process engine codebase and the project test suite.</td></tr><tr><td style="border: 1px solid #000000;">db</td><td style="border: 1px solid #000000;">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.</td></tr><tr><td style="border: 1px solid #000000;">distribution</td><td style="border: 1px solid #000000;"><p>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.</p></td></tr><tr><td style="border: 1px solid #000000;">enterprise</td><td style="border: 1px solid #000000;">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.</td></tr><tr><td style="border: 1px solid #000000;">examples</td><td style="border: 1px solid #000000;">Sample processes that ship with the product.</td></tr><tr><td style="border: 1px solid #000000;">identity</td><td style="border: 1px solid #000000;">Identity component containing the classes for users, groups and memberships.</td></tr><tr><td style="border: 1px solid #000000;">simulation</td><td style="border: 1px solid #000000;">Process analysis and optimization tool donated by <a class="jive-link-external-small" href="http://www.camunda.com/">Camunda GmbH</a>. Not part of the product.</td></tr><tr><td style="border: 1px solid #000000;"><p>userguide</p></td><td style="border: 1px solid #000000;">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.</td></tr></tbody></table><h3></h3><h3 id="Tooling_Interfaces">Tooling Interfaces</h3><h4 id="Graphical_process_designer">Graphical process designer</h4><p>GPD depends on the file <span style="font-family: courier new,courier;">src/main/etc/version.info.xml</span> 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:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><table cellpadding="3" class="jiveBorder" style="border: 1px solid #000000;"><tbody><tr align="center" style="color: #ffffff; background-color:#6690BC;"><th style="border: 1px solid #000000;">Directory</th><th style="border: 1px solid #000000;">Contents</th></tr><tr><td style="border: 1px solid #000000;">lib</td><td style="border: 1px solid #000000;">binaries and dependencies</td></tr><tr><td style="border: 1px solid #000000;">src</td><td style="border: 1px solid #000000;">source jars</td></tr><tr><td style="border: 1px solid #000000;">config</td><td style="border: 1px solid #000000;">configuration resources</td></tr><tr><td style="border: 1px solid #000000;">examples</td><td style="border: 1px solid #000000;">sample processes</td></tr></tbody></table><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>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.</p><h4 id="Web_console">Web console</h4><p>The console just uses the jBPM 3 API and libraries directly and it should be configured to connect to a data source.</p><h3 id="Database">Database</h3><h4 id="Compatibility">Compatibility</h4><p>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).</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>jBPM is continuously evaluated with the relational database systems listed in <a class="jive-link-wiki-small" href="http://community.jboss.org/docs/DOC-13763">jBPM3 Platform Support</a>.</p><h4 id="Schema">Schema</h4><p>The following sections will discuss the jBPM schema. Refer to <a class="jive-link-wiki-small" href="http://community.jboss.org/docs/DOC-11086">Jbpm31DataModel</a> for diagrams of the definition and execution data models.</p><h5 id="Definition_data">Definition data</h5><ul><li>JBPM_PROCESSDEFINITION: general process definition data (name, description, etc).</li><li>JBPM_NODE: data about one node in the process definition. All node types will store common data in this table.</li><li>JBPM_TRANSITION: every record in this table represents one transition between two nodes of the process definition.</li><li>JBPM_EVENT: static data about events that are triggered during process execution.</li><li>JBPM_ACTION: user code related to the process definition.</li><li>JBPM_DELEGATION: information about user code that uses delegation classes.</li><li>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.</li><li>JBPM_VARIABLEACCESS: stores the read/write and mapping information for variables when variables are passed to for example subprocesses.</li><li>JBPM_TASK: contains static information about tasks: task name, properties (blocking, duedate, etc.), assignee expression.</li><li>JBPM_MODULEDEFINITION: generic table that stores for example (a part of) a task definition, a process definition start task, etc.</li><li>JBPM_SWIMLANE: static description of a task swimlane. Contains an expression or a reference to a delegation class for the actual assignment at runtime.</li><li>JBPM_TASKCONTROLLER: Stores the reference to a user code delegation class that implements task controller functionality.</li><li>JBPM_ID_USER/GROUP/MEMBERSHIP: user/group data for the default identity component</li></ul><h5 id="Execution_data">Execution data</h5><ul><li>JBPM_PROCESSINSTANCE: general data about an execution of a process definition.</li><li>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.</li><li>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.</li><li>JBPM_BYTEARRAY/JBPM_BYTEBLOCK: tables used to store binary data (eg binary variables).</li><li>JBPM_SWIMLANEINSTANCE: contains runtime evaluations of assignment expressions/delegations.</li><li>JBPM_TASKINSTANCE: runtime tasks (ie with a runtime actor and token reference).</li><li>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.</li><li>JBPM_JOB: stores runtime job information that is used to execute jobs, and in particular asynchronous continuations of process logic, by the job executor.</li><li>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.</li><li>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.</li></ul><h3 id="API_Usage">API Usage</h3><h4 id="Starting_a_process_instance">Starting a process instance</h4><p><a href="http://community.jboss.org/servlet/JiveServlet/showImage/102-15934-3-9968/jbpm3.api.sequence.start.process.instance.png"><span> http://community.jboss.org/servlet/JiveServlet/downloadImage/102-15934-3-9968/450-332/jbpm3.api.sequence.start.process.instance.png </span></a></p><h4 id="Signaling_a_token">Signaling a token</h4><p><a href="http://community.jboss.org/servlet/JiveServlet/showImage/102-15934-3-9969/jbpm3.api.sequence.signal.png"><span> http://community.jboss.org/servlet/JiveServlet/downloadImage/102-15934-3-9969/450-416/jbpm3.api.sequence.signal.png </span></a></p><h4 id="Retrieving_a_task_list">Retrieving a task list</h4><p><a href="http://community.jboss.org/servlet/JiveServlet/showImage/102-15934-3-9970/jbpm3.api.sequence.task.list.png"><span> http://community.jboss.org/servlet/JiveServlet/downloadImage/102-15934-3-9970/450-330/jbpm3.api.sequence.task.list.png </span></a></p><h3 id="Test_Coverage">Test Coverage</h3><h4 id="Continuous_integration">Continuous integration</h4><p>The project leverages the <a class="jive-link-external-small" href="http://http://hudson.jboss.org/hudson/view/jBPM/">Hudson installation</a> maintained by JBoss QA. The codebase also provides scripts and configuration files to set up a local Hudson server useful for troubleshooting purposes. Visit <a class="jive-link-wiki-small" href="http://community.jboss.org/docs/DOC-12865">jBPM3 Hudson Setup</a> for a step-by-step guide.</p><h4 id="Areas_of_attention">Areas of attention</h4><p>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.</p><p>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.</p></div>
<div style="background-color: #f4f4f4; padding: 10px; margin-top: 20px;">
<p style="margin: 0;">Comment by <a href="http://community.jboss.org/docs/DOC-15934">going to Community</a></p>
<p style="margin: 0;">Create a new document in jBPM at <a href="http://community.jboss.org/choose-container!input.jspa?contentType=102&containerType=14&container=2034">Community</a></p>
</div></td>
</tr>
</tbody>
</table>
</td>
</tr>
</tbody>
</table>
</div>
</body>
</html>