org.apache.commons.mail

Class HtmlEmail

java.lang.Object

org.apache.commons.mail.Email

org.apache.commons.mail.MultiPartEmail

org.apache.commons.mail.HtmlEmail

public class HtmlEmail
extends MultiPartEmail

An HTML multipart email.

This class is used to send HTML formatted email. A text message can also be set for HTML unaware email clients, such as text-based email clients.

This class also inherits from MultiPartEmail, so it is easy to add attachents to the email.

To send an email in HTML, one should create a HtmlEmail, then use the setFrom, addTo, etc. methods. The HTML content can be set with the setHtmlMsg method. The alternate text content can be set with setTextMsg.

Either the text or HTML can be omitted, in which case the "main" part of the multipart becomes whichever is supplied rather than a multipart/alternative.

Version:

$Id: HtmlEmail.java,v 1.16 2004/11/14 18:07:43 epugh Exp $

Author:

Regis Koenig, Sean Legassick

Field Summary

Fields

Modifier and Type	Field and Description
static int	CID_LENGTH Defintion of the length of generated CID's
protected String	html Html part of the message
protected List	inlineImages Embeded images
protected String	text Text part of the message.

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

Constructors

Constructor and Description
HtmlEmail()

Method Summary

Modifier and Type	Method and Description
String	embed(DataSource ds, String name) Embeds a DataSource in the HTML.
String	embed(URL url, String name) Embeds an URL in the HTML.
void	send() Does the work of actually sending the email.
HtmlEmail	setHtmlMsg(String aHtml) Set the HTML content.
Email	setMsg(String msg) Set the message.
HtmlEmail	setTextMsg(String aText) Set the text content.

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

addPart, addPart, attach, attach, attach, attach, attach, getContainer, getPrimaryBodyPart, getSubType, init, isBoolHasAttachments, setBoolHasAttachments, setSubType

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

addBcc, addBcc, addCc, addCc, addHeader, addReplyTo, addReplyTo, addTo, addTo, getMailSession, getSentDate, 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, toString, wait, wait, wait

Field Detail

text

protected String text

Text part of the message. This will be used as alternative text if the email client does not support HTML messages.

html

protected String html

Html part of the message

inlineImages

protected List inlineImages

Embeded images

CID_LENGTH

public static final int CID_LENGTH

Defintion of the length of generated CID's

See Also:

Constant Field Values

Constructor Detail

HtmlEmail

public HtmlEmail()

Method Detail

setTextMsg

public HtmlEmail setTextMsg(String aText)
                     throws javax.mail.MessagingException

Set the text content.

Parameters:

aText - A String.

Returns:

An HtmlEmail.

Throws:

javax.mail.MessagingException - see javax.mail.internet.MimeBodyPart for defintions

setHtmlMsg

public HtmlEmail setHtmlMsg(String aHtml)
                     throws javax.mail.MessagingException

Set the HTML content.

Parameters:

aHtml - A String.

Returns:

An HtmlEmail.

Throws:

javax.mail.MessagingException - see javax.mail.internet.MimeBodyPart for defintions

setMsg

public Email setMsg(String msg)
             throws javax.mail.MessagingException

Set the message.

This method overrides the MultiPartEmail setMsg() method in order to send an HTML message instead of a full text message in the mail body. The message is formatted in HTML for the HTML part of the message, it is let as is in the alternate text part.

Overrides:

setMsg in class MultiPartEmail

Parameters:

msg - A String.

Returns:

An Email.

Throws:

javax.mail.MessagingException - see javax.mail.internet.MimeBodyPart for defintions

embed

public String embed(URL url,
                    String name)
             throws javax.mail.MessagingException

Embeds an URL in the HTML.

This method allows to embed a file located by an URL into the mail body. It allows, for instance, to add inline images to the email. Inline files may be referenced with a cid:xxxxxx URL, where xxxxxx is the Content-ID returned by the embed function.

Example of use:

 HtmlEmail he = new HtmlEmail();
 he.setHtmlMsg("<html><img src=cid:" +
  embed("file:/my/image.gif","image.gif") +
  "></html>");
 // code to set the others email fields (not shown)
 

Parameters:

url - The URL of the file.

name - The name that will be set in the filename header field.

Returns:

A String with the Content-ID of the file.

Throws:

javax.mail.MessagingException - when URL suplpied is invalid also see javax.mail.internet.MimeBodyPart for defintions

embed

public String embed(DataSource ds,
                    String name)
             throws javax.mail.MessagingException

Embeds a DataSource in the HTML.

This method allows to embed a DataSource into the mail body. It allows, for instance, to add inline images to the email. Inline files may be referenced with a cid:xxxxxx URL, where xxxxxx is the Content-ID returned by the embed function. This is useful for the case an image is available as a byte array. Maybe used in conjunction with ByteArrayDataSource.

Parameters:

ds - The DataSource.

name - The name that will be set in the filename header field.

Returns:

A String with the Content-ID of the file.

Throws:

javax.mail.MessagingException - when DataSource supplied is invalid also see javax.mail.internet.MimeBodyPart for definitions

send

public void send()
          throws javax.mail.MessagingException

Does the work of actually sending the email.

Overrides:

send in class MultiPartEmail

Throws:

javax.mail.MessagingException - if there was an error.