org.apache.turbine.util.velocity

## Class VelocityHtmlEmail

- java.lang.Object
- - org.apache.commons.mail.Email
  - - org.apache.commons.mail.MultiPartEmail
    - - org.apache.commons.mail.HtmlEmail
      - - org.apache.turbine.util.velocity.VelocityHtmlEmail

-     public class VelocityHtmlEmail
      extends org.apache.commons.mail.HtmlEmail

  This is a simple class for sending html email from within Velocity. Essentially, the bodies (text and html) of the email are a Velocity Context objects. 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!

  This class allows you to send HTML email with embedded content and/or with attachments. You can access the VelocityHtmlEmail instance within your templates trough the `$mail` Velocity variable.

  `VelocityHtmlEmail myEmail= new VelocityHtmlEmail(data);
  context.put("mail", myMail);` or `VelocityHtmlEmail myEmail= new VelocityHtmlEmail(context);
  context.put("mail", myMail);`

  The templates should be located under your Template turbine directory.

  This class wraps the HtmlEmail class from commons-email. Thus, it uses the JavaMail API and also 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 TurbineResourceService.setPropertiesFileName() method for more information.

  This class is basically a conversion of the WebMacroHtmlEmail written by Regis Koenig

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

  Version:
    $Id: VelocityHtmlEmail.java 1706239 2015-10-01 13:18:35Z tv $
  Author:
    Eric Pugh, Andre Schild, Quinton McCombs, Henning P. Schmiedehausen, Peter Courcoux

- - ### Field Summary

    - ### Fields inherited from class org.apache.commons.mail.HtmlEmail

      `CID_LENGTH, html, inlineEmbeds, inlineImages, text`

    - ### 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
    `VelocityHtmlEmail(org.apache.velocity.context.Context context)` Constructor, sets the context object.
    `VelocityHtmlEmail(PipelineData pipelineData)` Constructor, sets the context object from the passed `PipelineData` object

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `String` | `embed(String surl, String name)` Embed a file in the mail.
    `String` | `getCid(String filename)` Get the cid of an embedded file.
    `String` | `getMailServer()` Gets the host name of the outgoing mail server.
    `String` | `send()` Actually send the mail.
    `VelocityHtmlEmail` | `setHtmlTemplate(String template)` Set the HTML template for the mail.
    `void` | `setMailServer(String serverAddress)` Sets the address of the outgoing mail server.
    `VelocityHtmlEmail` | `setTextTemplate(String template)` Set the text template for the mail.

    - ### Methods inherited from class org.apache.commons.mail.HtmlEmail

      `buildMimeMessage, embed, embed, embed, embed, embed, setHtmlMsg, setMsg, setTextMsg`

    - ### Methods inherited from class org.apache.commons.mail.MultiPartEmail

      `addPart, addPart, addPart, attach, attach, attach, attach, attach, attach, createBodyPart, createMimeMultipart, getContainer, getPrimaryBodyPart, getSubType, init, isBoolHasAttachments, isInitialized, setBoolHasAttachments, setInitialized, setSubType`

    - ### 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, createMimeMessage, getBccAddresses, getBounceAddress, getCcAddresses, getFromAddress, 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, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### VelocityHtmlEmail

          public VelocityHtmlEmail(PipelineData pipelineData)

      Constructor, sets the context object from the passed `PipelineData` object
      Parameters:
        `pipelineData` - A Turbine `PipelineData` object.

    - #### VelocityHtmlEmail

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

      Constructor, sets the context object.
      Parameters:
        `context` - A Velocity context object.

  - ### Method Detail

    - #### setHtmlTemplate

          public VelocityHtmlEmail setHtmlTemplate(String template)

      Set the HTML template for the mail. This is the Velocity template to execute for the HTML part. Path is relative to the VM templates directory.
      Parameters:
        `template` - A String.
      Returns:
        A VelocityHtmlEmail (self).

    - #### setTextTemplate

          public VelocityHtmlEmail setTextTemplate(String template)

      Set the text template for the mail. This is the Velocity template to execute for the text part. Path is relative to the VM templates directory
      Parameters:
        `template` - A String.
      Returns:
        A VelocityHtmlEmail (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

      Actually send the mail.
      Overrides:
        `send` in class `org.apache.commons.mail.Email`
      Throws:
        `org.apache.commons.mail.EmailException` - thrown if mail cannot be sent.

    - #### embed

          public String embed(String surl,
                     String name)

      Embed a file in the mail. The file can be referenced through its Content-ID. This function also registers the CID in an internal map, so the embedded file can be referenced more than once by using the getCid() function. This may be useful in a template.

      Example of template: ``

           <html>
           <!-- $mail.embed("http://server/border.gif","border.gif"); -->
           <img src=$mail.getCid("border.gif")>
           <p>This is your content
           <img src=$mail.getCid("border.gif")>
           </html>

      Overrides:
        `embed` in class `org.apache.commons.mail.HtmlEmail`
      Parameters:
        `surl` - A String.
        `name` - A String.
      Returns:
        A String with the cid of the embedded file.
      See Also:
        `embed.`

    - #### getCid

          public String getCid(String filename)

      Get the cid of an embedded file.
      Parameters:
        `filename` - A String.
      Returns:
        A String with the cid of the embedded file.
      See Also:
        `embed.`

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