public class

InetAddress

extends Object
implements Serializable
java.lang.Object
   ↳ java.net.InetAddress
Known Direct Subclasses

Class Overview

An Internet Protocol (IP) address. This can be either an IPv4 address or an IPv6 address, and in practice you'll have an instance of either Inet4Address or Inet6Address (this class cannot be instantiated directly). Most code does not need to distinguish between the two families, and should use InetAddress.

An InetAddress may have a hostname (accessible via getHostName), but may not, depending on how the InetAddress was created.

IPv4 numeric address formats

The getAllByName method accepts IPv4 addresses in the following forms:

  • "1.2.3.4" - 1.2.3.4
  • "1.2.3" - 1.2.0.3
  • "1.2" - 1.0.0.2
  • "16909060" - 1.2.3.4

In the first three cases, each number is treated as an 8-bit value between 0 and 255. In the fourth case, the single number is treated as a 32-bit value representing the entire address.

Note that each numeric part can be expressed in decimal (as above) or hex. For example, "0x01020304" is equivalent to 1.2.3.4 and "0xa.0xb.0xc.0xd" is equivalent to 10.11.12.13.

Typically, only the four-dot decimal form ("1.2.3.4") is ever used. Any method that returns a textual numeric address will use four-dot decimal form.

IPv6 numeric address formats

The getAllByName method accepts IPv6 addresses in the following forms (this text comes from RFC 2373, which you should consult for full details of IPv6 addressing):

  • The preferred form is x:x:x:x:x:x:x:x, where the 'x's are the hexadecimal values of the eight 16-bit pieces of the address. Note that it is not necessary to write the leading zeros in an individual field, but there must be at least one numeral in every field (except for the case described in the next bullet). Examples: 

         FEDC:BA98:7654:3210:FEDC:BA98:7654:3210
     1080:0:0:0:8:800:200C:417A
  • Due to some methods of allocating certain styles of IPv6 addresses, it will be common for addresses to contain long strings of zero bits. In order to make writing addresses containing zero bits easier a special syntax is available to compress the zeros. The use of "::" indicates multiple groups of 16-bits of zeros. The "::" can only appear once in an address. The "::" can also be used to compress the leading and/or trailing zeros in an address. For example the following addresses: 
         1080:0:0:0:8:800:200C:417A  a unicast address
     FF01:0:0:0:0:0:0:101        a multicast address
     0:0:0:0:0:0:0:1             the loopback address
     0:0:0:0:0:0:0:0             the unspecified addresses
    may be represented as: 
         1080::8:800:200C:417A       a unicast address
     FF01::101                   a multicast address
     ::1                         the loopback address
     ::                          the unspecified addresses

  • An alternative form that is sometimes more convenient when dealing with a mixed environment of IPv4 and IPv6 nodes is x:x:x:x:x:x:d.d.d.d, where the 'x's are the hexadecimal values of the six high-order 16-bit pieces of the address, and the 'd's are the decimal values of the four low-order 8-bit pieces of the address (standard IPv4 representation). Examples: 

         0:0:0:0:0:0:13.1.68.3
     0:0:0:0:0:FFFF:129.144.52.38
    or in compressed form: 
         ::13.1.68.3
     ::FFFF:129.144.52.38

Scopes are given using a trailing % followed by the scope id, as in 1080::8:800:200C:417A%2 or 1080::8:800:200C:417A%en0. See RFC 4007 for more on IPv6's scoped address architecture.

Additionally, for backwards compatibility, IPv6 addresses may be surrounded by square brackets.

DNS caching

On Android, addresses are cached for 600 seconds (10 minutes) by default. Failed lookups are cached for 10 seconds. The underlying C library or OS may cache for longer, but you can control the Java-level caching with the usual "networkaddress.cache.ttl" and "networkaddress.cache.negative.ttl" system properties. These are parsed as integer numbers of seconds, where the special value 0 means "don't cache" and -1 means "cache forever".

