Package org.apache.turbine.util.velocity

Class 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$
    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

      Constructors 
      Constructor Description
      VelocityEmail()
      Constructor
      VelocityEmail​(org.apache.velocity.context.Context context)
      Constructor

    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      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, addBcc, addCc, addCc, addCc, addCc, addHeader, addReplyTo, addReplyTo, addReplyTo, addTo, addTo, addTo, addTo, buildMimeMessage, createMimeMessage, getBccAddresses, getBounceAddress, getCcAddresses, getFromAddress, getHeader, getHeaders, getHostName, getMailSession, getMimeMessage, getReplyToAddresses, getSentDate, getSmtpPort, getSocketConnectionTimeout, getSocketTimeout, getSslSmtpPort, getSubject, getToAddresses, isSendPartial, isSSL, isSSLCheckServerIdentity, isSSLOnConnect, isStartTLSEnabled, isStartTLSRequired, isTLS, sendMimeMessage, setAuthentication, setAuthenticator, setBcc, setBounceAddress, setCc, setCharset, setContent, setContent, setDebug, setFrom, setFrom, setFrom, setHeaders, setHostName, setMailSession, setMailSessionFromJNDI, setPopBeforeSmtp, setReplyTo, setSendPartial, setSentDate, setSmtpPort, setSocketConnectionTimeout, setSocketTimeout, setSSL, setSSLCheckServerIdentity, setSSLOnConnect, setSslSmtpPort, setStartTLSEnabled, setStartTLSRequired, setSubject, setTLS, setTo, toInternetAddressArray, updateContentType

    • Constructor Detail

      • VelocityEmail

        public VelocityEmail​(org.apache.velocity.context.Context context)
        Constructor
        Parameters:
        context - the velocity context to use

    • 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.