com.google.common.net
Class InternetDomainName

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

@Beta
public final class InternetDomainName
extends Object

An immutable well-formed internet domain name, as defined by RFC 1035, with the exception that names ending in "." are not supported (as they are not generally used in browsers, email, and other end-user applications. Examples include com and 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. Invalid domain names throw IllegalArgumentException on construction.

It is often the case that domains of interest are those under a public suffix but not themselves a public suffix; hasPublicSuffix() and isTopPrivateDomain() test for this. Similarly, one often needs to obtain the domain consisting of the public suffix plus one subdomain level, typically to obtain the highest-level domain for which cookies may be set. Use topPrivateDomain() for this purpose.

Equality of domain names is case-insensitive, so for convenience, the name() and parts() methods return the lowercase form of the name.

internationalized domain names (IDN) such as 网络.cn are supported.

Since:

5

Author:

Craig Berry

from

public static InternetDomainName from(String domain)

A factory method for creating InternetDomainName objects.

Parameters:

domain - A domain name (not IP address)

Throws:

IllegalArgumentException - If name is not syntactically valid

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"].

isRecognizedTld

@Deprecated
public boolean isRecognizedTld()

Deprecated. use isPublicSuffix()

Old location of isPublicSuffix().

isUnderRecognizedTld

@Deprecated
public boolean isUnderRecognizedTld()

Deprecated. use isUnderPublicSuffix()

Old location of isUnderPublicSuffix().

hasRecognizedTld

@Deprecated
public boolean hasRecognizedTld()

Deprecated. use hasPublicSuffix()

Old location of hasPublicSuffix().

recognizedTld

@Deprecated
public InternetDomainName recognizedTld()

Deprecated. use publicSuffix()

Old location of publicSuffix().

isImmediatelyUnderTld

@Deprecated
public boolean isImmediatelyUnderTld()

Deprecated. use isTopPrivateDomain()

Old location of isTopPrivateDomain().

topCookieDomain

@Deprecated
public InternetDomainName topCookieDomain()

Deprecated. use topPrivateDomain()

Old location of topPrivateDomain().

rightmostNonTldPart

@Deprecated
public String rightmostNonTldPart()

Deprecated. use the first part of the topPrivateDomain()

Returns the rightmost non-TLD domain name part. For example new InternetDomainName("www.google.com").rightmostNonTldPart() returns "google". Returns null if either no TLD is found, or the whole domain name is itself a TLD.

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.

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.

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.

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. This is the highest-level parent of this domain for which cookies may be set, as cookies cannot be set on a public suffix itself.

If isTopPrivateDomain() is true, the current domain name instance is returned.

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.from("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

isValid

public static boolean isValid(String name)

Indicates whether the argument is a syntactically valid domain name. This method is intended for the case where a String must be validated as a valid domain name, but no further work with that String as an InternetDomainName will be required. Code like the following will unnecessarily repeat the work of validation:

   if (InternetDomainName.isValid(name)) {
     domainName = InternetDomainName.from(name);
   } else {
     domainName = DEFAULT_DOMAIN;
   }

Such code could instead be written as follows:

   try {
     domainName = InternetDomainName.from(name);
   } catch (IllegalArgumentException e) {
     domainName = DEFAULT_DOMAIN;
   }

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:

• It is reflexive: for any non-null reference value x, x.equals(x) should return true.
• It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
• It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
• It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
• For any non-null reference value x, x.equals(null) should return false.

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(), HashMap

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 hash tables such as those provided by HashMap.

The general contract of hashCode is:

• Whenever it is invoked on the same object more than once during an execution of a Java application, the 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.
• If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.
• It is not required that if two objects are unequal according to the 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^TM programming language.)

Overrides:

hashCode in class Object

Returns:

a hash code value for this object.

See Also:

Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)