org.apache.cocoon.mail.transformation
Class SendMailTransformer

java.lang.Object
  org.apache.avalon.framework.logger.AbstractLogEnabled
      org.apache.cocoon.xml.AbstractXMLProducer
          org.apache.cocoon.xml.AbstractXMLPipe
              org.apache.cocoon.transformation.AbstractTransformer
                  org.apache.cocoon.transformation.AbstractSAXTransformer
                      org.apache.cocoon.mail.transformation.SendMailTransformer

All Implemented Interfaces:

Poolable, Recyclable, Disposable, Component, Configurable, LogEnabled, Serviceable, SitemapModelComponent, Transformer, XMLPipe, XMLProducer, XMLConsumer, ContentHandler, LexicalHandler

public class SendMailTransformer
extends AbstractSAXTransformer

The SendMailTransformer send mails with optional attachments using a SMTP server and delivers furthermore a status report of each sent mail.

The SendMailTransformer requires the Sun's JavaMail API implementation. Please download and copy the following files to the Cocoon lib directory:

• mail.jar from http://java.sun.com/products/javamail/
• activation.jar from http://java.sun.com/products/javabeans/glasgow/jaf.html

Use the following sitemap component declaration to define, configure and parameterize the transformer. in the map:sitemap/map:components/map:transformers:

  <map:transformer name="sendmail" src="org.apache.cocoon.mail.transformation.SendMailTransformer">
     <smtphost>smtp.foo.com</smtphost>
     <from>sender@localhost</from>
  </map:transformer>
  

where
• <smtphost> is the SMTP server host name, e.g. smtp.foo.com
• <from> is the sender e-mail address

Furthermore, these parameters can be defined in the sitemap pipeline section:

• smtphost, from - If they are defined, this values overwrite the values from component section described above.
• to - email addresses of recipients e.g.: <map:parameter name="to" value="customer1@target.com,customer2@target.com"/>
• subject - a string, can also come from an input module e.g.; <map:parameter name="subject" value="{request-param:subject}"/>
• body - a string, can also come from an input module e.g.; <map:parameter name="body" value="{request-param:body}"/>
• sendpartial - a boolean, define how to send the mails. When mail is being send to more than one recipient and the parameter is set to false, then all email addresses will appear concatenated in the address field at the mail client of the recipient. The default is true.

More configurations can be made in a specific configuration file, which can be retrieved with a generator as the input document. The input document should have the following configuration entities:

• <email:smtphost>, <email:from> and <email:subject> can be set to overwrite values from the sitemap
• <email:to> - each entry will be append to the list of email addresses
• <email:body> - Overwrites the value from the sitemap. If there is a src attribute, the transformer will try to retrieve the file and place it instead of a text-string as the mail body.
• <email:attachment> - each entry defines a attachment. The attribute name defines the name of the attachment. The mime-type attribute defines the content of the attachment. If there is a nested <email:content> - element, text can be included and the attachment will then be a plain text-file. Is there a url attribute, the transformer tries to retrieve the appropriate file and handle it as an attachment. To use a file as an attachment, retrieved over a protocol like http or cocoon, use the src attribute.

Input document sample:

   <?xml version="1.0" encoding="UTF-8"?>
   <document xmlns:email="http://apache.org/cocoon/transformation/sendmail">
     <email:sendmail>
       <email:smtphost>hostname.company.com</email:smtphost>
       <email:from>info@company.com</email:from>
       <email:to>customer3@target.com</email:to>
       <email:to>customer4@target.com</email:to>
       <email:to>customer5@target.com</email:to>
       <email:to>customer6@target.com</email:to>
       <email:subject>subject-content</email:subject>
       <email:body src="cocoon:/softwareupdate.html?locale=en&country=UK"/>
       <!-- <email:body>some Text</email:body> -->
       <email:attachment name="hello.html" mime-type="text/html">
         <email:content>
           Dear Customer, please visit out new Product-Shop.
         </email:content>
       </email:attachment>
       <email:attachment name="hello2.html" mime-type="text/html" src="cocoon:/src1"/>
       <email:attachment name="hello3.html" mime-type="text/html"
          url="C:\path\softwareupdate.html"/>
       <email:attachment name="hello.gif" mime-type="image/gif"
          url="c:\path\powered.gif"/>
     </email:sendmail>
   </document>
   

