- java.lang.Object
-
- jakarta.mail.Address
-
- jakarta.mail.internet.InternetAddress
-
- All Implemented Interfaces:
java.io.Serializable
,java.lang.Cloneable
public class InternetAddress extends Address implements java.lang.Cloneable
This class represents an Internet email address using the syntax of RFC822. Typical address syntax is of the form "user@host.domain" or "Personal Name <user@host.domain>".- See Also:
- Serialized Form
-
-
Field Summary
Fields Modifier and Type Field Description protected java.lang.String
address
The email address.private static boolean
allowUtf8
protected java.lang.String
encodedPersonal
The RFC 2047 encoded version of the personal name.private static boolean
ignoreBogusGroupName
protected java.lang.String
personal
The personal name.private static java.lang.String
rfc822phrase
private static long
serialVersionUID
private static java.lang.String
specialsNoDot
private static java.lang.String
specialsNoDotNoAt
private static boolean
useCanonicalHostName
-
Constructor Summary
Constructors Constructor Description InternetAddress()
Default constructor.InternetAddress(java.lang.String address)
Constructor.InternetAddress(java.lang.String address, boolean strict)
Parse the given string and create an InternetAddress.InternetAddress(java.lang.String address, java.lang.String personal)
Construct an InternetAddress given the address and personal name.InternetAddress(java.lang.String address, java.lang.String personal, java.lang.String charset)
Construct an InternetAddress given the address and personal name.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description (package private) static InternetAddress
_getLocalAddress(Session session)
A package-private version of getLocalAddress that doesn't swallow the exception.private static void
checkAddress(java.lang.String addr, boolean routeAddr, boolean validate)
Check that the address is a valid "mailbox" per RFC822.java.lang.Object
clone()
Return a copy of this InternetAddress object.boolean
equals(java.lang.Object a)
The equality operator.java.lang.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.private static java.lang.String
getLocalHostName()
Get the local host name from InetAddress and return it in a form suitable for use in an email address.java.lang.String
getPersonal()
Get the personal name.java.lang.String
getType()
Return the type of this address.int
hashCode()
Compute a hash code for the address.private static int
indexOfAny(java.lang.String s, java.lang.String any)
Return the first index of any of the characters in "any" in "s", or -1 if none are found.private static int
indexOfAny(java.lang.String s, java.lang.String any, int start)
boolean
isGroup()
Indicates whether this address is an RFC 822 group address.private static boolean
isInetAddressLiteral(java.lang.String addr)
Is the address an IPv4 or IPv6 address literal, which needs to be enclosed in "[]" in an email address? IPv4 literals contain decimal digits and dots, IPv6 literals contain hex digits, dots, and colons.private boolean
isSimple()
Is this a "simple" address? Simple addresses don't contain quotes or any RFC822 special characters other than '@' and '.'.private static int
lengthOfFirstSegment(java.lang.String s)
private static int
lengthOfLastSegment(java.lang.String s, int used)
static InternetAddress[]
parse(java.lang.String addresslist)
Parse the given comma separated sequence of addresses into InternetAddress objects.static InternetAddress[]
parse(java.lang.String addresslist, boolean strict)
Parse the given sequence of addresses into InternetAddress objects.private static InternetAddress[]
parse(java.lang.String s, boolean strict, boolean parseHdr)
static InternetAddress[]
parseHeader(java.lang.String addresslist, boolean strict)
Parse the given sequence of addresses into InternetAddress objects.private static java.lang.String
quotePhrase(java.lang.String phrase)
void
setAddress(java.lang.String address)
Set the email address.void
setPersonal(java.lang.String name)
Set the personal name.void
setPersonal(java.lang.String name, java.lang.String charset)
Set the personal name.java.lang.String
toString()
Convert this address into a RFC 822 / RFC 2047 encoded address.static java.lang.String
toString(Address[] addresses)
Convert the given array of InternetAddress objects into a comma separated sequence of address strings.static java.lang.String
toString(Address[] addresses, int used)
Convert the given array of InternetAddress objects into a comma separated sequence of address strings.java.lang.String
toUnicodeString()
Returns a properly formatted address (RFC 822 syntax) of Unicode characters.static java.lang.String
toUnicodeString(Address[] addresses)
Convert the given array of InternetAddress objects into a comma separated sequence of address strings.static java.lang.String
toUnicodeString(Address[] addresses, int used)
Convert the given array of InternetAddress objects into a comma separated sequence of address strings.private static java.lang.String
unquote(java.lang.String s)
void
validate()
Validate that this address conforms to the syntax rules of RFC 822.
-
-
-
Field Detail
-
address
protected java.lang.String address
The email address.
-
personal
protected java.lang.String personal
The personal name.
-
encodedPersonal
protected java.lang.String encodedPersonal
The RFC 2047 encoded version of the personal name.This field and the
personal
field track each other, so if a subclass sets one of these fields directly, it should set the other tonull
, so that it is suitably recomputed.
-
serialVersionUID
private static final long serialVersionUID
- See Also:
- Constant Field Values
-
ignoreBogusGroupName
private static final boolean ignoreBogusGroupName
-
useCanonicalHostName
private static final boolean useCanonicalHostName
-
allowUtf8
private static final boolean allowUtf8
-
rfc822phrase
private static final java.lang.String rfc822phrase
-
specialsNoDotNoAt
private static final java.lang.String specialsNoDotNoAt
- See Also:
- Constant Field Values
-
specialsNoDot
private static final java.lang.String specialsNoDot
- See Also:
- Constant Field Values
-
-
Constructor Detail
-
InternetAddress
public InternetAddress()
Default constructor.
-
InternetAddress
public InternetAddress(java.lang.String address) throws AddressException
Constructor.Parse the given string and create an InternetAddress. See the
parse
method for details of the parsing. The address is parsed using "strict" parsing. This constructor does not perform the additional syntax checks that theInternetAddress(String address, boolean strict)
constructor does whenstrict
istrue
. This constructor is equivalent toInternetAddress(address, false)
.- Parameters:
address
- the address in RFC822 format- Throws:
AddressException
- if the parse failed
-
InternetAddress
public InternetAddress(java.lang.String address, boolean strict) throws AddressException
Parse the given string and create an InternetAddress. Ifstrict
is false, the detailed syntax of the address isn't checked.- Parameters:
address
- the address in RFC822 formatstrict
- enforce RFC822 syntax- Throws:
AddressException
- if the parse failed- Since:
- JavaMail 1.3
-
InternetAddress
public InternetAddress(java.lang.String address, java.lang.String personal) throws java.io.UnsupportedEncodingException
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 formatpersonal
- the personal name- Throws:
java.io.UnsupportedEncodingException
- if the personal name can't be encoded in the given charset
-
InternetAddress
public InternetAddress(java.lang.String address, java.lang.String personal, java.lang.String charset) throws java.io.UnsupportedEncodingException
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 formatpersonal
- the personal namecharset
- the MIME charset for the name- Throws:
java.io.UnsupportedEncodingException
- if the personal name can't be encoded in the given charset
-
-
Method Detail
-
clone
public java.lang.Object clone()
Return a copy of this InternetAddress object.- Overrides:
clone
in classjava.lang.Object
- Since:
- JavaMail 1.2
-
getType
public java.lang.String getType()
Return the type of this address. The type of an InternetAddress is "rfc822".- Specified by:
getType
in classAddress
- Returns:
- address type
- See Also:
InternetAddress
-
setAddress
public void setAddress(java.lang.String address)
Set the email address.- Parameters:
address
- email address
-
setPersonal
public void setPersonal(java.lang.String name, java.lang.String charset) throws java.io.UnsupportedEncodingException
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 namecharset
- MIME charset to be used to encode the name as per RFC 2047- Throws:
java.io.UnsupportedEncodingException
- if the charset encoding fails.- See Also:
setPersonal(String)
-
setPersonal
public void setPersonal(java.lang.String name) throws java.io.UnsupportedEncodingException
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:
java.io.UnsupportedEncodingException
- if the charset encoding fails.- See Also:
setPersonal(String name, String charset)
-
getAddress
public java.lang.String getAddress()
Get the email address.- Returns:
- email address
-
getPersonal
public java.lang.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 conversion fails, the raw data is returned as is.- Returns:
- personal name
-
toString
public java.lang.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.
-
toUnicodeString
public java.lang.String toUnicodeString()
Returns a properly formatted address (RFC 822 syntax) of Unicode characters.- Returns:
- Unicode address string
- Since:
- JavaMail 1.2
-
quotePhrase
private static java.lang.String quotePhrase(java.lang.String phrase)
-
unquote
private static java.lang.String unquote(java.lang.String s)
-
equals
public boolean equals(java.lang.Object a)
The equality operator.
-
hashCode
public int hashCode()
Compute a hash code for the address.- Overrides:
hashCode
in classjava.lang.Object
-
toString
public static java.lang.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 string of addresses
- Throws:
java.lang.ClassCastException
- if any address object in the given array is not an InternetAddress object. Note that this is a RuntimeException.
-
toUnicodeString
public static java.lang.String toUnicodeString(Address[] addresses)
Convert the given array of InternetAddress objects into a comma separated sequence of address strings. The resulting string contains Unicode characters.- Parameters:
addresses
- array of InternetAddress objects- Returns:
- comma separated string of addresses
- Throws:
java.lang.ClassCastException
- if any address object in the given array is not an InternetAddress object. Note that this is a RuntimeException.- Since:
- JavaMail 1.6
-
toString
public static java.lang.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. It is used to determine the line-break positions in the resulting address sequence string.
- Parameters:
addresses
- array of InternetAddress objectsused
- number of character positions already used, in the field into which the address string is to be inserted.- Returns:
- comma separated string of addresses
- Throws:
java.lang.ClassCastException
- if any address object in the given array is not an InternetAddress object. Note that this is a RuntimeException.
-
toUnicodeString
public static java.lang.String toUnicodeString(Address[] addresses, int used)
Convert the given array of InternetAddress objects into a comma separated sequence of address strings. The resulting string contains Unicode characters.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. It is used to determine the line-break positions in the resulting address sequence string.
- Parameters:
addresses
- array of InternetAddress objectsused
- number of character positions already used, in the field into which the address string is to be inserted.- Returns:
- comma separated string of addresses
- Throws:
java.lang.ClassCastException
- if any address object in the given array is not an InternetAddress object. Note that this is a RuntimeException.- Since:
- JavaMail 1.6
-
lengthOfFirstSegment
private static int lengthOfFirstSegment(java.lang.String s)
-
lengthOfLastSegment
private static int lengthOfLastSegment(java.lang.String s, int used)
-
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 andInetAddress.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
-
_getLocalAddress
static InternetAddress _getLocalAddress(Session session) throws java.lang.SecurityException, AddressException, java.net.UnknownHostException
A package-private version of getLocalAddress that doesn't swallow the exception. Used by MimeMessage.setFrom() to report the reason for the failure.- Throws:
java.lang.SecurityException
AddressException
java.net.UnknownHostException
-
getLocalHostName
private static java.lang.String getLocalHostName() throws java.net.UnknownHostException
Get the local host name from InetAddress and return it in a form suitable for use in an email address.- Throws:
java.net.UnknownHostException
-
isInetAddressLiteral
private static boolean isInetAddressLiteral(java.lang.String addr)
Is the address an IPv4 or IPv6 address literal, which needs to be enclosed in "[]" in an email address? IPv4 literals contain decimal digits and dots, IPv6 literals contain hex digits, dots, and colons. We're lazy and don't check the exact syntax, just the allowed characters; strings that have only the allowed characters in a literal but don't meet the syntax requirements for a literal definitely can't be a host name and thus will fail later when used as an address literal.
-
parse
public static InternetAddress[] parse(java.lang.String addresslist) throws AddressException
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(java.lang.String addresslist, boolean strict) throws AddressException
Parse the given sequence of addresses into InternetAddress objects. Ifstrict
is false, simple email addresses separated by spaces are also allowed. Ifstrict
is true, many (but not all) of the RFC822 syntax rules are enforced. In particular, even ifstrict
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 stringsstrict
- enforce RFC822 syntax- Returns:
- array of InternetAddress objects
- Throws:
AddressException
- if the parse failed
-
parseHeader
public static InternetAddress[] parseHeader(java.lang.String addresslist, boolean strict) throws AddressException
Parse the given sequence of addresses into InternetAddress objects. Ifstrict
is false, the full syntax rules for individual addresses are not enforced. Ifstrict
is true, many (but not all) of the RFC822 syntax rules are enforced.To better support the range of "invalid" addresses seen in real messages, this method enforces fewer syntax rules than the
parse
method when the strict flag is false and enforces more rules when the strict flag is true. If the strict flag is false and the parse is successful in separating out an email address or addresses, the syntax of the addresses themselves is not checked.- Parameters:
addresslist
- comma separated address stringsstrict
- enforce RFC822 syntax- Returns:
- array of InternetAddress objects
- Throws:
AddressException
- if the parse failed- Since:
- JavaMail 1.3
-
parse
private static InternetAddress[] parse(java.lang.String s, boolean strict, boolean parseHdr) throws AddressException
- Throws:
AddressException
-
validate
public void validate() throws AddressException
Validate that this address conforms to the syntax rules of RFC 822. The current implementation checks many, but 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.- Throws:
AddressException
- if the address isn't valid.- Since:
- JavaMail 1.3
-
checkAddress
private static void checkAddress(java.lang.String addr, boolean routeAddr, boolean validate) throws AddressException
Check that the address is a valid "mailbox" per RFC822. (We also allow simple names.) XXX - much more to check XXX - doesn't handle domain-literals properly (but no one uses them)- Throws:
AddressException
-
isSimple
private boolean isSimple()
Is this a "simple" address? Simple addresses don't contain quotes or any RFC822 special characters other than '@' and '.'.
-
isGroup
public boolean isGroup()
Indicates whether this address is an RFC 822 group address. Note that a group address is different than the mailing list addresses supported by most mail servers. Group addresses are rarely used; see RFC 822 for details.- Returns:
- true if this address represents a group
- Since:
- JavaMail 1.3
-
getGroup
public InternetAddress[] getGroup(boolean strict) throws AddressException
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. Thestrict
parameter controls whether the group list is parsed using strict RFC 822 rules or not. The parsing is done using theparseHeader
method.- Parameters:
strict
- use strict RFC 822 rules?- Returns:
- array of InternetAddress objects, or null
- Throws:
AddressException
- if the group list can't be parsed- Since:
- JavaMail 1.3
-
indexOfAny
private static int indexOfAny(java.lang.String s, java.lang.String any)
Return the first index of any of the characters in "any" in "s", or -1 if none are found. This should be a method on String.
-
indexOfAny
private static int indexOfAny(java.lang.String s, java.lang.String any, int start)
-
-