Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 1078552 2011-03-06 19:58:46Z 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_CONNECTIONTIMEOUT, MAIL_SMTP_FROM, MAIL_SMTP_PASSWORD, MAIL_SMTP_SOCKET_FACTORY_CLASS, MAIL_SMTP_SOCKET_FACTORY_FALLBACK, MAIL_SMTP_SOCKET_FACTORY_PORT, MAIL_SMTP_TIMEOUT, MAIL_SMTP_USER, MAIL_TRANSPORT_PROTOCOL, MAIL_TRANSPORT_TLS, message, popBeforeSmtp, popHost, popPassword, popUsername, RECEIVER_EMAIL, RECEIVER_NAME, replyList, SENDER_EMAIL, SENDER_NAME, sentDate, SMTP, smtpPort, socketConnectionTimeout, socketTimeout, ssl, sslSmtpPort, subject, TEXT_HTML, TEXT_PLAIN, tls, 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.
`String` | `getMailServer()` Gets the host name of the outgoing mail server.
`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(String serverAddress)` Sets the address of the outgoing mail server.
`VelocityEmail` | `setTemplate(String template)` Velocity template to execute.
`VelocityEmail` | `setTo(String toName, 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.
`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, addBcc, addCc, addCc, addCc, addHeader, addReplyTo, addReplyTo, addReplyTo, addTo, addTo, addTo, buildMimeMessage, createMimeMessage, getBccAddresses, getCcAddresses, getFromAddress, getHostName, getMailSession, getMimeMessage, getReplyToAddresses, getSentDate, getSmtpPort, getSocketConnectionTimeout, getSocketTimeout, getSslSmtpPort, getSubject, getToAddresses, isSSL, isTLS, sendMimeMessage, setAuthentication, setAuthenticator, setBcc, setBounceAddress, setCc, setCharset, setContent, setContent, setDebug, setFrom, setFrom, setFrom, setHeaders, setHostName, setMailSession, setMailSessionFromJNDI, setPopBeforeSmtp, setReplyTo, setSentDate, setSmtpPort, setSocketConnectionTimeout, setSocketTimeout, setSSL, setSslSmtpPort, setSubject, setTLS, setTo, toInternetAddressArray, updateContentType`

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

    @Deprecated
    public VelocityEmail setTo(String toName,
                                          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(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(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 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 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.

  Overrides:
    `send` in class `org.apache.commons.mail.Email`
  Throws:
    `org.apache.commons.mail.EmailException` - Failure during merging the velocity template or sending the email.

### toString

    public String toString()

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

  Overrides:
    `toString` in class `Object`
  Returns:
    An empty string.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2000-2011 The Apache Software Foundation. All Rights Reserved.