After the transformation a report will be generated, where the state for each sent mail can be seen. In case of an exception, the exception-message and a stacktrace will be reported.

FIXME: Known Issues:

• Refactor to use MailSender component
• No support for RFC 2554: SMTP Service Extension for Authentication
• No support for different mail servers, first one will always be used

Version:

$Id: SendMailTransformer.html 1304258 2012-03-23 10:09:27Z ilgrosso $

Field Summary

protected org.apache.cocoon.mail.transformation.SendMailTransformer.AttachmentDescriptor	attachmentDescriptor
protected List	attachments
protected String	body
protected String	bodyMimeType
protected String	bodyURI
protected String	contextPath
static String	DEFAULT_BODY_MIMETYPE
protected String	defaultFromAddress
protected List	defaultReplyToAddresses
protected String	defaultSmtpHost
protected int	defaultSmtpPort
protected List	defaultToAddresses
static String	ELEMENT_ATTACHMENT
static String	ELEMENT_ATTACHMENT_CONTENT
static String	ELEMENT_EMAIL_PREFIX
static String	ELEMENT_ERROR
static String	ELEMENT_FAILURE
static String	ELEMENT_MAILBODY
static String	ELEMENT_MAILFROM
static String	ELEMENT_MAILSUBJECT
static String	ELEMENT_MAILTO
static String	ELEMENT_REPLYTO
static String	ELEMENT_RESULT
static String	ELEMENT_SENDMAIL
static String	ELEMENT_SMTPHOST
static String	ELEMENT_SMTPPORT
static String	ELEMENT_SUCCESS
protected String	fromAddress
protected String	mailHost
protected int	mailPort
protected int	mode
protected static int	MODE_ATTACHMENT
protected static int	MODE_ATTACHMENT_CONTENT
protected static int	MODE_BODY
protected static int	MODE_FROM
protected static int	MODE_NONE
protected static int	MODE_REPLY_TO
protected static int	MODE_SMTPHOST
protected static int	MODE_SMTPPORT
protected static int	MODE_SUBJECT
protected static int	MODE_TO
static String	NAMESPACE
static String	PARAM_BODY
static String	PARAM_FROM
static String	PARAM_REPLY_TO
static String	PARAM_SENDPARTIAL
static String	PARAM_SMTPHOST
static String	PARAM_SMTPPORT
static String	PARAM_SUBJECT
static String	PARAM_TO
protected int	port
protected List	replyToAddresses
protected boolean	sendPartial
protected Message	smtpMessage
protected String	subject
protected List	toAddresses
protected List	usedSources

Fields inherited from class org.apache.cocoon.transformation.AbstractSAXTransformer

context, defaultNamespaceURI, EMPTY_ATTRIBUTES, emptyAttributes, ignoreEmptyCharacters, ignoreEventsCount, ignoreHooksCount, ignoreWhitespaces, manager, namespaceURI, objectModel, parameters, recorderStack, request, resolver, response, source, stack

Fields inherited from class org.apache.cocoon.xml.AbstractXMLProducer

contentHandler, EMPTY_CONTENT_HANDLER, lexicalHandler, xmlConsumer

Fields inherited from interface org.apache.cocoon.transformation.Transformer

ROLE

Constructor Summary

SendMailTransformer()
create a new Transformer

Method Summary

void	configure(Configuration configuration)
void	endTransformingElement(String uri, String name, String raw) Start processing elements of our namespace.
static InternetAddress[]	getAddresses(org.apache.cocoon.mail.transformation.SendMailTransformer.AddressHandler[] handlerArr)
void	recycle() Recycle the producer by removing references, and resetting handlers to null (empty) implementations.
void	setup(SourceResolver resolver, Map objectModel, String src, Parameters par) invoked every time when the transformer is triggered by the pipeline
void	startTransformingElement(String uri, String name, String raw, Attributes attr) Start processing elements of our namespace.

