HostSpecifier
Date: 2016-05-24

com.google.common.net

## Class HostSpecifier

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

-     @Beta
      public final class HostSpecifier
      extends java.lang.Object

  A syntactically valid host specifier, suitable for use in a URI. This may be either a numeric IP address in IPv4 or IPv6 notation, or a domain name.

  Because this class is intended to represent host specifiers which can reasonably be used in a URI, the domain name case is further restricted to include only those domain names which end in a recognized public suffix; see `InternetDomainName.isPublicSuffix()` for details.

  Note that no network lookups are performed by any `HostSpecifier` methods. No attempt is made to verify that a provided specifier corresponds to a real or accessible host. Only syntactic and pattern-based checks are performed.

  If you know that a given string represents a numeric IP address, use `InetAddresses` to obtain and manipulate a `InetAddress` instance from it rather than using this class. Similarly, if you know that a given string represents a domain name, use `InternetDomainName` rather than this class.

  Since:
    5.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(java.lang.Object other)`
    `static HostSpecifier` | `from(java.lang.String specifier)` Attempts to return a `HostSpecifier` for the given string, throwing an exception if parsing fails.
    `static HostSpecifier` | `fromValid(java.lang.String specifier)` Returns a `HostSpecifier` built from the provided `specifier`, which is already known to be valid.
    `int` | `hashCode()`
    `static boolean` | `isValid(java.lang.String specifier)` Determines whether `specifier` represents a valid `HostSpecifier` as described in the documentation for `fromValid(String)`.
    `java.lang.String` | `toString()` Returns a string representation of the host specifier suitable for inclusion in a URI.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Method Detail

    - #### fromValid

          public static HostSpecifier fromValid(java.lang.String specifier)

      Returns a `HostSpecifier` built from the provided `specifier`, which is already known to be valid. If the `specifier` might be invalid, use `from(String)` instead.

      The specifier must be in one of these formats:

      - A domain name, like `google.com`
      - A IPv4 address string, like `127.0.0.1`
      - An IPv6 address string with or without brackets, like `[2001:db8::1]` or `2001:db8::1`
      Throws:
        `java.lang.IllegalArgumentException` - if the specifier is not valid.

    - #### from

          public static HostSpecifier from(java.lang.String specifier)
                                    throws java.text.ParseException

      Attempts to return a `HostSpecifier` for the given string, throwing an exception if parsing fails. Always use this method in preference to `fromValid(String)` for a specifier that is not already known to be valid.
      Throws:
        `java.text.ParseException` - if the specifier is not valid.

    - #### isValid

          public static boolean isValid(java.lang.String specifier)

      Determines whether `specifier` represents a valid `HostSpecifier` as described in the documentation for `fromValid(String)`.

    - #### equals

          public boolean equals(@Nullable
                       java.lang.Object other)

      Overrides:
        `equals` in class `java.lang.Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### toString

          public java.lang.String toString()

      Returns a string representation of the host specifier suitable for inclusion in a URI. If the host specifier is a domain name, the string will be normalized to all lower case. If the specifier was an IPv6 address without brackets, brackets are added so that the result will be usable in the host part of a URI.
      Overrides:
        `toString` in class `java.lang.Object`