org.clapper.util.mail

Class EmailMessage

java.lang.Object

org.clapper.util.mail.EmailMessage

All Implemented Interfaces:

java.io.Serializable

public class EmailMessage
extends java.lang.Object
implements java.io.Serializable

The EmailMessage class is a simplified front-end to a portion of Sun's Java Mail API.

Overview

This class and package provides an easy-to-use API for composing and sending an email message, including simple single-part and more complicated multipart email messages. Using an EmailMessage object, a caller can compose and send a message consisting of an optional text part and zero or more MIME-encoded attachments. The message can have any number of recipients. The recipients can be

• primary ("To:") recipients
• "carbon copy" ("Cc:") recipients
• blind copy ("Bcc:") recipient

in any combination.

Once created and filled, an EmailMessage can be sent multiple times, through different SMTP servers if desired. To send an EmailMessage, use an EmailTransport object.

The EmailMessage class supports both the MIME "multipart/mixed" and "multipart/alternative" message types. According to RFC 1341, the differences between the two types are as follows:

How multipart types are handled

multipart/mixed

Intended for use when the body parts (i.e., the text and the attachments) are independent and intended to be displayed serially. For example, to send a text message with an attached image, you would use a "multipart/mixed" message.

multipart/alternative

Each of the parts (i.e., the main text part and the attachments) is an alternative version of the same information. The most typical "multipart/alternative" message contains a plain text part (i.e., MIME type "text/plain") and an HTML text part. Both contain the same text, but the HTML part has a "richer" version of it. The recipient's mail client should either display the "best" version of the message, based on the user's environments and preferences; or, it should offer the user a choice of which part to view. A mail reader that's capable of displaying HTML might choose to ignore the plain text part and display only the HTML attachment; by contrast, a mail reader that cannot render HTML might choose to display only the plain text part.

By default, an EmailMessage uses the "multipart/mixed" mode. To use "multipart/alternative", use the setMultipartSubtype() method, passing it the constant value MULTIPART_ALTERNATIVE. Note: You cannot change the subtype once you've added content to the message.

Examples

The following code builds and sends a message containing a simple text part and one attachment, a Zip file.

 EmailMessage message = new EmailMessage();

 message.setSubject ("The Zip file");
 message.setText ("Joe, here's the Zip file I promised.");
 message.setSender (new EmailAddress ("me@example.com"));
 message.addTo (new EmailAddress ("joe@example.com"));
 message.addAttachment (new File ("stuff.zip"));

 SMTPEmailTransport transport = new SMTPEmailTransport ("smtp.example.com");
 transport.send (message);

 message.clear();
 

Restrictions

As a simplified front-end, this class does have some restrictions, including the following.

• It cannot currently be used to read incoming email messages (e.g., from a POP3 or IMAP service).
• An EmailMessage object cannot be saved to "normal" email stores, though it can be serialized and unserialized.
• It doesn't handle multipart types other than "multipart/mixed" and "multipart/alternative".

For more complicated email interactions, use the Java Mail API directly.

Third-party Library Requirements

Note: This class requires the use of the Java Activation Framework (JAF) classes (package javax.activation) and the Java Mail API (package javax.mail). It was tested with the following Java Mail API and JAF versions:

• Java Mail API 1.1.2 and Java Activation Framework API 1.0
• Java Mail API 1.3.1 and Java Activation Framework API 1.0.2

Both APIs are available from java.sun.com.

See Also:

EmailTransport, SMTPEmailTransport, The Java Mail API home page, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static MultipartSubtype	MULTIPART_ALTERNATIVE Denotes a "multipart/alternative" message.
static MultipartSubtype	MULTIPART_MIXED Denotes a "multipart/mixed" message.

Constructor Summary

Constructors

Constructor and Description
EmailMessage() Constructs a new EmailMessage object.
EmailMessage(java.lang.String sender) Constructs a new EmailMessage object, with the specified sender address.

Method Summary