Methods inherited from class org.apache.cocoon.transformation.AbstractSAXTransformer

addRecorder, characters, comment, dispose, endCDATA, endDocument, endDTD, endElement, endEntity, endParametersRecording, endParametersRecording, endPrefixMapping, endRecording, endSAXRecording, endSerializedXMLRecording, endTextRecording, findPrefixMapping, getMutableAttributes, ignorableWhitespace, processingInstruction, removeRecorder, sendEndElementEvent, sendEndElementEventNS, sendEndPrefixMapping, sendEvents, sendParametersEvents, sendStartElementEvent, sendStartElementEvent, sendStartElementEventNS, sendStartElementEventNS, sendStartPrefixMapping, sendTextEvent, service, setDocumentLocator, setupTransforming, skippedEntity, startCDATA, startDocument, startDTD, startElement, startEntity, startParametersRecording, startPrefixMapping, startRecording, startSAXRecording, startSerializedXMLRecording, startTextRecording

Methods inherited from class org.apache.cocoon.xml.AbstractXMLProducer

setConsumer, setContentHandler, setLexicalHandler

Methods inherited from class org.apache.avalon.framework.logger.AbstractLogEnabled

enableLogging, getLogger, setupLogger, setupLogger, setupLogger

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.cocoon.xml.XMLProducer

setConsumer

Field Detail

NAMESPACE

public static final String NAMESPACE

See Also:

Constant Field Values

ELEMENT_SENDMAIL

public static final String ELEMENT_SENDMAIL

See Also:

Constant Field Values

ELEMENT_SMTPHOST

public static final String ELEMENT_SMTPHOST

See Also:

Constant Field Values

ELEMENT_SMTPPORT

public static final String ELEMENT_SMTPPORT

See Also:

Constant Field Values

ELEMENT_MAILFROM

public static final String ELEMENT_MAILFROM

See Also:

Constant Field Values

ELEMENT_MAILTO

public static final String ELEMENT_MAILTO

See Also:

Constant Field Values

ELEMENT_REPLYTO

public static final String ELEMENT_REPLYTO

See Also:

Constant Field Values

ELEMENT_MAILSUBJECT

public static final String ELEMENT_MAILSUBJECT

See Also:

Constant Field Values

ELEMENT_MAILBODY

public static final String ELEMENT_MAILBODY

See Also:

Constant Field Values

ELEMENT_ATTACHMENT

public static final String ELEMENT_ATTACHMENT

See Also:

Constant Field Values

ELEMENT_ATTACHMENT_CONTENT

public static final String ELEMENT_ATTACHMENT_CONTENT

See Also:

Constant Field Values

ELEMENT_EMAIL_PREFIX

public static final String ELEMENT_EMAIL_PREFIX

See Also:

Constant Field Values

ELEMENT_ERROR

public static final String ELEMENT_ERROR

See Also:

Constant Field Values

ELEMENT_SUCCESS

public static final String ELEMENT_SUCCESS

See Also:

Constant Field Values

ELEMENT_FAILURE

public static final String ELEMENT_FAILURE

See Also:

Constant Field Values

ELEMENT_RESULT

public static final String ELEMENT_RESULT

See Also:

Constant Field Values

DEFAULT_BODY_MIMETYPE

public static final String DEFAULT_BODY_MIMETYPE

See Also:

Constant Field Values

MODE_NONE

protected static final int MODE_NONE

See Also:

Constant Field Values

MODE_SMTPHOST

protected static final int MODE_SMTPHOST

See Also:

Constant Field Values

MODE_FROM

protected static final int MODE_FROM

See Also:

Constant Field Values

MODE_TO

protected static final int MODE_TO

See Also:

Constant Field Values

MODE_SUBJECT

protected static final int MODE_SUBJECT

See Also:

Constant Field Values

MODE_BODY

protected static final int MODE_BODY

See Also:

Constant Field Values

MODE_ATTACHMENT

protected static final int MODE_ATTACHMENT

See Also:

Constant Field Values

MODE_ATTACHMENT_CONTENT

protected static final int MODE_ATTACHMENT_CONTENT

See Also:

Constant Field Values

