com.arsdigita.mail
Class Mail

java.lang.Object
  com.arsdigita.mail.Mail

All Implemented Interfaces:

MessageType

public class Mail

extends Object

implements MessageType

Represents a email message with optional attachments. This class is a wrapper for the JavaMail API that makes it easier for application developers to create and send email. For simple plain text message, there is a static convenience method that does not require the construction of an explicit Mail object:

 Mail.send(to, from, subject, body)
 

For more complex messages, the API provides methods to set all standard mail headers, attach other pieces of content, and finally invoke the transport process to deliver the message.

Version:

$Id: //core-platform/dev/src/com/arsdigita/mail/Mail.java#14 $

Author:

Ron Henderson

Field Summary

static String	ATTACHMENT Disposition of "attachment"
static String	INLINE Disposition of "inline"

Fields inherited from interface com.arsdigita.util.MessageType

TEXT_HTML, TEXT_PLAIN, TEXT_PREFORMATTED, TEXT_SMART

Constructor Summary

Mail()
Default constructor.

Mail(String to, String from, String subject)
Constructor used to specify to, from, and subject.

Mail(String to, String from, String subject, String body)
Constructor used to specify to, from, subject, and body.

Mail(String to, String from, String subject, String body, String enc)
Constructor used to specify to, from, subject, body, and encoding.

Method Summary

void	addHeader(String name, String value) Adds a header (name, value) pair.
void	attach(byte[] data, String type, String name) Attaches a byte array to a message.
void	attach(byte[] data, String type, String name, String description, String disposition) Attaches a byte array to a message.
protected void	attach(ByteArrayDataSource dataSource, String description, String disposition) Attaches the content from a ByteArrayDataSource to a message.
void	attach(ByteArrayInputStream is, String type, String name) Attaches the content from a ByteArrayInputStream to a message.
void	attach(ByteArrayInputStream is, String type, String name, String description, String disposition) Attaches the content from a ByteArrayInputStream to a message.
void	attach(javax.activation.DataHandler dh) Attaches content to a message by supplying a DataHandler.
void	attach(javax.activation.DataHandler dh, String description, String disposition) Attaches content to a message by supplying a DataHandler.
void	attach(File path, String name, String description) Adds an attachment with a specified name and description to a message by fetching its content from a local file.
void	attach(File path, String name, String description, String disposition) Adds an attachment with a specified name, description and disposition to a message by fetching its content from a local file.
void	attach(String data, String type, String name) Attaches a String to a message.
void	attach(String data, String type, String name, String description, String disposition) Attaches a String to a message.
void	attach(URL url, String name, String description) Adds an attachment with a specified name and description to a message by fetching its content from a URL.
void	attach(URL url, String name, String description, String disposition) Adds an attachment with a specified name, description and disposition to a message by fetching its content from a URL.
String	getEncoding() Returns the character encoding that is being used.
static String	getSmtpServer() Returns the SMTP mail host for debugging and account information.
void	send() Sends the message.
static void	send(String to, String from, String subject, String body) A convenience method to send a simple plain-text message.
void	setBcc(String bcc) Sets the email address that is being blind carbon-copied.
void	setBody(String body) Sets the body of the email to a simple plain text message.
void	setBody(String body, String alt) Sets the body of the email to an HTML encoded message with a plain text alternative.
void	setCc(String cc) Sets the email address that is being carbon-copied.
void	setEncoding(String enc) Sets the character encoding.
void	setFrom(String from) Sets the email address that the message is being sent from.
void	setHeaders(String headers) Sets the mail's MIME headers.
void	setMessageID(String messageID) Sets the Message ID
void	setReplyTo(String replyTo) Sets the replyTo address.
void	setSubject(String subject) Sets the subject of the message.
void	setTo(String to) Sets the email address that the message is being sent to.
void	writeTo(OutputStream os) Writes the content of the message to the given output stream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

INLINE

public static final String INLINE

Disposition of "inline"

See Also:

Constant Field Values

ATTACHMENT

public static final String ATTACHMENT

Disposition of "attachment"

See Also:

Constant Field Values

Constructor Detail

Mail

public Mail()

Default constructor. Must use the setTo, setSubject (and so on) methods to create a valid mail message.

Mail

public Mail(String to,
            String from,
            String subject)

Constructor used to specify to, from, and subject.

Parameters:

to - one or more of addresses to send the message to

