[jbpm-commits] JBoss JBPM SVN: r4805 - jbpm4/trunk/modules/devguide/src/main/docbook/en/modules.

do-not-reply at jboss.org do-not-reply at jboss.org
Wed May 13 03:36:19 EDT 2009


Author: tom.baeyens at jboss.com
Date: 2009-05-13 03:36:19 -0400 (Wed, 13 May 2009)
New Revision: 4805

Added:
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch08-Persistence.xml
Removed:
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/chxx-Persistence.xml
Log:
added note in the dev guide that we might switch from hibernate to jpa in the future

Copied: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch08-Persistence.xml (from rev 4789, jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/chxx-Persistence.xml)
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch08-Persistence.xml	                        (rev 0)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch08-Persistence.xml	2009-05-13 07:36:19 UTC (rev 4805)
@@ -0,0 +1,15 @@
+<chapter id="persistence">
+  <title>Persistence</title>
+
+  <para>Currently jBPM's persistence is based on hibernate.  But in the future we might 
+  switch to JPA.  That is why we recommend to stick with the API as much as possible as 
+  the API will hide you from those changes.
+  </para>
+
+  <para>TODO: leveraging the db for managing concurrent access
+  </para>
+  <para>TODO: hibernate-session and the standard transaction
+  </para>
+  <para>TODO: process definition caching
+  </para>
+</chapter>
\ No newline at end of file

