ACT-1553: added BpmnParseHandler docs to the user guide

distro/src/readme.html

@@ -23,12 +23,7 @@
       <li><a href="docs/javadocs/index.html">Javadocs</a></li>
     </ul>
     
-    <h1>Links for demo setup</h1>
-    <p>After installing the Activiti distribution,
-    you can open the <a href="http://localhost:8080/activiti-explorer/">Activiti Explorer</a>
-    </p>
-    
-    <h1>Other Links</h1>
+    <h1>Links</h1>
     <ul>
       <li><a href="http://forums.activiti.org/en/viewforum.php?f=3">Activiti User Forum</a></li>
       <li><a href="http://forums.activiti.org/en/viewforum.php?f=4">Activiti Developer Forum</a></li>
@@ -40,6 +35,21 @@
 
   <h1>Activiti Release Notes</h1>
 
+  <h3>Release Notes - Activiti - Version 5.12</h3>
+  
+  <h4>Important upgrade note</h4>
+  
+  <p>
+    The internal <i>org.activiti.engine.impl.bpmn.parser.BpmnParseListener</i> interface and related classes have been removed.
+  </p>
+    
+  <p>  
+    Yes, we know many people relied on its capabilities, altough it was a class in an internal package. But do not worry:
+    we have introduced a replacement in the <b>api package</b> that offers similar (and even more powerful) functionality.
+    The code is not backwards compatible, but the required changes should be minimal (eg the XML element is replaced by a
+    Java pojo representation of the element). Read more about it in the new 'Advanced' chapter of the userguide.
+  </p>
+
   <h3>Release Notes - Activiti - Version 5.11</h3>
 
   <h4>Highlights</h4>

modules/activiti-engine/src/main/java/org/activiti/engine/parse/BpmnParseHandler.java

@@ -12,7 +12,7 @@
  */
 package org.activiti.engine.parse;
 
-import java.util.Set;
+import java.util.Collection;
 
 import org.activiti.bpmn.model.BaseElement;
 import org.activiti.engine.impl.bpmn.parser.BpmnParse;
