@Beta @GwtCompatible @Immutable 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.
Using the subset of public suffixes that are registry suffixes,
one can get a better result, as only a few registry suffixes are addressable. However, the most
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. Of course, to actually
determine addressability of any host, clients of this class will need to perform their own DNS
lookups.
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 leftParts)
Creates and returns a new
InternetDomainName by prepending the argument and a dot to
the current name. |
boolean |
equals(@Nullable Object object)
Equality testing is based on the text supplied by the caller, after normalization as described
in the class documentation.
|
static InternetDomainName |
from(String domain)
Returns an instance of
InternetDomainName after lenient validation. |
int |
hashCode()
Returns a hash code value for the object.
|
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 |
hasRegistrySuffix()
Indicates whether this domain name ends in a registry suffix,
including if it is a registry 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 |
isRegistrySuffix()
Indicates whether this domain name represents a registry suffix, as defined by a subset
of the Mozilla Foundation's Public Suffix List (PSL).
|
boolean |
isTopDomainUnderRegistrySuffix()
Indicates whether this domain name is composed of exactly one subdomain component followed by a
registry suffix.
|
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.
|
boolean |
isUnderRegistrySuffix()
Indicates whether this domain name ends in a registry suffix,
while not being a registry suffix itself.
|
static boolean |
isValid(String name)
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<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 |
registrySuffix()
Returns the registry suffix portion of the domain name, or
null if no registry suffix is present. |
InternetDomainName |
topDomainUnderRegistrySuffix()
Returns the portion of this domain name that is one level beneath the registry suffix.
|
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 InternetDomainName from(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 domain
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.com
, foo.co.uk
, and myblog.blogspot.com
.
Public suffixes are a proper superset of registry suffixes.
The list of public suffixes additionally contains privately owned domain names under which
Internet users can register subdomains. An example of a public suffix that is not a registry
suffix is blogspot.com
. Note that it is true that all public suffixes have
registry suffixes, since domain name registries collectively control all internet domain names.
For considerations on whether the public suffix or registry suffix designation is more suitable for your application, see this article.
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 invalid
or google.invalid
. This is the recommended method for determining whether a domain is potentially
an addressable host.
Note that this method is equivalent to hasRegistrySuffix()
because all registry
suffixes are public suffixes and all public suffixes have registry suffixes.
public InternetDomainName publicSuffix()
null
if no public suffix is present.public boolean isUnderPublicSuffix()
true
for www.google.com
, foo.co.uk
and myblog.blogspot.com
, but not for com
,
co.uk
, google.invalid
, or blogspot.com
.
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
foo.co.uk
, and myblog.blogspot.com
, but not for www.google.com
, co.uk
, or blogspot.com
.
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. Similarly, for myblog.blogspot.com
it returns the same domain, myblog.blogspot.com
, since blogspot.com
is a public suffix.
If isTopPrivateDomain()
is true, the current domain name instance is returned.
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 suffixpublic boolean isRegistrySuffix()
com
, co.uk
, and pvt.k12.wy.us
. Examples of domain names that are not registry suffixes include google.com
and foo.co.uk
.
Registry suffixes are a proper subset of public suffixes. The
list of public suffixes additionally contains privately owned domain names under which Internet
users can register subdomains. An example of a public suffix that is not a registry suffix is
blogspot.com
. Note that it is true that all public suffixes have registry
suffixes, since domain name registries collectively control all internet domain names.
For considerations on whether the public suffix or registry suffix designation is more suitable for your application, see this article.
true
if this domain name appears exactly on the public suffix list as part of
the registry suffix section (labelled "ICANN").public boolean hasRegistrySuffix()
true
for www.google.com
, foo.co.uk
and com
, but not for invalid
or google.invalid
.
Note that this method is equivalent to hasPublicSuffix()
because all registry
suffixes are public suffixes and all public suffixes have registry suffixes.
public InternetDomainName registrySuffix()
null
if no registry suffix is present.public boolean isUnderRegistrySuffix()
true
for www.google.com
, foo.co.uk
and blogspot.com
, but not for com
, co.uk
, or google.invalid
.public boolean isTopDomainUnderRegistrySuffix()
true
for google.com
, foo.co.uk
, and blogspot.com
, but not for www.google.com
,
co.uk
, or myblog.blogspot.com
.
Warning: This method should not be used to determine the probable highest level
parent domain for which cookies may be set. Use topPrivateDomain()
for that purpose.
public InternetDomainName topDomainUnderRegistrySuffix()
x.adwords.google.co.uk
it
returns google.co.uk
, since co.uk
is a registry suffix. Similarly, for myblog.blogspot.com
it returns blogspot.com
, since com
is a registry suffix.
If isTopDomainUnderRegistrySuffix()
is true, the current domain name instance is
returned.
Warning: This method should not be used to determine whether a domain is probably the
highest level for which cookies may be set. Use isTopPrivateDomain()
for that purpose.
IllegalStateException
- if this domain does not end with a registry 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
.IllegalStateException
- if the domain has no parent, as determined by hasParent()
public InternetDomainName child(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 nullIllegalArgumentException
- if the resulting name is not validpublic static boolean isValid(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
)public boolean equals(@Nullable Object object)
equals
in class Object
object
- the reference object with which to compare.true
if this object is the same as the obj
argument; false
otherwise.Object.hashCode()
,
HashMap
public int hashCode()
java.lang.Object
HashMap
.
The general contract of hashCode
is:
hashCode
method
must consistently return the same integer, provided no information
used in equals
comparisons on the object is modified.
This integer need not remain consistent from one execution of an
application to another execution of the same application.
equals(Object)
method, then calling the hashCode
method on each of
the two objects must produce the same integer result.
Object.equals(java.lang.Object)
method, then calling the hashCode
method on each of the
two objects must produce distinct integer results. However, the
programmer should be aware that producing distinct integer results
for unequal objects may improve the performance of hash tables.
As much as is reasonably practical, the hashCode method defined by
class Object
does return distinct integers for distinct
objects. (This is typically implemented by converting the internal
address of the object into an integer, but this implementation
technique is not required by the
Java™ programming language.)
hashCode
in class Object
Object.equals(java.lang.Object)
,
System.identityHashCode(java.lang.Object)
Copyright © 2010–2019. All rights reserved.