org.apache.turbine.util.velocity
Class VelocityEmail

java.lang.Object
  org.apache.commons.mail.Email
      org.apache.commons.mail.SimpleEmail
          org.apache.turbine.util.velocity.VelocityEmail

public class VelocityEmail

extends org.apache.commons.mail.SimpleEmail

This is a simple class for sending email from within Velocity. Essentially, the body of the email is processed with a Velocity Context object. The beauty of this is that you can send email from within your Velocity template or from your business logic in your Java code. The body of the email is just a Velocity template so you can use all the template functionality of Velocity within your emails!

Example Usage (This all needs to be on one line in your template):

Setup your context:

context.put ("VelocityEmail", new VelocityEmail() );

Then, in your template:

 $VelocityEmail.setTo("Jon Stevens", "jon@latchkey.com")
     .setFrom("Mom", "mom@mom.com").setSubject("Eat dinner")
     .setTemplate("email/momEmail.vm")
     .setContext($context)
 

The email/momEmail.wm template will then be parsed with the Context that was defined with setContext().

If you want to use this class from within your Java code all you have to do is something like this:

 VelocityEmail ve = new VelocityEmail();
 ve.setTo("Jon Stevens", "jon@latchkey.com");
 ve.setFrom("Mom", "mom@mom.com").setSubject("Eat dinner");
 ve.setContext(context);
 ve.setTemplate("email/momEmail.vm")
 ve.send();
 

(Note that when used within a Velocity template, the send method will be called for you when Velocity tries to convert the VelocityEmail to a string by calling toString()).

If you need your email to be word-wrapped, you can add the following call to those above:

 ve.setWordWrap (60);
 

This class is just a wrapper around the SimpleEmail class from commons-mail using the JavaMail API. Thus, it depends on having the mail.server property set in the TurbineResources.properties file. If you want to use this class outside of Turbine for general processing that is also possible by making sure to set the path to the TurbineResources.properties. See the TurbineConfig class for more information.

You can turn on debugging for the JavaMail API by calling setDebug(true). The debugging messages will be written to System.out.

Version:

$Id: VelocityEmail.java 534527 2007-05-02 16:10:59Z tv $

Author:

Jon S. Stevens, Greg Coladonato, Quinton McCombs, Henning P. Schmiedehausen

Field Summary

Fields inherited from class org.apache.commons.mail.Email

ATTACHMENTS, authenticator, bccList, bounceAddress, ccList, charset, content, CONTENT_TYPE, contentType, debug, EMAIL_BODY, EMAIL_SUBJECT, emailBody, FILE_SERVER, fromAddress, headers, hostName, ISO_8859_1, KOI8_R, MAIL_DEBUG, MAIL_HOST, MAIL_PORT, MAIL_SMTP_AUTH, MAIL_SMTP_FROM, MAIL_TRANSPORT_PROTOCOL, message, popBeforeSmtp, popHost, popPassword, popUsername, RECEIVER_EMAIL, RECEIVER_NAME, replyList, SENDER_EMAIL, SENDER_NAME, sentDate, SMTP, smtpPort, subject, TEXT_HTML, TEXT_PLAIN, toList, US_ASCII

Constructor Summary

VelocityEmail()
Constructor

VelocityEmail(org.apache.velocity.context.Context context)
Constructor

Method Summary

org.apache.velocity.context.Context	getContext() Get the context object that will be merged with the template.
java.lang.String	getMailServer() Gets the host name of the outgoing mail server.
java.lang.String	send() This method sends the email.
VelocityEmail	setContext(org.apache.velocity.context.Context context) Set the context object that will be merged with the template.
void	setMailServer(java.lang.String serverAddress) Sets the address of the outgoing mail server.
VelocityEmail	setTemplate(java.lang.String template) Velocity template to execute.
VelocityEmail	setTo(java.lang.String toName, java.lang.String toEmail) Deprecated. use addTo(email,name) instead
VelocityEmail	setWordWrap(int wordWrap) Set the column at which long lines of text should be word- wrapped.
java.lang.String	toString() The method toString() calls send() for ease of use within a Velocity template (see example usage above).

Methods inherited from class org.apache.commons.mail.SimpleEmail

setMsg

Methods inherited from class org.apache.commons.mail.Email

addBcc, addBcc, addCc, addCc, addHeader, addReplyTo, addReplyTo, addTo, addTo, buildMimeMessage, getFromAddress, getHostName, getMailSession, getMimeMessage, getSentDate, getSmtpPort, getSubject, sendMimeMessage, setAuthentication, setAuthenticator, setBcc, setBounceAddress, setCc, setCharset, setContent, setContent, setDebug, setFrom, setFrom, setHeaders, setHostName, setMailSession, setPopBeforeSmtp, setSentDate, setSmtpPort, setSubject, setTo, toInternetAddressArray

Methods inherited from class java.lang.Object

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

Constructor Detail

VelocityEmail

public VelocityEmail()

Constructor

VelocityEmail

public VelocityEmail(org.apache.velocity.context.Context context)

Constructor

Method Detail

setTo

public VelocityEmail setTo(java.lang.String toName,
                           java.lang.String toEmail)
                    throws org.apache.commons.mail.EmailException

Deprecated. use addTo(email,name) instead

To: toName, toEmail

Parameters:

toName - A String with the TO toName.

toEmail - A String with the TO toEmail.

Returns:

A VelocityEmail (self).

Throws:

org.apache.commons.mail.EmailException - email address could not be parsed

setTemplate

public VelocityEmail setTemplate(java.lang.String template)

Velocity template to execute. Path is relative to the Velocity templates directory.

Parameters:

template - relative path of the template to parse including the filename.

Returns:

A VelocityEmail (self).

setWordWrap

public VelocityEmail setWordWrap(int wordWrap)

Set the column at which long lines of text should be word- wrapped. Setting to zero turns off word-wrap (default). NOTE: don't use tabs in your email template document, or your word-wrapping will be off for the lines with tabs in them.

Parameters:

wordWrap - The column at which to wrap long lines.

Returns:

A VelocityEmail (self).

setContext

public VelocityEmail setContext(org.apache.velocity.context.Context context)

Set the context object that will be merged with the template.

Parameters:

context - A Velocity context object.

Returns:

A VelocityEmail (self).

getContext

public org.apache.velocity.context.Context getContext()

Get the context object that will be merged with the template.

Returns:

A Context (self).

setMailServer

public void setMailServer(java.lang.String serverAddress)

Sets the address of the outgoing mail server. This method should be used when you need to override the value stored in TR.props.

Parameters:

serverAddress - host name of your outgoing mail server

getMailServer

public java.lang.String getMailServer()

Gets the host name of the outgoing mail server. If the server name has not been set by calling setMailServer(), the value from TR.props for mail.server will be returned. If TR.props has no value for mail.server, localhost will be returned.

Returns:

host name of the mail server.

send

public java.lang.String send()
                      throws org.apache.commons.mail.EmailException

This method sends the email.

If the mail server was not set by calling, setMailServer() the value of mail.server will be used from TR.props. If that value was not set, localhost is used.

Throws:

org.apache.commons.mail.EmailException - Failure during merging the velocity template or sending the email.

toString

public java.lang.String toString()

The method toString() calls send() for ease of use within a Velocity template (see example usage above).

Returns:

An empty string.