com.arsdigita.mail
Class Mail

java.lang.Object
  extended bycom.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


Copyright (c) 2004 Red Hat, Inc. Corporation. All Rights Reserved. Generated at July 21 2004:2337 UTC