@Beta @GwtCompatible public final class InternetDomainName extends 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 | Method and Description |
---|---|
InternetDomainName |
child(String
Creates and returns a new
InternetDomainName by prepending the argument and a dot to the current name.
|
boolean |
equals(Object
Equality testing is based on the text supplied by the caller, after normalization as described in the class documentation.
|
static InternetDomainName |
from(String
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(String
Indicates whether the argument is a syntactically valid domain name using lenient validation.
|
InternetDomainName |
parent()
Returns an
InternetDomainName that is the immediate ancestor of this one; that is, the current domain with the leftmost part removed.
|
ImmutableList |
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.
|
String |
toString()
Returns the domain name, normalized to all lower case.
|
public static InternetDomainNamefrom(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)
IllegalArgumentException
- if
name
is not syntactically valid according to
isValid(java.lang.String)
fromLenient
)
public ImmutableList<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 list
public 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 InternetDomainNamepublicSuffix()
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 InternetDomainNametopPrivateDomain()
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.
IllegalStateException
- if this domain does not end with a public suffix
public boolean hasParent()
public InternetDomainNameparent()
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
.
IllegalStateException
- if the domain has no parent, as determined by
hasParent()
public InternetDomainNamechild(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
.
NullPointerException
- if leftParts is null
IllegalArgumentException
- if the resulting name is not valid
public static boolean isValid(Stringname)
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
)
public StringtoString()
public boolean equals(Objectobject)
public int hashCode()