⇒ Index (Frames) |  ⇒ Index (No Frames) |  ⇒ Package |  ⇒ Package Tree |  ⇒ Full Tree 
javax.mail.internet

Class InternetAddress

java.lang.Object
|
+--javax.mail.Address
   |
   +--javax.mail.internet.InternetAddress

All Implemented Interfaces:
Cloneable, Serializable


public class InternetAddress
extends Address
implements Cloneable

This class models an RFC822 address.
Author:

Field Summary

String

address

The string form of the address.

String

encodedPersonal

The RFC 2047 encoded version of the personal name.

String

personal

The personal name.

Constructor Summary

InternetAddress()

Default constructor.

InternetAddress(String address)

Parse the given string and create an InternetAddress.

InternetAddress(String address, boolean strict)

Parse the given string and create an InternetAddress.

InternetAddress(String address, String personal)

Construct an InternetAddress given the address and personal name.

InternetAddress(String address, String personal, String charset)

Construct an InternetAddress given the address and personal name.

Method Summary

Object

clone()

Return a copy of this InternetAddress object.

boolean

equals(Object other)

The equality operator.

String

getAddress()

Get the email address.

InternetAddress[]

getGroup(boolean strict)

Return the members of a group address.

static InternetAddress

getLocalAddress(Session session)

Return an InternetAddress object representing the current user.

String

getPersonal()

Get the personal name.

String

getType()

Return the type of this address.

int

hashCode()

Compute a hash code for the address.

boolean

isGroup()

Indicates whether this address is an RFC 822 group address.

static InternetAddress[]

parse(String addresslist)

Parse the given comma separated sequence of addresses into InternetAddress objects.

static InternetAddress[]

parse(String addresslist, boolean strict)

Parse the given sequence of addresses into InternetAddress objects.

static InternetAddress[]

parseHeader(String addresslist, boolean strict)

Parse the given sequence of addresses into InternetAddress objects.

void

setAddress(String address)

Set the email address.

void

setPersonal(String name, String charset)

Set the personal name.

void

setPersonal(String name)

Set the personal name.

String

toString()

Convert this address into a RFC 822 / RFC 2047 encoded address.

static String

toString(Address[] addresses)

Convert the given array of InternetAddress objects into a comma separated sequence of address strings.

static String

toString(Address[] addresses, int used)

Convert the given array of InternetAddress objects into a comma separated sequence of address strings.

String

toUnicodeString()

Returns a properly formatted address (RFC 822 syntax) of Unicode characters.

void

validate()

Validate that this address conforms to the syntax rules of RFC 822.

Field Details

address

protected String address

The string form of the address.


encodedPersonal

protected String encodedPersonal

The RFC 2047 encoded version of the personal name.


personal

protected String personal

The personal name.

Constructor Details

InternetAddress

public InternetAddress()

Default constructor.


InternetAddress

public InternetAddress(String address)

Parse the given string and create an InternetAddress.

Parameters:
address - the address in RFC822 format
Throws:
AddressException - if the parse failed

InternetAddress

public InternetAddress(String address, String personal)

Construct an InternetAddress given the address and personal name. The address is assumed to be a syntactically valid RFC822 address.

Parameters:
address - the address in RFC822 format
personal - the personal name

InternetAddress

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

Construct an InternetAddress given the address and personal name. The address is assumed to be a syntactically valid RFC822 address.

Parameters:
address - the address in RFC822 format
personal - the personal name
charset - the charset for the name

InternetAddress

public InternetAddress(String address, boolean strict)

Parse the given string and create an InternetAddress. If strict is false, the detailed syntax of the address isn't checked.

Since:
JavaMail 1.3
Parameters:
address - the address in RFC822 format
strict - enforce RFC822 syntax
Throws:
AddressException - if the parse failed

Method Details

clone

public Object clone()

Return a copy of this InternetAddress object.


equals

public boolean equals(Object other)

The equality operator.

Parameters:
other

getAddress

public String getAddress()

Get the email address.


getGroup

public InternetAddress[] getGroup(boolean strict)

Return the members of a group address. A group may have zero, one, or more members. If this address is not a group, null is returned. The strict parameter controls whether the group list is parsed using strict RFC 822 rules or not. The parsing is done using the parseHeader method.

Since:
JavaMail 1.3
Parameters:
strict
Throws:
AddressException - if the group list can't be parsed

getLocalAddress

public static InternetAddress getLocalAddress(Session session)

