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 1723699 2016-01-08 11:29:21Z 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

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and 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`

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

Copyright © 2000–2018 The Apache Software Foundation. All rights reserved.