[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/<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/<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é</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>
- <process-engine-context>
- <command-service>
- <emphasis role="bold"><spring-transaction-interceptor /></emphasis>
- ...
- </command-service>
- ...
- </process-engine-context>
- <transaction-context>
- ...
- <emphasis role="bold"><hibernate-session current="true"/></emphasis>
- </transaction-context>
- </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>
- <bean id="jbpmConfiguration" class="org.jbpm.pvm.internal.cfg.SpringConfiguration">
- <constructor-arg value="be/inze/spring/demo/jbpm.cfg.xml" />
- </bean>
- </programlisting>
- </para>
-
- <para>
- The jBPM services can also be defined in the Spring applicationContext, as following:
- <programlisting>
-<bean id="processEngine" factory-bean="jbpmConfiguration" factory-method="buildProcessEngine" />
-<bean id="repositoryService" factory-bean="processEngine" factory-method="getRepositoryService" />
-<bean id="executionService" factory-bean="processEngine" factory-method="getExecutionService" />
- </programlisting>
- </para>
-
- <para>
- For accessing Spring beans from withing a process, we need to register
- the Spring applicationContext with the scripting-manager.
-
- <programlisting>
- <script-manager default-expression-language="juel"
- default-script-language="juel"
- read-contexts="execution, environment, process-engine, <emphasis role="bold">spring</emphasis>"
- write-context="">
- <script-language name="juel"
- factory="org.jbpm.pvm.internal.script.JuelScriptEngineFactory" />
- </script-manager>
- </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>
-<java name="echo" expr="#{echoService}" method="sayHello" >
- <transition name="to accept" to="join1"/>
- </java>
- </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 <env class="identitySession" />)
- </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 <outputfile> <processfile></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("simple.jpdl");
- 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é</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>
+ <process-engine-context>
+ <command-service>
+ <emphasis role="bold"><spring-transaction-interceptor /></emphasis>
+ ...
+ </command-service>
+ ...
+ </process-engine-context>
+ <transaction-context>
+ ...
+ <emphasis role="bold"><hibernate-session current="true"/></emphasis>
+ </transaction-context>
+ </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>
+ <bean id="jbpmConfiguration" class="org.jbpm.pvm.internal.cfg.SpringConfiguration">
+ <constructor-arg value="be/inze/spring/demo/jbpm.cfg.xml" />
+ </bean>
+ </programlisting>
+ </para>
+
+ <para>
+ The jBPM services can also be defined in the Spring applicationContext, as following:
+ <programlisting>
+<bean id="processEngine" factory-bean="jbpmConfiguration" factory-method="buildProcessEngine" />
+<bean id="repositoryService" factory-bean="processEngine" factory-method="getRepositoryService" />
+<bean id="executionService" factory-bean="processEngine" factory-method="getExecutionService" />
+ </programlisting>
+ </para>
+
+ <para>
+ For accessing Spring beans from withing a process, we need to register
+ the Spring applicationContext with the scripting-manager.
+
+ <programlisting>
+ <script-manager default-expression-language="juel"
+ default-script-language="juel"
+ read-contexts="execution, environment, process-engine, <emphasis role="bold">spring</emphasis>"
+ write-context="">
+ <script-language name="juel"
+ factory="org.jbpm.pvm.internal.script.JuelScriptEngineFactory" />
+ </script-manager>
+ </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>
+<java name="echo" expr="#{echoService}" method="sayHello" >
+ <transition name="to accept" to="join1"/>
+ </java>
+ </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 <env class="identitySession" />)
+ </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 <outputfile> <processfile></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("simple.jpdl");
+ 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>
+<process name="InlineMail" xmlns="http://jbpm.org/4.0/jpdl">
+ <start>
+ <transition to="send birthday reminder note" />
+ </start>
+ <mail name="send birthday reminder note">
+ <to addresses="johnDoe at some-company.com" />
+ <subject>Reminder: ${person} celebrates his birthday!</subject>
+ <text>Do not forget: ${date} is the birthday of ${person} </text>
+ <transition to="end" />
+ </mail>
+ <state name="end"/>
+</process>
+ </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>
+<transaction-context>
+ ...
+ <mail-session>
+ <mail-server>
+ <session-properties resource="jbpm.mail.properties" />
+ </mail-server>
+ </mail-session>
+</transaction-context>
+ </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