# SNIHostName

public final class **SNIHostName** extends [SNIServerName](https://developers.google.com/j2objc/javadoc/jre/reference/javax/net/ssl/SNIServerName.html)  
Instances of this class represent a server name of type
`https://developers.google.com/j2objc/javadoc/jre/reference/javax/net/ssl/StandardConstants.html#SNI_HOST_NAME` in a Server Name
Indication (SNI) extension.


As described in section 3, "Server Name Indication", of
[TLS Extensions (RFC 6066)](http://www.ietf.org/rfc/rfc6066.txt),
"HostName" contains the fully qualified DNS hostname of the server, as
understood by the client. The encoded server name value of a hostname is
represented as a byte string using ASCII encoding without a trailing dot.
This allows the support of Internationalized Domain Names (IDN) through
the use of A-labels (the ASCII-Compatible Encoding (ACE) form of a valid
string of Internationalized Domain Names for Applications (IDNA)) defined
in [RFC 5890](http://www.ietf.org/rfc/rfc5890.txt).


Note that `SNIHostName` objects are immutable.

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/javax/net/ssl/SNIServerName.html`
- `https://developers.google.com/j2objc/javadoc/jre/reference/javax/net/ssl/StandardConstants.html#SNI_HOST_NAME`

### Public Constructor Summary

|---|---|
|   | [SNIHostName](https://developers.google.com/j2objc/javadoc/jre/reference/javax/net/ssl/SNIHostName.html#SNIHostName(java.lang.String))([String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) hostname) Creates an `SNIHostName` using the specified hostname. |
|   | [SNIHostName](https://developers.google.com/j2objc/javadoc/jre/reference/javax/net/ssl/SNIHostName.html#SNIHostName(byte[]))(byte\[\] encoded) Creates an `SNIHostName` using the specified encoded value. |

### Public Method Summary

|---|---|
| static [SNIMatcher](https://developers.google.com/j2objc/javadoc/jre/reference/javax/net/ssl/SNIMatcher.html) | [createSNIMatcher](https://developers.google.com/j2objc/javadoc/jre/reference/javax/net/ssl/SNIHostName.html#createSNIMatcher(java.lang.String))([String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) regex) Creates an `https://developers.google.com/j2objc/javadoc/jre/reference/javax/net/ssl/SNIMatcher.html` object for `SNIHostName`s. |
| boolean | [equals](https://developers.google.com/j2objc/javadoc/jre/reference/javax/net/ssl/SNIHostName.html#equals(java.lang.Object))([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) other) Compares this server name to the specified object. |
| [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) | [getAsciiName](https://developers.google.com/j2objc/javadoc/jre/reference/javax/net/ssl/SNIHostName.html#getAsciiName())() Returns the `https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/charset/StandardCharsets.html#US_ASCII`-compliant hostname of this `SNIHostName` object. |
| int | [hashCode](https://developers.google.com/j2objc/javadoc/jre/reference/javax/net/ssl/SNIHostName.html#hashCode())() Returns a hash code value for this `SNIHostName`. |
| [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) | [toString](https://developers.google.com/j2objc/javadoc/jre/reference/javax/net/ssl/SNIHostName.html#toString())() Returns a string representation of the object, including the DNS hostname in this `SNIHostName` object. |

### Inherited Method Summary

From class [javax.net.ssl.SNIServerName](https://developers.google.com/j2objc/javadoc/jre/reference/javax/net/ssl/SNIServerName.html)

|---|---|
| boolean | [equals](https://developers.google.com/j2objc/javadoc/jre/reference/javax/net/ssl/SNIServerName.html#equals(java.lang.Object))([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) other) Indicates whether some other object is "equal to" this server name. |
| final byte\[\] | [getEncoded](https://developers.google.com/j2objc/javadoc/jre/reference/javax/net/ssl/SNIServerName.html#getEncoded())() Returns a copy of the encoded server name value of this server name. |
| final int | [getType](https://developers.google.com/j2objc/javadoc/jre/reference/javax/net/ssl/SNIServerName.html#getType())() Returns the name type of this server name. |
| int | [hashCode](https://developers.google.com/j2objc/javadoc/jre/reference/javax/net/ssl/SNIServerName.html#hashCode())() Returns a hash code value for this server name. |
| [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) | [toString](https://developers.google.com/j2objc/javadoc/jre/reference/javax/net/ssl/SNIServerName.html#toString())() Returns a string representation of this server name, including the server name type and the encoded server name value in this `SNIServerName` object. |

From class [java.lang.Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html)

|---|---|
| [Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) | [clone](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#clone())() Creates and returns a copy of this `Object`. |
| boolean | [equals](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#equals(java.lang.Object))([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) obj) Compares this instance with the specified object and indicates if they are equal. |
| void | [finalize](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#finalize())() Invoked when the garbage collector has detected that this instance is no longer reachable. |
| final [Class](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Class.html)\<?\> | [getClass](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#getClass())() Returns the unique instance of `https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Class.html` that represents this object's class. |
| int | [hashCode](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#hashCode())() Returns an integer hash code for this object. |
| final void | [notify](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#notify())() Causes a thread which is waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up. |
| final void | [notifyAll](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#notifyAll())() Causes all threads which are waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up. |
| [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) | [toString](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#toString())() Returns a string containing a concise, human-readable description of this object. |
| final void | [wait](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#wait(long,%20int))(long timeout, int nanos) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires. |
| final void | [wait](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#wait(long))(long timeout) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires. |
| final void | [wait](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#wait())() Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object. |

## Public Constructors

#### public
**SNIHostName**
([String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) hostname)

Creates an `SNIHostName` using the specified hostname.


Note that per [RFC 6066](http://www.ietf.org/rfc/rfc6066.txt),
the encoded server name value of a hostname is
`https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/charset/StandardCharsets.html#US_ASCII`-compliant. In this method,
`hostname` can be a user-friendly Internationalized Domain Name
(IDN). `https://developers.google.com/j2objc/javadoc/jre/reference/java/net/IDN.html#toASCII(java.lang.String,%20int)` is used to enforce the
restrictions on ASCII characters in hostnames (see
[RFC 3490](http://www.ietf.org/rfc/rfc3490.txt),
[RFC 1122](http://www.ietf.org/rfc/rfc1122.txt),
[RFC 1123](http://www.ietf.org/rfc/rfc1123.txt)) and
translate the `hostname` into ASCII Compatible Encoding (ACE), as:

```
     IDN.toASCII(hostname, IDN.USE_STD3_ASCII_RULES);
 
```


The `hostname` argument is illegal if it:

- `hostname` is empty,
- `hostname` ends with a trailing dot,
- `hostname` is not a valid Internationalized Domain Name (IDN) compliant with the RFC 3490 specification.

<br />

##### Parameters

| hostname | the hostname of this server name |
|---|---|

##### Throws

| [NullPointerException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if `hostname` is `null` |
| [IllegalArgumentException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/IllegalArgumentException.html) | if `hostname` is illegal |
|---|---|

#### public
**SNIHostName**
(byte\[\] encoded)

Creates an `SNIHostName` using the specified encoded value.


This method is normally used to parse the encoded name value in a
requested SNI extension.


Per [RFC 6066](http://www.ietf.org/rfc/rfc6066.txt),
the encoded name value of a hostname is
`https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/charset/StandardCharsets.html#US_ASCII`-compliant. However, in the previous
version of the SNI extension (
[RFC 4366](http://www.ietf.org/rfc/rfc4366.txt)),
the encoded hostname is represented as a byte string using UTF-8
encoding. For the purpose of version tolerance, this method allows
that the charset of `encoded` argument can be
`https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/charset/StandardCharsets.html#UTF_8`, as well as
`https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/charset/StandardCharsets.html#US_ASCII`. `https://developers.google.com/j2objc/javadoc/jre/reference/java/net/IDN.html#toASCII(java.lang.String)` is used
to translate the `encoded` argument into ASCII Compatible
Encoding (ACE) hostname.


It is strongly recommended that this constructor is only used to parse
the encoded name value in a requested SNI extension. Otherwise, to
comply with [RFC 6066](http://www.ietf.org/rfc/rfc6066.txt),
please always use `https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/charset/StandardCharsets.html#US_ASCII`-compliant charset
and enforce the restrictions on ASCII characters in hostnames (see
[RFC 3490](http://www.ietf.org/rfc/rfc3490.txt),
[RFC 1122](http://www.ietf.org/rfc/rfc1122.txt),
[RFC 1123](http://www.ietf.org/rfc/rfc1123.txt))
for `encoded` argument, or use
`https://developers.google.com/j2objc/javadoc/jre/reference/javax/net/ssl/SNIHostName.html#SNIHostName(java.lang.String)` instead.


The `encoded` argument is illegal if it:

- `encoded` is empty,
- `encoded` ends with a trailing dot,
- `encoded` is not encoded in `https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/charset/StandardCharsets.html#US_ASCII` or `https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/charset/StandardCharsets.html#UTF_8`-compliant charset,
- `encoded` is not a valid Internationalized Domain Name (IDN) compliant with the RFC 3490 specification.


Note that the `encoded` byte array is cloned
to protect against subsequent modification.

##### Parameters

| encoded | the encoded hostname of this server name |
|---|---|

##### Throws

| [NullPointerException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if `encoded` is `null` |
| [IllegalArgumentException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/IllegalArgumentException.html) | if `encoded` is illegal |
|---|---|

## Public Methods

#### public static [SNIMatcher](https://developers.google.com/j2objc/javadoc/jre/reference/javax/net/ssl/SNIMatcher.html)
**createSNIMatcher**
([String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) regex)

Creates an `https://developers.google.com/j2objc/javadoc/jre/reference/javax/net/ssl/SNIMatcher.html` object for `SNIHostName`s.


This method can be used by a server to verify the acceptable
`SNIHostName`s. For example,

```
     SNIMatcher matcher =
         SNIHostName.createSNIMatcher("www\\.example\\.com");
 
```
will accept the hostname "www.example.com".

```
     SNIMatcher matcher =
         SNIHostName.createSNIMatcher("www\\.example\\.(com|org)");
 
```
will accept hostnames "www.example.com" and "www.example.org".

<br />

##### Parameters

| regex | the [regular expression pattern](https://developers.google.com/j2objc/javadoc/jre//java/util/regex/Pattern.html#sum) representing the hostname(s) to match |
|---|---|

##### Returns

- a `SNIMatcher` object for `SNIHostName`s

##### Throws

| [NullPointerException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if `regex` is `null` |
| [PatternSyntaxException](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/regex/PatternSyntaxException.html) | if the regular expression's syntax is invalid |
|---|---|

#### public boolean
**equals**
([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) other)

Compares this server name to the specified object.


Per [RFC 6066](http://www.ietf.org/rfc/rfc6066.txt), DNS
hostnames are case-insensitive. Two server hostnames are equal if,
and only if, they have the same name type, and the hostnames are
equal in a case-independent comparison.

##### Parameters

| other | the other server name object to compare with. |
|---|---|

##### Returns

- true if, and only if, the `other` is considered equal to this instance

#### public [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html)
**getAsciiName**
()

Returns the `https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/charset/StandardCharsets.html#US_ASCII`-compliant hostname of
this `SNIHostName` object.


Note that, per
[RFC 6066](http://www.ietf.org/rfc/rfc6066.txt), the
returned hostname may be an internationalized domain name that
contains A-labels. See
[RFC 5890](http://www.ietf.org/rfc/rfc5890.txt)
for more information about the detailed A-label specification.

##### Returns

- the `https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/charset/StandardCharsets.html#US_ASCII`-compliant hostname of this `SNIHostName` object

#### public int
**hashCode**
()

Returns a hash code value for this `SNIHostName`.


The hash code value is generated using the case-insensitive hostname
of this `SNIHostName`.

##### Returns

- a hash code value for this `SNIHostName`.

#### public [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html)
**toString**
()

Returns a string representation of the object, including the DNS
hostname in this `SNIHostName` object.


The exact details of the representation are unspecified and subject
to change, but the following may be regarded as typical:

```
     "type=host_name (0), value=<hostname>"
 
```
The "\<hostname\>" is an ASCII representation of the hostname, which may contains A-labels. For example, a returned value of an pseudo hostname may look like:

```
     "type=host_name (0), value=www.example.com"
 
```
or

```
     "type=host_name (0), value=xn--fsqu00a.xn--0zwm56d"
 
```


Please NOTE that the exact details of the representation are unspecified
and subject to change.

##### Returns

- a string representation of the object.