Return an InternetAddress object representing the current user. The entire email address may be specified in the "mail.from" property. If not set, the "mail.user" and "mail.host" properties are tried. If those are not set, the "user.name" property and InetAddress.getLocalHost method are tried. Security exceptions that may occur while accessing this information are ignored. If it is not possible to determine an email address, null is returned.

Parameters:
session - Session object used for property lookup
Returns:
current user's email address

getPersonal

public String getPersonal()

Get the personal name. If the name is encoded as per RFC 2047, it is decoded and converted into Unicode. If the decoding or convertion fails, the raw data is returned as is.


getType

public String getType()

Return the type of this address. The type of an InternetAddress is "rfc822".


hashCode

public int hashCode()

Compute a hash code for the address.


isGroup

public boolean isGroup()

Indicates whether this address is an RFC 822 group address. Note that a group address is different from the mailing list addresses supported by most mail servers. Group addresses are rarely used; see RFC 822 for details.

Since:
JavaMail 1.3

parse

public static InternetAddress[] parse(String addresslist)

Parse the given comma separated sequence of addresses into InternetAddress objects. Addresses must follow RFC822 syntax.

Parameters:
addresslist - comma separated address strings
Returns:
array of InternetAddress objects
Throws:
AddressException - if the parse failed

parse

public static InternetAddress[] parse(String addresslist, boolean strict)

Parse the given sequence of addresses into InternetAddress objects. If strict is false, simple email addresses separated by spaces are also allowed. If strict is true, many (but not all) of the RFC822 syntax rules are enforced. In particular, even if strict is true, addresses composed of simple names (with no "@domain" part) are allowed. Such "illegal" addresses are not uncommon in real messages.

Non-strict parsing is typically used when parsing a list of mail addresses entered by a human. Strict parsing is typically used when parsing address headers in mail messages.

Parameters:
addresslist - comma separated address strings
strict - enforce RFC822 syntax
Returns:
array of InternetAddress objects
Throws:
AddressException - if the parse failed

parseHeader

public static InternetAddress[] parseHeader(String addresslist, boolean strict)

Parse the given sequence of addresses into InternetAddress objects. If strict is false, the full syntax rules for individual addresses are not enforced. If strict is true, many (but not all) of the RFC822 syntax rules are enforced.

Non-strict parsing is typically used when parsing a list of mail addresses entered by a human. Strict parsing is typically used when parsing address headers in mail messages.

Since:
JavaMail 1.3
Parameters:
addresslist - comma separated address strings
strict - enforce RFC822 syntax

setAddress

public void setAddress(String address)

Set the email address.

Parameters:
address

setPersonal

public void setPersonal(String name)

Set the personal name. If the name contains non US-ASCII characters, then the name will be encoded using the platform's default charset. If the name contains only US-ASCII characters, no encoding is done and the name is used as is.

Parameters:
name - - personal name
Throws:
- - if the charset encoding fails.

setPersonal

public void setPersonal(String name, String charset)

Set the personal name. If the name contains non US-ASCII characters, then the name will be encoded using the specified charset as per RFC 2047. If the name contains only US-ASCII characters, no encoding is done and the name is used as is.

Parameters:
name - personal name
charset - charset to be used to encode the name as per RFC 2047.

toString

public String toString()

Convert this address into a RFC 822 / RFC 2047 encoded address. The resulting string contains only US-ASCII characters, and hence is mail-safe.


toString

public static String toString(Address[] addresses)

Convert the given array of InternetAddress objects into a comma separated sequence of address strings. The resulting string contains only US-ASCII characters, and hence is mail-safe.

Parameters:
addresses - array of InternetAddress objects
Returns:
comma separated address strings
Throws:
- if any address object in the given array is not an InternetAddress objects.

toString

public static String toString(Address[] addresses, int used)

Convert the given array of InternetAddress objects into a comma separated sequence of address strings. The resulting string contains only US-ASCII characters, and hence is mail-safe.

The 'used' parameter specifies the number of character positions already taken up in the field into which the resulting address sequence string is to be inserted. Its used to determine the line-break positions in the resulting address sequence string.

Parameters:
addresses - array of InternetAddress objects
used - number of character positions already used, in the field into which the address string is to be inserted.
Returns:
comma separated address strings
Throws:
- if any address object in the given array is not an InternetAddress object.

toUnicodeString

public String toUnicodeString()

Returns a properly formatted address (RFC 822 syntax) of Unicode characters.


validate

public void validate()

Validate that this address conforms to the syntax rules of RFC 822. The current implementation checks many, not all, syntax rules. Note that, even though the syntax of the address may be correct, there's no guarantee that a mailbox of that name exists.

Since:
JavaMail 1.3
Throws:
AddressException - if the address isn't valid