MODE_REPLY_TO

protected static final int MODE_REPLY_TO

See Also:

Constant Field Values

MODE_SMTPPORT

protected static final int MODE_SMTPPORT

See Also:

Constant Field Values

PARAM_SMTPHOST

public static final String PARAM_SMTPHOST

See Also:

Constant Field Values

PARAM_SMTPPORT

public static final String PARAM_SMTPPORT

See Also:

Constant Field Values

PARAM_FROM

public static final String PARAM_FROM

See Also:

Constant Field Values

PARAM_TO

public static final String PARAM_TO

See Also:

Constant Field Values

PARAM_REPLY_TO

public static final String PARAM_REPLY_TO

See Also:

Constant Field Values

PARAM_SUBJECT

public static final String PARAM_SUBJECT

See Also:

Constant Field Values

PARAM_BODY

public static final String PARAM_BODY

See Also:

Constant Field Values

PARAM_SENDPARTIAL

public static final String PARAM_SENDPARTIAL

See Also:

Constant Field Values

mode

protected int mode

toAddresses

protected List toAddresses

replyToAddresses

protected List replyToAddresses

defaultToAddresses

protected List defaultToAddresses

defaultReplyToAddresses

protected List defaultReplyToAddresses

attachments

protected List attachments

subject

protected String subject

body

protected String body

bodyURI

protected String bodyURI

bodyMimeType

protected String bodyMimeType

mailHost

protected String mailHost

mailPort

protected int mailPort

fromAddress

protected String fromAddress

attachmentDescriptor

protected org.apache.cocoon.mail.transformation.SendMailTransformer.AttachmentDescriptor attachmentDescriptor

port

protected int port

contextPath

protected String contextPath

sendPartial

protected boolean sendPartial

smtpMessage

protected Message smtpMessage

defaultSmtpHost

protected String defaultSmtpHost

defaultSmtpPort

protected int defaultSmtpPort

defaultFromAddress

protected String defaultFromAddress

usedSources

protected List usedSources

Constructor Detail

SendMailTransformer

public SendMailTransformer()

create a new Transformer

Method Detail

configure

public void configure(Configuration configuration)
               throws ConfigurationException

Specified by:

configure in interface Configurable

Overrides:

configure in class AbstractSAXTransformer

Throws:

ConfigurationException

setup

public void setup(SourceResolver resolver,
                  Map objectModel,
                  String src,
                  Parameters par)
           throws ProcessingException,
                  SAXException,
                  IOException

invoked every time when the transformer is triggered by the pipeline

Specified by:

setup in interface SitemapModelComponent

Overrides:

setup in class AbstractSAXTransformer

Throws:

ProcessingException

SAXException

IOException

startTransformingElement

public void startTransformingElement(String uri,
                                     String name,
                                     String raw,
                                     Attributes attr)
                              throws SAXException

Description copied from class: AbstractSAXTransformer

Start processing elements of our namespace. This hook is invoked for each sax event with our namespace.

Overrides:

startTransformingElement in class AbstractSAXTransformer

Parameters:

uri - The namespace of the element.

name - The local name of the element.

raw - The qualified name of the element.

attr - The attributes of the element.

Throws:

SAXException

endTransformingElement

public void endTransformingElement(String uri,
                                   String name,
                                   String raw)
                            throws SAXException,
                                   ProcessingException

Description copied from class: AbstractSAXTransformer

Start processing elements of our namespace. This hook is invoked for each sax event with our namespace.

Overrides:

endTransformingElement in class AbstractSAXTransformer

Parameters:

uri - The namespace of the element.

name - The local name of the element.

raw - The qualified name of the element.

Throws:

SAXException

ProcessingException

getAddresses

public static InternetAddress[] getAddresses(org.apache.cocoon.mail.transformation.SendMailTransformer.AddressHandler[] handlerArr)

recycle

public void recycle()

Description copied from class: AbstractXMLProducer

Recycle the producer by removing references, and resetting handlers to null (empty) implementations.

Specified by:

recycle in interface Recyclable

Overrides:

recycle in class AbstractSAXTransformer

See Also:

Recyclable.recycle()