Author: tom.baeyens(a)jboss.com Date: 2008-09-18 15:11:04 -0400 (Thu, 18 Sep 2008) New Revision: 2282 Added: jbpm4/pvm/trunk/modules/core/src/test/java/org/jbpm/pvm/example07/ jbpm4/pvm/trunk/modules/core/src/test/java/org/jbpm/pvm/example07/EventListenerTest.java jbpm4/pvm/trunk/modules/core/src/test/java/org/jbpm/pvm/example07/PrintLn.java jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/images/process.anatomy.classes.png Modified: jbpm4/pvm/trunk/assembly.xml jbpm4/pvm/trunk/modules/core/src/main/java/org/jbpm/pvm/internal/model/TransitionImpl.java jbpm4/pvm/trunk/modules/core/src/main/java/org/jbpm/pvm/model/Event.java jbpm4/pvm/trunk/modules/core/src/test/java/org/jbpm/pvm/example04/TestConsole.java jbpm4/pvm/trunk/modules/manual/src/main/diagrams/diagrams.mdzip jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch04-ImplementingBasicActivities.xml jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch05-ProcessAnatomy.xml Log: docs Modified: jbpm4/pvm/trunk/assembly.xml =================================================================== --- jbpm4/pvm/trunk/assembly.xml 2008-09-18 19:11:01 UTC (rev 2281) +++ jbpm4/pvm/trunk/assembly.xml 2008-09-18 19:11:04 UTC (rev 2282) @@ -6,6 +6,7 @@ <format>tar.gz</format> </formats> <includeBaseDirectory>true</includeBaseDirectory> + <baseDirectory>jbpm-pvm-${version}</baseDirectory> <moduleSets> <moduleSet> <includes> @@ -54,7 +55,7 @@ <fileSet> <directory>modules/core/src/test/java</directory> <includes> - <include>org/jbpm/pvm/samples/**/*.*</include> + <include>org/jbpm/pvm/example*/**/*.*</include> </includes> <outputDirectory>examples</outputDirectory> </fileSet> Modified: jbpm4/pvm/trunk/modules/core/src/main/java/org/jbpm/pvm/internal/model/TransitionImpl.java =================================================================== --- jbpm4/pvm/trunk/modules/core/src/main/java/org/jbpm/pvm/internal/model/TransitionImpl.java 2008-09-18 19:11:01 UTC (rev 2281) +++ jbpm4/pvm/trunk/modules/core/src/main/java/org/jbpm/pvm/internal/model/TransitionImpl.java 2008-09-18 19:11:04 UTC (rev 2282) @@ -66,6 +66,10 @@ addEvent(event); return event; } + + public EventImpl getEvent() { + return getEvent(Event.TRANSITION_TAKE); + } // get parent /////////////////////////////////////////////////////////////// @@ -134,9 +138,6 @@ return (Condition) WireContext.create(waitConditionDescriptor); } - public EventImpl getEvent() { - return getEvent(Event.TRANSITION_TAKE); - } public NodeImpl getSource() { return source; } Modified: jbpm4/pvm/trunk/modules/core/src/main/java/org/jbpm/pvm/model/Event.java =================================================================== --- jbpm4/pvm/trunk/modules/core/src/main/java/org/jbpm/pvm/model/Event.java 2008-09-18 19:11:01 UTC (rev 2281) +++ jbpm4/pvm/trunk/modules/core/src/main/java/org/jbpm/pvm/model/Event.java 2008-09-18 19:11:04 UTC (rev 2282) @@ -24,14 +24,26 @@ /** event constants. * + * <b>WARNING: these event names will be subject to change in the next release. + * See <a href="https://jira.jboss.org/jira/browse/JBPM-1753">JBPM-175... + * * @author Tom Baeyens */ public interface Event { + /** <b>WARNING: this event name will be subject to change in the next release. See <a href="https://jira.jboss.org/jira/browse/JBPM-1753">JBPM-175... + * @deprecated */ String TRANSITION_TAKE = "transition-take"; + /** <b>WARNING: this event name will be subject to change in the next release. See <a href="https://jira.jboss.org/jira/browse/JBPM-1753">JBPM-175... + * @deprecated */ String PROCESS_BEGIN = "process-begin"; + /** <b>WARNING: this event name will be subject to change in the next release. See <a href="https://jira.jboss.org/jira/browse/JBPM-1753">JBPM-175... + * @deprecated */ String PROCESS_END = "process-end"; + /** <b>WARNING: this event name will be subject to change in the next release. See <a href="https://jira.jboss.org/jira/browse/JBPM-1753">JBPM-175... + * @deprecated */ String NODE_BEGIN = "node-begin"; + /** <b>WARNING: this event name will be subject to change in the next release. See <a href="https://jira.jboss.org/jira/browse/JBPM-1753">JBPM-175... + * @deprecated */ String NODE_END = "node-end"; - } Modified: jbpm4/pvm/trunk/modules/core/src/test/java/org/jbpm/pvm/example04/TestConsole.java =================================================================== --- jbpm4/pvm/trunk/modules/core/src/test/java/org/jbpm/pvm/example04/TestConsole.java 2008-09-18 19:11:01 UTC (rev 2281) +++ jbpm4/pvm/trunk/modules/core/src/test/java/org/jbpm/pvm/example04/TestConsole.java 2008-09-18 19:11:04 UTC (rev 2282) @@ -8,7 +8,7 @@ * so that those can be asserted */ public class TestConsole extends PrintStream { - List<String> lines = new ArrayList<String>(); + public List<String> lines = new ArrayList<String>(); public TestConsole() { super(System.out); Added: jbpm4/pvm/trunk/modules/core/src/test/java/org/jbpm/pvm/example07/EventListenerTest.java =================================================================== --- jbpm4/pvm/trunk/modules/core/src/test/java/org/jbpm/pvm/example07/EventListenerTest.java (rev 0) +++ jbpm4/pvm/trunk/modules/core/src/test/java/org/jbpm/pvm/example07/EventListenerTest.java 2008-09-18 19:11:04 UTC (rev 2282) @@ -0,0 +1,49 @@ +package org.jbpm.pvm.example07; + +import javax.enterprise.deploy.spi.exceptions.ClientExecuteException; + +import org.jbpm.pvm.client.ClientExecution; +import org.jbpm.pvm.client.ClientProcessDefinition; +import org.jbpm.pvm.example01.AutomaticActivity; +import org.jbpm.pvm.example01.WaitState; +import org.jbpm.pvm.example04.Display; +import org.jbpm.pvm.example04.TestConsole; +import org.jbpm.pvm.model.Event; +import org.jbpm.pvm.model.ProcessFactory; +import org.jbpm.pvm.test.base.JbpmTestCase; + + +public class EventListenerTest extends JbpmTestCase { + + TestConsole testConsole; + + public void setUp() { + testConsole = TestConsole.install(); + } + + public void tearDown() { + TestConsole.uninstall(); + testConsole = null; + } + + public void testEventListener() { + ClientProcessDefinition processDefinition = ProcessFactory.build() + .node("a").initial().behaviour(new AutomaticActivity()) + .event(Event.NODE_END) + .listener(new PrintLn("leaving a")) + .listener(new PrintLn("second message while leaving a")) + .transition().to("b") + .listener(new PrintLn("taking transition")) + .node("b").behaviour(new WaitState()) + .event(Event.NODE_BEGIN) + .listener(new PrintLn("entering b")) + .done(); + + ClientExecution execution = processDefinition.startProcessInstance(); + + assertEquals("leaving a", testConsole.getLine(0)); + assertEquals("second message while leaving a", testConsole.getLine(1)); + assertEquals("taking transition", testConsole.getLine(2)); + assertEquals("entering b", testConsole.getLine(3)); + } +} Added: jbpm4/pvm/trunk/modules/core/src/test/java/org/jbpm/pvm/example07/PrintLn.java =================================================================== --- jbpm4/pvm/trunk/modules/core/src/test/java/org/jbpm/pvm/example07/PrintLn.java (rev 0) +++ jbpm4/pvm/trunk/modules/core/src/test/java/org/jbpm/pvm/example07/PrintLn.java 2008-09-18 19:11:04 UTC (rev 2282) @@ -0,0 +1,20 @@ +package org.jbpm.pvm.example07; + +import org.jbpm.pvm.listener.EventListener; +import org.jbpm.pvm.listener.EventListenerExecution; + + +public class PrintLn implements EventListener { + + private static final long serialVersionUID = 1L; + + String message; + + public PrintLn(String message) { + this.message = message; + } + + public void notify(EventListenerExecution execution) throws Exception { + System.out.println(message); + } +} Modified: jbpm4/pvm/trunk/modules/manual/src/main/diagrams/diagrams.mdzip =================================================================== (Binary files differ) Added: jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/images/process.anatomy.classes.png =================================================================== (Binary files differ) Property changes on: jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/images/process.anatomy.classes.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Modified: jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch04-ImplementingBasicActivities.xml =================================================================== --- jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch04-ImplementingBasicActivities.xml 2008-09-18 19:11:01 UTC (rev 2281) +++ jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch04-ImplementingBasicActivities.xml 2008-09-18 19:11:04 UTC (rev 2282) @@ -288,29 +288,21 @@ </figure> </section> - <!-- ### MOTIVATION ##################################################### --> - <section id="motivation"> - <title>Motivation</title> - <para>There are basically two forms of process languages: graph based and composite - process languages. First of all, this design supports both. Even graph based execution - and node composition can be used in combination to implement something like UML super states. - </para> - <para>In this design, control flow activity implementations will have to be - aware of whether they are dependent on transitions (graph based) or whether they are - using the composite node structure. The goal of this design is that all non-control - flow activities can be implemented in the same way so that you can use them in graph - based process languages as well as in composite process languages. - </para> - </section> - <!-- ### EVENTS ######################################################### --> <section id="events"> <title>Events</title> <para>Events are points in the process definition to which a list of - activities can be subscribed as listeners. The motivation for events is to allow for + <literal>EventListener</literal>s can be subscribed. + </para> + <programlisting>public interface EventListener extends Serializable { + + void notify(EventListenerExecution execution) throws Exception; + +}</programlisting> + <para>The motivation for events is to allow for developers to add programming logic to a process without changing the process diagram. - This is a very valuable instrument in - facilitating the collaboration between business analysts and developers. Business analysts + This is a very valuable instrument in facilitating the collaboration between business analysts + and developers. Business analysts are responsible for expressing the requirements. When they use a process graph to document those requirements, developers can take this diagram and make it executable. Events can be a very handy to insert technical details into a process (like e.g. some database insert) @@ -318,24 +310,28 @@ </para> <para>Most common events are fired by the execution automatically: </para> + <para><emphasis role="bold">WARNING: the following event names will be + subject to change in the next release: see + <ulink url="https://jira.jboss.org/jira/browse/JBPM-1753">JBPM-1753... + </para> <itemizedlist> - <listitem><literal>Transition.EVENT_TRANSITION_TAKE = "transition-take"</literal> : + <listitem><literal><emphasis role="bold">Event.TRANSITION_TAKE</emphasis> = "transition-take"</literal> : fired on transitions when transitions are taken. </listitem> - <listitem><literal>Node.EVENT_NODE_ENTER = "node-enter"</literal> : fired on the node + <listitem><literal><emphasis role="bold">Event.NODE_BEGIN</emphasis> = "node-begin"</literal> : fired on the node when execution enters that node. This happens when execution takes a transition to that node, when a child node is being executed with <literal>execution.execute(Node)</literal> or when a transition is taken from a node outside that node to a contained node. The latter refers to super states in state machines. </listitem> - <listitem><literal>Node.EVENT_NODE_LEAVE = "node-leave"</literal> : fired on the node + <listitem><literal><emphasis role="bold">Event.NODE_END</emphasis> = "node-end"</literal> : fired on the node when a transition is taken out of that node or when a child node execution is finished and the execution is propagated to the parent node. </listitem> - <listitem><literal>ProcessDefinition.EVENT_PROCESS_START = "process-start"</literal> : fired on a process + <listitem><literal><emphasis role="bold">Event.PROCESS_BEGIN</emphasis> = "process-begin"</literal> : fired on a process when a new process is started. </listitem> - <listitem><literal>ProcessDefinition.EVENT_PROCESS_END = "process-end"</literal> : fired on a process + <listitem><literal><emphasis role="bold">Event.PROCESS_END</emphasis> = "process-end"</literal> : fired on a process when a new process is ended. This might include a executions that are ended with a cancelled or error state. </listitem> @@ -350,38 +346,43 @@ ... }</programlisting> - <para>A list of <link linkend="activity"><literal>Activity</literal>s</link> can be associated to an - event. But activities on events can not influence the control flow of the execution since - they are merely listeners to an execution wich is already in progress. This is different from + <para>A list of <literal>EventListeners</literal> can be associated to an + event. But event listeners can not influence the control flow of the execution since + they are merely listeners to an execution which is already in progress. This is different from activities that serve as the behaviour for nodes. Node behaviour activities are responsible - for propagating the execution. So if an activity in an event invokes any of the - following methods, then it will result in an exception. + for propagating the execution. </para> - - <itemizedlist> - <listitem><literal>waitForSignal()</literal></listitem> - <listitem><literal>take(Transition)</literal></listitem> - <listitem><literal>end(*)</literal></listitem> - <listitem><literal>execute(Node)</literal></listitem> - </itemizedlist> - - <para>We'll reuse the <literal><link linkend="activity">Display</link></literal> - activity from above in a simple process: two nodes connected by a - transition. The Display listener will be subscribed to the transition event.</para> + <para>We'll create a <literal>PrintLn</literal> event listener which is + very similar to the <literal>Display</literal> activity from above. + </para> + <programlisting>public class PrintLn implements EventListener { + + String message; + + public PrintLn(String message) { + this.message = message; + } + + public void notify(EventListenerExecution execution) throws Exception { + System.out.println("message"); + } +}</programlisting> + <para>Several <literal>PrintLn</literal> listeners will be subscribed to events in + the process.</para> <figure id="action.process"> - <title>The process to which a listener activity will be associated</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/process.png"/></imageobject></mediaobject> + <title>The PrintLn listener process</title> + <mediaobject><imageobject><imagedata align="center" fileref="images/process.ab.png"/></imageobject></mediaobject> </figure> - <programlisting>ProcessDefinition processDefinition = ProcessFactory.build() - .node("a").initial().behaviour(new WaitState()) - <emphasis role="bold">.event("node-leave") - .listener(new Display("leaving a")) - .listener(new Display("second message while leaving a"))</emphasis> - .transition().to("b") - <emphasis role="bold">.listener(new Display("taking transition"))</emphasis> - .node("b").behaviour(new WaitState()) - <emphasis role="bold">.event("node-enter") - .listener(new Display("entering b"))</emphasis> + <programlisting>ClientProcessDefinition processDefinition = ProcessFactory.build() + .node("a").initial().behaviour(new AutomaticActivity()) + <emphasis role="bold">.event("node-end") + .listener(new PrintLn("leaving a")) + .listener(new PrintLn("second message while leaving a"))</emphasis> + .transition().to("b") + <emphasis role="bold">.listener(new PrintLn("taking transition"))</emphasis> + .node("b").behaviour(new WaitState()) + .event("node-begin") + <emphasis role="bold">.listener(new PrintLn("entering b"))</emphasis> .done();</programlisting> <para>The first event shows how to register multiple listeners to the same event. They will be notified in the order as they are specified. @@ -396,7 +397,7 @@ control the propagation of execution. </para> </section> - + <!-- ### EVENT PROPAGATION ############################################## --> <section> <title>Event propagation</title> @@ -521,56 +522,4 @@ <programlisting>leaving node(composite)</programlisting> </section> - <!-- ### PROCESS STRUCTURE ############################################## --> - <section> - <title>Process structure</title> - <para>Above we already touched briefly on the two main process constructs: - Nodes, transitions and node composition. This section will elaborate - on all the basic combination possibilities. - </para> - <figure id="process.structure"> - <title>UML class diagram of the basic process structure</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/process.structure.classes.png"/></imageobject></mediaobject> - </figure> - <para>Next is a series of example diagram structures that can be formed - with the PVM process model. - </para> - <figure id="transition"> - <title>Any two nodes can be connected with a transition.</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/transition.png"/></imageobject></mediaobject> - </figure> - <figure id="self.transition"> - <title>A self transition.</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/self.transition.png"/></imageobject></mediaobject> - </figure> - <figure id="composite.node"> - <title>Composite node is a list of nested nodes.</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/composite.node.png"/></imageobject></mediaobject> - </figure> - <figure id="transition.into.composite"> - <title>Transition to a node inside a composite.</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/transition.into.composite.png"/></imageobject></mediaobject> - </figure> - <figure id="transition.out.of.composite"> - <title>Transition from a node inside a composite to a node outside the composite.</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/transition.out.of.composite.png"/></imageobject></mediaobject> - </figure> - <figure id="transition.inheritence"> - <title>Transition of composite nodes are inherited. The node inside can take the transition of the composite node.</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/transition.inheritence.png"/></imageobject></mediaobject> - </figure> - <figure id="transition.to.outer"> - <title>Transition from a node to an outer composite.</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/transition.to.outer.png"/></imageobject></mediaobject> - </figure> - <figure id="transition.to.inner"> - <title>Transition from a composite node to an inner composed node.</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/transition.to.inner.png"/></imageobject></mediaobject> - </figure> - <figure id="initial.in.composite"> - <title>An initial node inside a composite node.</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/initial.in.composite.png"/></imageobject></mediaobject> - </figure> - </section> - </chapter> Modified: jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch05-ProcessAnatomy.xml =================================================================== --- jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch05-ProcessAnatomy.xml 2008-09-18 19:11:01 UTC (rev 2281) +++ jbpm4/pvm/trunk/modules/manual/src/main/docbook/en/modules/ch05-ProcessAnatomy.xml 2008-09-18 19:11:04 UTC (rev 2282) @@ -1,4 +1,62 @@ <chapter id="processanatomy"> <title>Process anatomy</title> - <para>TODO</para> + + <para>Above we already touched briefly on the two main process constructs: + Nodes, transitions and node composition. This chapter explores in full + all the possibilities of the process definition structures. + </para> + + <para>There are basically two forms of process languages: graph based and composite + process languages. First of all, the process supports both. Even graph based execution + and node composition can be used in combination to implement something like UML super states. + Furthermore, automatic functional activities can be implemented so that they can be + used with transitions as well as with node composition. + </para> + + <figure id="process.anatomy"> + <title>UML class diagram of the logical process structure</title> + <mediaobject><imageobject><imagedata align="center" fileref="images/process.anatomy.classes.png"/></imageobject></mediaobject> + </figure> + + <para>Next we'll describe a series of example diagram structures that can be formed + with the PVM process model. + </para> + + <figure id="transition"> + <title>Any two nodes can be connected with a transition.</title> + <mediaobject><imageobject><imagedata align="center" fileref="images/transition.png"/></imageobject></mediaobject> + </figure> + + <figure id="self.transition"> + <title>A self transition.</title> + <mediaobject><imageobject><imagedata align="center" fileref="images/self.transition.png"/></imageobject></mediaobject> + </figure> + <figure id="composite.node"> + <title>Composite node is a list of nested nodes.</title> + <mediaobject><imageobject><imagedata align="center" fileref="images/composite.node.png"/></imageobject></mediaobject> + </figure> + <figure id="transition.into.composite"> + <title>Transition to a node inside a composite.</title> + <mediaobject><imageobject><imagedata align="center" fileref="images/transition.into.composite.png"/></imageobject></mediaobject> + </figure> + <figure id="transition.out.of.composite"> + <title>Transition from a node inside a composite to a node outside the composite.</title> + <mediaobject><imageobject><imagedata align="center" fileref="images/transition.out.of.composite.png"/></imageobject></mediaobject> + </figure> + <figure id="transition.inheritence"> + <title>Transition of composite nodes are inherited. The node inside can take the transition of the composite node.</title> + <mediaobject><imageobject><imagedata align="center" fileref="images/transition.inheritence.png"/></imageobject></mediaobject> + </figure> + <figure id="transition.to.outer"> + <title>Transition from a node to an outer composite.</title> + <mediaobject><imageobject><imagedata align="center" fileref="images/transition.to.outer.png"/></imageobject></mediaobject> + </figure> + <figure id="transition.to.inner"> + <title>Transition from a composite node to an inner composed node.</title> + <mediaobject><imageobject><imagedata align="center" fileref="images/transition.to.inner.png"/></imageobject></mediaobject> + </figure> + <figure id="initial.in.composite"> + <title>An initial node inside a composite node.</title> + <mediaobject><imageobject><imagedata align="center" fileref="images/initial.in.composite.png"/></imageobject></mediaobject> + </figure> </chapter> \ No newline at end of file