from - the address the message is being sent from

subject - the subject for the message

Mail

public Mail(String to,
            String from,
            String subject,
            String body)

Constructor used to specify to, from, subject, and body.

Parameters:

to - one or more of addresses to send the message to

from - the address the message is being sent from

subject - the subject for the message

body - the plain text body of the message

Mail

public Mail(String to,
            String from,
            String subject,
            String body,
            String enc)

Constructor used to specify to, from, subject, body, and encoding.

Parameters:

to - one or more of addresses to send the message to

from - the address the message is being sent from

subject - the subject for the message

body - is plain text body of the message

enc - the encoding of the body

Method Detail

send

public static void send(String to,
                        String from,
                        String subject,
                        String body)
                 throws javax.mail.MessagingException,
                        javax.mail.SendFailedException

A convenience method to send a simple plain-text message.

Parameters:

to - one or more of addresses to send the message to

from - the address the message is being sent from

subject - the subject for the message

body - the plain text body of the message

Throws:

javax.mail.MessagingException

javax.mail.SendFailedException

send

public void send()
          throws javax.mail.MessagingException,
                 javax.mail.SendFailedException

Sends the message.

Throws:

javax.mail.MessagingException

javax.mail.SendFailedException

setTo

public void setTo(String to)

Sets the email address that the message is being sent to.

Parameters:

to - one or more addresses to send the message to

setFrom

public void setFrom(String from)

Sets the email address that the message is being sent from.

Parameters:

from - the address the message is sent from

setSubject

public void setSubject(String subject)

Sets the subject of the message.

Parameters:

subject - the subject of the message

setReplyTo

public void setReplyTo(String replyTo)

Sets the replyTo address.

Parameters:

replyTo - the address to use for replies

setMessageID

public void setMessageID(String messageID)

Sets the Message ID

Parameters:

messageID - unique identifier for each email.

setHeaders

public void setHeaders(String headers)

Sets the mail's MIME headers.

Parameters:

headers - a String containing MIME headers

addHeader

public void addHeader(String name,
                      String value)

Adds a header (name, value) pair.

Parameters:

name - the header element name

value - the header element value

setCc

public void setCc(String cc)

Sets the email address that is being carbon-copied.

Parameters:

cc - the email address for a carbon copy

setBcc

public void setBcc(String bcc)

Sets the email address that is being blind carbon-copied.

Parameters:

bcc - the email address for a blind carbon copy

setBody

public void setBody(String body)

Sets the body of the email to a simple plain text message.

Parameters:

body - the body of the message in plain text

setBody

public void setBody(String body,
                    String alt)

Sets the body of the email to an HTML encoded message with a plain text alternative.

Parameters:

body - the body of the message in HTML

alt - the alternate message body in plain text

setEncoding

public void setEncoding(String enc)

Sets the character encoding. Valid encodings include "us-ascii", "iso-8859-1" for w-Europe, "iso-8859-2" for e-Europe, and so on.

Parameters:

enc - the requested encoding

getEncoding

public String getEncoding()

Returns the character encoding that is being used. The default is "us-ascii".

Returns:

the string value of the character encoding being used

attach

public void attach(URL url,
                   String name,
                   String description)
            throws javax.mail.MessagingException

Adds an attachment with a specified name and description to a message by fetching its content from a URL. Sets the disposition to ATTACHMENT.

Parameters:

url - the URL to retreieve the content from

name - the name of the attachment

description - a description of the attachment

Throws:

javax.mail.MessagingException

attach

public void attach(URL url,
                   String name,
                   String description,
                   String disposition)
            throws javax.mail.MessagingException

Adds an attachment with a specified name, description and disposition to a message by fetching its content from a URL.

Parameters:

url - the URL to retreieve the content from

name - the name of the attachment

description - a description of the attachment

disposition - Mail.ATTACHMENT or Mail.INLINE

Throws:

javax.mail.MessagingException

attach

public void attach(File path,
                   String name,
                   String description)
            throws javax.mail.MessagingException

Adds an attachment with a specified name and description to a message by fetching its content from a local file. Sets the disposition to ATTACHMENT.

Parameters:

path - the file path to retreieve the content from

name - the name of the attachment

description - a description of the attachment

Throws:

javax.mail.MessagingException

attach

public void attach(File path,
                   String name,
                   String description,
                   String disposition)
            throws javax.mail.MessagingException

