com.google.common.net
Class InternetDomainName

java.lang.Object
  extended by com.google.common.net.InternetDomainName

@Beta
@GwtCompatible(emulated=true)
public class InternetDomainName
extends Object

An immutable well-formed internet domain name, such as 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:

  1. ASCII uppercase characters are converted to lowercase.
  2. Unicode dot separators other than the ASCII period ('.') are converted to the ASCII period.
The normalized values will be returned from name() 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.

Since:
5
Author:
Craig Berry

Method Summary
 InternetDomainName child(String leftParts)
          Creates and returns a new InternetDomainName by prepending the argument and a dot to the current name.
 boolean equals(Object object)
          Indicates whether some other object is "equal to" this one.
static InternetDomainName fromLenient(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 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 isValidLenient(String name)
          Indicates whether the argument is a syntactically valid domain name after lenient validation.
 String name()
          Returns the domain name, normalized to all lower case.
 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 topPrivateDomain()
          Returns the portion of this domain name that is one level beneath the public suffix.
 String toString()
          Returns a string representation of the object.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Method Detail

fromLenient

public static InternetDomainName fromLenient(String domain)
Returns an instance of 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:

Parameters:
domain - A domain name (not IP address)
Throws:
IllegalArgumentException - if name is not syntactically valid according to isValidLenient(java.lang.String)
Since:
8 (previously named from)

name

public String name()
Returns the domain name, normalized to all lower case.


parts

public ImmutableList<String> parts()
Returns the individual components of this domain name, normalized to all lower case. For example, for the domain name mail.google.com, this method returns the list ["mail", "google", "com"].


isPublicSuffix

public boolean isPublicSuffix()
Indicates whether this domain name represents a public suffix, as defined by the Mozilla Foundation's Public Suffix List (PSL). A public suffix is one under which Internet users can directly register names, such as 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.

Returns:
true if this domain name appears exactly on the public suffix list
Since:
6

hasPublicSuffix

public boolean hasPublicSuffix()
Indicates whether this domain name ends in a public suffix, including if it is a public suffix itself. For example, returns 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.

Since:
6

publicSuffix

public InternetDomainName publicSuffix()
Returns the public suffix portion of the domain name, or null if no public suffix is present.

Since:
6

isUnderPublicSuffix

public boolean isUnderPublicSuffix()
Indicates whether this domain name ends in a public suffix, while not being a public suffix itself. For example, returns 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.

Since:
6

isTopPrivateDomain

public boolean isTopPrivateDomain()
Indicates whether this domain name is composed of exactly one subdomain component followed by a public suffix. For example, returns 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.

Since:
6

topPrivateDomain

public InternetDomainName topPrivateDomain()
Returns the portion of this domain name that is one level beneath the public suffix. For example, for 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.

Throws:
IllegalStateException - if this domain does not end with a public suffix
Since:
6

hasParent

public boolean hasParent()
Indicates whether this domain is composed of two or more parts.


parent

public InternetDomainName parent()
Returns an 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.

Throws:
IllegalStateException - if the domain has no parent, as determined by hasParent()

child

public InternetDomainName child(String leftParts)
Creates and returns a new InternetDomainName by prepending the argument and a dot to the current name. For example, InternetDomainName.fromLenient("foo.com").child("www.bar") returns a new InternetDomainName with the value www.bar.foo.com.

Throws:
NullPointerException - if leftParts is null
IllegalArgumentException - if the resulting name is not valid

isValidLenient

public static boolean isValidLenient(String name)
Indicates whether the argument is a syntactically valid domain name after lenient validation. Specifically, validation against RFC 3490 ("Internationalizing Domain Names in Applications") is skipped.

The follow two code snippets are equivalent:

   if (InternetDomainName.isValidLenient(name)) {
     domainName = InternetDomainName.fromLenient(name);
   } else {
     domainName = DEFAULT_DOMAIN;
   }
   try {
     domainName = InternetDomainName.fromLenient(name);
   } catch (IllegalArgumentException e) {
     domainName = DEFAULT_DOMAIN;
   }

Since:
8 (previously named isValid)

toString

public String toString()
Description copied from class: java.lang.Object
Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 

Overrides:
toString in class Object
Returns:
a string representation of the object.

equals

public boolean equals(@Nullable
                      Object object)
Description copied from class: java.lang.Object
Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any non-null reference values x and y, this method returns true if and only if x and y refer to the same object (x == y has the value true).

Note that it is generally necessary to override the hashCode method whenever this method is overridden, so as to maintain the general contract for the hashCode method, which states that equal objects must have equal hash codes.

Overrides:
equals in class Object
Parameters:
object - the reference object with which to compare.
Returns:
true if this object is the same as the obj argument; false otherwise.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Description copied from class: java.lang.Object
Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable.

The general contract of hashCode is:

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 JavaTM programming language.)

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable