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

do-not-reply at jboss.org do-not-reply at jboss.org
Wed Oct 28 08:48:41 EDT 2009


Author: jbarrez
Date: 2009-10-28 08:48:41 -0400 (Wed, 28 Oct 2009)
New Revision: 5828

Modified:
   jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch02-Installation.xml
   jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch04-DeployingBusinessArchives.xml
   jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch05-Services.xml
Log:
revision doc chapter 2/4/5

Modified: jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch02-Installation.xml
===================================================================
--- jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch02-Installation.xml	2009-10-28 10:54:55 UTC (rev 5827)
+++ jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch02-Installation.xml	2009-10-28 12:48:41 UTC (rev 5828)
@@ -374,7 +374,7 @@
       <title>Get Eclipse</title>
       <para>You'll need Eclipse 3.5.0.
       </para>
-      <para>Use the <link linkend="gettingstarted">demo setup</link> or download 
+      <para>Use the <link linkend="gettingstartedquickly">demo setup</link> or download 
       eclipse manually:      
       <ulink url="http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/galileo">Eclipse IDE for Java EE Developers (163 MB)</ulink>.
       </para>

Modified: jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch04-DeployingBusinessArchives.xml
===================================================================
--- jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch04-DeployingBusinessArchives.xml	2009-10-28 10:54:55 UTC (rev 5827)
+++ jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch04-DeployingBusinessArchives.xml	2009-10-28 12:48:41 UTC (rev 5828)
@@ -16,7 +16,7 @@
     </para>
     
     <para>There is a jBPM ant task to deploy business archives
-    (<literal>org.jbpm.pvm.internal.ant.JbpmDeployTask</literal>)
+    (<literal>org.jbpm.pvm.internal.ant.JbpmDeployTask</literal>).
     The <literal>JbpmDeployTask</literal> can deploy individual  
     process files and business archives.  They are deployed  
     directly to the database over a JDBC connection.  So it is a 
@@ -40,7 +40,7 @@
 
     <para>The JDBC driver jar(s) for your database should also be included
     in the path.  MySQL, PostgreSQL and HSQLDB are in the distribution.  But
-    the oracle driver you have to download separately from the oracle site since 
+    the Oracle driver you have to download separately from the oracle site since 
     we're not allowed to redistribute that file. 
     </para>
 

Modified: jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch05-Services.xml
===================================================================
--- jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch05-Services.xml	2009-10-28 10:54:55 UTC (rev 5827)
+++ jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch05-Services.xml	2009-10-28 12:48:41 UTC (rev 5828)
@@ -57,7 +57,7 @@
     </para>
     
     <para>The code snippets in this section and the next section about process 
-    deployments are taken from example 
+    deployments are taken from the example 
     <literal>org.jbpm.examples.services.ServicesTest</literal> 
     </para>
     
@@ -217,11 +217,13 @@
       </tgroup>
     </table>
   </section>
-
+  
+<!-- 
   <section id="undeployingdeployments">
     <title>Undeploying deployments</title>
     <para>TODO</para>
   </section>
+-->
 
   <section id="deletingadeployment">
     <title>Deleting a deployment</title>
@@ -266,10 +268,11 @@
 
     <section id="withakey">
       <title>With a key</title>
-      <para>A new process instance can optionally be given a key.  A key is 
-      a user defined reference to the execution.  A key must be unique within the 
-      scope of all versions of a process definition.  Typically it is easy 
-      to find such a key in the domain of the business process.  For example, an 
+      <para>A new process instance can optionally be given a key.  This key is 
+      a user defined reference to the execution and is sometimes referred to as
+      the 'business key'.  A business key must be unique within the 
+      scope of all versions of a process definition. Typically it is easy 
+      to find such a key in the domain of the business process. For example, an 
       order id or an insurance claim number.
       </para>
       <programlisting>ProcessInstance processInstance = 
@@ -286,10 +289,10 @@
     executionService.startProcessInstanceByKey(&quot;ICL&quot;);
 String pid = processInstance.getId();</programlisting>
       </para> 
