[jbpm-commits] JBoss JBPM SVN: r6271 - jbpm4/trunk/modules/devguide/src/main/docbook/en/modules.

do-not-reply at jboss.org do-not-reply at jboss.org
Wed Apr 21 11:28:51 EDT 2010


Author: alex.guizar at jboss.com
Date: 2010-04-21 11:28:50 -0400 (Wed, 21 Apr 2010)
New Revision: 6271

Modified:
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch13-AdvancedEmail.xml
Log:
JBPM-2844: document custom mail producers

Modified: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch13-AdvancedEmail.xml
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch13-AdvancedEmail.xml	2010-04-21 09:59:08 UTC (rev 6270)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch13-AdvancedEmail.xml	2010-04-21 15:28:50 UTC (rev 6271)
@@ -5,9 +5,9 @@
 
   <section id="mailproducers">
     <title>Producers</title>
-    <para>Producers are responsible for creating email messages within jBPM. All mail producers 
+    <para>Mail producers are responsible for creating email messages within jBPM. 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>
+      A default producer is available out of the box to address typical email needs.</para>
 
     <section id="defaultmailproducer">
       <title>Default Producer</title>
@@ -52,12 +52,12 @@
       <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>
+        classpath resources, local files or expressions.</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>
+      linkend="custommailproducers">custom mail producers</link>.</para>
   </section>
 
   <section id="mailtemplates">
@@ -85,9 +85,10 @@
       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>
+    <para>See the <ulink 
+      url="http://java.sun.com/products/javamail/javadocs/com/sun/mail/smtp/package-summary.html">
+      JavaMail documentation</ulink> for details on the supported properties.</para>
+
     <programlisting><![CDATA[<jbpm-configuration>
 <transaction-context>
   <mail-session>
@@ -101,47 +102,54 @@
   </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>
+
+      <para>See the <ulink 
+        url="http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html">Pattern
+        API</ulink> for more information about the allowable regular expressions.</para>
+
       <programlisting><![CDATA[<jbpm-configuration>
 <transaction-context>
   <mail-session>
     <mail-server>
       <address-filter>
-        <include>.+ at jbpm.org</include>
+        <include>.+ at example.com</include>
       </address-filter>
       <session-properties>
-        <property name="mail.smtp.host" value="int.smtp.jbpm.org" />
-        <property name="mail.from" value="noreply at jbpm.org" />
+        <property name="mail.smtp.host" value="internal.smtp.example.com" />
+        <property name="mail.from" value="noreply at example.com" />
       </session-properties>
     </mail-server>
     <mail-server>
       <address-filter>
-        <exclude>.+ at jbpm.org</exclude>
+        <exclude>.+ at example.com</exclude>
       </address-filter>
       <session-properties>
-        <property name="mail.smtp.host" value="ext.smtp.jbpm.org" />
-        <property name="mail.from" value="noreply at jbpm.org" />
+        <property name="mail.smtp.host" value="external.smtp.example.com" />
+        <property name="mail.from" value="noreply at example.com" />
       </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>
@@ -153,44 +161,75 @@
     </section>
   </section>
 
-  <section id="extensibility">
-    <title>Extension Points</title>
+  <section id="custommailproducers">
+    <title>Custom Mail Producers</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 {
+    <para>jBPM 4 allows the creation of custom mail producers to address the specific
+      requirements of an organization. To do so, create a class that implements the 
+      <literal>org.jbpm.pvm.internal.email.spi.MailProducer</literal> interface. Method
+      <literal>produce</literal> takes an Execution and returns a collection of 
+      <literal>Message</literal>s to be sent through the <literal>MailSession</literal>.
+      </para>
 
-  protected void addAttachments(Execution execution, Multipart multipart) {
-    // have default mail producer create attachments from template
-    super.addAttachments(execution, multipart);
+    <section id="extenddefaultmailproducer">
+      <title>Extending the default mail producer</title>
 
-    // create a body part to carry the content
-    BodyPart attachmentPart = new MimeBodyPart();
+      <para>The underpinning of customized mail production is the ability to instantiate
+        a class that implements the MailProducer interface. In the simplest scenario,
+        the class will extend the default mail producer and make a small addition such
+        as adding more recipients. The following process snippet shows a mail
+        activity with a custom mail producer.</para>
 
-    // set content provided by an arbitrary data handler
-    attachmentPart.setDataHandler(...);
+      <programlisting><![CDATA[<mail name='send mail' class='org.example.AuditMailProducer'>
+  <property name='template'>
+    <object method='getTemplate'>
+      <factory><ref type='org.jbpm.pvm.internal.email.impl.MailTemplateRegistry'/></factory>
+      <arg><string value='rectify-template'/></arg>
+    </object>
+  </property>
+  <property name='auditGroup'><string value='thinkpol'/></property>
+  <transition to='end' />
+</mail>]]></programlisting>
 
-    // attach content
-    multipart.addBodyPart(attachmentPart);
+     <para>The Java code for the <classname>AuditMailProducer</classname> comes next.</para>
+
+     <programlisting><![CDATA[public class AuditMailProducer extends MailProducerImpl {
+  private String auditGroup;
+
+  public String getAuditGroup() {
+    return auditGroup;
   }
+  public void setAuditGroup(String auditGroup) {
+    this.auditGroup = auditGroup;
+  }
+
+  @Override
+  protected void fillRecipients(Execution execution, Message email) throws MessagingException {
+    // add recipients from template
+    super.fillRecipients(execution, email);
+
+    // load audit group from database
+    EnvironmentImpl environment = EnvironmentImpl.getCurrent();
+    IdentitySession identitySession = environment.get(IdentitySession.class);
+    Group group = identitySession.findGroupById(auditGroup);
+
+    // send a blind carbon copy of every message to the audit group
+    AddressResolver addressResolver = environment.get(AddressResolver.class);
+    email.addRecipients(RecipientType.BCC, addressResolver.resolveAddresses(group));
+  }
 }]]></programlisting>
-      </section>
+
+      <para><classname>MailProducerImpl</classname> exposes a <literal>template</literal>
+        property. To access a mail template, the mail producer descriptor references
+        the <classname>MailTemplateRegistry</classname> object and invokes its
+        <methodname>getTemplate</methodname> method. This method takes one string
+        parameter, the name of the desired template.</para>
+
+      <para><classname>AuditMailProducer</classname> adds an extra property,
+        the identifier of the group that will receive blind carbon copies of the
+        outgoing emails. The audit mail producer overrides the default 
+        <methodname>fillRecipients</methodname> implementation to add the
+        extra BCC recipients.</para>
     </section>
-  
   </section>
-  
 </chapter>
\ No newline at end of file



More information about the jbpm-commits mailing list