Note also that on Android – unlike the RI – the cache is not unbounded. The current implementation caches around 512 entries, removed on a least-recently-used basis. (Obviously, you should not rely on these details.)

See Also

Summary

Public Methods
boolean equals(Object obj)
Compares this InetAddress instance against the specified address in obj.
byte[] getAddress()
Returns the IP address represented by this InetAddress instance as a byte array.
static InetAddress[] getAllByName(String host)
Gets all IP addresses associated with the given host identified by name or literal IP address.
static InetAddress getByAddress(byte[] ipAddress)
Returns the InetAddress corresponding to the array of bytes.
static InetAddress getByAddress(String hostName, byte[] ipAddress)
Returns the InetAddress corresponding to the array of bytes, and the given hostname.
static InetAddress getByName(String host)
Returns the address of a host according to the given host string name host.
String getCanonicalHostName()
Gets the fully qualified domain name for the host associated with this IP address.
String getHostAddress()
Gets the textual representation of this IP address.
String getHostName()
Gets the host name of this IP address.
static InetAddress getLocalHost()
Returns an InetAddress for the local host if possible, or the loopback address otherwise.
int hashCode()
Gets the hashcode of the represented IP address.
boolean isAnyLocalAddress()
Returns whether this is a wildcard address or not.
boolean isLinkLocalAddress()
Returns whether this address is a link-local address or not.
boolean isLoopbackAddress()
Returns whether this address is a loopback address or not.
boolean isMCGlobal()
Returns whether this address is a global multicast address or not.
boolean isMCLinkLocal()
Returns whether this address is a link-local multicast address or not.
boolean isMCNodeLocal()
Returns whether this address is a node-local multicast address or not.
boolean isMCOrgLocal()
Returns whether this address is a organization-local multicast address or not.
boolean isMCSiteLocal()
Returns whether this address is a site-local multicast address or not.
boolean isMulticastAddress()
boolean isReachable(int timeout)
Tries to reach this InetAddress.
boolean isReachable(NetworkInterface networkInterface, int ttl, int timeout)
Tries to reach this InetAddress.
boolean isSiteLocalAddress()
Returns whether this address is a site-local address or not.
String toString()
Returns a string containing a concise, human-readable description of this IP address.
[Expand]
Inherited Methods
From class java.lang.Object

Public Methods

public boolean equals (Object obj)

Since: API Level 1

Compares this InetAddress instance against the specified address in obj. Two addresses are equal if their address byte arrays have the same length and if the bytes in the arrays are equal.

Parameters
obj the object to be tested for equality.
Returns
  • true if both objects are equal, false otherwise.

public byte[] getAddress ()

Since: API Level 1

Returns the IP address represented by this InetAddress instance as a byte array. The elements are in network order (the highest order address byte is in the zeroth element).

Returns
  • the address in form of a byte array.

public static InetAddress[] getAllByName (String host)

Since: API Level 1

Gets all IP addresses associated with the given host identified by name or literal IP address. The IP address is resolved by the configured name service. If the host name is empty or null an UnknownHostException is thrown. If the host name is a literal IP address string an array with the corresponding single InetAddress is returned.

Parameters
host the hostname or literal IP string to be resolved.
Returns
  • the array of addresses associated with the specified host.
Throws
UnknownHostException if the address lookup fails.

public static InetAddress getByAddress (byte[] ipAddress)

Since: API Level 1

Returns the InetAddress corresponding to the array of bytes. In the case of an IPv4 address there must be exactly 4 bytes and for IPv6 exactly 16 bytes. If not, an UnknownHostException is thrown.

The IP address is not validated by a name service.

The high order byte is ipAddress[0].

Parameters
ipAddress is either a 4 (IPv4) or 16 (IPv6) byte long array.
Returns
  • an InetAddress instance representing the given IP address ipAddress.
Throws
UnknownHostException if the given byte array has no valid length.