@@ -22,7 +22,7 @@ import org.activiti.engine.impl.bpmn.parser.BpmnParse;
  */
 public interface BpmnParseHandler {
   
-  Set<Class<? extends BaseElement>> getHandledTypes();
+  Collection<Class<? extends BaseElement>> getHandledTypes();
   
   void parse(BpmnParse bpmnParse, BaseElement element);
 

userguide/src/en/chapters/ch16-Advanced.xml

+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "../../../target/docbook-tool-1.0/docbook-xml/docbookx.dtd">
+
+<chapter>
+	<title>Advanced</title>
+	
+	<para>
+	   The following sections cover advanced use cases of using Activiti, that go beyond typical execution of BPMN 2.0 processes.
+	   As such, a certain proficiency and experience with Activiti is advisable to understand the material here. 
+	</para>
+
+	<section id="advanced_parseHandlers">
+	
+	   <title>Hooking into process parsing</title>
+	
+	   <para>
+	       A bpmn 2.0 xml needs to be parsed to the Activiti internal model to be executed on the Activiti engine. This parsing
+	       happens during a deployment of the process or when a process is not found in memory, and the
+	       xml is fetched from the database. 
+	   </para>
+	   
+	   <para>
+	       For each of these processes, the <literal>BpmnParser</literal> class creates a new <literal>BpmnParse</literal> instance.
+	       This instance will be used as container for all things that are done during parsing. The parsing on itself is very simple:
+	       for each BPMN 2.0 element, there is a matching instance of the <literal>org.activiti.engine.parse.BpmnParseHandler</literal>
+	       available in the engine. As such, the parser has a map which basically maps an BPMN 2.0 element class to an instance of 
+	       <literal>BpmnParseHandler</literal>. By default, Activiti has <literal>BpmnParseHandler</literal> instances to handle
+	       all supported elements and also uses it to attach execution listeners to steps of the process for creating the history.
+	   </para>
+	   
+	   <para>
+	       It is possible to add custom instances of <literal>org.activiti.engine.parse.BpmnParseHandler</literal> to the Activiti engine.
+	       An often seen use case is for example to add execution listeners to certain steps that fire events to some queue for event processing.
+	       The history handling is done in such a way internally in Activiti.
+	       To add such custom handlers, the Activiti configuration needs to be tweaked:
+	       <programlisting>
+&lt;property name=&quot;preBpmnParseHandlers&quot;&gt;
+  &lt;list&gt;
+    &lt;bean class=&quot;org.activiti.parsing.MyFirstBpmnParseHandler&quot; /&gt;
+  &lt;/list&gt;
+&lt;/property&gt;
+	    
+&lt;property name=&quot;postBpmnParseHandlers&quot;&gt;
+  &lt;list&gt;
+    &lt;bean class=&quot;org.activiti.parsing.MySecondBpmnParseHandler&quot; /&gt;
+    &lt;bean class=&quot;org.activiti.parsing.MyThirdBpmnParseHandler&quot; /&gt;
+  &lt;/list&gt;
+&lt;/property&gt;    
+	       </programlisting>
+	       The list of <literal>BpmnParseHandler</literal> instances that is configured in the <literal>preBpmnParseHandlers</literal> property
+	       are added before any of the default handlers. Likewise, the <literal>postBpmnParseHandlers</literal> are added after those.
+	       This can be important if the order of things matter for the logic contained in the custom parse handlers.
+	   </para>
+	   
+	   <para>
+	       <literal>org.activiti.engine.parse.BpmnParseHandler</literal> is a simple interface:
+	       <programlisting>
+public interface BpmnParseHandler {
+  
+  Collection&lt;Class&gt;? extends BaseElement&gt;&gt; getHandledTypes();
+  
+  void parse(BpmnParse bpmnParse, BaseElement element);
+
+}	       
+	       </programlisting>
+	       The <literal>getHandledTypes()</literal> method returns a collection of all the types handled by this parser. 
+	       The possible types are a subclass of <literal>BaseElement</literal>, as directed by the generic type of the collection.
+	       You can also extend the <literal>AbstractBpmnParseHandler</literal> class and override the <literal>getHandledType()</literal>
+	       method, which only returns one Class and not a collection. This class contains also some helper methods
+	       shared by many of the default parse handlers. 
+	       The <literal>BpmnParseHandler</literal> instance will be called when the parser encounters any of the returned
+	       types by this method. In the following example, whenever a process contained in a BPMN 2.0 xml is encountered, it 
+	       will execute the logic in the <literal>executeParse</literal> method (which is a typecasted method that replaces
+	       the regular <literal>parse</literal> method on the <literal>BpmnParseHandler</literal> interface). 
+	       <programlisting>
+public class TestBPMNParseHandler extends AbstractBpmnParseHandler&lt;Process&gt; {
+
+  protected Class&lt;? extends BaseElement&gt; getHandledType() {
+    return Process.class;
+  }
+  
+  protected void executeParse(BpmnParse bpmnParse, Process element) {
+     ..
+  }
+
+}	       
+	       </programlisting>
+	   </para>
+	   
+	   <para>
+         It is possible (but less common) to replace the default <literal>BpmnParseHandler</literal> instances
+         that are responsible for the parsing of the BPMN 2.0 elements to the internal Activiti model.
+         This can be done by following snippet of logic:
+         <programlisting>
+&lt;property name=&quot;customDefaultBpmnParseHandlers&quot;&gt;
+  &lt;list&gt;
+    ...
+  &lt;/list&gt;
+&lt;/property&gt;         
+         </programlisting>
+         A simple example could for example be to force all of the service tasks to be asynchronous:
+         <programlisting>
+public class CustomUserTaskBpmnParseHandler extends ServiceTaskParseHandler {
+  
+  protected void executeParse(BpmnParse bpmnParse, ServiceTask serviceTask) {
+    
+    // Do the regular stuff
+    super.executeParse(bpmnParse, serviceTask);
+    
+    // Make always async
+    ActivityImpl activity = findActivity(bpmnParse, serviceTask.getId());
+    activity.setAsync(true);
+  }
+
+}         
+         </programlisting>          
+	   </para>
+        
+	</section>
+	
+</chapter>
\ No newline at end of file

userguide/src/en/index.xml

@@ -16,6 +16,7 @@
   <!ENTITY ch13 SYSTEM "chapters/ch13-Modeler.xml">
   <!ENTITY ch14 SYSTEM "chapters/ch14-REST.xml">
   <!ENTITY ch15 SYSTEM "chapters/ch15-Cdi.xml">
+  <!ENTITY ch16 SYSTEM "chapters/ch16-Advanced.xml">
 ]>
 
 <book>
@@ -40,5 +41,6 @@
 &ch13;
 &ch14;
 &ch15;
+&ch16;
 
 </book>