InternetDomainName (Guava: Google Core Libraries for Java 28.0-jre API)

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

```
@Beta
 @GwtCompatible
 @Immutable
public final 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. 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:
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 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.
Since:

5.0

Author:

Catherine Berry

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
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.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Method Detail
  - from
```
public static InternetDomainName from(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:
    - Any part containing non-ASCII characters is considered valid.
    - Underscores ('_') are permitted wherever dashes ('-') are permitted.
    - Parts other than the final part may start with a digit, as mandated by RFC 1123.
    Parameters:
    
    domain - A domain name (not IP address)
    
    Throws:
    
    IllegalArgumentException - if domain is not syntactically valid according to isValid(java.lang.String)
    
    Since:
    
    10.0 (previously named fromLenient)
  - 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.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.
    
    Returns:
    
    true if this domain name appears exactly on the public suffix list
    
    Since:
    
    6.0
  - 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 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.
    
    Since:
    
    6.0
  - publicSuffix
```
public InternetDomainName publicSuffix()
```
    Returns the public suffix portion of the domain name, or null if no public suffix is present.
    
    Since:
    
    6.0
  - 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 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.
    
    Since:
    
    6.0
  - 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 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.
    
    Since:
    
    6.0
  - 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. 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.
    
    Throws:
    
    IllegalStateException - if this domain does not end with a public suffix
    
    Since:
    
    6.0
  - isRegistrySuffix
```
public 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). A registry suffix is one under which Internet users can directly register names via a domain name registrar, and have such registrations lawfully protected by internet-governing bodies such as ICANN. Examples of registry suffixes include 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.
    
    Returns:
    
    true if this domain name appears exactly on the public suffix list as part of the registry suffix section (labelled "ICANN").
    
    Since:
    
    23.3
  - hasRegistrySuffix
```
public boolean hasRegistrySuffix()
```
    Indicates whether this domain name ends in a registry suffix, including if it is a registry suffix itself. For example, returns 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.
    
    Since:
    
    23.3
  - registrySuffix
```
public InternetDomainName registrySuffix()
```
    Returns the registry suffix portion of the domain name, or null if no registry suffix is present.
    
    Since:
    
    23.3
  - isUnderRegistrySuffix
```
public boolean isUnderRegistrySuffix()
```
    Indicates whether this domain name ends in a registry suffix, while not being a registry suffix itself. For example, returns true for www.google.com, foo.co.uk and blogspot.com, but not for com, co.uk, or google.invalid.
    
    Since:
    
    23.3
  - isTopDomainUnderRegistrySuffix
```
public boolean isTopDomainUnderRegistrySuffix()
```
    Indicates whether this domain name is composed of exactly one subdomain component followed by a registry suffix. For example, returns 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.
    
    Since:
    
    23.3
  - topDomainUnderRegistrySuffix
```
public InternetDomainName topDomainUnderRegistrySuffix()
```
    Returns the portion of this domain name that is one level beneath the registry suffix. For example, for 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.
    
    Throws:
    
    IllegalStateException - if this domain does not end with a registry suffix
    
    Since:
    
    23.3
  - 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. Only lenient validation is performed, as described here.
    
    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 using lenient validation. Specifically, validation against RFC 3490 ("Internationalizing Domain Names in Applications") is skipped.
    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;
 }
 
```
    Since:
    
    8.0 (previously named isValidLenient)
  - toString
```
public String toString()
```
    Returns the domain name, normalized to all lower case.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    a string representation of the object.
  - equals
```
public boolean equals(@Nullable Object object)
```
    Equality testing is based on the text supplied by the caller, after normalization as described in the class documentation. For example, a non-ASCII Unicode domain name and the Punycode version of the same domain name would not be considered equal.
    
    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™ 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)

Class InternetDomainName

Method Summary

Methods inherited from class java.lang.Object

Method Detail

from

parts

isPublicSuffix

hasPublicSuffix

publicSuffix

isUnderPublicSuffix

isTopPrivateDomain

topPrivateDomain

isRegistrySuffix

hasRegistrySuffix

registrySuffix

isUnderRegistrySuffix

isTopDomainUnderRegistrySuffix

topDomainUnderRegistrySuffix

hasParent

parent

child

isValid

toString

equals

hashCode