public static InetAddress getByAddress (String hostName, byte[] ipAddress)

Since: API Level 1

Returns the InetAddress corresponding to the array of bytes, and the given hostname. In the case of an IPv4 address there must be exactly 4 bytes and for IPv6 exactly 16 bytes. If not, an UnknownHostException will be thrown.

The host name and IP address are not validated.

The hostname either be a machine alias or a valid IPv6 or IPv4 address format.

The high order byte is ipAddress[0].

Parameters
hostName the string representation of hostname or IP address.
ipAddress either a 4 (IPv4) or 16 (IPv6) byte long array.
Returns
  • an InetAddress instance representing the given IP address and hostname.
Throws
UnknownHostException if the given byte array has no valid length.

public static InetAddress getByName (String host)

Since: API Level 1

Returns the address of a host according to the given host string name host. The host string may be either a machine name or a dotted string IP address. If the latter, the hostName field is determined upon demand. host can be null which means that an address of the loopback interface is returned.

Parameters
host the hostName to be resolved to an address or null.
Returns
  • the InetAddress instance representing the host.
Throws
UnknownHostException if the address lookup fails.

public String getCanonicalHostName ()

Since: API Level 1

Gets the fully qualified domain name for the host associated with this IP address. If a security manager is set, it is checked if the method caller is allowed to get the hostname. Otherwise, the textual representation in a dotted-quad-notation is returned.

Returns
  • the fully qualified domain name of this IP address.

public String getHostAddress ()

Since: API Level 1

Gets the textual representation of this IP address.

Returns
  • the textual representation of host's IP address.

public String getHostName ()

Since: API Level 1

Gets the host name of this IP address. If the IP address could not be resolved, the textual representation in a dotted-quad-notation is returned.

Returns
  • the corresponding string name of this IP address.

public static InetAddress getLocalHost ()

Since: API Level 1

Returns an InetAddress for the local host if possible, or the loopback address otherwise. This method works by getting the hostname, performing a DNS lookup, and then taking the first returned address. For devices with multiple network interfaces and/or multiple addresses per interface, this does not necessarily return the InetAddress you want.

Multiple interface/address configurations were relatively rare when this API was designed, but multiple interfaces are the default for modern mobile devices (with separate wifi and radio interfaces), and the need to support both IPv4 and IPv6 has made multiple addresses commonplace. New code should thus avoid this method except where it's basically being used to get a loopback address or equivalent.

There are two main ways to get a more specific answer:

  • If you have a connected socket, you should probably use getLocalAddress() instead: that will give you the address that's actually in use for that connection. (It's not possible to ask the question "what local address would a connection to a given remote address use?"; you have to actually make the connection and see.)
  • For other use cases, see NetworkInterface, which lets you enumerate all available network interfaces and their addresses.

Note that if the host doesn't have a hostname set – as Android devices typically don't – this method will effectively return the loopback address, albeit by getting the name localhost and then doing a lookup to translate that to 127.0.0.1.

Returns
  • an InetAddress representing the local host, or the loopback address.
Throws
UnknownHostException if the address lookup fails.

public int hashCode ()

Since: API Level 1

Gets the hashcode of the represented IP address.

Returns
  • the appropriate hashcode value.

public boolean isAnyLocalAddress ()

Since: API Level 1

Returns whether this is a wildcard address or not. This implementation returns always false.

Returns
  • true if this instance represents a wildcard address, false otherwise.

public boolean isLinkLocalAddress ()

Since: API Level 1

Returns whether this address is a link-local address or not. This implementation returns always false.

Valid IPv6 link-local addresses are FE80::0 through to FEBF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF.

There are no valid IPv4 link-local addresses.

Returns
  • true if this instance represents a link-local address, false otherwise.

public boolean isLoopbackAddress ()

Since: API Level 1

Returns whether this address is a loopback address or not. This implementation returns always false. Valid IPv4 loopback addresses are 127.d.d.d The only valid IPv6 loopback address is ::1.

