Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
  /*
   * Copyright (C) 2009 The Guava Authors
   *
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   * http://www.apache.org/licenses/LICENSE-2.0
   *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 
 package com.google.common.net;
 
 import static com.google.common.base.Preconditions.checkArgument;
 import static com.google.common.base.Preconditions.checkNotNull;
 import static com.google.common.base.Preconditions.checkState;
 
 
 import java.util.List;
 
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 isPublicSuffix() 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(java.lang.Object).

internationalized domain names such as 网络.cn are supported, as are the equivalent IDNA Punycode-encoded versions.

Author(s):
Craig Berry
Since:
5.0
 
 @GwtCompatible(emulated = true)
 public final class InternetDomainName {
 
   private static final CharMatcher DOTS_MATCHER =
       CharMatcher.anyOf(".\u3002\uFF0E\uFF61");
   private static final Splitter DOT_SPLITTER = Splitter.on('.');
   private static final Joiner DOT_JOINER = Joiner.on('.');

  
Value of publicSuffixIndex which indicates that no public suffix was found.
 
   private static final int NO_PUBLIC_SUFFIX_FOUND = -1;
 
   private static final String DOT_REGEX = "\\.";

  
Maximum parts (labels) in a domain name. This value arises from the 255-octet limit described in RFC 2181 part 11 with the fact that the encoding of each part occupies at least two bytes (dot plus label externally, length byte plus label internally). Thus, if all labels have the minimum size of one byte, 127 of them will fit.
 
  private static final int MAX_PARTS = 127;

  
Maximum length of a full domain name, including separators, and leaving room for the root label. See RFC 2181 part 11.
  private static final int MAX_LENGTH = 253;

  
Maximum size of a single part of a domain name. See RFC 2181 part 11.
  private static final int MAX_DOMAIN_PART_LENGTH = 63;

  
The full domain name, converted to lower case.
  private final String name;

  
The parts of the domain name, converted to lower case.
  private final ImmutableList<Stringparts;

  
The index in the parts() list at which the public suffix begins. For example, for the domain name www.google.co.uk, the value would be 2 (the index of the co part). The value is negative (specifically, NO_PUBLIC_SUFFIX_FOUND) if no public suffix was found.
  private final int publicSuffixIndex;

  
Constructor used to implement from(java.lang.String), and from subclasses.
    // Normalize:
    // * ASCII characters to lowercase
    // * All dot-like characters to '.'
    // * Strip trailing '.'
    name = Ascii.toLowerCase(.replaceFrom(name'.'));
    if (name.endsWith(".")) {
      name = name.substring(0, name.length() - 1);
    }
    checkArgument(name.length() <= ,
        "Domain name too long: '%s':"name);
    this. = name;
    this. = ImmutableList.copyOf(.split(name));
        "Domain has too many parts: '%s'"name);
    checkArgument(validateSyntax(), "Not a valid domain name: '%s'"name);
  }

  
Returns the index of the leftmost part of the public suffix, or -1 if not found. Note that the value defined as the "public suffix" may not be a public suffix according to isPublicSuffix() if the domain ends with an excluded domain pattern such as "nhs.uk".
  private int findPublicSuffix() {
    final int partsSize = .size();
    for (int i = 0; i < partsSizei++) {
      String ancestorName = .join(.subList(ipartsSize));
      if (..contains(ancestorName)) {
        return i;
      }
      // Excluded domains (e.g. !nhs.uk) use the next highest
      // domain as the effective public suffix (e.g. uk).
      if (..contains(ancestorName)) {
        return i + 1;
      }
      if (matchesWildcardPublicSuffix(ancestorName)) {
        return i;
      }
    }
    return ;
  }

  
A deprecated synonym for from(java.lang.String).

Deprecated:
Use from(java.lang.String)
Parameters:
domain A domain name (not IP address)
Throws:
java.lang.IllegalArgumentException if name is not syntactically valid according to isValidLenient(java.lang.String)
Since:
8.0 (previously named from)
  public static InternetDomainName fromLenient(String domain) {
    return from(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.

Parameters:
domain A domain name (not IP address)
Throws:
java.lang.IllegalArgumentException if name is not syntactically valid according to isValid(java.lang.String)
Since:
10.0 (previously named fromLenient)
  public static InternetDomainName from(String domain) {
    return new InternetDomainName(checkNotNull(domain));
  }

  
Validation method used by to ensure that the domain name is syntactically valid according to RFC 1035.

Returns:
Is the domain name syntactically valid?
  private static boolean validateSyntax(List<Stringparts) {
    final int lastIndex = parts.size() - 1;
    // Validate the last part specially, as it has different syntax rules.
    if (!validatePart(parts.get(lastIndex), true)) {
      return false;
    }
    for (int i = 0; i < lastIndexi++) {
      String part = parts.get(i);
      if (!validatePart(partfalse)) {
        return false;
      }
    }
    return true;
  }
  private static final CharMatcher DASH_MATCHER = CharMatcher.anyOf("-_");
  private static final CharMatcher PART_CHAR_MATCHER =
Helper method for validateSyntax(java.util.List). Validates that one part of a domain name is valid.

Parameters:
part The domain name part to be validated
isFinalPart Is this the final (rightmost) domain part?
Returns:
Whether the part is valid
  private static boolean validatePart(String partboolean isFinalPart) {
    // These tests could be collapsed into one big boolean expression, but
    // they have been left as independent tests for clarity.
    if (part.length() < 1 || part.length() > ) {
      return false;
    }
    /*
     * GWT claims to support java.lang.Character's char-classification methods,
     * but it actually only works for ASCII. So for now, assume any non-ASCII
     * characters are valid. The only place this seems to be documented is here:
     * http://osdir.com/ml/GoogleWebToolkitContributors/2010-03/msg00178.html
     *
     * <p>ASCII characters in the part are expected to be valid per RFC 1035,
     * with underscore also being allowed due to widespread practice.
     */
    String asciiChars = ..retainFrom(part);
    if (!.matchesAllOf(asciiChars)) {
      return false;
    }
    // No initial or final dashes or underscores.
    if (.matches(part.charAt(0))
        || .matches(part.charAt(part.length() - 1))) {
      return false;
    }
    /*
     * Note that we allow (in contravention of a strict interpretation of the
     * relevant RFCs) domain parts other than the last may begin with a digit
     * (for example, "3com.com"). It's important to disallow an initial digit in
     * the last part; it's the only thing that stops an IPv4 numeric address
     * like 127.0.0.1 from looking like a valid domain name.
     */
    if (isFinalPart && ..matches(part.charAt(0))) {
      return false;
    }
    return true;
  }

  