Modifier and Type	Method and Description
void	addAttachment(java.io.File file) Add an attachment from the contents of a file.
void	addAttachment(java.io.File file, java.lang.String mimeType) Add an attachment from the contents of a file.
void	addAttachment(java.io.File file, java.lang.String fileName, java.lang.String mimeType) Add an attachment from the contents of a file.
void	addAttachment(java.io.InputStream is) Add an attachment to this message from an InputStream object.
void	addAttachment(java.io.InputStream is, java.lang.String fileName) Add an attachment to this message from an InputStream object.
void	addAttachment(java.io.InputStream is, java.lang.String fileName, java.lang.String mimeType) Add a attachment to this message from an InputStream object.
void	addAttachment(java.util.Iterator iterator) Add a text attachment to this message from an Iterator of String objects.
void	addAttachment(java.util.Iterator iterator, java.lang.String fileName) Add a text attachment to this message from an Iterator of String objects.
void	addAttachment(java.util.Iterator iterator, java.lang.String fileName, java.lang.String mimeType) Add a text attachment to this message from an Iterator of String objects.
void	addAttachment(java.lang.String contents) Add a text attachment to this message.
void	addAttachment(java.lang.String[] contents) Add a text attachment to this message from an array of String objects.
void	addAttachment(java.lang.String[] contents, java.lang.String fileName) Add a text attachment to this message from an array of String objects.
void	addAttachment(java.lang.String[] text, java.lang.String fileName, java.lang.String mimeType) Add a text attachment to this message from an array of String objects.
void	addAttachment(java.lang.String contents, java.lang.String fileName) Add a text attachment to this message.
void	addAttachment(java.lang.String contents, java.lang.String fileName, java.lang.String mimeType) Add a text attachment to this message.
void	addBcc(java.util.Collection<?> emailAddresses) Add multiple email addresses to the list of "Bcc" addresses to receive this message.
void	addBcc(EmailAddress emailAddress) Add an email address to the list of "Bcc" (blind carbon copy) addresses to receive this message.
void	addBcc(java.lang.String emailAddress) Add an email address to the list of "Bcc" (blind carbon copy) addresses to receive this message.
void	addBcc(java.lang.String[] emailAddresses) Add multiple email addresses to the list of "Bcc" addresses to receive this message.
void	addCc(java.util.Collection<?> emailAddresses) Add multiple email addresses to the list of "Cc" addresses to receive this message.
void	addCc(EmailAddress emailAddress) Add an email address, in the form of an EmailAddress object, to the list of "Cc" addresses to receive this message.
void	addCc(java.lang.String emailAddress) Add an email address to the list of "Cc" addresses to receive this message.
void	addCc(java.lang.String[] emailAddresses) Add multiple email addresses to the list of "Cc" addresses to receive this message.
void	addHeader(java.lang.String header, java.lang.String value) Add a header to the outgoing message.
void	addTo(java.util.Collection<?> emailAddresses) Add multiple email addresses to the list of "To" addresses to receive this message.
void	addTo(EmailAddress emailAddress) Add an email address, in the form of an EmailAddress object, to the list of "To" addresses to receive this message.
void	addTo(java.lang.String emailAddress) Add an email address to the list of "To" addresses to receive this message.
void	addTo(java.lang.String[] emailAddresses) Add multiple email addresses to the list of "To" addresses to receive this message.
void	clear() Clear the message.
void	clearAllAttachments() Clear all attachments from this message.
void	clearAllRecipients() Clear all recipient addresses from this message.
void	clearBcc() Clear the list of "Bcc" addresses in this message, without clearing the "Cc" or "To" lists.
void	clearCc() Clear the list of "Cc" addresses in this message, without clearing the "To" or "Bcc" lists.
void	clearSubject() Clear this message's subject.
void	clearText() Clear the text portion of this message.
void	clearTo() Clear the list of "To" addresses in this message, without clearing the "Cc" or "Bcc" lists.
protected void	finalize() Destructor.
java.io.InputStream	getAttachment(int index) Get an attachment from the message.
java.lang.String	getAttachmentContentType(int index) Get the content type (i.e., MIME type) of a given attachment.
java.util.Collection<EmailAddress>	getBcc() Get the list of "Bcc" addresses to which this message will be sent.
java.util.Collection<EmailAddress>	getCc() Get the list of "Cc" addresses to which this message will be sent.
MultipartSubtype	getMultipartSubtype() Get this message's multipart subtype value.
EmailAddress	getSender() Get the email address that will be used as the sender.
java.lang.String	getSubject() Get the subject of this message.
java.lang.String	getText() Get the text portion of the message.
java.util.Collection<EmailAddress>	getTo() Get the list of "To" addresses to which this message will be sent.
void	setMultipartSubtype(MultipartSubtype subType) Set the multipart subtype.
void	setSender(EmailAddress senderAddress) Set the sender's email address.
void	setSender(java.lang.String senderAddress) Set the sender's email address.
void	setSubject(java.lang.String subject) Set the subject of this message.
void	setText(java.io.File file) Set the text part of the message from the contents of a file.
void	setText(java.io.File file, java.lang.String mimeType) Set the text part of the message from the contents of a file.
void	setText(java.io.File file, java.lang.String fileName, java.lang.String mimeType) Set the text part of the message from the contents of a file, allowing the caller to specify the file name to use when identifying the text part.
void	setText(java.io.InputStream is) Set the text part of the message from an InputStream object.
void	setText(java.io.InputStream is, java.lang.String fileName) Set the text part of the message from an InputStream object.
void	setText(java.io.InputStream is, java.lang.String fileName, java.lang.String mimeType) Set the text part of the message from an InputStream object.
void	setText(java.util.Iterator iterator) Set the text part of the message from Iterator of String objects.
void	setText(java.util.Iterator iterator, java.lang.String mimeType) Set the text part of the message from Iterator of String objects.
void	setText(java.util.Iterator iterator, java.lang.String fileName, java.lang.String mimeType) Set the text part of the message from an Iterator of String objects.
void	setText(java.lang.String text) Set the text part of the message from a String object.
void	setText(java.lang.String[] text) Set the text part of the message from an array of String objects.
void	setText(java.lang.String[] text, java.lang.String fileName) Set the text part of the message from an array of String objects.
void	setText(java.lang.String[] text, java.lang.String fileName, java.lang.String mimeType) Set the text part of the message from an array of String objects.
void	setText(java.lang.String text, java.lang.String fileName) Set the text part of the message from a String object.
void	setText(java.lang.String text, java.lang.String fileName, java.lang.String mimeType) Set the text part of the message from a String object.
int	totalAttachments() Get the total number of attachments, not counting the text part, in this message.

Methods inherited from class java.lang.Object

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

Field Detail

MULTIPART_MIXED

public static final MultipartSubtype MULTIPART_MIXED

Denotes a "multipart/mixed" message. This is the default.

See Also:

setMultipartSubtype(MultipartSubtype)

MULTIPART_ALTERNATIVE

public static final MultipartSubtype MULTIPART_ALTERNATIVE

Denotes a "multipart/alternative" message.

See Also:

setMultipartSubtype(MultipartSubtype)

Constructor Detail

EmailMessage

public EmailMessage()

Constructs a new EmailMessage object. The sender's address is built from the system's user.name property and the SMTP host name.

EmailMessage

public EmailMessage(java.lang.String sender)
             throws EmailException

Constructs a new EmailMessage object, with the specified sender address. Note: This method does not call setSender(java.lang.String), because setSender(java.lang.String) might be overridden by a subclass. (Calling an overridable method from a constructor is dangerous.)

Parameters:

sender - The email address of the sender. If this parameter is null, the sender's address is built from the system's user.name property and the host name of the SMTP server used to send the message.

Throws:

EmailException - improperly formed email address

See Also:

EmailTransport.send(EmailMessage)

Method Detail

finalize

protected void finalize()
                 throws java.lang.Throwable

Destructor.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

clear

public void clear()

Clear the message. This method clears all fields except the SMTP host. Specifically, this method:

• Clears the lists of To, Cc and Bcc recipients
• Clears the text part
• Clears and removes all attachments
• Deletes any temporary files that were created to store attachments
• Clears the sender field
• Resets the message type to MULTIPART_MIXED

