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

do-not-reply at jboss.org do-not-reply at jboss.org
Fri Jul 3 08:21:36 EDT 2009


Author: jbarrez
Date: 2009-07-03 08:21:36 -0400 (Fri, 03 Jul 2009)
New Revision: 5215

Added:
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch11-AdvancedEmail.xml
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch12-SoftwareLogging.xml
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch13-History.xml
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch14-JBossIntegration.xml
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch15-SpringIntegration.xml
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch16-Jpdl3Migration.xml
Removed:
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch11-SoftwareLogging.xml
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch12-History.xml
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch13-JBossIntegration.xml
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch14-SpringIntegration.xml
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch15-Jpdl3Migration.xml
Modified:
   jbpm4/trunk/modules/devguide/src/main/docbook/en/master.xml
   jbpm4/trunk/modules/userguide/src/main/docbook/en/master.xml
   jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch06-Jpdl.xml
Log:
JBPM-2364: move advanced mail support to devguide. Added example to mail activity in user guide.

Modified: jbpm4/trunk/modules/devguide/src/main/docbook/en/master.xml
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/master.xml	2009-07-03 11:46:43 UTC (rev 5214)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/master.xml	2009-07-03 12:21:36 UTC (rev 5215)
@@ -11,11 +11,12 @@
   <!ENTITY ch08-Configuration                  SYSTEM "modules/ch08-Configuration.xml">
   <!ENTITY ch09-Persistence                    SYSTEM "modules/ch09-Persistence.xml">
   <!ENTITY ch10-JobExecutor                    SYSTEM "modules/ch10-JobExecutor.xml">
-  <!ENTITY ch11-SoftwareLogging                SYSTEM "modules/ch11-SoftwareLogging.xml">
-  <!ENTITY ch12-History                        SYSTEM "modules/ch12-History.xml">
-  <!ENTITY ch13-JBossIntegration               SYSTEM "modules/ch13-JBossIntegration.xml">
-  <!ENTITY ch14-SpringIntegration              	SYSTEM "modules/ch14-SpringIntegration.xml">
-  <!ENTITY ch15-Jpdl3Migration               	SYSTEM "modules/ch15-Jpdl3Migration.xml">
+  <!ENTITY ch11-AdvancedEmail                  SYSTEM "modules/ch11-AdvancedEmail.xml">
+  <!ENTITY ch12-SoftwareLogging                SYSTEM "modules/ch12-SoftwareLogging.xml">
+  <!ENTITY ch13-History                        SYSTEM "modules/ch13-History.xml">
+  <!ENTITY ch14-JBossIntegration               SYSTEM "modules/ch14-JBossIntegration.xml">
+  <!ENTITY ch15-SpringIntegration              SYSTEM "modules/ch15-SpringIntegration.xml">
+  <!ENTITY ch16-Jpdl3Migration                 SYSTEM "modules/ch16-Jpdl3Migration.xml">
 ]>
 
 <book lang="en">
@@ -36,10 +37,11 @@
   &ch08-Configuration;
   &ch09-Persistence;
   &ch10-JobExecutor;
-  &ch11-SoftwareLogging;
-  &ch12-History;
-  &ch13-JBossIntegration;
-  &ch14-SpringIntegration;
-  &ch15-Jpdl3Migration;
+  &ch11-AdvancedEmail;
+  &ch12-SoftwareLogging;
+  &ch13-History;
+  &ch14-JBossIntegration;
+  &ch15-SpringIntegration;
+  &ch16-Jpdl3Migration;
 
 </book>
\ No newline at end of file