-      <para>We recommend the use of a user defined keys.  Typically in your application 
-      code, you'll have the key available.  By providing a user defined key, you can 
+      <para>It is a best practice to use a user defined business key. Typically in your application 
+      domain, finding such a key is not difficult. By providing a user defined key, you can 
       then compose the id of the execution, rather then performing a query based 
-      on the process variables.
+      on the process variables - which is also more costly performance-wise.
       </para>
     </section>
     
@@ -312,8 +315,8 @@
   <section id="singallingawaitingexecution">
     <title>Signalling a waiting execution</title>
     <para>When using a <literal>state</literal> activity, the execution (or process instance) 
-    will wait when it arrives in the state, waiting for a signal (aka external trigger).  
-    Methods <literal>signalExecution</literal> can be used for that.  Executions are 
+    will halt when it arrives in a state, waiting for a signal (aka external trigger).  
+    The method <literal>signalExecution</literal> and alike can be used for that.  Executions are 
     referenced by an execution id (String).
     </para>
     <para>In some cases, the execution that arrives in a state will be the process instance 
@@ -333,7 +336,7 @@
     <para>In event listener <literal>StartExternalWork</literal> you can kick off what needs to
     be done externally.  In that event listener you can also obtain the exact execution id
     with <literal>execution.getId()</literal>.  It's that executionId that you'll need to provide 
-    the signal later on when the external work is done:
+    with the signal later on when the external work is done:
     </para>
     <programlisting>executionService.signalExecutionById(executionId);</programlisting>
     <para>There is an alternatively (less preferrable) way to obtain the executionId 
@@ -352,6 +355,11 @@
 Execution execution = processInstance.findActiveExecutionIn("external work");
 String executionId = execution.getId();</programlisting>
   </section>
+  
+  <para>
+  Do note that the above solution couples the application logic (too) closely
+  by using knowledge about the actual process structure.
+  </para>
 
   <section id="taskservice">
     <title>TaskService</title>
@@ -419,8 +427,50 @@
   <section id="managementservice">
     <title>ManagementService</title>
     <para>The management service is mostly used to manage the jobs.  See javadocs for 
-    more information.  This functionality is also exposed through the console.
+    more information.  This functionality is also exposed through the jBPM web console.
     </para>
   </section>
 
+  <section id="queryApi">
+    <title>Query API</title>
+    <para>
+    Starting from jBPM 4.0, a new API has been introuced with a query system that 
+    covers most of the queries you can think of. Developers who need to write company-specific
+    queries can of course still rely on Hibernate. But for most use cases,
+    the query API will be more then suffice. 
+    Queries can be written in a unified way on all major jBPM concepts: 
+    Process Instances, Tasks, Deployments, Historical processes, etc.
+    </para>
+    <para>
+    For example:
+    <programlisting>
+List&lt;ProcessInstance&gt; results = executionService.createProcessInstanceQuery()
+                                       .processDefinitionId(&quot;my_process_definition&quot;)
+                                       .notSuspended()
+                                       .page(0, 50)
+                                       .list();
+    </programlisting>
+    This example returns all the process instances of the given process definition
+    which are not suspended. The result is also paged, and the first page of 50
+    results is given. 
+    </para><para>Querying tasks is done in completely the same way:
+    <programlisting>
+List&lt;Task&gt; myTasks = taskService.createTaskQuery()
+    .processInstanceId(piId)
+    .assignee(&quot;John&quot;)
+    .page(100, 120)
+    .orderDesc(TaskQuery.PROPERTY_DUEDATE)
+    .list();
+</programlisting>
+This query will give all the tasks for a given process instance assigned to John, 
+paged of course, in a descending order based on the duedate. 
+    </para>
+    <para>
+    Every service has operations of creating such unified queries (eg. querying
+    jobs through the <literal>ManagementService</literal>, querying completed
+    process instances through the <literal>HistoryService</literal>. Do check
+    the Javadoc of the services to learn everything about the query API.
+    </para>
+  </section>
+
 </chapter>



More information about the jbpm-commits mailing list