The cleared EmailMessage can then be used for a fresh message.

NOTE: It's a good idea to call this method when you're finished with the message; it ensures that the resources used by the message--including temporary files for certain kinds of attachments--are released. The finalizer calls this method, but the finalizer might not fire right away (and, on some platforms, in some circumstances, the finalizer may not fire at all).

See Also:

clearTo(), clearBcc(), clearCc(), clearAllRecipients(), clearText()

addHeader

public void addHeader(java.lang.String header,
                      java.lang.String value)

Add a header to the outgoing message. Note that callers should never use this method to add "Received" headers, "To" headers, "Cc" headers, or any other "official" header. Non-standard headers should typically be prefixed with "X-" (e.g., "X-Mailing-List"). The specified header replaces any existing header with the same name. This class defines its own default "X-Mailer" header; however, the calling application is free to override that default header by adding its own.

Parameters:

header - the header name (e.g., "X-Mailer", "X-Mailing-List", etc."), without the trailing ":".

value - the value for the header

addTo

public void addTo(java.lang.String emailAddress)
           throws EmailException

Add an email address to the list of "To" addresses to receive this message. The address can be any RFC822-compliant email address. Examples include:

 
 moe@example.com
 Moe Howard <moe@example.com>
 "Curley Howard" <curley@example.com>
 larry@example.com (Larry Fine)
 
 

If you want to validate the address before calling this method, simply pass it to the constructor of an EmailAddress object.

Parameters:

emailAddress - the email address to add

Throws:

EmailException - improperly formed email address

See Also:

addTo(String[]), addTo(EmailAddress), getTo(), clearTo(), addCc(java.lang.String), addBcc(java.lang.String), clearAllRecipients(), EmailAddress

addTo

public void addTo(EmailAddress emailAddress)
           throws EmailException

Add an email address, in the form of an EmailAddress object, to the list of "To" addresses to receive this message.

Parameters:

emailAddress - the email address to add

Throws:

EmailException - on error

See Also:

addTo(String[]), addTo(String), getTo(), clearTo(), addCc(java.lang.String), addBcc(java.lang.String), clearAllRecipients(), EmailAddress

addTo

public void addTo(java.lang.String[] emailAddresses)
           throws EmailException

Add multiple email addresses to the list of "To" addresses to receive this message.

Parameters:

emailAddresses - the email addresses to add

Throws:

EmailException - improperly formed email address

See Also:

addTo(String), addTo(Collection), getTo(), clearTo(), addCc(String[]), addBcc(String[]), clearAllRecipients()

addTo

public void addTo(java.util.Collection<?> emailAddresses)
           throws EmailException

Add multiple email addresses to the list of "To" addresses to receive this message.

Parameters:

emailAddresses - A Collection of the email addresses. The Collection can contain String or EmailAddress objects.

Throws:

EmailException - improperly formed email address

See Also:

addTo(String[]), addTo(String), addTo(EmailAddress), getTo(), clearTo(), addCc(Collection), addBcc(Collection), clearAllRecipients(), EmailAddress

getTo

public java.util.Collection<EmailAddress> getTo()
                                         throws EmailException

Get the list of "To" addresses to which this message will be sent.

Returns:

a Collection of email addresses. Each object in the returned Collection is an EmailAddress object. If there are no "To" addresses, an empty Collection is returned.

Throws:

EmailException - error retrieving addresses

See Also:

addTo(String), addTo(String[]), clearTo(), EmailAddress

clearTo

public void clearTo()

Clear the list of "To" addresses in this message, without clearing the "Cc" or "Bcc" lists.

See Also:

addTo(String), addTo(String[]), getTo(), clearCc(), clearBcc(), clearAllRecipients()

addCc

public void addCc(java.lang.String emailAddress)
           throws EmailException

Add an email address to the list of "Cc" addresses to receive this message. The address can be any RFC822-compliant email address. Examples include:

 
 moe@example.com
 Moe Howard <moe@example.com>
 "Curley Howard" <curley@example.com>
 larry@example.com (Larry Fine)
 
 

If you want to validate the address before calling this method, simply pass it to the constructor of an EmailAddress object.

Parameters:

emailAddress - the email address to add

Throws:

EmailException - improperly formed email address

See Also:

addCc(String[]), addCc(EmailAddress), getCc(), clearCc(), addTo(String), addBcc(String), clearAllRecipients(), EmailAddress

addCc

public void addCc(EmailAddress emailAddress)
           throws EmailException

Add an email address, in the form of an EmailAddress object, to the list of "Cc" addresses to receive this message.

Parameters:

emailAddress - the email address to add

Throws:

EmailException - improperly formed email address

See Also:

addCc(String[]), addCc(String), getCc(), clearCc(), addTo(String), addBcc(String), clearAllRecipients(), EmailAddress

addCc

public void addCc(java.lang.String[] emailAddresses)
           throws EmailException

Add multiple email addresses to the list of "Cc" addresses to receive this message.

Parameters:

emailAddresses - the email addresses to add

Throws:

EmailException - improperly formed email address

See Also:

addCc(String), addCc(Collection), getTo(), clearTo(), addTo(String[]), addBcc(String[]), clearAllRecipients()

addCc

public void addCc(java.util.Collection<?> emailAddresses)
           throws EmailException

Add multiple email addresses to the list of "Cc" addresses to receive this message.

Parameters:

emailAddresses - A Collection of the email addresses. The Collection can contain String or EmailAddress objects.

Throws:

EmailException - improperly formed email address

See Also:

addCc(String[]), addCc(String), addCc(EmailAddress), getCc(), clearCc(), addTo(Collection), addBcc(Collection), clearAllRecipients(), EmailAddress

getCc

public java.util.Collection<EmailAddress> getCc()
                                         throws EmailException

Get the list of "Cc" addresses to which this message will be sent.

Returns:

a Collection of email addresses. Each object in the returned Collection is an EmailAddress object. If there are no "Cc" addresses, an empty Collection is returned.

Throws:

EmailException - error retrieving addresses

See Also:

addCc(String), addCc(String[]), clearCc(), EmailAddress

clearCc

public void clearCc()

Clear the list of "Cc" addresses in this message, without clearing the "To" or "Bcc" lists.

See Also:

addCc(String), addCc(String[]), getCc(), clearTo(), clearBcc(), clearAllRecipients()

addBcc

public void addBcc(java.lang.String emailAddress)
            throws EmailException

Add an email address to the list of "Bcc" (blind carbon copy) addresses to receive this message. The address can be any RFC822-compliant email address. Examples include:

 
 moe@example.com
 Moe Howard <moe@example.com>
 "Curley Howard" <curley@example.com>
 larry@example.com (Larry Fine)
 
 

If you want to validate the address before calling this method, simply pass it to the constructor of an EmailAddress object.

Parameters:

emailAddress - the email address to add

Throws:

EmailException - improperly formed email address

See Also:

addBcc(String[]), addBcc(EmailAddress), getBcc(), clearBcc(), addCc(String), addTo(String), clearAllRecipients(), EmailAddress

addBcc

public void addBcc(EmailAddress emailAddress)
            throws EmailException

Add an email address to the list of "Bcc" (blind carbon copy) addresses to receive this message.

Parameters:

emailAddress - the email address to add

Throws:

EmailException - improperly formed email address

See Also:

addBcc(String[]), addBcc(String), getBcc(), clearBcc(), addCc(String), addTo(String), clearAllRecipients(), EmailAddress

addBcc

public void addBcc(java.lang.String[] emailAddresses)
            throws EmailException

Add multiple email addresses to the list of "Bcc" addresses to receive this message.

Parameters:

emailAddresses - the email addresses to add

Throws:

EmailException - improperly formed email address

See Also:

addBcc(String), addBcc(Collection), getTo(), clearTo(), addTo(Collection), addCc(Collection), clearAllRecipients()

addBcc

public void addBcc(java.util.Collection<?> emailAddresses)
            throws EmailException

Add multiple email addresses to the list of "Bcc" addresses to receive this message.

Parameters:

emailAddresses - A Collection of the email addresses. The Collection can contain String or EmailAddress objects.

Throws:

EmailException - improperly formed email address

See Also:

addBcc(String[]), addBcc(String), addBcc(EmailAddress), getBcc(), clearBcc(), addTo(Collection), addCc(Collection), clearAllRecipients(), EmailAddress

getBcc

public java.util.Collection<EmailAddress> getBcc()
                                          throws EmailException

Get the list of "Bcc" addresses to which this message will be sent.

Returns:

a Collection of email addresses. Each object in the returned Collection is an EmailAddress object. If there are no "Bcc" addresses, an empty Collection is returned.

Throws:

EmailException - error retrieving addresses

See Also:

addBcc(String), addBcc(String[]), clearBcc(), EmailAddress

clearBcc

public void clearBcc()

Clear the list of "Bcc" addresses in this message, without clearing the "Cc" or "To" lists.

See Also:

addBcc(String), addBcc(String[]), getBcc(), clearCc(), clearTo(), clearAllRecipients()

clearAllRecipients

public void clearAllRecipients()

Clear all recipient addresses from this message. Calling this method is equivalent to:

 
 message.clearTo();
 message.clearCc();
 message.clearBcc();
 
 

setMultipartSubtype

public void setMultipartSubtype(MultipartSubtype subType)
                         throws EmailException

Set the multipart subtype. By default, the multipart subtype is set to MultipartSubtype.MIXED; that is, the text and the attachments are distinct, separate items. The only other possible value is MultipartSubtype.ALTERNATIVE, which signifies that each of the parts is an "alternative" version of the same information. See the class documentation for more details.

Note: You must set the subtype before adding the text part and any attachments! The attachments are encoded as you add them to the message, and the encoded format can differ depending on the subtype.

Parameters:

subType - the desired subtype

Throws:

EmailException - message already has attachments, so subtype cannot be changed

See Also:

getMultipartSubtype(), MULTIPART_MIXED, MULTIPART_ALTERNATIVE

getMultipartSubtype

public MultipartSubtype getMultipartSubtype()

Get this message's multipart subtype value.

Returns:

the multipart subtype

See Also:

setMultipartSubtype(org.clapper.util.mail.MultipartSubtype)

getText

public java.lang.String getText()
                         throws EmailException

Get the text portion of the message.

Returns:

a String containing the text, or null if there's no text part in the message

Throws:

EmailException - on error

See Also:

setText(String), setText(String,String), setText(String,String,String), setText(String[],String,String), setText(InputStream,String), setText(InputStream,String,String), setText(Iterator), setText(Iterator,String), setText(Iterator,String,String), setText(File)

setText

public void setText(java.lang.String text)
             throws EmailException

Set the text part of the message from a String object. The corresponding MIME type is assumed to be "text/plain". If this message already has a text part, it will be replaced.

Parameters:

text - The string to use as the text of the message. It may contain multiple lines.

Throws:

EmailException - error setting text part of message

See Also:

getText(), setText(String,String), setText(String,String,String), setText(String[],String), setText(String[],String,String), setText(InputStream,String), setText(InputStream,String,String), setText(Iterator), setText(Iterator,String), setText(Iterator,String,String), setText(File), setText(File,String), clearText()

setText

public void setText(java.lang.String text,
                    java.lang.String fileName)
             throws EmailException

Set the text part of the message from a String object. The corresponding MIME type is assumed to be "text/plain". If this message already has a text part, it will be replaced.

Parameters:

text - The string to use as the text of the message. It may contain multiple lines.

fileName - File name to associate with attachment, or null for generated one

Throws:

EmailException - error setting text part of message

See Also:

getText(), setText(String,String,String), setText(String[],String), setText(String[],String,String), setText(InputStream,String), setText(InputStream,String,String), setText(Iterator), setText(Iterator,String), setText(Iterator,String,String), setText(File), setText(File,String), clearText()

setText

public void setText(java.lang.String text,
                    java.lang.String fileName,
                    java.lang.String mimeType)
             throws EmailException

Set the text part of the message from a String object. If this message already has a text part, it will be replaced.

Parameters:

text - The string to use as the text of the message. It may contain multiple lines.

fileName - File name to associate with attachment, or null for generated one

mimeType - The MIME type for the text

Throws:

EmailException - error setting text part of message

See Also:

getText(), setText(String,String), setText(String[],String), setText(String[],String,String), setText(InputStream,String), setText(InputStream,String,String), setText(Iterator), setText(Iterator,String), setText(Iterator,String,String), setText(File), setText(File,String), clearText()

setText

public void setText(java.lang.String[] text)
             throws EmailException

Set the text part of the message from an array of String objects. Each element in the array is assumed to represent a single line of text. The corresponding MIME type is assumed to be "text/plain". If this message already has a text part, it will be replaced.

Parameters:

text - The strings to use as the text of the message.

Throws:

EmailException - error setting text part of message

See Also:

getText(), setText(String,String), setText(String,String,String), setText(String[],String), setText(String[],String,String), setText(InputStream,String), setText(InputStream,String,String), setText(Iterator), setText(Iterator,String), setText(Iterator,String,String), setText(File), setText(File,String), clearText()

setText

public void setText(java.lang.String[] text,
                    java.lang.String fileName)
             throws EmailException

Set the text part of the message from an array of String objects. Each element in the array is assumed to represent a single line of text. The corresponding MIME type is assumed to be "text/plain". If this message already has a text part, it will be replaced.

Parameters:

text - The strings to use as the text of the message.

fileName - The file name for the attachment

Throws:

EmailException - error setting text part of message

See Also:

getText(), setText(String,String), setText(String,String,String), setText(String[]), setText(String[],String,String), setText(InputStream,String), setText(InputStream,String,String), setText(Iterator), setText(Iterator,String), setText(Iterator,String,String), setText(File), setText(File,String), clearText()

setText

public void setText(java.lang.String[] text,
                    java.lang.String fileName,
                    java.lang.String mimeType)
             throws EmailException

Set the text part of the message from an array of String objects. Each element in the array is assumed to represent a single line of text. If this message already has a text part, it will be replaced.

Parameters:

text - The strings to use as the text of the message.

fileName - File name to associate with attachment, or null for generated one

mimeType - The MIME type for the text

Throws:

EmailException - error setting text part of message

See Also:

getText(), setText(String,String), setText(String,String,String), setText(String[]), setText(String[],String), setText(String[],String,String), setText(InputStream,String), setText(InputStream,String,String), setText(Iterator), setText(Iterator,String), setText(Iterator,String,String), setText(File), setText(File,String), clearText()

setText

public void setText(java.io.InputStream is)
             throws EmailException

Set the text part of the message from an InputStream object. The corresponding MIME type is assumed to be "text/plain". If this message already has a text part, it will be replaced.

Parameters:

is - The InputStream whose contents are to be read and fed into the text part of this message

Throws:

EmailException - error setting text part of message

See Also:

getText(), setText(String,String), setText(String,String,String), setText(String[],String,String), setText(InputStream,String), setText(InputStream,String,String), setText(Iterator), setText(Iterator,String), setText(Iterator,String,String), setText(File,String), setText(File), clearText()

setText

public void setText(java.io.InputStream is,
                    java.lang.String fileName)
             throws EmailException

Set the text part of the message from an InputStream object. The corresponding MIME type is assumed to be "text/plain". If this message already has a text part, it will be replaced.

Parameters:

is - The InputStream whose contents are to be read and fed into the text part of this message

fileName - File name to associate with attachment, or null for generated one

Throws:

EmailException - error setting text part of message

See Also:

getText(), setText(String,String), setText(String,String,String), setText(String[],String,String), setText(InputStream,String), setText(InputStream,String,String), setText(Iterator), setText(Iterator,String), setText(Iterator,String,String), setText(File,String), setText(File), clearText()

setText

public void setText(java.io.InputStream is,
                    java.lang.String fileName,
                    java.lang.String mimeType)
             throws EmailException

Set the text part of the message from an InputStream object. If this message already has a text part, it will be replaced.

Parameters:

is - The InputStream whose contents are to be read and fed into the text part of this message

fileName - File name to associate with attachment, or null for generated one

mimeType - The MIME type for the text

Throws:

EmailException - error setting text part of message

See Also:

getText(), setText(String,String), setText(String,String,String), setText(String[],String,String), setText(InputStream,String), setText(InputStream,String,String), setText(Iterator), setText(Iterator,String), setText(Iterator,String,String), setText(File), setText(File,String), clearText()

setText

public void setText(java.util.Iterator iterator)
             throws EmailException

Set the text part of the message from Iterator of String objects. Each element returned by the iterator is assumed to represent a single line of text. The corresponding MIME type is assumed to be "text/plain". If this message already has a text part, it will be replaced.

Parameters:

iterator - The Iterator that will return the String objects that represent the text lines

Throws:

EmailException - error setting text part of message

See Also:

getText(), setText(String,String), setText(String,String,String), setText(String[],String,String), setText(InputStream,String), setText(InputStream,String,String), setText(Iterator,String), setText(Iterator,String,String), setText(File), setText(File,String), clearText()

setText

public void setText(java.util.Iterator iterator,
                    java.lang.String mimeType)
             throws EmailException

Set the text part of the message from Iterator of String objects. Each element returned by the iterator is assumed to represent a single line of text. The corresponding MIME type is assumed to be "text/plain". If this message already has a text part, it will be replaced.

Parameters:

iterator - The Iterator that will return the String objects that represent the text lines

mimeType - The MIME type for the text

Throws:

EmailException - error setting text part of message

See Also:

getText(), setText(String,String), setText(String,String,String), setText(String[],String,String), setText(InputStream,String), setText(InputStream,String,String), setText(Iterator), setText(Iterator,String,String), setText(File), setText(File,String), clearText()

setText

public void setText(java.util.Iterator iterator,
                    java.lang.String fileName,
                    java.lang.String mimeType)
             throws EmailException

Set the text part of the message from an Iterator of String objects. Each element returned by the iterator is assumed to represent a single line of text. If this message already has a text part, it will be replaced.

Parameters:

iterator - The Iterator that will return the String objects that represent the text lines

fileName - File name to associate with attachment, or null for generated one

mimeType - The MIME type for the text

Throws:

EmailException - error setting text part of message

See Also:

getText(), setText(String,String), setText(String,String,String), setText(String[],String,String), setText(InputStream,String), setText(InputStream,String,String), setText(Iterator), setText(Iterator,String), setText(File), setText(File,String), clearText()

setText

public void setText(java.io.File file)
             throws EmailException

Set the text part of the message from the contents of a file. The MIME type is taken from the file's extension. If this message already has a text part, it will be replaced.

Parameters:

file - The File object from which to get the text

Throws:

EmailException - error setting text part of message

See Also:

getText(), setText(File,String), setText(String,String), setText(String,String,String), setText(String[],String,String), setText(InputStream,String), setText(InputStream,String,String), setText(Iterator), setText(Iterator,String), setText(Iterator,String,String), clearText()

setText

public void setText(java.io.File file,
                    java.lang.String mimeType)
             throws EmailException

Set the text part of the message from the contents of a file. If this message already has a text part, it will be replaced. The text part's file name will be taken from the File object.

Parameters:

file - The File object from which to get the text

mimeType - The MIME type to associate with the text part, or null to assume the default based on the file extension

Throws:

EmailException - error setting text part of message

See Also:

getText(), setText(File), setText(String,String), setText(String,String,String), setText(String[],String,String), setText(InputStream,String), setText(InputStream,String,String), setText(Iterator), setText(Iterator,String), setText(Iterator,String,String), clearText()

setText

public void setText(java.io.File file,
                    java.lang.String fileName,
                    java.lang.String mimeType)
             throws EmailException

Set the text part of the message from the contents of a file, allowing the caller to specify the file name to use when identifying the text part. If this message already has a text part, it will be replaced.

Parameters:

file - The File object from which to get the text

fileName - The file name to use

mimeType - The MIME type to associate with the text part, or null to assume the default based on the file extension

Throws:

EmailException - error setting text part of message

See Also:

getText(), setText(File), setText(String,String), setText(String,String,String), setText(String[],String,String), setText(InputStream,String), setText(InputStream,String,String), setText(Iterator), setText(Iterator,String), setText(Iterator,String,String), clearText()

clearText

public void clearText()

Clear the text portion of this message. Note: Removing the text portion does not remove any attachments.

See Also:

getText(), setText(String), setText(String,String), setText(String,String,String), setText(String[],String), setText(String[],String,String), setText(InputStream), setText(InputStream,String), setText(InputStream,String,String), setText(Iterator), setText(Iterator,String), setText(Iterator,String,String), setText(File), clearAllAttachments()

getAttachment

public java.io.InputStream getAttachment(int index)
                                  throws java.lang.ArrayIndexOutOfBoundsException,
                                         EmailException

Get an attachment from the message. Since the attachment can consist of any type of data, this method simply returns an InputStream that can be used to read the bytes of the attachment.

Parameters:

index - The 0-based index of the attachment. Index 0 corresponds to the first attachment (not including the text part), index 1 corresponds to the second attachment, etc.

Returns:

an InputStream for reading the attachment's contents

Throws:

java.lang.ArrayIndexOutOfBoundsException - index is out of range

EmailException - error retrieving attachment

See Also:

getAttachmentContentType(int), totalAttachments(), addAttachment(String,String), addAttachment(String,String,String), addAttachment(String[],String), addAttachment(String[],String,String), addAttachment(InputStream,String), addAttachment(InputStream,String,String), addAttachment(Iterator,String), addAttachment(Iterator,String,String), addAttachment(File), addAttachment(File,String)

getAttachmentContentType

public java.lang.String getAttachmentContentType(int index)
                                          throws java.lang.ArrayIndexOutOfBoundsException,
                                                 EmailException

Get the content type (i.e., MIME type) of a given attachment.

Parameters:

index - The 0-based index of the attachment. Index 0 corresponds to the first attachment (not including the text part), index 1 corresponds to the second attachment, etc.

Returns:

the attachment's MIME type

Throws:

java.lang.ArrayIndexOutOfBoundsException - index is out of range

EmailException - error retrieving attachment

See Also:

getAttachment(int), totalAttachments(), addAttachment(String,String), addAttachment(String,String,String), addAttachment(String[],String), addAttachment(String[],String,String), addAttachment(InputStream,String), addAttachment(InputStream,String,String), addAttachment(Iterator,String), addAttachment(Iterator,String,String), addAttachment(File), addAttachment(File,String)

totalAttachments

public int totalAttachments()

Get the total number of attachments, not counting the text part, in this message.

Returns:

the total number of attachments in this message

See Also:

getAttachment(int), getAttachmentContentType(int), addAttachment(String,String), addAttachment(String,String,String), addAttachment(String[],String), addAttachment(String[],String,String), addAttachment(InputStream,String), addAttachment(InputStream,String,String), addAttachment(Iterator,String), addAttachment(Iterator,String,String), addAttachment(File), addAttachment(File,String)

addAttachment

public void addAttachment(java.lang.String contents)
                   throws EmailException

Add a text attachment to this message. The attachment's MIME type is assumed to be "text/plain". The attachment is added onto the end of the attachments in the message.

Parameters:

contents - The string to use as the attachment's contents. It may contain multiple lines.

Throws:

EmailException - error creating the attachment

See Also:

addAttachment(String,String), addAttachment(String[],String), addAttachment(String[],String,String), addAttachment(InputStream,String), addAttachment(InputStream,String,String), addAttachment(Iterator,String), addAttachment(Iterator,String,String), addAttachment(File), addAttachment(File,String), getAttachment(int), getAttachmentContentType(int), totalAttachments()

addAttachment

public void addAttachment(java.lang.String contents,
                          java.lang.String fileName)
                   throws EmailException

Add a text attachment to this message. The attachment's MIME type is assumed to be "text/plain". The attachment is added onto the end of the attachments in the message.

Parameters:

contents - The string to use as the attachment's contents. It may contain multiple lines.

fileName - The file name for the attachment

Throws:

EmailException - error creating the attachment

See Also:

addAttachment(String,String), addAttachment(String[],String), addAttachment(String[],String,String), addAttachment(InputStream,String), addAttachment(InputStream,String,String), addAttachment(Iterator,String), addAttachment(Iterator,String,String), addAttachment(File), addAttachment(File,String), getAttachment(int), getAttachmentContentType(int), totalAttachments()

addAttachment

public void addAttachment(java.lang.String contents,
                          java.lang.String fileName,
                          java.lang.String mimeType)
                   throws EmailException

Add a text attachment to this message. The attachment is added onto the end of the attachments in the message.

Parameters:

contents - The string to use as the attachment's contents. It may contain multiple lines.

fileName - The file name for the attachment

mimeType - The MIME type for the attachment

Throws:

EmailException - error adding the attachment

See Also:

addAttachment(String,String), addAttachment(String[],String), addAttachment(String[],String,String), addAttachment(InputStream,String), addAttachment(InputStream,String,String), addAttachment(Iterator,String), addAttachment(Iterator,String,String), addAttachment(File), addAttachment(File,String), getAttachment(int), getAttachmentContentType(int), totalAttachments()

addAttachment

public void addAttachment(java.lang.String[] contents)
                   throws EmailException

Add a text attachment to this message from an array of String objects. Each element in the array is assumed to represent a single line of text. The corresponding MIME type is assumed to be "text/plain".

Parameters:

contents - The strings to use as the attachment's contents

Throws:

EmailException - error adding the attachment

See Also:

addAttachment(String,String), addAttachment(String,String,String), addAttachment(String[],String,String), addAttachment(InputStream,String), addAttachment(InputStream,String,String), addAttachment(Iterator,String), addAttachment(Iterator,String,String), addAttachment(File), addAttachment(File,String), getAttachment(int), getAttachmentContentType(int), totalAttachments()

addAttachment

public void addAttachment(java.lang.String[] contents,
                          java.lang.String fileName)
                   throws EmailException

Add a text attachment to this message from an array of String objects. Each element in the array is assumed to represent a single line of text. The corresponding MIME type is assumed to be "text/plain".

Parameters:

contents - The strings to use as the attachment's contents

fileName - The file name for the attachment

Throws:

EmailException - error adding the attachment

See Also:

addAttachment(String,String), addAttachment(String,String,String), addAttachment(String[],String,String), addAttachment(InputStream,String), addAttachment(InputStream,String,String), addAttachment(Iterator,String), addAttachment(Iterator,String,String), addAttachment(File), addAttachment(File,String), getAttachment(int), getAttachmentContentType(int), totalAttachments()

addAttachment

public void addAttachment(java.lang.String[] text,
                          java.lang.String fileName,
                          java.lang.String mimeType)
                   throws EmailException

Add a text attachment to this message from an array of String objects. Each element in the array is assumed to represent a single line of text.

Parameters:

text - The strings to use as the text of the message.

fileName - The file name for the attachment

mimeType - The MIME type for the text

Throws:

EmailException - error adding the attachment

See Also:

addAttachment(String,String), addAttachment(String,String,String), addAttachment(String[],String,String), addAttachment(InputStream,String), addAttachment(InputStream,String,String), addAttachment(Iterator,String), addAttachment(Iterator,String,String), addAttachment(File), getAttachment(int), getAttachmentContentType(int), totalAttachments()

addAttachment

public void addAttachment(java.io.InputStream is)
                   throws EmailException

Add an attachment to this message from an InputStream object. The corresponding MIME type is assumed to be "application/octet-stream".

Parameters:

is - The InputStream whose contents are to be read to create the attachment

Throws:

EmailException - error adding the attachment

See Also:

addAttachment(String), addAttachment(String,String), addAttachment(String[],String), addAttachment(InputStream), addAttachment(InputStream,String), addAttachment(Iterator), addAttachment(Iterator,String), addAttachment(File), addAttachment(File,String), getAttachment(int), getAttachmentContentType(int), totalAttachments()

addAttachment

public void addAttachment(java.io.InputStream is,
                          java.lang.String fileName)
                   throws EmailException

Add an attachment to this message from an InputStream object. The corresponding MIME type is assumed to be "application/octet-stream".

Parameters:

is - The InputStream whose contents are to be read to create the attachment

fileName - the file name to use for the attachment, or null for a generated one

Throws:

EmailException - error adding the attachment

See Also:

addAttachment(String), addAttachment(String,String), addAttachment(String[],String), addAttachment(InputStream), addAttachment(InputStream,String), addAttachment(Iterator), addAttachment(Iterator,String), addAttachment(File), addAttachment(File,String), getAttachment(int), getAttachmentContentType(int), totalAttachments()

addAttachment

public void addAttachment(java.io.InputStream is,
                          java.lang.String fileName,
                          java.lang.String mimeType)
                   throws EmailException

Add a attachment to this message from an InputStream object.

Parameters:

is - The InputStream whose contents are to be read to create the attachment

fileName - The file name for the attachment

mimeType - The MIME type

Throws:

EmailException - error adding the attachment

See Also:

addAttachment(String), addAttachment(String,String), addAttachment(String[],String), addAttachment(InputStream), addAttachment(InputStream,String), addAttachment(Iterator), addAttachment(Iterator,String), addAttachment(File), addAttachment(File,String), getAttachment(int), getAttachmentContentType(int), totalAttachments()

addAttachment

public void addAttachment(java.util.Iterator iterator)
                   throws EmailException

Add a text attachment to this message from an Iterator of String objects. Each element in the array is assumed to represent a single line of text. The corresponding MIME type is assumed to be "text/plain".

Parameters:

iterator - The Iterator that will return the String objects that represent the text lines

Throws:

EmailException - error adding the attachment

See Also:

addAttachment(String), addAttachment(String,String), addAttachment(String[],String), addAttachment(InputStream), addAttachment(InputStream,String), addAttachment(Iterator,String), addAttachment(File), addAttachment(File,String), getAttachment(int), getAttachmentContentType(int), totalAttachments()

addAttachment

public void addAttachment(java.util.Iterator iterator,
                          java.lang.String fileName)
                   throws EmailException

Add a text attachment to this message from an Iterator of String objects. Each element in the array is assumed to represent a single line of text. The corresponding MIME type is assumed to be "text/plain".

Parameters:

iterator - The Iterator that will return the String objects that represent the text lines

fileName - The file name for the attachment

Throws:

EmailException - error adding the attachment

See Also:

addAttachment(String), addAttachment(String,String), addAttachment(String[],String), addAttachment(InputStream), addAttachment(InputStream,String), addAttachment(Iterator,String), addAttachment(File), addAttachment(File,String), getAttachment(int), getAttachmentContentType(int), totalAttachments()

addAttachment

public void addAttachment(java.util.Iterator iterator,
                          java.lang.String fileName,
                          java.lang.String mimeType)
                   throws EmailException

Add a text attachment to this message from an Iterator of String objects. Each element in the array is assumed to represent a single line of text. The corresponding MIME type is assumed to be "text/plain". Set the text part of the message from an Iterator of String objects. Each element in the array is assumed to represent a single line of text.

Parameters:

iterator - The Iterator that will return the String objects that represent the text lines

fileName - The file name for the attachment, or null to use a generated one.

mimeType - The MIME type for the text

Throws:

EmailException - error adding the attachment

See Also:

addAttachment(String), addAttachment(String,String), addAttachment(String[],String), addAttachment(InputStream), addAttachment(InputStream,String), addAttachment(Iterator), addAttachment(File), addAttachment(File,String), getAttachment(int), getAttachmentContentType(int), totalAttachments()

addAttachment

public void addAttachment(java.io.File file)
                   throws EmailException

Add an attachment from the contents of a file. The MIME type is taken from the file's extension. The file's name will be used as the attachment name.

Parameters:

file - The File to read to create the attachment

Throws:

EmailException - error adding the attachment

See Also:

addAttachment(File,String), addAttachment(String), addAttachment(String,String), addAttachment(String[],String), addAttachment(InputStream), addAttachment(InputStream,String), addAttachment(Iterator), getAttachment(int), getAttachmentContentType(int), totalAttachments()

addAttachment

public void addAttachment(java.io.File file,
                          java.lang.String mimeType)
                   throws EmailException

Add an attachment from the contents of a file. The file's name will be used as the attachment name.

Parameters:

file - The File to read to create the attachment

mimeType - The MIME type to associate with the file, or null to infer the MIME type from the file's extension

Throws:

EmailException - error adding the attachment

See Also:

addAttachment(File,String), addAttachment(String), addAttachment(String,String), addAttachment(String[],String), addAttachment(InputStream), addAttachment(InputStream,String), addAttachment(Iterator), getAttachment(int), getAttachmentContentType(int), totalAttachments()

addAttachment

public void addAttachment(java.io.File file,
                          java.lang.String fileName,
                          java.lang.String mimeType)
                   throws EmailException

Add an attachment from the contents of a file.

Parameters:

file - The File to read to create the attachment

fileName - The file name to use as the attachment name

mimeType - The MIME type to associate with the file, or null to infer the MIME type from the file's extension

Throws:

EmailException - error adding the attachment

See Also:

addAttachment(File,String), addAttachment(String), addAttachment(String,String), addAttachment(String[],String), addAttachment(InputStream), addAttachment(InputStream,String), addAttachment(Iterator), getAttachment(int), getAttachmentContentType(int), totalAttachments()

clearAllAttachments

public void clearAllAttachments()

Clear all attachments from this message. Note: Removing the attachments does not remove the text part of the message.

See Also:

addAttachment(String), addAttachment(String,String), addAttachment(String[],String), addAttachment(InputStream), addAttachment(InputStream,String), addAttachment(Iterator), addAttachment(File), clearText()

setSubject

public void setSubject(java.lang.String subject)

Set the subject of this message.

Parameters:

subject - The text subject of the message, or null to clear the subject

See Also:

getSubject(), clearSubject()

getSubject

public java.lang.String getSubject()

Get the subject of this message.

Returns:

The text subject of the message, or null if there is no subject

See Also:

setSubject(String), clearSubject()

clearSubject

public void clearSubject()

Clear this message's subject. Calling this method is equivalent to calling setSubject() with a null parameter.

See Also:

setSubject(String), getSubject()

setSender

public void setSender(java.lang.String senderAddress)
               throws EmailException

Set the sender's email address. If not set, the sender's address is computed, by send(), from the Java "user.name" property and the SMTP host name. The address can be any RFC822-compliant email address. Examples include:

 
 vangogh@example.com
 Vincent Van Gogh <vangogh@example.com>
 "Vincent Van Gogh" <vangogh@example.com>
 vangogh@example.com (Vincent Van Gogh)
 
 

Parameters:

senderAddress - the new sender address value, or null to clear the sender (and force it to be computed as described above)

Throws:

EmailException - improperly formed email address

See Also:

setSender(EmailAddress)

setSender

public void setSender(EmailAddress senderAddress)
               throws EmailException

Set the sender's email address. If not set, the sender's address is computed, by send(), from the Java "user.name" property and the SMTP host name. The address can be any RFC822-compliant email address. Examples include:

 
 vangogh@example.com
 Vincent Van Gogh <vangogh@example.com>
 "Vincent Van Gogh" <vangogh@example.com>
 vangogh@example.com (Vincent Van Gogh)
 
 

Parameters:

senderAddress - the new sender address value, or null to clear the sender (and force it to be computed as described above)

Throws:

EmailException - improperly formed email address

See Also:

setSender(String)

getSender

public EmailAddress getSender()
                       throws EmailException

Get the email address that will be used as the sender. If setSender has not been called, then the sender address is computed from the Java "user.name" property and the current host name.

Returns:

the EmailAddress of the sender

Throws:

EmailException - error calculating sender address

See Also:

EmailAddress