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 TLDs but not themselves TLDs; hasRecognizedTld() and isImmediatelyUnderTld() test for this. Similarly, one often needs to obtain the domain consisting of the TLD plus one subdomain level, typically to obtain the highest-level domain for which cookies may be set. Use topCookieDomain() for this purpose.

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

TLD identification is done by reference to the generated Java class TldPatterns, which is in turn derived from a Mozilla-supplied text file listing known TLD patterns.

Note that internationalized domain names (IDN) are not supported. If IDN is required, the ToASCII transformation (described in the referenced page) should be applied to the domain string before it is provided to this class.

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 parts of the domain name, normalized to all lower case.

isRecognizedTld

public boolean isRecognizedTld()

Returns true if the domain name is an effective top-level domain. An effective TLD is a domain which is controlled by a national or other registrar, and which is not itself in use as a real, separately addressable domain name. Addressable domains occur as subdomains of effective TLDs. Examples of TLDs include com, co.uk, and ca.us. Examples of non-TLDs include google, google.com, and foo.co.uk.

Identification of effective TLDs is done by reference to a list of patterns maintained by the Mozilla project; see the Gecko:Effective TLD List project page for details.

TODO: Note that the Mozilla TLD list does not guarantee that the one-part TLDs like com and us will necessarily be listed explicitly in the patterns file. All of the ones required for proper operation of this class appear to be there in the current version of the file, but this might not always be the case. We may wish to tighten this up by providing an auxilliary source for the canonical one-part TLDs, using the existing "amendment file" process or a similar mechanism.

isUnderRecognizedTld

public boolean isUnderRecognizedTld()

Returns true if the domain name ends in a TLD, but is not a complete TLD itself. For example, returns true for www.google.com, foo.co.uk, and bar.ca.us; returns false for google, com, and google.foo.

hasRecognizedTld

public boolean hasRecognizedTld()

Returns true if the domain name ends in a TLD, or is a complete TLD itself. For example, returns true for www.google.com, foo.co.uk, and com; returns false for google and google.foo.

recognizedTld

public InternetDomainName recognizedTld()

Returns the TLD portion of the domain name, or null if no TLD is present according to hasRecognizedTld().

isImmediatelyUnderTld

public boolean isImmediatelyUnderTld()

Returns true if the domain name is an immediate subdomain of a TLD, but is not a TLD itself. For example, returns true for google.com and foo.co.uk; returns false for www.google.com and co.uk.

rightmostNonTldPart

public String rightmostNonTldPart()

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.

topCookieDomain

public InternetDomainName topCookieDomain()

Returns the "top cookie domain" for the InternetDomainName. This is defined as the domain consisting of the TLD plus one subdomain level. This is the highest-level parent of this domain for which cookies may be set, as cookies cannot be set on TLDs themselves. Note that this information has non-cookie-related uses as well, but determining the cookie domain is the most common.

If called on a domain for which isImmediatelyUnderTld() is true, this is an identity operation which returns the existing object.

Throws:

IllegalStateException - if the domain is not under a recognized TLD.

hasParent

public boolean hasParent()

Does this domain have a parent domain? That is, does it have two or more parts?

parent

public InternetDomainName parent()

Create a new InternetDomainName which is the parent of this one; that is, the parent domain is the current domain with the leftmost part removed. For example, new InternetDomainName("www.google.com").parent() returns a new InternetDomainName corresponding to the value "google.com".

Throws:

IllegalStateException - if the domain has no parent

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)

Determines 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 should instead be written as follows:

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

toString

public String toString()

Overrides:

toString in class Object

equals

public boolean equals(@Nullable
                      Object object)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object