001/*
002 * Copyright (C) 2009 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.net;
016
017import static com.google.common.base.Preconditions.checkArgument;
018import static com.google.common.base.Preconditions.checkNotNull;
019import static com.google.common.base.Preconditions.checkState;
020
021import com.google.common.annotations.GwtCompatible;
022import com.google.common.base.Ascii;
023import com.google.common.base.CharMatcher;
024import com.google.common.base.Joiner;
025import com.google.common.base.Optional;
026import com.google.common.base.Splitter;
027import com.google.common.collect.ImmutableList;
028import com.google.errorprone.annotations.CanIgnoreReturnValue;
029import com.google.errorprone.annotations.Immutable;
030import com.google.thirdparty.publicsuffix.PublicSuffixPatterns;
031import com.google.thirdparty.publicsuffix.PublicSuffixType;
032import java.util.List;
033import javax.annotation.CheckForNull;
034
035/**
036 * An immutable well-formed internet domain name, such as {@code com} or {@code foo.co.uk}. Only
037 * syntactic analysis is performed; no DNS lookups or other network interactions take place. Thus
038 * there is no guarantee that the domain actually exists on the internet.
039 *
040 * <p>One common use of this class is to determine whether a given string is likely to represent an
041 * addressable domain on the web -- that is, for a candidate string {@code "xxx"}, might browsing to
042 * {@code "http://xxx/"} result in a webpage being displayed? In the past, this test was frequently
043 * done by determining whether the domain ended with a {@linkplain #isPublicSuffix() public suffix}
044 * but was not itself a public suffix. However, this test is no longer accurate. There are many
045 * domains which are both public suffixes and addressable as hosts; {@code "uk.com"} is one example.
046 * Using the subset of public suffixes that are {@linkplain #isRegistrySuffix() registry suffixes},
047 * one can get a better result, as only a few registry suffixes are addressable. However, the most
048 * useful test to determine if a domain is a plausible web host is {@link #hasPublicSuffix()}. This
049 * will return {@code true} for many domains which (currently) are not hosts, such as {@code "com"},
050 * but given that any public suffix may become a host without warning, it is better to err on the
051 * side of permissiveness and thus avoid spurious rejection of valid sites. Of course, to actually
052 * determine addressability of any host, clients of this class will need to perform their own DNS
053 * lookups.
054 *
055 * <p>During construction, names are normalized in two ways:
056 *
057 * <ol>
058 *   <li>ASCII uppercase characters are converted to lowercase.
059 *   <li>Unicode dot separators other than the ASCII period ({@code '.'}) are converted to the ASCII
060 *       period.
061 * </ol>
062 *
063 * <p>The normalized values will be returned from {@link #toString()} and {@link #parts()}, and will
064 * be reflected in the result of {@link #equals(Object)}.
065 *
066 * <p><a href="http://en.wikipedia.org/wiki/Internationalized_domain_name">Internationalized domain
067 * names</a> such as {@code 网络.cn} are supported, as are the equivalent <a
068 * href="http://en.wikipedia.org/wiki/Internationalized_domain_name">IDNA Punycode-encoded</a>
069 * versions.
070 *
071 * @author Catherine Berry
072 * @since 5.0
073 */
074@GwtCompatible(emulated = true)
075@Immutable
076@ElementTypesAreNonnullByDefault
077public final class InternetDomainName {
078
079  private static final CharMatcher DOTS_MATCHER = CharMatcher.anyOf(".\u3002\uFF0E\uFF61");
080  private static final Splitter DOT_SPLITTER = Splitter.on('.');
081  private static final Joiner DOT_JOINER = Joiner.on('.');
082
083  /**
084   * Value of {@link #publicSuffixIndex} or {@link #registrySuffixIndex} which indicates that no
085   * relevant suffix was found.
086   */
087  private static final int NO_SUFFIX_FOUND = -1;
088
089  /**
090   * Maximum parts (labels) in a domain name. This value arises from the 255-octet limit described
091   * in <a href="http://www.ietf.org/rfc/rfc2181.txt">RFC 2181</a> part 11 with the fact that the
092   * encoding of each part occupies at least two bytes (dot plus label externally, length byte plus
093   * label internally). Thus, if all labels have the minimum size of one byte, 127 of them will fit.
094   */
095  private static final int MAX_PARTS = 127;
096
097  /**
098   * Maximum length of a full domain name, including separators, and leaving room for the root
099   * label. See <a href="http://www.ietf.org/rfc/rfc2181.txt">RFC 2181</a> part 11.
100   */
101  private static final int MAX_LENGTH = 253;
102
103  /**
104   * Maximum size of a single part of a domain name. See <a
105   * href="http://www.ietf.org/rfc/rfc2181.txt">RFC 2181</a> part 11.
106   */
107  private static final int MAX_DOMAIN_PART_LENGTH = 63;
108
109  /** The full domain name, converted to lower case. */
110  private final String name;
111
112  /** The parts of the domain name, converted to lower case. */
113  private final ImmutableList<String> parts;
114
115  /**
116   * The index in the {@link #parts()} list at which the public suffix begins. For example, for the
117   * domain name {@code myblog.blogspot.co.uk}, the value would be 1 (the index of the {@code
118   * blogspot} part). The value is negative (specifically, {@link #NO_SUFFIX_FOUND}) if no public
119   * suffix was found.
120   */
121  private final int publicSuffixIndex;
122
123  /**
124   * The index in the {@link #parts()} list at which the registry suffix begins. For example, for
125   * the domain name {@code myblog.blogspot.co.uk}, the value would be 2 (the index of the {@code
126   * co} part). The value is negative (specifically, {@link #NO_SUFFIX_FOUND}) if no registry suffix
127   * was found.
128   */
129  private final int registrySuffixIndex;
130
131  /** Constructor used to implement {@link #from(String)}, and from subclasses. */
132  InternetDomainName(String name) {
133    // Normalize:
134    // * ASCII characters to lowercase
135    // * All dot-like characters to '.'
136    // * Strip trailing '.'
137
138    name = Ascii.toLowerCase(DOTS_MATCHER.replaceFrom(name, '.'));
139
140    if (name.endsWith(".")) {
141      name = name.substring(0, name.length() - 1);
142    }
143
144    checkArgument(name.length() <= MAX_LENGTH, "Domain name too long: '%s':", name);
145    this.name = name;
146
147    this.parts = ImmutableList.copyOf(DOT_SPLITTER.split(name));
148    checkArgument(parts.size() <= MAX_PARTS, "Domain has too many parts: '%s'", name);
149    checkArgument(validateSyntax(parts), "Not a valid domain name: '%s'", name);
150
151    this.publicSuffixIndex = findSuffixOfType(Optional.<PublicSuffixType>absent());
152    this.registrySuffixIndex = findSuffixOfType(Optional.of(PublicSuffixType.REGISTRY));
153  }
154
155  /**
156   * Returns the index of the leftmost part of the suffix, or -1 if not found. Note that the value
157   * defined as a suffix may not produce {@code true} results from {@link #isPublicSuffix()} or
158   * {@link #isRegistrySuffix()} if the domain ends with an excluded domain pattern such as {@code
159   * "nhs.uk"}.
160   *
161   * <p>If a {@code desiredType} is specified, this method only finds suffixes of the given type.
162   * Otherwise, it finds the first suffix of any type.
163   */
164  private int findSuffixOfType(Optional<PublicSuffixType> desiredType) {
165    int partsSize = parts.size();
166
167    for (int i = 0; i < partsSize; i++) {
168      String ancestorName = DOT_JOINER.join(parts.subList(i, partsSize));
169
170      if (matchesType(
171          desiredType, Optional.fromNullable(PublicSuffixPatterns.EXACT.get(ancestorName)))) {
172        return i;
173      }
174
175      // Excluded domains (e.g. !nhs.uk) use the next highest
176      // domain as the effective public suffix (e.g. uk).
177
178      if (PublicSuffixPatterns.EXCLUDED.containsKey(ancestorName)) {
179        return i + 1;
180      }
181
182      if (matchesWildcardSuffixType(desiredType, ancestorName)) {
183        return i;
184      }
185    }
186
187    return NO_SUFFIX_FOUND;
188  }
189
190  /**
191   * Returns an instance of {@link InternetDomainName} after lenient validation. Specifically,
192   * validation against <a href="http://www.ietf.org/rfc/rfc3490.txt">RFC 3490</a>
193   * ("Internationalizing Domain Names in Applications") is skipped, while validation against <a
194   * href="http://www.ietf.org/rfc/rfc1035.txt">RFC 1035</a> is relaxed in the following ways:
195   *
196   * <ul>
197   *   <li>Any part containing non-ASCII characters is considered valid.
198   *   <li>Underscores ('_') are permitted wherever dashes ('-') are permitted.
199   *   <li>Parts other than the final part may start with a digit, as mandated by <a
200   *       href="https://tools.ietf.org/html/rfc1123#section-2">RFC 1123</a>.
201   * </ul>
202   *
203   * @param domain A domain name (not IP address)
204   * @throws IllegalArgumentException if {@code domain} is not syntactically valid according to
205   *     {@link #isValid}
206   * @since 10.0 (previously named {@code fromLenient})
207   */
208  @CanIgnoreReturnValue // TODO(b/219820829): consider removing
209  public static InternetDomainName from(String domain) {
210    return new InternetDomainName(checkNotNull(domain));
211  }
212
213  /**
214   * Validation method used by {@code from} to ensure that the domain name is syntactically valid
215   * according to RFC 1035.
216   *
217   * @return Is the domain name syntactically valid?
218   */
219  private static boolean validateSyntax(List<String> parts) {
220    int lastIndex = parts.size() - 1;
221
222    // Validate the last part specially, as it has different syntax rules.
223
224    if (!validatePart(parts.get(lastIndex), true)) {
225      return false;
226    }
227
228    for (int i = 0; i < lastIndex; i++) {
229      String part = parts.get(i);
230      if (!validatePart(part, false)) {
231        return false;
232      }
233    }
234
235    return true;
236  }
237
238  private static final CharMatcher DASH_MATCHER = CharMatcher.anyOf("-_");
239
240  private static final CharMatcher DIGIT_MATCHER = CharMatcher.inRange('0', '9');
241
242  private static final CharMatcher LETTER_MATCHER =
243      CharMatcher.inRange('a', 'z').or(CharMatcher.inRange('A', 'Z'));
244
245  private static final CharMatcher PART_CHAR_MATCHER =
246      DIGIT_MATCHER.or(LETTER_MATCHER).or(DASH_MATCHER);
247
248  /**
249   * Helper method for {@link #validateSyntax(List)}. Validates that one part of a domain name is
250   * valid.
251   *
252   * @param part The domain name part to be validated
253   * @param isFinalPart Is this the final (rightmost) domain part?
254   * @return Whether the part is valid
255   */
256  private static boolean validatePart(String part, boolean isFinalPart) {
257
258    // These tests could be collapsed into one big boolean expression, but
259    // they have been left as independent tests for clarity.
260
261    if (part.length() < 1 || part.length() > MAX_DOMAIN_PART_LENGTH) {
262      return false;
263    }
264
265    /*
266     * GWT claims to support java.lang.Character's char-classification methods, but it actually only
267     * works for ASCII. So for now, assume any non-ASCII characters are valid. The only place this
268     * seems to be documented is here:
269     * https://groups.google.com/d/topic/google-web-toolkit-contributors/1UEzsryq1XI
270     *
271     * <p>ASCII characters in the part are expected to be valid per RFC 1035, with underscore also
272     * being allowed due to widespread practice.
273     */
274
275    String asciiChars = CharMatcher.ascii().retainFrom(part);
276
277    if (!PART_CHAR_MATCHER.matchesAllOf(asciiChars)) {
278      return false;
279    }
280
281    // No initial or final dashes or underscores.
282
283    if (DASH_MATCHER.matches(part.charAt(0))
284        || DASH_MATCHER.matches(part.charAt(part.length() - 1))) {
285      return false;
286    }
287
288    /*
289     * Note that we allow (in contravention of a strict interpretation of the relevant RFCs) domain
290     * parts other than the last may begin with a digit (for example, "3com.com"). It's important to
291     * disallow an initial digit in the last part; it's the only thing that stops an IPv4 numeric
292     * address like 127.0.0.1 from looking like a valid domain name.
293     */
294
295    if (isFinalPart && DIGIT_MATCHER.matches(part.charAt(0))) {
296      return false;
297    }
298
299    return true;
300  }
301
302  /**
303   * Returns the individual components of this domain name, normalized to all lower case. For
304   * example, for the domain name {@code mail.google.com}, this method returns the list {@code
305   * ["mail", "google", "com"]}.
306   */
307  public ImmutableList<String> parts() {
308    return parts;
309  }
310
311  /**
312   * Indicates whether this domain name represents a <i>public suffix</i>, as defined by the Mozilla
313   * Foundation's <a href="http://publicsuffix.org/">Public Suffix List</a> (PSL). A public suffix
314   * is one under which Internet users can directly register names, such as {@code com}, {@code
315   * co.uk} or {@code pvt.k12.wy.us}. Examples of domain names that are <i>not</i> public suffixes
316   * include {@code google.com}, {@code foo.co.uk}, and {@code myblog.blogspot.com}.
317   *
318   * <p>Public suffixes are a proper superset of {@linkplain #isRegistrySuffix() registry suffixes}.
319   * The list of public suffixes additionally contains privately owned domain names under which
320   * Internet users can register subdomains. An example of a public suffix that is not a registry
321   * suffix is {@code blogspot.com}. Note that it is true that all public suffixes <i>have</i>
322   * registry suffixes, since domain name registries collectively control all internet domain names.
323   *
324   * <p>For considerations on whether the public suffix or registry suffix designation is more
325   * suitable for your application, see <a
326   * href="https://github.com/google/guava/wiki/InternetDomainNameExplained">this article</a>.
327   *
328   * @return {@code true} if this domain name appears exactly on the public suffix list
329   * @since 6.0
330   */
331  public boolean isPublicSuffix() {
332    return publicSuffixIndex == 0;
333  }
334
335  /**
336   * Indicates whether this domain name ends in a {@linkplain #isPublicSuffix() public suffix},
337   * including if it is a public suffix itself. For example, returns {@code true} for {@code
338   * www.google.com}, {@code foo.co.uk} and {@code com}, but not for {@code invalid} or {@code
339   * google.invalid}. This is the recommended method for determining whether a domain is potentially
340   * an addressable host.
341   *
342   * <p>Note that this method is equivalent to {@link #hasRegistrySuffix()} because all registry
343   * suffixes are public suffixes <i>and</i> all public suffixes have registry suffixes.
344   *
345   * @since 6.0
346   */
347  public boolean hasPublicSuffix() {
348    return publicSuffixIndex != NO_SUFFIX_FOUND;
349  }
350
351  /**
352   * Returns the {@linkplain #isPublicSuffix() public suffix} portion of the domain name, or {@code
353   * null} if no public suffix is present.
354   *
355   * @since 6.0
356   */
357  @CheckForNull
358  public InternetDomainName publicSuffix() {
359    return hasPublicSuffix() ? ancestor(publicSuffixIndex) : null;
360  }
361
362  /**
363   * Indicates whether this domain name ends in a {@linkplain #isPublicSuffix() public suffix},
364   * while not being a public suffix itself. For example, returns {@code true} for {@code
365   * www.google.com}, {@code foo.co.uk} and {@code myblog.blogspot.com}, but not for {@code com},
366   * {@code co.uk}, {@code google.invalid}, or {@code blogspot.com}.
367   *
368   * <p>This method can be used to determine whether it will probably be possible to set cookies on
369   * the domain, though even that depends on individual browsers' implementations of cookie
370   * controls. See <a href="http://www.ietf.org/rfc/rfc2109.txt">RFC 2109</a> for details.
371   *
372   * @since 6.0
373   */
374  public boolean isUnderPublicSuffix() {
375    return publicSuffixIndex > 0;
376  }
377
378  /**
379   * Indicates whether this domain name is composed of exactly one subdomain component followed by a
380   * {@linkplain #isPublicSuffix() public suffix}. For example, returns {@code true} for {@code
381   * google.com} {@code foo.co.uk}, and {@code myblog.blogspot.com}, but not for {@code
382   * www.google.com}, {@code co.uk}, or {@code blogspot.com}.
383   *
384   * <p>This method can be used to determine whether a domain is probably the highest level for
385   * which cookies may be set, though even that depends on individual browsers' implementations of
386   * cookie controls. See <a href="http://www.ietf.org/rfc/rfc2109.txt">RFC 2109</a> for details.
387   *
388   * @since 6.0
389   */
390  public boolean isTopPrivateDomain() {
391    return publicSuffixIndex == 1;
392  }
393
394  /**
395   * Returns the portion of this domain name that is one level beneath the {@linkplain
396   * #isPublicSuffix() public suffix}. For example, for {@code x.adwords.google.co.uk} it returns
397   * {@code google.co.uk}, since {@code co.uk} is a public suffix. Similarly, for {@code
398   * myblog.blogspot.com} it returns the same domain, {@code myblog.blogspot.com}, since {@code
399   * blogspot.com} is a public suffix.
400   *
401   * <p>If {@link #isTopPrivateDomain()} is true, the current domain name instance is returned.
402   *
403   * <p>This method can be used to determine the probable highest level parent domain for which
404   * cookies may be set, though even that depends on individual browsers' implementations of cookie
405   * controls.
406   *
407   * @throws IllegalStateException if this domain does not end with a public suffix
408   * @since 6.0
409   */
410  public InternetDomainName topPrivateDomain() {
411    if (isTopPrivateDomain()) {
412      return this;
413    }
414    checkState(isUnderPublicSuffix(), "Not under a public suffix: %s", name);
415    return ancestor(publicSuffixIndex - 1);
416  }
417
418  /**
419   * Indicates whether this domain name represents a <i>registry suffix</i>, as defined by a subset
420   * of the Mozilla Foundation's <a href="http://publicsuffix.org/">Public Suffix List</a> (PSL). A
421   * registry suffix is one under which Internet users can directly register names via a domain name
422   * registrar, and have such registrations lawfully protected by internet-governing bodies such as
423   * ICANN. Examples of registry suffixes include {@code com}, {@code co.uk}, and {@code
424   * pvt.k12.wy.us}. Examples of domain names that are <i>not</i> registry suffixes include {@code
425   * google.com} and {@code foo.co.uk}.
426   *
427   * <p>Registry suffixes are a proper subset of {@linkplain #isPublicSuffix() public suffixes}. The
428   * list of public suffixes additionally contains privately owned domain names under which Internet
429   * users can register subdomains. An example of a public suffix that is not a registry suffix is
430   * {@code blogspot.com}. Note that it is true that all public suffixes <i>have</i> registry
431   * suffixes, since domain name registries collectively control all internet domain names.
432   *
433   * <p>For considerations on whether the public suffix or registry suffix designation is more
434   * suitable for your application, see <a
435   * href="https://github.com/google/guava/wiki/InternetDomainNameExplained">this article</a>.
436   *
437   * @return {@code true} if this domain name appears exactly on the public suffix list as part of
438   *     the registry suffix section (labelled "ICANN").
439   * @since 23.3
440   */
441  public boolean isRegistrySuffix() {
442    return registrySuffixIndex == 0;
443  }
444
445  /**
446   * Indicates whether this domain name ends in a {@linkplain #isRegistrySuffix() registry suffix},
447   * including if it is a registry suffix itself. For example, returns {@code true} for {@code
448   * www.google.com}, {@code foo.co.uk} and {@code com}, but not for {@code invalid} or {@code
449   * google.invalid}.
450   *
451   * <p>Note that this method is equivalent to {@link #hasPublicSuffix()} because all registry
452   * suffixes are public suffixes <i>and</i> all public suffixes have registry suffixes.
453   *
454   * @since 23.3
455   */
456  public boolean hasRegistrySuffix() {
457    return registrySuffixIndex != NO_SUFFIX_FOUND;
458  }
459
460  /**
461   * Returns the {@linkplain #isRegistrySuffix() registry suffix} portion of the domain name, or
462   * {@code null} if no registry suffix is present.
463   *
464   * @since 23.3
465   */
466  @CheckForNull
467  public InternetDomainName registrySuffix() {
468    return hasRegistrySuffix() ? ancestor(registrySuffixIndex) : null;
469  }
470
471  /**
472   * Indicates whether this domain name ends in a {@linkplain #isRegistrySuffix() registry suffix},
473   * while not being a registry suffix itself. For example, returns {@code true} for {@code
474   * www.google.com}, {@code foo.co.uk} and {@code blogspot.com}, but not for {@code com}, {@code
475   * co.uk}, or {@code google.invalid}.
476   *
477   * @since 23.3
478   */
479  public boolean isUnderRegistrySuffix() {
480    return registrySuffixIndex > 0;
481  }
482
483  /**
484   * Indicates whether this domain name is composed of exactly one subdomain component followed by a
485   * {@linkplain #isRegistrySuffix() registry suffix}. For example, returns {@code true} for {@code
486   * google.com}, {@code foo.co.uk}, and {@code blogspot.com}, but not for {@code www.google.com},
487   * {@code co.uk}, or {@code myblog.blogspot.com}.
488   *
489   * <p><b>Warning:</b> This method should not be used to determine the probable highest level
490   * parent domain for which cookies may be set. Use {@link #topPrivateDomain()} for that purpose.
491   *
492   * @since 23.3
493   */
494  public boolean isTopDomainUnderRegistrySuffix() {
495    return registrySuffixIndex == 1;
496  }
497
498  /**
499   * Returns the portion of this domain name that is one level beneath the {@linkplain
500   * #isRegistrySuffix() registry suffix}. For example, for {@code x.adwords.google.co.uk} it
501   * returns {@code google.co.uk}, since {@code co.uk} is a registry suffix. Similarly, for {@code
502   * myblog.blogspot.com} it returns {@code blogspot.com}, since {@code com} is a registry suffix.
503   *
504   * <p>If {@link #isTopDomainUnderRegistrySuffix()} is true, the current domain name instance is
505   * returned.
506   *
507   * <p><b>Warning:</b> This method should not be used to determine whether a domain is probably the
508   * highest level for which cookies may be set. Use {@link #isTopPrivateDomain()} for that purpose.
509   *
510   * @throws IllegalStateException if this domain does not end with a registry suffix
511   * @since 23.3
512   */
513  public InternetDomainName topDomainUnderRegistrySuffix() {
514    if (isTopDomainUnderRegistrySuffix()) {
515      return this;
516    }
517    checkState(isUnderRegistrySuffix(), "Not under a registry suffix: %s", name);
518    return ancestor(registrySuffixIndex - 1);
519  }
520
521  /** Indicates whether this domain is composed of two or more parts. */
522  public boolean hasParent() {
523    return parts.size() > 1;
524  }
525
526  /**
527   * Returns an {@code InternetDomainName} that is the immediate ancestor of this one; that is, the
528   * current domain with the leftmost part removed. For example, the parent of {@code
529   * www.google.com} is {@code google.com}.
530   *
531   * @throws IllegalStateException if the domain has no parent, as determined by {@link #hasParent}
532   */
533  public InternetDomainName parent() {
534    checkState(hasParent(), "Domain '%s' has no parent", name);
535    return ancestor(1);
536  }
537
538  /**
539   * Returns the ancestor of the current domain at the given number of levels "higher" (rightward)
540   * in the subdomain list. The number of levels must be non-negative, and less than {@code N-1},
541   * where {@code N} is the number of parts in the domain.
542   *
543   * <p>TODO: Reasonable candidate for addition to public API.
544   */
545  private InternetDomainName ancestor(int levels) {
546    return from(DOT_JOINER.join(parts.subList(levels, parts.size())));
547  }
548
549  /**
550   * Creates and returns a new {@code InternetDomainName} by prepending the argument and a dot to
551   * the current name. For example, {@code InternetDomainName.from("foo.com").child("www.bar")}
552   * returns a new {@code InternetDomainName} with the value {@code www.bar.foo.com}. Only lenient
553   * validation is performed, as described {@link #from(String) here}.
554   *
555   * @throws NullPointerException if leftParts is null
556   * @throws IllegalArgumentException if the resulting name is not valid
557   */
558  public InternetDomainName child(String leftParts) {
559    return from(checkNotNull(leftParts) + "." + name);
560  }
561
562  /**
563   * Indicates whether the argument is a syntactically valid domain name using lenient validation.
564   * Specifically, validation against <a href="http://www.ietf.org/rfc/rfc3490.txt">RFC 3490</a>
565   * ("Internationalizing Domain Names in Applications") is skipped.
566   *
567   * <p>The following two code snippets are equivalent:
568   *
569   * <pre>{@code
570   * domainName = InternetDomainName.isValid(name)
571   *     ? InternetDomainName.from(name)
572   *     : DEFAULT_DOMAIN;
573   * }</pre>
574   *
575   * <pre>{@code
576   * try {
577   *   domainName = InternetDomainName.from(name);
578   * } catch (IllegalArgumentException e) {
579   *   domainName = DEFAULT_DOMAIN;
580   * }
581   * }</pre>
582   *
583   * @since 8.0 (previously named {@code isValidLenient})
584   */
585  public static boolean isValid(String name) {
586    try {
587      InternetDomainName unused = from(name);
588      return true;
589    } catch (IllegalArgumentException e) {
590      return false;
591    }
592  }
593
594  /**
595   * Does the domain name match one of the "wildcard" patterns (e.g. {@code "*.ar"})? If a {@code
596   * desiredType} is specified, the wildcard pattern must also match that type.
597   */
598  private static boolean matchesWildcardSuffixType(
599      Optional<PublicSuffixType> desiredType, String domain) {
600    List<String> pieces = DOT_SPLITTER.limit(2).splitToList(domain);
601    return pieces.size() == 2
602        && matchesType(
603            desiredType, Optional.fromNullable(PublicSuffixPatterns.UNDER.get(pieces.get(1))));
604  }
605
606  /**
607   * If a {@code desiredType} is specified, returns true only if the {@code actualType} is
608   * identical. Otherwise, returns true as long as {@code actualType} is present.
609   */
610  private static boolean matchesType(
611      Optional<PublicSuffixType> desiredType, Optional<PublicSuffixType> actualType) {
612    return desiredType.isPresent() ? desiredType.equals(actualType) : actualType.isPresent();
613  }
614
615  /** Returns the domain name, normalized to all lower case. */
616  @Override
617  public String toString() {
618    return name;
619  }
620
621  /**
622   * Equality testing is based on the text supplied by the caller, after normalization as described
623   * in the class documentation. For example, a non-ASCII Unicode domain name and the Punycode
624   * version of the same domain name would not be considered equal.
625   */
626  @Override
627  public boolean equals(@CheckForNull Object object) {
628    if (object == this) {
629      return true;
630    }
631
632    if (object instanceof InternetDomainName) {
633      InternetDomainName that = (InternetDomainName) object;
634      return this.name.equals(that.name);
635    }
636
637    return false;
638  }
639
640  @Override
641  public int hashCode() {
642    return name.hashCode();
643  }
644}