[jbpm-commits] JBoss JBPM SVN: r2144 - in jbpm4/pvm/trunk: modules/manual and 4 other directories.

Author: tom.baeyens(a)jboss.com Date: 2008-09-08 12:05:24 -0400 (Mon, 08 Sep 2008) New Revision: 2144 Added: jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/images/apis.png jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch03-Environments.xml jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch04-Services.xml Removed: jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch10-Services.xml Modified: jbpm4/pvm/trunk/build.xml jbpm4/pvm/trunk/modules/manual/pom.xml jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/master.xml jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch01-Introduction.xml jbpm4/pvm/trunk/modules/manual/src/main/docbook/images.ppt Log: docs update Modified: jbpm4/pvm/trunk/build.xml =================================================================== --- jbpm4/pvm/trunk/build.xml 2008-09-08 15:17:21 UTC (rev 2143) +++ jbpm4/pvm/trunk/build.xml 2008-09-08 16:05:24 UTC (rev 2144) @@ -61,12 +61,12 @@ </antcall> </target> - <target name="reference"> - <exec executable="cmd" dir="modules/core"> - <arg line="/C mvn docbkx:generate-html" /> + <target name="manual"> + <exec executable="cmd" dir="modules/manual"> + <arg line="/C mvn jdocbook:resources jdocbook:generate" /> </exec> <antcall target="show.html"> - <param name="page" value="modules/core/target/site/apidocs/index.html"/> + <param name="page" value="modules/manual/target/docbook/publish/en/html_single/index.html"/> </antcall> </target> Modified: jbpm4/pvm/trunk/modules/manual/pom.xml =================================================================== --- jbpm4/pvm/trunk/modules/manual/pom.xml 2008-09-08 15:17:21 UTC (rev 2143) +++ jbpm4/pvm/trunk/modules/manual/pom.xml 2008-09-08 16:05:24 UTC (rev 2144) @@ -32,6 +32,7 @@ <build> <plugins> +<!-- <plugin> <groupId>com.agilejava.docbkx</groupId> <artifactId>docbkx-maven-plugin</artifactId> @@ -56,7 +57,7 @@ </postProcess> </configuration> </execution> - <!-- + <execution> <id>doc-reference chunk html</id> <goals> @@ -91,7 +92,7 @@ <imgSrcPath>${basedir}/src/docbook/doc-reference/en/</imgSrcPath> </configuration> </execution> - --> + </executions> <dependencies> <dependency> @@ -102,39 +103,45 @@ </dependency> </dependencies> </plugin> +--> -<!-- <plugin> <groupId>org.jboss.maven.plugins</groupId> <artifactId>maven-jdocbook-plugin</artifactId> <extensions>true</extensions> - <executions> - <execution> - <phase>package</phase> - <goals> - <goal>generate</goal> - <goal>bundle</goal> - </goals> - <configuration> - <sourceDocumentName>en/master.xml</sourceDocumentName> - <formats> - <format> - <formatName>html_single</formatName> - </format> - </formats> - </configuration> - </execution> - </executions> + + <dependencies> + <dependency> + <groupId>org.jboss</groupId> + <artifactId>jbossorg-docbook-xslt</artifactId> + <version>1.1.0</version> + </dependency> + <dependency> + <groupId>org.jboss</groupId> + <artifactId>jbossorg-jdocbook-style</artifactId> + <version>1.1.0</version> + <type>jdocbook-style</type> + </dependency> + </dependencies> + <configuration> - <sourceDocumentName>en/master.xml</sourceDocumentName> + <sourceDocumentName>master.xml</sourceDocumentName> + <masterTranslation>en</masterTranslation> + <imageResource> + <directory>src/main/docbook/en</directory> + <includes> + <include>images/*.png</include> + </includes> + </imageResource> <formats> <format> <formatName>html_single</formatName> + <stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource> + <finalName>index.html</finalName> </format> </formats> </configuration> </plugin> ---> </plugins> </build> Added: jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/images/apis.png =================================================================== (Binary files differ) Property changes on: jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/images/apis.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Modified: jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/master.xml =================================================================== --- jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/master.xml 2008-09-08 15:17:21 UTC (rev 2143) +++ jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/master.xml 2008-09-08 16:05:24 UTC (rev 2144) @@ -3,15 +3,16 @@ <!DOCTYPE book [ <!ENTITY ch01-Introduction SYSTEM "modules/ch01-Introduction.xml"> <!ENTITY ch02-SoftwareLogging SYSTEM "modules/ch02-SoftwareLogging.xml"> - <!ENTITY ch03-BasicGraphExecution SYSTEM "modules/ch03-BasicGraphExecution.xml"> + <!ENTITY ch03-Environments SYSTEM "modules/ch03-Environments.xml"> + <!ENTITY ch04-Services SYSTEM "modules/ch04-Services.xml"> + <!ENTITY ch03-BasicGraphExecution SYSTEM "modules/ch03-BasicGraphExecution.xml"> <!ENTITY ch04-AdvancedGraphExecution SYSTEM "modules/ch04-AdvancedGraphExecution.xml"> <!ENTITY ch05-DelegationClasses SYSTEM "modules/ch05-DelegationClasses.xml"> <!ENTITY ch06-Variables SYSTEM "modules/ch06-Variables.xml"> <!ENTITY ch07-History SYSTEM "modules/ch07-History.xml"> <!ENTITY ch08-Environment SYSTEM "modules/ch08-Environment.xml"> <!ENTITY ch09-Persistence SYSTEM "modules/ch09-Persistence.xml"> - <!ENTITY ch10-Services SYSTEM "modules/ch10-Services.xml"> <!ENTITY ch11-AsynchronousContinuations SYSTEM "modules/ch11-AsynchronousContinuations.xml"> <!ENTITY ch12-Timers SYSTEM "modules/ch12-Timers.xml"> <!ENTITY ch13-ProcessLanguages SYSTEM "modules/ch13-ProcessLanguages.xml"> @@ -30,17 +31,7 @@ &ch01-Introduction; &ch02-SoftwareLogging; - &ch03-BasicGraphExecution; + &ch03-Environments; + &ch04-Services; - &ch04-AdvancedGraphExecution; - &ch05-DelegationClasses; - &ch06-Variables; - &ch07-History; - &ch08-Environment; - &ch09-Persistence; - &ch10-Services; - &ch11-AsynchronousContinuations; - &ch12-Timers; - &ch13-ProcessLanguages; - </book> \ No newline at end of file Modified: jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch01-Introduction.xml =================================================================== --- jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch01-Introduction.xml 2008-09-08 15:17:21 UTC (rev 2143) +++ jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch01-Introduction.xml 2008-09-08 16:05:24 UTC (rev 2144) @@ -2,13 +2,6 @@ <title>Introduction</title> <section> - <title>Scope and target audience</title> - <para>This is the reference manual that explains all the concepts of the Process Virtual Machine. - If you're looking for an introduction, check out the tutorial first. - </para> - </section> - - <section> <title>JVM version</title> <para>jbpm-pvm.jar requires a JVM version 5 or higher. </para> @@ -25,17 +18,25 @@ <section> <title>What is it</title> - <para>In essence, the process virtual machine is a framework specifying executable + <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 - . Many executions can be - started for one process definition. Typically, process definitions are static. A - process definition is composed of nodes and transitions. The runtime behaviour - of a node is encapsulated in a so called Activity and it's decoupled from the process - graph structure. + be represented graphically as a diagram. Many executions can be + started for one process definition. + </para> + <figure id="example.process.graph"> + <title>Example process definition</title> + <mediaobject><imageobject><imagedata align="center" fileref="images/first.graph.process.png"/></imageobject></mediaobject> + </figure> + <para>Typically, process definitions are static. A process definition is composed of + nodes and transitions. The runtime behaviour of a node is encapsulated in a so called + Activity and it's decoupled from the process graph structure. The Process Virtual + Machine doesn't contain any such activity implementations. It only provides the + execution environment and a set of basic operations such as taking a transition. + It also gives the user a simple way of implementing the process + constructs as concrete <literal>Activity</literal> implementations. </para> <figure id="class.diagram.process.definition"> - <title>Process definition structure in UML class diagram</title> + <title>Process structure class diagram</title> <mediaobject><imageobject><imagedata align="center" fileref="images/class.diagram.process.definition.png"/></imageobject></mediaobject> </figure> <para>Activities can also be wait states. This means that the node control flow goes @@ -43,7 +44,7 @@ </para> <para>An execution is a pointer that keeps track of the current node. To represent concurrent paths of execution, there is a hierarchical parent-child relation between - so that one process instance can correspond with a tree of executions. + so that one process instance can cope with concurrent paths of execution. </para> <figure id="class.diagram.process.execution"> <title>Process structure class diagram</title> @@ -83,4 +84,30 @@ </para> </section> + <section> + <title>APIs</title> + <para>The Process Virtual Machine has 4 integrated API's that together offer a complete coverage + of working with processes. + </para> + <figure id="apis"> + <title>The 4 API's of the Process Virtual Machine</title> + <mediaobject><imageobject><imagedata align="center" fileref="images/apis.png"/></imageobject></mediaobject> + </figure> + <para>The services interfaces should be used from application code that wants to interact + with the Process Virtual Machine which runs in transactional persistent mode, backed by a + database. This is the most typical way how users interact with the PVM as a workflow engine. + </para> + <para>To execute processes without persistence, the client API can be used to work with process + and execution objects directly. The client API expose the methods of the core model objects. + </para> + <para>The activity API is used to implement the runtime behaviour of activities. So a activity + type is in fact a component with at the core an implementation of the <literal>Activity</literal> + interface. Activity implementations can control the flow of execution. + </para> + <para>The event listener API serves to write pieces of Java code that should be executed upon + process events. It's very similar to the activity API with that exception that event listeners + are not able to control the flow of execution. + </para> + </section> + </chapter> Added: jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch03-Environments.xml =================================================================== --- jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch03-Environments.xml (rev 0) +++ jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch03-Environments.xml 2008-09-08 16:05:24 UTC (rev 2144) @@ -0,0 +1,7 @@ +<chapter id="environments"> + <title>Environments</title> + + <para> + </para> + +</chapter> \ No newline at end of file Copied: jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch04-Services.xml (from rev 2138, jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch10-Services.xml) =================================================================== --- jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch04-Services.xml (rev 0) +++ jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch04-Services.xml 2008-09-08 16:05:24 UTC (rev 2144) @@ -0,0 +1,82 @@ +<chapter id="services"> + <title>Services</title> + + <para>Services can be fetched from the EnvironmentFactory, which in it's turn + can be created from a configuration file. + </para> + + <programlisting>EnvironmentFactory environmentFactory = new PvmEnvironmentFactory("pvm.cfg.xml"); +ProcessService processService = environmentFactory.get(ProcessService.class);</programlisting> + + <para>Services are thread safe so only 1 single service object should be maintained + by the application and it can serve all requests for the application. + </para> + + + + <section id="architecture"> + <title>Architecture</title> + <para>Service methods are implemented through command classes. + Each method creates a command object and the command is executed with + the <literal>execute</literal> method of the <literal>CommandService</literal>. + The <literal>CommandService</literal> is responsible for setting up the + environment. + </para> + <para>There are four command services: + </para> + <itemizedlist> + <listitem><literal>command-service</literal> will just + execute the command and pass in the current environment.</listitem> + <listitem>(UNTESTED) <literal>async-command-service</literal> will send an + asynchronous message. So right after that in a separate transaction, + the message is consumed and the command is executed.</listitem> + <listitem>(TODO) <literal>cmt-command-service</literal> will delegate + execution of the command to a local SLSB that has transaction attribute + <literal>required</literal>.</listitem> + <listitem>(TODO) <literal>remote-command-service</literal> will delegate + execution of the command to a remote SLSB.</listitem> + </itemizedlist> + <para>Each of the command services can be configured with a list of + interceptors that span around the command execution. Following + interceptors are available:</para> + <itemizedlist> + <listitem><literal>environment-interceptor</literal>: Will execute the + command within an <link linkend="environmentblock">environment block</link>. + </listitem> + <listitem>(UNTESTED) <literal>authorization-interceptor</literal>: Will perform + an authrorization check before the command is executed. The + authorization interceptor will look up the AuthorizationSession + from the environment to delegate the actual authorization check to. + </listitem> + <listitem><literal>retry-interceptor</literal>: Will catch hibernate's + optmistic locking exceptions (StaleStateException) and retries + to execute the command for a configurable number of times + </listitem> + <listitem><literal>transaction-interceptor</literal>: Will get + the transaction from the current context and invoke + setRollbackOnly() on it in case an exception comes out of + the command execution. + </listitem> + </itemizedlist> + <para>Following configuration can be used in default standard persistence + situations: + </para> + <programlisting>&lt;contexts&gt; + &lt;environment-factory&gt; + + &lt;pvm-service /&gt; + + &lt;command-service&gt; + &lt;retry-interceptor /&gt; + &lt;environment-interceptor /&gt; + &lt;transaction-interceptor /&gt; + &lt;/command-service&gt; + + ... + &lt;/environment-factory&gt; + ... + +&lt;/contexts&gt;</programlisting> + </section> + +</chapter> \ No newline at end of file Property changes on: jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch04-Services.xml ___________________________________________________________________ Name: svn:keywords + Id Revision Name: svn:mergeinfo + Name: svn:eol-style + LF Deleted: jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch10-Services.xml =================================================================== --- jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch10-Services.xml 2008-09-08 15:17:21 UTC (rev 2143) +++ jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch10-Services.xml 2008-09-08 16:05:24 UTC (rev 2144) @@ -1,86 +0,0 @@ -<chapter id="services"> - <title>Services</title> - - <section> - <title>Introduction</title> - <para>All session facades are called services in the PVM and it's related projects. - A service is the front door of the API. It has a number of methods that - expose the functionality of the component. The service takes care of getting - or setting up an <link linkend="environmentblock">environment</link> for each operation - that is invoked. - </para> - </section> - - <section id="pvmservice"> - <title>PvmService</title> - <para>The class org.jbpm.PvmService is the main way to access functionality from the - PVM. - </para> - </section> - - <section id="architecture"> - <title>Architecture</title> - <para>Service methods are implemented through command classes. - Each method creates a command object and the command is executed with - the <literal>execute</literal> method of the <literal>CommandService</literal>. - The <literal>CommandService</literal> is responsible for setting up the - environment. - </para> - <para>There are four command services: - </para> - <itemizedlist> - <listitem><literal>command-service</literal> will just - execute the command and pass in the current environment.</listitem> - <listitem>(UNTESTED) <literal>async-command-service</literal> will send an - asynchronous message. So right after that in a separate transaction, - the message is consumed and the command is executed.</listitem> - <listitem>(TODO) <literal>cmt-command-service</literal> will delegate - execution of the command to a local SLSB that has transaction attribute - <literal>required</literal>.</listitem> - <listitem>(TODO) <literal>remote-command-service</literal> will delegate - execution of the command to a remote SLSB.</listitem> - </itemizedlist> - <para>Each of the command services can be configured with a list of - interceptors that span around the command execution. Following - interceptors are available:</para> - <itemizedlist> - <listitem><literal>environment-interceptor</literal>: Will execute the - command within an <link linkend="environmentblock">environment block</link>. - </listitem> - <listitem>(UNTESTED) <literal>authorization-interceptor</literal>: Will perform - an authrorization check before the command is executed. The - authorization interceptor will look up the AuthorizationSession - from the environment to delegate the actual authorization check to. - </listitem> - <listitem><literal>retry-interceptor</literal>: Will catch hibernate's - optmistic locking exceptions (StaleStateException) and retries - to execute the command for a configurable number of times - </listitem> - <listitem><literal>transaction-interceptor</literal>: Will get - the transaction from the current context and invoke - setRollbackOnly() on it in case an exception comes out of - the command execution. - </listitem> - </itemizedlist> - <para>Following configuration can be used in default standard persistence - situations: - </para> - <programlisting>&lt;contexts&gt; - &lt;environment-factory&gt; - - &lt;pvm-service /&gt; - - &lt;command-service&gt; - &lt;retry-interceptor /&gt; - &lt;environment-interceptor /&gt; - &lt;transaction-interceptor /&gt; - &lt;/command-service&gt; - - ... - &lt;/environment-factory&gt; - ... - -&lt;/contexts&gt;</programlisting> - </section> - -</chapter> \ No newline at end of file Modified: jbpm4/pvm/trunk/modules/manual/src/main/docbook/images.ppt =================================================================== (Binary files differ)