<?xml version="1.0" encoding="UTF-8"?>
<chapter id="ch.quickstarts" 
         version="5.0"
         xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd"
         xml:base="../" xmlns="http://docbook.org/ns/docbook" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:ns="http://docbook.org/ns/docbook">
  <title>Quickstarts</title>

  <para>This chapter contains a number of simple, common task that you can follow to get started.</para>

  <section>
    <title>Invoking a Java service</title>

    <para>It is common that you already have existing Java code that you would like to invoke from
    your process.  How do you do that?  There are different ways of doing this, and this quickstart will
    show you some of these alternatives.</para>
    
  <section>
    <title>Using a script task</title>
    
    <para>One of the easiest ways to include some Java code into your process is to use a Script Task.
    This task will execute some script code whenever that node is reached during the execution of the
    process.  This allows you to include some Java code as part of the process.  For example, imagine
    this simple process that contains one Script Task to invoke some existing Java code:</para>
    
  <figure>
    <mediaobject>
      <imageobject>
	<imagedata align="center" fileref="images/Chapter-Quickstarts/HelloScriptProcess.png" format="PNG" role="" />
      </imageobject>
    </mediaobject>
  </figure>
  
    <para>The script task defines a script that needs to be executed when the task is reached.  In this
    case, the script invokes an existing class <code>org.jbpm.examples.quickstarts.HelloService</code>:</para>
  
<programlisting language="java">HelloService.getInstance().sayHello(person.getName());</programlisting>

    <para>where the HelloService class looks like this:</para>
    
<programlisting language="java">package org.jbpm.examples.quickstarts;
public class HelloService {
  private static final HelloService INSTANCE = new HelloService();
  public static HelloService getInstance() {
    return INSTANCE;
  }
  public void sayHello(String name) {
    System.out.println("Hello " + name);
  }
}</programlisting>

    <para>The script retrieves an instance of the HelloService and passes it the name of the person
    that started this process.  This is possible because <code>person</code> is defined as a variable
    of the process, of type <code>org.jbpm.examples.quickstarts.Person</code>, and script tasks can directly reference
    process variables as if they were local variables (at least for reading, for setting the value of
    a variable, you should use <code>kcontext.setVariable(name, value)</code>).  This process also 
    references HelloService without fully qualifying the package as HelloService is defined using an
    import statement.</para>
    
    <para>The underlying XML might look something like this:</para>
<programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt; 
&lt;definitions id="Definition"
             targetNamespace="http://www.jboss.org/drools"
             typeLanguage="http://www.java.com/javaTypes"
             expressionLanguage="http://www.mvel.org/2.0"
             xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://www.omg.org/spec/BPMN/20100524/MODEL BPMN20.xsd"
             xmlns:g="http://www.jboss.org/drools/flow/gpd"
             xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI"
             xmlns:dc="http://www.omg.org/spec/DD/20100524/DC"
             xmlns:di="http://www.omg.org/spec/DD/20100524/DI"
             xmlns:tns="http://www.jboss.org/drools"&gt;
  &lt;itemDefinition id="_personItem" structureRef="org.jbpm.examples.quickstarts.Person" /&gt;
  &lt;process processType="Private" isExecutable="true" id="org.jbpm.examples.quickstarts.script" 
           name="Sample Process" tns:packageName="defaultPackage" &gt;
    &lt;extensionElements&gt;
      &lt;tns:import name="org.jbpm.examples.quickstarts.HelloService" /&gt;
    &lt;/extensionElements&gt;
    &lt;!-- process variables --&gt;
    &lt;property id="person" itemSubjectRef="_personItem"/&gt;
    &lt;!-- nodes --&gt;
    &lt;startEvent id="_1" name="StartProcess" /&gt;
    &lt;scriptTask id="_2" name="Script" &gt;
      &lt;script&gt;HelloService.getInstance().sayHello(person.getName());&lt;/script&gt;
    &lt;/scriptTask&gt;
    &lt;endEvent id="_3" name="End" &gt;
      &lt;terminateEventDefinition/&gt;
    &lt;/endEvent&gt;
    &lt;!-- connections --&gt;
    &lt;sequenceFlow id="_1-_2" sourceRef="_1" targetRef="_2" /&gt;
    &lt;sequenceFlow id="_2-_3" sourceRef="_2" targetRef="_3" /&gt;
  &lt;/process&gt;
  &lt;bpmndi:BPMNDiagram&gt;
    &lt;bpmndi:BPMNPlane bpmnElement="org.jbpm.examples.quickstarts.script" &gt;
      &lt;bpmndi:BPMNShape bpmnElement="_1" &gt;
        &lt;dc:Bounds x="45" y="45" width="48" height="48" /&gt;
      &lt;/bpmndi:BPMNShape&gt;
      &lt;bpmndi:BPMNShape bpmnElement="_2" &gt;
        &lt;dc:Bounds x="131" y="46" width="80" height="48" /&gt;
      &lt;/bpmndi:BPMNShape&gt;
      &lt;bpmndi:BPMNShape bpmnElement="_3" &gt;
        &lt;dc:Bounds x="252" y="47" width="48" height="48" /&gt;
      &lt;/bpmndi:BPMNShape&gt;
      &lt;bpmndi:BPMNEdge bpmnElement="_1-_2" &gt;
        &lt;di:waypoint x="69" y="69" /&gt;
        &lt;di:waypoint x="171" y="70" /&gt;
      &lt;/bpmndi:BPMNEdge&gt;
      &lt;bpmndi:BPMNEdge bpmnElement="_2-_3" &gt;
        &lt;di:waypoint x="171" y="70" /&gt;
        &lt;di:waypoint x="276" y="71" /&gt;
      &lt;/bpmndi:BPMNEdge&gt;
    &lt;/bpmndi:BPMNPlane&gt;
  &lt;/bpmndi:BPMNDiagram&gt;
&lt;/definitions&gt;</programlisting>

    <para>A simple test that executes this process could look something like this: simply create a ksession
    and start the process by id, passing in a <code>Person</code> object that will then be set as the 
    <code>person</code> process variable:</para>

<programlisting language="java">public class JavaServiceQuickstartTest extends JbpmJUnitTestCase {
  @Test
  public void testProcess() {
    StatefulKnowledgeSession ksession = createKnowledgeSession("test.bpmn");
    Map&lt;String, Object&gt; params = new HashMap&lt;String, Object&gt;();
    params.put("person", new Person("krisv"));
    ksession.startProcess("org.jbpm.examples.quickstarts.script", params);
  }
}</programlisting>

    <para>This example shows how easy it is to include custom Java code in your process using Script
    Tasks, to invoke existing code and to pass it process variable values.  Note that some node types
    allow you to specify on-entry and on-exit actions (which will be executed when the node is 
    triggered or left respectively).  This allows you to include scripts, just
    like you would do when using a Script Task, but hiding these more or less from the diagram (as for
    example business users might not be interested in these details).</para>

  </section>
    
  <section>
    <title>Using a Java handler</title>
    
    <para></para>

  </section>
    
  <section>
    <title>Writing your own domain-specific task</title>
    
    <para></para>

  </section>
    
  </section>

</chapter>
