1:37 a.m.
Author: alex.guizar(a)jboss.com
Date: 2009-04-30 02:37:19 -0400 (Thu, 30 Apr 2009)
New Revision: 4684
Modified:
jbpm4/trunk/modules/pvm/src/main/java/org/jbpm/pvm/internal/util/XmlUtil.java
jbpm4/trunk/modules/pvm/src/main/java/org/jbpm/pvm/internal/wire/binding/MailTemplateBinding.java
jbpm4/trunk/modules/pvm/src/main/java/org/jbpm/pvm/internal/wire/descriptor/ObjectDescriptor.java
jbpm4/trunk/modules/pvm/src/test/java/org/jbpm/pvm/internal/wire/MailTemplateWireTest.java
jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch10-Emails.xml
Log:
[JBPM-2058] edit and extend email chapter
fix html binding
Modified: jbpm4/trunk/modules/pvm/src/main/java/org/jbpm/pvm/internal/util/XmlUtil.java
===================================================================
---
jbpm4/trunk/modules/pvm/src/main/java/org/jbpm/pvm/internal/util/XmlUtil.java 2009-04-29
19:51:48 UTC (rev 4683)
+++
jbpm4/trunk/modules/pvm/src/main/java/org/jbpm/pvm/internal/util/XmlUtil.java 2009-04-30
06:37:19 UTC (rev 4684)
@@ -29,11 +29,12 @@
import java.util.StringTokenizer;
import org.jbpm.api.JbpmException;
-import org.jbpm.internal.log.Log;
import org.jbpm.pvm.internal.xml.Parse;
import javax.xml.namespace.QName;
+import javax.xml.transform.OutputKeys;
import javax.xml.transform.Transformer;
+import javax.xml.transform.TransformerException;
import javax.xml.transform.TransformerFactory;
import javax.xml.transform.dom.DOMSource;
import javax.xml.transform.stream.StreamResult;
@@ -52,8 +53,6 @@
*/
public class XmlUtil {
- private static Log log = Log.getLog(XmlUtil.class.getName());
-
private XmlUtil() {
// hide default constructor to prevent instantiation
}
@@ -217,21 +216,21 @@
return onlyChild;
}
- public static String toString(Element element) {
- if (element == null) {
- return "null";
- }
+ public static String toString(Node node) {
+ if (node == null) return "null";
- StringWriter stringWriter = new StringWriter();
try {
TransformerFactory transformerFactory = TransformerFactory.newInstance();
Transformer transformer = transformerFactory.newTransformer();
- transformer.transform(new DOMSource(element), new StreamResult(stringWriter));
- } catch (Exception e) {
- log.error("couldn't transform dom element into string
representation");
- return "<" + element.getTagName() + " ... >...</" +
element.getTagName() + ">";
+ transformer.setOutputProperty(OutputKeys.OMIT_XML_DECLARATION, "yes");
+
+ StringWriter stringWriter = new StringWriter();
+ transformer.transform(new DOMSource(node), new StreamResult(stringWriter));
+ return stringWriter.toString();
+ }
+ catch (TransformerException e) {
+ throw new JbpmException("could not transform dom node to string", e);
}
- return stringWriter.toString();
}
public static String getContentText(Element element) {
Modified:
jbpm4/trunk/modules/pvm/src/main/java/org/jbpm/pvm/internal/wire/binding/MailTemplateBinding.java
===================================================================
---
jbpm4/trunk/modules/pvm/src/main/java/org/jbpm/pvm/internal/wire/binding/MailTemplateBinding.java 2009-04-29
19:51:48 UTC (rev 4683)
+++
jbpm4/trunk/modules/pvm/src/main/java/org/jbpm/pvm/internal/wire/binding/MailTemplateBinding.java 2009-04-30
06:37:19 UTC (rev 4684)
@@ -32,10 +32,11 @@
import org.jbpm.pvm.internal.wire.descriptor.ListDescriptor;
import org.jbpm.pvm.internal.wire.descriptor.ObjectDescriptor;
import org.jbpm.pvm.internal.wire.descriptor.StringDescriptor;
-import org.jbpm.pvm.internal.wire.operation.PropertyOperation;
import org.jbpm.pvm.internal.xml.Parse;
import org.jbpm.pvm.internal.xml.Parser;
+import org.w3c.dom.DocumentFragment;
import org.w3c.dom.Element;
+import org.w3c.dom.Node;
/**
* @author Alejandro Guizar
@@ -71,7 +72,7 @@
Element toElement = XmlUtil.element(element, "to");
if (toElement != null) {
Descriptor toDescriptor = parseRecipientTemplate(toElement, parse, parser);
- addPropertyInjection(templateDescriptor, "to", toDescriptor);
+ templateDescriptor.addPropertyInjection("to", toDescriptor);
}
else {
parse.addProblem("template '" + name + "' has no
'to' recipients");
@@ -80,13 +81,13 @@
Element ccElement = XmlUtil.element(element, "cc");
if (ccElement != null) {
Descriptor ccDescriptor = parseRecipientTemplate(ccElement, parse, parser);
- addPropertyInjection(templateDescriptor, "cc", ccDescriptor);
+ templateDescriptor.addPropertyInjection("cc", ccDescriptor);
}
// bcc
Element bccElement = XmlUtil.element(element, "bcc");
if (bccElement != null) {
Descriptor bccDescriptor = parseRecipientTemplate(bccElement, parse, parser);
- addPropertyInjection(templateDescriptor, "bcc", bccDescriptor);
+ templateDescriptor.addPropertyInjection("bcc", bccDescriptor);
}
// subject
Element subjectElement = XmlUtil.element(element, "subject");
@@ -107,7 +108,13 @@
// html
Element htmlElement = XmlUtil.element(element, "html");
if (htmlElement != null) {
- StringDescriptor htmlDescriptor = new
StringDescriptor(XmlUtil.toString(htmlElement));
+ // extract child nodes from html element
+ DocumentFragment fragment =
htmlElement.getOwnerDocument().createDocumentFragment();
+ for (Node child = htmlElement.getFirstChild(), next; child != null; child = next)
{
+ next = child.getNextSibling();
+ fragment.appendChild(child);
+ }
+ StringDescriptor htmlDescriptor = new
StringDescriptor(XmlUtil.toString(fragment));
templateDescriptor.addInjection("html", htmlDescriptor);
}
// attachments
@@ -136,14 +143,6 @@
return templateDescriptor;
}
- private static void addPropertyInjection(ObjectDescriptor objectDescriptor, String
propertyName,
- Descriptor valueDescriptor) {
- PropertyOperation operation = new PropertyOperation();
- operation.setPropertyName(propertyName);
- operation.setDescriptor(valueDescriptor);
- objectDescriptor.addOperation(operation);
- }
-
protected Descriptor parseRecipientTemplate(Element element, Parse parse, Parser
parser) {
ObjectDescriptor recipientDescriptor = new ObjectDescriptor(AddressTemplate.class);
Modified:
jbpm4/trunk/modules/pvm/src/main/java/org/jbpm/pvm/internal/wire/descriptor/ObjectDescriptor.java
===================================================================
---
jbpm4/trunk/modules/pvm/src/main/java/org/jbpm/pvm/internal/wire/descriptor/ObjectDescriptor.java 2009-04-29
19:51:48 UTC (rev 4683)
+++
jbpm4/trunk/modules/pvm/src/main/java/org/jbpm/pvm/internal/wire/descriptor/ObjectDescriptor.java 2009-04-30
06:37:19 UTC (rev 4684)
@@ -370,7 +370,7 @@
addInjection(fieldName, new EnvDescriptor(type));
}
- /** add an injection based on a descriptor */
+ /** add a field injection based on a descriptor */
public void addInjection(String fieldName, Descriptor descriptor) {
FieldOperation injectionOperation = new FieldOperation();
injectionOperation.setFieldName(fieldName);
@@ -378,6 +378,15 @@
addOperation(injectionOperation);
}
+ /** add a property injection based on a descriptor */
+ public void addPropertyInjection(String propertyName,
+ Descriptor valueDescriptor) {
+ PropertyOperation operation = new PropertyOperation();
+ operation.setPropertyName(propertyName);
+ operation.setDescriptor(valueDescriptor);
+ addOperation(operation);
+ }
+
/**
* Gets the class name of the object to create.
* This name is defined only when creating objects from a constructor or when invoking
static methods.
Modified:
jbpm4/trunk/modules/pvm/src/test/java/org/jbpm/pvm/internal/wire/MailTemplateWireTest.java
===================================================================
---
jbpm4/trunk/modules/pvm/src/test/java/org/jbpm/pvm/internal/wire/MailTemplateWireTest.java 2009-04-29
19:51:48 UTC (rev 4683)
+++
jbpm4/trunk/modules/pvm/src/test/java/org/jbpm/pvm/internal/wire/MailTemplateWireTest.java 2009-04-30
06:37:19 UTC (rev 4684)
@@ -150,8 +150,7 @@
+ "</objects>");
MailTemplate template = wireContext.get(MailTemplate.class);
- System.out.println(template.getHtml());
- assertTextPresent("<strong>rich</strong> content</html>",
template.getHtml());
+ assertEquals("<strong>rich</strong> content",
template.getHtml());
}
public void testAttachments() {
Modified: jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch10-Emails.xml
===================================================================
--- jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch10-Emails.xml 2009-04-29
19:51:48 UTC (rev 4683)
+++ jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch10-Emails.xml 2009-04-30
06:37:19 UTC (rev 4684)
@@ -1,258 +1,195 @@
-<chapter id="emails">
- <title>Email Support</title>
- <para>
- This chapter explains Email Support provided within jBPM 4.
- </para>
-
-
- <section id="mailinjpdl">
- <title>Mail in jPDL</title>
- </section>
- <section id="scriptableemails">
+<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 emails within jBPM. All mail
producers implement the
<literal>org.jbpm.pvm.internal.email.producer.MailProducer</literal>
interface.
- Several out-of-the-box implementations have been created to address simple email
needs.</para>
-
- <section id="standardemailformat">
- <title>Standard</title>
- <para>Used to send non-scripted text emails.</para>
- <table><title>Standard Email</title>
- <tgroup cols="2" rowsep="1" colsep="1">
- <thead>
- <row>
- <entry>Property</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>subject</literal></entry>
- <entry>Email subject.</entry>
- </row>
- <row>
- <entry><literal>text</literal></entry>
- <entry>The textual body of the email.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- <section id="scriptedemailformat">
- <title>Scriptable Standard</title>
- <para>Used to send scripted text emails for the subject and/or
text.</para>
- <table><title>Scriptable Email</title>
- <tgroup cols="2" rowsep="1" colsep="1">
- <thead>
- <row>
- <entry>Property</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>language</literal></entry>
- <entry>The scripting language used to resolve properties within the
subject and textual body. If not provided, the default script language is
applied.</entry>
- </row>
- <row>
- <entry><literal>subject</literal></entry>
- <entry>Email subject.</entry>
- </row>
- <row>
- <entry><literal>text</literal></entry>
- <entry>The textual body of the email.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- <section id="htmlemailformat">
- <title>Scriptable HTML</title>
- <para>Used to send scripted HTML formatted emails for the subject, text, and
html.</para>
- </section>
- <table><title>Scriptable HTML Email</title>
- <tgroup cols="2" rowsep="1" colsep="1">
- <thead>
- <row>
- <entry>Property</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>language</literal></entry>
- <entry>The scripting language used to resolve properties within the
subject, textual body, and HTML body. If not provided, the default script language is
applied.</entry>
- </row>
- <row>
- <entry><literal>subject</literal></entry>
- <entry>Email subject.</entry>
- </row>
- <row>
- <entry><literal>text</literal></entry>
- <entry>The textual body of the email.</entry>
- </row>
- <row>
- <entry><literal>html</literal></entry>
- <entry>The HTML formatted body of the email.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>For complex emails or custom generation of attachments, see: <link
linkend="customemails">Extension Points: Custom
Emails</link>.</para>
+ <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="emailtemplates">
+
+ <section id="mailtemplates">
<title>Templates</title>
- <para>Templates are available to externalize commonly used messages from jPDL
definitions. In jBPM 4, templates can produce either standard or HTML message; also,
templates
- can support any scripting language supported by the jBPM Script Manager. As you will
see, any <literal>MailProducer</literal> implementation available to jPDL is
also available to be templated.
- </para>
- <para>The following is an example of a scriptable Email Template.</para>
- <programlisting>TODO</programlisting>
- <para>The following is an example of a scriptable HTML Email
Template.</para>
- <programlisting>TODO</programlisting>
+ <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="emailserverconfiguration">
- <title>Server Configuration</title>
- <para>Mail Server configuration is provided within jbpm.cfg.xml The
<literal>mail-server</literal> tag 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>
- subtag of <literal>mail-server</literal>, the SMTP properties must be
provided as described 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...
SMTP Properties</ulink>.
- </para>
- <programlisting><objects>
- <mail-session>
- <mail-server><emphasis role="bold">
- <session-properties>
- <property name='mail.host' value='localhost' />
- ...
- </session-properties></emphasis>
- </mail-server>
- </mail-session>
-</objects></programlisting>
- <section id="serverconfigurationmultipl">
- <title>Multiple Mail Servers</title>
- <para>Multiple SMTP server support has been added to jBPM 4 to support many
organizational server structures.
- This is useful for organizations who have both internal and external SMTP servers,
for example.</para>
- <para>
- To setup multiple SMTP mail servers, provide multiple mail servers within the jBPM
configuration, as described below.
-
- Note that the tag <literal>address-filter</literal> has been added to
filter which domains are serviced by each mail server.
- The mail filter accepts regular expressions to determine if an address is to be sent
by a given server.
- </para>
- <para>See the Sun Pattern API for more information on supported RegEx
expressions: <ulink
url="http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern...
Regex Patterns</ulink>.
- </para>
- <programlisting><objects>
- <mail-session>
- <mail-server><emphasis role="bold">
- <address-filter>
- &lt;include&gt;.+(a)jbpm.org&lt;/include&gt;
- </address-filter></emphasis>
- <session-properties>
- <property name='mail.host' value='internal.host.url'
/>
- ...
- </session-properties>
- </mail-server>
- <mail-server><emphasis role="bold">
- <address-filter>
- &lt;exclude&gt;.+(a)jbpm.org&lt;/exclude&gt;
- </address-filter></emphasis>
- <session-properties>
- <property name='mail.host' value='external.host.url'
/>
- ...
- </session-properties>
- </mail-server>
- </mail-session>
-</objects></programlisting>
- <para>
- The include/excude logic includes an address if it is <emphasis
role="bold">included and not explicitly excluded.</emphasis>
-
- The include/exclude logic within the address filter is described below.
-
- <table><title>Address Filter</title>
- <tgroup cols="3" rowsep="1" colsep="1">
- <thead>
- <row>
- <entry>Property</entry>
- <entry>Multiple</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>include</literal></entry>
- <entry>0</entry>
- <entry>If no includes are present, the address filter will include all
email addresses.</entry>
- </row>
- <row>
- <entry><literal>include</literal></entry>
- <entry>1..Many</entry>
- <entry>If one or more includes are present, the address filter will
include only email addresses matching the include patterns provided.</entry>
- </row>
- <row>
- <entry><literal>exclude</literal></entry>
- <entry>0</entry>
- <entry>If no excludes are present, no addresses are explicitly
excluded.</entry>
- </row>
- <row>
- <entry><literal>exclude</literal></entry>
- <entry>1..Many</entry>
- <entry>If one or more excludes are present, the address filter will
explicitly exclude only email addresses matching the exclude patterns
provided.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
+
+ <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="noreply(a)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...
+ Sun Regex Patterns</ulink>.</para>
+ <programlisting><![CDATA[<jbpm-configuration>
+<transaction-context>
+ <mail-session>
+ <mail-server>
+ <address-filter>
+ <include>.+(a)jbpm.org</include>
+ </address-filter>
+ <session-properties>
+ <property name="mail.smtp.host" value="int.smtp.jbpm.org"
/>
+ <property name="mail.from" value="noreply(a)jbpm.org" />
+ </session-properties>
+ </mail-server>
+ <mail-server>
+ <address-filter>
+ <exclude>.+(a)jbpm.org</exclude>
+ </address-filter>
+ <session-properties>
+ <property name="mail.smtp.host" value="ext.smtp.jbpm.org"
/>
+ <property name="mail.from" value="noreply(a)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="addressresolvers">
- <title>Address Resolvers</title>
- <para>When implementing a different Identity Management in jBPM [such as
LDAP], an Address Resolver is required to resolve Actor and Group email addresses from the
Identity Management system.</para>
- <para>Address Resolvers must implement the
<literal>org.jbpm.pvm.internal.email.resolver.AddressResolver</literal>
interface. Provided with a User or Group Identifier, the should return valid JavaMail
<literal>javax.mail.internet.InternetAddress</literal>es for the given
identifier.</para>
- <para>Plugging in a custom Address Resolver to jBPM is handled within the jBPM
Configuration. The following is an example of providing a custom Address Resolver within
<literal>jbpm.cfg.xml</literal>.</para>
- <programlisting>TODO</programlisting>
-
- </section>
- <section id="customemails">
- <title>Custom Emails</title>
- <para>jBPM 4 allows the creation of your own Email Producers to address an
organization's specific email needs.
- To do so, users must implement the
<literal>org.jbpm.pvm.internal.email.producer.MailProducer</literal>
interface. The method produce will return one or more Email objects, which jBPM will then
send using the jBPM MailSession.
- <para>Apache Commons Email was choosen to simplify the email interface for jBPM.
All emails returned by the MailProducer implementation must extend the base
<literal>org.apache.commons.mail.Email</literal>.</para>
- <para>See the Apache Commons for more information on supported
<literal>Email</literal> types:
- <ulink url="http://commons.apache.org/email/">Apache Commons
Email</ulink>.</para>
- </para>
-
- <section id="generatedemailattachments">
- <title>Attachments</title>
- <para>
- Generation of custom attachments at runtime can be easily implemented in jBPM 4.
By extending out-of-the-box mail producers, or implementing your own with the
<literal>MailProducer</literal> interface, attachments can be generated,
attachments can be generated and added to
- emails at runtime.
- </para>
- <para>The following is an example of how to extend
<literal>HtmlScriptMailProducer</literal> to produce HTML emails with custom
attachments.</para>
- <programlisting>public class CustomAttachmentHtmlScriptMailProducer extends
HtmlScriptMailProducer{
- @Override
- public Collection<Email> produce(Execution exe, MailContext mailContext)
- throws Exception {
- //Use the HTML producer to create the body, subject, text.
- Collection<Email> emails = super.produce(exe, mailContext);
-
- //Add custom code to generate attachments here.
- EmailAttachment attachment = null;
-
- for(Email email : emails)
- {
- //We know it's a collection of HTML email.
- HtmlEmail html = (HtmlEmail)email;
- //Add your custom attachment.
- html.attach(attachment);
- }
-
- return emails;
-
- }
-}</programlisting>
- </section>
- </section>
+ <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>