Adds an attachment with a specified name, description and disposition to a message by fetching its content from a local file.

Parameters:

path - the file path to retreieve the content from

name - the name of the attachment

description - a description of the attachment

disposition - Mail.ATTACHMENT or Mail.INLINE

Throws:

javax.mail.MessagingException

attach

public void attach(byte[] data,
                   String type,
                   String name)
            throws javax.mail.MessagingException

Attaches a byte array to a message. Sets the MIME type and name of the attachment, and initializes its disposition to ATTACHMENT.

Parameters:

data - the content of the attachment

type - the MIME type of the attachment

name - the name of the attachment

Throws:

javax.mail.MessagingException

attach

public void attach(byte[] data,
                   String type,
                   String name,
                   String description,
                   String disposition)
            throws javax.mail.MessagingException

Attaches a byte array to a message. Sets the MIME type, name, description and disposition of the attachment.

Parameters:

data - the content of the attachment

type - the MIME type of the attachment

name - the name of the attachment

description - a description of the attachment

disposition - Mail.ATTACHMENT or Mail.INLINE

Throws:

javax.mail.MessagingException

attach

public void attach(String data,
                   String type,
                   String name)
            throws javax.mail.MessagingException

Attaches a String to a message. Sets the MIME type and name of the attachment, and initializes the disposition to ATTACHMENT.

Parameters:

data - the content of the attachment

type - the MIME type of the attachment

name - the name of the attachment

Throws:

javax.mail.MessagingException

attach

public void attach(String data,
                   String type,
                   String name,
                   String description,
                   String disposition)
            throws javax.mail.MessagingException

Attaches a String to a message. Sets the MIME type, name, description and disposition of the attachment.

Parameters:

data - the content of the attachment

type - the MIME type of the attachment

name - the name of the attachment

description - a description of the attachment

disposition - Mail.ATTACHMENT or Mail.INLINE

Throws:

javax.mail.MessagingException

attach

public void attach(ByteArrayInputStream is,
                   String type,
                   String name)
            throws javax.mail.MessagingException

Attaches the content from a ByteArrayInputStream to a message. Sets the MIME type and name of the attachment, and initializes the disposition to ATTACHMENT.

Parameters:

is - the input stream to read from.

type - the MIME type of the attachment

name - the name of the attachment

Throws:

javax.mail.MessagingException

attach

public void attach(ByteArrayInputStream is,
                   String type,
                   String name,
                   String description,
                   String disposition)
            throws javax.mail.MessagingException

Attaches the content from a ByteArrayInputStream to a message. Sets the MIME type, name, description and disposition of the attachment.

Parameters:

is - the input stream to read from.

type - the MIME type of the attachment

name - the name of the attachment

description - a description of the attachment

disposition - Mail.ATTACHMENT or Mail.INLINE

Throws:

javax.mail.MessagingException

attach

protected void attach(ByteArrayDataSource dataSource,
                      String description,
                      String disposition)
               throws javax.mail.MessagingException

Attaches the content from a ByteArrayDataSource to a message. This is used internally by various other methods that take higher-level object types as input. The MIME type and name are determined directly from the dataSource.

Parameters:

dataSource - the data source to read from

description - a description of the attachment

disposition - Mail.ATTACHMENT or Mail.INLINE

Throws:

javax.mail.MessagingException

attach

public void attach(javax.activation.DataHandler dh)
            throws javax.mail.MessagingException

Attaches content to a message by supplying a DataHandler. All relevant parameters (MIME type, name, ...) are determined directly from the DataHandler.

Parameters:

dh - a DataHandler for some piece of content.

Throws:

javax.mail.MessagingException

attach

public void attach(javax.activation.DataHandler dh,
                   String description,
                   String disposition)
            throws javax.mail.MessagingException

Attaches content to a message by supplying a DataHandler. Sets the description and disposition of the content.

Parameters:

dh - the data source to read from

description - a description of the attachment

disposition - Mail.ATTACHMENT or Mail.INLINE

Throws:

javax.mail.MessagingException

getSmtpServer

public static String getSmtpServer()

Returns the SMTP mail host for debugging and account information.

Returns:

the SMTP mail host for debugging and account information.

writeTo

public void writeTo(OutputStream os)
             throws javax.mail.MessagingException

Writes the content of the message to the given output stream. Useful for debugging.

Parameters:

os - the output stream to write the message to

Throws:

javax.mail.MessagingException