de.trantor.mail
Class Envelope

java.lang.Object
  |
  +--de.trantor.mail.Envelope

public class Envelope

extends java.lang.Object

Represents an envelope used for sending a message via the SMTP protocol. The envelope holds information about a message's sender and recipients as used during an SMTP session. It serves more or less the same purpose that an envelope is used for when sending snail mail. Note that there is a difference between the message envelope and the message header.

Most of the time the envelope data will be identical to the "From:", "To:", "CC:" and "BCC:" fields of the message header. There are cases, though, where one might want to send a message to a recipient different from the one originally specified in the message. A mailing list is an example of an application that makes use of this feature: Postings are forwarded to the subscribers *without* changing the original message. This is one reason for separating the envelope from the message itself.

Another reason for separating the message from its envelope is memory savings: The envelope information in only needed while sending a message via SMTP. It is not required for receiving messages via POP3 or for holding messages in-memory.

See Also:

Message, SmtpClient

Constructor Summary

Envelope(Message message, boolean autofill)
Creates a new envelope for a given message.

Method Summary

int	addRecipient(java.lang.String address) Adds a recipient to the message's envelope.
Message	getMessage() Returns the message contained in this envelope.
java.lang.String	getRecipient(int index) Returns one of the envelope's recipients by index.
int	getRecipientCount() Returns the number of recipients specified in this envelope.
java.lang.String	getSender() Returns the envelope's sender field.
void	removeRecipient(int index) Removes a recipient from the message's envelope.
void	setRecipient(int index, java.lang.String address) Replaces the envelope's recipient at the given index by a new one.
void	setSender(java.lang.String address) Sets the envelope's sender field to the given value.

Methods inherited from class java.lang.Object

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

Constructor Detail

Envelope

public Envelope(Message message,
                boolean autofill)

Creates a new envelope for a given message. The value of the "autofill" parameter determines whether sender and recipient data is automatically copied from the message's "From:", "To:", "CC:" and "BCC:" fields.

Method Detail

getMessage

public Message getMessage()

Returns the message contained in this envelope.

setSender

public void setSender(java.lang.String address)

Sets the envelope's sender field to the given value. Note that SMTP requires a message to have a (valid) sender. Otherwise the message can't be delivered.

See Also:

getSender(), addRecipient(java.lang.String), getRecipientCount(), getRecipient(int), setRecipient(int, java.lang.String), removeRecipient(int)

getSender

public java.lang.String getSender()

Returns the envelope's sender field. This will be equal to the message's "From:" field most of the time, but this is not a necessity.

See Also:

setSender(java.lang.String), addRecipient(java.lang.String), getRecipientCount(), getRecipient(int), setRecipient(int, java.lang.String), removeRecipient(int)

addRecipient

public int addRecipient(java.lang.String address)

Adds a recipient to the message's envelope. The method returns the index of the new recipient, starting from zero. Note that SMTP requires a message to have a least one (valid) recipient. Otherwise the message can't be delivered.

See Also:

getSender(), setSender(java.lang.String), getRecipientCount(), getRecipient(int), setRecipient(int, java.lang.String), removeRecipient(int)

setRecipient

public void setRecipient(int index,
                         java.lang.String address)
                  throws java.lang.ArrayIndexOutOfBoundsException

Replaces the envelope's recipient at the given index by a new one.

java.lang.ArrayIndexOutOfBoundsException

See Also:

getSender(), setSender(java.lang.String), addRecipient(java.lang.String), getRecipientCount(), getRecipient(int), removeRecipient(int)

getRecipientCount

public int getRecipientCount()

Returns the number of recipients specified in this envelope.

See Also:

getSender(), setSender(java.lang.String), addRecipient(java.lang.String), getRecipient(int), setRecipient(int, java.lang.String), removeRecipient(int)

getRecipient

public java.lang.String getRecipient(int index)
                              throws java.lang.ArrayIndexOutOfBoundsException

Returns one of the envelope's recipients by index. The first recipient has index zero.

java.lang.ArrayIndexOutOfBoundsException

See Also:

getSender(), setSender(java.lang.String), addRecipient(java.lang.String), getRecipientCount(), setRecipient(int, java.lang.String), removeRecipient(int)

removeRecipient

public void removeRecipient(int index)
                     throws java.lang.ArrayIndexOutOfBoundsException

Removes a recipient from the message's envelope.

java.lang.ArrayIndexOutOfBoundsException

See Also:

getSender(), setSender(java.lang.String), addRecipient(java.lang.String), getRecipientCount(), getRecipient(int), setRecipient(int, java.lang.String)