Added: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch11-AdvancedEmail.xml
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch11-AdvancedEmail.xml	                        (rev 0)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch11-AdvancedEmail.xml	2009-07-03 12:21:36 UTC (rev 5215)
@@ -0,0 +1,196 @@
+<chapter id="mailsupport">
+  <title>Advanced Mail Support</title>
+  <para>jBPM 4 takes advantage of the JavaMail API to make high-level email
+    services available to business process authors.</para>
+
+  <section id="mailproducers">
+    <title>Producers</title>
+    <para>Producers are responsible for creating email messages within jBPM. All mail producers 
+      implement the <literal>org.jbpm.pvm.internal.email.spi.MailProducer</literal> interface.
+      A default mail producer is available out of the box to address typical email needs.</para>
+
+    <section id="defaultmailproducer">
+      <title>Default Producer</title>
+      <para>The default mail producer is capable of creating email messages with text,
+        HTML and attachments from a template. Templates can be provided inline or
+        in the process-engine-context section of the jBPM configuration. Templates
+        may contain expressions which are evaluated through the script manager.
+      </para>
+      <para>The following listing presents a mail activity with an inline template.</para>
+      <programlisting><![CDATA[<mail name="rectify" language="juel">                             (1)
+  <from addresses='winston at minitrue' />                           (2)
+  <to addresses='julia at minitrue, obrien at miniluv'/>                (3)
+  <cc users='bigbrother'/>
+  <bcc groups='thinkpol, innerparty'/>
+  <subject>Part ${part} Chapter ${chapter}</subject>              (4)
+  <text>times ${date} reporting bb dayorder doubleplusungood      (5)
+    refs ${unpersons} rewrite fullwise upsub antefiling</text>
+  <html><table><tr><td>times</td><td>${date}</td>                 (6)
+    <td>reporting bb dayorder doubleplusungood 
+    refs ${unpersons} rewrite fullwise upsub antefiling</td>
+    </tr></table></html>
+  <attachments>                                                   (7)
+    <attachment url='http://www.george-orwell.org/1984/3.html'/>
+    <attachment resource='org/example/pic.jpg'/>
+    <attachment file='${user.home}/.face'/>
+  </attachments>
+</mail>]]></programlisting>
+      <orderedlist>
+      <listitem><para>Expressions within the template are written in the scripting language
+        indicated here. If not specified, the default expression language will be assumed.
+        </para></listitem>
+      <listitem><para>List of message senders. Senders are either identified directly by
+        their email addresses or appointed by means of the identity model.</para></listitem>
+      <listitem><para>Lists of message recipients, categorized as follows: <emphasis>To</emphasis>
+        (primary), <emphasis>CC</emphasis> (carbon copy) and <emphasis>BCC</emphasis> (blind 
+        carbon copy). Like senders, recipients are directly identified by their email addresses
+        or appointed by means of the identity model.</para></listitem>
+      <listitem><para>Character data contained in element <literal>subject</literal> 
+        are used as the message subject.</para></listitem>
+      <listitem><para>Character data contained in element <literal>text</literal> 
+        are used as the plain text content of the message.</para></listitem>
+      <listitem><para>Nodes contained in element <literal>html</literal>
+        are used as the HTML content of the message.</para></listitem>
+      <listitem><para>Attachments can be specified as absolute URLs,
+        classpath resources or local files.</para></listitem>
+      </orderedlist>
+      <para>Note that every section of the template is amenable to expression evaluation.</para>
+    </section>
+    <para>For complex emails or custom generation of attachments, see: <link 
+      linkend="customemails">Extension Points: Custom Emails</link>.</para>
+  </section>
+
+  <section id="mailtemplates">
+    <title>Templates</title>
+    <para>Mail templates are available to externalize commonly used messages from process definitions.
+      Templates are placed in the process-engine-context section of your configuration file. All elements
+      available to inline templates, as described in the <link linkend="defaultmailproducer">previous
+      section</link> are available to external templates. Consider the fragment below.</para>
+    <programlisting><![CDATA[<jbpm-configuration>
+<process-engine-context>
+  <mail-template name="rectify-template">
+    <!-- same elements as inline template -->
+  </mail-template>
+</process-engine-context>
+</jbpm-configuration>]]></programlisting>
+    <para>Each template must have an unique name. Mail activities may reference the template
+      through the <literal>template</literal> attribute, as follows.</para>
+    <programlisting><![CDATA[<mail name="rectify" template="rectify-template />]]></programlisting>
+  </section>
+
+  <section id="mailservers">
+    <title>Servers</title>
+    <para>Mail servers are declared in the configuration file. The <literal>mail-server</literal>
+      element describes an SMTP mail server capable of sending email messages.
+      Because jBPM uses JavaMail to send mail, all properties supported by JavaMail are also
+      exposed to jBPM.  Within the <literal>session-properties</literal> child element, 
+      the SMTP properties must be provided as shown in the example below.</para>
+    <para>See the Sun JavaMail API for more information on supported properties:
+      <ulink url="http://java.sun.com/products/javamail/javadocs/com/sun/mail/smtp/package-summary.html">
+      Sun SMTP Properties</ulink>.</para>
+    <programlisting><![CDATA[<jbpm-configuration>
+<transaction-context>
+  <mail-session>
+    <mail-server>
+      <session-properties>
+        <property name="mail.smtp.host" value="localhost" />
+        <property name="mail.smtp.port" value="2525" />
+        <property name="mail.from" value="noreply at jbpm.org" />
+      </session-properties>
+    </mail-server>
+  </mail-session>
+</transaction-context>
+</jbpm-configuration>]]></programlisting>
+    <para>If the "From" attribute is not present in an outgoing message, the value of the 
+      <literal>mail.from</literal> property will be used instead.</para>
+      
+    <section id="multiplemailservers">
+      <title>Multiple Servers</title>
+      <para>Multiple SMTP server support has been added to jBPM 4 to accommodate a wider
+        variety of organizational server structures. For example, this is useful for companies
+        that have both internal and external SMTP servers.</para>
+      <para>To setup multiple SMTP mail servers, declare multiple mail servers within the 
+        configuration file, as described below. The tag <literal>address-filter</literal> exists
+        to define which domains are serviced by each mail server. The address filter consists
+        of regular expressions that determine whether an address will be processed by a given
+        server.</para>
+      <para>See the Sun Pattern API for more information on supported regular expressions:
+        <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html">
+        Sun Regex Patterns</ulink>.</para>
+      <programlisting><![CDATA[<jbpm-configuration>
+<transaction-context>
+  <mail-session>
+    <mail-server>
+      <address-filter>
+        <include>.+ at jbpm.org</include>
+      </address-filter>
+      <session-properties>
+        <property name="mail.smtp.host" value="int.smtp.jbpm.org" />
+        <property name="mail.from" value="noreply at jbpm.org" />
+      </session-properties>
+    </mail-server>
+    <mail-server>
+      <address-filter>
+        <exclude>.+ at jbpm.org</exclude>
+      </address-filter>
+      <session-properties>
+        <property name="mail.smtp.host" value="ext.smtp.jbpm.org" />
+        <property name="mail.from" value="noreply at jbpm.org" />
+      </session-properties>
+    </mail-server>
+  </mail-session>
+</transaction-context>
+</jbpm-configuration>]]></programlisting>
+    <para>Address filters follow the logic below to accept an address.</para>
+    <itemizedlist>
+      <listitem><para>Address is accepted if it is <emphasis>included</emphasis> and
+        <emphasis>not excluded</emphasis>.</para></listitem>
+      <listitem><para>Absence of includes implies the address is 
+        <emphasis>included</emphasis>.</para></listitem>
+      <listitem><para>Absence of excludes implies the address is 
+        <emphasis>not excluded</emphasis>.</para></listitem>
+    </itemizedlist>
+    </section>
+  </section>
+
+  <section id="extensibility">
+    <title>Extension Points</title>
+
+    <section id="customproducers">
+      <title>Custom Producers</title>
+      <para>jBPM 4 allows the creation of your own Mail Producers to address an organization's
+        specific email needs.  To do so, users must implement the 
+        <literal>org.jbpm.pvm.internal.email.spi.MailProducer</literal> interface.  The method
+        <literal>produce</literal> will return one or more <literal>Message</literal> objects,
+        which will be sent through the <literal>MailSession</literal>.</para>
+    
+      <section id="custom attachments">
+        <title>Example: Custom Attachments</title>
+        <para>Generation of custom attachments at runtime can be easily implemented in jBPM 4.
+          By extending the default mail producer, or implementing your own with the
+          <literal>MailProducer</literal> interface, attachments can be generated and
+          added to email messages at runtime.</para>
+        <para>The following is an example of how to extend <literal>MailProducerImpl</literal>
+           to add an extra attachment to every outgoing mail.</para>
+        <programlisting><![CDATA[public class CustomMailProducer extends MailProducerImpl {
+
+  protected void addAttachments(Execution execution, Multipart multipart) {
+    // have default mail producer create attachments from template
+    super.addAttachments(execution, multipart);
+
+    // create a body part to carry the content
+    BodyPart attachmentPart = new MimeBodyPart();
+
+    // set content provided by an arbitrary data handler
+    attachmentPart.setDataHandler(...);
+
+    // attach content
+    multipart.addBodyPart(attachmentPart);
+  }
+}]]></programlisting>
+      </section>
+    </section>
+  
+  </section>
+  
+</chapter>
\ No newline at end of file

Deleted: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch11-SoftwareLogging.xml
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch11-SoftwareLogging.xml	2009-07-03 11:46:43 UTC (rev 5214)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch11-SoftwareLogging.xml	2009-07-03 12:21:36 UTC (rev 5215)
@@ -1,99 +0,0 @@
-<chapter id="softwarelogging">
-  <title>Software logging</title>
-
-  <section>
-    <title>Configuration</title>
-    <para>PVM can use JDK logging (java.util.logging) or log4j. When the first message is 
-    logged, PVM logging will make the selection with following procedure:
-    <orderedlist>
-      <listitem>If a <literal>logging.properties</literal> resource is found 
-      on the classpath (using the context classloader), then JDK logging will 
-      be used and that file will be used to initialize the JDK logging.
-      </listitem>
-      <listitem>If log4j is found on the classpath, then log4j will be used.
-      The check for log4j will be done by checking availability of class 
-      <literal>org.apache.log4j.LogManager</literal> with the context classloader.
-      </listitem>
-      <listitem>If none of the above, JDK logging will be used.</listitem>
-    </orderedlist>
-    </para>
-  </section>
-
-  <section>
-    <title>Categories</title>
-    <para>The PVM classes use their class name as the category for the logger.
-    </para>
-    <para>To have a basic understanding of what the PVM classes are doing, 
-    turning on the <literal>debug</literal> level is great.  Level 
-    <literal>trace</literal> might be spitting out too much for that 
-    purpose. 
-    </para>
-  </section>
-  
-  <section>
-    <title>JDK logging</title>
-    <para>In JDK logging, <literal>debug</literal>maps to <literal>fine</literal> 
-    and <literal>trace</literal> maps to <literal>finest</literal>. 
-    Level <literal>finer</literal> is not used.
-    </para>
-    <para><literal>org.jbpm.pvm.internal.log.LogFormatter</literal> is part of 
-    the pvm library and it can create a nice one-line output for log messages.
-    It also has a neat feature that creates a unique indentation per thread.
-    To configure it, this is a typical <literal>logging.properties</literal>
-    </para>
-    <programlisting>handlers = java.util.logging.ConsoleHandler
-java.util.logging.ConsoleHandler.level = FINEST
-java.util.logging.ConsoleHandler.formatter = org.jbpm.pvm.internal.log.LogFormatter
-
-# For example, set the com.xyz.foo logger to only log SEVERE messages:
-# com.xyz.foo.level = SEVERE
-
-.level = SEVERE
-org.jbpm.level=FINE
-org.jbpm.tx.level=FINE
-org.jbpm.pvm.internal.wire.level=FINE</programlisting>
-
-<!-- 
-    <para>For production usage, jBPM also includes an error triggered log handler.  This is 
-    a log handler that will only keep the most recent log messages in 
-    memory and these will only be flushed to a file in case an error occurs.
-    </para>
-    <para>to configure it, add <literal>org.jbpm.util.ErrorTriggeredFileHandler</literal>
-    to the handlers in the logging properties like this:
-    </para>
-    <programlisting>handlers = java.util.logging.ConsoleHandler org.jbpm.util.ErrorTriggeredFileHandler</programlisting>
-    <para>Next snippet shows how in the same logging.properties, the error 
-    triggered file handler can be configured.  The given values are the default 
-    values.
-    </para>
-    <programlisting>org.jbpm.util.ErrorTriggeredFileHandler.size = 500
-org.jbpm.util.ErrorTriggeredFileHandler.push = SEVERE
-org.jbpm.util.ErrorTriggeredFileHandler.pattern = %h/jbpm%u.log</programlisting>
-    <para>Alternatively to using the org.jbpm.util.ErrorTriggeredFileHandler, the 
-    JDK handlers FileHandler and MemoryHandler can used in combination to get 
-    similar results with a bit more configuration.
-    </para>
-
--->    
-  </section>
-
-  <section>
-    <title>Debugging persistence</title>
-    <para>When testing the persistence, following logging configurations can be 
-    valuable.  Category <literal>org.hibernate.SQL</literal> shows the SQL statement that is executed 
-    and category <literal>org.hibernate.type</literal> shows the values of the parameters that are 
-    set in the queries. 
-    </para>
-    <programlisting>org.hibernate.SQL.level=FINEST
-org.hibernate.type.level=FINEST</programlisting>
-    <para>And in case you get a failed batch as a cause in a hibernate exception,
-    you might want to set the batch size to 0 like this in the hibernate properties:
-    </para>
-    <programlisting>hibernate.jdbc.batch_size = 0</programlisting>
-    <para>Also in the hibernate properties, the following properties allow for 
-    detailed logs of the SQL that hibernate spits out:</para>
-    <programlisting>hibernate.show_sql = true
-hibernate.format_sql = true
-hibernate.use_sql_comments = true</programlisting>
-  </section>
-</chapter>  
\ No newline at end of file

Deleted: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch12-History.xml
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch12-History.xml	2009-07-03 11:46:43 UTC (rev 5214)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch12-History.xml	2009-07-03 12:21:36 UTC (rev 5215)
@@ -1,42 +0,0 @@
-<chapter id="history">
-  <title>History</title>
-
-  <section id="overview">
-    <title>Overview</title>
-    
-    <para>HistoryEvents are fired during process execution.
-    </para>
-
-    <para>We maintain history information on 2 levels: process instance and activity instance.
-    </para>
-
-    <para>Process instance start and process instance end generate history events are fired directly 
-    from within the implementation.
-    </para>
-
-    <para>ActivityBehaviour implementations are responsible for calling the historyXxx methods that 
-    are exposed on the ActivityExecution
-    </para>
-
-    <para>All the HistoryEvents are delegated to a HistorySession.  The default HistorySessionImpl 
-    will invoke the process() method on the history events themselves.
-    </para>
-
-    <para>The HistoryEvents are temporary events.  In the process method, they build up the information 
-    in the history model.  There is a HistoryProcessInstance and there is a whole class hierarchy starting with HistoryActivityInstance.   
-    </para>
-
-    <para>In the HistoryEvent.process methods, the history events create model entities or merge 
-    information into the model entities.  For instance, a ProcessInstanceStart history event will 
-    create a HistoryProcessInstance entity/record.  And the ProcessInstanceEnd will set the endTime 
-    property in the existing HistoryProcessInstance entity/record.  
-    </para>
-
-    <para>Similar pattern for the activities.  But for automatic activities, there is an optimisation 
-    so that only 1 event is created and all the information is stored in one single insert (as all 
-    this happens inside 1 transaction).
-    </para>
-
-  </section>
-
-</chapter>
\ No newline at end of file

Copied: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch12-SoftwareLogging.xml (from rev 5210, jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch11-SoftwareLogging.xml)
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch12-SoftwareLogging.xml	                        (rev 0)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch12-SoftwareLogging.xml	2009-07-03 12:21:36 UTC (rev 5215)
@@ -0,0 +1,99 @@
+<chapter id="softwarelogging">
+  <title>Software logging</title>
+
+  <section>
+    <title>Configuration</title>
+    <para>PVM can use JDK logging (java.util.logging) or log4j. When the first message is 
+    logged, PVM logging will make the selection with following procedure:
+    <orderedlist>
+      <listitem>If a <literal>logging.properties</literal> resource is found 
+      on the classpath (using the context classloader), then JDK logging will 
+      be used and that file will be used to initialize the JDK logging.
+      </listitem>
+      <listitem>If log4j is found on the classpath, then log4j will be used.
+      The check for log4j will be done by checking availability of class 
+      <literal>org.apache.log4j.LogManager</literal> with the context classloader.
+      </listitem>
+      <listitem>If none of the above, JDK logging will be used.</listitem>
+    </orderedlist>
+    </para>
+  </section>
+
+  <section>
+    <title>Categories</title>
+    <para>The PVM classes use their class name as the category for the logger.
+    </para>
+    <para>To have a basic understanding of what the PVM classes are doing, 
+    turning on the <literal>debug</literal> level is great.  Level 
+    <literal>trace</literal> might be spitting out too much for that 
+    purpose. 
+    </para>
+  </section>
+  
+  <section>
+    <title>JDK logging</title>
+    <para>In JDK logging, <literal>debug</literal>maps to <literal>fine</literal> 
+    and <literal>trace</literal> maps to <literal>finest</literal>. 
+    Level <literal>finer</literal> is not used.
+    </para>
+    <para><literal>org.jbpm.pvm.internal.log.LogFormatter</literal> is part of 
+    the pvm library and it can create a nice one-line output for log messages.
+    It also has a neat feature that creates a unique indentation per thread.
+    To configure it, this is a typical <literal>logging.properties</literal>
+    </para>
+    <programlisting>handlers = java.util.logging.ConsoleHandler
+java.util.logging.ConsoleHandler.level = FINEST
+java.util.logging.ConsoleHandler.formatter = org.jbpm.pvm.internal.log.LogFormatter
+
+# For example, set the com.xyz.foo logger to only log SEVERE messages:
+# com.xyz.foo.level = SEVERE
+
+.level = SEVERE
+org.jbpm.level=FINE
+org.jbpm.tx.level=FINE
+org.jbpm.pvm.internal.wire.level=FINE</programlisting>
+
+<!-- 
+    <para>For production usage, jBPM also includes an error triggered log handler.  This is 
+    a log handler that will only keep the most recent log messages in 
+    memory and these will only be flushed to a file in case an error occurs.
+    </para>
+    <para>to configure it, add <literal>org.jbpm.util.ErrorTriggeredFileHandler</literal>
+    to the handlers in the logging properties like this:
+    </para>
+    <programlisting>handlers = java.util.logging.ConsoleHandler org.jbpm.util.ErrorTriggeredFileHandler</programlisting>
+    <para>Next snippet shows how in the same logging.properties, the error 
+    triggered file handler can be configured.  The given values are the default 
+    values.
+    </para>
+    <programlisting>org.jbpm.util.ErrorTriggeredFileHandler.size = 500
+org.jbpm.util.ErrorTriggeredFileHandler.push = SEVERE
+org.jbpm.util.ErrorTriggeredFileHandler.pattern = %h/jbpm%u.log</programlisting>
+    <para>Alternatively to using the org.jbpm.util.ErrorTriggeredFileHandler, the 
+    JDK handlers FileHandler and MemoryHandler can used in combination to get 
+    similar results with a bit more configuration.
+    </para>
+
+-->    
+  </section>
+
+  <section>
+    <title>Debugging persistence</title>
+    <para>When testing the persistence, following logging configurations can be 
+    valuable.  Category <literal>org.hibernate.SQL</literal> shows the SQL statement that is executed 
+    and category <literal>org.hibernate.type</literal> shows the values of the parameters that are 
+    set in the queries. 
+    </para>
+    <programlisting>org.hibernate.SQL.level=FINEST
+org.hibernate.type.level=FINEST</programlisting>
+    <para>And in case you get a failed batch as a cause in a hibernate exception,
+    you might want to set the batch size to 0 like this in the hibernate properties:
+    </para>
+    <programlisting>hibernate.jdbc.batch_size = 0</programlisting>
+    <para>Also in the hibernate properties, the following properties allow for 
+    detailed logs of the SQL that hibernate spits out:</para>
+    <programlisting>hibernate.show_sql = true
+hibernate.format_sql = true
+hibernate.use_sql_comments = true</programlisting>
+  </section>
+</chapter>  
\ No newline at end of file

Copied: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch13-History.xml (from rev 5210, jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch12-History.xml)
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch13-History.xml	                        (rev 0)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch13-History.xml	2009-07-03 12:21:36 UTC (rev 5215)
@@ -0,0 +1,42 @@
+<chapter id="history">
+  <title>History</title>
+
+  <section id="overview">
+    <title>Overview</title>
+    
+    <para>HistoryEvents are fired during process execution.
+    </para>
+
+    <para>We maintain history information on 2 levels: process instance and activity instance.
+    </para>
+
+    <para>Process instance start and process instance end generate history events are fired directly 
+    from within the implementation.
+    </para>
+
+    <para>ActivityBehaviour implementations are responsible for calling the historyXxx methods that 
+    are exposed on the ActivityExecution
+    </para>
+
+    <para>All the HistoryEvents are delegated to a HistorySession.  The default HistorySessionImpl 
+    will invoke the process() method on the history events themselves.
+    </para>
+
+    <para>The HistoryEvents are temporary events.  In the process method, they build up the information 
+    in the history model.  There is a HistoryProcessInstance and there is a whole class hierarchy starting with HistoryActivityInstance.   
+    </para>
+
+    <para>In the HistoryEvent.process methods, the history events create model entities or merge 
+    information into the model entities.  For instance, a ProcessInstanceStart history event will 
+    create a HistoryProcessInstance entity/record.  And the ProcessInstanceEnd will set the endTime 
+    property in the existing HistoryProcessInstance entity/record.  
+    </para>
+
+    <para>Similar pattern for the activities.  But for automatic activities, there is an optimisation 
+    so that only 1 event is created and all the information is stored in one single insert (as all 
+    this happens inside 1 transaction).
+    </para>
+
+  </section>
+
+</chapter>
\ No newline at end of file

Deleted: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch13-JBossIntegration.xml
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch13-JBossIntegration.xml	2009-07-03 11:46:43 UTC (rev 5214)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch13-JBossIntegration.xml	2009-07-03 12:21:36 UTC (rev 5215)
@@ -1,140 +0,0 @@
-<chapter id="jbossintegration">
-  <title>JBoss Integration</title>
-
-  <para>
-    jBPM provides integration with JBoss 4.2.x and JBoss 5.0.0.GA.
-    As part of the <link linkend="runningtheinstaller">installation</link>, the ProcessEngine and a deployer for jBPM archives
-    will be installed as a JBoss service.
-  </para>
-
-  <para>
-    After a successful installation you should see that the ProcessEngine
-    has been started and bound to JNDI:
-  </para>
-
-  <programlisting>
-    [...]
-    14:12:09,301 INFO  [JBPMService] jBPM 4 - Integration JBoss 4
-    14:12:09,301 INFO  [JBPMService] 4.0.0.Beta1
-    14:12:09,301 INFO  [JBPMService] ProcessEngine bound to: java:/ProcessEngine
-  </programlisting>
-
-  <section>
-    <title>Packaging process archives</title>
-    <para>
-      When jBPM is deployed on a JBoss instance, process deployments are treated like
-      any other deployment artifact (i.e. *.war, *.ear) and processed by the JBPMDeployer.
-      In order to deploy a process archive simply create a *.jpdl archive (zip file) that contains
-      the process definition (*.jpdl.xml) and all required resources to execute the process (i.e. classes, property files):
-    </para>
-    <programlisting>
-      Bonanova:Desktop hbraun$ jar -tf OrderProcess.jpdl
-
-      META-INF/MANIFEST.MF
-      OrderProcess.jpdl.xml
-      org/mycompany/order/*.class
-    </programlisting>
-  </section>
-
-  <section>
-    <title>Deploying processes archives to a JBoss instance</title>
-    <para>
-      In order to deploy a process archive simply copy it to $JBOSS_HOME/server/&lt;config>/deploy:
-    </para>
-
-    <programlisting>
-      (1) cp OrderProcess.jpdl $JBOSS_HOME/server/default/deploy
-
-      (2) less $JBOSS_HOME/server/default/log
-      [...]
-      2009-04-08 14:12:21,947 INFO  [org.jbpm.integration.jboss4.JBPMDeployer]
-      Deploy file:/Users/hbraun/dev/prj/jboss/tags/JBoss_4_2_2_GA
-      /build/output/jboss-4.2.2.GA/server/default/deploy/OrderProcess.jpdl
-    </programlisting>
-
-    <para>
-      In order to remove a process simply remove the process archive from the deploy directory.
-    </para>
-  </section>
-
-  <section>
-    <title>Process deployments and versioning</title>
-    <para>
-      TBD: A prelimenary explanation cn be found <ulink url="http://relative-order.blogspot.com/2009/03/rfc-process-deployment-use-cases.html">here</ulink>
-    </para>
-  </section>
-
-  <section>
-    <title>ProcessEngine and J2EE/JEE programming models</title>
-    <para>
-      As described above the ProcessEngine will be installed as JBoss service and bound to JNDI.
-      This means that any EE component (i.e. servlet, ejb) can access it doing a JNDI lookup:
-    </para>
-
-    <programlisting>
-    private ProcessEngine processEngine;
-    [...]
-
-    try
-    {
-      InitialContext ctx = new InitialContext();
-      this.processEngine = (ProcessEngine)ctx.lookup("java:/ProcessEngine");
-    }
-    catch (Exception e)
-    {
-      throw new RuntimeException("Failed to lookup process engine");
-    }
-    </programlisting>
-
-    <para>
-      Once you obtained an instance of the ProcessEngine you can invoke on it
-      as described in <link linkend="services">chapter services</link>
-    </para>
-
-    <programlisting>
-    UserTransaction tx = (UserTransaction)ctx.lookup("UserTransaction");        (1)
-    Environment env = ((EnvironmentFactory)processEngine).openEnvironment();
-
-    try
-    {
-
-      ExecutionService execService = (ExecutionService)
-              this.processEngine.get(ExecutionService.class);
-
-      // begin transaction
-      tx.begin();
-
-      // invoke on process engine
-      executionService.signalExecutionById("ICL.82436");
-
-      // commit transaction
-      tx.commit();
-      
-    }
-    catch (Exception e)
-    {
-      if(tx!=null)
-      {
-        try
-        {
-          tx.rollback();
-        }
-        catch (SystemException e1) {}
-      }
-
-      throw new RuntimeException("...", e);
-
-    }
-    finally
-    {
-      env.close();
-    }
-    </programlisting>
-
-    <para>
-      (1) Wrapping the call in a UserTransaction is not necessary if the invocation comes a
-      CMT component, i.e. an EJB.
-    </para>
-  </section>
-
-</chapter>

Copied: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch14-JBossIntegration.xml (from rev 5210, jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch13-JBossIntegration.xml)
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch14-JBossIntegration.xml	                        (rev 0)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch14-JBossIntegration.xml	2009-07-03 12:21:36 UTC (rev 5215)
@@ -0,0 +1,140 @@
+<chapter id="jbossintegration">
+  <title>JBoss Integration</title>
+
+  <para>
+    jBPM provides integration with JBoss 4.2.x and JBoss 5.0.0.GA.
+    As part of the <link linkend="runningtheinstaller">installation</link>, the ProcessEngine and a deployer for jBPM archives
+    will be installed as a JBoss service.
+  </para>
+
+  <para>
+    After a successful installation you should see that the ProcessEngine
+    has been started and bound to JNDI:
+  </para>
+
+  <programlisting>
+    [...]
+    14:12:09,301 INFO  [JBPMService] jBPM 4 - Integration JBoss 4
+    14:12:09,301 INFO  [JBPMService] 4.0.0.Beta1
+    14:12:09,301 INFO  [JBPMService] ProcessEngine bound to: java:/ProcessEngine
+  </programlisting>
+
+  <section>
+    <title>Packaging process archives</title>
+    <para>
+      When jBPM is deployed on a JBoss instance, process deployments are treated like
+      any other deployment artifact (i.e. *.war, *.ear) and processed by the JBPMDeployer.
+      In order to deploy a process archive simply create a *.jpdl archive (zip file) that contains
+      the process definition (*.jpdl.xml) and all required resources to execute the process (i.e. classes, property files):
+    </para>
+    <programlisting>
+      Bonanova:Desktop hbraun$ jar -tf OrderProcess.jpdl
+
+      META-INF/MANIFEST.MF
+      OrderProcess.jpdl.xml
+      org/mycompany/order/*.class
+    </programlisting>
+  </section>
+
+  <section>
+    <title>Deploying processes archives to a JBoss instance</title>
+    <para>
+      In order to deploy a process archive simply copy it to $JBOSS_HOME/server/&lt;config>/deploy:
+    </para>
+
+    <programlisting>
+      (1) cp OrderProcess.jpdl $JBOSS_HOME/server/default/deploy
+
+      (2) less $JBOSS_HOME/server/default/log
+      [...]
+      2009-04-08 14:12:21,947 INFO  [org.jbpm.integration.jboss4.JBPMDeployer]
+      Deploy file:/Users/hbraun/dev/prj/jboss/tags/JBoss_4_2_2_GA
+      /build/output/jboss-4.2.2.GA/server/default/deploy/OrderProcess.jpdl
+    </programlisting>
+
+    <para>
+      In order to remove a process simply remove the process archive from the deploy directory.
+    </para>
+  </section>
+
+  <section>
+    <title>Process deployments and versioning</title>
+    <para>
+      TBD: A prelimenary explanation cn be found <ulink url="http://relative-order.blogspot.com/2009/03/rfc-process-deployment-use-cases.html">here</ulink>
+    </para>
+  </section>
+
+  <section>
+    <title>ProcessEngine and J2EE/JEE programming models</title>
+    <para>
+      As described above the ProcessEngine will be installed as JBoss service and bound to JNDI.
+      This means that any EE component (i.e. servlet, ejb) can access it doing a JNDI lookup:
+    </para>
+
+    <programlisting>
+    private ProcessEngine processEngine;
+    [...]
+
+    try
+    {
+      InitialContext ctx = new InitialContext();
+      this.processEngine = (ProcessEngine)ctx.lookup("java:/ProcessEngine");
+    }
+    catch (Exception e)
+    {
+      throw new RuntimeException("Failed to lookup process engine");
+    }
+    </programlisting>
+
+    <para>
+      Once you obtained an instance of the ProcessEngine you can invoke on it
+      as described in <link linkend="services">chapter services</link>
+    </para>
+
+    <programlisting>
+    UserTransaction tx = (UserTransaction)ctx.lookup("UserTransaction");        (1)
+    Environment env = ((EnvironmentFactory)processEngine).openEnvironment();
+
+    try
+    {
+
+      ExecutionService execService = (ExecutionService)
+              this.processEngine.get(ExecutionService.class);
+
+      // begin transaction
+      tx.begin();
+
+      // invoke on process engine
+      executionService.signalExecutionById("ICL.82436");
+
+      // commit transaction
+      tx.commit();
+      
+    }
+    catch (Exception e)
+    {
+      if(tx!=null)
+      {
+        try
+        {
+          tx.rollback();
+        }
+        catch (SystemException e1) {}
+      }
+
+      throw new RuntimeException("...", e);
+
+    }
+    finally
+    {
+      env.close();
+    }
+    </programlisting>
+
+    <para>
+      (1) Wrapping the call in a UserTransaction is not necessary if the invocation comes a
+      CMT component, i.e. an EJB.
+    </para>
+  </section>
+
+</chapter>

Deleted: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch14-SpringIntegration.xml
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch14-SpringIntegration.xml	2009-07-03 11:46:43 UTC (rev 5214)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch14-SpringIntegration.xml	2009-07-03 12:21:36 UTC (rev 5215)
@@ -1,137 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<chapter id="springIntegration">
-  <title>Spring Integration</title>
-  
-  <para>
-  	The embeddability of the jBPM engine in different environments has always
-  	been one of its core strengths, but often extra libraries to do the integration
-  	were required. Since jBPM4 however, it is now possible to natively
-  	integrate jBPM with <ulink url="http://www.springsource.org/about">Spring</ulink>.
-  	This section will explain which steps are required for such an integration.
-  </para>
-  
-  <para>
-  	The Spring integration has started out as a community effort by
-  	<ulink url="http://www.inze.be/andries/">Andries Inz&#233;</ulink>.
-  	Do note that Spring integration currently is in 'incubation', before
-  	it is moved to the user guide.
-  </para>
-
-  <section id="spring_overview">
-    <title>Overview</title>
-    <para>
-		The default jBPM behaviour is to open a transaction for each operation
-		that is called on the service API. In a typical Spring setup, applications are 
-		accessed from the web tier and enter a transactional boundary by invoking
-		operations on service beans. These service beans will then access the jBPM services. 
-		All these operations run typically in a single transaction (ie one transaction
-		per request from the browser), which invalidates the standard jBPM 
-		transaction handling approach. Instead of starting and committing
-		a transaction for every service operation, the existing transaction
-		should be used (or a new one started if none exists).
-    </para>
-  </section>
-  
-  <section id="spring_configuration">
-  	<title>Configuration</title>
-    <para>
-		Replace the standard-transaction-interceptor with the 
-		spring-transaction-interceptor. The hibernate session needs the attribute current=”true”. 
-		This forces jBPM to search for the current session, 
-		which will be provided by Spring.
-		<programlisting>
-	&lt;process-engine-context&gt;
-	    &lt;command-service&gt;
-	      <emphasis role="bold">&lt;spring-transaction-interceptor /&gt;</emphasis>
-	      ...
-	    &lt;/command-service&gt;
-	    ...
-	&lt;/process-engine-context&gt;
-	&lt;transaction-context&gt;
-	    ...
-		<emphasis role="bold">&lt;hibernate-session current=&quot;true&quot;/&gt;</emphasis>
-	&lt;/transaction-context&gt;
-		</programlisting>
-	</para>
-	
-	<para>
-		The Spring integration provides a special context, which is added to
-		the set of context where the jBPM engine will look for beans.
-		Using this SpringContext, it is now possible to retrieve beans from the 
-		Spring Application Context. For the Spring context to be known, a 
-		SpringConfiguration must be created. This class extends the JbpmConfiguration 
-		but will add itself as a context. The single constructor take the location of the jBPM configuration.
-		
-		<programlisting>
-	&lt;bean id=&quot;jbpmConfiguration&quot; class=&quot;org.jbpm.pvm.internal.cfg.SpringConfiguration&quot;&gt;
-   		&lt;constructor-arg value=&quot;be/inze/spring/demo/jbpm.cfg.xml&quot; /&gt;
-	&lt;/bean&gt;
-		</programlisting>
-	</para>	
-	
-	<para>
-		The jBPM services can also be defined in the Spring applicationContext, as following:
-		<programlisting>
-&lt;bean id=&quot;processEngine&quot; factory-bean=&quot;jbpmConfiguration&quot; factory-method=&quot;buildProcessEngine&quot; /&gt;
-&lt;bean id=&quot;repositoryService&quot; factory-bean=&quot;processEngine&quot; factory-method=&quot;getRepositoryService&quot; /&gt;
-&lt;bean id=&quot;executionService&quot; factory-bean=&quot;processEngine&quot; factory-method=&quot;getExecutionService&quot; /&gt;
-		</programlisting>
-	</para>
-
-	<para>
-		For accessing Spring beans from withing a process, we need to register 
-		the Spring applicationContext with the scripting-manager.
-		
-		<programlisting>
-	&lt;script-manager default-expression-language=&quot;juel&quot;
-	 default-script-language=&quot;juel&quot;
-	 read-contexts=&quot;execution, environment, process-engine, <emphasis role="bold">spring</emphasis>&quot;
-	 write-context=&quot;&quot;&gt;
-	 &lt;script-language name=&quot;juel&quot;
-	 factory=&quot;org.jbpm.pvm.internal.script.JuelScriptEngineFactory&quot; /&gt;
-	 &lt;/script-manager&gt;		
-		</programlisting>	
-    </para>
-  </section>
-  
-  <section id="spring_usage">
-  	<title>Usage</title>
-  	
-  	<para>
-  		The previous section already showed how the jBPM services can be made
-  		accessible for other Spring services. The other use case is calling
-  		Spring beans from within a process. This can be done by using
-  		an expression which resolves to the name of a Spring bean.
-  		
-  		<programlisting>
-&lt;java name=&quot;echo&quot; expr=&quot;#{echoService}&quot; method=&quot;sayHello&quot; &gt;
-    &lt;transition name=&quot;to accept&quot; to=&quot;join1&quot;/&gt;
- &lt;/java&gt;
-  		</programlisting>
-  		
-  		The scripting engine will look into all contexts from the bean named echoService. 
-  		If you configured the ScriptManager as above, Spring will be the last context to search for.
-  		You can also add a Spring bean to the Spring Application context
-  		(eg IdentitySessionImpl with id <emphasis role="italic">identitySession</emphasis>)
-  		and use it in the jBPM config (eg by adding	&lt;env class=&quot;identitySession&quot; /&gt;)
-  	</para>
-  	
-  </section>
-  
-  <section id="spring_testing">
-  	<title>Testing</title>
-  	
-  	<para>
-  		Use the <emphasis role="bold">AbstractTransactionalJbpmTestCase</emphasis> 
-  		to test a process in isolation (ie without impact on the database).
-  		This class extends from
-  		the <emphasis role="italic">AbstractTransactionalDataSourceSpringContextTests</emphasis>
-  		class, which means that testing a process comes down to exactly the same
-  		approach as testing a DAO.
-  	</para>
-  
-  </section>
-    
-    
-  
-</chapter>

Deleted: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch15-Jpdl3Migration.xml
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch15-Jpdl3Migration.xml	2009-07-03 11:46:43 UTC (rev 5214)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch15-Jpdl3Migration.xml	2009-07-03 12:21:36 UTC (rev 5215)
@@ -1,84 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<chapter id="jpdl3Migration">
-  <title>JPDL3 migration</title>
-  
-  <para>
-	In many cases, a lot of work has been put in the design of JPDL3 process
-	definitions. To avoid a complete manual translation of these processes to the
-	JPDL4 format, the jBPM distribution contains a subdirectory called
-	<emphasis role="bold">migration</emphasis>, which contains a command-line
-	tool for converting JPDL3 process definition files to JPDL process XML files.
-  </para>
-  
-  <para>
-	The tool itself uses only dom4j to do the translation between
-	the two formats and should be easy extensible (the source code is also in
-	the same directory). The design of the tool is deliberately kept very simple
-	(ie most of the logic can be found in the <emphasis role="bold">Jpdl3Converter</emphasis> class).
-	Note that this tool is experimental and tested only a small set of JPDL3 
-	process files. 
-  </para>
-
-  <section id="migration_overview">
-    <title>Overview</title>
-    <para>
-		The jPDL Conversion tool takes a jpdl3 process file as input, and 
-		converts it to a jpdl4 process file.
-	</para>
-	<para>		
-		Syntax:
-		<programlisting>java org.jbpm.jpdl.internal.convert.JpdlConverterTool -v -o &lt;outputfile&gt; &lt;processfile&gt;</programlisting>
-	</para>
-  </section>
-  
-  <section id="migration_arguments">
-  	<title>Arguments</title>
-  	<itemizedlist>
-	    <listitem>
-	      <emphasis role="bold">-v (verbose):</emphasis> The tool will print the detail 
-	      messages while converting the process file. When this argument is used,
-	       it will also print the error stacktrace if exceptions are thrown.
-	    </listitem>
-	    <listitem>
-	      <emphasis role="bold">-o (output)</emphasis> Specifies the output file name.
-	      By default, the tool will generate a file name ending in 'converted.jpdl.xml' 
-	      using as a base file name the name derived from the input process file.
-	      The output-filename can be an absolute file name path or a relative file name path.
-	    </listitem>
-	  </itemizedlist>
-  </section>
-  
-  <section id="migration_examples">
-  	<title>Usage examples</title>
-  	<programlisting>
-  		java -jar jpdl-migration-XX.jar simple.jpdl.xml
-		java -jar jpdl-migration-XX.jar -v simple.jpdl.xml
-		java -jar jpdl-migration-XX.jar -o /home/scott/simple.converted.xml simple.jpdl.xml   
-  	</programlisting>
-  </section>
-  
-  <section id="migration_integration">
-  	<title>Advanced</title>
-  	<para>
-  		The conversion tool can easily be integrated with regular Java code
-  		(or with Maven or Ant). The following code example shows how to call the
-  		internal api to convert the process file:
-  		<programlisting>
-	URL url = new URL(&quot;simple.jpdl&quot;);
-	Jpdl3Converter jpdlConverter = new Jpdl3Converter(url);
-	Document jpdl4Doc = jpdlConverter.readAndConvert();
-
-	for (Problem problem : jpdlConverter.problems) {
-	   //do something to handle the problem
-	}
-
-	Writer fileWriter = new FileWriter(outputFile);
-	OutputFormat format = OutputFormat.createPrettyPrint();
-	XMLWriter writer = new XMLWriter( fileWriter, format );
-	writer.write(jpdl4Doc);
-	writer.close();
-  		</programlisting>
-  	</para>
-  </section>
-  
-</chapter>

Copied: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch15-SpringIntegration.xml (from rev 5210, jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch14-SpringIntegration.xml)
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch15-SpringIntegration.xml	                        (rev 0)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch15-SpringIntegration.xml	2009-07-03 12:21:36 UTC (rev 5215)
@@ -0,0 +1,137 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="springIntegration">
+  <title>Spring Integration</title>
+  
+  <para>
+  	The embeddability of the jBPM engine in different environments has always
+  	been one of its core strengths, but often extra libraries to do the integration
+  	were required. Since jBPM4 however, it is now possible to natively
+  	integrate jBPM with <ulink url="http://www.springsource.org/about">Spring</ulink>.
+  	This section will explain which steps are required for such an integration.
+  </para>
+  
+  <para>
+  	The Spring integration has started out as a community effort by
+  	<ulink url="http://www.inze.be/andries/">Andries Inz&#233;</ulink>.
+  	Do note that Spring integration currently is in 'incubation', before
+  	it is moved to the user guide.
+  </para>
+
+  <section id="spring_overview">
+    <title>Overview</title>
+    <para>
+		The default jBPM behaviour is to open a transaction for each operation
+		that is called on the service API. In a typical Spring setup, applications are 
+		accessed from the web tier and enter a transactional boundary by invoking
+		operations on service beans. These service beans will then access the jBPM services. 
+		All these operations run typically in a single transaction (ie one transaction
+		per request from the browser), which invalidates the standard jBPM 
+		transaction handling approach. Instead of starting and committing
+		a transaction for every service operation, the existing transaction
+		should be used (or a new one started if none exists).
+    </para>
+  </section>
+  
+  <section id="spring_configuration">
+  	<title>Configuration</title>
+    <para>
+		Replace the standard-transaction-interceptor with the 
+		spring-transaction-interceptor. The hibernate session needs the attribute current=”true”. 
+		This forces jBPM to search for the current session, 
+		which will be provided by Spring.
+		<programlisting>
+	&lt;process-engine-context&gt;
+	    &lt;command-service&gt;
+	      <emphasis role="bold">&lt;spring-transaction-interceptor /&gt;</emphasis>
+	      ...
+	    &lt;/command-service&gt;
+	    ...
+	&lt;/process-engine-context&gt;
+	&lt;transaction-context&gt;
+	    ...
+		<emphasis role="bold">&lt;hibernate-session current=&quot;true&quot;/&gt;</emphasis>
+	&lt;/transaction-context&gt;
+		</programlisting>
+	</para>
+	
+	<para>
+		The Spring integration provides a special context, which is added to
+		the set of context where the jBPM engine will look for beans.
+		Using this SpringContext, it is now possible to retrieve beans from the 
+		Spring Application Context. For the Spring context to be known, a 
+		SpringConfiguration must be created. This class extends the JbpmConfiguration 
+		but will add itself as a context. The single constructor take the location of the jBPM configuration.
+		
+		<programlisting>
+	&lt;bean id=&quot;jbpmConfiguration&quot; class=&quot;org.jbpm.pvm.internal.cfg.SpringConfiguration&quot;&gt;
+   		&lt;constructor-arg value=&quot;be/inze/spring/demo/jbpm.cfg.xml&quot; /&gt;
+	&lt;/bean&gt;
+		</programlisting>
+	</para>	
+	
+	<para>
+		The jBPM services can also be defined in the Spring applicationContext, as following:
+		<programlisting>
+&lt;bean id=&quot;processEngine&quot; factory-bean=&quot;jbpmConfiguration&quot; factory-method=&quot;buildProcessEngine&quot; /&gt;
+&lt;bean id=&quot;repositoryService&quot; factory-bean=&quot;processEngine&quot; factory-method=&quot;getRepositoryService&quot; /&gt;
+&lt;bean id=&quot;executionService&quot; factory-bean=&quot;processEngine&quot; factory-method=&quot;getExecutionService&quot; /&gt;
+		</programlisting>
+	</para>
+
+	<para>
+		For accessing Spring beans from withing a process, we need to register 
+		the Spring applicationContext with the scripting-manager.
+		
+		<programlisting>
+	&lt;script-manager default-expression-language=&quot;juel&quot;
+	 default-script-language=&quot;juel&quot;
+	 read-contexts=&quot;execution, environment, process-engine, <emphasis role="bold">spring</emphasis>&quot;
+	 write-context=&quot;&quot;&gt;
+	 &lt;script-language name=&quot;juel&quot;
+	 factory=&quot;org.jbpm.pvm.internal.script.JuelScriptEngineFactory&quot; /&gt;
+	 &lt;/script-manager&gt;		
+		</programlisting>	
+    </para>
+  </section>
+  
+  <section id="spring_usage">
+  	<title>Usage</title>
+  	
+  	<para>
+  		The previous section already showed how the jBPM services can be made
+  		accessible for other Spring services. The other use case is calling
+  		Spring beans from within a process. This can be done by using
+  		an expression which resolves to the name of a Spring bean.
+  		
+  		<programlisting>
+&lt;java name=&quot;echo&quot; expr=&quot;#{echoService}&quot; method=&quot;sayHello&quot; &gt;
+    &lt;transition name=&quot;to accept&quot; to=&quot;join1&quot;/&gt;
+ &lt;/java&gt;
+  		</programlisting>
+  		
+  		The scripting engine will look into all contexts from the bean named echoService. 
+  		If you configured the ScriptManager as above, Spring will be the last context to search for.
+  		You can also add a Spring bean to the Spring Application context
+  		(eg IdentitySessionImpl with id <emphasis role="italic">identitySession</emphasis>)
+  		and use it in the jBPM config (eg by adding	&lt;env class=&quot;identitySession&quot; /&gt;)
+  	</para>
+  	
+  </section>
+  
+  <section id="spring_testing">
+  	<title>Testing</title>
+  	
+  	<para>
+  		Use the <emphasis role="bold">AbstractTransactionalJbpmTestCase</emphasis> 
+  		to test a process in isolation (ie without impact on the database).
+  		This class extends from
+  		the <emphasis role="italic">AbstractTransactionalDataSourceSpringContextTests</emphasis>
+  		class, which means that testing a process comes down to exactly the same
+  		approach as testing a DAO.
+  	</para>
+  
+  </section>
+    
+    
+  
+</chapter>

Copied: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch16-Jpdl3Migration.xml (from rev 5210, jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch15-Jpdl3Migration.xml)
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch16-Jpdl3Migration.xml	                        (rev 0)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch16-Jpdl3Migration.xml	2009-07-03 12:21:36 UTC (rev 5215)
@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="jpdl3Migration">
+  <title>JPDL3 migration</title>
+  
+  <para>
+	In many cases, a lot of work has been put in the design of JPDL3 process
+	definitions. To avoid a complete manual translation of these processes to the
+	JPDL4 format, the jBPM distribution contains a subdirectory called
+	<emphasis role="bold">migration</emphasis>, which contains a command-line
+	tool for converting JPDL3 process definition files to JPDL process XML files.
+  </para>
+  
+  <para>
+	The tool itself uses only dom4j to do the translation between
+	the two formats and should be easy extensible (the source code is also in
+	the same directory). The design of the tool is deliberately kept very simple
+	(ie most of the logic can be found in the <emphasis role="bold">Jpdl3Converter</emphasis> class).
+	Note that this tool is experimental and tested only a small set of JPDL3 
+	process files. 
+  </para>
+
+  <section id="migration_overview">
+    <title>Overview</title>
+    <para>
+		The jPDL Conversion tool takes a jpdl3 process file as input, and 
+		converts it to a jpdl4 process file.
+	</para>
+	<para>		
+		Syntax:
+		<programlisting>java org.jbpm.jpdl.internal.convert.JpdlConverterTool -v -o &lt;outputfile&gt; &lt;processfile&gt;</programlisting>
+	</para>
+  </section>
+  
+  <section id="migration_arguments">
+  	<title>Arguments</title>
+  	<itemizedlist>
+	    <listitem>
+	      <emphasis role="bold">-v (verbose):</emphasis> The tool will print the detail 
+	      messages while converting the process file. When this argument is used,
+	       it will also print the error stacktrace if exceptions are thrown.
+	    </listitem>
+	    <listitem>
+	      <emphasis role="bold">-o (output)</emphasis> Specifies the output file name.
+	      By default, the tool will generate a file name ending in 'converted.jpdl.xml' 
+	      using as a base file name the name derived from the input process file.
+	      The output-filename can be an absolute file name path or a relative file name path.
+	    </listitem>
+	  </itemizedlist>
+  </section>
+  
+  <section id="migration_examples">
+  	<title>Usage examples</title>
+  	<programlisting>
+  		java -jar jpdl-migration-XX.jar simple.jpdl.xml
+		java -jar jpdl-migration-XX.jar -v simple.jpdl.xml
+		java -jar jpdl-migration-XX.jar -o /home/scott/simple.converted.xml simple.jpdl.xml   
+  	</programlisting>
+  </section>
+  
+  <section id="migration_integration">
+  	<title>Advanced</title>
+  	<para>
+  		The conversion tool can easily be integrated with regular Java code
+  		(or with Maven or Ant). The following code example shows how to call the
+  		internal api to convert the process file:
+  		<programlisting>
+	URL url = new URL(&quot;simple.jpdl&quot;);
+	Jpdl3Converter jpdlConverter = new Jpdl3Converter(url);
+	Document jpdl4Doc = jpdlConverter.readAndConvert();
+
+	for (Problem problem : jpdlConverter.problems) {
+	   //do something to handle the problem
+	}
+
+	Writer fileWriter = new FileWriter(outputFile);
+	OutputFormat format = OutputFormat.createPrettyPrint();
+	XMLWriter writer = new XMLWriter( fileWriter, format );
+	writer.write(jpdl4Doc);
+	writer.close();
+  		</programlisting>
+  	</para>
+  </section>
+  
+</chapter>

Modified: jbpm4/trunk/modules/userguide/src/main/docbook/en/master.xml
===================================================================
--- jbpm4/trunk/modules/userguide/src/main/docbook/en/master.xml	2009-07-03 11:46:43 UTC (rev 5214)
+++ jbpm4/trunk/modules/userguide/src/main/docbook/en/master.xml	2009-07-03 12:21:36 UTC (rev 5215)
@@ -10,7 +10,6 @@
   <!ENTITY ch07-Variables          SYSTEM "modules/ch07-Variables.xml">
   <!ENTITY ch08-Scripting          SYSTEM "modules/ch08-Scripting.xml">
   <!ENTITY ch09-Identity           SYSTEM "modules/ch09-Identity.xml">
-  <!ENTITY ch11-Emails             SYSTEM "modules/ch11-Emails.xml">
 ]>
 
 <book lang="en">
@@ -30,6 +29,5 @@
   &ch07-Variables;
   &ch08-Scripting;
   &ch09-Identity;
-  &ch11-Emails;
 
 </book>
\ No newline at end of file

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-03 11:46:43 UTC (rev 5214)
+++ jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch06-Jpdl.xml	2009-07-03 12:21:36 UTC (rev 5215)
@@ -1233,8 +1233,6 @@
      <notification/>
      <reminder duedate="2 days" repeat="1 day"/>
 </task>]]></programlisting>
-        <para>Refer to the <link linkend="mailsupport">mail chapter</link> for full details
-        on mail support.</para>
       </section>
     </section>
 
@@ -2313,8 +2311,44 @@
           </tbody>
         </tgroup>
       </table>
-      <para>Refer to the <link linkend="mailsupport">mail chapter</link> for full details
-        on mail support.</para>
+      
+      <para>
+      	Example usage:
+     	<programlisting>
+&lt;process name=&quot;InlineMail&quot; xmlns=&quot;http://jbpm.org/4.0/jpdl&quot;&gt;
+  &lt;start&gt;
+    &lt;transition to=&quot;send birthday reminder note&quot; /&gt;
+  &lt;/start&gt;
+  &lt;mail name=&quot;send birthday reminder note&quot;&gt;
+    &lt;to addresses=&quot;johnDoe at some-company.com&quot; /&gt;
+    &lt;subject&gt;Reminder: ${person} celebrates his birthday!&lt;/subject&gt;
+    &lt;text&gt;Do not forget: ${date} is the birthday of ${person} &lt;/text&gt;
+    &lt;transition to=&quot;end&quot; /&gt;
+  &lt;/mail&gt;
+  &lt;state name=&quot;end&quot;/&gt;
+&lt;/process&gt;     	
+     	</programlisting>
+      </para>
+      
+      <para>
+      	The examples in the distribution contain some processes using the mail
+      	activity. If you want to change the SMTP server, you can adjust the
+      	<emphasis role="bold">jbpm.mail.properties</emphasis> file, which is
+      	imported in the examples jBPM configuration file as follows:
+      	
+      	<programlisting>
+&lt;transaction-context&gt;
+   ...
+    &lt;mail-session&gt;
+      &lt;mail-server&gt;
+        &lt;session-properties resource=&quot;jbpm.mail.properties&quot; /&gt;
+      &lt;/mail-server&gt;
+    &lt;/mail-session&gt;
+&lt;/transaction-context&gt;
+      	</programlisting>
+      </para>
+      
+      <para>Refer to the Developers Guide for advanced mail configuration and usage.</para>
     </section>
 
   </section>




More information about the jbpm-commits mailing list