Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.google.common.net
Class InternetDomainName

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

    @Beta
    @GwtCompatible(emulated=true)
    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. 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(Object)`.

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

Since:
  5.0
Author:
  Craig Berry

Method Summary
`InternetDomainName` | `child(String leftParts)` Creates and returns a new `InternetDomainName` by prepending the argument and a dot to the current name.
`boolean` | `equals(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.
`static InternetDomainName` | `fromLenient(String domain)` Deprecated. Use `from(String)`
`int` | `hashCode()`
`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` | `isPublicSuffix()` Indicates whether this domain name represents a public suffix, as defined by the Mozilla Foundation's Public Suffix List (PSL).
`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.
`static boolean` | `isValid(String name)` Indicates whether the argument is a syntactically valid domain name using lenient validation.
`static boolean` | `isValidLenient(String name)` Deprecated. Use `isValid(String)` instead
`String` | `name()` Returns the domain name, normalized to all lower case.
`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` | `topPrivateDomain()` Returns the portion of this domain name that is one level beneath the public suffix.
`String` | `toString()`

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

Method Detail

### fromLenient

    @Deprecated
    public static InternetDomainName fromLenient(String domain)

  Deprecated. Use `from(String)`

  A deprecated synonym for `from(String)`.

  Parameters:
    `domain` - A domain name (not IP address)
  Throws:
    `IllegalArgumentException` - if `name` is not syntactically valid according to `isValidLenient(java.lang.String)`
  Since:
    8.0 (previously named `from`)

### 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.

  Parameters:
    `domain` - A domain name (not IP address)
  Throws:
    `IllegalArgumentException` - if `name` is not syntactically valid according to `isValid(java.lang.String)`
  Since:
    10.0 (previously named `fromLenient`)

### name

    public String name()

  Returns the domain name, normalized to all lower case.

### 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`, `google.com` and `foo.co.uk`.

  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 `google` or `google.foo`. This is the recommended method for determining whether a domain is potentially an addressable host.

  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 `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

### 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` 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

### 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.

  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:
    `IllegalStateException` - if this domain does not end with a public suffix
  Since:
    6.0

### 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

### isValidLenient

    @Deprecated
    public static boolean isValidLenient(String name)

  Deprecated. Use `isValid(String)` instead

  A deprecated synonym for `isValid(String)`.

  Since:
    8.0 (previously named `isValid`)

### 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()

  Overrides:
    `toString` in class `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`

### hashCode

    public int hashCode()

  Overrides:
    `hashCode` in class `Object`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2010-2011. All Rights Reserved.