@Beta @GwtCompatible public final class InternetDomainName extends java.lang.Object
com
or foo.co.uk
. Only syntactic analysis is performed; no DNS lookups or other network interactions
take place. Thus there is no guarantee that the domain actually exists on the internet.
One common use of this class is to determine whether a given string is likely to represent an
addressable domain on the web -- that is, for a candidate string "xxx"
, might browsing to
"http://xxx/"
result in a webpage being displayed? In the past, this test was frequently
done by determining whether the domain ended with a public suffix
but was not itself a public suffix. However, this test is no longer accurate. There are many
domains which are both public suffixes and addressable as hosts; "uk.com"
is one example.
As a result, the only useful test to determine if a domain is a plausible web host is
hasPublicSuffix()
. This will return true
for many domains which (currently) are
not hosts, such as "com"
, but given that any public suffix may become a host without
warning, it is better to err on the side of permissiveness and thus avoid spurious rejection of
valid sites.
During construction, names are normalized in two ways:
'.'
) are converted to the ASCII
period.
The normalized values will be returned from toString()
and parts()
, and will
be reflected in the result of equals(Object)
.
Internationalized domain
names such as 网络.cn
are supported, as are the equivalent
IDNA Punycode-encoded
versions.
Modifier and Type | Field and Description |
---|---|
private static CharMatcher |
DASH_MATCHER |
private static Joiner |
DOT_JOINER |
private static java.lang.String |
DOT_REGEX |
private static Splitter |
DOT_SPLITTER |
private static CharMatcher |
DOTS_MATCHER |
private static int |
MAX_DOMAIN_PART_LENGTH
Maximum size of a single part of a domain name.
|
private static int |
MAX_LENGTH
Maximum length of a full domain name, including separators, and leaving room for the root
label.
|
private static int |
MAX_PARTS
Maximum parts (labels) in a domain name.
|
private java.lang.String |
name
The full domain name, converted to lower case.
|
private static int |
NO_PUBLIC_SUFFIX_FOUND
Value of
publicSuffixIndex which indicates that no public suffix was found. |
private static CharMatcher |
PART_CHAR_MATCHER |
private ImmutableList<java.lang.String> |
parts
The parts of the domain name, converted to lower case.
|
private int |
publicSuffixIndex
The index in the
parts() list at which the public suffix begins. |
Constructor and Description |
---|
InternetDomainName(java.lang.String name)
Constructor used to implement
from(String) , and from subclasses. |
Modifier and Type | Method and Description |
---|---|
private InternetDomainName |
ancestor(int levels)
Returns the ancestor of the current domain at the given number of levels "higher" (rightward)
in the subdomain list.
|
InternetDomainName |
child(java.lang.String leftParts)
Creates and returns a new
InternetDomainName by prepending the argument and a dot to
the current name. |
boolean |
equals(java.lang.Object object)
Equality testing is based on the text supplied by the caller, after normalization as described
in the class documentation.
|
private int |
findPublicSuffix()
Returns the index of the leftmost part of the public suffix, or -1 if not found.
|
static InternetDomainName |
from(java.lang.String domain)
Returns an instance of
InternetDomainName after lenient validation. |
int |
hashCode() |
boolean |
hasParent()
Indicates whether this domain is composed of two or more parts.
|
boolean |
hasPublicSuffix()
Indicates whether this domain name ends in a public suffix,
including if it is a public suffix itself.
|
boolean |
isPublicSuffix()
Indicates whether this domain name represents a public suffix, as defined by the Mozilla
Foundation's Public Suffix List (PSL).
|
boolean |
isTopPrivateDomain()
Indicates whether this domain name is composed of exactly one subdomain component followed by a
public suffix.
|
boolean |
isUnderPublicSuffix()
Indicates whether this domain name ends in a public suffix,
while not being a public suffix itself.
|
static boolean |
isValid(java.lang.String name)
Indicates whether the argument is a syntactically valid domain name using lenient validation.
|
private static boolean |
matchesWildcardPublicSuffix(java.lang.String domain)
Does the domain name match one of the "wildcard" patterns (e.g.
|
InternetDomainName |
parent()
Returns an
InternetDomainName that is the immediate ancestor of this one; that is, the
current domain with the leftmost part removed. |
ImmutableList<java.lang.String> |
parts()
Returns the individual components of this domain name, normalized to all lower case.
|
InternetDomainName |
publicSuffix()
Returns the public suffix portion of the domain name, or
null if no public suffix is present. |
InternetDomainName |
topPrivateDomain()
Returns the portion of this domain name that is one level beneath the public suffix.
|
java.lang.String |
toString()
Returns the domain name, normalized to all lower case.
|
private static boolean |
validatePart(java.lang.String part,
boolean isFinalPart)
Helper method for
validateSyntax(List) . |
private static boolean |
validateSyntax(java.util.List<java.lang.String> parts)
Validation method used by to ensure that the domain name is syntactically valid
according to RFC 1035.
|
private static final CharMatcher DOTS_MATCHER
private static final Splitter DOT_SPLITTER
private static final Joiner DOT_JOINER
private static final int NO_PUBLIC_SUFFIX_FOUND
publicSuffixIndex
which indicates that no public suffix was found.private static final java.lang.String DOT_REGEX
private static final int MAX_PARTS
private static final int MAX_LENGTH
private static final int MAX_DOMAIN_PART_LENGTH
private final java.lang.String name
private final ImmutableList<java.lang.String> parts
private final int publicSuffixIndex
parts()
list at which the public suffix begins. For example, for the
domain name www.google.co.uk
, the value would be 2 (the index of the co
part).
The value is negative (specifically, NO_PUBLIC_SUFFIX_FOUND
) if no public suffix was
found.private static final CharMatcher DASH_MATCHER
private static final CharMatcher PART_CHAR_MATCHER
InternetDomainName(java.lang.String name)
from(String)
, and from subclasses.private int findPublicSuffix()
isPublicSuffix()
if the domain ends with an excluded domain pattern such as
"nhs.uk"
.public static InternetDomainName from(java.lang.String domain)
InternetDomainName
after lenient validation. Specifically,
validation against RFC 3490
("Internationalizing Domain Names in Applications") is skipped, while validation against
RFC 1035 is relaxed in the following ways:
domain
- A domain name (not IP address)java.lang.IllegalArgumentException
- if name
is not syntactically valid according to
isValid(java.lang.String)
fromLenient
)private static boolean validateSyntax(java.util.List<java.lang.String> parts)
private static boolean validatePart(java.lang.String part, boolean isFinalPart)
validateSyntax(List)
. Validates that one part of a domain name is
valid.part
- The domain name part to be validatedisFinalPart
- Is this the final (rightmost) domain part?public ImmutableList<java.lang.String> parts()
mail.google.com
, this method returns the list
["mail", "google", "com"]
.public boolean isPublicSuffix()
com
,
co.uk
or pvt.k12.wy.us
. Examples of domain names that are not public
suffixes include google
, google.com
and foo.co.uk
.true
if this domain name appears exactly on the public suffix listpublic boolean hasPublicSuffix()
true
for
www.google.com
, foo.co.uk
and com
, but not for google
or
google.foo
. This is the recommended method for determining whether a domain is
potentially an addressable host.public InternetDomainName publicSuffix()
null
if no public suffix is present.public boolean isUnderPublicSuffix()
true
for
www.google.com
, foo.co.uk
and bar.ca.us
, but not for google
,
com
, or google.foo
.
Warning: a false
result from this method does not imply that the domain does
not represent an addressable host, as many public suffixes are also addressable hosts. Use
hasPublicSuffix()
for that test.
This method can be used to determine whether it will probably be possible to set cookies on the domain, though even that depends on individual browsers' implementations of cookie controls. See RFC 2109 for details.
public boolean isTopPrivateDomain()
true
for
google.com
and foo.co.uk
, but not for www.google.com
or co.uk
.
Warning: A true
result from this method does not imply that the domain is at
the highest level which is addressable as a host, as many public suffixes are also addressable
hosts. For example, the domain bar.uk.com
has a public suffix of uk.com
, so it
would return true
from this method. But uk.com
is itself an addressable host.
This method can be used to determine whether a domain is probably the highest level for which cookies may be set, though even that depends on individual browsers' implementations of cookie controls. See RFC 2109 for details.
public InternetDomainName topPrivateDomain()
x.adwords.google.co.uk
it returns google.co.uk
, since
co.uk
is a public suffix.
If isTopPrivateDomain()
is true, the current domain name instance is returned.
This method should not be used to determine the topmost parent domain which is addressable
as a host, as many public suffixes are also addressable hosts. For example, the domain
foo.bar.uk.com
has a public suffix of uk.com
, so it would return
bar.uk.com
from this method. But uk.com
is itself an addressable host.
This method can be used to determine the probable highest level parent domain for which cookies may be set, though even that depends on individual browsers' implementations of cookie controls.
java.lang.IllegalStateException
- if this domain does not end with a public suffixpublic boolean hasParent()
public InternetDomainName parent()
InternetDomainName
that is the immediate ancestor of this one; that is, the
current domain with the leftmost part removed. For example, the parent of
www.google.com
is google.com
.java.lang.IllegalStateException
- if the domain has no parent, as determined by hasParent()
private InternetDomainName ancestor(int levels)
N-1
,
where N
is the number of parts in the domain.
TODO: Reasonable candidate for addition to public API.
public InternetDomainName child(java.lang.String leftParts)
InternetDomainName
by prepending the argument and a dot to
the current name. For example, InternetDomainName.from("foo.com").child("www.bar")
returns a new InternetDomainName
with the value www.bar.foo.com
. Only lenient validation is performed, as described
here
.java.lang.NullPointerException
- if leftParts is nulljava.lang.IllegalArgumentException
- if the resulting name is not validpublic static boolean isValid(java.lang.String name)
The following two code snippets are equivalent:
domainName = InternetDomainName.isValid(name)
? InternetDomainName.from(name)
: DEFAULT_DOMAIN;
try {
domainName = InternetDomainName.from(name);
} catch (IllegalArgumentException e) {
domainName = DEFAULT_DOMAIN;
}
isValidLenient
)private static boolean matchesWildcardPublicSuffix(java.lang.String domain)
"*.ar"
)?public java.lang.String toString()
toString
in class java.lang.Object
public boolean equals(@Nullable java.lang.Object object)
equals
in class java.lang.Object
public int hashCode()
hashCode
in class java.lang.Object