[jbpm-commits] JBoss JBPM SVN: r5485 - jbpm4/trunk/modules/userguide/src/main/docbook/en/modules.
do-not-reply at jboss.org
do-not-reply at jboss.org
Tue Aug 18 04:17:27 EDT 2009
Author: camunda
Date: 2009-08-18 04:17:27 -0400 (Tue, 18 Aug 2009)
New Revision: 5485
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
jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch06-Jpdl.xml
Log:
small fixes of errors by my colleague
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-08-18 02:20:19 UTC (rev 5484)
+++ jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch02-Installation.xml 2009-08-18 08:17:27 UTC (rev 5485)
@@ -110,7 +110,7 @@
directly, is possible, but not supported.
</para>
- <para>As you already saw one example in the demo setup, the distribution a couple of ant
+ <para>As you already saw one example in the demo setup, the distribution contains a couple of ant
scripts:
</para>
<itemizedlist>
@@ -147,7 +147,7 @@
<section id="librarydependenciesandconfigurationfiles">
<title>Library dependencies and configuration files</title>
<para>We provide support for installations of jBPM through our automatic ant
- scripts. Those scripts will be put the right libs and the right configuration
+ scripts. Those scripts will put the right libs and the right configuration
files in the right location for you. If you want to create your own installation of
jBPM in your application, see the developers guide for more information.
</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-08-18 02:20:19 UTC (rev 5484)
+++ jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch04-DeployingBusinessArchives.xml 2009-08-18 08:17:27 UTC (rev 5485)
@@ -1,155 +1,155 @@
-<chapter id="deployingbusinessarchives">
- <title>Deploying business archives</title>
-
- <para>A business archive is a collection of files
- assembled in a jar formatted file. The files in
- a business archive can be jPDL process files, forms,
- process image and other process resources.
- </para>
-
- <section id="deployingprocessfilesandprocessresources">
- <title>Deploying process files and process resources</title>
-
- <para>Process files and process resources have to be
- deployed in the process repository which is stored in
- the database.
- </para>
-
- <para>There is a jBPM ant task to deploy business archives
- (<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
- requirement that the database is up and running before you can
- deploy processes.
- </para>
-
- <para>An example of creating and deploying a business
- archive can be found in the examples directory of the
- distribution. Let's look at the relevant parts. First a path is
- declared that includes the jbpm.jar and all its dependencies.
- </para>
-
- <programlisting><path id="jbpm.libs.incl.dependencies">
- <pathelement location="${jbpm.home}/examples/target/classes" />
- <fileset dir="${jbpm.home}">
- <include name="jbpm.jar" />
- </fileset>
- <fileset dir="${jbpm.home}/lib" />
-</path></programlisting>
-
- <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
- we're not allowed to redistribute that file.
- </para>
-
- <para>When a business archive is deployed, jBPM scans for all the files
- with the <literal>.jpdl.xml</literal> extension in the business archive.
- All those files will be parsed as jPDL processes and made available to the
- runtime engine. All other resources in the business archive will also
- be stored as resources in that deployment and made accessible through
- <literal>InputStream getResourceAsStream(long deploymentDbid, String resourceName);</literal>
- in class <literal>RepositoryService</literal>
- </para>
-
- <para>For creating a business archives, the <literal>jar</literal> task
- can be used.
- </para>
-
- <programlisting><jar destfile="${jbpm.home}/examples/target/examples.bar">
- <fileset dir="${jbpm.home}/examples/src">
- <include name="**/*.jpdl.xml" />
- ...
- </fileset>
- </jar></programlisting>
-
- <para>Before the jbpm-deploy task can be used it need to be declared like this:</para>
-
- <programlisting><taskdef name="jbpm-deploy"
- classname="org.jbpm.pvm.internal.ant.JbpmDeployTask"
- classpathref="jbpm.libs.incl.dependencies" /></programlisting>
-
- <para>Then the ant task can be used like this</para>
-
- <programlisting>
- <jbpm-deploy file="${jbpm.home}/examples/target/examples.bar" /></programlisting>
-
- <table><title><literal>jbpm-deploy</literal> attributes:</title>
- <tgroup cols="5" rowsep="1" colsep="1">
- <thead>
- <row>
- <entry>Attribute</entry>
- <entry>Type</entry>
- <entry>Default</entry>
- <entry>Required?</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>file</literal></entry>
- <entry>file</entry>
- <entry></entry>
- <entry>optional</entry>
- <entry>A file to be deployed. Files ending with <literal>.xml</literal> will be deployed
- as process files. Files ending with <literal>ar</literal> like .bar or .jar
- will be deployed as business archives.
- </entry>
- </row>
- <row>
- <entry><literal>cfg</literal></entry>
- <entry>file</entry>
- <entry>jbpm.cfg.xml</entry>
- <entry>optional</entry>
- <entry>Points to the jbpm configuration file that has to be on the classpath in which
- the <literal>jbpm-deploy</literal> task was defined.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <table><title><literal>jbpm-deploy</literal> elements:</title>
- <tgroup cols="3" rowsep="1" colsep="1">
- <thead>
- <row>
- <entry>Element</entry>
- <entry>Multiplicity</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>fileset</literal></entry>
- <entry>0..*</entry>
- <entry>files to be deployed expressed as a plain ant fileset.
- Files ending with <literal>.xml</literal> will be deployed
- as process files. Files ending with <literal>ar</literal> like .bar or .jar
- will be deployed as business archives.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- </section>
-
- <section id="deployingclasses">
- <title>Deploying classes</title>
- <para>jBPM 4 does not yet have a process classloading mechanism as in jBPM 3.
- </para>
- <para>All the classes that are referred to
- in your process files, either directly or indirectly, need to be made available
- on the classpath of your jBPM installation.
- </para>
- <para>In case of the examples, an examples.jar file is created with
- all the classes and it is put in the <literal>lib</literal> directory of the JBoss
- server configuration.</para>
- <para>If you want process classloading so that user defined classes can be deployed
- in and loaded from the business archive, vote for it in
- <ulink url="https://jira.jboss.org/jira/browse/JBPM-2200">JIRA issue JBPM-2200</ulink>.
- We'll prioritize this depending on the number of votes and on the use cases that
- you can add as a comment in which you explain why you need it.
- </para>
- </section>
-
-</chapter>
+<chapter id="deployingbusinessarchives">
+ <title>Deploying business archives</title>
+
+ <para>A business archive is a collection of files
+ assembled in a jar formatted file. The files in
+ a business archive can be jPDL process files, forms,
+ process image and other process resources.
+ </para>
+
+ <section id="deployingprocessfilesandprocessresources">
+ <title>Deploying process files and process resources</title>
+
+ <para>Process files and process resources have to be
+ deployed in the process repository which is stored in
+ the database.
+ </para>
+
+ <para>There is a jBPM ant task to deploy business archives
+ (<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
+ requirement that the database is up and running before you can
+ deploy processes.
+ </para>
+
+ <para>An example of creating and deploying a business
+ archive can be found in the ant build script (build.xml) in the examples directory of the
+ distribution. Let's look at the relevant parts. First a path is
+ declared that includes the jbpm.jar and all its dependencies.
+ </para>
+
+ <programlisting><path id="jbpm.libs.incl.dependencies">
+ <pathelement location="${jbpm.home}/examples/target/classes" />
+ <fileset dir="${jbpm.home}">
+ <include name="jbpm.jar" />
+ </fileset>
+ <fileset dir="${jbpm.home}/lib" />
+</path></programlisting>
+
+ <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
+ we're not allowed to redistribute that file.
+ </para>
+
+ <para>When a business archive is deployed, jBPM scans for all the files
+ with the <literal>.jpdl.xml</literal> extension in the business archive.
+ All those files will be parsed as jPDL processes and made available to the
+ runtime engine. All other resources in the business archive will also
+ be stored as resources in that deployment and made accessible through
+ <literal>InputStream getResourceAsStream(long deploymentDbid, String resourceName);</literal>
+ in class <literal>RepositoryService</literal>
+ </para>
+
+ <para>For creating a business archives, the <literal>jar</literal> task
+ can be used.
+ </para>
+
+ <programlisting><jar destfile="${jbpm.home}/examples/target/examples.bar">
+ <fileset dir="${jbpm.home}/examples/src">
+ <include name="**/*.jpdl.xml" />
+ ...
+ </fileset>
+ </jar></programlisting>
+
+ <para>Before the jbpm-deploy task can be used it need to be declared like this:</para>
+
+ <programlisting><taskdef name="jbpm-deploy"
+ classname="org.jbpm.pvm.internal.ant.JbpmDeployTask"
+ classpathref="jbpm.libs.incl.dependencies" /></programlisting>
+
+ <para>Then the ant task can be used like this</para>
+
+ <programlisting>
+ <jbpm-deploy file="${jbpm.home}/examples/target/examples.bar" /></programlisting>
+
+ <table><title><literal>jbpm-deploy</literal> attributes:</title>
+ <tgroup cols="5" rowsep="1" colsep="1">
+ <thead>
+ <row>
+ <entry>Attribute</entry>
+ <entry>Type</entry>
+ <entry>Default</entry>
+ <entry>Required?</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>file</literal></entry>
+ <entry>file</entry>
+ <entry></entry>
+ <entry>optional</entry>
+ <entry>A file to be deployed. Files ending with <literal>.xml</literal> will be deployed
+ as process files. Files ending with <literal>ar</literal> like .bar or .jar
+ will be deployed as business archives.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>cfg</literal></entry>
+ <entry>file</entry>
+ <entry>jbpm.cfg.xml</entry>
+ <entry>optional</entry>
+ <entry>Points to the jbpm configuration file that has to be on the classpath in which
+ the <literal>jbpm-deploy</literal> task was defined.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <table><title><literal>jbpm-deploy</literal> elements:</title>
+ <tgroup cols="3" rowsep="1" colsep="1">
+ <thead>
+ <row>
+ <entry>Element</entry>
+ <entry>Multiplicity</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>fileset</literal></entry>
+ <entry>0..*</entry>
+ <entry>files to be deployed expressed as a plain ant fileset.
+ Files ending with <literal>.xml</literal> will be deployed
+ as process files. Files ending with <literal>ar</literal> like .bar or .jar
+ will be deployed as business archives.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </section>
+
+ <section id="deployingclasses">
+ <title>Deploying classes</title>
+ <para>jBPM 4 does not yet have a process classloading mechanism as in jBPM 3.
+ </para>
+ <para>All the classes that are referred to
+ in your process files, either directly or indirectly, need to be made available
+ on the classpath of your jBPM installation.
+ </para>
+ <para>In case of the examples, an examples.jar file is created with
+ all the classes and it is put in the <literal>lib</literal> directory of the JBoss
+ server configuration.</para>
+ <para>If you want process classloading so that user defined classes can be deployed
+ in and loaded from the business archive, vote for it in
+ <ulink url="https://jira.jboss.org/jira/browse/JBPM-2200">JIRA issue JBPM-2200</ulink>.
+ We'll prioritize this depending on the number of votes and on the use cases that
+ you can add as a comment in which you explain why you need it.
+ </para>
+ </section>
+
+</chapter>
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-08-18 02:20:19 UTC (rev 5484)
+++ jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch05-Services.xml 2009-08-18 08:17:27 UTC (rev 5485)
@@ -1,426 +1,426 @@
-<chapter id="services">
- <title>Services</title>
-
- <section id="processdefinitionprocessinstanceandexecutions">
- <title>Process definition, process instance and executions</title>
- <para>A process definition is description of the steps in a procedure.
- For example, an insurance company could have a <literal>loan</literal>
- process definition that describes the steps of how the company deals
- with loan requests.
- </para>
- <figure id="loan.process.definition.example">
- <title>The loan process definition example</title>
- <mediaobject><imageobject><imagedata align="center" fileref="images/loan.process.definition.png"/></imageobject></mediaobject>
- </figure>
- <para>One process instance represents one particular run of a process definition.
- For example, the loan request of John Doe last Friday to finance his new boat
- is represented in one process instance of the loan process definition.
- </para>
- <para>A process instance contains all the runtime state. The
- most prominent property is the pointer that keeps track of the current activity.
- </para>
- <figure id="loan.process.instance.example">
- <title>The loan process instance example</title>
- <mediaobject><imageobject><imagedata align="center" fileref="images/loan.process.instance.png"/></imageobject></mediaobject>
- </figure>
- <para>Suppose that wiring the money and archiving can be done in parallel.
- Then the main process instance will have two child executions to keep
- track of the state like this:
- </para>
- <figure id="loan.executions.example">
- <title>The loan executions example</title>
- <mediaobject><imageobject><imagedata align="center" fileref="images/loan.executions.png"/></imageobject></mediaobject>
- </figure>
- <para>More general, a process instance is the root of a tree of executions.
- When a new process instance is started, the process instance is in fact the root
- execution scope. Only leaf executions can be active.
- </para>
- <para>The motivation to work with a tree structure like this is that
- this conceptually remains simple in the case where there is only one path
- of execution. The services API doesn't need to make a functional difference
- between process instances and executions. Therefore, the API has only
- one Execution type to refer to both <literal>ProcessInstance</literal>s and
- <literal>Execution</literal>s.
- </para>
- </section>
-
- <section id="processengine">
- <title>ProcessEngine</title>
- <para>Interacting with jBPM occurs through services.
- The service interfaces can be obtained from the <literal>ProcessEngine</literal>
- which is build from a <literal>Configuration</literal>.
- </para>
- <para>A <literal>ProcessEngine</literal> is thread safe and can be stored in a
- static member field or even better in JNDI or some other central location.
- One <literal>ProcessEngine</literal> object can be used by all requests and
- threads in an application. Here's how you can obtain a <literal>ProcessEngine</literal>
- </para>
-
- <para>The code snippets in this section and the next section about process
- deployments are taken from example
- <literal>org.jbpm.examples.services.ServicesTest</literal>
- </para>
-
- <programlisting>ProcessEngine processEngine = new Configuration()
- .buildProcessEngine();</programlisting>
-
- <para>The previous code snippet shows how to build a <literal>ProcessEngine</literal>
- from the default configuration file <literal>jbpm.cfg.xml</literal> which is
- expected in the root of the classpath. If you want to specify another
- resource location, use the <literal>setResource</literal> method like this:
- </para>
-
- <programlisting>ProcessEngine processEngine = new Configuration()
- .setResource("my-own-configuration-file.xml")
- .buildProcessEngine();</programlisting>
-
- <para>There are other <literal>setXxxx</literal> methods that allow to specify
- the configuration content as an <literal>InputStream</literal>, an
- <literal>xmlString</literal>, <literal>InputSource</literal>,
- <literal>URL</literal> or <literal>File</literal>.
- </para>
-
- <para>From a <literal>ProcessEngine</literal> the following services
- can be obtained:
- </para>
-
- <programlisting><emphasis role="bold">RepositoryService</emphasis> repositoryService = processEngine.getRepositoryService();
-<emphasis role="bold">ExecutionService</emphasis> executionService = processEngine.getExecutionService();
-<emphasis role="bold">TaskService</emphasis> taskService = processEngine.getTaskService();
-<emphasis role="bold">HistoryService</emphasis> historyService = processEngine.getHistoryService();
-<emphasis role="bold">ManagementService</emphasis> managementService = processEngine.getManagementService();</programlisting>
-
- <para>Process engine objects defined in the configuration can also be retrieved by
- type (<literal>processEngine.get(Class<T>)</literal>)
- or by name (<literal>processEngine.get(String)</literal>)</para>
-
- </section>
-
- <section id="deployingaprocess">
- <title>Deploying a process</title>
- <para>The <literal>RepositoryService</literal> groups all methods to manage
- the repository of deployments. In this first example, we'll deploy one process
- resource from the classpath with the <literal>RepositoryService</literal>:
- </para>
- <programlisting>long deploymentDbid = repositoryService.createDeployment()
- .addResourceFromClasspath("org/jbpm/examples/services/Order.jpdl.xml")
- .deploy();</programlisting>
- <para>Analogue to the <literal>addResourceFromClasspath</literal> method above,
- the source of the processes definitions XML can be picked up from a file, url, string,
- input stream or zip input stream.
- </para>
- <para>Each deployment is composed of a set of named resources. The content
- of each resource is a byte array. jPDL process files are recognized by their extension
- <literal>.jpdl.xml</literal>. Other resource types are task forms and java classes.
- </para>
- <para>A deployment works with a set of named resources and can potentially contain
- multiple process descriptions and multiple other artifact types. The jPDL deployer
- will recognise process files based on the <literal>.jpdl.xml</literal>
- extension automatically.
- </para>
- <para>During deployment, an <literal>id</literal> is assigned to the process
- definitions. The <literal>id</literal> will have format
- <literal>{key}-{version}</literal> with a dash between key and version
- </para>
- <para>If <literal>key</literal> is not provided, it is generated automatically
- based on the name. All non alpha numeric characters in the name will be replaced
- by underscores to generate the key.
- </para>
- <para>The same <literal>name</literal> can only be associated to one
- <literal>key</literal> and vice verca.
- </para>
- <para>If <literal>version</literal> is not provided, a <literal>version</literal>
- will be automatically be assigned. For version
- assignment, the versions of all deployed process definitions with the same name will
- be taken into account. The assigned <literal>version</literal> will be one higher
- then the highest <literal>version</literal> number of deployed process definitions
- with the same <literal>key</literal>. If no process definitions with a similar
- <literal>key</literal> have been deployed, version number 1 is assigned.
- </para>
- <para>In this first example, we'll supply a name and nothing else.</para>
- <programlisting><process name="Insurance claim">
-...
-</process></programlisting>
- <para>Let's assume that this is the first time that this process gets deployed.
- Then it will get the following properties:
- </para>
- <table><title>Process properties without key</title>
- <tgroup cols="3" rowsep="1" colsep="1">
- <thead>
- <row>
- <entry>Property</entry>
- <entry>Value</entry>
- <entry>Source</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>name</literal></entry>
- <entry>Insurance claim</entry>
- <entry>process xml</entry>
- </row>
- <row>
- <entry><literal>key</literal></entry>
- <entry>Insurance_claim</entry>
- <entry>generated</entry>
- </row>
- <row>
- <entry><literal>version</literal></entry>
- <entry>1</entry>
- <entry>generated</entry>
- </row>
- <row>
- <entry><literal>id</literal></entry>
- <entry>Insurance_claim:1</entry>
- <entry>generated</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>And as a second example, we'll show how you can get shorter ids by
- specifying a process key:</para>
- <programlisting><process name="Insurance claim" key="ICL">
-...
-</process></programlisting>
- <para>Then the process definition properties look like this:</para>
- <table><title>Process properties with key</title>
- <tgroup cols="2" rowsep="1" colsep="1">
- <thead>
- <row>
- <entry>Property</entry>
- <entry>Value</entry>
- <entry>Source</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>name</literal></entry>
- <entry>Insurance claim</entry>
- <entry>process xml</entry>
- </row>
- <row>
- <entry><literal>key</literal></entry>
- <entry>ICL</entry>
- <entry>process xml</entry>
- </row>
- <row>
- <entry><literal>version</literal></entry>
- <entry>1</entry>
- <entry>generated</entry>
- </row>
- <row>
- <entry><literal>id</literal></entry>
- <entry>ICL:1</entry>
- <entry>generated</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section id="undeployingdeployments">
- <title>Undeploying deployments</title>
- <para>TODO</para>
- </section>
-
- <section id="deletingadeployment">
- <title>Deleting a deployment</title>
- <para>Deleting a deployment will remove it from the DB.</para>
- <programlisting>repositoryService.deleteDeployment(deploymentDbid);</programlisting>
- <para>That method will throw an exception when there are still active
- process executions for process definitions in that deployment.
- </para>
- <para>If you want to cascade deletion of a deployment to all
- the process instances of all the process definitions, use
- <literal>deleteDeploymentCascade</literal>.
- </para>
- </section>
-
- <section id="startinganewprocessinstance">
- <title>Starting a new process instance</title>
-
- <section id="inlatest">
- <title>In latest</title>
- <para>Simplest and most common way to start a new process instance for a process
- definition is like this:
- </para>
- <programlisting>ProcessInstance processInstance = executionService.startProcessInstanceByKey("ICL");</programlisting>
- <para>In this case, the service method will first look up the latest version of
- the processes with key <literal>ICL</literal>. Then a new
- process instance is started in that latest process definition.
- </para>
- <para>When a new version of the insurance claim process
- is deployed, all invocations of <literal>startProcessInstanceByKey</literal>
- will automatically switch to the newly deployed version.
- </para>
- </section>
-
- <section id="specificprocessversion">
- <title>Specific process version</title>
- <para>If instead you want to start a new process instance in a very
- specific version, you can use the id of the process definition like this:
- </para>
- <programlisting>ProcessInstance processInstance =
- executionService.startProcessInstanceById("ICL-1");</programlisting>
- </section>
-
- <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
- order id or an insurance claim number.
- </para>
- <programlisting>ProcessInstance processInstance =
- executionService.startProcessInstanceByKey("ICL", "CL92837");</programlisting>
- <para>The key is used to create the id of the process instance.
- The format used is <literal>{process-key}.{execution-id}</literal>.
- With a dot between process-key and execution-id.
- So execution created in the previous code snippet will have id
- <literal>ICL.CL92837</literal>.
- </para>
- <para>If no user defined key is provided, the DB primary key is taken
- as the key. In that case, the id can be retrieved like this:
- <programlisting>ProcessInstance processInstance =
- executionService.startProcessInstanceByKey("ICL");
-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
- then compose the id of the execution, rather then performing a query based
- on the process variables.
- </para>
- </section>
-
- <section id="withvariables">
- <title>With variables</title>
- <para>A map of named parameter objects can be provided when starting a
- new process instance. These parameters will be set as variables on the process
- instance between creation and start of the process instance.
- </para>
- <programlisting>Map<String,Object> variables = new HashMap<String,Object>();
-variables.put("customer", "John Doe");
-variables.put("type", "Accident");
-variables.put("amount", new Float(763.74));
-
-ProcessInstance processInstance =
- executionService.startProcessInstanceByKey("ICL", variables);</programlisting>
- </section>
- </section>
-
- <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
- referenced by an execution id (String).
- </para>
- <para>In some cases, the execution that arrives in a state will be the process instance
- itself. But that is not always the case. In case of timers or concurrency, a process
- is the root execution of a tree of executions. So you have to make sure that you signal
- the right path of execution.
- </para>
- <para>The preferred way to capture the right execution is by associating an event listener to
- the state activity like this:
- </para>
- <programlisting><state name="wait">
- <on event="start">
- <event-listener class="org.jbpm.examples.StartExternalWork" />
- </on>
- ...
-</state></programlisting>
- <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:
- </para>
- <programlisting>executionService.signalExecutionById(executionId);</programlisting>
- <para>There is an alternatively (less preferrable) way to obtain the executionId
- when the execution arrives in the <literal>state</literal> activity.
- It's only possible to obtain the execution id this way if you know after which jBPM
- API call the execution will have entered the <literal>state</literal> activity:
- </para>
- <programlisting>// assume that we know that after the next call
-// the process instance will arrive in <literal>state</literal> external work
-
-ProcessInstance processInstance =
- executionService.startProcessInstanceById(processDefinitionId);
-// or ProcessInstance processInstance =
-// executionService.signalProcessInstanceById(executionId);
-
-Execution execution = processInstance.findActiveExecutionIn("external work");
-String executionId = execution.getId();</programlisting>
- </section>
-
- <section id="taskservice">
- <title>TaskService</title>
- <para>The primary purpose of the TaskService is to provide access to
- task lists. The code sample will show how to get the task list for
- the user with id <literal>johndoe</literal>.
- </para>
- <programlisting>List<Task> taskList = taskService.findPersonalTasks("johndoe");</programlisting>
- <para>Typically tasks are associated with a form and displayed in some user
- interface. The form needs to be able to read and write data related to the task.
- </para>
- <programlisting>long taskDbid = task.getDbid();
-
-Set<String> variableNames = taskService.getVariableNames(taskDbid);
-variables = taskService.getVariables(taskDbid, variableNames);
-
-variables = new HashMap<String, Object>();
-variables.put("category", "small");
-variables.put("lires", 923874893);
-taskService.setVariables(taskDbid, variables);</programlisting>
- <para>and complete tasks</para>
- <programlisting>taskService.completeTask(taskDbid);</programlisting>
- <para>Tasks can also be offered to a set of candidates. Candidates can be
- users or groups. Users can take tasks for which they are a candidate. Taking
- a task means that this user will be set as the assignee. After that, other users
- will be blocked from taking the task.
- </para>
- <para>People should not work on
- a task unless they are assigned to that task. The user interface displays
- forms and allow users to complete tasks if they are assigned to it.
- For unassigned tasks for which the user is a candidate, the only action that
- should be exposed is 'take'.
- </para>
- <para>More on tasks in <xref linkend="task" /> </para>
- </section>
-
- <section id="historyservice">
- <title>HistoryService</title>
- <para>During runtime execution of process instances, events are generated. And from
- those events, history information on both running and completed process executions are
- collected in the history tables. The <literal>HistoryService</literal> provides
- access to that information.
- </para>
- <para>Querying for all process instances for a specific process definition can be
- done like this:</para>
- <programlisting>List<HistoryProcessInstance> historyProcessInstances = historyService
- .createHistoryProcessInstanceQuery()
- .processDefinitionId("ICL-1")
- .orderAsc(HistoryProcessInstanceQuery.PROPERTY_STARTTIME)
- .list();</programlisting>
- <para>Also individual activity executions are stored in the history information as
- <literal>HistoryActivityInstance</literal>s.
- </para>
- <programlisting>List<HistoryActivityInstance> histActInsts = historyService
- .createHistoryActivityInstanceQuery()
- .processDefinitionId("ICL-1")
- .activityName("a")
- .list();</programlisting>
- <para>Convenience methods <literal>avgDurationPerActivity</literal> and
- <literal>choiceDistribution</literal> are also available. See javadocs for more
- information on those methods.
- </para>
- </section>
-
- <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.
- </para>
- </section>
-
-</chapter>
\ No newline at end of file
+<chapter id="services">
+ <title>Services</title>
+
+ <section id="processdefinitionprocessinstanceandexecutions">
+ <title>Process definition, process instance and executions</title>
+ <para>A process definition is description of the steps in a procedure.
+ For example, an insurance company could have a <literal>loan</literal>
+ process definition that describes the steps of how the company deals
+ with loan requests.
+ </para>
+ <figure id="loan.process.definition.example">
+ <title>The loan process definition example</title>
+ <mediaobject><imageobject><imagedata align="center" fileref="images/loan.process.definition.png"/></imageobject></mediaobject>
+ </figure>
+ <para>One process instance represents one particular run of a process definition.
+ For example, the loan request of John Doe last Friday to finance his new boat
+ is represented in one process instance of the loan process definition.
+ </para>
+ <para>A process instance contains all the runtime state. The
+ most prominent property is the pointer that keeps track of the current activity.
+ </para>
+ <figure id="loan.process.instance.example">
+ <title>The loan process instance example</title>
+ <mediaobject><imageobject><imagedata align="center" fileref="images/loan.process.instance.png"/></imageobject></mediaobject>
+ </figure>
+ <para>Suppose that wiring the money and archiving can be done in parallel.
+ Then the main process instance will have two child executions to keep
+ track of the state like this:
+ </para>
+ <figure id="loan.executions.example">
+ <title>The loan executions example</title>
+ <mediaobject><imageobject><imagedata align="center" fileref="images/loan.executions.png"/></imageobject></mediaobject>
+ </figure>
+ <para>More general, a process instance is the root of a tree of executions.
+ When a new process instance is started, the process instance is in fact the root
+ execution scope. Only leaf executions can be active.
+ </para>
+ <para>The motivation to work with a tree structure like this is that
+ this conceptually remains simple in the case where there is only one path
+ of execution. The services API doesn't need to make a functional difference
+ between process instances and executions. Therefore, the API has only
+ one Execution type to refer to both <literal>ProcessInstance</literal>s and
+ <literal>Execution</literal>s.
+ </para>
+ </section>
+
+ <section id="processengine">
+ <title>ProcessEngine</title>
+ <para>Interacting with jBPM occurs through services.
+ The service interfaces can be obtained from the <literal>ProcessEngine</literal>
+ which is build from a <literal>Configuration</literal>.
+ </para>
+ <para>A <literal>ProcessEngine</literal> is thread safe and can be stored in a
+ static member field or even better in JNDI or some other central location.
+ One <literal>ProcessEngine</literal> object can be used by all requests and
+ threads in an application. Here's how you can obtain a <literal>ProcessEngine</literal>
+ </para>
+
+ <para>The code snippets in this section and the next section about process
+ deployments are taken from example
+ <literal>org.jbpm.examples.services.ServicesTest</literal>
+ </para>
+
+ <programlisting>ProcessEngine processEngine = new Configuration()
+ .buildProcessEngine();</programlisting>
+
+ <para>The previous code snippet shows how to build a <literal>ProcessEngine</literal>
+ from the default configuration file <literal>jbpm.cfg.xml</literal> which is
+ expected in the root of the classpath. If you want to specify another
+ resource location, use the <literal>setResource</literal> method like this:
+ </para>
+
+ <programlisting>ProcessEngine processEngine = new Configuration()
+ .setResource("my-own-configuration-file.xml")
+ .buildProcessEngine();</programlisting>
+
+ <para>There are other <literal>setXxxx</literal> methods that allow to specify
+ the configuration content as an <literal>InputStream</literal>, an
+ <literal>xmlString</literal>, <literal>InputSource</literal>,
+ <literal>URL</literal> or <literal>File</literal>.
+ </para>
+
+ <para>From a <literal>ProcessEngine</literal> the following services
+ can be obtained:
+ </para>
+
+ <programlisting><emphasis role="bold">RepositoryService</emphasis> repositoryService = processEngine.getRepositoryService();
+<emphasis role="bold">ExecutionService</emphasis> executionService = processEngine.getExecutionService();
+<emphasis role="bold">TaskService</emphasis> taskService = processEngine.getTaskService();
+<emphasis role="bold">HistoryService</emphasis> historyService = processEngine.getHistoryService();
+<emphasis role="bold">ManagementService</emphasis> managementService = processEngine.getManagementService();</programlisting>
+
+ <para>Process engine objects defined in the configuration can also be retrieved by
+ type (<literal>processEngine.get(Class<T>)</literal>)
+ or by name (<literal>processEngine.get(String)</literal>)</para>
+
+ </section>
+
+ <section id="deployingaprocess">
+ <title>Deploying a process</title>
+ <para>The <literal>RepositoryService</literal> groups all methods to manage
+ the repository of deployments. In this first example, we'll deploy one process
+ resource from the classpath with the <literal>RepositoryService</literal>:
+ </para>
+ <programlisting>long deploymentId = repositoryService.createDeployment()
+ .addResourceFromClasspath("org/jbpm/examples/services/Order.jpdl.xml")
+ .deploy();</programlisting>
+ <para>Analogue to the <literal>addResourceFromClasspath</literal> method above,
+ the source of the processes definitions XML can be picked up from a file, url, string,
+ input stream or zip input stream.
+ </para>
+ <para>Each deployment is composed of a set of named resources. The content
+ of each resource is a byte array. jPDL process files are recognized by their extension
+ <literal>.jpdl.xml</literal>. Other resource types are task forms and java classes.
+ </para>
+ <para>A deployment works with a set of named resources and can potentially contain
+ multiple process descriptions and multiple other artifact types. The jPDL deployer
+ will recognise process files based on the <literal>.jpdl.xml</literal>
+ extension automatically.
+ </para>
+ <para>During deployment, an <literal>id</literal> is assigned to the process
+ definitions. The <literal>id</literal> will have format
+ <literal>{key}-{version}</literal> with a dash between key and version
+ </para>
+ <para>If <literal>key</literal> is not provided, it is generated automatically
+ based on the name. All non alpha numeric characters in the name will be replaced
+ by underscores to generate the key.
+ </para>
+ <para>The same <literal>name</literal> can only be associated to one
+ <literal>key</literal> and vice versa.
+ </para>
+ <para>If <literal>version</literal> is not provided, a <literal>version</literal>
+ will be automatically be assigned. For version
+ assignment, the versions of all deployed process definitions with the same name will
+ be taken into account. The assigned <literal>version</literal> will be one higher
+ then the highest <literal>version</literal> number of deployed process definitions
+ with the same <literal>key</literal>. If no process definitions with a similar
+ <literal>key</literal> have been deployed, version number 1 is assigned.
+ </para>
+ <para>In this first example, we'll supply a name and nothing else.</para>
+ <programlisting><process name="Insurance claim">
+...
+</process></programlisting>
+ <para>Let's assume that this is the first time that this process gets deployed.
+ Then it will get the following properties:
+ </para>
+ <table><title>Process properties without key</title>
+ <tgroup cols="3" rowsep="1" colsep="1">
+ <thead>
+ <row>
+ <entry>Property</entry>
+ <entry>Value</entry>
+ <entry>Source</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>name</literal></entry>
+ <entry>Insurance claim</entry>
+ <entry>process xml</entry>
+ </row>
+ <row>
+ <entry><literal>key</literal></entry>
+ <entry>Insurance_claim</entry>
+ <entry>generated</entry>
+ </row>
+ <row>
+ <entry><literal>version</literal></entry>
+ <entry>1</entry>
+ <entry>generated</entry>
+ </row>
+ <row>
+ <entry><literal>id</literal></entry>
+ <entry>Insurance_claim-1</entry>
+ <entry>generated</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>And as a second example, we'll show how you can get shorter ids by
+ specifying a process key:</para>
+ <programlisting><process name="Insurance claim" key="ICL">
+...
+</process></programlisting>
+ <para>Then the process definition properties look like this:</para>
+ <table><title>Process properties with key</title>
+ <tgroup cols="2" rowsep="1" colsep="1">
+ <thead>
+ <row>
+ <entry>Property</entry>
+ <entry>Value</entry>
+ <entry>Source</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>name</literal></entry>
+ <entry>Insurance claim</entry>
+ <entry>process xml</entry>
+ </row>
+ <row>
+ <entry><literal>key</literal></entry>
+ <entry>ICL</entry>
+ <entry>process xml</entry>
+ </row>
+ <row>
+ <entry><literal>version</literal></entry>
+ <entry>1</entry>
+ <entry>generated</entry>
+ </row>
+ <row>
+ <entry><literal>id</literal></entry>
+ <entry>ICL-1</entry>
+ <entry>generated</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section id="undeployingdeployments">
+ <title>Undeploying deployments</title>
+ <para>TODO</para>
+ </section>
+
+ <section id="deletingadeployment">
+ <title>Deleting a deployment</title>
+ <para>Deleting a deployment will remove it from the DB.</para>
+ <programlisting>repositoryService.deleteDeployment(deploymentId);</programlisting>
+ <para>That method will throw an exception when there are still active
+ process executions for process definitions in that deployment.
+ </para>
+ <para>If you want to cascade deletion of a deployment to all
+ the process instances of all the process definitions, use
+ <literal>deleteDeploymentCascade</literal>.
+ </para>
+ </section>
+
+ <section id="startinganewprocessinstance">
+ <title>Starting a new process instance</title>
+
+ <section id="inlatest">
+ <title>In latest</title>
+ <para>Simplest and most common way to start a new process instance for a process
+ definition is like this:
+ </para>
+ <programlisting>ProcessInstance processInstance = executionService.startProcessInstanceByKey("ICL");</programlisting>
+ <para>In this case, the service method will first look up the latest version of
+ the processes with key <literal>ICL</literal>. Then a new
+ process instance is started in that latest process definition.
+ </para>
+ <para>When a new version of the insurance claim process
+ is deployed, all invocations of <literal>startProcessInstanceByKey</literal>
+ will automatically switch to the newly deployed version.
+ </para>
+ </section>
+
+ <section id="specificprocessversion">
+ <title>Specific process version</title>
+ <para>If instead you want to start a new process instance in a very
+ specific version, you can use the id of the process definition like this:
+ </para>
+ <programlisting>ProcessInstance processInstance =
+ executionService.startProcessInstanceById("ICL-1");</programlisting>
+ </section>
+
+ <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
+ order id or an insurance claim number.
+ </para>
+ <programlisting>ProcessInstance processInstance =
+ executionService.startProcessInstanceByKey("ICL", "CL92837");</programlisting>
+ <para>The key is used to create the id of the process instance.
+ The format used is <literal>{process-key}.{execution-id}</literal>.
+ With a dot between process-key and execution-id.
+ So execution created in the previous code snippet will have id
+ <literal>ICL.CL92837</literal>.
+ </para>
+ <para>If no user defined key is provided, the DB primary key is taken
+ as the key. In that case, the id can be retrieved like this:
+ <programlisting>ProcessInstance processInstance =
+ executionService.startProcessInstanceByKey("ICL");
+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
+ then compose the id of the execution, rather then performing a query based
+ on the process variables.
+ </para>
+ </section>
+
+ <section id="withvariables">
+ <title>With variables</title>
+ <para>A map of named parameter objects can be provided when starting a
+ new process instance. These parameters will be set as variables on the process
+ instance between creation and start of the process instance.
+ </para>
+ <programlisting>Map<String,Object> variables = new HashMap<String,Object>();
+variables.put("customer", "John Doe");
+variables.put("type", "Accident");
+variables.put("amount", new Float(763.74));
+
+ProcessInstance processInstance =
+ executionService.startProcessInstanceByKey("ICL", variables);</programlisting>
+ </section>
+ </section>
+
+ <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
+ referenced by an execution id (String).
+ </para>
+ <para>In some cases, the execution that arrives in a state will be the process instance
+ itself. But that is not always the case. In case of timers or concurrency, a process
+ is the root execution of a tree of executions. So you have to make sure that you signal
+ the right path of execution.
+ </para>
+ <para>The preferred way to capture the right execution is by associating an event listener to
+ the state activity like this:
+ </para>
+ <programlisting><state name="wait">
+ <on event="start">
+ <event-listener class="org.jbpm.examples.StartExternalWork" />
+ </on>
+ ...
+</state></programlisting>
+ <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:
+ </para>
+ <programlisting>executionService.signalExecutionById(executionId);</programlisting>
+ <para>There is an alternatively (less preferrable) way to obtain the executionId
+ when the execution arrives in the <literal>state</literal> activity.
+ It's only possible to obtain the execution id this way if you know after which jBPM
+ API call the execution will have entered the <literal>state</literal> activity:
+ </para>
+ <programlisting>// assume that we know that after the next call
+// the process instance will arrive in <literal>state</literal> external work
+
+ProcessInstance processInstance =
+ executionService.startProcessInstanceById(processDefinitionId);
+// or ProcessInstance processInstance =
+// executionService.signalProcessInstanceById(executionId);
+
+Execution execution = processInstance.findActiveExecutionIn("external work");
+String executionId = execution.getId();</programlisting>
+ </section>
+
+ <section id="taskservice">
+ <title>TaskService</title>
+ <para>The primary purpose of the TaskService is to provide access to
+ task lists. The code sample will show how to get the task list for
+ the user with id <literal>johndoe</literal>.
+ </para>
+ <programlisting>List<Task> taskList = taskService.findPersonalTasks("johndoe");</programlisting>
+ <para>Typically tasks are associated with a form and displayed in some user
+ interface. The form needs to be able to read and write data related to the task.
+ </para>
+ <programlisting>long taskId = task.getId();
+
+Set<String> variableNames = taskService.getVariableNames(taskId);
+variables = taskService.getVariables(taskId, variableNames);
+
+variables = new HashMap<String, Object>();
+variables.put("category", "small");
+variables.put("lires", 923874893);
+taskService.setVariables(taskId, variables);</programlisting>
+ <para>and complete tasks</para>
+ <programlisting>taskService.completeTask(taskId);</programlisting>
+ <para>Tasks can also be offered to a set of candidates. Candidates can be
+ users or groups. Users can take tasks for which they are a candidate. Taking
+ a task means that this user will be set as the assignee. After that, other users
+ will be blocked from taking the task.
+ </para>
+ <para>People should not work on
+ a task unless they are assigned to that task. The user interface should display
+ forms and allow users to complete tasks if they are assigned to it.
+ For unassigned tasks for which the user is a candidate, the only action that
+ should be exposed is 'take'.
+ </para>
+ <para>More on tasks in <xref linkend="task" /> </para>
+ </section>
+
+ <section id="historyservice">
+ <title>HistoryService</title>
+ <para>During runtime execution of process instances, events are generated. And from
+ those events, history information on both running and completed process executions are
+ collected in the history tables. The <literal>HistoryService</literal> provides
+ access to that information.
+ </para>
+ <para>Querying for all process instances for a specific process definition can be
+ done like this:</para>
+ <programlisting>List<HistoryProcessInstance> historyProcessInstances = historyService
+ .createHistoryProcessInstanceQuery()
+ .processDefinitionId("ICL-1")
+ .orderAsc(HistoryProcessInstanceQuery.PROPERTY_STARTTIME)
+ .list();</programlisting>
+ <para>Also individual activity executions are stored in the history information as
+ <literal>HistoryActivityInstance</literal>s.
+ </para>
+ <programlisting>List<HistoryActivityInstance> histActInsts = historyService
+ .createHistoryActivityInstanceQuery()
+ .processDefinitionId("ICL-1")
+ .activityName("a")
+ .list();</programlisting>
+ <para>Convenience methods <literal>avgDurationPerActivity</literal> and
+ <literal>choiceDistribution</literal> are also available. See javadocs for more
+ information on those methods.
+ </para>
+ </section>
+
+ <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.
+ </para>
+ </section>
+
+</chapter>
Modified: jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch06-Jpdl.xml
===================================================================
--- jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch06-Jpdl.xml 2009-08-18 02:20:19 UTC (rev 5484)
+++ jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch06-Jpdl.xml 2009-08-18 08:17:27 UTC (rev 5485)
@@ -247,7 +247,7 @@
<para>Let's start a new process instance for this process definition:</para>
<programlisting>ProcessInstance processInstance = executionService
.startProcessInstanceByKey("StateChoice");</programlisting>
- <para>Now, the execution is arrived in the <literal>wait for response</literal>.
+ <para>Now, the execution has arrived in the <literal>wait for response</literal>.
The execution will wait there until an external trigger is given. In case
a <literal>state</literal> has multiple outgoing transitions, the signalName given
in the external trigger will be matched against the name of the outgoing transition
More information about the jbpm-commits
mailing list