InetAddress.getByName/getAllByName should clarify empty String behavior

Summary

Add a minor clarification to the specification of InetAddress::getByName and InetAddress::getAllByName, to specify existing behaviour when passed a String argument that is empty.

Problem

The longstanding behaviour of InetAddress::getByName and InetAddress::getAllByName is to return an InetAddress representing an address of the loopback interface, if passed a String argument that is either null or empty. The empty String case is not currently specified.

Additionally, it has been noticed that getByName does not specify how security manager checks are performed. This should be clarified too.

Solution

Specify existing behavior when passed an empty String. An empty String is identified as a String that has a length equal to zero, to be consistent with existing wording that describes security checks.

Document existing security manager checks performed by getByName ( which is similar to that of the wording in getAllByName ).

Specification

 /**
  * Determines the IP address of a host, given the host's name.
  *
  * <p> The host name can either be a machine name, such as
  * "{@code java.sun.com}", or a textual representation of its
  * IP address. If a literal IP address is supplied, only the
  * validity of the address format is checked.
  *
  * <p> For {@code host} specified in literal IPv6 address,
  * either the form defined in RFC 2732 or the literal IPv6 address
  * format defined in RFC 2373 is accepted. IPv6 scoped addresses are also
  * supported. See <a href="Inet6Address.html#scoped">here</a> for a description of IPv6
  * scoped addresses.
  *
- * <p> If the host is {@code null} then an {@code InetAddress}
- * representing an address of the loopback interface is returned.
+ * <p> If the host is {@code null} or {@code host.length()} is equal
+ * to zero, then an {@code InetAddress} representing an address of the
+ * loopback interface is returned.
  * See <a href="http://www.ietf.org/rfc/rfc3330.txt">RFC&nbsp;3330</a>
  * section&nbsp;2 and <a href="http://www.ietf.org/rfc/rfc2373.txt">RFC&nbsp;2373</a>
  * section&nbsp;2.5.3. </p>
+ *
+ * <p> If there is a security manager, and {@code host} is not {@code null}
+ * or {@code host.length() } is not equal to zero, the security manager's
+ * {@code checkConnect} method is called with the hostname and {@code -1}
+ * as its arguments to determine if the operation is allowed.
  *
  * @param      host   the specified host, or {@code null}.
  * @return     an IP address for the given host name.
  * @exception  UnknownHostException  if no IP address for the
  *               {@code host} could be found, or if a scope_id was specified
  *               for a global IPv6 address.
  * @exception  SecurityException if a security manager exists
  *             and its checkConnect method doesn't allow the operation
  */
 public static InetAddress getByName(String host)
     throws UnknownHostException { ... }

 /**
  * Given the name of a host, returns an array of its IP addresses,
  * based on the configured name service on the system.
  *
  * <p> The host name can either be a machine name, such as
  * "{@code java.sun.com}", or a textual representation of its IP
  * address. If a literal IP address is supplied, only the
  * validity of the address format is checked.
  *
  * <p> For {@code host} specified in <i>literal IPv6 address</i>,
  * either the form defined in RFC 2732 or the literal IPv6 address
  * format defined in RFC 2373 is accepted. A literal IPv6 address may
  * also be qualified by appending a scoped zone identifier or scope_id.
  * The syntax and usage of scope_ids is described
  * <a href="Inet6Address.html#scoped">here</a>.
- * <p> If the host is {@code null} then an {@code InetAddress}
- * representing an address of the loopback interface is returned.
+ * <p> If the host is {@code null} or {@code host.length()} is equal
+ * to zero, then an {@code InetAddress} representing an address of the
+ * loopback interface is returned.
  * See <a href="http://www.ietf.org/rfc/rfc3330.txt">RFC&nbsp;3330</a>
  * section&nbsp;2 and <a href="http://www.ietf.org/rfc/rfc2373.txt">RFC&nbsp;2373</a>
  * section&nbsp;2.5.3. </p>
  *
- * <p> If there is a security manager and {@code host} is not
- * null and {@code host.length() } is not equal to zero, the
- * security manager's
- * {@code checkConnect} method is called
- * with the hostname and {@code -1}
- * as its arguments to see if the operation is allowed.
+ * <p> If there is a security manager, and {@code host} is not {@code null}
+ * or {@code host.length() } is not equal to zero, the security manager's
+ * {@code checkConnect} method is called with the hostname and {@code -1}
+ * as its arguments to determine if the operation is allowed.
  *
  * @param      host   the name of the host, or {@code null}.
  * @return     an array of all the IP addresses for a given host name.
  *
  * @exception  UnknownHostException  if no IP address for the
  *               {@code host} could be found, or if a scope_id was specified
  *               for a global IPv6 address.
  * @exception  SecurityException  if a security manager exists and its
  *               {@code checkConnect} method doesn't allow the operation.
  *
  * @see SecurityManager#checkConnect
  */
 public static InetAddress[] getAllByName(String host)
     throws UnknownHostException { ... }