[jbpm-commits] JBoss JBPM SVN: r5981 - in jbpm4/trunk/modules: devguide/src/main/docbook/en/images and 9 other directories.

Author: jbarrez Date: 2009-12-17 15:49:49 -0500 (Thu, 17 Dec 2009) New Revision: 5981 Added: jbpm4/trunk/modules/devguide/src/main/docbook/en/images/bpmn2.service.task.png jbpm4/trunk/modules/examples/src/test/java/org/jbpm/examples/bpmn/task/ jbpm4/trunk/modules/examples/src/test/java/org/jbpm/examples/bpmn/task/service/ jbpm4/trunk/modules/examples/src/test/java/org/jbpm/examples/bpmn/task/service/JavaService.java jbpm4/trunk/modules/examples/src/test/java/org/jbpm/examples/bpmn/task/service/ServiceTaskTest.java jbpm4/trunk/modules/examples/src/test/resources/org/jbpm/examples/bpmn/task/ jbpm4/trunk/modules/examples/src/test/resources/org/jbpm/examples/bpmn/task/service/ jbpm4/trunk/modules/examples/src/test/resources/org/jbpm/examples/bpmn/task/service/service_task_java.bpmn.xml Removed: jbpm4/trunk/modules/test-db/src/test/java/org/jbpm/bpmn/JavaServiceTask.java jbpm4/trunk/modules/test-db/src/test/java/org/jbpm/bpmn/ServiceTaskTest.java jbpm4/trunk/modules/test-db/src/test/resources/org/jbpm/bpmn/ServiceTaskJava.bpmn.xml Modified: jbpm4/trunk/modules/bpmn/src/main/java/org/jbpm/bpmn/flownodes/ServiceTaskBinding.java jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch03-Bpmn2.xml Log: JBPM-2663: revised and documented Java Service Task Modified: jbpm4/trunk/modules/bpmn/src/main/java/org/jbpm/bpmn/flownodes/ServiceTaskBinding.java =================================================================== --- jbpm4/trunk/modules/bpmn/src/main/java/org/jbpm/bpmn/flownodes/ServiceTaskBinding.java 2009-12-17 19:45:24 UTC (rev 5980) +++ jbpm4/trunk/modules/bpmn/src/main/java/org/jbpm/bpmn/flownodes/ServiceTaskBinding.java 2009-12-17 20:49:49 UTC (rev 5981) @@ -53,6 +53,9 @@ //Element operationElement = dom.getElementById(operationRef); Element operationElement = bpmnProcessDefinition.getOperations().get(operationRef); + if (operationElement == null) { + parse.addProblem("No operation found for operationRef " + operationRef, operationElement); + } Element interfaceElement = (Element)operationElement.getParentNode(); javaActivity.setMethodName(operationElement.getAttribute("name")); Added: jbpm4/trunk/modules/devguide/src/main/docbook/en/images/bpmn2.service.task.png =================================================================== (Binary files differ) Property changes on: jbpm4/trunk/modules/devguide/src/main/docbook/en/images/bpmn2.service.task.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Modified: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch03-Bpmn2.xml =================================================================== --- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch03-Bpmn2.xml 2009-12-17 19:45:24 UTC (rev 5980) +++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch03-Bpmn2.xml 2009-12-17 20:49:49 UTC (rev 5981) @@ -467,7 +467,122 @@ </para> </section> + + <section id="task"> + + <title>Tasks</title> + + <para> + A BPMN task is a so-called 'atomic' activity, meaning that it cannot be broken into + more detailed constructs. A task represents work that needs to be done by an external + entity, such as a human actor or an automated service. + </para> + + <para> + It's important to note that the BPMN semantics of a 'task' differ from the JPDL semantics. + In JPDL, the concept 'task' is always used in the context of a human actor doing some + type of work. When the process engine encounters a task in JPDL, it will create a task in some human + actor's task list and it will behave as a wait state. In BPMN 2.0 however, there are several + task types, some indicating a wait state (eg. the <emphasis role="bold">User Task</emphasis> + and some indicating an automatic activity (eg. the <emphasis role="bold">Service Task</emphasis>. + So take good care not to confuse the meaning of the task concept when switching languages. + </para> + + <para> + Tasks are depicted by a rounded rectangle, typically containing a text inside. The type + of the task (user task, service task, script task, etc.) is shown as a little icon on the left top + corner of the rectangle. Depending on the task type, the engine will execute different + functionality. + </para> + + </section> + + <section id="serviceTask"> + + <title>Task: Java Service Task</title> + + <para> + A <emphasis role="bold">Service Task</emphasis> is an automatic activity that calls some + sort of service, such as a web service, Java service, etc. Currently, only Java service + invocations are supported by the jBPM engine, but Web service invocations are planned + for a future release. + <mediaobject><imageobject><imagedata align="center" fileref="images/bpmn2.service.task.png"/></imageobject></mediaobject> + </para> + + <para> + Defining a service task requires quite a few lines of XML (the BPEL influence is certainly + visible). Of course, in the near future, we expect that tooling will simplify this area + a lot. A service task is defined as follows: + <programlisting> +&lt;serviceTask id=&quot;MyServiceTask&quot; name=&quot;My service task&quot; implementation=&quot;Other&quot; operationRef=&quot;myOperation&quot; /&gt; + </programlisting> + The service task has a required <emphasis role="bold">id</emphasis> and an optional + <emphasis role="bold">name</emphasis>. The <emphasis role="bold">implementation</emphasis> + attribute is used to indicate what the type of the invoked service is. Possible values + are WebService, Other or Unspecified. Since we've only implemented the Java invocation, + only the <emphasis role="bold">Other</emphasis> choice will do something useful for the moment. + </para> + + <para> + The service task will invoke a certain operation that is referenced by the + <emphasis role="bold">operationRef</emphasis> attribute using the id of an + <emphasis role="bold">operation</emphasis>. Such an operation is part of an + <emphasis role="bold">interface</emphasis> as shown below. Every operations has + at least one <emphasis role="bold">input message</emphasis> and at most one + <emphasis role="bold">output message</emphasis>. + <programlisting> +&lt;interface id=&quot;myInterface&quot; + name=&quot;org.jbpm.MyJavaServicek&quot;&gt; + &lt;operation id=&quot;myOperation2&quot; name=&quot;myMethod&quot;&gt; + &lt;inMessageRef&gt;inputMessage&lt;/inMessageRef&gt; + &lt;outMessageRef&gt;outputMessage&lt;/outMessageRef&gt; + &lt;/bpmn:operation&gt; +&lt;/interface&gt; + </programlisting> + For a Java service, the <emphasis role="bold">name of the interface</emphasis> is used + to specificy the fully qualified classname of the Java class. The <emphasis role="bold"> + name of the operation</emphasis> is then used to specify the name of the method + that must be called. The input/output message that represent the parameters/return value of + the Java method are defined as follows: + <programlisting> +&lt;message id=&quot;inputMessag&quot; name=&quot;input message&quot; structureRef=&quot;myItemDefinition1&quot; /&gt; + </programlisting> + Several elements in BPMN are so-called 'item-aware', including this message construct. + This means that they are involved in storing or reading items during process execution. + The data structure to hold these elements is specified using a reference to an + <emphasis role="bold">ItemDefinition</emphasis>. In this context, the message specifies + its data structure by referencing an Itemdefinition in the + <emphasis role="bold">structureRef</emphasis> attribute. + <programlisting> + + &lt;itemDefinition id=&quot;myItemDefinition1&quot; &gt; + &lt;jbpm:arg&gt; + &lt;jbpm:object expr=&quot;#{var1}&quot; /&gt; + &lt;/jbpm:arg&gt; + &lt;/itemDefinition&gt; + &lt;itemDefinition id=&quot;myItemDefinition2&quot;&gt; + &lt;jbpm:var name=&quot;returnVar&quot; /&gt; + &lt;/itemDefinition&gt; + + </programlisting> + Do note that this is not standard BPMN 2.0 as by the specification (hence the 'jbpm' prefix). + In fact, according to the specification, the ItemDefinition shouldn't contain more + than a data structure definition. The actual mapping between input paramaters, with a ceratin + data structure, is done in the <emphasis role="bold">ioSpecification</emphasis> section + of the serviceTask. However, the current jBPM BPMN 2.0 implementation hasn't implemented + that construct yet. So, this means that the current usage as described above, will probably + change in the near future. + </para> + + <para> + <emphasis role="bold">Important note: Interfaces, ItemDefinitions and messages are + defined outside the &lt;process&gt;.</emphasis>. See the example <emphasis role="bold"> + ServiceTaskTest</emphasis> for a concrete process and unit test. + </para> + + </section> + </section> <!-- End of basic constructs section --> </chapter> Copied: jbpm4/trunk/modules/examples/src/test/java/org/jbpm/examples/bpmn/task/service/JavaService.java (from rev 5958, jbpm4/trunk/modules/test-db/src/test/java/org/jbpm/bpmn/JavaServiceTask.java) =================================================================== --- jbpm4/trunk/modules/examples/src/test/java/org/jbpm/examples/bpmn/task/service/JavaService.java (rev 0) +++ jbpm4/trunk/modules/examples/src/test/java/org/jbpm/examples/bpmn/task/service/JavaService.java 2009-12-17 20:49:49 UTC (rev 5981) @@ -0,0 +1,9 @@ +package org.jbpm.examples.bpmn.task.service; + +public class JavaService { + + String myMethod(String arg1) { + return "myMethod with arg1: "+ arg1; + } + +} Copied: jbpm4/trunk/modules/examples/src/test/java/org/jbpm/examples/bpmn/task/service/ServiceTaskTest.java (from rev 5958, jbpm4/trunk/modules/test-db/src/test/java/org/jbpm/bpmn/ServiceTaskTest.java) =================================================================== --- jbpm4/trunk/modules/examples/src/test/java/org/jbpm/examples/bpmn/task/service/ServiceTaskTest.java (rev 0) +++ jbpm4/trunk/modules/examples/src/test/java/org/jbpm/examples/bpmn/task/service/ServiceTaskTest.java 2009-12-17 20:49:49 UTC (rev 5981) @@ -0,0 +1,67 @@ +/* + * JBoss, Home of Professional Open Source + * Copyright 2005, JBoss Inc., and individual contributors as indicated + * by the @authors tag. See the copyright.txt in the distribution for a + * full listing of individual contributors. + * + * This is free software; you can redistribute it and/or modify it + * under the terms of the GNU Lesser General Public License as + * published by the Free Software Foundation; either version 2.1 of + * the License, or (at your option) any later version. + * + * This software is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this software; if not, write to the Free + * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA + * 02110-1301 USA, or see the FSF site: http://www.fsf.org. + */ +package org.jbpm.examples.bpmn.task.service; + +import java.util.HashMap; +import java.util.List; +import java.util.Map; + +import org.jbpm.api.NewDeployment; +import org.jbpm.api.ProcessInstance; +import org.jbpm.api.TaskQuery; +import org.jbpm.api.task.Task; +import org.jbpm.test.JbpmTestCase; + +/** + * @author Bernd Ruecker (bernd.ruecker(a)camunda.com) + * @author Joram Barrez + */ +public class ServiceTaskTest extends JbpmTestCase { + + @Override + protected void setUp() throws Exception { + super.setUp(); + NewDeployment deployment = repositoryService.createDeployment(); + deployment.addResourceFromClasspath("org/jbpm/examples/bpmn/task/service/service_task_java.bpmn.xml"); + registerDeployment(deployment.deploy()); + } + + public void testJavaServiceTaskCall() { + Map<String, Object> variables = new HashMap<String, Object>(); + variables.put("var1", "value"); + + ProcessInstance pi = executionService.startProcessInstanceByKey( + "ServiceTaskJavaProcess", variables); + + assertNotNull(pi.getId()); + assertEquals("myMethod with arg1: value", executionService.getVariable( + pi.getId(), "returnVar")); + + TaskQuery taskQuery = taskService.createTaskQuery(); + List<Task> allTasks = taskQuery.list(); + assertEquals(1, allTasks.size()); + + taskService.completeTask(allTasks.get(0).getId()); + assertProcessInstanceEnded(pi); + } + +} Copied: jbpm4/trunk/modules/examples/src/test/resources/org/jbpm/examples/bpmn/task/service/service_task_java.bpmn.xml (from rev 5970, jbpm4/trunk/modules/test-db/src/test/resources/org/jbpm/bpmn/ServiceTaskJava.bpmn.xml) =================================================================== --- jbpm4/trunk/modules/examples/src/test/resources/org/jbpm/examples/bpmn/task/service/service_task_java.bpmn.xml (rev 0) +++ jbpm4/trunk/modules/examples/src/test/resources/org/jbpm/examples/bpmn/task/service/service_task_java.bpmn.xml 2009-12-17 20:49:49 UTC (rev 5981) @@ -0,0 +1,55 @@ +<?xml version="1.0" encoding="UTF-8"?> +<bpmn:definitions id="ServiceTaskJava" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://schema.omg.org/spec/BPMN/2.0 ../../../../../../../bpmn/src/main/resources/BPMN20.xsd" + xmlns:bpmn="http://schema.omg.org/spec/BPMN/2.0" typeLanguage="http://www.w3.org/2001/XMLSchema" + expressionLanguage="http://www.w3.org/1999/XPath" targetNamespace="http://sample.bpmn.camunda.com/" + xmlns:jbpm="http://jbpm.org/4.0/bpmn2"> + + <bpmn:itemDefinition id="itemDefinition1" > + <jbpm:arg> + <jbpm:object expr="#{var1}" /> + </jbpm:arg> + </bpmn:itemDefinition> + + <bpmn:itemDefinition id="itemDefinition2"> + <jbpm:var name="returnVar" /> + </bpmn:itemDefinition> + + <bpmn:message id="inputMessage" name="input message" + structureRef="itemDefinition1"></bpmn:message> + + <bpmn:message id="outputMessage" name="output message" + structureRef="itemDefinition2"> + </bpmn:message> + + <bpmn:interface id="myInterface" name="org.jbpm.examples.bpmn.task.service.JavaService"> + <bpmn:operation id="myOperation" name="myMethod"> + <bpmn:inMessageRef>inputMessage</bpmn:inMessageRef> + <bpmn:outMessageRef>outputMessage</bpmn:outMessageRef> + </bpmn:operation> + </bpmn:interface> + + <bpmn:process id="ServiceTaskJavaProcess" name="Simple process with java service task"> + + <bpmn:startEvent id="Start" /> + + <bpmn:sequenceFlow id="flow1" name="fromStartToServiceTask" + sourceRef="Start" targetRef="ServiceTask" /> + + <bpmn:serviceTask id="ServiceTask" name="service task" + implementation="Other" operationRef="myOperation"> + </bpmn:serviceTask> + + <bpmn:sequenceFlow id="flow2" name="fromServiceTaskToUT1" + sourceRef="ServiceTask" targetRef="UT1" /> + + <bpmn:userTask id="UT1" name="bla" implementation="other" /> + + <bpmn:sequenceFlow id="flow3" name="fromUT1toEnd" + sourceRef="UT1" targetRef="End" /> + + <bpmn:endEvent id="End" name="End" /> + + </bpmn:process> +</bpmn:definitions> Deleted: jbpm4/trunk/modules/test-db/src/test/java/org/jbpm/bpmn/JavaServiceTask.java =================================================================== --- jbpm4/trunk/modules/test-db/src/test/java/org/jbpm/bpmn/JavaServiceTask.java 2009-12-17 19:45:24 UTC (rev 5980) +++ jbpm4/trunk/modules/test-db/src/test/java/org/jbpm/bpmn/JavaServiceTask.java 2009-12-17 20:49:49 UTC (rev 5981) @@ -1,9 +0,0 @@ -package org.jbpm.bpmn; - -public class JavaServiceTask { - - String myMethod(String arg1) { - return "myMethod with arg1: "+ arg1; - } - -} Deleted: jbpm4/trunk/modules/test-db/src/test/java/org/jbpm/bpmn/ServiceTaskTest.java =================================================================== --- jbpm4/trunk/modules/test-db/src/test/java/org/jbpm/bpmn/ServiceTaskTest.java 2009-12-17 19:45:24 UTC (rev 5980) +++ jbpm4/trunk/modules/test-db/src/test/java/org/jbpm/bpmn/ServiceTaskTest.java 2009-12-17 20:49:49 UTC (rev 5981) @@ -1,68 +0,0 @@ -/* - * JBoss, Home of Professional Open Source - * Copyright 2005, JBoss Inc., and individual contributors as indicated - * by the @authors tag. See the copyright.txt in the distribution for a - * full listing of individual contributors. - * - * This is free software; you can redistribute it and/or modify it - * under the terms of the GNU Lesser General Public License as - * published by the Free Software Foundation; either version 2.1 of - * the License, or (at your option) any later version. - * - * This software is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * Lesser General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public - * License along with this software; if not, write to the Free - * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA - * 02110-1301 USA, or see the FSF site: http://www.fsf.org. - */ -package org.jbpm.bpmn; - -import java.util.HashMap; -import java.util.List; -import java.util.Map; - -import org.jbpm.api.ProcessInstance; -import org.jbpm.api.TaskQuery; -import org.jbpm.api.task.Task; -import org.jbpm.test.JbpmTestCase; - -/** - * @author Bernd Ruecker (bernd.ruecker(a)camunda.com) - */ -public class ServiceTaskTest extends JbpmTestCase { - - public void testNormalJavaServiceTaskCall() { - String deploymentId = repositoryService.createDeployment().addResourceFromClasspath("org/jbpm/bpmn/ServiceTaskJava.bpmn.xml").deploy(); - - try { - - Map<String, Object> variables = new HashMap<String, Object>(); - variables.put("var1", "value"); - - ProcessInstance pi = executionService.startProcessInstanceByKey("ServiceTaskJavaProcess", variables); - - assertNotNull(pi.getId()); - assertEquals("myMethod with arg1: value",executionService.getVariable(pi.getId(), "returnVar")); - - TaskQuery taskQuery = taskService.createTaskQuery(); - List<Task> allTasks = taskQuery.list(); - assertEquals(1, allTasks.size()); - - taskService.completeTask(allTasks.get(0).getId()); - - // process instance is ended - pi = executionService.findProcessInstanceById(pi.getId()); - // One way or another I would also expect this to work... pi is gone from - // database immediately when ended. Only in History DB - // assertEquals(true, pi.isEnded()); - assertNull(pi); - } finally { - repositoryService.deleteDeploymentCascade(deploymentId); - } - } - -} Deleted: jbpm4/trunk/modules/test-db/src/test/resources/org/jbpm/bpmn/ServiceTaskJava.bpmn.xml =================================================================== --- jbpm4/trunk/modules/test-db/src/test/resources/org/jbpm/bpmn/ServiceTaskJava.bpmn.xml 2009-12-17 19:45:24 UTC (rev 5980) +++ jbpm4/trunk/modules/test-db/src/test/resources/org/jbpm/bpmn/ServiceTaskJava.bpmn.xml 2009-12-17 20:49:49 UTC (rev 5981) @@ -1,56 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<bpmn:definitions id="ServiceTaskJava" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://schema.omg.org/spec/BPMN/2.0 ../../../../../../../bpmn/src/main/resources/BPMN20.xsd" - xmlns:bpmn="http://schema.omg.org/spec/BPMN/2.0" typeLanguage="http://www.w3.org/2001/XMLSchema" - expressionLanguage="http://www.w3.org/1999/XPath" targetNamespace="http://sample.bpmn.camunda.com/" - xmlns:jbpm="http://jbpm.org/4.0/bpmn2"> - - <bpmn:itemDefinition id="itemDefinition1"> - <jbpm:arg> - <jbpm:object expr="#{var1}" /> - </jbpm:arg> - </bpmn:itemDefinition> - - <bpmn:itemDefinition id="itemDefinition2"> - <jbpm:var name="returnVar" /> - </bpmn:itemDefinition> - - <bpmn:message id="inputMessage" name="input message" - structureRef="itemDefinition1"></bpmn:message> - - <bpmn:message id="outputMessage" name="output message" - structureRef="itemDefinition2"> - </bpmn:message> - - <bpmn:interface id="interface21" - name="org.jbpm.bpmn.JavaServiceTask"> - <bpmn:operation id="operation42" name="myMethod"> - <bpmn:inMessageRef>inputMessage</bpmn:inMessageRef> - <bpmn:outMessageRef>outputMessage</bpmn:outMessageRef> - </bpmn:operation> - </bpmn:interface> - - <bpmn:process id="ServiceTaskJavaProcess" name="Simple process with java service task"> - - <bpmn:startEvent id="Start" /> - - <bpmn:sequenceFlow id="flow1" name="fromStartToServiceTask" - sourceRef="Start" targetRef="ServiceTask" /> - - <bpmn:serviceTask id="ServiceTask" name="service task" - implementation="Other" operationRef="operation42"> - </bpmn:serviceTask> - - <bpmn:sequenceFlow id="flow2" name="fromServiceTaskToUT1" - sourceRef="ServiceTask" targetRef="UT1" /> - - <bpmn:userTask id="UT1" name="bla" implementation="other" /> - - <bpmn:sequenceFlow id="flow3" name="fromUT1toEnd" - sourceRef="UT1" targetRef="End" /> - - <bpmn:endEvent id="End" name="End" /> - - </bpmn:process> -</bpmn:definitions>