Returns
  • true if this instance represents a loopback address, false otherwise.

public boolean isMCGlobal ()

Since: API Level 1

Returns whether this address is a global multicast address or not. This implementation returns always false.

Valid IPv6 link-global multicast addresses are FFxE:/112 where x is a set of flags, and the additional 112 bits make up the global multicast address space.

Valid IPv4 global multicast addresses are between: 224.0.1.0 to 238.255.255.255.

Returns
  • true if this instance represents a global multicast address, false otherwise.

public boolean isMCLinkLocal ()

Since: API Level 1

Returns whether this address is a link-local multicast address or not. This implementation returns always false.

Valid IPv6 link-local multicast addresses are FFx2:/112 where x is a set of flags, and the additional 112 bits make up the link-local multicast address space.

Valid IPv4 link-local addresses are between: 224.0.0.0 to 224.0.0.255

Returns
  • true if this instance represents a link-local multicast address, false otherwise.

public boolean isMCNodeLocal ()

Since: API Level 1

Returns whether this address is a node-local multicast address or not. This implementation returns always false.

Valid IPv6 node-local multicast addresses are FFx1:/112 where x is a set of flags, and the additional 112 bits make up the node-local multicast address space.

There are no valid IPv4 node-local multicast addresses.

Returns
  • true if this instance represents a node-local multicast address, false otherwise.

public boolean isMCOrgLocal ()

Since: API Level 1

Returns whether this address is a organization-local multicast address or not. This implementation returns always false.

Valid IPv6 organization-local multicast addresses are FFx8:/112 where x is a set of flags, and the additional 112 bits make up the organization-local multicast address space.

Valid IPv4 organization-local addresses are between: 239.192.0.0 to 239.251.255.255

Returns
  • true if this instance represents a organization-local multicast address, false otherwise.

public boolean isMCSiteLocal ()

Since: API Level 1

Returns whether this address is a site-local multicast address or not. This implementation returns always false.

Valid IPv6 site-local multicast addresses are FFx5:/112 where x is a set of flags, and the additional 112 bits make up the site-local multicast address space.

Valid IPv4 site-local addresses are between: 239.252.0.0 to 239.255.255.255

Returns
  • true if this instance represents a site-local multicast address, false otherwise.

public boolean isMulticastAddress ()

Since: API Level 1

public boolean isReachable (int timeout)

Since: API Level 1

Tries to reach this InetAddress. This method first tries to use ICMP (ICMP ECHO REQUEST). When first step fails, a TCP connection on port 7 (Echo) of the remote host is established.

Parameters
timeout timeout in milliseconds before the test fails if no connection could be established.
Returns
  • true if this address is reachable, false otherwise.
Throws
IOException if an error occurs during an I/O operation.
IllegalArgumentException if timeout is less than zero.

public boolean isReachable (NetworkInterface networkInterface, int ttl, int timeout)

Since: API Level 1

Tries to reach this InetAddress. This method first tries to use ICMP (ICMP ECHO REQUEST). When first step fails, a TCP connection on port 7 (Echo) of the remote host is established.

Parameters
networkInterface the network interface on which to connection should be established.
ttl the maximum count of hops (time-to-live).
timeout timeout in milliseconds before the test fails if no connection could be established.
Returns
  • true if this address is reachable, false otherwise.
Throws
IOException if an error occurs during an I/O operation.
IllegalArgumentException if ttl or timeout is less than zero.

public boolean isSiteLocalAddress ()

Since: API Level 1

Returns whether this address is a site-local address or not. This implementation returns always false.

Valid IPv6 site-local addresses are FEC0::0 through to FEFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF.

There are no valid IPv4 site-local addresses.

Returns
  • true if this instance represents a site-local address, false otherwise.

public String toString ()

Since: API Level 1

Returns a string containing a concise, human-readable description of this IP address.

Returns
  • the description, as host/address.