8:28 a.m.
Author: jbarrez
Date: 2009-07-01 09:28:51 -0400 (Wed, 01 Jul 2009)
New Revision: 5176
Modified:
jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch08-AdvancedJpdl.xml
jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch06-Jpdl.xml
Log:
JBPM-2328: moved timer documentation to devguide
Modified: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch08-AdvancedJpdl.xml
===================================================================
---
jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch08-AdvancedJpdl.xml 2009-07-01
13:24:21 UTC (rev 5175)
+++
jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch08-AdvancedJpdl.xml 2009-07-01
13:28:51 UTC (rev 5176)
@@ -7,7 +7,274 @@
to try and use. We don't give any stability guarantees on these
activities and features. So use at your own risk.
</para>
+
+ <!-- ### Timer ########################################################## -->
+ <section id="timer">
+ <title><literal>timer</literal> </title>
+ <para>A timer can be specified in the
<literal>transition</literal>
+ element in wait state activities such as <literal>state</literal>s,
+ <literal>task</literal>s, <literal>sub-process</literal>es
and
+ <literal>group</literal>s.
+ When such a timer fires, that transition is taken.
+ </para>
+ <para>A timer can also be specified in custom events in wait state
+ activities such as <literal>state</literal>s,
+ <literal>task</literal>s, <literal>sub-process</literal>es
and
+ <literal>group</literal>s. The <literal>timer</literal>
element
+ should then be the first element in the <literal>on</literal> element
representing
+ the event. In that case the event fires upon the duedate of the timer.
+ </para>
+ <para>Timers are created when the activity is entered. The timer can fire
+ when the execution remains in the activity until the
<literal>duedate</literal>.
+ When the execution leaves the activity, the timer is cancelled.
+ </para>
+ <table><title><literal>timer</literal>
attributes:</title>
+ <tgroup cols="5" rowsep="1" colsep="1">
+ <thead>
+ <row>
+ <entry>Attribute</entry>
+ <entry>Type</entry>
+ <entry>Default</entry>
+ <entry>Required?</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>duedate</literal></entry>
+ <entry><link linkend="duedateexpressions">duedate
expression</link></entry>
+ <entry></entry>
+ <entry><emphasis
role="bold">required</emphasis></entry>
+ <entry>Specifies when the timer needs to fire. For
+ example: <literal>20 minutes</literal> or
+ <literal>3 business days</literal>
+ </entry>
+ </row>
+ <row>
+ <entry><literal>repeat</literal></entry>
+ <entry><link linkend="duedateexpressions">duedate
expression</link></entry>
+ <entry></entry>
+ <entry>optional</entry>
+ <entry>When a timer fires, this attribute specifies when the timer
+ needs to fire again. For example: <literal>20 minutes</literal>
or
+ <literal>3 business days</literal>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <section id="duedateexpressions">
+ <title>Duedate expressions</title>
+ <para>A duedate expression has the following syntax:</para>
+ <programlisting>quantity [business] {second | seconds | minute | minutes |
+ hour | hours | day | days | week |
+ weeks | month | months | year | years}</programlisting>
+ <para>where <literal>quantity</literal> is a positive integer.
+ </para>
+ <para>And adding the optional indication
<literal>business</literal> means
+ that only business hours should be taken into account for this duration. Without
+ the indication business, the duration will be interpreted as an absolute time
period.
+ How to configure business hours is explained in <xref
linkend="businesscalendar"/>
+ </para>
+ </section>
+
+ <section id="businesscalendar">
+ <title>Business calendar</title>
+ <para>The default configuration will contain a reference to the file
+ <literal>jbpm.business.calendar.xml</literal>. That contains a
+ configuration of business hours in the following format:
+ </para>
+ <programlisting><?xml version="1.0"
encoding="UTF-8"?>
+
+<jbpm-configuration xmlns="http://jbpm.org/xsd/cfg">
+
+ <process-engine-context>
+
+ <business-calendar>
+ <monday hours="9:00-12:00 and 12:30-17:00"/>
+ <tuesday hours="9:00-12:00 and 12:30-17:00"/>
+ <wednesday hours="9:00-12:00 and 12:30-17:00"/>
+ <thursday hours="9:00-12:00 and 12:30-17:00"/>
+ <friday hours="9:00-12:00 and 12:30-17:00"/>
+ <holiday period="01/07/2008 - 31/08/2008"/>
+ </business-calendar>
+
+ </process-engine-context>
+
+</jbpm-configuration></programlisting>
+ <para>For an example of where the business calendar is used, see
+ <xref linkedn="timerbusinesstime" />
+ </para>
+ </section>
+
+ <section id="timertransition">
+ <title>Timer transition</title>
+ <para>Example TimerTransitionTest shows how to put a timer on a
transition.</para>
+ <figure id="process.timer.transition">
+ <title>The timer transition example process</title>
+ <mediaobject><imageobject><imagedata align="center"
fileref="images/process.timer.transition.png"/></imageobject></mediaobject>
+ </figure>
+ <programlisting><process name="TimerTransition"
xmlns="http://jbpm.org/4.0/jpdl">
+
+ <start>
+ <transition to="guardedWait" />
+ </start>
+
+ <state name="guardedWait">
+ <transition name="go on" to="next step"
/>
+ <transition name="timeout"
to="escalation">
+ <emphasis role="bold"><timer duedate="10
minutes" /></emphasis>
+ </transition>
+ </state>
+
+ <state name="next step" />
+ <state name="escalation" />
+
+</process></programlisting>
+ <para>When an process instance for this process is started, it arrives
immediately
+ in the <literal>guardedWait</literal> state. At that time, a timer is
created that will fire
+ after 10 minutes.
+ </para>
+ <programlisting>Execution processInstance = executionService
+
.startProcessInstanceByKey("TimerTransition");</programlisting>
+ <para>With the following query, we can query for the timers related to the
newly created
+ processInstance. We know that there should be exactly one such timer.
+ </para>
+ <programlisting>Job job = managementService.createJobQuery()
+ .timers()
+ .processInstanceId(processInstance.getId())
+ .uniqueResult();
+ </programlisting>
+ <para>In a unit test, we won't use the JobExecutor to execute the timer.
Instead,
+ we execute timers directly in the thread of the unit test. That way it is easy to
+ simulate one scenario though an execution.
+ </para>
+ <para>So as the next step, we assume that the timer will fire. We simulate
this
+ by executing the timer programmatically:
+ </para>
+
<programlisting>managementService.executeJob(job.getDbid());</programlisting>
+ <para>After that the process instance will have taken the
+ <literal>timeout</literal> transition and moved to the escalation
state.
+ </para>
+ <programlisting>processInstance =
executionService.findExecutionById(processInstance.getId());
+assertEquals("escalation",
processInstance.getActivityName());</programlisting>
+ <para>The second scenario in TimerTransitionTest shows that the
+ timer is cancelled in case the signal <literal>go on</literal> is given
+ before the timer fires. In that case the execution ends up in the
+ <literal>next step</literal>.
+ </para>
+ </section>
+
+ <section id="timerevent">
+ <title>Timer event</title>
+ <para>Example TimerEventTest shows how to put a timer on a custom
event.</para>
+ <figure id="process.timer.event">
+ <title>The timer event example process</title>
+ <mediaobject><imageobject><imagedata align="center"
fileref="images/process.timer.event.png"/></imageobject></mediaobject>
+ </figure>
+ <programlisting><process name="TimerEvent"
xmlns="http://jbpm.org/4.0/jpdl">
+
+ <start>
+ <transition to="guardedWait" />
+ </start>
+
+ <state name="guardedWait" >
+ <emphasis role="bold"><on
event="timeout">
+ <timer duedate="10 minutes"/>
+ <event-listener
class="org.jbpm.examples.timer.event.Escalate" />
+ </on></emphasis>
+ <transition name="go on" to="next step"
/>
+ </state>
+
+ <state name="next step" />
+
+</process></programlisting>
+ <para>In this case, if the execution is not signalled within 10 minutes after
the
+ activity is started, the event <literal>timeout</literal> is fired
+ and the event listener
<literal>org.jbpm.examples.timer.event.Escalate</literal>
+ will be notified.
+ </para>
+ <para>Again, if the <literal>guardedWait</literal> activity is
ended within
+ 10 minutes, then the timer is cancelled and the
<literal>Escalate</literal>
+ event listener will not be notified.
+ </para>
+ </section>
+
+ <section id="timerbusinesstime">
+ <title>Timer business time</title>
+ <para>Example TimerBusinessTimeTest shows how business time
works.</para>
+ <figure id="process.timer.event">
+ <title>The timer businesstime example process</title>
+ <mediaobject><imageobject><imagedata align="center"
fileref="images/process.timer.transition.png"/></imageobject></mediaobject>
+ </figure>
+ <programlisting><process name="TimerBusinessTime"
xmlns="http://jbpm.org/4.0/jpdl">
+
+ <start>
+ <transition to="guardedWait" />
+ </start>
+
+ <state name="guardedWait" >
+ <transition name="go on" to="next step"
/>
+ <transition name="timeout" to="escalation"
>
+ <timer <emphasis role="bold">duedate="9 business
hours"</emphasis> />
+ </transition>
+ </state>
+
+ <state name="next step" />
+ <state name="escalation" />
+
+</process></programlisting>
+ <para>Suppose that a new <literal>TimerBusinessTime</literal>
process instance is started
+ at 11:30am on a tuesday. The default configured business calendar specifies
working hours
+ between 9:00-12:00 and 12:30-17:00. So 9 business hours later results in an actual
duedate
+ for the timer of wednesday 13:00 (1pm).
+ </para>
+ <para>Since we do not know when the TimerBusinessTimeTest will be ran, we
only assert
+ in the test that the actual duedate of the scheduled timer at least 24 hours
ahead.
+ </para>
+ </section>
+
+ <section id="timerrepeat">
+ <title>Timer repeat</title>
+ <para>Example TimerRepeatTest shows how to put a timer with a repeat. The
attribute
+ <literal>repeat</literal> on a timer will cause the timer to be
rescheduled automatically
+ after it is executed.
+ </para>
+ <figure id="process.timer.repeat">
+ <title>The timer repeat example process</title>
+ <mediaobject><imageobject><imagedata align="center"
fileref="images/process.timer.event.png"/></imageobject></mediaobject>
+ </figure>
+ <programlisting><process name="TimerRepeat"
xmlns="http://jbpm.org/4.0/jpdl">
+
+ <start>
+ <transition to="guardedWait" />
+ </start>
+
+ <state name="guardedWait">
+ <on event="timeout">
+ <timer duedate="20 minutes" <emphasis
role="bold">repeat="10 seconds"</emphasis> />
+ <event-listener
class="org.jbpm.examples.timer.repeat.Escalate" />
+ </on>
+ <transition name="go on" to="next
step"/>
+ </state>
+
+ <state name="next step"/>
+
+</process></programlisting>
+ <para>When a new process is started, a timer is created and the duedate
+ will be 20 minutes ahead. When the timer fires, a new timer will be created
+ with a duedate of 10 seconds ahead. When that timer fires, a new timer will
+ be created again 10 seconds ahead. And so on.
+ </para>
+ <para>New timers will be created each time the timer fires until the
+ <literal>guardedWait</literal> state activity is ended with a signal.
+ When the <literal>guardedWait</literal> state activity is ended, the
+ existing timer will be cancelled.
+ </para>
+ </section>
+ </section>
+
<!-- ### GROUP ########################################################## -->
<section id="group">
<title><literal>group</literal></title>
Modified: jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch06-Jpdl.xml
===================================================================
--- jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch06-Jpdl.xml 2009-07-01
13:24:21 UTC (rev 5175)
+++ jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch06-Jpdl.xml 2009-07-01
13:28:51 UTC (rev 5176)
@@ -2759,272 +2759,6 @@
</section>
</section>
- <section id="timer">
- <title><literal>timer</literal> </title>
- <para>A timer can be specified in the
<literal>transition</literal>
- element in wait state activities such as <literal>state</literal>s,
- <literal>task</literal>s, <literal>sub-process</literal>es
and
- <literal>group</literal>s.
- When such a timer fires, that transition is taken.
- </para>
- <para>A timer can also be specified in custom events in wait state
- activities such as <literal>state</literal>s,
- <literal>task</literal>s, <literal>sub-process</literal>es
and
- <literal>group</literal>s. The <literal>timer</literal>
element
- should then be the first element in the <literal>on</literal> element
representing
- the event. In that case the event fires upon the duedate of the timer.
- </para>
- <para>Timers are created when the activity is entered. The timer can fire
- when the execution remains in the activity until the
<literal>duedate</literal>.
- When the execution leaves the activity, the timer is cancelled.
- </para>
- <table><title><literal>timer</literal>
attributes:</title>
- <tgroup cols="5" rowsep="1" colsep="1">
- <thead>
- <row>
- <entry>Attribute</entry>
- <entry>Type</entry>
- <entry>Default</entry>
- <entry>Required?</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>duedate</literal></entry>
- <entry><link linkend="duedateexpressions">duedate
expression</link></entry>
- <entry></entry>
- <entry><emphasis
role="bold">required</emphasis></entry>
- <entry>Specifies when the timer needs to fire. For
- example: <literal>20 minutes</literal> or
- <literal>3 business days</literal>
- </entry>
- </row>
- <row>
- <entry><literal>repeat</literal></entry>
- <entry><link linkend="duedateexpressions">duedate
expression</link></entry>
- <entry></entry>
- <entry>optional</entry>
- <entry>When a timer fires, this attribute specifies when the timer
- needs to fire again. For example: <literal>20 minutes</literal>
or
- <literal>3 business days</literal>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <section id="duedateexpressions">
- <title>Duedate expressions</title>
- <para>A duedate expression has the following syntax:</para>
- <programlisting>quantity [business] {second | seconds | minute | minutes |
- hour | hours | day | days | week |
- weeks | month | months | year | years}</programlisting>
- <para>where <literal>quantity</literal> is a positive integer.
- </para>
- <para>And adding the optional indication
<literal>business</literal> means
- that only business hours should be taken into account for this duration. Without
- the indication business, the duration will be interpreted as an absolute time
period.
- How to configure business hours is explained in <xref
linkend="businesscalendar"/>
- </para>
- </section>
-
- <section id="businesscalendar">
- <title>Business calendar</title>
- <para>The default configuration will contain a reference to the file
- <literal>jbpm.business.calendar.xml</literal>. That contains a
- configuration of business hours in the following format:
- </para>
- <programlisting><?xml version="1.0"
encoding="UTF-8"?>
-
-<jbpm-configuration xmlns="http://jbpm.org/xsd/cfg">
-
- <process-engine-context>
-
- <business-calendar>
- <monday hours="9:00-12:00 and 12:30-17:00"/>
- <tuesday hours="9:00-12:00 and 12:30-17:00"/>
- <wednesday hours="9:00-12:00 and 12:30-17:00"/>
- <thursday hours="9:00-12:00 and 12:30-17:00"/>
- <friday hours="9:00-12:00 and 12:30-17:00"/>
- <holiday period="01/07/2008 - 31/08/2008"/>
- </business-calendar>
-
- </process-engine-context>
-
-</jbpm-configuration></programlisting>
- <para>For an example of where the business calendar is used, see
- <xref linkedn="timerbusinesstime" />
- </para>
- </section>
-
- <section id="timertransition">
- <title>Timer transition</title>
- <para>Example TimerTransitionTest shows how to put a timer on a
transition.</para>
- <figure id="process.timer.transition">
- <title>The timer transition example process</title>
- <mediaobject><imageobject><imagedata align="center"
fileref="images/process.timer.transition.png"/></imageobject></mediaobject>
- </figure>
- <programlisting><process name="TimerTransition"
xmlns="http://jbpm.org/4.0/jpdl">
-
- <start>
- <transition to="guardedWait" />
- </start>
-
- <state name="guardedWait">
- <transition name="go on" to="next step"
/>
- <transition name="timeout"
to="escalation">
- <emphasis role="bold"><timer duedate="10
minutes" /></emphasis>
- </transition>
- </state>
-
- <state name="next step" />
- <state name="escalation" />
-
-</process></programlisting>
- <para>When an process instance for this process is started, it arrives
immediately
- in the <literal>guardedWait</literal> state. At that time, a timer is
created that will fire
- after 10 minutes.
- </para>
- <programlisting>Execution processInstance = executionService
-
.startProcessInstanceByKey("TimerTransition");</programlisting>
- <para>With the following query, we can query for the timers related to the
newly created
- processInstance. We know that there should be exactly one such timer.
- </para>
- <programlisting>Job job = managementService.createJobQuery()
- .timers()
- .processInstanceId(processInstance.getId())
- .uniqueResult();
- </programlisting>
- <para>In a unit test, we won't use the JobExecutor to execute the timer.
Instead,
- we execute timers directly in the thread of the unit test. That way it is easy to
- simulate one scenario though an execution.
- </para>
- <para>So as the next step, we assume that the timer will fire. We simulate
this
- by executing the timer programmatically:
- </para>
-
<programlisting>managementService.executeJob(job.getDbid());</programlisting>
- <para>After that the process instance will have taken the
- <literal>timeout</literal> transition and moved to the escalation
state.
- </para>
- <programlisting>processInstance =
executionService.findExecutionById(processInstance.getId());
-assertEquals("escalation",
processInstance.getActivityName());</programlisting>
- <para>The second scenario in TimerTransitionTest shows that the
- timer is cancelled in case the signal <literal>go on</literal> is given
- before the timer fires. In that case the execution ends up in the
- <literal>next step</literal>.
- </para>
- </section>
-
- <section id="timerevent">
- <title>Timer event</title>
- <para>Example TimerEventTest shows how to put a timer on a custom
event.</para>
- <figure id="process.timer.event">
- <title>The timer event example process</title>
- <mediaobject><imageobject><imagedata align="center"
fileref="images/process.timer.event.png"/></imageobject></mediaobject>
- </figure>
- <programlisting><process name="TimerEvent"
xmlns="http://jbpm.org/4.0/jpdl">
-
- <start>
- <transition to="guardedWait" />
- </start>
-
- <state name="guardedWait" >
- <emphasis role="bold"><on
event="timeout">
- <timer duedate="10 minutes"/>
- <event-listener
class="org.jbpm.examples.timer.event.Escalate" />
- </on></emphasis>
- <transition name="go on" to="next step"
/>
- </state>
-
- <state name="next step" />
-
-</process></programlisting>
- <para>In this case, if the execution is not signalled within 10 minutes after
the
- activity is started, the event <literal>timeout</literal> is fired
- and the event listener
<literal>org.jbpm.examples.timer.event.Escalate</literal>
- will be notified.
- </para>
- <para>Again, if the <literal>guardedWait</literal> activity is
ended within
- 10 minutes, then the timer is cancelled and the
<literal>Escalate</literal>
- event listener will not be notified.
- </para>
- </section>
-
- <section id="timerbusinesstime">
- <title>Timer business time</title>
- <para>Example TimerBusinessTimeTest shows how business time
works.</para>
- <figure id="process.timer.event">
- <title>The timer businesstime example process</title>
- <mediaobject><imageobject><imagedata align="center"
fileref="images/process.timer.transition.png"/></imageobject></mediaobject>
- </figure>
- <programlisting><process name="TimerBusinessTime"
xmlns="http://jbpm.org/4.0/jpdl">
-
- <start>
- <transition to="guardedWait" />
- </start>
-
- <state name="guardedWait" >
- <transition name="go on" to="next step"
/>
- <transition name="timeout" to="escalation"
>
- <timer <emphasis role="bold">duedate="9 business
hours"</emphasis> />
- </transition>
- </state>
-
- <state name="next step" />
- <state name="escalation" />
-
-</process></programlisting>
- <para>Suppose that a new <literal>TimerBusinessTime</literal>
process instance is started
- at 11:30am on a tuesday. The default configured business calendar specifies
working hours
- between 9:00-12:00 and 12:30-17:00. So 9 business hours later results in an actual
duedate
- for the timer of wednesday 13:00 (1pm).
- </para>
- <para>Since we do not know when the TimerBusinessTimeTest will be ran, we
only assert
- in the test that the actual duedate of the scheduled timer at least 24 hours
ahead.
- </para>
- </section>
-
- <section id="timerrepeat">
- <title>Timer repeat</title>
- <para>Example TimerRepeatTest shows how to put a timer with a repeat. The
attribute
- <literal>repeat</literal> on a timer will cause the timer to be
rescheduled automatically
- after it is executed.
- </para>
- <figure id="process.timer.repeat">
- <title>The timer repeat example process</title>
- <mediaobject><imageobject><imagedata align="center"
fileref="images/process.timer.event.png"/></imageobject></mediaobject>
- </figure>
- <programlisting><process name="TimerRepeat"
xmlns="http://jbpm.org/4.0/jpdl">
-
- <start>
- <transition to="guardedWait" />
- </start>
-
- <state name="guardedWait">
- <on event="timeout">
- <timer duedate="20 minutes" <emphasis
role="bold">repeat="10 seconds"</emphasis> />
- <event-listener
class="org.jbpm.examples.timer.repeat.Escalate" />
- </on>
- <transition name="go on" to="next
step"/>
- </state>
-
- <state name="next step"/>
-
-</process></programlisting>
- <para>When a new process is started, a timer is created and the duedate
- will be 20 minutes ahead. When the timer fires, a new timer will be created
- with a duedate of 10 seconds ahead. When that timer fires, a new timer will
- be created again 10 seconds ahead. And so on.
- </para>
- <para>New timers will be created each time the timer fires until the
- <literal>guardedWait</literal> state activity is ended with a signal.
- When the <literal>guardedWait</literal> state activity is ended, the
- existing timer will be cancelled.
- </para>
- </section>
- </section>
-
<section id="usercode">
<title>User code</title>
<para>Various elements in the jPDL process language refer to a an