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

Author: alex.guizar(a)jboss.com Date: 2009-02-09 21:27:07 -0500 (Mon, 09 Feb 2009) New Revision: 3820 Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/async.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/calendar.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/configuration.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/context.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/database.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/deployment.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/developers.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/introduction.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/jpdl.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/logging.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/mail.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/modelling.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/persistence.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/pluggable.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/scheduler.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/security.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/taskmgmt.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/tdd.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/tutorial.xml Log: JBPM-1808 apply changes made to jBPM guide included in SOA 4.3 GA release Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/async.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/async.xml 2009-02-09 16:40:15 UTC (rev 3819) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/async.xml 2009-02-10 02:27:07 UTC (rev 3820) @@ -1,4 +1,4 @@ -<chapter id="asynchronouscontinuations"> +<chapter id="ch_asynchronouscontinuations"> <title>Asynchronous continuations</title> <section id="theconcept"> @@ -28,7 +28,7 @@ executed in the thread of the client. We'll explore asynchronous continuations by looking two examples. The first example is a part of a process with 3 nodes. Node 'a' is a wait state, node 'b' is an automated step and node 'c' is again a wait state. This process does - not contain any asynchronous behaviour and it is represented in the picture below. + not contain any asynchronous behavior and it is represented in the picture below. </para> <para>The first frame, shows the starting situation. The token points to node 'a', meaning @@ -94,7 +94,7 @@ </para> <para>jBPM can be configured to use a JMS provider or its built-in asynchronous messaging - system. The built-in messaging system is quite limited in functionality, but allowes + system. The built-in messaging system is quite limited in functionality, but allows this feature to be supported on environments where JMS is unavailable. </para> @@ -134,7 +134,7 @@ </para> <para>Jobs are records in the database. Jobs are objects and can be executed, too. Both timers - and async messages are jobs. For async messages, the dueDate is simply set to the current time when they + and asynchronous messages are jobs. For asynchronous messages, the dueDate is simply set to now when they are inserted. The job executor must execute the jobs. This is done in 2 phases: 1) a job executor thread must acquire a job and 2) the thread that acquired the job must execute it. </para> @@ -150,11 +150,11 @@ <para>A thread could die between acquisition and execution of a job. To clean-up after those situations, there is one lock-monitor thread per job executor that checks the lock times. - Jobs that are locked for more then 30 mins (by default) will be unlocked so that they can be - executed by another job. + The lock monitor thread will unlock any jobs that have been locked for more than 30 minutes, + so that they can be executed by another job executor thread. </para> - <para>The required isolation level should be set to REPEATABLE_READ for hibernate's optimistic + <para>The required isolation level should be set to REPEATABLE_READ for Hibernate's optimistic locking to work correctly. That isolation level will guarantee that </para> @@ -167,13 +167,13 @@ <para>will only result in 1 row updated in exactly 1 of the competing transactions. </para> - <para>Non-Repeatable Reads means that the following anomaly can happen: A transaction re-reads - data it has previously read and finds that data has been modified by another transaction, one + <para>Non-Repeatable Reads means that the following anomaly can happen: A transaction reads + previously read data again and finds that data has been modified by another transaction, one that has been committed since the transaction's previous read. </para> - <para>Non-Repeatable reads are a problem for optimistic locking and therefore isolation level - READ_COMMITTED is not enough cause it allows for Non-Repeatable reads to occur. So + <para>Non-Repeatable reads are a problem for optimistic locking. Therefore, isolation level + READ_COMMITTED is not enough, as it allows for Non-Repeatable reads to occur. So REPEATABLE_READ is required if you configure more than one job executor thread. </para> </section> @@ -205,7 +205,7 @@ message remains in the queue without an exception so it will be retried later. </para> <para>Limitation: beware that jBPM's built-in asynchronous messaging system does - not support multinode locking. So you cannot just deploy the POJO command + not support multi-node locking. So you cannot just deploy the POJO command executor multiple times and have them configured to use the same database. </para> </section> Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/calendar.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/calendar.xml 2009-02-09 16:40:15 UTC (rev 3819) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/calendar.xml 2009-02-10 02:27:07 UTC (rev 3820) @@ -7,14 +7,14 @@ for tasks and timers.</para> <para>The business calendar is able to calculate a due date by adding a - duration to or subtracting it from a base date. If the base date is ommited, + duration to or subtracting it from a base date. If the base date is omitted, the 'current' date is used.</para> <section id="duedate"> <title>Duedate</title> <para>As mentioned the due date is composed of a duration and a base date. - If this base date is ommitted, the duration is relative to the date (and + If this base date is omitted, the duration is relative to the date (and time) at the moment of calculating the duedate. The format is:</para> <para><literal>duedate ::= [&lt;basedate&gt; +/-] @@ -63,7 +63,7 @@ <para>The following examples of the usage are all possible</para> - <programlisting>&lt;timer name="daysBeforeHoliday" duedate="5 business days"&gt;...&lt;/timer&gt; + <programlisting language="xml">&lt;timer name="daysBeforeHoliday" duedate="5 business days"&gt;...&lt;/timer&gt; &lt;timer name="pensionDate" duedate="#{dateOfBirth} + 65 years" &gt;...&lt;/timer&gt; Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/configuration.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/configuration.xml 2009-02-09 16:40:15 UTC (rev 3819) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/configuration.xml 2009-02-10 02:27:07 UTC (rev 3820) @@ -18,7 +18,7 @@ <literal>JbpmConfiguration.parseXxxx</literal> methods. </para> - <programlisting>static JbpmConfinguration jbpmConfiguration = JbpmConfinguration.parseResource("my.jbpm.cfg.xml");</programlisting> + <programlisting language="java">static JbpmConfiguration jbpmConfiguration = JbpmConfiguration.parseResource("my.jbpm.cfg.xml");</programlisting> <para>The JbpmConfiguration is threadsafe and hence can be kept in a static member. All threads can use the JbpmConfiguration as a factory for JbpmContext objects. A JbpmContext typically represents one @@ -26,7 +26,7 @@ A context block looks like this: </para> - <programlisting>JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); + <programlisting language="java">JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); try { // This is what we call a context block. // Here you can perform workflow operations @@ -44,7 +44,7 @@ <para>Here's the default configuration for the JbpmContext: </para> -<programlisting>&lt;jbpm-configuration&gt; +<programlisting language="xml">&lt;jbpm-configuration&gt; &lt;jbpm-context&gt; &lt;service name='persistence' factory='org.jbpm.persistence.db.DbPersistenceServiceFactory' /&gt; @@ -103,13 +103,13 @@ Then you update the reference in this file and jbpm will use your customized version of that configuration file. </para></listitem> - <listitem><para>The third part are some miscallanious configurations used in jbpm. + <listitem><para>The third part are some miscellaneous configurations used in jbpm. These configuration options are described in the chapters that cover the specific topic. </para></listitem> </itemizedlist> - <para>The default configured set of services is targetted at a simple webapp environment + <para>The default configured set of services is targeted at a simple web-app environment and minimal dependencies. The persistence service will obtain a jdbc connection and all the other services will use the same connection to perform their services. So all of your workflow operations are centralized into 1 transaction on a JDBC connection without the @@ -120,7 +120,7 @@ process operations: </para> -<programlisting> public void deployProcessDefinition(ProcessDefinition processDefinition) {...} +<programlisting language="java">public void deployProcessDefinition(ProcessDefinition processDefinition) {...} public List getTaskList() {...} public List getTaskList(String actorId) {...} public List getGroupTaskList(List actorIds) {...} @@ -138,7 +138,7 @@ <para>Note that the <literal>XxxForUpdate</literal> methods will register the loaded object for auto-save so that you don't have to call one of the save methods - explicitely. + explicitly. </para> <para>It's possible to specify multiple <literal>jbpm-context</literal>s, but then you have @@ -162,12 +162,11 @@ <para>A common mistake when customizing factories is to mix the short and the long notation. Examples of the short notation can be seen in the default configuration file and above: E.g. </para> - <programlisting> ... - &lt;service name='persistence' factory='org.jbpm.persistence.db.DbPersistenceServiceFactory' /&gt;</programlisting> + <programlisting language="xml">&lt;service name='persistence' factory='org.jbpm.persistence.db.DbPersistenceServiceFactory' /&gt;</programlisting> <para>If specific properties on a service need to be specified, the short notation can't be used, but instead, - the long notation has to be used like this: E.g. + the long notation has to be used like this: </para> - <programlisting> &lt;service name="persistence"&gt; + <programlisting language="xml"> &lt;service name="persistence"&gt; &lt;factory&gt; &lt;bean class="org.jbpm.persistence.db.DbPersistenceServiceFactory"&gt; &lt;field name="dataSourceJndiName"&gt;&lt;string value="java:/myDataSource"/&gt;&lt;/field&gt; @@ -203,12 +202,12 @@ </para> <section id="hibernatecfgxmlfile"> - <title>Hibernate cfg xml file</title> + <title>Hibernate Configuration file</title> <para>This file contains hibernate configurations and references to the hibernate mapping resource files.</para> <para>Location: <literal>hibernate.cfg.xml</literal> unless specified otherwise in the resource.hibernate.cfg.xml property in the jbpm.cfg.xml file. - In the jbpm project the default hibernate cfg xml file is located in + In the jbpm project the default hibernate configuration file is located in directory <literal>src/config.files/hibernate.cfg.xml</literal></para> </section> @@ -286,12 +285,12 @@ want to get rid of these stack traces, put the level of <literal>org.hibernate.event.def.AbstractFlushingEventListener</literal> to FATAL. If you use log4j following line of configuration can be used for that: - <programlisting>log4j.logger.org.hibernate.event.def.AbstractFlushingEventListener=FATAL</programlisting> + <programlisting language="xml">log4j.logger.org.hibernate.event.def.AbstractFlushingEventListener=FATAL</programlisting> </para> <para>If you want to enable logging of the jBPM stack traces, add the following line to your - jbpm.cfg.xml: - <programlisting>&lt;boolean name="jbpm.hide.stale.object.exceptions" value="false" /&gt;</programlisting>. + <filename>jbpm.cfg.xml</filename>: + <programlisting language="xml">&lt;boolean name="jbpm.hide.stale.object.exceptions" value="false" /&gt;</programlisting>. </para> </section> @@ -305,7 +304,7 @@ <para>In its simplest form, the object factory is able to create basic types and java beans from such a configuration: </para> - <programlisting>&lt;beans&gt; + <programlisting language="xml">&lt;beans&gt; &lt;bean name="task" class="org.jbpm.taskmgmt.exe.TaskInstance"/&gt; &lt;string name="greeting"&gt;hello world&lt;/string&gt; &lt;int name="answer"&gt;42&lt;/int&gt; @@ -331,7 +330,7 @@ <para>Also you can configure lists:</para> - <programlisting>&lt;beans&gt; + <programlisting language="xml">&lt;beans&gt; &lt;list name="numbers"&gt; &lt;string&gt;one&lt;/string&gt; &lt;string&gt;two&lt;/string&gt; @@ -341,7 +340,7 @@ <para>and maps</para> - <programlisting>&lt;beans&gt; + <programlisting language="xml">&lt;beans&gt; &lt;map name="numbers"&gt; &lt;entry&gt;&lt;key&gt;&lt;int&gt;1&lt;/int&gt;&lt;/key&gt;&lt;value&gt;&lt;string&gt;one&lt;/string&gt;&lt;/value&gt;&lt;/entry&gt; &lt;entry&gt;&lt;key&gt;&lt;int&gt;2&lt;/int&gt;&lt;/key&gt;&lt;value&gt;&lt;string&gt;two&lt;/string&gt;&lt;/value&gt;&lt;/entry&gt; @@ -351,7 +350,7 @@ <para>Beans can be configured with direct field injection and via property setters.</para> - <programlisting>&lt;beans&gt; + <programlisting language="xml">&lt;beans&gt; &lt;bean name="task" class="org.jbpm.taskmgmt.exe.TaskInstance" &gt; &lt;field name="name"&gt;&lt;string&gt;do dishes&lt;/string&gt;&lt;/field&gt; &lt;property name="actorId"&gt;&lt;string&gt;theotherguy&lt;/string&gt;&lt;/property&gt; @@ -362,14 +361,14 @@ it can be a string, integer or any other object. </para> - <programlisting>&lt;beans&gt; + <programlisting language="xml">&lt;beans&gt; &lt;bean name="a" class="org.jbpm.A" /> &lt;ref name="b" bean="a" /> &lt;/beans&gt;</programlisting> <para>Beans can be constructed with any constructor</para> - <programlisting>&lt;beans&gt; + <programlisting language="xml">&lt;beans&gt; &lt;bean name="task" class="org.jbpm.taskmgmt.exe.TaskInstance" &gt; &lt;constructor&gt; &lt;parameter class="java.lang.String"&gt; @@ -384,7 +383,7 @@ <para>... or with a factory method on a bean ...</para> - <programlisting>&lt;beans&gt; + <programlisting language="xml">&lt;beans&gt; &lt;bean name="taskFactory" class="org.jbpm.UnexistingTaskInstanceFactory" singleton="true"/&gt; @@ -403,7 +402,7 @@ <para>... or with a static factory method on a class ...</para> - <programlisting>&lt;beans&gt; + <programlisting language="xml">&lt;beans&gt; &lt;bean name="task" class="org.jbpm.taskmgmt.exe.TaskInstance" &gt; &lt;constructor factory-class="org.jbpm.UnexistingTaskInstanceFactory" method="createTask" &gt; &lt;parameter class="java.lang.String"&gt; Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/context.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/context.xml 2009-02-09 16:40:15 UTC (rev 3819) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/context.xml 2009-02-10 02:27:07 UTC (rev 3820) @@ -13,12 +13,12 @@ interface to work with process variables. You can obtain the ContextInstance from a ProcessInstance like this : </para> -<programlisting>ProcessInstance processInstance = ...; +<programlisting language="java">ProcessInstance processInstance = ...; ContextInstance contextInstance = (ContextInstance) processInstance.getInstance(ContextInstance.class);</programlisting> <para>The most basic operations are</para> -<programlisting>void ContextInstance.setVariable(String variableName, Object value); +<programlisting language="java">void ContextInstance.setVariable(String variableName, Object value); void ContextInstance.setVariable(String variableName, Object value, Token token); Object ContextInstance.getVariable(String variableName); Object ContextInstance.getVariable(String variableName, Token token);</programlisting> @@ -29,19 +29,19 @@ <para> <itemizedlist> - <listitem><literal>java.lang.String</literal></listitem> - <listitem><literal>java.lang.Boolean</literal></listitem> - <listitem><literal>java.lang.Character</literal></listitem> - <listitem><literal>java.lang.Float</literal></listitem> - <listitem><literal>java.lang.Double</literal></listitem> - <listitem><literal>java.lang.Long</literal></listitem> - <listitem><literal>java.lang.Byte</literal></listitem> - <listitem><literal>java.lang.Short</literal></listitem> - <listitem><literal>java.lang.Integer</literal></listitem> - <listitem><literal>java.util.Date</literal></listitem> - <listitem><literal>byte[]</literal></listitem> - <listitem><literal>java.io.Serializable</literal></listitem> - <listitem><literal>classes that are persistable with hibernate</literal></listitem> + <listitem><para><literal>java.lang.String</literal></para></listitem> + <listitem><para><literal>java.lang.Boolean</literal></para></listitem> + <listitem><para><literal>java.lang.Character</literal></para></listitem> + <listitem><para><literal>java.lang.Float</literal></para></listitem> + <listitem><para><literal>java.lang.Double</literal></para></listitem> + <listitem><para><literal>java.lang.Long</literal></para></listitem> + <listitem><para><literal>java.lang.Byte</literal></para></listitem> + <listitem><para><literal>java.lang.Short</literal></para></listitem> + <listitem><para><literal>java.lang.Integer</literal></para></listitem> + <listitem><para><literal>java.util.Date</literal></para></listitem> + <listitem><para><literal>byte[]</literal></para></listitem> + <listitem><para><literal>java.io.Serializable</literal></para></listitem> + <listitem><para><literal>classes that are able to be persisted with hibernate</literal></para></listitem> </itemizedlist> </para> @@ -66,7 +66,7 @@ <para>Variables can be deleted with</para> -<programlisting>ContextInstance.deleteVariable(String variableName); +<programlisting language="java">ContextInstance.deleteVariable(String variableName); ContextInstance.deleteVariable(String variableName, Token token);</programlisting> <para>Automatic changing of types is now supported. This means that it is allowed to @@ -90,27 +90,27 @@ <title>Variables scopes</title> <para>Each path of execution (read: token) has its own set of process variables. Requesting a variable is always done on a token. Process instances have a tree - of tokens (see <link linkend="graphorientedprogramming">graph oriented programming</link>). + of tokens (see <xref linkend="graphorientedprogramming"/>). When requesting a variable without specifying a token, the default token is the root token. </para> <para>The variable lookup is done recursively over the parents of the given - token. The behaviour is similar to the scoping of variables in programming + token. The behavior is similar to the scoping of variables in programming languages. </para> <para>When a non-existing variable is set on a token, the variable is created on the root-token. This means that each variable has by default process - scope. To make a variable token-local, you have to create it explicitely + scope. To make a variable token-local, you have to create it explicitly with:</para> -<programlisting>ContextInstance.createVariable(String name, Object value, Token token);</programlisting> +<programlisting language="java">ContextInstance.createVariable(String name, Object value, Token token);</programlisting> <section id="variableoverloading"> <title>Variables overloading</title> <para>Variable overloading means that each path of execution can have its - own copy of a variable with the same name. They are treated as independant + own copy of a variable with the same name. They are treated independently and hence can be of different types. Variable overloading can be interesting if you launch multiple concurrent paths of execution over the same transition. Then the only thing that distinguishes those paths @@ -152,11 +152,11 @@ <para>Because of their nature, transient variables are not related to a token. So there is only one map of transient variables for a process instance object.</para> - <para>The transient variables are accessable with their own set of methods + <para>The transient variables are accessible with their own set of methods in the context instance, and don't need to be declared in the processdefinition.xml</para> -<programlisting>Object ContextInstance.getTransientVariable(String name); +<programlisting language="java">Object ContextInstance.getTransientVariable(String name); void ContextInstance.setTransientVariable(String name, Object value);</programlisting> </section> @@ -165,9 +165,10 @@ <title>Customizing variable persistence</title> <para>Variables are stored in the database in a 2-step approach :</para> + + <!-- TODO: this should be a figure --> + <programlisting>user-java-object &lt;---&gt; converter &lt;---&gt; variable instance</programlisting> -<programlisting>user-java-object &lt;---&gt; converter &lt;---&gt; variable instance</programlisting> - <para>Variables are stored in <literal>VariableInstance</literal>s. The members of <literal>VariableInstance</literal>s are mapped to fields in the database with hibernate. In the default configuration of jBPM, @@ -208,14 +209,14 @@ <literal>Converter</literal>s are implementations of the following interface: </para> -<programlisting>public interface Converter extends Serializable { +<programlisting language="java">public interface Converter extends Serializable { boolean supports(Object value); Object convert(Object o); Object revert(Object o); }</programlisting> <para>Converters are optional. Converters must be available to - <link linkend="thejbpmclassloader">the jBPM class loader</link></para> + the jBPM class loader. See <xref linkend="thejbpmclassloader"/></para> <para>The way that user-java-objects are converted and stored in variable instances is configured in the file @@ -223,11 +224,11 @@ To customize this property file, put a modified version in the root of the classpath, as explained in <xref linkend="configurationfiles"/> Each line of the properties file specifies 2 or 3 class-names separated by spaces : - the classname of the user-java-object, optionally the classname of the converter - and the classname of the variable instance. When you refer your custom converters, - make sure they are in <link linkend="thejbpmclassloader">the jBPM class path</link>. + the class name of the user-java-object, optionally the class name of the converter + and the class name of the variable instance. When you refer your custom converters, + make sure they are in the jBPM class path (see <xref linkend="thejbpmclassloader"/>). When you refer to your custom variable instances, they also have to be in - the <link linkend="thejbpmclassloader">the jBPM class path</link> and the hibernate + the the jBPM class path and the hibernate mapping file for <literal>org/jbpm/context/exe/VariableInstance.hbm.xml</literal> has to be updated to include the custom subclass of VariableInstance. </para> @@ -235,7 +236,7 @@ <para>For example, take a look at the following xml snippet in the file <literal>org/jbpm/context/exe/jbpm.varmapping.xml</literal>.</para> -<programlisting> &lt;jbpm-type&gt; +<programlisting language="xml"> &lt;jbpm-type&gt; &lt;matcher&gt; &lt;bean class="org.jbpm.context.exe.matcher.ClassNameMatcher"&gt; &lt;field name="className"&gt;&lt;string value="java.lang.Boolean" /&gt;&lt;/field&gt; @@ -252,7 +253,7 @@ <para>If no converter is specified as in</para> -<programlisting> &lt;jbpm-type&gt; +<programlisting language="xml"> &lt;jbpm-type&gt; &lt;matcher&gt; &lt;bean class="org.jbpm.context.exe.matcher.ClassNameMatcher"&gt; &lt;field name="className"&gt;&lt;string value="java.lang.Long" /&gt;&lt;/field&gt; Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/database.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/database.xml 2009-02-09 16:40:15 UTC (rev 3819) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/database.xml 2009-02-10 02:27:07 UTC (rev 3820) @@ -22,7 +22,7 @@ location on your machine named ${jbpm-jpdl-home}. You will find the DB subproject of jBPM in the ${jbpm-jpdl-home}/db.</para> - <para>After installing the of your choice database, you will have to run + <para>After installing the database of your choice, you will have to run the database creation scripts to create the jBPM tables. Note that in the hsqldb inside jboss this is done automatically during installation. </para> @@ -30,7 +30,7 @@ <title>Isolation level</title> <para>Whatever database that you use, make sure that the isolation level of the configured JDBC connection is at least READ_COMMITTED, as explained - in <xref linkend="isolationlevelofthejdbcconnection"/> + in <xref linkend="isolationlevelofthejdbcconnection"/>. </para> </section> @@ -132,7 +132,7 @@ consoles</para> <section> - <title>Creating the JBoss jBPM Database with PostGreSQL</title> + <title>Creating the JBoss jBPM Database with PostgreSQL</title> <para>As already mentioned you will find the database scripts for a lot of the supported databases in the DB subproject. The database @@ -154,7 +154,7 @@ </mediaobject> </figure> - <para>To execution this script with DBVisualizer, you select + <para>To execute this script with DBVisualizer, you select 'Database-&gt;Execute'. After this step all JBoss jBPM tables are created. The situation is illustrated in the figure below.</para> @@ -191,14 +191,14 @@ scripts. Open a DOS box or terminal window and type the following command:</para> - <programlisting> mysql -u root -p </programlisting> + <screen>$ mysql -u root -p </screen> <para>You will be prompted for your MySQL password for the root account or whatever account you are using to modify this database. After logging in, type the following command to use the newly created jbpmdb:</para> - <programlisting>use jbpmdb </programlisting> + <screen>use jbpmdb </screen> <figure> <title>Loading the database create scripts for MySQL</title> @@ -213,9 +213,9 @@ <para>Now you can load the database script for jBPM by executing the following command:</para> - <programlisting>source mysql.drop.create.sql </programlisting> + <screen>source mysql.drop.create.sql </screen> - <para>Once the script executes, you should have the folling output in + <para>Once the script executes, you should have the following output in the MySQL command window:</para> <figure> @@ -234,7 +234,7 @@ <title>Last Steps</title> <para>After these steps, there is not yet any data present in the - tables. For the jBPM webapp to work, you should at least create some + tables. For the jBPM web app to work, you should at least create some records in the jbpm_id_user table. In order to have exactly the same entries in this table as the default distribution of the starter's kit running on HSQLDB, we suggest to run the script below.</para> @@ -253,7 +253,7 @@ <title>Update the JBoss jBPM Server Configuration</title> <para>Before we can really use our newly created database with the JBoss - jBPM default webapp we will have to do some updates to the JBoss jBPM + jBPM default web app we will have to do some updates to the JBoss jBPM configuration. The location of the jbpm server configuration is <literal>${jboss-home}/server/default/deploy/jbpm</literal>. </para> @@ -282,9 +282,7 @@ <para>For MySQL, the datasource definition would look as follows:</para> - <programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt; - -&lt;datasources&gt; + <programlisting language="xml">&lt;datasources&gt; &lt;local-tx-datasource&gt; &lt;jndi-name&gt;JbpmDS&lt;/jndi-name&gt; &lt;connection-url&gt;jdbc:mysql://localhost:3306/jbpmdb&lt;/connection-url&gt; @@ -307,7 +305,7 @@ We already used this JDBC driver above when we were installing it in DBVisualizer to be able to browse our newly created database. The file is named <literal>postgresql-8.1-*.jdbc3.jar</literal> and it can be found in the jdbc - subfolder of your PostgreSQL installation folder.</para> + subdirectory of your PostgreSQL installation folder.</para> <para>For MySQL, copy the jdbc driver installed from the MySQL ConnectorJ package. The version you need to use is currently the MySQL @@ -331,13 +329,7 @@ using. You can get a list of supported database Dialect types from here http://www.hibernate.org/hib_docs/v3/reference/en/html/session-configurat... - <programlisting>&lt;?xml version='1.0' encoding='utf-8'?&gt; - -&lt;!DOCTYPE hibernate-configuration PUBLIC - "-//Hibernate/Hibernate Configuration DTD 3.0//EN" - "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd"&gt; - -&lt;hibernate-configuration&gt; + <programlisting language="xml">&lt;hibernate-configuration&gt; &lt;session-factory&gt; &lt;!-- jdbc connection properties --&gt; @@ -360,7 +352,7 @@ &lt;/session-factory&gt; &lt;/hibernate-configuration&gt;</programlisting> - <para>Now we are ready to fire up the server, and look if the webapp + <para>Now we are ready to fire up the server, and look if the web app works. You will not be able to start any processes yet, as there are no processes deployed yet. To do this we refer to the document on process definition deployment.</para> Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/deployment.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/deployment.xml 2009-02-09 16:40:15 UTC (rev 3819) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/deployment.xml 2009-02-10 02:27:07 UTC (rev 3820) @@ -42,9 +42,11 @@ </para> <table frame="topbot" id="minimal.dependencies.table"> + <title>Minimal Dependencies</title> <tgroup cols="3" rowsep="1" colsep="1"> <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="2*"/> <thead> <row> <entry align="center">Library</entry> @@ -60,7 +62,7 @@ library can be configured to dispatch the logs to e.g. java 1.4 logging, log4j, ... See <ulink url="http://jakarta.apache.org/commons/logging/guide.html"> - the apache commons user guide</ulink> for more information on how + the Apache commons user guide</ulink> for more information on how to configure commons logging. if you're used to log4j, the easiest way is to put the log4j lib and a log4j.properties in the classpath. commons logging will automatically detect this and use that configuration. @@ -80,16 +82,18 @@ not have any dependencies outside hibernate and its dependent libraries. </para> - <para>Of course, hibernate's required libraries depend on the environment + <para>Of course, Hibernate's required libraries depend on the environment and what features you use. For details refer to the hibernate documentation. The next table gives an indication for a plain standalone POJO development environment. </para> <table frame="topbot" id="typical.dependencies.table"> + <title>Typical Dependencies</title> <tgroup cols="3" rowsep="1" colsep="1"> <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="2*"/> <thead> <row> <entry align="center">Library</entry> @@ -134,9 +138,11 @@ </para> <table frame="topbot" id="optional.dependencies.table"> + <title>Optional Dependencies</title> <tgroup cols="3" rowsep="1" colsep="1"> <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="2*"/> <thead> <row> <entry align="center">Library</entry> @@ -184,27 +190,29 @@ <literal>jboss-{version}/server/default/config/log4j.xml</literal> Look for </para> - <programlisting> &lt;!-- ============================== --&gt; - &lt;!-- Append messages to the console --&gt; - &lt;!-- ============================== --&gt; + <programlisting language="xml">&lt;!-- ============================== --&gt; +&lt;!-- Append messages to the console --&gt; +&lt;!-- ============================== --&gt; - &lt;appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender"&gt; - &lt;errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/&gt; - &lt;param name="Target" value="System.out"/&gt; - &lt;param name="Threshold" value="INFO"/&gt;</programlisting> - <para>And in param <literal>Threshold</literal>, change <literal>INFO</literal> to +&lt;appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender"&gt; + &lt;errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/&gt; + &lt;param name="Target" value="System.out"/&gt; + &lt;param name="Threshold" value="INFO"/&gt;</programlisting> + + <para>And in param <literal>Threshold</literal>, change <literal>INFO</literal> to <literal>DEBUG</literal>. </para> <para>Then you'll get debug logs of all the components. To limit the number of debug logs, look a bit further down that file until you see 'Limit categories'. You might want to add - tresholds there for specific packages like e.g. </para> - <programlisting> &lt;category name="org.hibernate"&gt; - &lt;priority value="INFO"/&gt; - &lt;/category&gt; + thresholds there for specific packages like e.g. </para> + + <programlisting language="xml">&lt;category name="org.hibernate"&gt; + &lt;priority value="INFO"/&gt; +&lt;/category&gt; - &lt;category name="org.jboss"&gt; - &lt;priority value="INFO"/&gt; - &lt;/category&gt;</programlisting> +&lt;category name="org.jboss"&gt; + &lt;priority value="INFO"/&gt; +&lt;/category&gt;</programlisting> </section> <section id="debuggingaprocessinthesuite"> Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/developers.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/developers.xml 2009-02-09 16:40:15 UTC (rev 3819) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/developers.xml 2009-02-10 02:27:07 UTC (rev 3820) @@ -20,8 +20,8 @@ <title>Building the docs</title> <para>Building the docs requires a separate module to be put besides the jbpm.3 home directory: <literal>docbook-support</literal>. - This module can be found in the public jboss anonymous accessible + This module can be found in the public JBoss anonymous accessible cvs repository : TODO</para> </section> -</chapter> \ No newline at end of file +</chapter> Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/introduction.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/introduction.xml 2009-02-09 16:40:15 UTC (rev 3819) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/introduction.xml 2009-02-10 02:27:07 UTC (rev 3820) @@ -22,7 +22,7 @@ database.</para> <figure id="overview.image"> <title>Overview of the jPDL components</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/overview.gif"/></imageobject></mediaobject> + <mediaobject><imageobject><imagedata align="center" fileref="images/overview.png"/></imageobject></mediaobject> </figure> </section> @@ -32,30 +32,30 @@ download. The download includes: </para> <itemizedlist> - <listitem><emphasis role="bold">config</emphasis>, configuration files for a standard java environment</listitem> - <listitem><emphasis role="bold">db</emphasis>, SQL scripts for DB creation and compatibility information</listitem> - <listitem><emphasis role="bold">designer</emphasis>, the eclipse plugin to author jPDL processes and installation scripts (this is not part of the plain jpdl download) See also <xref linkend="jpdlgraphicalprocessdesigner"/>.</listitem> - <listitem><emphasis role="bold">doc</emphasis>, userguide and javadocs</listitem> - <listitem><emphasis role="bold">examples</emphasis></listitem> - <listitem><emphasis role="bold">lib</emphasis>, libraries on which jbpm depends. For more information on this see <xref linkend="thirdpartylibraries" /></listitem> - <listitem><emphasis role="bold">server</emphasis>, a preconfigured jboss that contains jbpm inside the console web application (this is not part of the plain jpdl download)</listitem> - <listitem><emphasis role="bold">src</emphasis>, the jbpm and identity component java sources</listitem> + <listitem><para><emphasis role="bold">config</emphasis>, configuration files for a standard java environment</para></listitem> + <listitem><para><emphasis role="bold">db</emphasis>, SQL scripts for DB creation and compatibility information</para></listitem> + <listitem><para><emphasis role="bold">designer</emphasis>, the eclipse plugin to author jPDL processes and installation scripts (this is not part of the plain jpdl download) See also <xref linkend="jpdlgraphicalprocessdesigner"/>.</para></listitem> + <listitem><para><emphasis role="bold">doc</emphasis>, userguide and javadocs</para></listitem> + <listitem><para><emphasis role="bold">examples</emphasis></para></listitem> + <listitem><para><emphasis role="bold">lib</emphasis>, libraries on which jbpm depends. For more information on this see <xref linkend="thirdpartylibraries" /></para></listitem> + <listitem><para><emphasis role="bold">server</emphasis>, a pre-configured jboss that contains jbpm inside the console web application (this is not part of the plain jpdl download)</para></listitem> + <listitem><para><emphasis role="bold">src</emphasis>, the jbpm and identity component java sources</para></listitem> </itemizedlist> - <para>The preconfigured JBoss application server has the following components installed : + <para>The pre-configured JBoss application server has the following components installed : </para> <itemizedlist> - <listitem>The <emphasis role="bold">web console</emphasis>, packaged as a web archive. That console can be - used by process participants as well as jBPM administrators.</listitem> - <listitem>The <emphasis role="bold">job executor</emphasis> enacts timers and asynchronous messages. There is + <listitem><para>The <emphasis role="bold">web console</emphasis>, packaged as a web archive. That console can be + used by process participants as well as jBPM administrators.</para></listitem> + <listitem><para>The <emphasis role="bold">job executor</emphasis> enacts timers and asynchronous messages. There is a servlet context listener in the console web app that launches the job executor, which - spawns a thread pool for monitoring and executing timers and asynchronous messages.</listitem> - <listitem>The <emphasis role="bold">jBPM database</emphasis>, an in-process hypersonic database that - contains the jBPM tables.</listitem> - <listitem>One <emphasis role="bold">example process</emphasis> is already deployed into the jBPM database.</listitem> - <listitem>The <emphasis role="bold">Identity component</emphasis> libraries are part of + spawns a thread pool for monitoring and executing timers and asynchronous messages.</para></listitem> + <listitem><para>The <emphasis role="bold">jBPM database</emphasis>, an in-process hypersonic database that + contains the jBPM tables.</para></listitem> + <listitem><para>One <emphasis role="bold">example process</emphasis> is already deployed into the jBPM database.</para></listitem> + <listitem><para>The <emphasis role="bold">Identity component</emphasis> libraries are part of the console web application. The tables of the identity component are available in the database (those are the tables - that start with JBPM_ID_)</listitem> + that start with JBPM_ID_)</para></listitem> </itemizedlist> </section> @@ -66,7 +66,7 @@ <para>The most important feature of the graphical designer tool is that it includes support for both the business analyst as well as the technical developer. This enables a smooth transition from business process - modelling to the practical implementation.</para> + modeling to the practical implementation.</para> <para>The plugin is available as a local update site (plain zip file) for installation via the standard eclipse software updates mechanism. The jPDL graphical process designer plugin is also included in @@ -83,7 +83,7 @@ executions. Secondly, it is an administration and monitoring console that allows to inspect and manipulate runtime instances. The third functionality is Business Activity Monitoring. These are statistics about process executions. This is useful information - for managers to find bottlenecks or other kinds of optimisations.</para> + for managers to find bottlenecks or other kinds of optimizations.</para> </section> <section> @@ -92,13 +92,13 @@ process definitions and the runtime environment for execution of process instances. </para> <para>JBoss jBPM is a java library. As a consequence, it can be used in any java - environment like e.g. a webapplication, a swing application, an EJB, a webservice,... + environment like e.g. a web application, a swing application, an EJB, a webservice,... The jBPM library can also be packaged and exposed as a stateless session EJB. This allows clustered deployment and scalability for extreme high throughput. The stateless session EJB will be written against the J2EE 1.4 specifications so that it is deployable on any application server. </para> - <para>Depending on the functionalities that you use, the library <literal>lib/jbpm-jpdl.jar</literal> + <para>Depending on the functionality that you use, the library <literal>lib/jbpm-jpdl.jar</literal> has some dependencies on other third party libraries such as e.g. hibernate, dom4j and others. We have done great efforts to require only those dependent libraries that you actually use. The dependencies are further documented in <xref linkend="deployment" /></para> @@ -113,9 +113,9 @@ <section> <title>The JBoss jBPM identity component</title> <para>JBoss jBPM can integrate with any company directory that contains users and other - organisational information. But for projects where no organisational information component + organizational information. But for projects where no organizational information component is readily available, JBoss jBPM includes this component. The model used in the identity - component is richer then the traditional servlet-, ejb- and portlet models.</para> + component is richer than the traditional servlet-, ejb- and portlet models.</para> <para>For more information, see <xref linkend="theidentitycomponent" /></para> </section> Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/jpdl.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/jpdl.xml 2009-02-09 16:40:15 UTC (rev 3819) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/jpdl.xml 2009-02-10 02:27:07 UTC (rev 3820) @@ -20,13 +20,13 @@ </para> <para>Deploying a process archive with the designer tool is supported in the starters-kit. Right click on the process archive folder to find the "Deploy process archive" option. - The starters-kit server contains the jBPM webapp, which has a servlet to upload + The starters-kit server contains the jBPM web application, which has a servlet to upload process archives called ProcessUploadServlet. This servlet is capable of uploading process archives and deploying them to the default jBPM instance configured. </para> <para>Deploying a process archive with an ant task can be done as follows: </para> - <programlisting>&lt;target name="deploy.par"&gt; + <programlisting language="xml">&lt;target name="deploy.par"&gt; &lt;taskdef name="deploypar" classname="org.jbpm.ant.DeployProcessTask"&gt; &lt;classpath --make sure the jbpm-[version].jar is in this classpath--/&gt; &lt;/taskdef&gt; @@ -35,13 +35,13 @@ <para>To deploy more process archives at once, use the nested fileset elements. The file attribute itself is optional. Other attributes of the ant task are:</para> <itemizedlist> - <listitem><emphasis role="bold">cfg</emphasis>: cfg is optional, the default value + <listitem><para><emphasis role="bold">cfg</emphasis>: cfg is optional, the default value is 'hibernate.cfg.xml'. The hibernate configuration file that contains the jdbc - connection properties to the database and the mapping files.</listitem> - <listitem><emphasis role="bold">properties</emphasis>: properties is optional and - overwrites *all* hibernate properties as found in the hibernate.cfg.xml</listitem> - <listitem><emphasis role="bold">createschema</emphasis>: if set to true, the jbpm - database schema is created before the processes get deployed.</listitem> + connection properties to the database and the mapping files.</para></listitem> + <listitem><para><emphasis role="bold">properties</emphasis>: properties is optional and + overwrites *all* hibernate properties as found in the hibernate.cfg.xml</para></listitem> + <listitem><para><emphasis role="bold">createschema</emphasis>: if set to true, the jbpm + database schema is created before the processes get deployed.</para></listitem> </itemizedlist> <para>Process archives can also be deployed programmatically with the class <literal>org.jbpm.jpdl.par.ProcessArchiveDeployer</literal> </para> @@ -61,7 +61,7 @@ that same process definition for its complete lifetime. When a newer version is deployed, newly created instances will be started in the newest version, while older process instances keep on executing in the older process - defintions.</para> + definitions.</para> <para>If the process includes references to Java classes, the java classes can be made available to the jBPM runtime environment in 2 ways : by making sure these @@ -96,13 +96,13 @@ are harmless, but some other changes have implications far beyond the expected and desirable. </para> - <para>So please consider <link linkend="migratingprocessinstances">migrating - process instances</link> to a new definition over this approach. + <para>So please consider migrating + process instances to a new definition (see <xref linkend="migratingprocessinstances"/>)over this approach. </para> <para>In case you would consider it, these are the points to take into consideration: </para> - <para><emphasis role="bold">Use hibernate's update</emphasis>: You can + <para><emphasis role="bold">Use Hibernate's update</emphasis>: You can just load a process definition, change it and save it with the hibernate session. The hibernate session can be accessed with the method <literal>JbpmContext.getSession()</literal>. @@ -151,7 +151,7 @@ Meaning, the classloader that has the library <literal>jbpm-3.x.jar</literal> in its classpath. To make classes visible to the jBPM classloader, put them in a jar file and put the jar file besides the <literal>jbpm-3.x.jar</literal>. - E.g. in the WEB-INF/lib folder in the case of webapplications. + E.g. in the WEB-INF/lib folder in the case of web applications. </para> </section> @@ -170,9 +170,9 @@ from the <literal>/classes</literal> directory in the process archive. If you want to load resources outside of the classes directory, start with a double slash (<literal> // </literal>). For example - to load resource <literal>data.xml</literal> wich is located next to the + to load resource <literal>data.xml</literal> which is located next to the processdefinition.xml on the root of the process archive file, you can do - <literal>clazz.getResource("//data.xml")</literal> or + <literal>class.getResource("//data.xml")</literal> or <literal>classLoader.getResourceAsStream("//data.xml")</literal> or any of those variants. </para> @@ -187,39 +187,39 @@ be called on an event in the process. Delegations are specified in the <literal>processdefinition.xml</literal>. 3 pieces of data can be supplied when specifying a delegation : </para> - <itemizedlist> - <listitem>1) the class name (required) : the fully qualified class name of the - delegation class.</listitem> - <listitem>2) configuration type (optional) : specifies the way to instantiate + <orderedlist> + <listitem><para>the class name (required) : the fully qualified class name of the + delegation class.</para></listitem> + <listitem><para>configuration type (optional) : specifies the way to instantiate and configure the delegation object. By default the default - constructor is used and the configuration information is ignored.</listitem> - <listitem>3) configuration (optional) : the configuration of the delegation - object in the format as required by the configuration type.</listitem> - </itemizedlist> + constructor is used and the configuration information is ignored.</para></listitem> + <listitem><para>configuration (optional) : the configuration of the delegation + object in the format as required by the configuration type.</para></listitem> + </orderedlist> <para>Next is a description of all the configuration types:</para> <section id="configtypefield"> <title>config-type field</title> <para>This is the default configuration type. The <literal>config-type field</literal> will first instantiate an object of the delegation class and then set values in the fields of the object as specified in the configuration. The configuration is xml, where the - elementnames have to correspond with the field names of the class. The content + element names have to correspond with the field names of the class. The content text of the element is put in the corresponding field. If necessary and possible, the content text of the element is converted to the field type. </para> <para>Supported type conversions:</para> <itemizedlist> - <listitem>String doesn't need converting, of course. But it is trimmed. + <listitem><para>String doesn't need converting, of course. But it is trimmed.</para> </listitem> - <listitem>primitive types such as int, long, float, double, ... + <listitem><para>primitive types such as int, long, float, double, ...</para> </listitem> - <listitem>and the basic wrapper classes for the primitive types. + <listitem><para>and the basic wrapper classes for the primitive types.</para> </listitem> - <listitem>lists, sets and collections. In that case each element of the - xml-content is consitered as an element of the collection and is parsed, recursively applying the + <listitem><para>lists, sets and collections. In that case each element of the + xml-content is considered as an element of the collection and is parsed, recursively applying the conversions. If the type of the elements is different from <literal>java.lang.String</literal> this can be indicated by specifying a type attribute with the fully qualified type name. - For example, following snippet will inject an ArrayList of Strings into field 'numbers': - <programlisting>&lt;numbers&gt; + For example, following snippet will inject an ArrayList of Strings into field 'numbers':</para> + <programlisting language="xml">&lt;numbers&gt; &lt;element&gt;one&lt;/element&gt; &lt;element&gt;two&lt;/element&gt; &lt;element&gt;three&lt;/element&gt; @@ -230,31 +230,31 @@ </para> <para>Here's another example of a map: </para> - <programlisting>&lt;numbers&gt; + <programlisting language="xml">&lt;numbers&gt; &lt;entry&gt;&lt;key&gt;one&lt;/key&gt;&lt;value&gt;1&lt;/value&gt;&lt;/entry&gt; &lt;entry&gt;&lt;key&gt;two&lt;/key&gt;&lt;value&gt;2&lt;/value&gt;&lt;/entry&gt; &lt;entry&gt;&lt;key&gt;three&lt;/key&gt;&lt;value&gt;3&lt;/value&gt;&lt;/entry&gt; &lt;/numbers&gt;</programlisting> </listitem> - <listitem>maps. In this case, each element of the field-element is expected to have one subelement + <listitem><para>maps. In this case, each element of the field-element is expected to have one sub-element <literal>key</literal> and one element <literal>value</literal>. The key and element are both parsed using the conversion rules recursively. Just the same as with collections, a conversion to - <literal>java.lang.String</literal> is assumed if no <literal>type</literal> attribute is specified. + <literal>java.lang.String</literal> is assumed if no <literal>type</literal> attribute is specified.</para> </listitem> - <listitem>org.dom4j.Element + <listitem><para>org.dom4j.Element</para> </listitem> - <listitem>for any other type, the string constructor is used. + <listitem><para>for any other type, the string constructor is used.</para> </listitem> </itemizedlist> <para>For example in the following class...</para> - <programlisting>public class MyAction implements ActionHandler { + <programlisting language="java">public class MyAction implements ActionHandler { // access specifiers can be private, default, protected or public private String city; Integer rounds; ... }</programlisting> <para>...this is a valid configuration:</para> - <programlisting>... + <programlisting language="xml">... &lt;action class="org.test.MyAction"&gt; &lt;city&gt;Atlanta&lt;/city&gt; &lt;rounds&gt;5&lt;/rounds&gt; @@ -299,18 +299,18 @@ be used as starting variables along with the following implicit objects: </para> <itemizedlist> - <listitem>taskInstance (org.jbpm.taskmgmt.exe.TaskInstance)</listitem> - <listitem>processInstance (org.jbpm.graph.exe.ProcessInstance)</listitem> - <listitem>processDefinition (org.jbpm.graph.def.ProcessDefinition)</listitem> - <listitem>token (org.jbpm.graph.exe.Token)</listitem> - <listitem>taskMgmtInstance (org.jbpm.taskmgmt.exe.TaskMgmtInstance)</listitem> - <listitem>contextInstance (org.jbpm.context.exe.ContextInstance)</listitem> + <listitem><para>taskInstance (org.jbpm.taskmgmt.exe.TaskInstance)</para></listitem> + <listitem><para>processInstance (org.jbpm.graph.exe.ProcessInstance)</para></listitem> + <listitem><para>processDefinition (org.jbpm.graph.def.ProcessDefinition)</para></listitem> + <listitem><para>token (org.jbpm.graph.exe.Token)</para></listitem> + <listitem><para>taskMgmtInstance (org.jbpm.taskmgmt.exe.TaskMgmtInstance)</para></listitem> + <listitem><para>contextInstance (org.jbpm.context.exe.ContextInstance)</para></listitem> </itemizedlist> - <para>This feature becomes really powerfull in a JBoss SEAM environment. + <para>This feature becomes really powerful in a JBoss SEAM environment. Because of the integration between jBPM and <ulink url="http://www.jboss.com/products/seam">JBoss SEAM</ulink>, all of your backed beans, EJB's and other <literal>one-kind-of-stuff</literal> becomes available right - inside of your process definition. Thanks Gavin ! Absolutely awsome ! :-) + inside of your process definition. Thanks Gavin ! Absolutely awesome ! :-) </para> </section> @@ -325,10 +325,10 @@ jPDL schema when two conditions are met: first, the schema has to be referenced in the XML document like this </para> - <programlisting>&lt;process-definition xmlns=&quot;urn:jbpm.org:jpdl-3.2&quot;&gt; + <programlisting language="xml">&lt;process-definition xmlns=&quot;urn:jbpm.org:jpdl-3.2&quot;&gt; ... &lt;/process-definition&gt;</programlisting> - <para>And second, the xerces parser has to be on the classpath.</para> + <para>And second, the Xerces parser has to be on the classpath.</para> <para>The jPDL schema can be found in <literal>${jbpm.home}/src/java.jbpm/org/jbpm/jpdl/xml/jpdl-3.2.xsd</literal> or at <ulink url="http://jbpm.org/jpdl-3.2.xsd">http://jbpm.org/jpdl-3.2....;. </para> @@ -337,9 +337,12 @@ <section id="processdefinition.element"> <title>process-definition</title> <table id="process.definition.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Process Definition Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -356,51 +359,51 @@ <entry>the name of the process</entry> </row> <row> - <entry><link linkend="swimlane.element">swimlane</link></entry> + <entry>swimlane<footnote><para><xref linkend="swimlane.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..*]</entry> <entry>the swimlanes used in this process. The swimlanes represent process roles and they are used for task assignments.</entry> </row> <row> - <entry><link linkend="startstate.element">start-state</link></entry> + <entry>start-state<footnote><para><xref linkend="startstate.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..1]</entry> <entry>the start state of the process. Note that a process without a start-state is valid, but cannot be executed.</entry> </row> <row> - <entry>{<link linkend="endstate.element">end-state</link>|<link linkend="state.element">state</link>|<link linkend="node.element">node</link>|<link linkend="tasknode.element">task-node</link>|<link linkend="processstate.element">process-state</link>|<link linkend="superstate.element">super-state</link>|<link linkend="fork.element">fork</link>|<link linkend="join.element">join</link>|<link linkend="decision.element">decision</link>}</entry> + <entry>task<footnote><para><xref linkend="task.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>the nodes of the process definition. Note that a process without nodes is valid, but - cannot be executed.</entry> + <entry>global defined tasks that can be used in e.g. actions.</entry> </row> <row> - <entry><link linkend="event.element">event</link></entry> + <entry>exception-handler<footnote><para><xref linkend="exceptionhandler.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>the process events that serve as a container for actions</entry> + <entry>a list of exception handlers that applies to all + exceptions thrown by delegation classes thrown in this process definition.</entry> </row> <row> - <entry>{<link linkend="action.element">action</link>|<link linkend="script.element">script</link>|<link linkend="create.timer.element">create-timer</link>|<link linkend="cancel.timer.element">cancel-timer</link>}</entry> + <entry>{end-state <footnote><para><xref linkend="endstate.element"/>.</para></footnote>|state<footnote><para><xref linkend="state.element"/>.</para></footnote>|node<footnote><para><xref linkend="node.element"/>.</para></footnote>|task-node<footnote><para><xref linkend="tasknode.element"/>.</para></footnote>|process-state<footnote><para><xref linkend="processstate.element"/>.</para></footnote>|super-state<footnote><para><xref linkend="superstate.element"/>.</para></footnote>|fork<footnote><para><xref linkend="fork.element"/>.</para></footnote>|join<footnote><para><xref linkend="join.element"/>.</para></footnote>|decision<footnote><para><xref linkend="decision.element"/>.</para></footnote>}</entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>global defined actions that can be referenced from events and transitions. Note that - these actions must specify a name in order to be referenced.</entry> + <entry>the nodes of the process definition. Note that a process without nodes is valid, but + cannot be executed.</entry> </row> <row> - <entry><link linkend="task.element">task</link></entry> + <entry>event<footnote><para><xref linkend="event.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>global defined tasks that can be used in e.g. actions.</entry> + <entry>the process events that serve as a container for actions</entry> </row> <row> - <entry><link linkend="exceptionhandler.element">exception-handler</link></entry> + <entry>{action<footnote><para><xref linkend="action.element"/>.</para></footnote>|script<footnote><para><xref linkend="script.element"/>.</para></footnote>|create-timer<footnote><para><xref linkend="create.timer.element"/>.</para></footnote>|cancel-timer<footnote><para><xref linkend="cancel.timer.element"/>.</para></footnote>}</entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>a list of exception handlers that applies to all - exceptions thrown by delegation classes thrown in this process definition.</entry> + <entry>global defined actions that can be referenced from events and transitions. Note that + these actions must specify a name in order to be referenced.</entry> </row> </tbody> </tgroup> @@ -410,9 +413,12 @@ <section id="node.element"> <title>node</title> <table frame="topbot" id="node.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Node Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -423,16 +429,16 @@ </thead> <tbody> <row> - <entry>{<link linkend="action.element">action</link>|<link linkend="script.element">script</link>|<link linkend="create.timer.element">create-timer</link>|<link linkend="cancel.timer.element">cancel-timer</link>}</entry> + <entry>{action<footnote><para><xref linkend="action.element"/>.</para></footnote>|script<footnote><para><xref linkend="script.element"/>.</para></footnote>|create-timer<footnote><para><xref linkend="create.timer.element"/>.</para></footnote>|cancel-timer<footnote><para><xref linkend="cancel.timer.element"/>.</para></footnote>}</entry> <entry>element</entry> <entry>1</entry> - <entry>a custom action that represents the behaviour for this node</entry> + <entry>a custom action that represents the behavior for this node</entry> </row> <row> - <entry><link linkend="common.node.elements">common node elements</link></entry> + <entry>common node elements<footnote><para><xref linkend="common.node.elements"/>.</para></footnote></entry> <entry></entry> <entry></entry> - <entry>See <link linkend="common.node.elements">common node elements</link></entry> + <entry>See <xref linkend="common.node.elements"/></entry> </row> </tbody> </tgroup> @@ -442,9 +448,12 @@ <section id="common.node.elements"> <title>common node elements</title> <table frame="topbot" id="common.node.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Common Node Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -469,30 +478,30 @@ </entry> </row> <row> - <entry><link linkend="transition.element">transition</link></entry> + <entry>transition<footnote><para><xref linkend="transition.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..*]</entry> <entry>the leaving transitions. Each transition leaving a node *must* have a distinct name. A maximum of one of the leaving transitions is - allowed to have no name. The first transition that is specifed is called + allowed to have no name. The first transition that is specified is called the default transition. The default transition is taken when the node is left without specifying a transition.</entry> </row> <row> - <entry><link linkend="event.element">event</link></entry> + <entry>event<footnote><para><xref linkend="event.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..*]</entry> <entry>supported event types: {node-enter|node-leave}</entry> </row> <row> - <entry><link linkend="exceptionhandler.element">exception-handler</link></entry> + <entry>exception-handler<footnote><para><xref linkend="exceptionhandler.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..*]</entry> <entry>a list of exception handlers that applies to all exceptions thrown by delegation classes thrown in this process node.</entry> </row> <row> - <entry><link linkend="timer.element">timer</link></entry> + <entry>timer<footnote><para><xref linkend="timer.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..*]</entry> <entry>specifies a timer that monitors the duration of an execution in this node.</entry> @@ -505,9 +514,12 @@ <section id="startstate.element"> <title>start-state</title> <table frame="topbot" id="start.state.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Start State Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -524,26 +536,26 @@ <entry>the name of the node</entry> </row> <row> - <entry><link linkend="task.element">task</link></entry> + <entry>task<footnote><para><xref linkend="task.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..1]</entry> <entry>the task to start a new instance for this process or to capture the process initiator. See <xref linkend="swimlaneinstarttask"/></entry> </row> <row> - <entry><link linkend="event.element">event</link></entry> + <entry>event<footnote><para><xref linkend="event.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..*]</entry> <entry>supported event types: {node-leave}</entry> </row> <row> - <entry><link linkend="transition.element">transition</link></entry> + <entry>transition<footnote><para><xref linkend="transition.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..*]</entry> <entry>the leaving transitions. Each transition leaving a node *must* have a distinct name.</entry> </row> <row> - <entry><link linkend="exceptionhandler.element">exception-handler</link></entry> + <entry>exception-handler<footnote><para><xref linkend="exceptionhandler.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..*]</entry> <entry>a list of exception handlers that applies to all @@ -557,9 +569,12 @@ <section id="endstate.element"> <title>end-state</title> <table frame="topbot" id="end.state.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>End State Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -586,13 +601,13 @@ true, then the full process instance is ended.</entry> </row> <row> - <entry><link linkend="event.element">event</link></entry> + <entry>event<footnote><para><xref linkend="event.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..*]</entry> <entry>supported event types: {node-enter}</entry> </row> <row> - <entry><link linkend="exceptionhandler.element">exception-handler</link></entry> + <entry>exception-handler<footnote><para><xref linkend="exceptionhandler.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..*]</entry> <entry>a list of exception handlers that applies to all @@ -606,9 +621,12 @@ <section id="state.element"> <title>state</title> <table frame="topbot" id="state.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>State Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -619,10 +637,10 @@ </thead> <tbody> <row> - <entry><link linkend="common.node.elements">common node elements</link></entry> + <entry>common node elements<footnote><para><xref linkend="common.node.elements"/>.</para></footnote></entry> <entry></entry> <entry></entry> - <entry>See <link linkend="common.node.elements">common node elements</link></entry> + <entry>See <xref linkend="common.node.elements"/></entry> </row> </tbody> </tgroup> @@ -632,9 +650,12 @@ <section id="tasknode.element"> <title>task-node</title> <table frame="topbot" id="task.node.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Task Node Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -672,16 +693,16 @@ </entry> </row> <row> - <entry><link linkend="task.element">task</link></entry> + <entry>task<footnote><para><xref linkend="task.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..*]</entry> <entry>the tasks that should be created when execution arrives in this task node.</entry> </row> <row> - <entry><link linkend="common.node.elements">common node elements</link></entry> + <entry>common node elements<footnote><para><xref linkend="common.node.elements"/>.</para></footnote></entry> <entry></entry> <entry></entry> - <entry>See <link linkend="common.node.elements">common node elements</link></entry> + <entry>See <xref linkend="common.node.elements"/></entry> </row> </tbody> </tgroup> @@ -691,9 +712,12 @@ <section id="processstate.element"> <title>process-state</title> <table frame="topbot" id="process.state.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Process State Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -707,16 +731,16 @@ <entry>binding</entry> <entry>attribute</entry> <entry>optional</entry> - <entry>Defines the moment a subprocess is resolved. {late|*} defaults to resolving deploytime</entry> + <entry>Defines the moment a sub-process is resolved. {late|*} defaults to resolving deploy time</entry> </row> <row> - <entry><link linkend="subprocess.element">sub-process</link></entry> + <entry>sub-process<footnote><para><xref linkend="subprocess.element"/>.</para></footnote></entry> <entry>element</entry> <entry>1</entry> <entry>the sub process that is associated with this node</entry> </row> <row> - <entry><link linkend="variable.element">variable</link></entry> + <entry>variable<footnote><para><xref linkend="variable.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..*]</entry> <entry>specifies how data should be copied from the super process @@ -724,10 +748,10 @@ super process upon completion of the sub process.</entry> </row> <row> - <entry><link linkend="common.node.elements">common node elements</link></entry> + <entry>common node elements<footnote><para><xref linkend="common.node.elements"/>.</para></footnote></entry> <entry></entry> <entry></entry> - <entry>See <link linkend="common.node.elements">common node elements</link></entry> + <entry>See <xref linkend="common.node.elements"/></entry> </row> </tbody> </tgroup> @@ -737,9 +761,12 @@ <section id="superstate.element"> <title>super-state</title> <table frame="topbot" id="super.state.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Super State Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -750,16 +777,16 @@ </thead> <tbody> <row> - <entry>{<link linkend="endstate.element">end-state</link>|<link linkend="state.element">state</link>|<link linkend="node.element">node</link>|<link linkend="tasknode.element">task-node</link>|<link linkend="processstate.element">process-state</link>|<link linkend="superstate.element">super-state</link>|<link linkend="fork.element">fork</link>|<link linkend="join.element">join</link>|<link linkend="decision.element">decision</link>}</entry> + <entry>{end-state<footnote><para><xref linkend="endstate.element"/>.</para></footnote>|state<footnote><para><xref linkend="state.element"/>.</para></footnote>|node<footnote><para><xref linkend="node.element"/>.</para></footnote>|task-node<footnote><para><xref linkend="tasknode.element"/>.</para></footnote>|process-state<footnote><para><xref linkend="processstate.element"/>.</para></footnote>|super-state<footnote><para><xref linkend="superstate.element"/>.</para></footnote>|fork<footnote><para><xref linkend="fork.element"/>.</para></footnote>|join<footnote><para><xref linkend="join.element"/>.</para></footnote>|decision<footnote><para><xref linkend="decision.element"/>.</para></footnote>}</entry> <entry>element</entry> <entry>[0..*]</entry> <entry>the nodes of the superstate. superstates can be nested.</entry> </row> <row> - <entry><link linkend="common.node.elements">common node elements</link></entry> + <entry>common node elements<footnote><para><xref linkend="common.node.elements"/>.</para></footnote></entry> <entry></entry> <entry></entry> - <entry>See <link linkend="common.node.elements">common node elements</link></entry> + <entry>See <xref linkend="common.node.elements"/></entry> </row> </tbody> </tgroup> @@ -769,9 +796,12 @@ <section id="fork.element"> <title>fork</title> <table frame="topbot" id="fork.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Fork Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -782,10 +812,10 @@ </thead> <tbody> <row> - <entry><link linkend="common.node.elements">common node elements</link></entry> + <entry>common node elements<footnote><para><xref linkend="common.node.elements"/>.</para></footnote></entry> <entry></entry> <entry></entry> - <entry>See <link linkend="common.node.elements">common node elements</link></entry> + <entry>See <xref linkend="common.node.elements"/></entry> </row> </tbody> </tgroup> @@ -795,9 +825,12 @@ <section id="join.element"> <title>join</title> <table frame="topbot" id="join.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Join Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -808,10 +841,10 @@ </thead> <tbody> <row> - <entry><link linkend="common.node.elements">common node elements</link></entry> + <entry>common node elements<footnote><para><xref linkend="common.node.elements"/>.</para></footnote></entry> <entry></entry> <entry></entry> - <entry>See <link linkend="common.node.elements">common node elements</link></entry> + <entry>See <xref linkend="common.node.elements"/></entry> </row> </tbody> </tgroup> @@ -821,9 +854,12 @@ <section id="decision.element"> <title>decision</title> <table frame="topbot" id="decision.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Decision Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -834,7 +870,7 @@ </thead> <tbody> <row> - <entry><link linkend="handler.element">handler</link></entry> + <entry>handler<footnote><para><xref linkend="handler.element"/>.</para></footnote></entry> <entry>element</entry> <entry>either a 'handler' element or conditions on the transitions should be specified</entry> <entry>the name of a <literal>org.jbpm.jpdl.Def.DecisionHandler</literal> implementation</entry> @@ -855,14 +891,14 @@ (to model the 'otherwise' branch). --> See - <link linkend="condition.element">the condition element</link> + <xref linkend="condition.element"/> </entry> </row> <row> - <entry><link linkend="common.node.elements">common node elements</link></entry> + <entry>common node elements<footnote><para><xref linkend="common.node.elements"/>.</para></footnote></entry> <entry></entry> <entry></entry> - <entry>See <link linkend="common.node.elements">common node elements</link></entry> + <entry>See <xref linkend="common.node.elements"/></entry> </row> </tbody> </tgroup> @@ -872,9 +908,12 @@ <section id="event.element"> <title>event</title> <table frame="topbot" id="event.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Event Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -892,7 +931,7 @@ on which the event is placed</entry> </row> <row> - <entry>{<link linkend="action.element">action</link>|<link linkend="script.element">script</link>|<link linkend="create.timer.element">create-timer</link>|<link linkend="cancel.timer.element">cancel-timer</link>}</entry> + <entry>{action<footnote><para><xref linkend="action.element"/>.</para></footnote>|script<footnote><para><xref linkend="script.element"/>.</para></footnote>|create-timer<footnote><para><xref linkend="create.timer.element"/>.</para></footnote>|cancel-timer<footnote><para><xref linkend="cancel.timer.element"/>.</para></footnote>}</entry> <entry>element</entry> <entry>[0..*]</entry> <entry>the list of actions that should be executed on this event</entry> @@ -905,9 +944,12 @@ <section id="transition.element"> <title>transition</title> <table frame="topbot" id="transition.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Transition Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -935,13 +977,13 @@ <entry>condition</entry> <entry>attribute or element text</entry> <entry>optional</entry> - <entry>a guard condition <link linkend="expressions">expression</link>. These condition + <entry>a guard condition expression<footnote><para><xref linkend="expressions"/>.</para></footnote>. These condition attributes (or child elements) can be used in decision nodes, or to calculate the available transitions on a token at runtime. </entry> </row> <row> - <entry>{<link linkend="action.element">action</link>|<link linkend="script.element">script</link>|<link linkend="create.timer.element">create-timer</link>|<link linkend="cancel.timer.element">cancel-timer</link>}</entry> + <entry>{action<footnote><para><xref linkend="action.element"/>.</para></footnote>|script<footnote><para><xref linkend="script.element"/>.</para></footnote>|create-timer<footnote><para><xref linkend="create.timer.element"/>.</para></footnote>|cancel-timer<footnote><para><xref linkend="cancel.timer.element"/>.</para></footnote>}</entry> <entry>element</entry> <entry>[0..*]</entry> <entry>the actions to be executed upon taking this transition. Note that the @@ -949,7 +991,7 @@ only one)</entry> </row> <row> - <entry><link linkend="exceptionhandler.element">exception-handler</link></entry> + <entry>exception-handler<footnote><para><xref linkend="exceptionhandler.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..*]</entry> <entry>a list of exception handlers that applies to all @@ -963,9 +1005,12 @@ <section id="action.element"> <title>action</title> <table frame="topbot" id="action.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Action Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -985,7 +1030,7 @@ </row> <row> <entry>class</entry> - <entry>attibute</entry> + <entry>attribute</entry> <entry>either, a ref-name or an expression</entry> <entry>the fully qualified class name of the class that implements the <literal>org.jbpm.graph.def.ActionHandler</literal> interface. @@ -993,14 +1038,14 @@ </row> <row> <entry>ref-name</entry> - <entry>attibute</entry> + <entry>attribute</entry> <entry>either this or class</entry> <entry>the name of the referenced action. The content of this action is not processed further if a referenced action is specified.</entry> </row> <row> <entry>expression</entry> - <entry>attibute</entry> + <entry>attribute</entry> <entry>either this, a class or a ref-name</entry> <entry>A jPDL expression that resolves to a method. See also <xref linkend="expressions" /> </entry> @@ -1018,17 +1063,17 @@ <entry>config-type</entry> <entry>attribute</entry> <entry>optional</entry> - <entry>{<link linkend="configtypefield">field</link>|<link linkend="configtypebean">bean</link>|<link linkend="configtypeconstructor">constructor</link>|<link linkend="configtypeconfigurationproperty">configuration-property</link>}. + <entry>{field<footnote><para><xref linkend="configtypefield"/>.</para></footnote>|bean<footnote><para><xref linkend="configtypebean"/>.</para></footnote>|constructor<footnote><para><xref linkend="configtypeconstructor"/>.</para></footnote>|configuration-property<footnote><para><xref linkend="configtypeconfigurationproperty"/>.</para></footnote>}. Specifies how the action-object should be constructed and how the content of this element should be used as configuration information for that action-object. </entry> </row> <row> <entry>async</entry> - <entry>attibute</entry> + <entry>attribute</entry> <entry>{true|false}</entry> <entry>Default is false, which means that the action is executed in the thread of the execution. If set to true, a message will be sent to the command executor and that - component will execute the action asynchonously in a separate transaction. + component will execute the action asynchronously in a separate transaction. </entry> </row> <row> @@ -1049,9 +1094,12 @@ <section id="script.element"> <title>script</title> <table frame="topbot" id="script.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Script Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1079,15 +1127,15 @@ </entry> </row> <row> - <entry><link linkend="expression.element">expression</link></entry> + <entry>expression<footnote><para><xref linkend="expression.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..1]</entry> - <entry>the beanshell script. If you don't specify <link linkend="variable.element">variable</link> + <entry>the beanshell script. If you don't specify variable<footnote><para><xref linkend="variable.element"/>.</para></footnote> elements, you can write the expression as the content of the script element (omitting the expression element tag).</entry> </row> <row> - <entry><link linkend="variable.element">variable</link></entry> + <entry>variable<footnote><para><xref linkend="variable.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..*]</entry> <entry>in variable for the script. If no in variables are specified, all the @@ -1103,9 +1151,12 @@ <section id="expression.element"> <title>expression</title> <table frame="topbot" id="expression.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Expression Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1130,9 +1181,12 @@ <section id="variable.element"> <title>variable</title> <table frame="topbot" id="variable.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Variable Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1177,9 +1231,12 @@ <section id="handler.element"> <title>handler</title> <table frame="topbot" id="handler.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Handler Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1191,7 +1248,7 @@ <tbody> <row> <entry>expression</entry> - <entry>attibute</entry> + <entry>attribute</entry> <entry>either this or a class</entry> <entry>A jPDL expression. The returned result is transformed to a string with the toString() method. The resulting string should match one of the leaving @@ -1200,7 +1257,7 @@ </row> <row> <entry>class</entry> - <entry>attibute</entry> + <entry>attribute</entry> <entry>either this or ref-name</entry> <entry>the fully qualified class name of the class that implements the <literal>org.jbpm.graph.node.DecisionHandler</literal> interface. @@ -1210,7 +1267,7 @@ <entry>config-type</entry> <entry>attribute</entry> <entry>optional</entry> - <entry>{<link linkend="configtypefield">field</link>|<link linkend="configtypebean">bean</link>|<link linkend="configtypeconstructor">constructor</link>|<link linkend="configtypeconfigurationproperty">configuration-property</link>}. + <entry>{field<footnote><para><xref linkend="configtypefield"/>.</para></footnote>|bean<footnote><para><xref linkend="configtypebean"/>.</para></footnote>|constructor<footnote><para><xref linkend="configtypeconstructor"/>.</para></footnote>|configuration-property<footnote><para><xref linkend="configtypeconfigurationproperty"/>.</para></footnote>}. Specifies how the action-object should be constructed and how the content of this element should be used as configuration information for that action-object. </entry> </row> @@ -1232,9 +1289,12 @@ <section id="timer.element"> <title>timer</title> <table frame="topbot" id="timer.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Timer Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1281,7 +1341,7 @@ <entry>attribute</entry> <entry>optional</entry> <entry>this attribute is only to be used in timers of tasks. it specifies the - event on which the timer should be cancelled. by default, this is the + event on which the timer should be canceled. by default, this is the <literal>task-end</literal> event, but it can be set to e.g. <literal>task-assign</literal> or <literal>task-start</literal>. The <literal>cancel-event</literal> types can be combined by specifying them in a @@ -1289,7 +1349,7 @@ </entry> </row> <row> - <entry>{<link linkend="action.element">action</link>|<link linkend="script.element">script</link>|<link linkend="create.timer.element">create-timer</link>|<link linkend="cancel.timer.element">cancel-timer</link>}</entry> + <entry>{action<footnote><para><xref linkend="action.element"/>.</para></footnote>|script<footnote><para><xref linkend="script.element"/>.</para></footnote>|create-timer<footnote><para><xref linkend="create.timer.element"/>.</para></footnote>|cancel-timer<footnote><para><xref linkend="cancel.timer.element"/>.</para></footnote>}</entry> <entry>element</entry> <entry>[0..1]</entry> <entry>an action that should be executed when this timer fires</entry> @@ -1302,9 +1362,12 @@ <section id="create.timer.element"> <title>create-timer</title> <table frame="topbot" id="create.timer.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Create Timer Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1318,7 +1381,7 @@ <entry>name</entry> <entry>attribute</entry> <entry>optional</entry> - <entry>the name of the timer. The name can be used for cancelling the timer + <entry>the name of the timer. The name can be used for canceling the timer with a cancel-timer action.</entry> </row> <row> @@ -1354,9 +1417,12 @@ <section id="cancel.timer.element"> <title>cancel-timer</title> <table frame="topbot" id="cancel.timer.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Cancel Timer Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1370,7 +1436,7 @@ <entry>name</entry> <entry>attribute</entry> <entry>optional</entry> - <entry>the name of the timer to be cancelled.</entry> + <entry>the name of the timer to be canceled.</entry> </row> </tbody> </tgroup> @@ -1380,9 +1446,12 @@ <section id="task.element"> <title>task</title> <table frame="topbot" id="task.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Task Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1413,7 +1482,7 @@ <entry>attribute</entry> <entry>optional</entry> <entry>{yes|no|true|false}, default is true. If signalling is set to false, - this task will never have the capability of trigering the continuation of the + this task will never have the capability of triggering the continuation of the token. </entry> </row> @@ -1428,7 +1497,7 @@ <entry>swimlane</entry> <entry>attribute</entry> <entry>optional</entry> - <entry>reference to a <link linkend="swimlane.element">swimlane</link>. If a swimlane + <entry>reference to a swimlane<footnote><para><xref linkend="swimlane.element"/>.</para></footnote>. If a swimlane is specified on a task, the assignment is ignored.</entry> </row> <row> @@ -1439,14 +1508,14 @@ can be specified for the priority. FYI: (highest=1, lowest=5)</entry> </row> <row> - <entry><link linkend="assignment.element">assignment</link></entry> + <entry>assignment<footnote><para><xref linkend="assignment.element"/>.</para></footnote></entry> <entry>element</entry> <entry>optional</entry> - <entry>describes a <link linkend="delegation">delegation</link> that will assign + <entry>describes a delegation<footnote><para><xref linkend="delegation"/>.</para></footnote> that will assign the task to an actor when the task is created.</entry> </row> <row> - <entry><link linkend="event.element">event</link></entry> + <entry>event<footnote><para><xref linkend="event.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..*]</entry> <entry>supported event types: {task-create|task-start|task-assign|task-end}. Especially @@ -1454,14 +1523,14 @@ <literal>previousActorId</literal> to the <literal>TaskInstance</literal></entry> </row> <row> - <entry><link linkend="exceptionhandler.element">exception-handler</link></entry> + <entry>exception-handler<footnote><para><xref linkend="exceptionhandler.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..*]</entry> <entry>a list of exception handlers that applies to all exceptions thrown by delegation classes thrown in this process node.</entry> </row> <row> - <entry><link linkend="timer.element">timer</link></entry> + <entry>timer<footnote><para><xref linkend="timer.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..*]</entry> <entry>specifies a timer that monitors the duration of an execution in this task. @@ -1472,11 +1541,11 @@ </entry> </row> <row> - <entry><link linkend="controller.element">controller</link></entry> + <entry>controller<footnote><para><xref linkend="controller.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..1]</entry> <entry>specifies how the process variables are transformed into task - form parameters. the task form paramaters are used by the user interface + form parameters. the task form parameters are used by the user interface to render a task form to the user. </entry> </row> @@ -1488,9 +1557,12 @@ <section id="swimlane.element"> <title>swimlane</title> <table frame="topbot" id="swimlane.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Swimlane Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1508,7 +1580,7 @@ <literal>TaskMgmtDefinition</literal></entry> </row> <row> - <entry><link linkend="assignment.element">assignment</link></entry> + <entry>assignment<footnote><para><xref linkend="assignment.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[1..1]</entry> <entry>specifies a the assignment of this swimlane. the assignment will be performed @@ -1523,9 +1595,12 @@ <section id="assignment.element"> <title>assignment</title> <table frame="topbot" id="assignment.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Assignment Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1540,7 +1615,7 @@ <entry>attribute</entry> <entry>optional</entry> <entry>For historical reasons, this attribute expression does <emphasis role="bold">not</emphasis> - refer to <link linkend="expressions">the jPDL expression</link>, but instead, it is + refer to the jPDL expression<footnote><para><xref linkend="expressions"/>.</para></footnote>, but instead, it is an assignment expression for the jBPM identity component. For more information on how to write jBPM identity component expressions, see <xref linkend="assignmentexpressions" />. @@ -1552,7 +1627,7 @@ <entry>attribute</entry> <entry>optional</entry> <entry>An actorId. Can be used in conjunction with pooled-actors. The actor-id - is resolved as <link linkend="expressions">an expression</link>. So you can refer to + is resolved as an expression<footnote><para><xref linkend="expressions"/>.</para></footnote>. So you can refer to a fixed actorId like this <literal>actor-id="bobthebuilder"</literal>. Or you can refer to a property or method that returns a String like this: <literal>actor-id="myVar.actorId"</literal>, which will invoke the getActorId method @@ -1566,8 +1641,8 @@ <entry>A comma separated list of actorIds. Can be used in conjunction with actor-id. A fixed set of pooled actors can be specified like this: <literal>pooled-actors="chicagobulls, pointersisters"</literal>. The - pooled-actors will be resolved as <link linkend="expressions">an - expression</link>. So you can also refer to a property or method that has to + pooled-actors will be resolved as an + expression<footnote><para><xref linkend="expressions"/>.</para></footnote>. So you can also refer to a property or method that has to return, a String[], a Collection or a comma separated list of pooled actors. </entry> </row> @@ -1582,7 +1657,7 @@ <entry>config-type</entry> <entry>attribute</entry> <entry>optional</entry> - <entry>{<link linkend="configtypefield">field</link>|<link linkend="configtypebean">bean</link>|<link linkend="configtypeconstructor">constructor</link>|<link linkend="configtypeconfigurationproperty">configuration-property</link>}. + <entry>{field<footnote><para><xref linkend="configtypefield"/>.</para></footnote>|bean<footnote><para><xref linkend="configtypebean"/>.</para></footnote>|constructor<footnote><para><xref linkend="configtypeconstructor"/>.</para></footnote>|configuration-property<footnote><para><xref linkend="configtypeconfigurationproperty"/>.</para></footnote>}. Specifies how the assignment-handler-object should be constructed and how the content of this element should be used as configuration information for that assignment-handler-object. </entry> </row> @@ -1604,9 +1679,12 @@ <section id="controller.element"> <title>controller</title> <table frame="topbot" id="controller.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Controller Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1627,7 +1705,7 @@ <entry>config-type</entry> <entry>attribute</entry> <entry>optional</entry> - <entry>{<link linkend="configtypefield">field</link>|<link linkend="configtypebean">bean</link>|<link linkend="configtypeconstructor">constructor</link>|<link linkend="configtypeconfigurationproperty">configuration-property</link>}. + <entry>{field<footnote><para><xref linkend="configtypefield"/>.</para></footnote>|bean<footnote><para><xref linkend="configtypebean"/>.</para></footnote>|constructor<footnote><para><xref linkend="configtypeconstructor"/>.</para></footnote>|configuration-property<footnote><para><xref linkend="configtypeconfigurationproperty"/>.</para></footnote>}. Specifies how the assignment-handler-object should be constructed and how the content of this element should be used as configuration information for that assignment-handler-object. </entry> </row> @@ -1641,7 +1719,7 @@ must be a list of variable elements.</entry> </row> <row> - <entry><link linkend="variable.element">variable</link></entry> + <entry>variable<footnote><para><xref linkend="variable.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[0..*]</entry> <entry>in case no task controller handler is specified by the class @@ -1656,9 +1734,12 @@ <section id="subprocess.element"> <title>sub-process</title> <table frame="topbot" id="sub.process.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Sub Process Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1673,7 +1754,7 @@ <entry>attribute</entry> <entry>required</entry> <entry>the name of the sub process. Can be an EL expression, as long as it resolves to a String. Powerful especially with late binding in the process-state. To know how you can test - subprocesses, see <xref linkend="testingsubprocesses" /></entry> + sub-processes, see <xref linkend="testingsubprocesses" /></entry> </row> <row> <entry>version</entry> @@ -1682,7 +1763,7 @@ <entry>the version of the sub process. If no version is specified, the latest version of the given process as known while deploying the parent - <link linkend="processstate.element">process-state</link> + process-state<footnote><para><xref linkend="processstate.element"/>.</para></footnote> will be taken.</entry> </row> <row> @@ -1690,7 +1771,7 @@ <entry>attribute</entry> <entry>optional</entry> <entry>indicates if the version of the sub process should be determined - when deploying the parent <link linkend="processstate.element">process-state</link> + when deploying the parent process-state<footnote><para><xref linkend="processstate.element"/>.</para></footnote> (default behavior), or when actually invoking the sub process (<literal>binding="late"</literal>). When both <literal>version</literal> and <literal>binding="late"</literal> are given then jBPM will use the version as @@ -1706,9 +1787,12 @@ <section id="condition.element"> <title>condition</title> <table frame="topbot" id="condition.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Condition Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1723,8 +1807,8 @@ <entry>{content} For backwards compatibility, the condition can also be entered with the 'expression' attribute, but that attribute is deprecated since 3.2</entry> <entry>required</entry> - <entry>The contents of the condition element is <link linkend="expressions">a - jPDL expression</link> that should evaluate to a boolean. A decision takes the + <entry>The contents of the condition element is a + jPDL expression<footnote><para><xref linkend="expressions"/>.</para></footnote> that should evaluate to a boolean. A decision takes the first transition (as ordered in the processdefinition.xml) for which the expression resolves to <literal>true</literal>. If none of the conditions resolve to true, the default leaving transition (== the first one) will be taken. @@ -1738,9 +1822,12 @@ <section id="exceptionhandler.element"> <title>exception-handler</title> <table frame="topbot" id="exception.handler.schema"> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> + <title>Exception Handler Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1759,7 +1846,7 @@ (<literal>java.lang.Throwable</literal>).</entry> </row> <row> - <entry><link linkend="action.element">action</link></entry> + <entry>action<footnote><para><xref linkend="action.element"/>.</para></footnote></entry> <entry>element</entry> <entry>[1..*]</entry> <entry>a list of actions to be executed when an exception is being handled by this Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/logging.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/logging.xml 2009-02-09 16:40:15 UTC (rev 3819) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/logging.xml 2009-02-10 02:27:07 UTC (rev 3820) @@ -3,7 +3,7 @@ <para>The purpose of logging is to keep track of the history of a process execution. As the runtime data of a process execution changes, - all the delta's are stored in the logs.</para> + all the deltas are stored in the logs.</para> <para>Process logging, which is covered in this chapter, is not to be confused with software logging. Software logging traces the execution of a software @@ -15,17 +15,17 @@ </para> <para>Another use case is - Business Activity Monitoring (BAM). BAM will query or analyse the logs of process - executions to find usefull statistical information about the business process. E.g. - how much time is spend on average in each step of the process ? Where are the - bottlenecks in the process ? ... This information is key to implement real business - process management in an organisation. Real business process management is about how - an organisation manages their processes, how these are supported by information technology + Business Activity Monitoring (BAM). BAM will query or analyze the logs of process + executions to find useful statistical information about the business process. E.g. + how much time is spent on average in each step of the process, where the bottlenecks + in the process are etc. This information is key to implement real business + process management in an organization. Real business process management is about how + an organization manages their processes, how these are supported by information technology *and* how these two improve the other in an iterative process. </para> <para>Next use case is the undo functionality. Process logs can be used to implement - the undo. Since the logs contain the delta's of the runtime information, the logs can be + the undo. Since the logs contain the deltas of the runtime information, the logs can be played in reverse order to bring the process back into a previous state. </para> @@ -53,12 +53,12 @@ refers to that token. The <literal>Token</literal> also serves as an index-sequence generator for the index of the <literal>ProcessLog</literal> in the <literal>Token</literal>. This will be important for log retrieval. That way, logs that are produced in subsequent transactions - will have sequential sequence numbers. (wow, that a lot of seq's in there :-s ).</para> + will have sequential sequence numbers.</para> <para>The API method for adding process logs is the following. </para> - <programlisting>public class LoggingInstance extends ModuleInstance { + <programlisting language="java">public class LoggingInstance extends ModuleInstance { ... public void addLog(ProcessLog processLog) {...} ... @@ -76,7 +76,7 @@ thereby creating the means for a hierarchical structure in the logs. The API for inserting a log is the following.</para> - <programlisting>public class LoggingInstance extends ModuleInstance { + <programlisting language="java">public class LoggingInstance extends ModuleInstance { ... public void startCompositeLog(CompositeLog compositeLog) {...} public void endCompositeLog() {...} @@ -87,7 +87,7 @@ <literal>try-finally</literal>-block to make sure that the hierarchical structure of logs is consistent. For example:</para> - <programlisting>startCompositeLog(new MyCompositeLog()); + <programlisting language="java">startCompositeLog(new MyCompositeLog()); try { ... } finally { @@ -101,7 +101,7 @@ <para>For deployments where logs are not important, it suffices to remove the logging line in the jbpm-context section of the jbpm.cfg.xml configuration file: </para> - <programlisting>&lt;service name='logging' factory='org.jbpm.logging.db.DbLoggingServiceFactory' /&gt;</programlisting> + <programlisting language="xml">&lt;service name='logging' factory='org.jbpm.logging.db.DbLoggingServiceFactory' /&gt;</programlisting> <para>In case you want to filter the logs, you need to write a custom implementation of the LoggingService that is a subclass of DbLoggingService. Also you need to create a custom logging ServiceFactory and specify that one in the factory attribute. @@ -121,7 +121,7 @@ with every Token in the process instance. The list will contain the ProcessLogs in the same ordered as they were created.</para> - <programlisting>public class LoggingSession { + <programlisting language="java">public class LoggingSession { ... public Map findLogsByProcessInstance(long processInstanceId) {...} ... @@ -130,7 +130,7 @@ <para>The second method retrieves the logs for a specific Token. The returned list will contain the ProcessLogs in the same ordered as they were created.</para> - <programlisting>public class LoggingSession { + <programlisting language="java">public class LoggingSession { public List findLogsByToken(long tokenId) {...} ... }</programlisting> @@ -145,7 +145,7 @@ </para> <para>There may be many reasons why you want to create a data warehouse with the - process log information. Sometimes it might be to offload heavy queryies from the + process log information. Sometimes it might be to offload heavy queries from the 'live' production database. In other situations it might be to do some extensive analysis. Data warehousing even might be done on a modified database schema which is optimized for its purpose.</para> Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/mail.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/mail.xml 2009-02-09 16:40:15 UTC (rev 3819) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/mail.xml 2009-02-10 02:27:07 UTC (rev 3820) @@ -12,51 +12,51 @@ <section id="mailaction"> <title>Mail action</title> - <para>A mail action can be used when the sending of this email should <emphasis role="bold">not</emphasis> + <para>A mail action can be used when the sending of this email should not be shown as a node in the process graph. </para> <para>Anywhere you are allowed to specify actions in the process, you can specify a mail action like this: </para> - <programlisting>&lt;<emphasis role="bold">mail</emphasis> actors="#{president}" subject="readmylips" text="nomoretaxes" /&gt;</programlisting> + <programlisting language="xml">&lt;mail actors="#{president}" subject="readmylips" text="nomoretaxes" /&gt;</programlisting> <para>The subject and text attributes can also be specified as an element like this:</para> - <programlisting>&lt;mail actors="#{president}" &gt; + <programlisting language="xml">&lt;mail actors="#{president}" &gt; &lt;subject&gt;readmylips&lt;/subject&gt; &lt;text&gt;nomoretaxes&lt;/text&gt; &lt;/mail&gt; </programlisting> <para>Each of the fields can contain JSF like expressions. For example: </para> - <programlisting>&lt;mail to='#{initiator}' subject='websale' text='your websale of #{quantity} #{item} was approved' /&gt;</programlisting> + <programlisting language="xml">&lt;mail to='#{initiator}' subject='websale' text='your websale of #{quantity} #{item} was approved' /&gt;</programlisting> <para>For more information about expressions, see <xref linkend="expressions" />. </para> <para>There are two attribute to specify recipients: <literal>actors</literal> and <literal>to</literal>. The <literal>to</literal> attribute should resolve to a semicolon separated list of email addresses. The <literal>actors</literal> attribute should resolve to a semicolon separated list of actorIds. Those actorIds will be resolved to email addresses with by - means of <link linkend="addressresolving">address resolving</link>. + means of address resolving<footnote><para><xref linkend="addressresolving"/>.</para></footnote>. </para> - <programlisting>&lt;mail to=&#39;admin(a)mycompany.com&#39; subject='urgent' text='the mailserver is down :-)' /&gt;</programlisting> + <programlisting language="xml">&lt;mail to=&#39;admin(a)mycompany.com&#39; subject='urgent' text='the mailserver is down :-)' /&gt;</programlisting> <para>For more about how to specify recipients, see <xref linkend="specifyingmailrecipients" /></para> <para>Mails can be defined in templates and in the process you can overwrite properties of the templates like this: </para> - <programlisting>&lt;mail template='sillystatement' actors="#{president}" /&gt;</programlisting> + <programlisting language="xml">&lt;mail template='sillystatement' actors="#{president}" /&gt;</programlisting> <para>More about templates can be found in <xref linkend="mailtemplates" /></para> </section> <section id="mailnode"> <title>Mail node</title> - <para>Just the same as with mail actions, sending of an email can also be modelled as a node. - In that case, the runtime behaviour is just the same, but the email will show up as a node + <para>Just the same as with mail actions, sending of an email can also be modeled as a node. + In that case, the runtime behavior is just the same, but the email will show up as a node in the process graph. </para> <para>The attributes and elements supported by mail nodes are exactly the same as with - the <link linkend="mailaction">mail actions</link>. + the mail actions<footnote><para><xref linkend="mailaction"/>.</para></footnote>. </para> - <programlisting>&lt;<emphasis role="bold">mail-node</emphasis> name="send email" to="#{president}" subject="readmylips" text="nomoretaxes"&gt; + <programlisting language="xml">&lt;mail-node name="send email" to="#{president}" subject="readmylips" text="nomoretaxes"&gt; &lt;transition to="the next node" /&gt; -&lt;/<emphasis role="bold">mail-node</emphasis>&gt;</programlisting> +&lt;/mail-node&gt;</programlisting> <para>Mail nodes should have exactly one leaving transition.</para> </section> @@ -65,8 +65,8 @@ <para>A notification email can be send when a task gets assigned to an actor. Just use the <literal>notify="yes"</literal> attribute on a task like this: </para> - <programlisting>&lt;task-node name='a'&gt; - &lt;task name='laundry' swimlane="grandma" <emphasis role="bold">notify='yes'</emphasis> /&gt; + <programlisting language="xml">&lt;task-node name='a'&gt; + &lt;task name='laundry' swimlane="grandma" notify='yes' /&gt; &lt;transition to='b' /&gt; &lt;/task-node&gt; </programlisting> @@ -78,13 +78,13 @@ <section id="taskremindermails"> <title>Task reminder mails</title> - <para>Similarly as with assignments, emails can be send as a task reminder. The <literal>reminder</literal> + <para>Similarly as with assignments, emails can be sent as a task reminder. The <literal>reminder</literal> element in jPDL is based upon the timer. The most common attributes will be the <literal>duedate</literal> and the <literal>repeat</literal>. The only difference is that no action has to be specified. </para> - <programlisting>&lt;task-node name='a'&gt; + <programlisting language="xml">&lt;task-node name='a'&gt; &lt;task name='laundry' swimlane="grandma" notify='yes'&gt; - <emphasis role="bold">&lt;reminder duedate="2 business days" repeat="2 business hours"/&gt;</emphasis> + &lt;reminder duedate="2 business days" repeat="2 business hours"/&gt; &lt;/task&gt; &lt;transition to='b' /&gt; &lt;/task-node&gt; @@ -101,12 +101,12 @@ <para>The variables in the expressions can be : swimlanes, process variables, transient variables beans configured in the jbpm.cfg.xml, ... </para> - <para>These expressions can be combined with the <link linkend="addressresolving">address resolving</link> + <para>These expressions can be combined with the address resolving<footnote><para><xref linkend="addressresolving"/>.</para></footnote> that is explained later in this chapter. For example, suppose that you have a swimlane called president in your process, then look at the following mail specification: </para> - <programlisting>&lt;mail actors="#{president}" subject="readmylips" text="nomoretaxes" /&gt;</programlisting> - <para>That will send an email to to the person that acts as the president for that perticular process + <programlisting language="xml">&lt;mail actors="#{president}" subject="readmylips" text="nomoretaxes" /&gt;</programlisting> + <para>That will send an email to to the person that acts as the president for that particular process execution. </para> </section> @@ -135,16 +135,16 @@ </section> <section id="addressresolving"> <title>Address resolving</title> - <para>In all of jBPM, actors are referenced by actorId's. This is a string that servers as the identifier + <para>In all of jBPM, actors are referenced by actorId's. This is a string that serves as the identifier of the process participant. An address resolver translates actorId's into email addresses. </para> - <para>Use the attribute <emphasis role="bold">actors</emphasis> in case you want to apply address resolving - and use the attribute <emphasis role="bold">to</emphasis> in case you are specifying email addresses + <para>Use the attribute actors in case you want to apply address resolving + and use the attribute to in case you are specifying email addresses directly and don't want to apply address resolving. </para> <para>An address resolver should implement the following interface: </para> - <programlisting>public interface AddressResolver extends Serializable { + <programlisting language="java">public interface AddressResolver extends Serializable { Object resolveAddress(String actorId); }</programlisting> <para>An address resolver should return 1 of 3 types: a String, a Collection of Strings or an array @@ -153,9 +153,8 @@ <para>The address resolver implementation should be a bean configured in the jbpm.cfg.xml with name <literal>jbpm.mail.address.resolver</literal> like this: </para> - <programlisting>&lt;jbpm-configuration&gt; - ... - <emphasis role="bold">&lt;bean name='jbpm.mail.address.resolver' class='org.jbpm.identity.mail.IdentityAddressResolver' singleton='true' /&gt;</emphasis> + <programlisting language="xml">&lt;jbpm-configuration&gt; + &lt;bean name='jbpm.mail.address.resolver' class='org.jbpm.identity.mail.IdentityAddressResolver' singleton='true' /&gt; &lt;/jbpm-configuration&gt; </programlisting> <para>The identity component of jBPM includes an address resolver. That address resolver @@ -171,7 +170,7 @@ file. When a template is used, each of the fields can still be overwritten in the processdefinition.xml. The mail templates should be specified in an XML file like this: </para> - <programlisting> + <programlisting language="xml"> &lt;mail-templates&gt; &lt;variable name="BaseTaskListURL" value="http://localhost:8080/jbpm/task?id=" /&gt; @@ -198,14 +197,13 @@ &lt;/mail-templates&gt; </programlisting> <para>As you can see in this example (BaseTaskListURL), extra variables can be defined in - the mail templates that will be availble in the expressions. + the mail templates that will be available in the expressions. </para> <para>The resource that contains the templates should be configured in the jbpm.cfg.xml like this: </para> - <programlisting>&lt;jbpm-configuration&gt; - ... - <emphasis role="bold">&lt;string name="resource.mail.templates" value="jbpm.mail.templates.xml" /&gt;</emphasis> + <programlisting language="xml">&lt;jbpm-configuration&gt; + &lt;string name="resource.mail.templates" value="jbpm.mail.templates.xml" /&gt; &lt;/jbpm-configuration&gt;</programlisting> </section> @@ -214,16 +212,14 @@ <para>The simplest way to configure the mail server is with the configuration property <literal>jbpm.mail.smtp.host</literal> in the jbpm.cfg.xml like this: </para> - <programlisting>&lt;jbpm-configuration&gt; - ... - <emphasis role="bold">&lt;string name="jbpm.mail.smtp.host" value="localhost" /&gt;</emphasis> + <programlisting language="xml">&lt;jbpm-configuration&gt; + &lt;string name="jbpm.mail.smtp.host" value="localhost" /&gt; &lt;/jbpm-configuration&gt;</programlisting> <para>Alternatively, when more properties need to be specified, a resource reference to a properties file can be given with the key '' like this: </para> - <programlisting>&lt;jbpm-configuration&gt; - ... - <emphasis role="bold">&lt;string name='resource.mail.properties' value='jbpm.mail.properties' /&gt;</emphasis> + <programlisting language="xml">&lt;jbpm-configuration&gt; + &lt;string name='resource.mail.properties' value='jbpm.mail.properties' /&gt; &lt;/jbpm-configuration&gt;</programlisting> </section> @@ -234,9 +230,8 @@ The from address of mails can be configured in the jBPM configuration file jbpm.xfg.xml with key 'jbpm.mail.from.address' like this: </para> - <programlisting>&lt;jbpm-configuration&gt; - ... - <emphasis role="bold">&lt;string name='jbpm.mail.from.address' value=&#39;jbpm(a)yourcompany.com&#39; /&gt;</emphasis> + <programlisting language="xml">&lt;jbpm-configuration&gt; + &lt;string name='jbpm.mail.from.address' value=&#39;jbpm(a)yourcompany.com&#39; /&gt; &lt;/jbpm-configuration&gt;</programlisting> </section> @@ -245,12 +240,11 @@ <para>All the mail support in jBPM is centralized in one class: <literal>org.jbpm.mail.Mail</literal> This is an ActionHandler implementation. Whenever an mail is specified in the process xml, this will result in a delegation to the mail class. It is possible to inherit from the Mail class and customize - certain behaviour for your perticular needs. To configure your class to be used for mail delegations, + certain behavior for your particular needs. To configure your class to be used for mail delegations, specify a 'jbpm.mail.class.name' configuration string in the jbpm.cfg.xml like this: </para> - <programlisting>&lt;jbpm-configuration&gt; - ... - <emphasis role="bold">&lt;string name='jbpm.mail.class.name' value='com.your.specific.CustomMail' /&gt;</emphasis> + <programlisting language="xml">&lt;jbpm-configuration&gt; + &lt;string name='jbpm.mail.class.name' value='com.your.specific.CustomMail' /&gt; &lt;/jbpm-configuration&gt;</programlisting> <para>The customized mail class will be read during parsing and actions will be configured in the process that reference the configured (or the default) mail classname. So if you change the @@ -260,7 +254,7 @@ <section id="mailserver"> <title>Mail server</title> - <para>If you need a mailserver that is easy to install, checkout <ulink url="http://www.jboss.org/products/mailservices">JBossMail Server</ulink> + <para>If you need a mail server that is easy to install, checkout <ulink url="http://www.jboss.org/products/mailservices">JBossMail Server</ulink> or <ulink url="http://james.apache.org/">Apache James</ulink> </para> </section> Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/modelling.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/modelling.xml 2009-02-09 16:40:15 UTC (rev 3819) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/modelling.xml 2009-02-10 02:27:07 UTC (rev 3820) @@ -1,5 +1,5 @@ <chapter id="processmodelling"> - <title>Process Modelling</title> + <title>Process Modeling</title> <section id="overview"> <title>Overview</title> @@ -7,7 +7,7 @@ <para>A process definition represents a formal specification of a business process and is based on a directed graph. The graph is composed of nodes and transitions. Every node in the graph is of a specific type. The type of the node defines the runtime - behaviour. A process definition has exactly one start state.</para> + behavior. A process definition has exactly one start state.</para> <para>A token is one path of execution. A token is the runtime concept that maintains a pointer to a node in the graph.</para> @@ -26,7 +26,7 @@ <para>After the token has entered a node, the node is executed. Nodes themselves are responsible for the continuation of the graph execution. Continuation of graph execution is done by making the token leave the node. Each node type can implement a different - behaviour for the continuation of the graph execution. A node that does not propagate + behavior for the continuation of the graph execution. A node that does not propagate execution will behave as a state.</para> <para>Actions are pieces of java code that are executed upon events in the process @@ -53,7 +53,7 @@ </figure> <para>Below is the process graph of the jBAY auction process represented as xml:</para> -<programlisting>&lt;process-definition&gt; +<programlisting language="xml">&lt;process-definition&gt; &lt;start-state&gt; &lt;transition to="auction" /&gt; @@ -97,12 +97,12 @@ <section id="nodes"> <title>Nodes</title> <para>A process graph is made up of nodes and transitions. For more information about the - graph and its executional model, refer to <xref linkend="graphorientedprogramming" />. + graph and its execution model, refer to <xref linkend="graphorientedprogramming" />. </para> <para>Each node has a specific type. The node type determines what will happen when - an execution arrives in the node at runtime. jBPM has a set of preimplemented node types + an execution arrives in the node at runtime. jBPM has a set of node types that you can use. Alternatively, you can write custom code for implementing your own specific - node behaviour.</para> + node behavior.</para> <section id="noderesponsibilities"> <title>Node responsibilities</title> @@ -112,38 +112,38 @@ is responsible for propagating the process execution. Basically, each node has the following options for propagating the process execution:</para> <itemizedlist> - <listitem><emphasis role="bold">1. not propagate the execution.</emphasis> In that - case the node behaves as a wait state.</listitem> - <listitem><emphasis role="bold">2. propagate the execution over one of the leaving + <listitem><para><emphasis role="bold">1. not propagate the execution.</emphasis> In that + case the node behaves as a wait state.</para></listitem> + <listitem><para><emphasis role="bold">2. propagate the execution over one of the leaving transitions of the node.</emphasis> This means that the token that originally arrived in the node is passed over one of the leaving transitions with the API call executionContext.leaveNode(String). The node will now act as an automatic node in the sense it can execute some custom programming logic and then continue process execution - automatically without waiting.</listitem> - <listitem><emphasis role="bold">3. create new paths of execution.</emphasis> A node can + automatically without waiting.</para></listitem> + <listitem><para><emphasis role="bold">3. create new paths of execution.</emphasis> A node can decide to create new tokens. Each new token represents a new path of execution and each new token can be launched over the node's leaving transitions. A good example of - this kind of behaviour is the fork node.</listitem> - <listitem><emphasis role="bold">4. end paths of execution.</emphasis> A node can decide + this kind of behavior is the fork node.</para></listitem> + <listitem><para><emphasis role="bold">4. end paths of execution.</emphasis> A node can decide to end a path of execution. That means that the token is ended and the path of execution - is finished.</listitem> - <listitem><emphasis role="bold">5. more general, a node can modify the whole runtime + is finished.</para></listitem> + <listitem><para><emphasis role="bold">5. more general, a node can modify the whole runtime structure of the process instance.</emphasis> The runtime structure is a process instance that contains a tree of tokens. Each token represents a path of execution. A node can create and end tokens, put each token in a node of the graph and launch tokens over - transitions.</listitem> + transitions.</para></listitem> </itemizedlist> - <para>jBPM contains --as any workflow and BPM engine-- a set of preimplemented node types - that have a specific documented configuration and behaviour. But the unique thing about - jBPM and the <link linkend="graphorientedprogramming">Graph Oriented Programming foundation</link> - is that we open up the model for developers. Developers can write their own node behaviour + <para>jBPM contains --as any workflow and BPM engine-- a set of pre-implemented node types + that have a specific documented configuration and behavior. But the unique thing about + jBPM and the Graph Oriented Programming foundation<footnote><para><xref linkend="graphorientedprogramming"/>.</para></footnote> + is that we open up the model for developers. Developers can write their own node behavior very easy and use it in a process. </para> <para>That is where traditional workflow and BPM systems are much more closed. They usually supply a fixed set of node types (called the process language). - Their process language is closed and the executional model is hidden in the runtime + Their process language is closed and the execution model is hidden in the runtime environment. Research of <ulink url="http://www.workflowpatterns.com">workflow patterns</ulink> - has shown that any process language is not powerfull enough. We have decided for a simple + has shown that any process language is not powerful enough. We have decided for a simple model and allow developers to write their own node types. That way the JPDL process language is open ended.</para> <para>Next, we discuss the most important node types of JPDL.</para> @@ -161,7 +161,7 @@ <section id="nodetypetaskstate"> <title>Nodetype state</title> <para>A state is a bare-bones wait state. The difference with a task node is that - no task instances will be created in any task list. This can be usefull if the process + no task instances will be created in any task list. This can be useful if the process should wait for an external system. E.g. upon entry of the node (via an action on the node-enter event), a message could be sent to the external system. After that, the process will go into a wait state. When the external system send a response message, this can lead to @@ -179,13 +179,13 @@ that return a boolean.</para> <para>At runtime the decision node will FIRST loop over its leaving transitions THAT HAVE a condition specified. It will evaluate those transitions first in - the order as specified in the xml. The first transition for which the conditions resolves to + the order as specified in the xml. The first transition for which the condition resolves to 'true' will be taken. If all transitions with a condition resolve to false, the default transition (the first in the XML) is taken.</para> <para>Another approach is to use an expression that returns the name of the transition to take. With the 'expression' attribute, you can specify an expression on the decision that has to resolve to one of the leaving transitions of the decision node.</para> - <para>Next aproach is the 'handler' element on the decision, that element can be used to specify + <para>Next approach is the 'handler' element on the decision, that element can be used to specify an implementation of the DecisionHandler interface can be specified on the decision node. Then the decision is calculated in a java class and the selected leaving transition is returned by the decide-method of the DecisionHandler implementation.</para> @@ -199,7 +199,7 @@ <section id="nodetypefork"> <title>Nodetype fork</title> <para>A fork splits one path of execution into multiple concurrent paths of execution. The - default fork behaviour is to create a child token for each transition that leaves the fork, + default fork behavior is to create a child token for each transition that leaves the fork, creating a parent-child relation between the token that arrives in the fork.</para> </section> <section id="nodetypejoin"> @@ -215,9 +215,9 @@ <section id="nodetypenode"> <title>Nodetype node</title> <para>The type node serves the situation where you want to write your own code in a node. - The nodetype node expects one subelement action. The action is executed when the execution + The nodetype node expects one sub-element action. The action is executed when the execution arrives in the node. The code you write in the actionhandler can do anything you want but - it is also <link linkend="noderesponsibilities">responsible for propagating the execution</link>. + it is also responsible for propagating the execution<footnote><para><xref linkend="noderesponsibilities"/>.</para></footnote>. </para> <para>This node can be used if you want to use a JavaAPI to implement some functional logic that is important for the business analyst. By using a node, the node is visible in the graphical @@ -235,7 +235,7 @@ <literal>to</literal>. </para> <para>A transition can optionally have a name. Note that most of the jBPM features depend on the uniqueness - of the transition name. If more then one transition has the same name, the first transition with + of the transition name. If more than one transition has the same name, the first transition with the given name is taken. In case duplicate transition names occur in a node, the method <literal>Map getLeavingTransitionsMap()</literal> will return less elements than <literal>List getLeavingTransitions()</literal>. @@ -259,8 +259,8 @@ that is placed in a node. Actions that are put in an event are executed when the event fires. Actions on events have no way to influence the flow of control of the process. It is similar to the observer pattern. On the other hand, an action that is put on a - <link linkend="nodetypenode">node</link> has the <link linkend="noderesponsibilities">responsibility - of propagating the execution</link>.</para> + node<footnote><para><xref linkend="nodetypenode"/>.</para></footnote> has the responsibility + of propagating the execution<footnote><para><xref linkend="noderesponsibilities"/>.</para></footnote>.</para> <para>Let's look at an example of an action on an event. Suppose we want to do a database update on a given transition. The database update is technically vital but it is not important @@ -271,7 +271,7 @@ <mediaobject><imageobject><imagedata align="center" fileref="images/database.update.example.gif"/></imageobject></mediaobject> </figure> - <programlisting>public class RemoveEmployeeUpdate implements ActionHandler { + <programlisting language="java">public class RemoveEmployeeUpdate implements ActionHandler { public void execute(ExecutionContext ctx) throws Exception { // get the fired employee from the process variables. String firedEmployee = (String) ctx.getContextInstance().getVariable("fired employee"); @@ -286,9 +286,7 @@ } }</programlisting> -<programlisting>&lt;process-definition name="yearly evaluation"&gt; - - ... +<programlisting language="xml">&lt;process-definition name="yearly evaluation"&gt; &lt;state name="fire employee"&gt; &lt;transition to="collect badge"&gt; &lt;action class="com.nomercy.hr.RemoveEmployeeUpdate" /> @@ -296,7 +294,6 @@ &lt;/state&gt; &lt;state name="collect badge"&gt; - ... &lt;/process-definition&gt;</programlisting> @@ -321,7 +318,7 @@ <section id="events"> <title>Events</title> <para>Events specify moments in the execution of the process. The jBPM engine - will fire events during graph execution. This occurs when jbpm calculats the + will fire events during graph execution. This occurs when jbpm calculates the next state (read: processing a signal). An event is always relative to an element in the process definition like e.g. the process definition, a node or a transition. Most process elements can fire different types of events. A node for example can @@ -349,14 +346,14 @@ </para> <itemizedlist> - <listitem>executionContext</listitem> - <listitem>token</listitem> - <listitem>node</listitem> - <listitem>task</listitem> - <listitem>taskInstance</listitem> + <listitem><para>executionContext</para></listitem> + <listitem><para>token</para></listitem> + <listitem><para>node</para></listitem> + <listitem><para>task</para></listitem> + <listitem><para>taskInstance</para></listitem> </itemizedlist> -<programlisting>&lt;process-definition&gt; +<programlisting language="xml">&lt;process-definition&gt; &lt;event type="node-enter"&gt; &lt;script&gt; System.out.println("this script is entering node "+node); @@ -365,12 +362,12 @@ ... &lt;/process-definition&gt;</programlisting> - <para>To customize the default behaviour of loading and storing variables into the script, the + <para>To customize the default behavior of loading and storing variables into the script, the <literal>variable</literal> element can be used as a sub-element of script. In that case, - the script expression also has to be put in a subelement of script: <literal>expression</literal>. + the script expression also has to be put in a sub-element of script: <literal>expression</literal>. </para> -<programlisting>&lt;process-definition&gt; +<programlisting language="xml">&lt;process-definition&gt; &lt;event type="process-end"&gt; &lt;script&gt; &lt;expression&gt; @@ -423,7 +420,7 @@ can be used to bring some hierarchy in the process definition. For example, one application could be to group all the nodes of a process in phases. Actions can be associated with superstate events. A consequence is that a token can be in multiple nested nodes at a given - time. This can be convenient to check wether a process execution is e.g. in the start-up phase. + time. This can be convenient to check whether a process execution is e.g. in the start-up phase. In the jBPM model, you are free to group any set of nodes in a superstate. </para> @@ -452,26 +449,23 @@ <section id="hierarchicalnames"> <title>Hierarchical names</title> <para>Node names have to be unique in their scope. The scope of the node is its node-collection. - Both the process definintion and the superstate are node collections. To refer to nodes in + Both the process definition and the superstate are node collections. To refer to nodes in superstates, you have to specify the relative, slash (/) separated name. The slash separates the node names. Use '..' to refer to an upper level. The next example shows how to reference a node in a superstate:</para> - <programlisting>&lt;process-definition&gt; - ... + <programlisting language="xml">&lt;process-definition&gt; &lt;state name="preparation"&gt; &lt;transition to="phase one/invite murphy"/&gt; &lt;/state&gt; &lt;super-state name="phase one"&gt; &lt;state name="invite murphy"/&gt; &lt;/super-state&gt; - ... &lt;/process-definition&gt;</programlisting> <para>The next example will show how to go up the superstate hierarchy</para> - <programlisting>&lt;process-definition&gt; - ... + <programlisting language="xml">&lt;process-definition&gt; &lt;super-state name="phase one"&gt; &lt;state name="preparation"&gt; &lt;transition to="../phase two/invite murphy"/&gt; @@ -480,7 +474,6 @@ &lt;super-state name="phase two"&gt; &lt;state name="invite murphy"/&gt; &lt;/super-state&gt; - ... &lt;/process-definition&gt;</programlisting> </section> @@ -497,7 +490,7 @@ <literal>transition</literal>s, a list of <literal>exception-handler</literal>s can be specified. Each <literal>exception-handler</literal> has a list of actions. When an exception occurs in a delegation class, the process - element parent hierarchy is serached for an appropriate <literal>exception-handler</literal>. + element parent hierarchy is searched for an appropriate <literal>exception-handler</literal>. When it is found, the actions of the <literal>exception-handler</literal> are executed. </para> @@ -517,18 +510,18 @@ </para> </section> - <section id="processcomposition"> + <section id="modelling_processcomposition"> <title>Process composition</title> <para>Process composition is supported in jBPM by means of the <literal>process-state</literal>. The process state is a state that is associated with another process definition. When graph execution arrives in the process state, a new process instance of the sub-process is created and it is associated with the path of execution that arrived in the process state. The - path of execution of the super process will wait till the sub process instance has ended. + path of execution of the super process will wait until the sub process instance has ended. When the sub process instance ends, the path of execution of the super process will leave the process state and continue graph execution in the super process. </para> - <programlisting>&lt;process-definition name=&quot;hire&quot;&gt; + <programlisting language="xml">&lt;process-definition name=&quot;hire&quot;&gt; &lt;start-state&gt; &lt;transition to=&quot;initial interview&quot; /&gt; &lt;/start-state&gt; @@ -558,7 +551,7 @@ interview process is copied back into the 'a' variable of the hire process.</para> - <para>In general, When a subprocess is started, all <literal>variable</literal>s with + <para>In general, When a sub-process is started, all <literal>variable</literal>s with <literal>read</literal> access are read from the super process and fed into the newly created sub process before the signal is given to leave the start state. When the sub process instances is finished, all the @@ -568,11 +561,11 @@ </section> <section id="customnodebehaviour"> - <title>Custom node behaviour</title> + <title>Custom node behavior</title> <para>In jBPM, it's quite easy to write your own custom nodes. For creating custom nodes, an implementation of the ActionHandler has to be written. The implementation can execute any business logic, but also has the responsibility to propagate the graph execution. Let's look - at an example that will update an ERP-system. We'll read an amout from the ERP-system, add + at an example that will update an ERP-system. We'll read an amount from the ERP-system, add an amount that is stored in the process variables and store the result back in the ERP-system. Based on the size of the amount, we have to leave the node via the 'small amounts' or the 'large amounts' transition. @@ -583,7 +576,7 @@ <mediaobject><imageobject><imagedata align="center" fileref="images/update.erp.example.gif"/></imageobject></mediaobject> </figure> - <programlisting>public class AmountUpdate implements ActionHandler { + <programlisting language="java">public class AmountUpdate implements ActionHandler { public void execute(ExecutionContext ctx) throws Exception { // business logic Float erpAmount = ...get amount from erp-system...; @@ -602,7 +595,7 @@ <para>It is also possible to create and join tokens in custom node implementations. For an example on how to do this, check out the Fork and - Join node implementation in the jbpm source code :-).</para> + Join node implementation in the jbpm source code.</para> </section> @@ -614,7 +607,7 @@ <para>Interpretation of the process definition means that the process definition data is stored in the database. At runtime the process definition information is used during process execution. Note for the concerned : - we use hibernate's second level cache to avoid loading of definition information + we use Hibernate's second level cache to avoid loading of definition information at runtime. Since the process definitions don't change (see process versioning) hibernate can cache the process definitions in memory.</para> @@ -626,7 +619,7 @@ continues till it enters a wait state.</para> <para>A token represents a path of execution. A token has a pointer to a node - in the process graph. During waitstates, the tokens can be persisted + in the process graph. During wait states, the tokens can be persisted in the database. Now we are going to look at the algorithm for calculating the execution of a token. Execution starts when a signal is sent to a token. The execution is then passed over the transitions and nodes via the chain of @@ -650,16 +643,16 @@ <literal>Node.enter(ExecutionContext)</literal> on the destination node of the transition. That method will fire the <literal>node-enter</literal> event and call the <literal>Node.execute(ExecutionContext)</literal>. Each type of node - has its own behaviour that is implementated in the execute method. Each node + has its own behaviour that is implemented in the execute method. Each node is responsible for propagating graph execution by calling the <literal>Node.leave(ExecutionContext,Transition)</literal> again. In summary:</para> <itemizedlist> - <listitem>Token.signal(Transition)</listitem> - <listitem>--> Node.leave(ExecutionContext,Transition)</listitem> - <listitem>--> Transition.take(ExecutionContext)</listitem> - <listitem>--> Node.enter(ExecutionContext)</listitem> - <listitem>--> Node.execute(ExecutionContext)</listitem> + <listitem><para>Token.signal(Transition)</para></listitem> + <listitem><para>--> Node.leave(ExecutionContext,Transition)</para></listitem> + <listitem><para>--> Transition.take(ExecutionContext)</para></listitem> + <listitem><para>--> Node.enter(ExecutionContext)</para></listitem> + <listitem><para>--> Node.execute(ExecutionContext)</para></listitem> </itemizedlist> <para>Note that the complete calculation of the next state, including the invocation @@ -680,14 +673,14 @@ or <literal>taskInstance.end()</literal> will only return when the process has entered a new wait state. </para> - <para>The jPDL feature that we describe here from a modelling perspective is + <para>The jPDL feature that we describe here from a modeling perspective is <xref linkend="asynchronouscontinuations" />. </para> <para>In most situations this is the most straightforward approach because the process execution can easily be bound to server side transactions: the process moves from one state to the next in one transaction. </para> - <para>In some scenarios where in-process calculations take a lot of time, this behaviour + <para>In some scenarios where in-process calculations take a lot of time, this behavior might be undesirable. To cope with this, jBPM includes an asynchronous messaging system that allows to continue a process in an asynchronous manner. Of course, in a java enterprise environment, jBPM can be configured to use a JMS message broker instead of the built in @@ -695,7 +688,7 @@ </para> <para>In any node, jPDL supports the attribute <literal>async=&quot;true&quot;</literal>. Asynchronous nodes will not be executed in the thread of the client. Instead, a message is - sent over the asynschronous messaging system and the thread is returned to the client + sent over the asynchronous messaging system and the thread is returned to the client (meaning that the <literal>token.signal()</literal> or <literal>taskInstance.end()</literal> will return). </para> @@ -714,7 +707,7 @@ in your web application. Alternatively, you should make sure that the CommandExecutor thread is up and running in any other way. </para> - <para>As a process modeller, you should not really be concerned with all this asynchronous + <para>As a process modeler, you should not really be concerned with all this asynchronous messaging. The main point to remember is transaction demarcation: By default jBPM will operate in the transaction of the client, doing the whole calculation until the process enters a wait state. Use <literal>async=&quot;true&quot;</literal> to demarcate a transaction in the process. @@ -722,8 +715,7 @@ <para>Let's look at an example: </para> - <programlisting>... -&lt;start-state&gt; + <programlisting language="xml">&lt;start-state&gt; &lt;transition to=&quot;one&quot; /&gt; &lt;/start-state&gt; &lt;node async=&quot;true&quot; name=&quot;one&quot;&gt; @@ -743,7 +735,7 @@ <para>Client code to interact with process executions (starting and resuming) is exactly the same as with normal (synchronous) processes: </para> - <programlisting>...start a transaction... + <programlisting language="java">//start a transaction JbpmContext jbpmContext = jbpmConfiguration.createContext(); try { ProcessInstance processInstance = jbpmContext.newProcessInstance("my async process"); Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/persistence.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/persistence.xml 2009-02-09 16:40:15 UTC (rev 3819) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/persistence.xml 2009-02-10 02:27:07 UTC (rev 3820) @@ -10,7 +10,7 @@ </para> <para>A process definition can be represented in 3 different forms : as xml, as - java objects and as records in the jBPM database. Executional (=runtime) + java objects and as records in the jBPM database. Execution (or runtime) information and logging information can be represented in 2 forms : as java objects and as records in the jBPM database. </para> @@ -31,13 +31,13 @@ <section id="relationtotheconfigurationframework"><title>Relation to the configuration framework</title> - <para>The persistence API is an integrated with the <link linkend="configuration"> - configuration framework</link> by exposing some convenience persistence methods + <para>The persistence API is an integrated with the + configuration framework<footnote><para><xref linkend="configuration"/>.</para></footnote> by exposing some convenience persistence methods on the JbpmContext. Persistence API operations can therefore be called inside a jBPM context block like this: </para> - <programlisting>JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); + <programlisting language="java">JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); try { // Invoke persistence operations here @@ -51,22 +51,20 @@ <literal>src/config.files/jbpm.cfg.xml</literal>): </para> - <programlisting>&lt;jbpm-configuration&gt; + <programlisting language="xml">&lt;jbpm-configuration&gt; &lt;jbpm-context&gt; &lt;service name='persistence' factory='org.jbpm.persistence.db.DbPersistenceServiceFactory' /&gt; - ... &lt;/jbpm-context&gt; - ... &lt;/jbpm-configuration&gt;</programlisting> </section><section id="conveniencemethodsonjbpmcontext"><title>Convenience methods on JbpmContext</title> <para>The three most common persistence operations are: <itemizedlist> - <listitem>Deploying a process</listitem> - <listitem>Starting a new execution of a process</listitem> - <listitem>Continuing an execution</listitem> + <listitem><para>Deploying a process</para></listitem> + <listitem><para>Starting a new execution of a process</para></listitem> + <listitem><para>Continuing an execution</para></listitem> </itemizedlist> </para> @@ -75,7 +73,7 @@ you can see how this is done programmatically: </para> - <programlisting>JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); + <programlisting language="java">JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); try { ProcessDefinition processDefinition = ...; jbpmContext.deployProcessDefinition(processDefinition); @@ -89,7 +87,7 @@ process in the database: </para> - <programlisting>JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); + <programlisting language="java">JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); try { String processName = ...; ProcessInstance processInstance = @@ -100,11 +98,11 @@ <para>For continuing a process execution, we need to fetch the process instance, the token or the taskInstance from the database, invoke some methods on the POJO jBPM - objects and afterwards save the updates made to the processInstance into the database + objects and afterward save the updates made to the processInstance into the database again. </para> - <programlisting>JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); + <programlisting language="java">JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); try { long processInstanceId = ...; ProcessInstance processInstance = @@ -124,7 +122,7 @@ to do this is to use the loadTaskInstanceForUpdate method: </para> - <programlisting>JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); + <programlisting language="java">JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); try { long taskInstanceId = ...; TaskInstance taskInstance = @@ -169,13 +167,13 @@ server like JBoss. The most common scenario is the following: </para> <itemizedlist> - <listitem>Configure a DataSource in your application server + <listitem><para>Configure a DataSource in your application server</para> </listitem> - <listitem>Configure hibernate to use that data source for its connections + <listitem><para>Configure hibernate to use that data source for its connections</para> </listitem> - <listitem>Use container managed transactions + <listitem><para>Use container managed transactions</para> </listitem> - <listitem>Disable transactions in jBPM + <listitem><para>Disable transactions in jBPM</para> </listitem> </itemizedlist> @@ -188,11 +186,11 @@ <para>The transaction attribute of the jbpm session facade methods should be 'required' </para> - <para>The the most important configuration property to specify in the hibernate.cfg.xml + <para>The the most important configuration property to specify in the <filename>hibernate.cfg.xml</filename> that is used by jbpm is: </para> - <programlisting>hibernate.connection.datasource= --datasource JNDI name-- like e.g. java:/JbpmDS</programlisting> + <programlisting language="xml">&lt;property name="hibernate.connection.datasource"&gt;datasource JNDI name -- e.g. java:/JbpmDS&lt;/property&gt;</programlisting> <para>More information on how to configure jdbc connections in hibernate, see <ulink url="http://www.hibernate.org/hib_docs/reference/en/html/session-con... the hibernate reference manual, section 'Hibernate provided JDBC connections'</ulink> @@ -218,7 +216,7 @@ API snippet: </para> - <programlisting>JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); + <programlisting language="java">JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); try { jbpmContext.setSession(SessionFactory.getCurrentSession()); @@ -253,7 +251,7 @@ for closing the connection from jBPM to the API user. </para> - <programlisting>JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); + <programlisting language="java">JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); try { // to inject resources in the jbpmContext before they are used, you can use jbpmContext.setConnection(connection); @@ -299,7 +297,7 @@ must be combined as nested elements. Like this: </para> - <programlisting> &lt;jbpm-context&gt; + <programlisting language="xml"> &lt;jbpm-context&gt; &lt;service name="persistence"&gt; &lt;factory&gt; &lt;bean class="org.jbpm.persistence.db.DbPersistenceServiceFactory"&gt; @@ -317,29 +315,29 @@ &lt;/jbpm-context&gt;</programlisting> <itemizedlist> - <listitem><emphasis role="bold">isTransactionEnabled</emphasis>: by default, jBPM will + <listitem><para><emphasis role="bold">isTransactionEnabled</emphasis>: by default, jBPM will begin a hibernate transaction when the session is fetched the first time and if the jbpmContext is closed, the hibernate transaction will be ended. The transaction is then committed or rolled back depending on wether jbpmContext.setRollbackOnly was called. The isRollbackOnly property is maintained in the TxService. To disable transactions and prohibit jBPM from managing transactions with hibernate, configure the isTransactionEnabled - property to false as in the example above. This property only controls the behaviour of + property to false as in the example above. This property only controls the behavior of the jbpmContext, you can still call the DbPersistenceService.beginTransaction() directly with the API, which ignores the isTransactionEnabled setting. For more info about transactions, see - <xref linkend="hibernatetransactions" />. + <xref linkend="hibernatetransactions" />.</para> </listitem> - <listitem><emphasis role="bold">sessionFactoryJndiName</emphasis>: by default, this + <listitem><para><emphasis role="bold">sessionFactoryJndiName</emphasis>: by default, this is null, meaning that the session factory is not fetched from JNDI. If set and a session factory is needed to create a hibernate session, the session factory - will be fetched from jndi using the provided JNDI name. + will be fetched from jndi using the provided JNDI name.</para> </listitem> - <listitem><emphasis role="bold">dataSourceJndiName</emphasis>: by default, this is + <listitem><para><emphasis role="bold">dataSourceJndiName</emphasis>: by default, this is null and creation of JDBC connections will be delegated to hibernate. By specifying a datasource, jBPM will fetch a JDBC connection from the datasource and provide that to hibernate while opening a new session. For user provided JDBC connections, - see <xref linkend="injectingresourcesprogrammatically" />. - </listitem> + see <xref linkend="injectingresourcesprogrammatically" />.</para> + </listitem> </itemizedlist> </section> @@ -352,14 +350,12 @@ and can be customized in the jbpm.cfg.xml. This is the default configuration: </para> - <programlisting>&lt;jbpm-configuration&gt; - ... + <programlisting language="xml">&lt;jbpm-configuration&gt; &lt;!-- configuration resource files pointing to default configuration files in jbpm-{version}.jar --&gt; &lt;string name='resource.hibernate.cfg.xml' value='hibernate.cfg.xml' /&gt; &lt;!-- &lt;string name='resource.hibernate.properties' value='hibernate.properties' /&gt; --&gt; - ... &lt;/jbpm-configuration&gt;</programlisting> <para>When the property <emphasis role="bold">resource.hibernate.properties</emphasis> @@ -385,15 +381,15 @@ <para>For more information about configuring a cache provider in hibernate, take a look at <ulink url="http://www.hibernate.org/hib_docs/reference/en/html/performance... the hibernate documentation, section 'Second level cache'</ulink> </para> - <para>The hibernate.cfg.xml that ships with jBPM includes the following line: + <para>The <filename>hibernate.cfg.xml</filename> that ships with jBPM includes the following line: </para> - <programlisting>&lt;property name="hibernate.cache.provider_class"&gt;org.hibernate.cache.HashtableCacheProvider&lt;/property&gt;</programlisting> - <para>This is done to get people up and running as fast as possible without having to worrie about classpaths. + <programlisting language="xml">&lt;property name="hibernate.cache.provider_class"&gt;org.hibernate.cache.HashtableCacheProvider&lt;/property&gt;</programlisting> + <para>This is done to get people up and running as fast as possible without having to worry about classpaths. Note that hibernate contains a warning that states not to use the HashtableCacheProvider in production. </para> <para>To use ehcache instead of the HashtableCacheProvider, simply remove that line and put ehcache.jar on the classpath. Note that you might have to search for the right ehcache library version that is compatible with - your environmment. Previous incompatibilities between a jboss version and a perticular ehcache version were + your environmment. Previous incompatibilities between a JBoss version and a particular ehcache version were the reason to change the default to HashtableCacheProvider. </para> </section> @@ -424,7 +420,7 @@ server like JBoss. The most common scenario to bind your transactions to JTA is the following: </para> - <programlisting> &lt;jbpm-context&gt; + <programlisting language="xml"> &lt;jbpm-context&gt; &lt;service name="persistence"&gt; &lt;factory&gt; &lt;bean class="org.jbpm.persistence.db.DbPersistenceServiceFactory"&gt; @@ -436,18 +432,17 @@ &lt;/bean&gt; &lt;/factory&gt; &lt;/service&gt; - ... &lt;/jbpm-context&gt;</programlisting> <para>Then you should specify in your hibernate session factory to use a datasource and bind hibernate to the transaction manager. Make sure that you bind the datasource - to an XA datasource in case you're using more then 1 resource. For more information + to an XA datasource in case you are using more than one resource. For more information about binding hibernate to your transaction manager, please, refer to <ulink url="http://www.hibernate.org/hib_docs/v3/reference/en/html_single/#... 'Transaction strategy configuration' in the hibernate documentation</ulink>. </para> - <programlisting>&lt;hibernate-configuration&gt; + <programlisting language="xml">&lt;hibernate-configuration&gt; &lt;session-factory&gt; &lt;!-- hibernate dialect --&gt; @@ -461,7 +456,6 @@ &lt;property name="hibernate.transaction.manager_lookup_class"&gt;org.hibernate.transaction.JBossTransactionManagerLookup&lt;/property&gt; &lt;property name="jta.UserTransaction"&gt;java:comp/UserTransaction&lt;/property&gt; - ... &lt;/session-factory&gt; &lt;/hibernate-configuration&gt;</programlisting> @@ -480,11 +474,9 @@ That resource file is referenced in the hibernate.cfg.xml configuration file like this: </para> - <programlisting>&lt;hibernate-configuration&gt; - ... + <programlisting language="xml">&lt;hibernate-configuration&gt; &lt;!-- hql queries and type defs --&gt; &lt;mapping resource="org/jbpm/db/hibernate.queries.hbm.xml" /&gt; - ... &lt;/hibernate-configuration&gt;</programlisting> <para>To customize one or more of those queries, take a copy of the original file and put your customized version somewhere on the classpath. Then update the @@ -522,11 +514,11 @@ use a different database: </para> <itemizedlist> - <listitem>put the jdbc-driver library archive in the classpath + <listitem><para>put the jdbc-driver library archive in the classpath</para> </listitem> - <listitem>update the hibernate configuration used by jBPM + <listitem><para>update the hibernate configuration used by jBPM</para> </listitem> - <listitem>create the schema in the new database + <listitem><para>create the schema in the new database</para> </listitem> </itemizedlist> </section> @@ -572,7 +564,7 @@ a transaction manager. </para> - <para>Secondly, this enable you to drop your hibernatable persistent object in to the + <para>Secondly, this enable you to drop your Hibernate persistent object in to the process variables without any further hassle. </para> @@ -590,27 +582,27 @@ follows: </para> <itemizedlist> - <listitem>copy the jBPM hibernate mapping file(s) you want to copy from the - sources (<literal>src/jbpm-jpdl-sources.jar</literal>) + <listitem><para>copy the jBPM hibernate mapping file(s) you want to copy from the + sources (<literal>src/jbpm-jpdl-sources.jar</literal>)</para> </listitem> <listitem> - put the copy anywhere you want on the classpath, but make sure it is not - the exact same location as they were before. + <para>put the copy anywhere you want on the classpath, but make sure it is not + the exact same location as they were before</para> </listitem> <listitem> - update the references to the customized mapping files in the hibernate.cfg.xml - configuration file + <para>update the references to the customized mapping files in the hibernate.cfg.xml + configuration file</para> </listitem> </itemizedlist> </section> <section id="secondlevelcache"> <title>Second level cache</title> - <para>jBPM uses hibernate's second level cache for keeping the process definitions + <para>jBPM uses Hibernate's second level cache for keeping the process definitions in memory after loading them once. The process definition classes and collections are configured in the jBPM hibernate mapping files with the cache element like this: </para> - <programlisting>&lt;cache usage="nonstrict-read-write"/&gt;</programlisting> + <programlisting language="xml">&lt;cache usage="nonstrict-read-write"/&gt;</programlisting> <para>Since process definitions (should) never change, it is ok to keep them in the second level cache. See also <xref linkend="changingdeployedprocessdefinitions" />. </para> Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/pluggable.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/pluggable.xml 2009-02-09 16:40:15 UTC (rev 3819) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/pluggable.xml 2009-02-10 02:27:07 UTC (rev 3820) @@ -6,7 +6,7 @@ module is the graph module, made up of the <literal>ProcessDefinition</literal> and the <literal>ProcessInstance</literal>. The process definition contains a graph and the process instance represents - one execution of the graph. All other functionalities of jBPM are grouped into + one execution of the graph. All other functions of jBPM are grouped into optional modules. Optional modules can extend the graph module with extra features like context (process variables), task management, timers, ...</para> @@ -29,7 +29,7 @@ can parse the information added to the process archive, create your custom <literal>ModuleDefinition</literal> and add it to the <literal>ProcessDefinition</literal>.</para> - <programlisting>public interface ProcessArchiveParser { + <programlisting language="java">public interface ProcessArchiveParser { void writeToArchive(ProcessDefinition processDefinition, ProcessArchive archive); ProcessDefinition readFromArchive(ProcessArchive archive, ProcessDefinition processDefinition); Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/scheduler.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/scheduler.xml 2009-02-09 16:40:15 UTC (rev 3819) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/scheduler.xml 2009-02-10 02:27:07 UTC (rev 3820) @@ -11,7 +11,7 @@ <para>The easiest way to specify a timer is by adding a timer element to the node.</para> - <programlisting>&lt;state name='catch crooks'&gt; + <programlisting language="xml">&lt;state name='catch crooks'&gt; &lt;timer name='reminder' duedate='3 business hours' repeat='10 business minutes' @@ -26,10 +26,10 @@ is executed, the following events occur in sequence : </para> <itemizedlist> - <listitem>an event is fired of type <literal>timer</literal></listitem> - <listitem>if an action is specified, the action is executed.</listitem> - <listitem>if a transition is specified, a signal will be sent to resume execution - over the given transition.</listitem> + <listitem><para>an event is fired of type <literal>timer</literal></para></listitem> + <listitem><para>if an action is specified, the action is executed.</para></listitem> + <listitem><para>if a transition is specified, a signal will be sent to resume execution + over the given transition.</para></listitem> </itemizedlist> <para>Every timer must have a unique name. If no name is specified in the @@ -39,7 +39,7 @@ <para>The timer action can be any supported action element like e.g. <literal>action</literal> or <literal>script</literal>.</para> - <para>Timers are created and cancelled by actions. The 2 action-elements are + <para>Timers are created and canceled by actions. The 2 action-elements are <literal>create-timer</literal> and <literal>cancel-timer</literal>. Actually, the timer element shown above is just a short notation for a create-timer action on <literal>node-enter</literal> and a cancel-timer action on Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/security.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/security.xml 2009-02-09 16:40:15 UTC (rev 3819) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/security.xml 2009-02-10 02:27:07 UTC (rev 3820) @@ -6,7 +6,7 @@ parts of the framework are finished and what parts not yet.</para> <section id="securitytodos"> - <title>Todos</title> + <title>TODOS</title> <para>On the framework part, we still need to define a set of permissions that are verified by the jbpm engine while a process is being executed. Currently you can check your own permissions, but there is not yet a jbpm @@ -26,7 +26,7 @@ <para>Authentication is the process of knowing on who's behalf the code is running. In case of jBPM this information should be made available from the environment to jBPM. Cause jBPM is always executed in a specific environment like - a webapp, an EJB, a swing application or some other environment, it is always the + a web application, an EJB, a swing application or some other environment, it is always the surrounding environment that should perform authentication.</para> <para>In a few situations, jBPM needs to know who is running the code. E.g. to add authentication information in the process logs to know who did what and when. Another @@ -61,11 +61,11 @@ operation with the API method <literal>org.jbpm.security.Authorization.checkPermission(Permission)</literal>. </para> <para>The Authorization class will also delegate that call to a configurable implementation. - The interface for pluggin in different authorization strategies is + The interface for plugging in different authorization strategies is <literal>org.jbpm.security.authorizer.Authorizer</literal>.</para> <para>In the package org.jbpm.security.authorizer there are some examples that show intentions - of authorizer implementations. Most are not fully implemented and none of them are tested.</para> - <para>Also still todo is the definition of a set of jBPM permissions and the verification of + of authorized implementations. Most are not fully implemented and none of them are tested.</para> + <para>Also still to do is the definition of a set of jBPM permissions and the verification of those permissions by the jBPM engine. An example could be verifying that the current authenticated user has sufficient privileges to end a task by calling <literal>Authorization.checkPermission(new TaskPermission("end", Long.toString(id)))</literal> Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/taskmgmt.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/taskmgmt.xml 2009-02-09 16:40:15 UTC (rev 3819) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/taskmgmt.xml 2009-02-10 02:27:07 UTC (rev 3820) @@ -3,7 +3,7 @@ <title>Task management</title> <para>The core business of jBPM is the ability to persist the execution of a process. A situation in which this feature is extremely useful is - the management of tasks and tasklists for people. jBPM allows to + the management of tasks and task-lists for people. jBPM allows to specify a piece of software describing an overall process which can have wait states for human tasks.</para> @@ -20,7 +20,7 @@ done by the user and the process execution should wait until the actor completes the task. When the actor completes the task, process execution should continue. When more tasks are specified in a - <literal>task-node</literal>, the default behaviour is to wait for all the + <literal>task-node</literal>, the default behavior is to wait for all the tasks to complete. </para> @@ -34,7 +34,7 @@ <para>Task names must be unique in the whole process definition. Tasks can be given a <literal>priority</literal>. This priority will be used as the initial priority for each task instance that is created for this task. - TaskInstances can change this initial priority afterwards.</para> + TaskInstances can change this initial priority afterward.</para> </section> <section id="taskinstances"> @@ -42,7 +42,7 @@ <para>A task instance can be assigned to an actorId (java.lang.String). All task instances are stored in one table of the database (JBPM_TASKINSTANCE). By querying this table for - all task instances for a given actorId, you get the task list for that perticular user. + all task instances for a given actorId, you get the task list for that particular user. </para> <para>The jBPM task list mechanism can combine jBPM tasks with other tasks, even when those @@ -51,8 +51,8 @@ </para> <section id="taskinstancelifecycle"> - <title>Task instance lifecycle</title> - <para>The task instance lifecycle is straightforward: After creation, task instances can optionally + <title>Task instance life-cycle</title> + <para>The task instance life-cycle is straightforward: After creation, task instances can optionally be started. Then, task instances can be ended, which means that the task instance is marked as completed.</para> <para>Note that for flexibility, assignment is not part of the life cycle. So task instances @@ -60,12 +60,12 @@ task instance life cycle.</para> <para>Task instances are typically created by the process execution entering a <literal>task-node</literal> (with the method <literal>TaskMgmtInstance.createTaskInstance(...)</literal>). - Then, a user interface component will query the database for the tasklists using the + Then, a user interface component will query the database for the task lists using the <literal>TaskMgmtSession.findTaskInstancesByActorId(...)</literal>. Then, after collecting input from the user, the UI component calls <literal>TaskInstance.assign(String)</literal>, <literal>TaskInstance.start()</literal> or <literal>TaskInstance.end(...)</literal>. </para> - <para>A task instance maintains it's state by means of date-properties : <literal>create</literal>, + <para>A task instance maintains its state by means of date-properties : <literal>create</literal>, <literal>start</literal> and <literal>end</literal>. Those properties can be accessed by their respective getters on the <literal>TaskInstance</literal>.</para> <para>Currently, completed task instances are marked with an end date so that they are not @@ -75,7 +75,7 @@ <section id="taskinstancesandgraphexecution"> <title>Task instances and graph execution</title> - <para>Task instances are the items in an actor's tasklist. Task instances + <para>Task instances are the items in an actor's task list. Task instances can be signalling. A signalling task instance is a task instance that, when completed, can send a signal to its token to continue the process execution. Task instances can be blocking, meaning that the related token (=path of @@ -89,12 +89,12 @@ given to the signal-property of a task-node.</para> <itemizedlist> - <listitem><emphasis role="bold">last</emphasis>: This is the default. Proceeds execution when the last task instance is completed. When no tasks are created on entrance of this node, execution is continued.</listitem> - <listitem><emphasis role="bold">last-wait</emphasis>: Proceeds execution when the last task instance is completed. When no tasks are created on entrance of this node, execution waits in the task node till tasks are created.</listitem> - <listitem><emphasis role="bold">first</emphasis>: Proceeds execution when the first task instance is completed. When no tasks are created on entrance of this node, execution is continued.</listitem> - <listitem><emphasis role="bold">first-wait</emphasis>: Proceeds execution when the first task instance is completed. When no tasks are created on entrance of this node, execution waits in the task node till tasks are created.</listitem> - <listitem><emphasis role="bold">unsynchronized</emphasis>: Execution always continues, regardless wether tasks are created or still unfinished.</listitem> - <listitem><emphasis role="bold">never</emphasis>: Execution never continues, regardless wether tasks are created or still unfinished.</listitem> + <listitem><para><emphasis role="bold">last</emphasis>: This is the default. Proceeds execution when the last task instance is completed. When no tasks are created on entrance of this node, execution is continued.</para></listitem> + <listitem><para><emphasis role="bold">last-wait</emphasis>: Proceeds execution when the last task instance is completed. When no tasks are created on entrance of this node, execution waits in the task node until tasks are created.</para></listitem> + <listitem><para><emphasis role="bold">first</emphasis>: Proceeds execution when the first task instance is completed. When no tasks are created on entrance of this node, execution is continued.</para></listitem> + <listitem><para><emphasis role="bold">first-wait</emphasis>: Proceeds execution when the first task instance is completed. When no tasks are created on entrance of this node, execution waits in the task node until tasks are created.</para></listitem> + <listitem><para><emphasis role="bold">unsynchronized</emphasis>: Execution always continues, regardless whether tasks are created or still unfinished.</para></listitem> + <listitem><para><emphasis role="bold">never</emphasis>: Execution never continues, regardless whether tasks are created or still unfinished.</para></listitem> </itemizedlist> <para>Task instance creation might be based upon a runtime calculation. In that case, add an @@ -102,7 +102,7 @@ set the attribute <literal>create-tasks="false"</literal>. Here is an example of such an action handler implementation: </para> - <programlisting>public class CreateTasks implements ActionHandler { + <programlisting language="java">public class CreateTasks implements ActionHandler { public void execute(ExecutionContext executionContext) throws Exception { Token token = executionContext.getToken(); TaskMgmtInstance tmi = executionContext.getTaskMgmtInstance(); @@ -140,13 +140,13 @@ definition. At runtime, tasks result in the creation of task instances. A task instance corresponds to one entry in a person's task list.</para> - <para>With jBPM, <link linkend="thepersonaltasklist">push (personal task list)</link> and - <link linkend="thegrouptasklist">pull (group task list)</link> model (see below) of + <para>With jBPM, push (personal task list)<footnote><para><xref linkend="thepersonaltasklist"/>.</para></footnote> and + pull (group task list)<footnote><para><xref linkend="thegrouptasklist"/>.</para></footnote> model (see below) of task assignment can be applied in combination. - The process can calculate the responsible for a task and push it in his/her tasklist. + The process can calculate the responsible for a task and push it in his/her task list. Or alternatively, a task can be assigned to a pool of actors, in which case each of the actors in the pool can pull the task and put it in the actor's - personal tasklist. + personal task list. </para> <section id="assignmentinterfaces"> @@ -154,7 +154,7 @@ <para>Assigning task instances is done via the interface <literal>AssignmentHandler</literal>:</para> - <programlisting>public interface AssignmentHandler extends Serializable { + <programlisting language="java">public interface AssignmentHandler extends Serializable { void assign( Assignable assignable, ExecutionContext executionContext ); }</programlisting> @@ -166,7 +166,7 @@ a <literal>TaskInstance</literal> or a <literal>SwimlaneInstance</literal> (=process role). </para> - <programlisting>public interface Assignable { + <programlisting language="java">public interface Assignable { public void setActorId(String actorId); public void setPooledActors(String[] pooledActors); }</programlisting> @@ -180,7 +180,7 @@ <para>Each task in the process definition can be associated with an assignment handler implementation to perform the assignment at runtime.</para> <para>When more than one task in a process should be assigned to the same person - or group of actors, consider the usage of a <link linkend="swimlanes">swimlane</link></para> + or group of actors, consider the usage of a swimlane<footnote><para><xref linkend="swimlanes"/>.</para></footnote></para> <para>To allow for the creation of reusable <literal>AssignmentHandler</literal>s, each usage of an <literal>AssignmentHandler</literal> can be configured in the <literal>processdefinition.xml</literal>. See <xref linkend="delegation" /> @@ -189,7 +189,7 @@ <section id="theassignmentdatamodel"> <title>The assignment data model</title> - <para>The datamodel for managing assignments of task instances and swimlane instances to + <para>The data model for managing assignments of task instances and swimlane instances to actors is the following. Each <literal>TaskInstance</literal> has an actorId and a set of pooled actors.</para> @@ -212,9 +212,9 @@ to put a TaskInstance in someone's personal task list, you just use one of the following ways: </para> <itemizedlist> - <listitem>Specify an expression in the attribute <literal>actor-id</literal> of the task element in the process</listitem> - <listitem>Use TaskInstance.setActorId(String) from anywhere in your code</listitem> - <listitem>Use assignable.setActorId(String) in an AssignmentHandler</listitem> + <listitem><para>Specify an expression in the attribute <literal>actor-id</literal> of the task element in the process</para></listitem> + <listitem><para>Use TaskInstance.setActorId(String) from anywhere in your code</para></listitem> + <listitem><para>Use assignable.setActorId(String) in an AssignmentHandler</para></listitem> </itemizedlist> <para>To fetch the personal task list for a given user, use <literal>TaskMgmtSession.findTaskInstances(String actorId)</literal>. </para> @@ -229,12 +229,12 @@ allowed to start working on tasks that are in their personal task list. </para> <para>To put a taskInstance in someone's group task list, you must put the user's actorId or one of the user's - groupIds in the pooledActorIds. So specify the pooled actors, use one of the following: + groupIds in the pooledActorIds. To specify the pooled actors, use one of the following: </para> <itemizedlist> - <listitem>Specify an expression in the attribute <literal>pooled-actor-ids</literal> of the task element in the process</listitem> - <listitem>Use TaskInstance.setPooledActorIds(String[]) from anywhere in your code</listitem> - <listitem>Use assignable.setPooledActorIds(String[]) in an AssignmentHandler</listitem> + <listitem><para>Specify an expression in the attribute <literal>pooled-actor-ids</literal> of the task element in the process</para></listitem> + <listitem><para>Use TaskInstance.setPooledActorIds(String[]) from anywhere in your code</para></listitem> + <listitem><para>Use assignable.setPooledActorIds(String[]) in an AssignmentHandler</para></listitem> </itemizedlist> <para>To fetch the group task list for a given user, proceed as follows: Make a collection that includes the user's actorId and all the ids of groups that the user belongs to. With <literal>TaskMgmtSession.findPooledTaskInstances(String actorId)</literal> or @@ -265,7 +265,7 @@ <para>This means that a task instance can 'see' its own variables plus all the variables of its related token. </para> - <para>The controller can be used to create populate and submit variables between + <para>The controller can be used to create, populate and submit variables between the task instance scope and the process scoped variables. </para> </section> @@ -281,13 +281,13 @@ to: </para> <itemizedlist> - <listitem>a) create copies of variables in the task instances so that intermediate updates - to the task instance variables don't affect the process variables untill the process - is finished and the copies are submitted back into the process variables. + <listitem><para>a) create copies of variables in the task instances so that intermediate updates + to the task instance variables don't affect the process variables until the process + is finished and the copies are submitted back into the process variables.</para> </listitem> - <listitem>b) the task instance variables do not relate one-on-one with the process variables. - E.g. suppose the process has variables 'sales in januari' 'sales in februari' and 'sales in march'. - Then the form for the task instance might need to show the average sales in the 3 months. + <listitem><para>b) the task instance variables do not relate one-on-one with the process variables. + E.g. suppose the process has variables 'sales in January' 'sales in February' and 'sales in march'. + Then the form for the task instance might need to show the average sales in the 3 months.</para> </listitem> </itemizedlist> <para>Tasks are intended to collect input from users. But there are many user interfaces @@ -318,7 +318,7 @@ based on the process variables: </para> - <programlisting>&lt;task name=&quot;clean ceiling&quot;&gt; + <programlisting language="xml">&lt;task name=&quot;clean ceiling&quot;&gt; &lt;controller&gt; &lt;variable name=&quot;a&quot; access=&quot;read&quot; mapped-name=&quot;x&quot; /&gt; &lt;variable name=&quot;b&quot; access=&quot;read,write,required&quot; mapped-name=&quot;y&quot; /&gt; @@ -335,7 +335,7 @@ <para> The <literal>access</literal> attribute specifies if the variable is copied at task instance - creation, will be written back to the process variables at task end and wether it is + creation, will be written back to the process variables at task end and whether it is required. This information can be used by the user interface to generate the proper form controls. The access attribute is optional and the default access is 'read,write'. @@ -349,14 +349,14 @@ can also write your own TaskControllerHandler implementation. Here's the TaskControllerHandler interface: </para> - <programlisting>public interface TaskControllerHandler extends Serializable { + <programlisting language="java">public interface TaskControllerHandler extends Serializable { void initializeTaskVariables(TaskInstance taskInstance, ContextInstance contextInstance, Token token); void submitTaskVariables(TaskInstance taskInstance, ContextInstance contextInstance, Token token); }</programlisting> <para>And here's how to configure your custom task controller implementation in a task:</para> - <programlisting>&lt;task name=&quot;clean ceiling&quot;&gt; + <programlisting language="xml">&lt;task name=&quot;clean ceiling&quot;&gt; &lt;controller class=&quot;com.yourcom.CleanCeilingTaskControllerHandler&quot;&gt; -- here goes your task controller handler configuration -- &lt;/controller&gt; @@ -370,9 +370,9 @@ after the first task instance is created for a given swimlane, the actor should be remembered in the process for all subsequent tasks that are in the same swimlane. A swimlane therefore has one - <link linkend="assignment"><literal>assignment</literal></link> + <literal>assignment</literal><footnote><para><xref linkend="assignment"/>.</para></footnote> and all tasks that reference a swimlane should not specify an - <link linkend="assignment"><literal>assignment</literal></link>. + <literal>assignment</literal><footnote><para><xref linkend="assignment"/>.</para></footnote>. </para> <para>When the first task in a given swimlane is created, the @@ -380,9 +380,9 @@ The <literal>Assignable</literal> that is passed to the <literal>AssignmentHandler</literal> will be the <literal>SwimlaneInstance</literal>. Important to know is that all assignments that are done on the task instances in a given swimlane will - propagate to the swimlane instance. This behaviour is implemented as the default + propagate to the swimlane instance. This behavior is implemented as the default because the person that takes a task to fulfilling a certain process role will - have the knowledge of that perticular process. So all subsequent assignements + have the knowledge of that particular process. So all subsequent assignments of task instances to that swimlane are done automatically to that user. </para> @@ -397,17 +397,16 @@ <para>A task can be specified in a start-state. That task be associated with a swimlane. When a new task instance is created for such a task, the current authenticated actor will be captured with - <link linkend="authentication">Authentication.getAuthenticatedActorId()</link> + Authentication.getAuthenticatedActorId()<footnote><para><xref linkend="authentication"/>.</para></footnote> and that actor will be stored in the swimlane of the start task. </para> <para>For example:</para> - <programlisting>&lt;process-definition&gt; + <programlisting language="xml">&lt;process-definition&gt; &lt;swimlane name='initiator' /&gt; &lt;start-state&gt; &lt;task swimlane='initiator' /&gt; &lt;transition to='...' /&gt; &lt;/start-state&gt; - ... &lt;/process-definition&gt;</programlisting> <para>Also variables can be added to the start task as with any other task to define the form associated with the task. See <xref linkend="taskcontrollers"/></para> @@ -439,7 +438,7 @@ <title>Task timers</title> <para>As on nodes, timers can be specified on tasks. See <xref linkend="timers" />.</para> <para>The special thing about timers for tasks is that the <literal>cancel-event</literal> - for task timers can be customized. By default, a timer on a task will be cancelled when + for task timers can be customized. By default, a timer on a task will be canceled when the task is ended (=completed). But with the <literal>cancel-event</literal> attribute on the timer, process developers can customize that to e.g. <literal>task-assign</literal> or <literal>task-start</literal>. The <literal>cancel-event</literal> supports multiple @@ -470,20 +469,20 @@ </para> <para>The jBPM identity management component - includes knowledge of the organisational model. - Task assignment is typically done with organisational knowledge. - So this implies knowledge of an organisational model, describing the + includes knowledge of the organizational model. + Task assignment is typically done with organizational knowledge. + So this implies knowledge of an organizational model, describing the users, groups, systems and the relations between them. Optionally, - permissions and roles can be included too in an organisational model. + permissions and roles can be included too in an organizational model. Various academic research attempts failed, proving that no generic - organisational model can be created that fits every organisation. + organizational model can be created that fits every organization. </para> <para>The way jBPM handles this is by defining an actor as an actual participant in a process. An actor is identified by its ID called an - actorId. jBPM has only knowledge about actorId's and they are represented + actorId. jBPM has only knowledge about actorIds and they are represented as <literal>java.lang.String</literal>s for maximum flexibility. So any - knowledge about the organisational model and the structure of that data + knowledge about the organizational model and the structure of that data is outside the scope of the jBPM core engine.</para> <para>As an extension to jBPM we will provide (in the future) a component to manage that simple user-roles model. This many to many relation between @@ -496,7 +495,7 @@ portlet specifications, is not sufficiently powerful for handling task assignments. That model is a many-to-many relation between users and roles. This doesn't include information about the teams and - the organisational structure of users involved in a process.</para> + the organizational structure of users involved in a process.</para> <section id="theidentitymodel"> <title>The identity model</title> @@ -514,10 +513,10 @@ Groups can be nested to model the relation between a team, a business unit and the whole company. Groups have a type to differentiate between the hierarchical groups and e.g. - haircolor groups. <literal>Membership</literal>s represent the + hair color groups. <literal>Membership</literal>s represent the many-to-many relation between users and groups. A membership can be used to represent a position in a company. The name of the membership - can be used to indicate the role that the user fullfills in the + can be used to indicate the role that the user fulfills in the group.</para> </section> @@ -527,15 +526,13 @@ expression for the calculation of actors during assignment of tasks. Here's an example of using the assignment expression in a process definition:</para> - <programlisting>&lt;process-definition&gt; - ... + <programlisting language="xml">&lt;process-definition&gt; &lt;task-node name='a'&gt; &lt;task name='laundry'&gt; &lt;assignment expression='previous --> group(hierarchy) --> member(boss)' /&gt; &lt;/task&gt; &lt;transition to='b' /&gt; - &lt;/task-node&gt; - ...</programlisting> + &lt;/task-node&gt;</programlisting> <para>Syntax of the assignment expression is like this:</para> <programlisting>first-term --> next-term --> next-term --> ... --> next-term @@ -599,11 +596,11 @@ <section id="removingtheidentitycomponent"> <title>Removing the identity component</title> - <para>When you want to use your own datasource for organisational - information such as your company's user database or ldap system, + <para>When you want to use your own datasource for organizational + information such as your company's user database or LDAP system, you can just rip out the jBPM identity component. The only thing you need to do is make sure that you delete the line ...</para> - <programlisting>&lt;mapping resource="org/jbpm/identity/User.hbm.xml"/&gt; + <programlisting language="xml">&lt;mapping resource="org/jbpm/identity/User.hbm.xml"/&gt; &lt;mapping resource="org/jbpm/identity/Group.hbm.xml"/&gt; &lt;mapping resource="org/jbpm/identity/Membership.hbm.xml"/&gt;</programlisting> @@ -614,7 +611,7 @@ store, you can extend from the <literal>ExpressionAssignmentHandler</literal> and override the method <literal>getExpressionSession</literal>. </para> - <programlisting>protected ExpressionSession getExpressionSession(AssignmentContext assignmentContext);</programlisting> + <programlisting language="java">protected ExpressionSession getExpressionSession(AssignmentContext assignmentContext);</programlisting> </section> </section> Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/tdd.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/tdd.xml 2009-02-09 16:40:15 UTC (rev 3819) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/tdd.xml 2009-02-10 02:27:07 UTC (rev 3820) @@ -1,6 +1,6 @@ <chapter id="tdd"> - <title>TDD for workflow</title> + <title>Test Driven Development for Workflow</title> <section id="intoducingtddforworkflow"> <title>Introducing TDD for workflow</title> @@ -15,7 +15,7 @@ you how to develop and test jBPM processes without intermediate steps.</para> <para>Mostly the unit tests of process definitions are execution scenarios. - Each scenario is executed in one JUnit testmethod and will feed in the external + Each scenario is executed in one JUnit test method and will feed in the external triggers (read: signals) into a process execution and verifies after each signal if the process is in the expected state.</para> @@ -29,7 +29,7 @@ <para>Now, let's write a test that executes the main scenario:</para> - <programlisting>public class AuctionTest extends TestCase { + <programlisting language="java">public class AuctionTest extends TestCase { // parse the process definition static ProcessDefinition auctionProcess = @@ -92,10 +92,8 @@ in a file called <literal>processdefinition.xml</literal>. The jBPM process designer reads and writes process archives. For example:</para> - <programlisting>... -static ProcessDefinition auctionProcess = - ProcessDefinition.parseParResource("org/jbpm/tdd/auction.par"); -...</programlisting> + <programlisting language="java">static ProcessDefinition auctionProcess = + ProcessDefinition.parseParResource("org/jbpm/tdd/auction.par");</programlisting> </section> <section id="parsinganxmlfile"> @@ -105,10 +103,8 @@ with e.g. an ant script. In that case, you can use the <literal>JpdlXmlReader</literal></para> - <programlisting>... -static ProcessDefinition auctionProcess = - ProcessDefinition.parseXmlResource("org/jbpm/tdd/auction.xml"); -...</programlisting> + <programlisting language="java">static ProcessDefinition auctionProcess = + ProcessDefinition.parseXmlResource("org/jbpm/tdd/auction.xml");</programlisting> </section> <section id="parsinganxmlstring"> @@ -116,8 +112,7 @@ <para>The simplest option is to parse the xml in the unit test inline from a plain String.</para> - <programlisting>... -static ProcessDefinition auctionProcess = + <programlisting>static ProcessDefinition auctionProcess = ProcessDefinition.parseXmlString( "&lt;process-definition>" + " &lt;start-state name='start'&gt;" + Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/tutorial.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/tutorial.xml 2009-02-09 16:40:15 UTC (rev 3819) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/tutorial.xml 2009-02-10 02:27:07 UTC (rev 3820) @@ -7,7 +7,7 @@ <para>The format of this tutorial is explaining a set of examples. The examples focus on a particular topic and contain extensive - comments. The examples can also be fond in the jBPM download package + comments. The examples can also be found in the jBPM download package in the directory <literal>src/java.examples</literal>.</para> <para>The best way to learn is to create a project and experiment @@ -37,57 +37,57 @@ <mediaobject><imageobject><imagedata align="center" fileref="images/hello.world.gif"/></imageobject></mediaobject> </figure> - <programlisting>public void testHelloWorldProcess() { - <emphasis role="bold">// This method shows a process definition and one execution</emphasis> - <emphasis role="bold">// of the process definition. The process definition has </emphasis> - <emphasis role="bold">// 3 nodes: an unnamed start-state, a state 's' and an </emphasis> - <emphasis role="bold">// end-state named 'end'.</emphasis> - <emphasis role="bold">// The next line parses a piece of xml text into a</emphasis> - <emphasis role="bold">// ProcessDefinition. A ProcessDefinition is the formal </emphasis> - <emphasis role="bold">// description of a process represented as a java object.</emphasis> - ProcessDefinition processDefinition = ProcessDefinition.parseXmlString( - &quot;<emphasis role="bold">&lt;process-definition&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;start-state&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;transition to='s' /&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;/start-state&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;state name='s'&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;transition to='end' /&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;/state&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;end-state name='end' /&gt;</emphasis>&quot; + - &quot;<emphasis role="bold">&lt;/process-definition&gt;</emphasis>&quot; - ); + <programlisting language="java">public void testHelloWorldProcess() { +// This method shows a process definition and one execution +// of the process definition. The process definition has +// 3 nodes: an unnamed start-state, a state 's' and an +// end-state named 'end'. +// The next line parses a piece of xml text into a +// ProcessDefinition. A ProcessDefinition is the formal +// description of a process represented as a java object. +ProcessDefinition processDefinition = ProcessDefinition.parseXmlString( + &quot;&lt;process-definition&gt;&quot; + + &quot; &lt;start-state&gt;&quot; + + &quot; &lt;transition to='s' /&gt;&quot; + + &quot; &lt;/start-state&gt;&quot; + + &quot; &lt;state name='s'&gt;&quot; + + &quot; &lt;transition to='end' /&gt;&quot; + + &quot; &lt;/state&gt;&quot; + + &quot; &lt;end-state name='end' /&gt;&quot; + + &quot;&lt;/process-definition&gt;&quot; +); - <emphasis role="bold">// The next line creates one execution of the process definition.</emphasis> - <emphasis role="bold">// After construction, the process execution has one main path</emphasis> - <emphasis role="bold">// of execution (=the root token) that is positioned in the</emphasis> - <emphasis role="bold">// start-state.</emphasis> + // The next line creates one execution of the process definition. + // After construction, the process execution has one main path + // of execution (=the root token) that is positioned in the + // start-state. ProcessInstance processInstance = new ProcessInstance(processDefinition); - <emphasis role="bold">// After construction, the process execution has one main path</emphasis> - <emphasis role="bold">// of execution (=the root token).</emphasis> + // After construction, the process execution has one main path + // of execution (=the root token). Token token = processInstance.getRootToken(); - <emphasis role="bold">// Also after construction, the main path of execution is positioned</emphasis> - <emphasis role="bold">// in the start-state of the process definition.</emphasis> + // Also after construction, the main path of execution is positioned + // in the start-state of the process definition. assertSame(processDefinition.getStartState(), token.getNode()); - <emphasis role="bold">// Let's start the process execution, leaving the start-state </emphasis> - <emphasis role="bold">// over its default transition.</emphasis> + // Let's start the process execution, leaving the start-state + // over its default transition. token.signal(); - <emphasis role="bold">// The signal method will block until the process execution </emphasis> - <emphasis role="bold">// enters a wait state.</emphasis> + // The signal method will block until the process execution + // enters a wait state. - <emphasis role="bold">// The process execution will have entered the first wait state</emphasis> - <emphasis role="bold">// in state 's'. So the main path of execution is now </emphasis> - <emphasis role="bold">// positioned in state 's'</emphasis> + // The process execution will have entered the first wait state + // in state 's'. So the main path of execution is now + // positioned in state 's' assertSame(processDefinition.getNode("s"), token.getNode()); - <emphasis role="bold">// Let's send another signal. This will resume execution by </emphasis> - <emphasis role="bold">// leaving the state 's' over its default transition.</emphasis> + // Let's send another signal. This will resume execution by + // leaving the state 's' over its default transition. token.signal(); - <emphasis role="bold">// Now the signal method returned because the process instance </emphasis> - <emphasis role="bold">// has arrived in the end-state.</emphasis> + // Now the signal method returned because the process instance + // has arrived in the end-state. assertSame(processDefinition.getNode("end"), token.getNode()); }</programlisting> @@ -99,41 +99,41 @@ in the database when they are in a wait state. The next example will show you how to store a process instance in the jBPM database. The example also suggests a context in which this might occur. Separate methods are created for different pieces of user code. - E.g. an piece of user code in a webapplication starts a process and persists the + E.g. an piece of user code in a web application starts a process and persists the execution in the database. Later, a message driven bean loads the process instance from the database and resumes its execution. </para> <para>More about the jBPM persistence can be found in <xref linkend="persistence" />.</para> - <programlisting>public class HelloWorldDbTest extends TestCase { + <programlisting language="java">public class HelloWorldDbTest extends TestCase { static JbpmConfiguration jbpmConfiguration = null; static { - <emphasis role="bold">// An example configuration file such as this can be found in </emphasis> - <emphasis role="bold">// 'src/config.files'. Typically the configuration information is in the </emphasis> - <emphasis role="bold">// resource file 'jbpm.cfg.xml', but here we pass in the configuration </emphasis> - <emphasis role="bold">// information as an XML string.</emphasis> + // An example configuration file such as this can be found in + // 'src/config.files'. Typically the configuration information is in the + // resource file 'jbpm.cfg.xml', but here we pass in the configuration + // information as an XML string. - <emphasis role="bold">// First we create a JbpmConfiguration statically. One JbpmConfiguration</emphasis> - <emphasis role="bold">// can be used for all threads in the system, that is why we can safely </emphasis> - <emphasis role="bold">// make it static.</emphasis> + // First we create a JbpmConfiguration statically. One JbpmConfiguration + // can be used for all threads in the system, that is why we can safely + // make it static. jbpmConfiguration = JbpmConfiguration.parseXmlString( "&lt;jbpm-configuration&gt;" + - <emphasis role="bold">// A jbpm-context mechanism separates the jbpm core </emphasis> - <emphasis role="bold">// engine from the services that jbpm uses from </emphasis> - <emphasis role="bold">// the environment. </emphasis> + // A jbpm-context mechanism separates the jbpm core + // engine from the services that jbpm uses from + // the environment. " &lt;jbpm-context&gt;" + " &lt;service name='persistence' " + " factory='org.jbpm.persistence.db.DbPersistenceServiceFactory' /&gt;" + " &lt;/jbpm-context&gt;" + - <emphasis role="bold">// Also all the resource files that are used by jbpm are </emphasis> - <emphasis role="bold">// referenced from the jbpm.cfg.xml</emphasis> + // Also all the resource files that are used by jbpm are + // referenced from the jbpm.cfg.xml " &lt;string name='resource.hibernate.cfg.xml' " + " value='hibernate.cfg.xml' /&gt;" + @@ -162,31 +162,31 @@ } public void testSimplePersistence() { - <emphasis role="bold">// Between the 3 method calls below, all data is passed via the </emphasis> - <emphasis role="bold">// database. Here, in this unit test, these 3 methods are executed</emphasis> - <emphasis role="bold">// right after each other because we want to test a complete process</emphasis> - <emphasis role="bold">// scenario. But in reality, these methods represent different </emphasis> - <emphasis role="bold">// requests to a server.</emphasis> + // Between the 3 method calls below, all data is passed via the + // database. Here, in this unit test, these 3 methods are executed + // right after each other because we want to test a complete process + // scenario. But in reality, these methods represent different + // requests to a server. - <emphasis role="bold">// Since we start with a clean, empty in-memory database, we have to </emphasis> - <emphasis role="bold">// deploy the process first. In reality, this is done once by the </emphasis> - <emphasis role="bold">// process developer.</emphasis> + // Since we start with a clean, empty in-memory database, we have to + // deploy the process first. In reality, this is done once by the + // process developer. deployProcessDefinition(); - <emphasis role="bold">// Suppose we want to start a process instance (=process execution)</emphasis> - <emphasis role="bold">// when a user submits a form in a web application...</emphasis> + // Suppose we want to start a process instance (=process execution) + // when a user submits a form in a web application... processInstanceIsCreatedWhenUserSubmitsWebappForm(); - <emphasis role="bold">// Then, later, upon the arrival of an asynchronous message the </emphasis> - <emphasis role="bold">// execution must continue.</emphasis> + // Then, later, upon the arrival of an asynchronous message the + // execution must continue. theProcessInstanceContinuesWhenAnAsyncMessageIsReceived(); } public void deployProcessDefinition() { - <emphasis role="bold">// This test shows a process definition and one execution </emphasis> - <emphasis role="bold">// of the process definition. The process definition has </emphasis> - <emphasis role="bold">// 3 nodes: an unnamed start-state, a state 's' and an </emphasis> - <emphasis role="bold">// end-state named 'end'.</emphasis> + // This test shows a process definition and one execution + // of the process definition. The process definition has + // 3 nodes: an unnamed start-state, a state 's' and an + // end-state named 'end'. ProcessDefinition processDefinition = ProcessDefinition.parseXmlString( "&lt;process-definition name='hello world'&gt;" + " &lt;start-state name='start'&gt;" + @@ -199,25 +199,25 @@ "&lt;/process-definition&gt;" ); - <emphasis role="bold">// Lookup the pojo persistence context-builder that is configured above</emphasis> + // Lookup the POJO persistence context-builder that is configured above JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); try { - <emphasis role="bold">// Deploy the process definition in the database </emphasis> + // Deploy the process definition in the database jbpmContext.deployProcessDefinition(processDefinition); } finally { - <emphasis role="bold">// Tear down the pojo persistence context.</emphasis> - <emphasis role="bold">// This includes flush the SQL for inserting the process definition </emphasis> - <emphasis role="bold">// to the database.</emphasis> + // Tear down the POJO persistence context. + // This includes flush the SQL for inserting the process definition + // to the database. jbpmContext.close(); } } public void processInstanceIsCreatedWhenUserSubmitsWebappForm() { - <emphasis role="bold">// The code in this method could be inside a struts-action </emphasis> - <emphasis role="bold">// or a JSF managed bean. </emphasis> + // The code in this method could be inside a struts-action + // or a JSF managed bean. - <emphasis role="bold">// Lookup the pojo persistence context-builder that is configured above</emphasis> + // Lookup the POJO persistence context-builder that is configured above JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); try { @@ -226,74 +226,74 @@ ProcessDefinition processDefinition = graphSession.findLatestProcessDefinition("hello world"); - <emphasis role="bold">// With the processDefinition that we retrieved from the database, we </emphasis> - <emphasis role="bold">// can create an execution of the process definition just like in the </emphasis> - <emphasis role="bold">// hello world example (which was without persistence).</emphasis> + // With the processDefinition that we retrieved from the database, we + // can create an execution of the process definition just like in the + // hello world example (which was without persistence). ProcessInstance processInstance = new ProcessInstance(processDefinition); Token token = processInstance.getRootToken(); assertEquals("start", token.getNode().getName()); - <emphasis role="bold">// Let's start the process execution</emphasis> + // Let's start the process execution token.signal(); - <emphasis role="bold">// Now the process is in the state 's'.</emphasis> + // Now the process is in the state 's'. assertEquals("s", token.getNode().getName()); - <emphasis role="bold">// Now the processInstance is saved in the database. So the - <emphasis role="bold">// current state of the execution of the process is stored in the </emphasis></emphasis> - <emphasis role="bold">// database. </emphasis> + // Now the processInstance is saved in the database. So the + // current state of the execution of the process is stored in the + // database. jbpmContext.save(processInstance); - <emphasis role="bold">// The method below will get the process instance back out </emphasis> - <emphasis role="bold">// of the database and resume execution by providing another </emphasis> - <emphasis role="bold">// external signal.</emphasis> + // The method below will get the process instance back out + // of the database and resume execution by providing another + // external signal. } finally { - <emphasis role="bold">// Tear down the pojo persistence context.</emphasis> + // Tear down the POJO persistence context. jbpmContext.close(); } } public void theProcessInstanceContinuesWhenAnAsyncMessageIsReceived() { - <emphasis role="bold">// The code in this method could be the content of a message driven bean.</emphasis> + // The code in this method could be the content of a message driven bean. - <emphasis role="bold">// Lookup the pojo persistence context-builder that is configured above</emphasis> + // Lookup the POJO persistence context-builder that is configured above JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); try { GraphSession graphSession = jbpmContext.getGraphSession(); - <emphasis role="bold">// First, we need to get the process instance back out of the database.</emphasis> - <emphasis role="bold">// There are several options to know what process instance we are dealing </emphasis> - <emphasis role="bold">// with here. The easiest in this simple test case is just to look for </emphasis> - <emphasis role="bold">// the full list of process instances. That should give us only one </emphasis> - <emphasis role="bold">// result. So let's look up the process definition.</emphasis> + // First, we need to get the process instance back out of the database. + // There are several options to know what process instance we are dealing + // with here. The easiest in this simple test case is just to look for + // the full list of process instances. That should give us only one + // result. So let's look up the process definition. ProcessDefinition processDefinition = graphSession.findLatestProcessDefinition("hello world"); - <emphasis role="bold">// Now, we search for all process instances of this process definition.</emphasis> + // Now, we search for all process instances of this process definition. List processInstances = graphSession.findProcessInstances(processDefinition.getId()); - <emphasis role="bold">// Because we know that in the context of this unit test, there is </emphasis> - <emphasis role="bold">// only one execution. In real life, the processInstanceId can be </emphasis> - <emphasis role="bold">// extracted from the content of the message that arrived or from </emphasis> - <emphasis role="bold">// the user making a choice.</emphasis> + // Because we know that in the context of this unit test, there is + // only one execution. In real life, the processInstanceId can be + // extracted from the content of the message that arrived or from + // the user making a choice. ProcessInstance processInstance = (ProcessInstance) processInstances.get(0); - <emphasis role="bold">// Now we can continue the execution. Note that the processInstance</emphasis> - <emphasis role="bold">// delegates signals to the main path of execution (=the root token).</emphasis> + // Now we can continue the execution. Note that the processInstance + // delegates signals to the main path of execution (=the root token). processInstance.signal(); - <emphasis role="bold">// After this signal, we know the process execution should have </emphasis> - <emphasis role="bold">// arrived in the end-state.</emphasis> + // After this signal, we know the process execution should have + // arrived in the end-state. assertTrue(processInstance.hasEnded()); - <emphasis role="bold">// Now we can update the state of the execution in the database</emphasis> + // Now we can update the state of the execution in the database jbpmContext.save(processInstance); } finally { - <emphasis role="bold">// Tear down the pojo persistence context.</emphasis> + // Tear down the POJO persistence context. jbpmContext.close(); } } @@ -311,8 +311,8 @@ <para>More information about variables can be found in <xref linkend="context" /></para> - <programlisting><emphasis role="bold">// This example also starts from the hello world process.</emphasis> -<emphasis role="bold">// This time even without modification.</emphasis> + <programlisting language="java">// This example also starts from the hello world process. +// This time even without modification. ProcessDefinition processDefinition = ProcessDefinition.parseXmlString( &quot;&lt;process-definition&gt;&quot; + &quot; &lt;start-state&gt;&quot; + @@ -328,26 +328,26 @@ ProcessInstance processInstance = new ProcessInstance(processDefinition); -<emphasis role="bold">// Fetch the context instance from the process instance </emphasis> -<emphasis role="bold">// for working with the process variables.</emphasis> +// Fetch the context instance from the process instance +// for working with the process variables. ContextInstance contextInstance = processInstance.getContextInstance(); -<emphasis role="bold">// Before the process has left the start-state, </emphasis> -<emphasis role="bold">// we are going to set some process variables in the </emphasis> -<emphasis role="bold">// context of the process instance.</emphasis> +// Before the process has left the start-state, +// we are going to set some process variables in the +// context of the process instance. contextInstance.setVariable("amount", new Integer(500)); contextInstance.setVariable("reason", "i met my deadline"); -<emphasis role="bold">// From now on, these variables are associated with the </emphasis> -<emphasis role="bold">// process instance. The process variables are now accessible </emphasis> -<emphasis role="bold">// by user code via the API shown here, but also in the actions </emphasis> -<emphasis role="bold">// and node implementations. The process variables are also </emphasis> -<emphasis role="bold">// stored into the database as a part of the process instance.</emphasis> +// From now on, these variables are associated with the +// process instance. The process variables are now accessible +// by user code via the API shown here, but also in the actions +// and node implementations. The process variables are also +// stored into the database as a part of the process instance. processInstance.signal(); -<emphasis role="bold">// The variables are accessible via the contextInstance. </emphasis> +// The variables are accessible via the contextInstance. assertEquals(new Integer(500), contextInstance.getVariable("amount")); @@ -358,7 +358,7 @@ <section id="taskassignmentexample"> <title>Task assignment example</title> <para>In the next example we'll show how you can assign a task to a user. Because - of the separation between the jBPM workflow engine and the organisational model, + of the separation between the jBPM workflow engine and the organizational model, an expression language for calculating actors would always be too limited. Therefore, you have to specify an implementation of AssignmentHandler for including the calculation of actors for tasks. @@ -366,64 +366,64 @@ - <programlisting>public void testTaskAssignment() { - <emphasis role="bold">// The process shown below is based on the hello world process.</emphasis> - <emphasis role="bold">// The state node is replaced by a task-node. The task-node </emphasis> - <emphasis role="bold">// is a node in JPDL that represents a wait state and generates </emphasis> - <emphasis role="bold">// task(s) to be completed before the process can continue to </emphasis> - <emphasis role="bold">// execute. </emphasis> + <programlisting language="java">public void testTaskAssignment() { + // The process shown below is based on the hello world process. + // The state node is replaced by a task-node. The task-node + // is a node in JPDL that represents a wait state and generates + // task(s) to be completed before the process can continue to + // execute. ProcessDefinition processDefinition = ProcessDefinition.parseXmlString( - &quot;<emphasis role="bold">&lt;process-definition name='the baby process'&gt;&quot;</emphasis> + - &quot;<emphasis role="bold"> &lt;start-state&gt;&quot;</emphasis> + - &quot;<emphasis role="bold"> &lt;transition name='baby cries' to='t' /&gt;&quot;</emphasis> + - &quot;<emphasis role="bold"> &lt;/start-state&gt;&quot;</emphasis> + - &quot;<emphasis role="bold"> &lt;task-node name='t'&gt;&quot;</emphasis> + - &quot;<emphasis role="bold"> &lt;task name='change nappy'&gt;&quot;</emphasis> + - &quot;<emphasis role="bold"> &lt;assignment class='org.jbpm.tutorial.taskmgmt.NappyAssignmentHandler' /&gt;&quot;</emphasis> + - &quot;<emphasis role="bold"> &lt;/task&gt;&quot;</emphasis> + - &quot;<emphasis role="bold"> &lt;transition to='end' /&gt;&quot;</emphasis> + - &quot;<emphasis role="bold"> &lt;/task-node&gt;&quot;</emphasis> + - &quot;<emphasis role="bold"> &lt;end-state name='end' /&gt;&quot;</emphasis> + - &quot;<emphasis role="bold">&lt;/process-definition&gt;&quot;</emphasis> + &quot;&lt;process-definition name='the baby process'&gt;&quot; + + &quot; &lt;start-state&gt;&quot; + + &quot; &lt;transition name='baby cries' to='t' /&gt;&quot; + + &quot; &lt;/start-state&gt;&quot; + + &quot; &lt;task-node name='t'&gt;&quot; + + &quot; &lt;task name='change nappy'&gt;&quot; + + &quot; &lt;assignment class='org.jbpm.tutorial.taskmgmt.NappyAssignmentHandler' /&gt;&quot; + + &quot; &lt;/task&gt;&quot; + + &quot; &lt;transition to='end' /&gt;&quot; + + &quot; &lt;/task-node&gt;&quot; + + &quot; &lt;end-state name='end' /&gt;&quot; + + &quot;&lt;/process-definition&gt;&quot; ); - <emphasis role="bold">// Create an execution of the process definition.</emphasis> + // Create an execution of the process definition. ProcessInstance processInstance = new ProcessInstance(processDefinition); Token token = processInstance.getRootToken(); - <emphasis role="bold">// Let's start the process execution, leaving the start-state </emphasis> - <emphasis role="bold">// over its default transition.</emphasis> + // Let's start the process execution, leaving the start-state + // over its default transition. token.signal(); - <emphasis role="bold">// The signal method will block until the process execution </emphasis> - <emphasis role="bold">// enters a wait state. In this case, that is the task-node.</emphasis> + // The signal method will block until the process execution + // enters a wait state. In this case, that is the task-node. assertSame(processDefinition.getNode("t"), token.getNode()); - <emphasis role="bold">// When execution arrived in the task-node, a task 'change nappy'</emphasis> - <emphasis role="bold">// was created and the NappyAssignmentHandler was called to determine</emphasis> - <emphasis role="bold">// to whom the task should be assigned. The NappyAssignmentHandler </emphasis> - <emphasis role="bold">// returned 'papa'.</emphasis> + // When execution arrived in the task-node, a task 'change nappy' + // was created and the NappyAssignmentHandler was called to determine + // to whom the task should be assigned. The NappyAssignmentHandler + // returned 'papa'. - <emphasis role="bold">// In a real environment, the tasks would be fetched from the</emphasis> - <emphasis role="bold">// database with the methods in the org.jbpm.db.TaskMgmtSession.</emphasis> - <emphasis role="bold">// Since we don't want to include the persistence complexity in </emphasis> - <emphasis role="bold">// this example, we just take the first task-instance of this </emphasis> - <emphasis role="bold">// process instance (we know there is only one in this test</emphasis> - <emphasis role="bold">// scenario).</emphasis> + // In a real environment, the tasks would be fetched from the + // database with the methods in the org.jbpm.db.TaskMgmtSession. + // Since we don't want to include the persistence complexity in + // this example, we just take the first task-instance of this + // process instance (we know there is only one in this test + // scenario). TaskInstance taskInstance = (TaskInstance) processInstance .getTaskMgmtInstance() .getTaskInstances() .iterator().next(); - <emphasis role="bold">// Now, we check if the taskInstance was actually assigned to 'papa'.</emphasis> + // Now, we check if the taskInstance was actually assigned to 'papa'. assertEquals("papa", taskInstance.getActorId() ); - <emphasis role="bold">// Now we suppose that 'papa' has done his duties and mark the task </emphasis> - <emphasis role="bold">// as done. </emphasis> + // Now we suppose that 'papa' has done his duties and mark the task + // as done. taskInstance.end(); - <emphasis role="bold">// Since this was the last (only) task to do, the completion of this</emphasis> - <emphasis role="bold">// task triggered the continuation of the process instance execution.</emphasis> + // Since this was the last (only) task to do, the completion of this + // task triggered the continuation of the process instance execution. assertSame(processDefinition.getNode("end"), token.getNode()); }</programlisting> @@ -448,17 +448,17 @@ <para>More information about actions can be found in <xref linkend="actions" /></para> - <programlisting><emphasis role="bold">// MyActionHandler represents a class that could execute </emphasis> -<emphasis role="bold">// some user code during the execution of a jBPM process.</emphasis> + <programlisting language="java">// MyActionHandler represents a class that could execute +// some user code during the execution of a jBPM process. public class MyActionHandler implements ActionHandler { - <emphasis role="bold">// Before each test (in the setUp), the isExecuted member </emphasis> - <emphasis role="bold">// will be set to false.</emphasis> + // Before each test (in the setUp), the isExecuted member + // will be set to false. public static boolean isExecuted = false; - <emphasis role="bold">// The action will set the isExecuted to true so the </emphasis> - <emphasis role="bold">// unit test will be able to show when the action</emphasis> - <emphasis role="bold">// is being executed.</emphasis> + // The action will set the isExecuted to true so the + // unit test will be able to show when the action + // is being executed. public void execute(ExecutionContext executionContext) { isExecuted = true; } @@ -467,56 +467,56 @@ <para>As mentioned before, before each test, we'll set the static field <literal>MyActionHandler.isExecuted</literal> to false;</para> - <programlisting> <emphasis role="bold">// Each test will start with setting the static isExecuted </emphasis> - <emphasis role="bold">// member of MyActionHandler to false.</emphasis> + <programlisting language="java"> // Each test will start with setting the static isExecuted + // member of MyActionHandler to false. public void setUp() { MyActionHandler.isExecuted = false; }</programlisting> <para>We'll start with an action on a transition.</para> - <programlisting>public void testTransitionAction() { - <emphasis role="bold">// The next process is a variant of the hello world process.</emphasis> - <emphasis role="bold">// We have added an action on the transition from state 's' </emphasis> - <emphasis role="bold">// to the end-state. The purpose of this test is to show </emphasis> - <emphasis role="bold">// how easy it is to integrate java code in a jBPM process.</emphasis> + <programlisting language="java">public void testTransitionAction() { + // The next process is a variant of the hello world process. + // We have added an action on the transition from state 's' + // to the end-state. The purpose of this test is to show + // how easy it is to integrate java code in a jBPM process. ProcessDefinition processDefinition = ProcessDefinition.parseXmlString( - &quot;<emphasis role="bold">&lt;process-definition&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;start-state&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;transition to='s' /&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;/start-state&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;state name='s'&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;transition to='end'&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;action class='org.jbpm.tutorial.action.MyActionHandler' /&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;/transition&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;/state&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;end-state name='end' /&gt;</emphasis>&quot; + - &quot;<emphasis role="bold">&lt;/process-definition&gt;</emphasis>&quot; + &quot;&lt;process-definition&gt;&quot; + + &quot; &lt;start-state&gt;&quot; + + &quot; &lt;transition to='s' /&gt;&quot; + + &quot; &lt;/start-state&gt;&quot; + + &quot; &lt;state name='s'&gt;&quot; + + &quot; &lt;transition to='end'&gt;&quot; + + &quot; &lt;action class='org.jbpm.tutorial.action.MyActionHandler' /&gt;&quot; + + &quot; &lt;/transition&gt;&quot; + + &quot; &lt;/state&gt;&quot; + + &quot; &lt;end-state name='end' /&gt;&quot; + + &quot;&lt;/process-definition&gt;&quot; ); - <emphasis role="bold">// Let's start a new execution for the process definition.</emphasis> + // Let's start a new execution for the process definition. ProcessInstance processInstance = new ProcessInstance(processDefinition); - <emphasis role="bold">// The next signal will cause the execution to leave the start </emphasis> - <emphasis role="bold">// state and enter the state 's'</emphasis> + // The next signal will cause the execution to leave the start + // state and enter the state 's' processInstance.signal(); - <emphasis role="bold">// Here we show that MyActionHandler was not yet executed. </emphasis> + // Here we show that MyActionHandler was not yet executed. assertFalse(MyActionHandler.isExecuted); - <emphasis role="bold">// ... and that the main path of execution is positioned in </emphasis> - <emphasis role="bold">// the state 's'</emphasis> + // ... and that the main path of execution is positioned in + // the state 's' assertSame(processDefinition.getNode("s"), processInstance.getRootToken().getNode()); - <emphasis role="bold">// The next signal will trigger the execution of the root </emphasis> - <emphasis role="bold">// token. The token will take the transition with the</emphasis> - <emphasis role="bold">// action and the action will be executed during the </emphasis> - <emphasis role="bold">// call to the signal method.</emphasis> + // The next signal will trigger the execution of the root + // token. The token will take the transition with the + // action and the action will be executed during the + // call to the signal method. processInstance.signal(); - <emphasis role="bold">// Here we can see that MyActionHandler was executed during </emphasis> - <emphasis role="bold">// the call to the signal method.</emphasis> + // Here we can see that MyActionHandler was executed during + // the call to the signal method. assertTrue(MyActionHandler.isExecuted); }</programlisting> @@ -527,18 +527,18 @@ node should be put in an event element. </para> - <programlisting>ProcessDefinition processDefinition = ProcessDefinition.parseXmlString( + <programlisting language="java">ProcessDefinition processDefinition = ProcessDefinition.parseXmlString( &quot;&lt;process-definition&gt;&quot; + &quot; &lt;start-state&gt;&quot; + &quot; &lt;transition to='s' /&gt;&quot; + &quot; &lt;/start-state&gt;&quot; + &quot; &lt;state name='s'&gt;&quot; + - &quot;<emphasis role="bold"> &lt;event type='node-enter'&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;action class='org.jbpm.tutorial.action.MyActionHandler' /&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;/event&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;event type='node-leave'&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;action class='org.jbpm.tutorial.action.MyActionHandler' /&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;/event&gt;</emphasis>&quot; + + &quot; &lt;event type='node-enter'&gt;&quot; + + &quot; &lt;action class='org.jbpm.tutorial.action.MyActionHandler' /&gt;&quot; + + &quot; &lt;/event&gt;&quot; + + &quot; &lt;event type='node-leave'&gt;&quot; + + &quot; &lt;action class='org.jbpm.tutorial.action.MyActionHandler' /&gt;&quot; + + &quot; &lt;/event&gt;&quot; + &quot; &lt;transition to='end'/&gt;&quot; + &quot; &lt;/state&gt;&quot; + &quot; &lt;end-state name='end' /&gt;&quot; + @@ -549,19 +549,19 @@ new ProcessInstance(processDefinition); assertFalse(MyActionHandler.isExecuted); -<emphasis role="bold">// The next signal will cause the execution to leave the start </emphasis> -<emphasis role="bold">// state and enter the state 's'. So the state 's' is entered </emphasis> -<emphasis role="bold">// and hence the action is executed. </emphasis> +// The next signal will cause the execution to leave the start +// state and enter the state 's'. So the state 's' is entered +// and hence the action is executed. processInstance.signal(); assertTrue(MyActionHandler.isExecuted); -<emphasis role="bold">// Let's reset the MyActionHandler.isExecuted </emphasis> +// Let's reset the MyActionHandler.isExecuted MyActionHandler.isExecuted = false; -<emphasis role="bold">// The next signal will trigger execution to leave the </emphasis> -<emphasis role="bold">// state 's'. So the action will be executed again. </emphasis> +// The next signal will trigger execution to leave the +// state 's'. So the action will be executed again. processInstance.signal(); -<emphasis role="bold">// Voila. </emphasis> +// Voila. assertTrue(MyActionHandler.isExecuted); </programlisting>