javax.mail.internet

Class InternetAddress

public class InternetAddress extends Address implements Cloneable

A representation of an Internet email address as specified by RFC822 in conjunction with a human-readable personal name that can be encoded as specified by RFC2047. A typical address is "user@host.domain" and personal name "Joe User"
Field Summary
protected Stringaddress
The address in RFC822 format.
protected StringencodedPersonal
The personal name in RFC2047 format.
protected Stringpersonal
The personal name as a Java String.
Constructor Summary
InternetAddress()
InternetAddress(String address)
InternetAddress(String address, boolean strict)
InternetAddress(String address, String personal)
InternetAddress(String address, String personal, String charset)
Method Summary
Objectclone()
Clone this object.
booleanequals(Object o)
Compares two addresses for equality.
StringgetAddress()
Return the address.
InternetAddress[]getGroup(boolean strict)
Return the members of a group address.
static InternetAddressgetLocalAddress(Session session)
Return an InternetAddress representing the current user.
StringgetPersonal()
Return the personal name.
StringgetType()
Return the type of this address.
inthashCode()
Return the hashCode for this address.
booleanisGroup()
Return true is this address is an RFC822 group address in the format phrase ":" [#mailbox] ";".
static InternetAddress[]parse(String addresses)
Parse addresses out of the string with basic checking.
static InternetAddress[]parse(String addresses, boolean strict)
Parse addresses out of the string.
static InternetAddress[]parseHeader(String addresses, boolean strict)
Parse addresses out of the string.
voidsetAddress(String address)
Set the address.
voidsetPersonal(String name, String charset)
Set the personal name.
voidsetPersonal(String name)
Set the personal name.
StringtoString()
Return a string representation of this address using only US-ASCII characters.
static StringtoString(Address[] addresses)
Convert the supplied addresses into a single String of comma-separated text as produced by toString().
static StringtoString(Address[] addresses, int used)
Convert the supplies addresses into a String of comma-separated text, inserting line-breaks between addresses as needed to restrict the line length to 72 characters.
StringtoUnicodeString()
Return a string representation of this address using Unicode characters.
voidvalidate()

Field Detail

address

protected String address
The address in RFC822 format.

encodedPersonal

protected String encodedPersonal
The personal name in RFC2047 format. Subclasses must ensure that this field is updated if the personal field is updated; alternatively, it can be invalidated by setting to null which will cause it to be recomputed.

personal

protected String personal
The personal name as a Java String. Subclasses must ensure that this field is updated if the encodedPersonal field is updated; alternatively, it can be invalidated by setting to null which will cause it to be recomputed.

Constructor Detail

InternetAddress

public InternetAddress()

InternetAddress

public InternetAddress(String address)

InternetAddress

public InternetAddress(String address, boolean strict)

InternetAddress

public InternetAddress(String address, String personal)

InternetAddress

public InternetAddress(String address, String personal, String charset)

Method Detail

clone

public Object clone()
Clone this object.

Returns: a copy of this object as created by Object.clone()

equals

public boolean equals(Object o)
Compares two addresses for equality. We define this as true if the other object is an InternetAddress and the two values returned by getAddress() are equal in a case-insensitive comparison.

Parameters: o the other object

Returns: true if the addresses are the same

getAddress

public String getAddress()
Return the address.

Returns: the address

getGroup

public InternetAddress[] getGroup(boolean strict)
Return the members of a group address. If strict is true and the address does not contain an initial phrase then an AddressException is thrown. Otherwise the phrase is skipped and the remainder of the address is checked to see if it is a group. If it is, the content and strict flag are passed to parseHeader to extract the list of addresses; if it is not a group then null is returned.

Parameters: strict whether strict RFC822 checking should be performed

Returns: an array of InternetAddress objects for the group members, or null if this address is not a group

Throws: AddressException if there was a problem parsing the header

getLocalAddress

public static InternetAddress getLocalAddress(Session session)
Return an InternetAddress representing the current user.

If session is not null, we first look for an address specified in its "mail.from" property; if this is not set, we look at its "mail.user" and "mail.host" properties and if both are not null then an address of the form "${mail.user}@${mail.host}" is created. If this fails to give an address, then an attempt is made to create an address by combining the value of the "user.name" System property with the value returned from InetAddress.getLocalHost().getHostName(). Any SecurityException raised accessing the system property or any UnknownHostException raised getting the hostname are ignored.

Finally, an attempt is made to convert the value obtained above to an InternetAddress. If this fails, then null is returned.

Parameters: session used to obtain mail properties

Returns: an InternetAddress for the current user, or null if it cannot be determined

getPersonal

public String getPersonal()
Return the personal name. If the personal field is null, then an attempt is made to decode the encodedPersonal field using decodeWord; if this is sucessful, then the personal field is updated with that value and returned; if there is a problem decoding the text then the raw value from encodedPersonal is returned.

Returns: the personal name

getType

public String getType()
Return the type of this address.

Returns: the type of this address; always "rfc822"

hashCode

public int hashCode()
Return the hashCode for this address. We define this to be the hashCode of the address after conversion to lowercase.

Returns: a hashCode for this address

isGroup

public boolean isGroup()
Return true is this address is an RFC822 group address in the format phrase ":" [#mailbox] ";". We check this by seeing stripping the leading phrase (which, for tolerance, we consider optional) and then checking if the first and last characters are ':' and ';' respectively.

Returns: true is this address represents a group

parse

public static InternetAddress[] parse(String addresses)
Parse addresses out of the string with basic checking.

Parameters: addresses the addresses to parse

Returns: an array of InternetAddresses parsed from the string

Throws: AddressException if addresses checking fails

parse

public static InternetAddress[] parse(String addresses, boolean strict)
Parse addresses out of the string.

Parameters: addresses the addresses to parse strict if true perform detailed checking, if false just perform basic checking

Returns: an array of InternetAddresses parsed from the string

Throws: AddressException if address checking fails

parseHeader

public static InternetAddress[] parseHeader(String addresses, boolean strict)
Parse addresses out of the string.

Parameters: addresses the addresses to parse strict if true perform detailed checking, if false perform little checking

Returns: an array of InternetAddresses parsed from the string

Throws: AddressException if address checking fails

setAddress

public void setAddress(String address)
Set the address. No validation is performed; validate() can be used to check if it is valid.

Parameters: address the address to set

setPersonal

public void setPersonal(String name, String charset)
Set the personal name. The name is first checked to see if it can be encoded; if this fails then an UnsupportedEncodingException is thrown and no fields are modified.

Parameters: name the new personal name charset the charset to use; see MimeUtilityencodeWord

Throws: UnsupportedEncodingException if the name cannot be encoded

setPersonal

public void setPersonal(String name)
Set the personal name. The name is first checked to see if it can be encoded using encodeWord; if this fails then an UnsupportedEncodingException is thrown and no fields are modified.

Parameters: name the new personal name

Throws: UnsupportedEncodingException if the name cannot be encoded

toString

public String toString()
Return a string representation of this address using only US-ASCII characters.

Returns: a string representation of this address

toString

public static String toString(Address[] addresses)
Convert the supplied addresses into a single String of comma-separated text as produced by toString(). No line-break detection is performed.

Parameters: addresses the array of addresses to convert

Returns: a one-line String of comma-separated addresses

toString

public static String toString(Address[] addresses, int used)
Convert the supplies addresses into a String of comma-separated text, inserting line-breaks between addresses as needed to restrict the line length to 72 characters. Splits will only be introduced between addresses so an address longer than 71 characters will still be placed on a single line.

Parameters: addresses the array of addresses to convert used the starting column

Returns: a String of comma-separated addresses with optional line breaks

toUnicodeString

public String toUnicodeString()
Return a string representation of this address using Unicode characters.

Returns: a string representation of this address

validate

public void validate()