Returns the domain name, normalized to all lower case.
  public String name() {
    return ;
  }

  
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"].
  public ImmutableList<Stringparts() {
    return ;
  }

  
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.0
  public boolean isPublicSuffix() {
    return  == 0;
  }

  
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.0
  public boolean hasPublicSuffix() {
  }

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

Since:
6.0
    return hasPublicSuffix() ? ancestor() : null;
  }

  
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.0
  public boolean isUnderPublicSuffix() {
    return  > 0;
  }

  
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.0
  public boolean isTopPrivateDomain() {
    return  == 1;
  }

  
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:
java.lang.IllegalStateException if this domain does not end with a public suffix
Since:
6.0
    if (isTopPrivateDomain()) {
      return this;
    }
    checkState(isUnderPublicSuffix(), "Not under a public suffix: %s");
    return ancestor( - 1);
  }

  
Indicates whether this domain is composed of two or more parts.
  public boolean hasParent() {
    return .size() > 1;
  }

  
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:
java.lang.IllegalStateException if the domain has no parent, as determined by hasParent()
  public InternetDomainName parent() {
    checkState(hasParent(), "Domain '%s' has no parent");
    return ancestor(1);
  }

  
Returns the ancestor of the current domain at the given number of levels "higher" (rightward) in the subdomain list. The number of levels must be non-negative, and less than N-1, where N is the number of parts in the domain.

TODO: Reasonable candidate for addition to public API.

  private InternetDomainName ancestor(int levels) {
    return from(.join(.subList(levels.size())));
  }

  
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:
java.lang.NullPointerException if leftParts is null
java.lang.IllegalArgumentException if the resulting name is not valid
  public InternetDomainName child(String leftParts) {
    return from(checkNotNull(leftParts) + "." + );
  }

  
A deprecated synonym for isValid(java.lang.String).

Deprecated:
Use isValid(java.lang.String) instead
Since:
8.0 (previously named isValid)
  public static boolean isValidLenient(String name) {
    return isValid(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)
  public static boolean isValid(String name) {
    try {
      from(name);
      return true;
    } catch (IllegalArgumentException e) {
      return false;
    }
  }

  
Does the domain name match one of the "wildcard" patterns (e.g. "*.ar")?
  private static boolean matchesWildcardPublicSuffix(String domain) {
    final String[] pieces = domain.split(, 2);
    return pieces.length == 2 && ..contains(pieces[1]);
  }
  // TODO: specify this to return the same as name(); remove name()
  public String toString() {
    return Objects.toStringHelper(this).add("name").toString();
  }

  
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.
  public boolean equals(@Nullable Object object) {
    if (object == this) {
      return true;
    }
    if (object instanceof InternetDomainName) {
      InternetDomainName that = (InternetDomainNameobject;
      return this..equals(that.name);
    }
    return false;
  }
  public int hashCode() {
    return .hashCode();
  }
New to GrepCode? Check out our FAQ X