@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