[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