Deleted: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/chxx-Persistence.xml
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/chxx-Persistence.xml	2009-05-12 21:02:20 UTC (rev 4804)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/chxx-Persistence.xml	2009-05-13 07:36:19 UTC (rev 4805)
@@ -1,267 +0,0 @@
-<chapter id="persistence">
-  <title>Persistence</title>
-  
-  <section>
-    <title>Standard environment configuration</title>
-	  <para>This section describes how the environment can be configured to use 
-	  hibernate in a standard Java environment.
-	  </para>
-	  <programlisting>01 | &lt;jbpm-configuration&gt;
-02 | 
-03 |   &lt;process-engine&gt;
-04 |<emphasis role="bold">     &lt;hibernate-session-factory /&gt;</emphasis>
-05 |<emphasis role="bold">     &lt;hibernate-configuration&gt;</emphasis>
-06 |<emphasis role="bold">       &lt;properties resource=&quot;hibernate.properties&quot; /&gt;</emphasis>
-07 |<emphasis role="bold">       &lt;mapping resource=&quot;jbpm.pvm.typedefs.hbm.xml&quot; /&gt;</emphasis>
-08 |<emphasis role="bold">       &lt;mapping resource=&quot;jbpm.pvm.wire.hbm.xml&quot; /&gt;</emphasis>
-09 |<emphasis role="bold">       &lt;mapping resource=&quot;jbpm.pvm.definition.hbm.xml&quot; /&gt;</emphasis>
-10 |<emphasis role="bold">       &lt;mapping resource=&quot;jbpm.pvm.execution.hbm.xml&quot; /&gt;</emphasis>
-11 |<emphasis role="bold">       &lt;mapping resource=&quot;jbpm.pvm.variable.hbm.xml&quot; /&gt;</emphasis>
-12 |<emphasis role="bold">       &lt;mapping resource=&quot;jbpm.pvm.job.hbm.xml&quot; /&gt;</emphasis>
-13 |<emphasis role="bold">       &lt;mapping resource=&quot;jbpm.jpdl.hbm.xml&quot; /&gt;</emphasis>
-14 |<emphasis role="bold">       &lt;cache-configuration resource=&quot;jbpm.pvm.cache.xml&quot;</emphasis> 
-15 |<emphasis role="bold">                           usage=&quot;nonstrict-read-write&quot; /&gt;</emphasis>
-16 |<emphasis role="bold">     &lt;/hibernate-configuration&gt;</emphasis>
-17 |   &lt;/process-engine&gt;
-18 |
-19 |   &lt;transaction-context&gt;
-20 |<emphasis role="bold">     &lt;standard-transaction /&gt;</emphasis>
-21 |<emphasis role="bold">     &lt;hibernate-session /&gt;</emphasis>
-22 |<emphasis role="bold">     &lt;pvm-db-session /&gt;</emphasis>
-23 |   &lt;/transaction-context&gt;
-24 |
-25 | &lt;/jbpm-configuration&gt;</programlisting>
-    <para><literal>line 04</literal> specifies a hibernate session factory in the 
-    process-engine context.  This means that a hibernate session factory is lazy 
-    created when it is first needed and cached in the 
-    <literal>EnvironmentFactory</literal>.
-    </para>
-    <para>A hibernate session factory is build calling the 
-    method <literal>buildSessionFactory()</literal> on a hibernate configuration.
-    By default, the hibernate configuration will be looked up by type.
-    </para>
-    <para><literal>line 05</literal> specifies a hibernate configuration.  
-    </para>
-    <para><literal>line 06</literal> specifies the that the resource file 
-    <literal>hibernate.properties</literal> should be loaded into the configuration. 
-    </para>
-    <para><literal>line 07 - 13</literal> specifies the mapping resources files.
-    </para>
-    <para><literal>line 14 - 15</literal> provide a single place to specify the 
-    hibernate caching strategy for all the PVM classes and collections.  
-    </para>
-    <para><literal>line 20</literal> specifies a standard transaction.  This is 
-    a very simple global transaction strategy without recovery that can be used 
-    in standard environments to get all-or-nothing semantics over multiple 
-    transactional resources.  
-    </para>
-    <para><literal>line 21</literal> specifies the hibernate session that will 
-    automatically register itself with the standard transaction.  
-    </para>
-    <para><literal>line 22</literal> specifies a <literal>PvmDbSession</literal>.
-    That is a class that adds methods that bind to specific queries to be executed
-    on the hibernate session.
-    </para>
-  </section>
-
-  <section>
-    <title>Standard hibernate configuration</title>
-    <para>Here is a set of default properties to configure hibernate with 
-    hsqldb in a standard Java environment.
-    </para>
-    <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.cache.use_second_level_cache true
-hibernate.cache.provider_class         org.hibernate.cache.HashtableCacheProvider</programlisting>
-    <para>Optionally in development the schema export can be used to 
-    create the schema when the session factory is created and drop the 
-    schema when the session factory is closed.
-    </para>
-    <programlisting>hibernate.hbm2ddl.auto                 create-drop</programlisting>
-    <para>For more information about hibernate configurations, see the hibernate 
-    reference manual.
-    </para>
-  </section>
-
-  <section>
-    <title>Standard transaction</title>
-    <para>By default, the <literal>&lt;hibernate-session /&gt;</literal> will
-    start a hibernate transaction with <literal>session.beginTransaction()</literal>.
-    Then the hibernate transaction is wrapped in a <literal>org.jbpm.pvm.internal.hibernate.HibernateTransactionResource</literal>
-    and that resource is enlisted with the <literal>&lt;standard-transaction /&gt;</literal> 
-    (<literal>org.jbpm.tx.StandardTransaction</literal>)
-    </para>
-    <para>Inside of the environment block, the transaction is available
-    through <literal>environment.getTransaction()</literal>.  So inside an 
-    environment block, the transaction can be rolled back with 
-    <literal>environment.getTransaction().setRollbackOnly()</literal> 
-    </para>
-    <para>When created, the standard transaction will register itself to be notified on the 
-    close of the environment.  So in side the close, the standard transaction will 
-    commit or rollback depending on whether <literal>setRollbackOnly()</literal> 
-    was called.
-    </para>
-    <para>So in the configuration shown above, each environment block will be 
-    a separate transaction.  At least, if the hibernate session is used.</para>
-  </section>
-
-  <section>
-    <title>Basics of process persistence</title>
-    <para>In the next example, we'll show how this hibernate persistence is 
-    used with a concrete example.  The 'persistent process' is a simple 
-    three-step process: 
-    </para>
-    <figure id="the.persistent.process">
-      <title>The persistent process</title>
-      <mediaobject><imageobject><imagedata align="center" fileref="images/ch09.persistent.process.png"/></imageobject></mediaobject>
-    </figure>
-    <para>The activities in the three activities will be wait states just like 
-    in <xref linkend="externalactivityexample" /> 
-    </para>
-    <para>To make sure we can persist this class, we create the hibernate mapping for 
-    it and add it to the configuration like this:
-    </para>
-    <programlisting>&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;
-  <emphasis role="bold">&lt;mapping resource="org/jbpm/examples/ch09/state.hbm.xml" /&gt;</emphasis>
-  &lt;cache-configuration resource=&quot;jbpm.pvm.cache.xml&quot; 
-                       usage=&quot;nonstrict-read-write&quot; /&gt;
-&lt;/hibernate-configuration&gt;</programlisting>
-    <para>The next code pieces show the contents of one unit test method.  The method 
-    will first create the environment factory. Then, in a first transaction, a process 
-    definition will be created and saved into the database.  Then the next transaction will 
-    create a new execution of that process.  And the following two transactions will 
-    provide external triggers to the execution.
-    </para>
-    <programlisting>EnvironmentFactory environmentFactory = EnvironmentFactory.parse(new ResourceStreamSource(
-    "org/jbpm/examples/ch09/environment.cfg.xml"
-));</programlisting>
-    <para>Then in a first transaction, a process is created and saved in the database.
-    This is typically referred to as deploying a process and it only needs to be done 
-    once.
-    </para>
-    <programlisting>Environment environment = environmentFactory.openEnvironment();
-try {
-  PvmDbSession pvmDbSession = environment.get(PvmDbSession.class);
-  
-  ProcessDefinition processDefinition = ProcessFactory.build("persisted process")
-    .activity("one").initial().behaviour(new State())
-      .transition().to("two")
-    .activity("two").behaviour(new State())
-      .transition().to("three")
-    .activity("three").behaviour(new State())
-  .done();
-  
-  pvmDbSession.save(processDefinition);
-} finally {
-  environment.close();
-}</programlisting>
-    <para>In the previous transaction, the process definition, the activities and transitions 
-    will be inserted into the database tables.
-    </para>
-    <para>Next we'll show how a new process execution can be started for this 
-    process definition.  Note that in this case, we provide <link linkend="businesskey">a 
-    business key</link> called 'first'.  This will make it easy for us to retrieve 
-    the same execution from the database in subsequent transactions.  After starting 
-    the new process execution, it will wait in activity 'one' cause the behaviour is a 
-    wait state.
-    </para>
-    <programlisting>environment = environmentFactory.openEnvironment();
-try {
-  PvmDbSession pvmDbSession = environment.get(PvmDbSession.class);
-  
-  ProcessDefinition processDefinition = pvmDbSession.findProcessDefinition("persisted process");
-  assertNotNull(processDefinition);
-  
-  Execution execution = processDefinition.startExecution("first");
-  assertEquals("one", execution.getActivity().getName());
-  pvmDbSession.save(execution);
-
-} finally {
-  environment.close();
-}</programlisting>
-    <para>In the previous transaction, a new execution record will be inserted into 
-    the database.
-    </para>
-    <para>Next we feed in an external trigger into this existing process execution.
-    We load the execution, provide a signal and just save it back into the database.
-    </para>
-    <programlisting>environment = environmentFactory.openEnvironment();
-try {
-  PvmDbSession pvmDbSession = environment.get(PvmDbSession.class);
-  
-  Execution execution = pvmDbSession.findExecution("persisted process", "first");
-  assertNotNull(execution);
-  assertEquals("one", execution.getActivity().getName());
-  
-  // external trigger that will cause the execution to execute until 
-  // it reaches the next wait state
-  execution.signal();
-
-  assertEquals("two", execution.getActivity().getName());
-
-  pvmDbSession.save(execution);
-
-} finally {
-  environment.close();
-}</programlisting>
-    <para>The previous transaction will result in an update of the existing 
-    execution, reassigning the foreign key to reference another record in 
-    the activity table.
-    </para>
-    <programlisting>UPDATE JBPM_EXECUTION 
-SET
-  NODE_=?,
-  DBVERSION_=?,
-  ...
-WHERE DBID_=? 
-  AND DBVERSION_=?</programlisting>
-    <para>The version in this SQL shows the automatic optimistic locking that 
-    is baked into the PVM persistence so that process persistence can easily 
-    scale to multiple JVM's or multiple machines.
-    </para>
-    <para>In the example code, there is one more transaction that is 
-    completely similar to the previous which takes the execution from 
-    activity 'two' to activity 'three'. 
-    </para>
-    <para>All of this shows that the PVM can move from one wait state to 
-    another wait state transactionally.  Each transaction correcponds to 
-    a state transition.
-    </para>
-    <para>Note that in case of automatic activities, multiple activities 
-    will be executed before the execution reaches a wait state.  Typically 
-    that is desired behaviour.  In case the automatic activities take too 
-    long or you don't want to block the original transaction to wait for 
-    the completion of those automatic activities, check out <xref linkend="asynchronouscontinuations"/>
-    to learn about how it's possible to demarcate transactions in the process 
-    definition, which can also be seen as safe-points during process execution.
-    </para>
-  </section>
-
-  <section id="businesskey">
-    <title>Business key</title>
-    <para>TODO</para>
-  </section>
-    	  
-	  
-  <para>TODO: General persistence architecture
-  </para>
-  <para>TODO: Object references
-  </para>
-  <para>TODO: Threads, concurrency with respect to forks and joins
-  </para>
-  <para>TODO: Caching
-  </para>
-  <para>TODO: Process instance migration
-  </para>
-</chapter>
\ No newline at end of file




More information about the jbpm-commits mailing list