Author: tom.baeyens(a)jboss.com Date: 2009-05-04 11:44:03 -0400 (Mon, 04 May 2009) New Revision: 4713 Added: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-ProcessVirtualMachine.xml jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/chxx-Environments.xml jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/chxx-ExecutionModes.xml jbpm4/trunk/modules/userguide/src/main/docbook/en/images/process.subprocess.document.png jbpm4/trunk/modules/userguide/src/main/docbook/en/images/process.subprocess.review.png Removed: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-Environments.xml jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-ExecutionModes.xml jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch07-Variables.xml jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch08-Timers.xml jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch09-AsynchronousContinuations.xml jbpm4/trunk/modules/userguide/src/main/docbook/en/images/process.subprocess.variables.review.png Modified: jbpm4/trunk/modules/devguide/src/main/docbook/en/master.xml jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch01-Introduction.xml jbpm4/trunk/modules/examples/src/test/resources/org/jbpm/examples/subprocess/outcomeactivity/SubProcessDocument.jpdl.xml jbpm4/trunk/modules/examples/src/test/resources/org/jbpm/examples/subprocess/outcomeactivity/SubProcessReview.jpdl.xml jbpm4/trunk/modules/examples/src/test/resources/org/jbpm/examples/subprocess/outcomevalue/SubProcessDocument.jpdl.xml jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch05-Jpdl.xml Log: devguide updates and subprocess images in userguide and coordinates in example sources Modified: jbpm4/trunk/modules/devguide/src/main/docbook/en/master.xml =================================================================== --- jbpm4/trunk/modules/devguide/src/main/docbook/en/master.xml 2009-05-04 15:40:57 UTC (rev 4712) +++ jbpm4/trunk/modules/devguide/src/main/docbook/en/master.xml 2009-05-04 15:44:03 UTC (rev 4713) @@ -2,14 +2,11 @@ <!DOCTYPE book [ <!ENTITY ch01-Introduction SYSTEM "modules/ch01-Introduction.xml"> - <!ENTITY ch02-ExecutionModes SYSTEM "modules/ch02-ExecutionModes.xml"> + <!ENTITY ch02-ProcessVirtualMachine SYSTEM "modules/ch02-ProcessVirtualMachine.xml"> <!ENTITY ch03-Architecture SYSTEM "modules/ch03-Architecture.xml"> <!ENTITY ch04-ImplementingBasicActivities SYSTEM "modules/ch04-ImplementingBasicActivities.xml"> <!ENTITY ch05-ProcessAnatomy SYSTEM "modules/ch05-ProcessAnatomy.xml"> <!ENTITY ch06-ImplementingAdvancedActivities SYSTEM "modules/ch06-ImplementingAdvancedActivities.xml"> - <!ENTITY ch07-Variables SYSTEM "modules/ch07-Variables.xml"> - <!ENTITY ch08-Timers SYSTEM "modules/ch08-Timers.xml"> - <!ENTITY ch09-AsynchronousContinuations SYSTEM "modules/ch09-AsynchronousContinuations.xml"> <!ENTITY ch10-SoftwareLogging SYSTEM "modules/ch10-SoftwareLogging.xml"> <!ENTITY ch11-History SYSTEM "modules/ch11-History.xml"> ]> @@ -23,14 +20,11 @@ <toc /> &ch01-Introduction; - &ch02-ExecutionModes; + &ch02-ProcessVirtualMachine; &ch03-Architecture; &ch04-ImplementingBasicActivities; &ch05-ProcessAnatomy; &ch06-ImplementingAdvancedActivities; - &ch07-Variables; - &ch08-Timers; - &ch09-AsynchronousContinuations; &ch10-SoftwareLogging; &ch11-History; Modified: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch01-Introduction.xml =================================================================== --- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch01-Introduction.xml 2009-05-04 15:40:57 UTC (rev 4712) +++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch01-Introduction.xml 2009-05-04 15:44:03 UTC (rev 4713) @@ -2,130 +2,32 @@ <title>Introduction</title> <section> - <title>License and EULA</title> - <para>The Process Virtual Machine component is distributed under the terms of the - GNU Lesser General Public License (LGPL) and the JBoss End User License Agreement (EULA). - See <ulink url="../../../lgpl.html">the full LGPL license text</ulink> and <ulink url="../../../JBossORG-EULA.txt">the - full End User License Agreement</ulink>. + <title>Target audience</title> + <para>This developers guide is intended for experienced developers that + want to get the full flexibility out of jBPM. The features described in this + developers guide will not be supported. Use at your own risk. </para> </section> <section> <title>Sources</title> - <para>The source code for this component can be found in the jBPM SVN repository: + <para>The source code for jBPM can be found here: + <ulink url="https://anonsvn.jboss.org/repos/jbpm/jbpm4/">https://an... </para> - <ulink url="https://anonsvn.jboss.org/repos/jbpm/jbpm4/pvm/">https:... + <para>A description of how to build the sources is available in the wiki:</para> + <ulink url="http://www.jboss.org/community/docs/DOC-12867">http://w... </section> <section> - <title>JVM version</title> - <para>jbpm-pvm.jar requires a JVM version 5 or higher. + <title>Maven repository</title> + <para>You can use jBPM with the libraries that ship in the distribution. The <literal>jbpm.jar</literal> + in the distribution contains the classes of many jBPM modules: jbpm-api, jbpm-log, jbpm-test-base, jbpm-pvm, + jbpm-jpdl and jbpm-enterprise. So the single <literal>jbpm.jar</literal> in the distribution + does not allow to make a compile time distinction between the API classes and the implementation classes. + If you prefer to build your project with only a dependency on jBPM's API, then + our repository can be used directly. It is located here: + <ulink url="http://repository.jboss.com/maven2/org/jbpm/jbpm4/">htt... </para> </section> - - <section> - <title>Library dependencies</title> - <para>For building and executing processes the jbpm-pvm.jar does not have any other - dependencies then on the JVM. If you're using DB persistence, then there is a dependency - on hibernate and it's dependencies. More information about the optional depedencies can - be found in the <ulink url="../../lib/optional-dependencies.html">lib directory</ulink>. - </para> - </section> - - <section> - <title>What is it</title> - <para>In essence, the Process Virtual Machine is a framework specifying executable - graphs. A process definition represents an execution flow and has a structure that - be represented graphically as a diagram. - </para> - <figure id="example.process.graph"> - <title>Example process definition</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/process.loan.png"/></imageobject></mediaobject> - </figure> - <para>Typically, process definitions are static. A process definition is composed of - activities and transitions. The runtime behaviour of a activity is encapsulated in a so called - Activity and it's decoupled from the process graph structure. - </para> - <figure id="class.diagram.process.definition"> - <title>Process structure class diagram</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/class.diagram.process.definition.png"/></imageobject></mediaobject> - </figure> - <para>The Process Virtual - Machine doesn't contain any such activity implementations. It only provides the - execution environment and an activity API to write <literal>Activity</literal> - implementations as Java components. Activities can also be wait states. This means - that the activity control flow goes outside the process system. For example a human task - or invoking an service asynchronously. - </para> - <para>Many executions can be started for one process definition. An execution is a pointer - that keeps track of the current activity. - </para> - <figure id="example.execution"> - <title>Example execution</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/loan.execution.png"/></imageobject></mediaobject> - </figure> - <para>To represent concurrent paths of execution, there is - a hierarchical parent-child relation between so that one process instance can cope with concurrent - paths of execution. - </para> - <figure id="class.diagram.process.execution"> - <title>Execution class diagram</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/class.diagram.process.execution.png"/></imageobject></mediaobject> - </figure> - </section> - <section> - <title>Features</title> - <para>The key features of this library are - <itemizedlist> - <listitem>Create executable processes that are based on a diagram structure</listitem> - <listitem>Runtime behaviour of the activities can be provided as Activity implementations</listitem> - <listitem>Activities can be wait states</listitem> - <listitem>There are no constraints on the process graph structure</listitem> - <listitem>Processes diagrams can be based on composition (aka block structured)</listitem> - <listitem>Processes diagrams can be a mix of graph based and composition</listitem> - <listitem>During wait states, the runtime state of a process execution can be persisted</listitem> - <listitem>Persistence is optional</listitem> - </itemizedlist> - </para> - </section> - - <section> - <title>Purpose</title> - <para>The Process Virtual Machine is designed in such a way that it's easy to build - workflow, BPM, orchestration and other graph based execution langauges on top - of it. Examples of languages that have been built on top of this library: - </para> - <itemizedlist> - <listitem>jPDL: Workflow language that combines powerful human task capabilities with easy binding to Java.</listitem> - <listitem>BPEL: Web-Service orchestration (to be exact for the purists: BPEL is a WSDL service orchestration language)</listitem> - <listitem>Pageflow: To describe navigation handling in a web application, pages can be seen as activities and the nagivation between the pages as transitions.</listitem> - <listitem>XPDL: A graph based process language standardized by the Workflow Management Coalition (WfMC)</listitem> - </itemizedlist> - <para>Even while the nature of these languages is already very diverse, these are - all examples of general purpose workflow languages. The real power of the - Process Virtual Machine is that it's very easy to build Domain Specific Languages (DSL) - with it. For instance, it's very easy to build a very simple (and dedicated) workflow - language to specify approvals related to documents in a document management system. - </para> - <para>BPM as a discipline refers to the management level effort to optimise efficiency - of an organisation by analysing and optimising the procedures of how people and systems - work together. In designing the Process Virtual Machine and the jPDL language - in particular, we have spend great care on facilitating the link between BPM analysis - notations and executable process languages. Here are the most known modeling notations: - </para> - <itemizedlist> - <listitem>BPMN: OMG latest notation for modeling business processes. - This is a modeling notation that is targetted explicitely to be bound - to executable processes. - </listitem> - <listitem>UML activity diagrams: OMG notation for modeling business - processes. Mostly used in business context.</listitem> - <listitem>UML state diagrams: OMG modeling notation for defining technical - state machines. More used in a technical context.</listitem> - <listitem>EPC: Event driven process chains. Rich notation for modeling - business processes driven by SAP and IDS Scheer.</listitem> - </itemizedlist> - </section> - </chapter> Deleted: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-Environments.xml =================================================================== --- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-Environments.xml 2009-05-04 15:40:57 UTC (rev 4712) +++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-Environments.xml 2009-05-04 15:44:03 UTC (rev 4713) @@ -1,20 +0,0 @@ -<chapter id="environments"> - <title>Environments</title> - - <para>This chapter describes the support for other environments then the ones - described in the userguide. - </para> - - <section id="spring"> - <title>Spring</title> - <para>TODO - </para> - </section> - - <section id="osgi"> - <title>OSGi</title> - <para>TODO - </para> - </section> - -</chapter> \ No newline at end of file Deleted: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-ExecutionModes.xml =================================================================== --- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-ExecutionModes.xml 2009-05-04 15:40:57 UTC (rev 4712) +++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-ExecutionModes.xml 2009-05-04 15:44:03 UTC (rev 4713) @@ -1,404 +0,0 @@ -<chapter id="executionmodes"> - <title>Execution modes</title> - - <para>There are basically three process execution modes: object, persistent - and embedded. For the persistent and embedded execution modes, the process - execution has to participate in a transaction. In that case, the process - execution has to take place inside of an Environment. The environment will be - used to bind process execution updates to a transaction in the application - transaction. The environment can be used to bind to e.g. a JDBC connection, - JTA, BMT, Spring transactions and so on. - </para> - - <section id="objectexecutionmode"> - <title>Object execution mode</title> - <para>Object execution mode is the simplest form of working with the Process - Virtual Machine. This means working with the process definition and execution - objects directly through the client API. Let's show this by an example. We - start by creating a <literal>ClientProcessDefinition</literal> that looks like this: - </para> - - <para>Object execution mode is the simplest form of working with the Process - Virtual Machine. This means working with the process definition and execution - objects directly through the client API. Let's show this by an example. We - start by creating a <literal>ClientProcessDefinition</literal> that looks like this: - </para> - <figure id="loan.process"> - <title>The loan process</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/process.loan.png"/></imageobject></mediaobject> - </figure> - <programlisting>ClientProcessDefinition processDefinition = ProcessFactory.build("loan") - .activity("submit loan request").initial().behaviour(AutomaticActivity.class) - .transition().to("evaluate") - .activity("evaluate").behaviour(WaitState.class) - .transition("approve").to("wire money") - .transition("reject").to("end") - .activity("wire money").behaviour(AutomaticActivity.class) - .transition().to("archive") - .activity("archive").behaviour(WaitState.class) - .transition().to("end") - .activity("end").behaviour(WaitState.class) -.done();</programlisting> - <para>The <literal>ProcessFactory</literal> is a helper class that provides convenience - for building an object graph that represents a process definition. - <literal>AutomaticActivity</literal> is a pass-through activity without anything - happening and <literal>WaitState</literal> will wait until an external signal is given. Both - activity implementations will be covered in more depth later. - </para> - <para>The <literal>processDefinition</literal> object serves as a factory for process - instance objects. A process instance represents one execution of the process definition. - More precise, the process instance is the main path of execution. - </para> - <programlisting>ClientExecution execution = processDefinition.startProcessInstance();</programlisting> - <para>A process instance - itself is also an <literal>Execution</literal>. Potentially, an execution can have - child executions to represent concurrent paths of execution. - </para> - <para>The <literal>execution</literal> can be seen as a state machine that operates as - described in the process definition. Starting a process - instance means that the initial activity of the process definition is executed. - Since this is an automatic activity, the execution will proceed to the - <literal>evaluate</literal> activity. The <literal>evaluate</literal> activity is a wait state. - When the execution arrived at the evaluate activity, the method <literal>startProcessInstance</literal> - will return and waits until an external signal is provided with the <literal>signal</literal> - method. So after the <literal>startProcessInstance</literal> we can verify if the - execution is positioned in the evaluate activity. - </para> - <programlisting>assertEquals("evaluate", execution.getActivityName());</programlisting> - <para>To make the process execute further, we provide an external trigger with the - <literal>signal</literal> method. The result of the evaluation will be given as the - signalName parameter like this: - </para> - <programlisting>execution.signal("approve");</programlisting> - <para>The <literal>WaitState</literal> activity implementation will take the transition - that corresponds to the given signalName. So the execution will first execute - the automatic activity <literal>wire money</literal> and then return after entering - the next wait state <literal>archive</literal>. - </para> - <programlisting>assertEquals("archive", execution.getActivityName());</programlisting> - <para>When the execution is waiting in the archive activity, the default signal will - make it take the first unnamed transition. - </para> - <programlisting>execution.signal(); -assertEquals("end", execution.getActivityName());</programlisting> - <para>The process has executed in the thread of the client. The - <literal>startProcessInstance</literal> method only returned when the <literal>evaluate</literal> - activity was reached. In other words, the <literal>ClientProcessDefinition.startProcessInstance</literal> - and <literal>ClientExecution.signal</literal> methods are blocking until the next - wait state is reached. - </para> - </section> - - <section id="persistentexecutionmode"> - <title>Persistent execution mode</title> - <para>The Process Virtual Machine also contains the hibernate mappings to store the - process definitions and executions in any database. A special session facade called - <literal>ExecutionService</literal> is provided for working with process executions - in such a persistent environment. - </para> - <para>Two configuration files should be available on the classpath: an environment - configuration file and a <literal>hibernate.properties</literal> file. A basic - configuration for persistent execution mode in a standard Java environment looks - like this: - </para> - <literal><emphasis role="bold">environment.cfg.xml</emphasis>:</literal> - <programlisting>&lt;jbpm-configuration xmlns=&quot;http://jbpm.org/xsd/cfg&quot;&gt; - - &lt;process-engine-context&gt; - - &lt;deployer-manager&gt; - &lt;assign-file-type&gt; - &lt;file extension=&quot;.jpdl.xml&quot; type=&quot;jpdl&quot; /&gt; - &lt;/assign-file-type&gt; - &lt;parse-jpdl /&gt; - &lt;check-process /&gt; - &lt;check-problems /&gt; - &lt;save /&gt; - &lt;/deployer-manager&gt; - - &lt;process-service /&gt; - &lt;execution-service /&gt; - &lt;management-service /&gt; - - &lt;command-service&gt; - &lt;retry-interceptor /&gt; - &lt;environment-interceptor /&gt; - &lt;standard-transaction-interceptor /&gt; - &lt;/command-service&gt; - - &lt;hibernate-configuration&gt; - &lt;properties resource=&quot;hibernate.properties&quot; /&gt; - &lt;mapping resource=&quot;jbpm.pvm.typedefs.hbm.xml&quot; /&gt; - &lt;mapping resource=&quot;jbpm.pvm.wire.hbm.xml&quot; /&gt; - &lt;mapping resource=&quot;jbpm.pvm.definition.hbm.xml&quot; /&gt; - &lt;mapping resource=&quot;jbpm.pvm.execution.hbm.xml&quot; /&gt; - &lt;mapping resource=&quot;jbpm.pvm.variable.hbm.xml&quot; /&gt; - &lt;mapping resource=&quot;jbpm.pvm.job.hbm.xml&quot; /&gt; - &lt;mapping resource=&quot;jbpm.jpdl.hbm.xml&quot; /&gt; - &lt;cache-configuration resource=&quot;jbpm.pvm.cache.xml&quot; - usage=&quot;nonstrict-read-write&quot; /&gt; - &lt;/hibernate-configuration&gt; - - &lt;hibernate-session-factory /&gt; - - &lt;id-generator /&gt; - &lt;types resource=&quot;jbpm.pvm.types.xml&quot; /&gt; - &lt;job-executor auto-start=&quot;false&quot; /&gt; - - &lt;/process-engine-context&gt; - - &lt;transaction-context&gt; - &lt;hibernate-session /&gt; - &lt;transaction /&gt; - &lt;pvm-db-session /&gt; - &lt;job-db-session /&gt; - &lt;message-session /&gt; - &lt;/transaction-context&gt; - -&lt;/jbpm-configuration&gt;</programlisting> - <para>And next to it a hibernate.properties like this</para> - <literal>hibernate.properties:</literal> - <programlisting>hibernate.dialect org.hibernate.dialect.HSQLDialect -hibernate.connection.driver_class org.hsqldb.jdbcDriver -hibernate.connection.url jdbc:hsqldb:mem:. -hibernate.connection.username sa -hibernate.connection.password -hibernate.hbm2ddl.auto create-drop -hibernate.cache.use_second_level_cache true -hibernate.cache.provider_class org.hibernate.cache.HashtableCacheProvider -# hibernate.show_sql true -hibernate.format_sql true -hibernate.use_sql_comments true</programlisting> - <para>Then you can obtain the services from the environment factory like this: - </para> - <programlisting>EnvironmentFactory environmentFactory = new PvmEnvironmentFactory(&quot;environment.cfg.xml&quot;); - -ProcessService processService = environmentFactory.get(ProcessService.class); -ExecutionService executionService = environmentFactory.get(ExecutionService.class); -ManagementService managementService = environmentFactory.get(ManagementService.class);</programlisting> - <para>The responsibility of the <literal>ProcessService</literal> is to manage - the repository of process definitions. Before we can start a process execution, - the process definition needs to be deployed into the process repository. - Process definitions can be supplied in various formats and process definition - languages. A deployment collects process definition information from various - sources like a ZIP file, an XML file or a process definition object. - The method <literal>ProcessService.deploy</literal> will take a deployment - through all the deployers that are configured in the configuration file. - </para> - <para>In this example, we'll supply a process definition programmatically - for deployment.</para> - <programlisting>ClientProcessDefinition processDefinition = ProcessFactory.build("loan") - .activity("submit loan request").initial().behaviour(AutomaticActivity.class) - .transition().to("evaluate") - .activity("evaluate").behaviour(WaitState.class) - .transition("approve").to("wire money") - .transition("reject").to("end") - .activity("wire money").behaviour(AutomaticActivity.class) - .transition().to("archive") - .activity("archive").behaviour(WaitState.class) - .transition().to("end") - .activity("end").behaviour(WaitState.class) -.done(); - -Deployment deployment = new Deployment(processDefinition); -processService.deploy(deployment);</programlisting> - <para>Now, a version of that process definition is stored in the database. - The <literal>check-version</literal> deployer will have assigned version 1 - to the stored process definition. The <literal>create-id</literal> deployer - will have distilled id <literal>loan:1</literal> from the process name and the - assigned version. - </para> - <para>Deploying that process again will lead to a new process definition - version being created in the database. But an incremented version number will - be assigned. For the purpose of versioning, process definitions are considered - equal if they have the same name.</para> - <para>It is recommended that a user provided key reference is supplied for - all process executions. Starting a new process execution goes like this: - </para> - <programlisting>Execution execution = executionService.startExecution("loan:1", "request7836");</programlisting> - <para>The return value is an execution interface, which prevents navigation of relations. - That is because outside of the service methods, the transaction and hibernate session - is not guaranteed to still be open. In fact, the default configuration as given - above will only keep the transaction and session open for the duration of the - service method. So navigating the relations outside of the service methods might result - into a hibernate <literal>LazyInitializationException</literal>. But the - current activity name can still be verified: - </para> - <programlisting>assertEquals("evaluate", execution.getActivityName());</programlisting> - <para>Also very important is the generated id that can be obtained. The default - <literal>id-generator</literal> will use the process definition id and the - given key to make a unique id for the process execution like this:</para> - <programlisting>assertEquals("loan:1/request7836", execution.getId());</programlisting> - <para>That id must be when providing the subsequent external triggers to the - process execution like this: - </para> - <programlisting>executionService.signalExecution("loan:1/request7836", "approve");</programlisting> - <para>More information about service interfaces to run in persistent - mode can be found in package - <ulink url="../../api/org/jbpm/pvm/package-summary.html"><literal>org.jbpm.pvm</literal> of the - api docs</ulink>. - </para> - </section> - - <section id="embeddedexecutionmode"> - <title>Embedded execution mode</title> - <para>Embedded execution mode means that the state of a process is stored - as a string column inside a user domain object like e.g. a loan. - </para> - <programlisting>public class Loan { - - <emphasis role="bold">/** the loan process definition as a static resource */ - private static final ClientProcessDefinition processDefinition = createLoanProcess(); - - private static ClientProcessDefinition createLoanProcess() { - ClientProcessDefinition processDefinition = ProcessFactory.build(&quot;loan&quot;) - .activity(&quot;submit loan request&quot;).initial().behaviour(AutomaticActivity.class) - .transition().to(&quot;evaluate&quot;) - .activity(&quot;evaluate&quot;).behaviour(WaitState.class) - .transition(&quot;approve&quot;).to(&quot;wire money&quot;) - .transition(&quot;reject&quot;).to(&quot;end&quot;) - .activity(&quot;wire money&quot;).behaviour(AutomaticActivity.class) - .transition().to(&quot;archive&quot;) - .activity(&quot;archive&quot;).behaviour(WaitState.class) - .transition().to(&quot;end&quot;) - .activity(&quot;end&quot;).behaviour(WaitState.class) - .done(); - - return processDefinition; - } - - /** exposes the process definition to the execution hibernate type */ - private static ClientProcessDefinition getProcessDefinition() { - return processDefinition; - } - </emphasis> - - long dbid; - String customer; - double amount; - <emphasis role="bold">ClientExecution execution;</emphasis> - - /** constructor for persistence */ - protected Loan() { - } - - public Loan(String customer, double amount) { - this.customer = customer; - this.amount = amount; - <emphasis role="bold">this.execution = processDefinition.startProcessInstance();</emphasis> - } - - public void approve() { - <emphasis role="bold">execution.signal(&quot;approve&quot;);</emphasis> - } - - public void reject() { - <emphasis role="bold">execution.signal(&quot;reject&quot;);</emphasis> - } - - public void archiveComplete() { - <emphasis role="bold">execution.signal();</emphasis> - } - - public String getState() { - return <emphasis role="bold">execution.getActivityName()</emphasis>; - } - - ...getters... -}</programlisting> - <para>If you ignore the bold parts for a second, you can see that this is a - POJO without anything fancy. It's just a bean that can be stored with hibernate. - The bold part indicate that implementation part of the class that is related - to process and execution. Not that nothing of the process definition or - execution is exposed to the user of the Loan class. - </para> - <para>Each <literal>Loan</literal> object corresponds to a <literal>loan</literal> - process instance. Some methods of the <literal>Loan</literal> class correspond - to the external triggers that need to be given during the lifecycle of a - <literal>Loan</literal> object. - </para> - <para>Next we'll show how to use this class. To get started we need a</para> - <emphasis role="bold"><literal>hibernate.cfg.xml:</literal></emphasis> - <programlisting>&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt; - -&lt;!DOCTYPE hibernate-configuration PUBLIC - &quot;-//Hibernate/Hibernate Configuration DTD 3.0//EN&quot; - &quot;http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd&quot;&gt; - -&lt;hibernate-configuration&gt; - &lt;session-factory&gt; - - &lt;property name=&quot;hibernate.dialect&quot;&gt;org.hibernate.dialect.HSQLDialect&lt;/property&gt; - &lt;property name=&quot;hibernate.connection.driver_class&quot;&gt;org.hsqldb.jdbcDriver&lt;/property&gt; - &lt;property name=&quot;hibernate.connection.url&quot;&gt;jdbc:hsqldb:mem:.&lt;/property&gt; - &lt;property name=&quot;hibernate.connection.username&quot;&gt;sa&lt;/property&gt; - &lt;property name=&quot;hibernate.connection.password&quot;&gt;&lt;/property&gt; - &lt;property name=&quot;hibernate.hbm2ddl.auto&quot;&gt;create&lt;/property&gt; - &lt;property name=&quot;hibernate.show_sql&quot;&gt;true&quot;&lt;/property&gt; - &lt;property name=&quot;hibernate.format_sql&quot;&gt;true&quot;&lt;/property&gt; - &lt;property name=&quot;hibernate.use_sql_comments&quot;&gt;true&quot;&lt;/property&gt; - - &lt;mapping resource=&quot;Loan.hbm.xml&quot;/&gt; - - &lt;/session-factory&gt; -&lt;/hibernate-configuration&gt;</programlisting> - <para>And a</para> - <emphasis role="bold"><literal>Loan.hbm.xml:</literal></emphasis> - <programlisting>&lt;?xml version=&quot;1.0&quot;?&lt; - -&lt;!DOCTYPE hibernate-mapping PUBLIC - &quot;-//Hibernate/Hibernate Mapping DTD 3.0//EN&quot; - &quot;http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd&quot;&lt; - -&lt;hibernate-mapping package=&quot;org.jbpm.pvm.api.db.embedded&quot; default-access=&quot;field&quot;&lt; - - &lt;typedef name=&quot;execution&quot; class=&quot;org.jbpm.pvm.internal.hibernate.ExecutionType&quot; /&lt; - - &lt;class name=&quot;Loan&quot; table=&quot;LOAN&quot;&lt; - - &lt;id name=&quot;dbid&quot;&lt; - &lt;generator class=&quot;sequence&quot;/&lt; - &lt;/id&lt; - - &lt;property name=&quot;execution&quot; type=&quot;execution&quot; /&lt; - &lt;property name=&quot;customer&quot; /&lt; - &lt;property name=&quot;amount&quot; /&lt; - - &lt;/class&lt; - -&lt;/hibernate-mapping&lt;</programlisting> - <para>Then you can use the Loan class like this in a test</para> - <programlisting>Configuration configuration = new Configuration(); -configuration.configure(); -SessionFactory sessionFactory = configuration.buildSessionFactory(); - -// start a session/transaction -Session session = sessionFactory.openSession(); -Transaction transaction = session.beginTransaction(); - -Loan loan = new Loan("john doe", 234.0); -session.save(loan); -assertEquals("evaluate", loan.getState()); - -// start a new session/transaction -transaction.commit(); -session.close(); -session = sessionFactory.openSession(); -transaction = session.beginTransaction(); - -loan = (Loan) session.get(Loan.class, loan.getDbid()); -assertEquals("evaluate", loan.getState()); -loan.approve(); -assertEquals("archive", loan.getState()); - -// start a new session/transaction -transaction.commit(); -session.close();</programlisting> - <para>After executing this code snippet, this is the loan record in the DB:</para> - <figure id="loan.db"> - <title>The loan record in the DB</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/loan.db.png"/></imageobject></mediaobject> - </figure> - </section> - -</chapter> \ No newline at end of file Added: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-ProcessVirtualMachine.xml =================================================================== --- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-ProcessVirtualMachine.xml (rev 0) +++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-ProcessVirtualMachine.xml 2009-05-04 15:44:03 UTC (rev 4713) @@ -0,0 +1,49 @@ +<chapter id="processvirtualmachine"> + <title>The Process Virtual Machine</title> + <para>To accomodate multiple process languages and activity pluggability, jBPM is based on + the Process Virtual Machine. In essence, the Process Virtual Machine is a framework specifying + executable graphs. A process definition represents an execution flow + and has a structure that be represented graphically as a diagram. + </para> + <para>The Process Virtual Machine separates the structure from a process definition from + the activity behaviours. The Process Virtual Machine takes the execution of a process from + one activity to the next and delegates the behaviour of the activities to pluggable Java classes. + There is an API (<literal>ActivityBehaviour</literal>) that serves as the interface between + the Process Virtual Machine and the activity behaviour code. Languages like jPDL are + merely a set of ActivityBehaviour implementations and a parser. + </para> + <figure id="example.process.graph"> + <title>Example process definition</title> + <mediaobject><imageobject><imagedata align="center" fileref="images/process.loan.png"/></imageobject></mediaobject> + </figure> + <para>Typically, process definitions are static. A process definition is composed of + activities and transitions. The runtime behaviour of a activity is encapsulated in a so called + Activity and it's decoupled from the process graph structure. + </para> + <figure id="class.diagram.process.definition"> + <title>Process structure class diagram</title> + <mediaobject><imageobject><imagedata align="center" fileref="images/class.diagram.process.definition.png"/></imageobject></mediaobject> + </figure> + <para>The Process Virtual + Machine doesn't contain any such activity implementations. It only provides the + execution environment and an activity API to write <literal>Activity</literal> + implementations as Java components. Activities can also be wait states. This means + that the activity control flow goes outside the process system. For example a human task + or invoking an service asynchronously. + </para> + <para>Many executions can be started for one process definition. An execution is a pointer + that keeps track of the current activity. + </para> + <figure id="example.execution"> + <title>Example execution</title> + <mediaobject><imageobject><imagedata align="center" fileref="images/loan.execution.png"/></imageobject></mediaobject> + </figure> + <para>To represent concurrent paths of execution, there is + a hierarchical parent-child relation between so that one process instance can cope with concurrent + paths of execution. + </para> + <figure id="class.diagram.process.execution"> + <title>Execution class diagram</title> + <mediaobject><imageobject><imagedata align="center" fileref="images/class.diagram.process.execution.png"/></imageobject></mediaobject> + </figure> +</chapter> Property changes on: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-ProcessVirtualMachine.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Deleted: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch07-Variables.xml =================================================================== --- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch07-Variables.xml 2009-05-04 15:40:57 UTC (rev 4712) +++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch07-Variables.xml 2009-05-04 15:44:03 UTC (rev 4713) @@ -1,4 +0,0 @@ -<chapter id="variables"> - <title>Variables</title> - <para>TODO</para> -</chapter> \ No newline at end of file Deleted: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch08-Timers.xml =================================================================== --- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch08-Timers.xml 2009-05-04 15:40:57 UTC (rev 4712) +++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch08-Timers.xml 2009-05-04 15:44:03 UTC (rev 4713) @@ -1,4 +0,0 @@ -<chapter id="timers"> - <title>Timers</title> - <para>TODO</para> -</chapter> \ No newline at end of file Deleted: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch09-AsynchronousContinuations.xml =================================================================== --- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch09-AsynchronousContinuations.xml 2009-05-04 15:40:57 UTC (rev 4712) +++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch09-AsynchronousContinuations.xml 2009-05-04 15:44:03 UTC (rev 4713) @@ -1,4 +0,0 @@ -<chapter id="asynchronouscontinuations"> - <title>Asynchronous continuations</title> - <para>TODO</para> -</chapter> Copied: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/chxx-Environments.xml (from rev 4705, jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-Environments.xml) =================================================================== --- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/chxx-Environments.xml (rev 0) +++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/chxx-Environments.xml 2009-05-04 15:44:03 UTC (rev 4713) @@ -0,0 +1,20 @@ +<chapter id="environments"> + <title>Environments</title> + + <para>This chapter describes the support for other environments then the ones + described in the userguide. + </para> + + <section id="spring"> + <title>Spring</title> + <para>TODO + </para> + </section> + + <section id="osgi"> + <title>OSGi</title> + <para>TODO + </para> + </section> + +</chapter> \ No newline at end of file Property changes on: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/chxx-Environments.xml ___________________________________________________________________ Name: svn:keywords + Id Revision Name: svn:eol-style + LF Copied: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/chxx-ExecutionModes.xml (from rev 4705, jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-ExecutionModes.xml) =================================================================== --- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/chxx-ExecutionModes.xml (rev 0) +++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/chxx-ExecutionModes.xml 2009-05-04 15:44:03 UTC (rev 4713) @@ -0,0 +1,404 @@ +<chapter id="executionmodes"> + <title>Execution modes</title> + + <para>There are basically three process execution modes: object, persistent + and embedded. For the persistent and embedded execution modes, the process + execution has to participate in a transaction. In that case, the process + execution has to take place inside of an Environment. The environment will be + used to bind process execution updates to a transaction in the application + transaction. The environment can be used to bind to e.g. a JDBC connection, + JTA, BMT, Spring transactions and so on. + </para> + + <section id="objectexecutionmode"> + <title>Object execution mode</title> + <para>Object execution mode is the simplest form of working with the Process + Virtual Machine. This means working with the process definition and execution + objects directly through the client API. Let's show this by an example. We + start by creating a <literal>ClientProcessDefinition</literal> that looks like this: + </para> + + <para>Object execution mode is the simplest form of working with the Process + Virtual Machine. This means working with the process definition and execution + objects directly through the client API. Let's show this by an example. We + start by creating a <literal>ClientProcessDefinition</literal> that looks like this: + </para> + <figure id="loan.process"> + <title>The loan process</title> + <mediaobject><imageobject><imagedata align="center" fileref="images/process.loan.png"/></imageobject></mediaobject> + </figure> + <programlisting>ClientProcessDefinition processDefinition = ProcessFactory.build("loan") + .activity("submit loan request").initial().behaviour(AutomaticActivity.class) + .transition().to("evaluate") + .activity("evaluate").behaviour(WaitState.class) + .transition("approve").to("wire money") + .transition("reject").to("end") + .activity("wire money").behaviour(AutomaticActivity.class) + .transition().to("archive") + .activity("archive").behaviour(WaitState.class) + .transition().to("end") + .activity("end").behaviour(WaitState.class) +.done();</programlisting> + <para>The <literal>ProcessFactory</literal> is a helper class that provides convenience + for building an object graph that represents a process definition. + <literal>AutomaticActivity</literal> is a pass-through activity without anything + happening and <literal>WaitState</literal> will wait until an external signal is given. Both + activity implementations will be covered in more depth later. + </para> + <para>The <literal>processDefinition</literal> object serves as a factory for process + instance objects. A process instance represents one execution of the process definition. + More precise, the process instance is the main path of execution. + </para> + <programlisting>ClientExecution execution = processDefinition.startProcessInstance();</programlisting> + <para>A process instance + itself is also an <literal>Execution</literal>. Potentially, an execution can have + child executions to represent concurrent paths of execution. + </para> + <para>The <literal>execution</literal> can be seen as a state machine that operates as + described in the process definition. Starting a process + instance means that the initial activity of the process definition is executed. + Since this is an automatic activity, the execution will proceed to the + <literal>evaluate</literal> activity. The <literal>evaluate</literal> activity is a wait state. + When the execution arrived at the evaluate activity, the method <literal>startProcessInstance</literal> + will return and waits until an external signal is provided with the <literal>signal</literal> + method. So after the <literal>startProcessInstance</literal> we can verify if the + execution is positioned in the evaluate activity. + </para> + <programlisting>assertEquals("evaluate", execution.getActivityName());</programlisting> + <para>To make the process execute further, we provide an external trigger with the + <literal>signal</literal> method. The result of the evaluation will be given as the + signalName parameter like this: + </para> + <programlisting>execution.signal("approve");</programlisting> + <para>The <literal>WaitState</literal> activity implementation will take the transition + that corresponds to the given signalName. So the execution will first execute + the automatic activity <literal>wire money</literal> and then return after entering + the next wait state <literal>archive</literal>. + </para> + <programlisting>assertEquals("archive", execution.getActivityName());</programlisting> + <para>When the execution is waiting in the archive activity, the default signal will + make it take the first unnamed transition. + </para> + <programlisting>execution.signal(); +assertEquals("end", execution.getActivityName());</programlisting> + <para>The process has executed in the thread of the client. The + <literal>startProcessInstance</literal> method only returned when the <literal>evaluate</literal> + activity was reached. In other words, the <literal>ClientProcessDefinition.startProcessInstance</literal> + and <literal>ClientExecution.signal</literal> methods are blocking until the next + wait state is reached. + </para> + </section> + + <section id="persistentexecutionmode"> + <title>Persistent execution mode</title> + <para>The Process Virtual Machine also contains the hibernate mappings to store the + process definitions and executions in any database. A special session facade called + <literal>ExecutionService</literal> is provided for working with process executions + in such a persistent environment. + </para> + <para>Two configuration files should be available on the classpath: an environment + configuration file and a <literal>hibernate.properties</literal> file. A basic + configuration for persistent execution mode in a standard Java environment looks + like this: + </para> + <literal><emphasis role="bold">environment.cfg.xml</emphasis>:</literal> + <programlisting>&lt;jbpm-configuration xmlns=&quot;http://jbpm.org/xsd/cfg&quot;&gt; + + &lt;process-engine-context&gt; + + &lt;deployer-manager&gt; + &lt;assign-file-type&gt; + &lt;file extension=&quot;.jpdl.xml&quot; type=&quot;jpdl&quot; /&gt; + &lt;/assign-file-type&gt; + &lt;parse-jpdl /&gt; + &lt;check-process /&gt; + &lt;check-problems /&gt; + &lt;save /&gt; + &lt;/deployer-manager&gt; + + &lt;process-service /&gt; + &lt;execution-service /&gt; + &lt;management-service /&gt; + + &lt;command-service&gt; + &lt;retry-interceptor /&gt; + &lt;environment-interceptor /&gt; + &lt;standard-transaction-interceptor /&gt; + &lt;/command-service&gt; + + &lt;hibernate-configuration&gt; + &lt;properties resource=&quot;hibernate.properties&quot; /&gt; + &lt;mapping resource=&quot;jbpm.pvm.typedefs.hbm.xml&quot; /&gt; + &lt;mapping resource=&quot;jbpm.pvm.wire.hbm.xml&quot; /&gt; + &lt;mapping resource=&quot;jbpm.pvm.definition.hbm.xml&quot; /&gt; + &lt;mapping resource=&quot;jbpm.pvm.execution.hbm.xml&quot; /&gt; + &lt;mapping resource=&quot;jbpm.pvm.variable.hbm.xml&quot; /&gt; + &lt;mapping resource=&quot;jbpm.pvm.job.hbm.xml&quot; /&gt; + &lt;mapping resource=&quot;jbpm.jpdl.hbm.xml&quot; /&gt; + &lt;cache-configuration resource=&quot;jbpm.pvm.cache.xml&quot; + usage=&quot;nonstrict-read-write&quot; /&gt; + &lt;/hibernate-configuration&gt; + + &lt;hibernate-session-factory /&gt; + + &lt;id-generator /&gt; + &lt;types resource=&quot;jbpm.pvm.types.xml&quot; /&gt; + &lt;job-executor auto-start=&quot;false&quot; /&gt; + + &lt;/process-engine-context&gt; + + &lt;transaction-context&gt; + &lt;hibernate-session /&gt; + &lt;transaction /&gt; + &lt;pvm-db-session /&gt; + &lt;job-db-session /&gt; + &lt;message-session /&gt; + &lt;/transaction-context&gt; + +&lt;/jbpm-configuration&gt;</programlisting> + <para>And next to it a hibernate.properties like this</para> + <literal>hibernate.properties:</literal> + <programlisting>hibernate.dialect org.hibernate.dialect.HSQLDialect +hibernate.connection.driver_class org.hsqldb.jdbcDriver +hibernate.connection.url jdbc:hsqldb:mem:. +hibernate.connection.username sa +hibernate.connection.password +hibernate.hbm2ddl.auto create-drop +hibernate.cache.use_second_level_cache true +hibernate.cache.provider_class org.hibernate.cache.HashtableCacheProvider +# hibernate.show_sql true +hibernate.format_sql true +hibernate.use_sql_comments true</programlisting> + <para>Then you can obtain the services from the environment factory like this: + </para> + <programlisting>EnvironmentFactory environmentFactory = new PvmEnvironmentFactory(&quot;environment.cfg.xml&quot;); + +ProcessService processService = environmentFactory.get(ProcessService.class); +ExecutionService executionService = environmentFactory.get(ExecutionService.class); +ManagementService managementService = environmentFactory.get(ManagementService.class);</programlisting> + <para>The responsibility of the <literal>ProcessService</literal> is to manage + the repository of process definitions. Before we can start a process execution, + the process definition needs to be deployed into the process repository. + Process definitions can be supplied in various formats and process definition + languages. A deployment collects process definition information from various + sources like a ZIP file, an XML file or a process definition object. + The method <literal>ProcessService.deploy</literal> will take a deployment + through all the deployers that are configured in the configuration file. + </para> + <para>In this example, we'll supply a process definition programmatically + for deployment.</para> + <programlisting>ClientProcessDefinition processDefinition = ProcessFactory.build("loan") + .activity("submit loan request").initial().behaviour(AutomaticActivity.class) + .transition().to("evaluate") + .activity("evaluate").behaviour(WaitState.class) + .transition("approve").to("wire money") + .transition("reject").to("end") + .activity("wire money").behaviour(AutomaticActivity.class) + .transition().to("archive") + .activity("archive").behaviour(WaitState.class) + .transition().to("end") + .activity("end").behaviour(WaitState.class) +.done(); + +Deployment deployment = new Deployment(processDefinition); +processService.deploy(deployment);</programlisting> + <para>Now, a version of that process definition is stored in the database. + The <literal>check-version</literal> deployer will have assigned version 1 + to the stored process definition. The <literal>create-id</literal> deployer + will have distilled id <literal>loan:1</literal> from the process name and the + assigned version. + </para> + <para>Deploying that process again will lead to a new process definition + version being created in the database. But an incremented version number will + be assigned. For the purpose of versioning, process definitions are considered + equal if they have the same name.</para> + <para>It is recommended that a user provided key reference is supplied for + all process executions. Starting a new process execution goes like this: + </para> + <programlisting>Execution execution = executionService.startExecution("loan:1", "request7836");</programlisting> + <para>The return value is an execution interface, which prevents navigation of relations. + That is because outside of the service methods, the transaction and hibernate session + is not guaranteed to still be open. In fact, the default configuration as given + above will only keep the transaction and session open for the duration of the + service method. So navigating the relations outside of the service methods might result + into a hibernate <literal>LazyInitializationException</literal>. But the + current activity name can still be verified: + </para> + <programlisting>assertEquals("evaluate", execution.getActivityName());</programlisting> + <para>Also very important is the generated id that can be obtained. The default + <literal>id-generator</literal> will use the process definition id and the + given key to make a unique id for the process execution like this:</para> + <programlisting>assertEquals("loan:1/request7836", execution.getId());</programlisting> + <para>That id must be when providing the subsequent external triggers to the + process execution like this: + </para> + <programlisting>executionService.signalExecution("loan:1/request7836", "approve");</programlisting> + <para>More information about service interfaces to run in persistent + mode can be found in package + <ulink url="../../api/org/jbpm/pvm/package-summary.html"><literal>org.jbpm.pvm</literal> of the + api docs</ulink>. + </para> + </section> + + <section id="embeddedexecutionmode"> + <title>Embedded execution mode</title> + <para>Embedded execution mode means that the state of a process is stored + as a string column inside a user domain object like e.g. a loan. + </para> + <programlisting>public class Loan { + + <emphasis role="bold">/** the loan process definition as a static resource */ + private static final ClientProcessDefinition processDefinition = createLoanProcess(); + + private static ClientProcessDefinition createLoanProcess() { + ClientProcessDefinition processDefinition = ProcessFactory.build(&quot;loan&quot;) + .activity(&quot;submit loan request&quot;).initial().behaviour(AutomaticActivity.class) + .transition().to(&quot;evaluate&quot;) + .activity(&quot;evaluate&quot;).behaviour(WaitState.class) + .transition(&quot;approve&quot;).to(&quot;wire money&quot;) + .transition(&quot;reject&quot;).to(&quot;end&quot;) + .activity(&quot;wire money&quot;).behaviour(AutomaticActivity.class) + .transition().to(&quot;archive&quot;) + .activity(&quot;archive&quot;).behaviour(WaitState.class) + .transition().to(&quot;end&quot;) + .activity(&quot;end&quot;).behaviour(WaitState.class) + .done(); + + return processDefinition; + } + + /** exposes the process definition to the execution hibernate type */ + private static ClientProcessDefinition getProcessDefinition() { + return processDefinition; + } + </emphasis> + + long dbid; + String customer; + double amount; + <emphasis role="bold">ClientExecution execution;</emphasis> + + /** constructor for persistence */ + protected Loan() { + } + + public Loan(String customer, double amount) { + this.customer = customer; + this.amount = amount; + <emphasis role="bold">this.execution = processDefinition.startProcessInstance();</emphasis> + } + + public void approve() { + <emphasis role="bold">execution.signal(&quot;approve&quot;);</emphasis> + } + + public void reject() { + <emphasis role="bold">execution.signal(&quot;reject&quot;);</emphasis> + } + + public void archiveComplete() { + <emphasis role="bold">execution.signal();</emphasis> + } + + public String getState() { + return <emphasis role="bold">execution.getActivityName()</emphasis>; + } + + ...getters... +}</programlisting> + <para>If you ignore the bold parts for a second, you can see that this is a + POJO without anything fancy. It's just a bean that can be stored with hibernate. + The bold part indicate that implementation part of the class that is related + to process and execution. Not that nothing of the process definition or + execution is exposed to the user of the Loan class. + </para> + <para>Each <literal>Loan</literal> object corresponds to a <literal>loan</literal> + process instance. Some methods of the <literal>Loan</literal> class correspond + to the external triggers that need to be given during the lifecycle of a + <literal>Loan</literal> object. + </para> + <para>Next we'll show how to use this class. To get started we need a</para> + <emphasis role="bold"><literal>hibernate.cfg.xml:</literal></emphasis> + <programlisting>&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt; + +&lt;!DOCTYPE hibernate-configuration PUBLIC + &quot;-//Hibernate/Hibernate Configuration DTD 3.0//EN&quot; + &quot;http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd&quot;&gt; + +&lt;hibernate-configuration&gt; + &lt;session-factory&gt; + + &lt;property name=&quot;hibernate.dialect&quot;&gt;org.hibernate.dialect.HSQLDialect&lt;/property&gt; + &lt;property name=&quot;hibernate.connection.driver_class&quot;&gt;org.hsqldb.jdbcDriver&lt;/property&gt; + &lt;property name=&quot;hibernate.connection.url&quot;&gt;jdbc:hsqldb:mem:.&lt;/property&gt; + &lt;property name=&quot;hibernate.connection.username&quot;&gt;sa&lt;/property&gt; + &lt;property name=&quot;hibernate.connection.password&quot;&gt;&lt;/property&gt; + &lt;property name=&quot;hibernate.hbm2ddl.auto&quot;&gt;create&lt;/property&gt; + &lt;property name=&quot;hibernate.show_sql&quot;&gt;true&quot;&lt;/property&gt; + &lt;property name=&quot;hibernate.format_sql&quot;&gt;true&quot;&lt;/property&gt; + &lt;property name=&quot;hibernate.use_sql_comments&quot;&gt;true&quot;&lt;/property&gt; + + &lt;mapping resource=&quot;Loan.hbm.xml&quot;/&gt; + + &lt;/session-factory&gt; +&lt;/hibernate-configuration&gt;</programlisting> + <para>And a</para> + <emphasis role="bold"><literal>Loan.hbm.xml:</literal></emphasis> + <programlisting>&lt;?xml version=&quot;1.0&quot;?&lt; + +&lt;!DOCTYPE hibernate-mapping PUBLIC + &quot;-//Hibernate/Hibernate Mapping DTD 3.0//EN&quot; + &quot;http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd&quot;&lt; + +&lt;hibernate-mapping package=&quot;org.jbpm.pvm.api.db.embedded&quot; default-access=&quot;field&quot;&lt; + + &lt;typedef name=&quot;execution&quot; class=&quot;org.jbpm.pvm.internal.hibernate.ExecutionType&quot; /&lt; + + &lt;class name=&quot;Loan&quot; table=&quot;LOAN&quot;&lt; + + &lt;id name=&quot;dbid&quot;&lt; + &lt;generator class=&quot;sequence&quot;/&lt; + &lt;/id&lt; + + &lt;property name=&quot;execution&quot; type=&quot;execution&quot; /&lt; + &lt;property name=&quot;customer&quot; /&lt; + &lt;property name=&quot;amount&quot; /&lt; + + &lt;/class&lt; + +&lt;/hibernate-mapping&lt;</programlisting> + <para>Then you can use the Loan class like this in a test</para> + <programlisting>Configuration configuration = new Configuration(); +configuration.configure(); +SessionFactory sessionFactory = configuration.buildSessionFactory(); + +// start a session/transaction +Session session = sessionFactory.openSession(); +Transaction transaction = session.beginTransaction(); + +Loan loan = new Loan("john doe", 234.0); +session.save(loan); +assertEquals("evaluate", loan.getState()); + +// start a new session/transaction +transaction.commit(); +session.close(); +session = sessionFactory.openSession(); +transaction = session.beginTransaction(); + +loan = (Loan) session.get(Loan.class, loan.getDbid()); +assertEquals("evaluate", loan.getState()); +loan.approve(); +assertEquals("archive", loan.getState()); + +// start a new session/transaction +transaction.commit(); +session.close();</programlisting> + <para>After executing this code snippet, this is the loan record in the DB:</para> + <figure id="loan.db"> + <title>The loan record in the DB</title> + <mediaobject><imageobject><imagedata align="center" fileref="images/loan.db.png"/></imageobject></mediaobject> + </figure> + </section> + +</chapter> \ No newline at end of file Modified: jbpm4/trunk/modules/examples/src/test/resources/org/jbpm/examples/subprocess/outcomeactivity/SubProcessDocument.jpdl.xml =================================================================== --- jbpm4/trunk/modules/examples/src/test/resources/org/jbpm/examples/subprocess/outcomeactivity/SubProcessDocument.jpdl.xml 2009-05-04 15:40:57 UTC (rev 4712) +++ jbpm4/trunk/modules/examples/src/test/resources/org/jbpm/examples/subprocess/outcomeactivity/SubProcessDocument.jpdl.xml 2009-05-04 15:44:03 UTC (rev 4713) @@ -2,7 +2,7 @@ <process name="SubProcessDocument" xmlns="http://jbpm.org/4.0/jpdl"> - <start g="20,20,48,48"> + <start g="32,111,48,48"> <transition to="review" /> </start> @@ -10,13 +10,13 @@ sub-process-key="SubProcessReview" g="96,16,127,52"> - <transition name="ok" to="next step" /> - <transition name="nok" to="update" /> - <transition name="reject" to="close" /> + <transition name="ok" to="next step" g="167,67:6,-19"/> + <transition name="nok" to="update" g="-22,-18"/> + <transition name="reject" to="close" g="167,200:7,3"/> </sub-process> - <state name="next step" g="255,16,88,52"/> - <state name="update" g="255,36,88,52"/> - <state name="close" g="255,56,88,52"/> + <state name="next step" g="255,41,88,52"/> + <state name="update" g="256,106,88,52"/> + <state name="close" g="258,175,88,52"/> </process> Modified: jbpm4/trunk/modules/examples/src/test/resources/org/jbpm/examples/subprocess/outcomeactivity/SubProcessReview.jpdl.xml =================================================================== --- jbpm4/trunk/modules/examples/src/test/resources/org/jbpm/examples/subprocess/outcomeactivity/SubProcessReview.jpdl.xml 2009-05-04 15:40:57 UTC (rev 4712) +++ jbpm4/trunk/modules/examples/src/test/resources/org/jbpm/examples/subprocess/outcomeactivity/SubProcessReview.jpdl.xml 2009-05-04 15:44:03 UTC (rev 4713) @@ -2,21 +2,21 @@ <process name="SubProcessReview" xmlns="http://jbpm.org/4.0/jpdl"> - <start g="20,20,48,48"> + <start g="25,101,48,48"> <transition to="get approval"/> </start> <task name="get approval" assignee="johndoe" - g="96,16,127,52"> + g="107,97,127,52"> - <transition name="ok" to="ok"/> - <transition name="nok" to="nok"/> - <transition name="reject" to="reject"/> + <transition name="ok" to="ok" g="171,71:9,-16"/> + <transition name="nok" to="nok" g="-16,-16"/> + <transition name="reject" to="reject" g="170,179:8,3"/> </task> - <end name="ok" g="254,19,88,52" /> - <end name="nok" g="254,19,88,52" /> - <end name="reject" g="254,19,88,52" /> + <end name="ok" g="269,48,88,52" /> + <end name="nok" "270,101,88,52" /> + <end name="reject" g="270,156,88,52"/> -</process> \ No newline at end of file +</process> Modified: jbpm4/trunk/modules/examples/src/test/resources/org/jbpm/examples/subprocess/outcomevalue/SubProcessDocument.jpdl.xml =================================================================== --- jbpm4/trunk/modules/examples/src/test/resources/org/jbpm/examples/subprocess/outcomevalue/SubProcessDocument.jpdl.xml 2009-05-04 15:40:57 UTC (rev 4712) +++ jbpm4/trunk/modules/examples/src/test/resources/org/jbpm/examples/subprocess/outcomevalue/SubProcessDocument.jpdl.xml 2009-05-04 15:44:03 UTC (rev 4713) @@ -2,7 +2,7 @@ <process name="SubProcessDocument" xmlns="http://jbpm.org/4.0/jpdl"> - <start g="20,20,48,48"> + <start g="32,111,48,48"> <transition to="review" /> </start> @@ -11,13 +11,13 @@ outcome="#{result}" g="96,16,127,52"> - <transition name="ok" to="next step" /> - <transition name="nok" to="update" /> - <transition name="reject" to="close" /> + <transition name="ok" to="next step" g="167,67:6,-19"/> + <transition name="nok" to="update" g="-22,-18"/> + <transition name="reject" to="close" g="167,200:7,3"/> </sub-process> - <state name="next step" g="255,16,88,52"/> - <state name="update" g="255,36,88,52"/> - <state name="close" g="255,56,88,52"/> + <state name="next step" g="255,41,88,52"/> + <state name="update" g="256,106,88,52"/> + <state name="close" g="258,175,88,52"/> </process> Added: jbpm4/trunk/modules/userguide/src/main/docbook/en/images/process.subprocess.document.png =================================================================== (Binary files differ) Property changes on: jbpm4/trunk/modules/userguide/src/main/docbook/en/images/process.subprocess.document.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Copied: jbpm4/trunk/modules/userguide/src/main/docbook/en/images/process.subprocess.review.png (from rev 4705, jbpm4/trunk/modules/userguide/src/main/docbook/en/images/process.subprocess.variables.review.png) =================================================================== (Binary files differ) Property changes on: jbpm4/trunk/modules/userguide/src/main/docbook/en/images/process.subprocess.review.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Deleted: jbpm4/trunk/modules/userguide/src/main/docbook/en/images/process.subprocess.variables.review.png =================================================================== (Binary files differ) Modified: jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch05-Jpdl.xml =================================================================== --- jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch05-Jpdl.xml 2009-05-04 15:40:57 UTC (rev 4712) +++ jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch05-Jpdl.xml 2009-05-04 15:44:03 UTC (rev 4713) @@ -1250,7 +1250,7 @@ <para>The parent process involves a document that needs to be reviewed.</para> <figure id="process.subprocess.variables.document"> <title>The subprocess document example process</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/process.subprocess.variables.document.png"/></imageobject></mediaobject> + <mediaobject><imageobject><imagedata align="center" fileref="images/process.task.png"/></imageobject></mediaobject> </figure> <programlisting>&lt;process name=&quot;SubProcessDocument&quot; xmlns=&quot;http://jbpm.org/4.0/jpdl&quot;&gt; @@ -1273,7 +1273,7 @@ <para>The review process is a reusable process for all kinds of reviews.</para> <figure id="process.subprocess.variables.review"> <title>The subprocess review example process</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/process.subprocess.variables.review.png"/></imageobject></mediaobject> + <mediaobject><imageobject><imagedata align="center" fileref="images/process.subprocess.review.png"/></imageobject></mediaobject> </figure> <programlisting>&lt;process name=&quot;SubProcessReview&quot; xmlns=&quot;http://jbpm.org/4.0/jpdl&quot;&gt; @@ -1333,7 +1333,7 @@ </para> <figure id="process.subprocess.outcomevalue.document"> <title>The subprocess document example process</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/process.subprocess.outcomevalue.document.png"/></imageobject></mediaobject> + <mediaobject><imageobject><imagedata align="center" fileref="images/process.subprocess.document.png"/></imageobject></mediaobject> </figure> <programlisting>&lt;process name=&quot;SubProcessDocument&quot;&gt; @@ -1359,7 +1359,7 @@ <link linkend="subprocessvariables">subprocess variables example</link>:</para> <figure id="process.subprocess.outcomevalue.review"> <title>The subprocess review example process for outcome value</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/process.subprocess.variables.review.png"/></imageobject></mediaobject> + <mediaobject><imageobject><imagedata align="center" fileref="images/process.subprocess.review.png"/></imageobject></mediaobject> </figure> <programlisting>&lt;process name=&quot;SubProcessReview&quot; xmlns=&quot;http://jbpm.org/4.0/jpdl&quot;&gt; @@ -1405,7 +1405,7 @@ </para> <figure id="process.subprocess.outcomeactivity.document"> <title>The subprocess document example process for outcome activity</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/process.subprocess.outcomevalue.document.png"/></imageobject></mediaobject> + <mediaobject><imageobject><imagedata align="center" fileref="images/process.subprocess.document.png"/></imageobject></mediaobject> </figure> <programlisting>&lt;process name=&quot;SubProcessDocument&quot;&gt;