Author: alex.guizar(a)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/smt... - Sun SMTP Properties</ulink>.</para> + <para>See the <ulink + url="http://java.sun.com/products/javamail/javadocs/com/sun/mail/smt... + 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... - Sun Regex Patterns</ulink>.</para> + + <para>See the <ulink + url="http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/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&gt;.+(a)jbpm.org&lt;/include&gt; + <include&gt;.+(a)example.com&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; /> + <property name="mail.smtp.host" value="internal.smtp.example.com" /> + <property name="mail.from" value=&quot;noreply(a)example.com&quot; /> </session-properties> </mail-server> <mail-server> <address-filter> - <exclude&gt;.+(a)jbpm.org&lt;/exclude&gt; + <exclude&gt;.+(a)example.com&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; /> + <property name="mail.smtp.host" value="external.smtp.example.com" /> + <property name="mail.from" value=&quot;noreply(a)example.com&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> @@ -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