[jbpm-commits] JBoss JBPM SVN: r4713 - in jbpm4/trunk/modules: devguide/src/main/docbook/en/modules and 4 other directories.

do-not-reply at jboss.org do-not-reply at jboss.org
Mon May 4 11:44:03 EDT 2009


Author: tom.baeyens at 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://anonsvn.jboss.org/repos/jbpm/jbpm4/</ulink>
     </para>
-    <ulink url="https://anonsvn.jboss.org/repos/jbpm/jbpm4/pvm/">https://anonsvn.jboss.org/repos/jbpm/jbpm4/pvm/</ulink>
+    <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://www.jboss.org/community/docs/DOC-12867</ulink>
   </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/">http://repository.jboss.com/maven2/org/jbpm/jbpm4/</ulink>
     </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;
 




More information about the jbpm-commits mailing list