Author: jbarrez Date: 2009-10-28 10:47:18 -0400 (Wed, 28 Oct 2009) New Revision: 5830 Removed: jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch11-Emails.xml Modified: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch01-Introduction.xml jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch06-Jpdl.xml Log: Revised doc: userguide chapter 6 + devguide chapter 1 Modified: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch01-Introduction.xml =================================================================== --- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch01-Introduction.xml 2009-10-28 12:49:19 UTC (rev 5829) +++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch01-Introduction.xml 2009-10-28 14:47:18 UTC (rev 5830) @@ -5,22 +5,23 @@ <title>Target audience</title> <para>This developers guide is intended for experienced developers that want to get the full flexibility out of jBPM. The features described in this - developers guide will not be supported. Use at your own risk. + developers guide are currently not supported. Use at your own risk. </para> </section> <section> <title>Overview</title> <para><xref linkend="incubation" /> explains the features that are intended to - move to the userguide eventually and become part of the supported offering. But - incubation features are not yet considered stable. + move to the userguide eventually and become part of the supported offering. + Do note that incubation features are not yet considered stable (ie. there + could be major syntax or implementation changes in next versions). </para> <para><xref linkend="processvirtualmachine" /> through <xref linkend="advancedgraphexecution" /> - explain the process virtual machine and how activity and event listener can be build - for it. + explain the core of jBPM, the process virtual machine (PVM) and how activity + and event listener can be build for it. </para> <para><xref linkend="configuration" /> through <xref linkend="jbossintegration" /> - explain internal developer topics. + explain advanced usage of the jBPM framework. </para> </section> @@ -49,10 +50,13 @@ <section> <title>Library dependencies</title> <para>If you want to install/deploy jBPM into your own application, this is still as easy - as it was before: Just put the right libs in your application classpath. We didn't yet clean + as it was before: just put the right libs in your application classpath. We didn't yet clean up the dependency description in the maven pom files. So we can't yet give the exact minimal set of libraries from the <literal>lib</literal> directory that you need to include - in your application. The versions of the libraties that are in the <literal>lib</literal> + in your application (See Jira issue + <ulink url="https://jira.jboss.org/jira/browse/JBPM-2556">JBPM-2556... + and vote for it if you want to let us know that this issue has priority for you). + The versions of the libraries that are in the <literal>lib</literal> directory are the ones that we tested with. So we recommend you to use those very versions of the libs. To help you on your way, here's the current maven dependency list for jPDL: </para> @@ -107,9 +111,6 @@ <literal>org.hibernate:hibernate-entitymanager</literal> </para> <para>This list should already get you started to select a small subset of libs instead of including all the libs from the <literal>${jbpm.home}/lib</literal> directory. - In one of the next releases, we'll clean up those dependency descriptions in the pom and include - a good description of which are the minimal libs to get jBPM up and running inside - your own application. </para> </section> 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-10-28 12:49:19 UTC (rev 5829) +++ jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch06-Jpdl.xml 2009-10-28 14:47:18 UTC (rev 5830) @@ -2,12 +2,13 @@ <title>jPDL</title> <para>This chapter will explain the jPDL file format for describing - process definitions. + process definitions. jPDL is the prominent process language of jBPM. The goal + of jPDL is to be as concise and developer-friendly as possible, while offering + every feature you'd expect from a BPM process language. </para> <para>The jPDL schema file contains more attributes and elements then this - documentation. This documentation explains the stable and supported part of jPDL. - So use this documentation as a reference to know what attributes and elements - are stable and supported. + documentation. This part of the documentation explains the stable and supported part of jPDL. + Experimental/not supported jPDL features can be found in the developers guide. </para> <para>An example jPDL process file looks like this: </para> @@ -176,7 +177,7 @@ <section id="state"> <title><literal>state</literal></title> <para>A wait state. Process execution will wait until an external trigger is - provided through the API. Apart from the <link linkend="commonactivitycontent"> + provided through the API. Apart from the <link linkend="commonactivitycontents"> common activity content</link>, <literal>state</literal> doesn't have any extra attributes or elements. </para> @@ -733,9 +734,7 @@ </programlisting> <para>This time, if we would start an execution and signal it to move out of the <literal>get return code</literal> wait state with the following code, the execution would end with the <literal>cancel</literal> state.</para> - <programlisting>TODO (paste the code snippit) - </programlisting> - <para>Similarly as above, using the value <literal>200</literal> or <literal>500</literal> would cause the execution + <para>Similarly, using the value <literal>200</literal> or <literal>500</literal> would cause the execution to end with the <literal>completed</literal> or with the <literal>error</literal> states respectively.</para> </section> @@ -1563,7 +1562,8 @@ <para>Then we set a variable on the task. This is typically done through a form. But here we'll show how it is done programmatically. </para> - <programlisting>Map&lt;String, Object&gt; variables = new HashMap&lt;String, Object&gt;(); + <programlisting> +Map&lt;String, Object&gt; variables = new HashMap&lt;String, Object&gt;(); variables.put(&quot;result&quot;, &quot;accept&quot;); taskService.setVariables(task.getDbid(), variables);</programlisting> <para>Completing this task, will cause the sub process instance to end. @@ -1641,7 +1641,7 @@ the task is completed. </para> <programlisting>Map&lt;String, Object&gt; variables = new HashMap&lt;String, Object&gt;(); -variables.put(quot;resultquot;, quot;okquot;); +variables.put(&quot;result&quot;, &quot;ok&quot;); taskService.setVariables(task.getId(), variables); taskService.completeTask(task.getDbid());</programlisting> <para>In this scenario, the <literal>ok</literal> transition is taken in @@ -2452,7 +2452,8 @@ <title>Events</title> <para>Events specify points in a process on which a list of event listeners can be registered. When an execution passes that point in the process, the event listeners are notified. - The events and listeners are not shown in the graphical view of the process. An event + The events and listeners are not shown in the graphical view of the process, which + makes them very interesting for implementing technical details. An event is fired by an element in the process definition like e.g. the process definition, an activity or a transition. </para> @@ -2599,8 +2600,7 @@ &lt;state name=&quot;park&quot;/&gt; &lt;/process&gt;</programlisting> - <para><literal>LogListener</literal> will maintain a list of logs in a static member - field:</para> + <para><literal>LogListener</literal> will maintain a list of logs as a process variable:</para> <programlisting>public class <emphasis role="bold">LogListener</emphasis> implements EventListener { // value gets injected from process definition Deleted: jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch11-Emails.xml =================================================================== --- jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch11-Emails.xml 2009-10-28 12:49:19 UTC (rev 5829) +++ jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch11-Emails.xml 2009-10-28 14:47:18 UTC (rev 5830) @@ -1,196 +0,0 @@ -<chapter id="mailsupport"> - <title>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. Refer to - <link linkend="scripting">Scripting</link> for details.</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@minitrue' /> (2) - <to addresses='julia@minitrue, obrien@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/smt... - 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=&quot;noreply(a)jbpm.org&quot; /> - </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... - Sun Regex Patterns</ulink>.</para> - <programlisting><![CDATA[<jbpm-configuration> -<transaction-context> - <mail-session> - <mail-server> - <address-filter> - <include&gt;.+(a)jbpm.org&lt;/include&gt; - </address-filter> - <session-properties> - <property name="mail.smtp.host" value="int.smtp.jbpm.org" /> - <property name="mail.from" value=&quot;noreply(a)jbpm.org&quot; /> - </session-properties> - </mail-server> - <mail-server> - <address-filter> - <exclude&gt;.+(a)jbpm.org&lt;/exclude&gt; - </address-filter> - <session-properties> - <property name="mail.smtp.host" value="ext.smtp.jbpm.org" /> - <property name="mail.from" value=&quot;noreply(a)jbpm.org&quot; /> - </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