[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 | <jbpm-configuration>
-02 |
-03 | <process-engine>
-04 |<emphasis role="bold"> <hibernate-session-factory /></emphasis>
-05 |<emphasis role="bold"> <hibernate-configuration></emphasis>
-06 |<emphasis role="bold"> <properties resource="hibernate.properties" /></emphasis>
-07 |<emphasis role="bold"> <mapping resource="jbpm.pvm.typedefs.hbm.xml" /></emphasis>
-08 |<emphasis role="bold"> <mapping resource="jbpm.pvm.wire.hbm.xml" /></emphasis>
-09 |<emphasis role="bold"> <mapping resource="jbpm.pvm.definition.hbm.xml" /></emphasis>
-10 |<emphasis role="bold"> <mapping resource="jbpm.pvm.execution.hbm.xml" /></emphasis>
-11 |<emphasis role="bold"> <mapping resource="jbpm.pvm.variable.hbm.xml" /></emphasis>
-12 |<emphasis role="bold"> <mapping resource="jbpm.pvm.job.hbm.xml" /></emphasis>
-13 |<emphasis role="bold"> <mapping resource="jbpm.jpdl.hbm.xml" /></emphasis>
-14 |<emphasis role="bold"> <cache-configuration resource="jbpm.pvm.cache.xml"</emphasis>
-15 |<emphasis role="bold"> usage="nonstrict-read-write" /></emphasis>
-16 |<emphasis role="bold"> </hibernate-configuration></emphasis>
-17 | </process-engine>
-18 |
-19 | <transaction-context>
-20 |<emphasis role="bold"> <standard-transaction /></emphasis>
-21 |<emphasis role="bold"> <hibernate-session /></emphasis>
-22 |<emphasis role="bold"> <pvm-db-session /></emphasis>
-23 | </transaction-context>
-24 |
-25 | </jbpm-configuration></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><hibernate-session /></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><standard-transaction /></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><hibernate-configuration>
- <properties resource="hibernate.properties" />
- <mapping resource="jbpm.pvm.typedefs.hbm.xml" />
- <mapping resource="jbpm.pvm.wire.hbm.xml" />
- <mapping resource="jbpm.pvm.definition.hbm.xml" />
- <mapping resource="jbpm.pvm.execution.hbm.xml" />
- <mapping resource="jbpm.pvm.variable.hbm.xml" />
- <mapping resource="jbpm.pvm.job.hbm.xml" />
- <mapping resource="jbpm.jpdl.hbm.xml" />
- <emphasis role="bold"><mapping resource="org/jbpm/examples/ch09/state.hbm.xml" /></emphasis>
- <cache-configuration resource="jbpm.pvm.cache.xml"
- usage="nonstrict-read-write" />
-</hibernate-configuration></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