APIdia Launch Partner
Top Description Fields Constructors Methods
java.net

public final Class Inet4Address

extends InetAddress
Class Inheritance
Imports
sun.net.util.IPAddressUtil, java.io.ObjectStreamException, java.util.Objects
This class represents an Internet Protocol version 4 (IPv4) address. Defined by RFC 790: Assigned Numbers, RFC 1918: Address Allocation for Private Internets, and RFC 2365: Administratively Scoped IP Multicast

Textual representation of IPv4 addresses

Textual representation of IPv4 address used as input to methods takes one of the following forms:

When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an IPv4 address.

When a three part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right most two bytes of the network address. This makes the three part address format convenient for specifying Class B network addresses as 128.net.host.

When a two part address is supplied, the last part is interpreted as a 24-bit quantity and placed in the right most three bytes of the network address. This makes the two part address format convenient for specifying Class A network addresses as net.host.

When only one part is given, the value is stored directly in the network address without any byte rearrangement.

For example, the following (decimal) forms are supported by the methods Inet4Address#ofLiteral(String) and InetAddress#getByName(String) which are capable of parsing textual representations of IPv4 addresses:

// Dotted-decimal 'd.d.d.d' form with four part address literal InetAddress.getByName("007.008.009.010"); // ==> /7.8.9.10 InetAddress.getByName("127.0.1.1"); // ==> /127.0.1.1 // Dotted-decimal 'd.d.d' form with three part address literal, // the last part is placed in the right most two bytes // of the constructed address InetAddress.getByName("127.0.257"); // ==> /127.0.1.1 // Dotted-decimal 'd.d' form with two part address literal, // the last part is placed in the right most three bytes // of the constructed address Inet4Address.ofLiteral("127.257"); // ==> /127.0.1.1 // 'd' form with one decimal value that is stored directly in // the constructed address bytes without any rearrangement Inet4Address.ofLiteral("02130706689"); // ==> /127.0.1.1 
// Dotted-decimal 'd.d.d.d' form with four part address literal
InetAddress.getByName("007.008.009.010"); // ==> /7.8.9.10
InetAddress.getByName("127.0.1.1");       // ==> /127.0.1.1

// Dotted-decimal 'd.d.d' form with three part address literal,
// the last part is placed in the right most two bytes
// of the constructed address
InetAddress.getByName("127.0.257"); // ==> /127.0.1.1

// Dotted-decimal 'd.d' form with two part address literal,
// the last part is placed in the right most three bytes
// of the constructed address
Inet4Address.ofLiteral("127.257"); // ==> /127.0.1.1

// 'd' form with one decimal value that is stored directly in
// the constructed address bytes without any rearrangement
Inet4Address.ofLiteral("02130706689"); // ==> /127.0.1.1

The above forms adhere to "strict" decimal-only syntax. Additionally, the Inet4Address#ofPosixLiteral(String) method implements a POSIX inet_addr compatible "loose" parsing algorithm, allowing octal and hexadecimal address segments. Please refer to RFC 6943: Issues in Identifier Comparison for Security Purposes. Aside from Inet4Address.ofPosixLiteral(String), all methods only support strict decimal parsing.

For methods that return a textual representation as output value, the first form, i.e. a dotted-quad string in strict decimal notation, is used.

The Scope of a Multicast Address

Historically the IPv4 TTL field in the IP header has doubled as a multicast scope field: a TTL of 0 means node-local, 1 means link-local, up through 32 means site-local, up through 64 means region-local, up through 128 means continent-local, and up through 255 are global. However, the administrative scoping is preferred. Please refer to RFC 2365: Administratively Scoped IP Multicast
Since
1.4
External Specification
https://www.rfc-editor.org/info/rfc1918, https://www.rfc-editor.org/info/rfc2365, https://www.rfc-editor.org/info/rfc790, https://www.rfc-editor.org/rfc/rfc6943.html#section-3.1.1

Field Summary

Modifier and TypeField and Description
pack-priv static final int
INADDRSZ

private static final long
serialVersionUID

Hides java.net.InetAddress.serialVersionUID.

use serialVersionUID from InetAddress, but Inet4Address instance is always replaced by an InetAddress instance before being serialized
Inherited from java.net.InetAddress:
holderimplIPv4IPv6PLATFORM_LOOKUP_POLICY

Constructor Summary

AccessConstructor and Description
pack-priv
Inet4Address()

pack-priv
Inet4Address(String hostName, byte[] addr)

pack-priv
Inet4Address(String hostName, int address)

Method Summary

Modifier and TypeMethod and Description
pack-priv int
addressValue()

Returns the 32-bit IPv4 address.

public boolean

Returns:

true if the objects are the same; false otherwise.
equals(Object
the object to compare against.
obj)

Overrides java.net.InetAddress.equals.

Compares this object against the specified object.

public byte[]

Returns:

the raw IP address of this object.
getAddress()

Overrides java.net.InetAddress.getAddress.

Returns the raw IP address of this InetAddress object.

public String

Returns:

the raw IP address in a string format.
getHostAddress()

Overrides java.net.InetAddress.getHostAddress.

Returns the IP address string in textual presentation form.

public int

Returns:

a hash code value for this IP address.
hashCode()

Overrides java.net.InetAddress.hashCode.

Returns a hashcode for this IP address.

private static native void
init()

Hides java.net.InetAddress.init.

Perform class load-time initializations.

public boolean

Returns:

a boolean indicating if the InetAddress is a wildcard address.
isAnyLocalAddress()

Overrides java.net.InetAddress.isAnyLocalAddress.

Utility routine to check if the InetAddress is a wildcard address.

public boolean

Returns:

a boolean indicating if the InetAddress is a link local address; or false if address is not a link local unicast address.
isLinkLocalAddress()

Overrides java.net.InetAddress.isLinkLocalAddress.

Utility routine to check if the InetAddress is a link local address.

public boolean

Returns:

a boolean indicating if the InetAddress is a loopback address; or false otherwise.
isLoopbackAddress()

Overrides java.net.InetAddress.isLoopbackAddress.

Utility routine to check if the InetAddress is a loopback address.

public boolean

Returns:

a boolean indicating if the address has is a multicast address of global scope, false if it is not of global scope or it is not a multicast address
isMCGlobal()

Overrides java.net.InetAddress.isMCGlobal.

Utility routine to check if the multicast address has global scope.

public boolean

Returns:

a boolean indicating if the address has is a multicast address of link-local scope, false if it is not of link-local scope or it is not a multicast address
isMCLinkLocal()

Overrides java.net.InetAddress.isMCLinkLocal.

Utility routine to check if the multicast address has link scope.

public boolean

Returns:

a boolean indicating if the address has is a multicast address of node-local scope, false if it is not of node-local scope or it is not a multicast address
isMCNodeLocal()

Overrides java.net.InetAddress.isMCNodeLocal.

Utility routine to check if the multicast address has node scope.

public boolean

Returns:

a boolean indicating if the address has is a multicast address of organization-local scope, false if it is not of organization-local scope or it is not a multicast address
isMCOrgLocal()

Overrides java.net.InetAddress.isMCOrgLocal.

Utility routine to check if the multicast address has organization scope.

public boolean

Returns:

a boolean indicating if the address has is a multicast address of site-local scope, false if it is not of site-local scope or it is not a multicast address
isMCSiteLocal()

Overrides java.net.InetAddress.isMCSiteLocal.

Utility routine to check if the multicast address has site scope.

public boolean

Returns:

a boolean indicating if the InetAddress is an IP multicast address
isMulticastAddress()

Overrides java.net.InetAddress.isMulticastAddress.

Utility routine to check if the InetAddress is an IP multicast address.

public boolean

Returns:

a boolean indicating if the InetAddress is a site local address; or false if address is not a site local unicast address.
isSiteLocalAddress()

Overrides java.net.InetAddress.isSiteLocalAddress.

Utility routine to check if the InetAddress is a site local address.

pack-priv static String

Returns:

a String representing the IPv4 address in textual representation format
numericToTextFormat(byte[]
a byte array representing an IPv4 numeric address
src)

Converts IPv4 binary address into a string suitable for presentation.

public static Inet4Address

Returns:

an Inet4Address object with no hostname set, and constructed from the provided IPv4 address literal.
ofLiteral(String
the textual representation of an IPv4 address.
ipv4AddressLiteral)

Hides java.net.InetAddress.ofLiteral.

Creates an Inet4Address based on the provided textual representation of an IPv4 address.

public static Inet4Address

Returns:

an Inet4Address object with no hostname set, and constructed from the provided IPv4 address literal.
ofPosixLiteral(String
a textual representation of an IPv4 address.
posixIPAddressLiteral)

Creates an Inet4Address based on the provided textual representation of an IPv4 address in POSIX inet_addr compatible form.

pack-priv static Inet4Address

Returns:

Inet4Address object constructed from the address literal; or null if the literal cannot be parsed as an IPv4 address
parseAddressString(String
IPv4 address literal to parse
addressLiteral, boolean
whether to throw IllegalArgumentException if the given addressLiteral string cannot be parsed as an IPv4 address literal.
throwIAE)

Parses the given string as an IPv4 address literal.

private static Inet4Address

Returns:

Inet4Address object constructed from the address literal; or null if the literal cannot be parsed as an IPv4 address
parseAddressStringPosix(String
IPv4 address literal to parse
addressLiteral)

Parses the given string as an IPv4 address literal in POSIX form.

If the given addressLiteral string cannot be parsed as an IPv4 address literal in POSIX form and throwIAE is false, null is returned.

private Object

Returns:

the alternate object to be serialized.
writeReplace()

Replaces the object to be serialized with an InetAddress object.

Inherited from java.net.InetAddress:
anyLocalAddressgetAddressesFromNameServicegetAllByNamegetAllByName0getByAddressgetByAddressgetByNamegetCanonicalHostNamegetHostNamegetLocalHostgetLoopbackAddressholderipv4AddressesFirstipv6AddressesFirstisReachableisReachablesystemAddressesOrdertoString

Field Detail

INADDRSZback to summary
pack-priv static final int INADDRSZ
serialVersionUIDback to summary
private static final long serialVersionUID

Hides java.net.InetAddress.serialVersionUID.

use serialVersionUID from InetAddress, but Inet4Address instance is always replaced by an InetAddress instance before being serialized

Annotations
@Serial

Constructor Detail

Inet4Addressback to summary
pack-priv Inet4Address()
Inet4Addressback to summary
pack-priv Inet4Address(String hostName, byte[] addr)
Inet4Addressback to summary
pack-priv Inet4Address(String hostName, int address)

Method Detail

addressValueback to summary
pack-priv int addressValue()

Returns the 32-bit IPv4 address.

equalsback to summary
public boolean equals(Object obj)

Overrides java.net.InetAddress.equals.

Compares this object against the specified object. The result is true if and only if the argument is not null and it represents the same IP address as this object.

Two instances of InetAddress represent the same IP address if the length of the byte arrays returned by getAddress is the same for both, and each of the array components is the same for the byte arrays.

Parameters
obj:Object

the object to compare against.

Returns:boolean

true if the objects are the same; false otherwise.

See Also
java.net.InetAddress#getAddress()
getAddressback to summary
public byte[] getAddress()

Overrides java.net.InetAddress.getAddress.

Returns the raw IP address of this InetAddress object. The result is in network byte order: the highest order byte of the address is in getAddress()[0].

Returns:byte[]

the raw IP address of this object.

getHostAddressback to summary
public String getHostAddress()

Overrides java.net.InetAddress.getHostAddress.

Returns the IP address string in textual presentation form.

Returns:String

the raw IP address in a string format.

hashCodeback to summary
public int hashCode()

Overrides java.net.InetAddress.hashCode.

Returns a hashcode for this IP address.

Returns:int

a hash code value for this IP address.

initback to summary
private static native void init()

Hides java.net.InetAddress.init.

Perform class load-time initializations.

isAnyLocalAddressback to summary
public boolean isAnyLocalAddress()

Overrides java.net.InetAddress.isAnyLocalAddress.

Utility routine to check if the InetAddress is a wildcard address.

Returns:boolean

a boolean indicating if the InetAddress is a wildcard address.

isLinkLocalAddressback to summary
public boolean isLinkLocalAddress()

Overrides java.net.InetAddress.isLinkLocalAddress.

Utility routine to check if the InetAddress is a link local address.

Returns:boolean

a boolean indicating if the InetAddress is a link local address; or false if address is not a link local unicast address.

isLoopbackAddressback to summary
public boolean isLoopbackAddress()

Overrides java.net.InetAddress.isLoopbackAddress.

Utility routine to check if the InetAddress is a loopback address.

Returns:boolean

a boolean indicating if the InetAddress is a loopback address; or false otherwise.

isMCGlobalback to summary
public boolean isMCGlobal()

Overrides java.net.InetAddress.isMCGlobal.

Utility routine to check if the multicast address has global scope.

Returns:boolean

a boolean indicating if the address has is a multicast address of global scope, false if it is not of global scope or it is not a multicast address

isMCLinkLocalback to summary
public boolean isMCLinkLocal()

Overrides java.net.InetAddress.isMCLinkLocal.

Utility routine to check if the multicast address has link scope.

Returns:boolean

a boolean indicating if the address has is a multicast address of link-local scope, false if it is not of link-local scope or it is not a multicast address

isMCNodeLocalback to summary
public boolean isMCNodeLocal()

Overrides java.net.InetAddress.isMCNodeLocal.

Utility routine to check if the multicast address has node scope.

Returns:boolean

a boolean indicating if the address has is a multicast address of node-local scope, false if it is not of node-local scope or it is not a multicast address

isMCOrgLocalback to summary
public boolean isMCOrgLocal()

Overrides java.net.InetAddress.isMCOrgLocal.

Utility routine to check if the multicast address has organization scope.

Returns:boolean

a boolean indicating if the address has is a multicast address of organization-local scope, false if it is not of organization-local scope or it is not a multicast address

isMCSiteLocalback to summary
public boolean isMCSiteLocal()

Overrides java.net.InetAddress.isMCSiteLocal.

Utility routine to check if the multicast address has site scope.

Returns:boolean

a boolean indicating if the address has is a multicast address of site-local scope, false if it is not of site-local scope or it is not a multicast address

isMulticastAddressback to summary
public boolean isMulticastAddress()

Overrides java.net.InetAddress.isMulticastAddress.

Utility routine to check if the InetAddress is an IP multicast address. IP multicast address is a Class D address i.e first four bits of the address are 1110.

Returns:boolean

a boolean indicating if the InetAddress is an IP multicast address

isSiteLocalAddressback to summary
public boolean isSiteLocalAddress()

Overrides java.net.InetAddress.isSiteLocalAddress.

Utility routine to check if the InetAddress is a site local address.

Returns:boolean

a boolean indicating if the InetAddress is a site local address; or false if address is not a site local unicast address.

numericToTextFormatback to summary
pack-priv static String numericToTextFormat(byte[] src)

Converts IPv4 binary address into a string suitable for presentation.

Parameters
src:byte[]

a byte array representing an IPv4 numeric address

Returns:String

a String representing the IPv4 address in textual representation format

ofLiteralback to summary
public static Inet4Address ofLiteral(String ipv4AddressLiteral)

Hides java.net.InetAddress.ofLiteral.

Creates an Inet4Address based on the provided textual representation of an IPv4 address.

If the provided IPv4 address literal cannot represent a valid IPv4 address an IllegalArgumentException is thrown.

This method doesn't block, i.e. no reverse lookup is performed.

Parameters
ipv4AddressLiteral:String

the textual representation of an IPv4 address.

Returns:Inet4Address

an Inet4Address object with no hostname set, and constructed from the provided IPv4 address literal.

Exceptions
IllegalArgumentException:
if the ipv4AddressLiteral cannot be parsed as an IPv4 address literal.
NullPointerException:
if the ipv4AddressLiteral is null.
Since
22
ofPosixLiteralback to summary
public static Inet4Address ofPosixLiteral(String posixIPAddressLiteral)

Creates an Inet4Address based on the provided textual representation of an IPv4 address in POSIX inet_addr compatible form.

The method ofPosixLiteral implements POSIX inet_addr compatible parsing algorithm, allowing octal and hexadecimal address segments. "0" is the prefix for octal numbers, "0x" and "0X" are the prefixes for hexadecimal numbers. Non-zero address segments that start from non-zero digits are parsed as decimal numbers. The following (non-decimal) forms are supported by this method:

// Dotted-quad 'x.x.x.x' form with four part address literal Inet4Address.ofPosixLiteral("0177.0.0.1"); // ==> /127.0.0.1 Inet4Address.ofPosixLiteral("0x7F.0.0.1"); // ==> /127.0.0.1 // Dotted-triple 'x.x.x' form with three part address literal, // the last part is placed in the rightmost two bytes // of the constructed address Inet4Address.ofPosixLiteral("0177.0.0402"); // ==> /127.0.1.2 Inet4Address.ofPosixLiteral("0x7F.0.0x102"); // ==> /127.0.1.2 // Dotted-double 'x.x' form with two part address literal, // the last part is placed in the rightmost three bytes // of the constructed address Inet4Address.ofPosixLiteral("0177.0201003"); // ==> /127.1.2.3 Inet4Address.ofPosixLiteral("0x7F.0x10203"); // ==> /127.1.2.3 Inet4Address.ofPosixLiteral("127.66051"); // ==> /127.1.2.3 // Dotless 'x' form with one value that is stored directly in // the constructed address bytes without any rearrangement Inet4Address.ofPosixLiteral("0100401404"); // ==> /1.2.3.4 Inet4Address.ofPosixLiteral("0x1020304"); // ==> /1.2.3.4 Inet4Address.ofPosixLiteral("16909060"); // ==> /1.2.3.4 
// Dotted-quad 'x.x.x.x' form with four part address literal
Inet4Address.ofPosixLiteral("0177.0.0.1"); // ==> /127.0.0.1
Inet4Address.ofPosixLiteral("0x7F.0.0.1"); // ==> /127.0.0.1

// Dotted-triple 'x.x.x' form with three part address literal,
// the last part is placed in the rightmost two bytes
// of the constructed address
Inet4Address.ofPosixLiteral("0177.0.0402"); // ==> /127.0.1.2
Inet4Address.ofPosixLiteral("0x7F.0.0x102"); // ==> /127.0.1.2

// Dotted-double 'x.x' form with two part address literal,
// the last part is placed in the rightmost three bytes
// of the constructed address
Inet4Address.ofPosixLiteral("0177.0201003"); // ==> /127.1.2.3
Inet4Address.ofPosixLiteral("0x7F.0x10203"); // ==> /127.1.2.3
Inet4Address.ofPosixLiteral("127.66051"); // ==> /127.1.2.3

// Dotless 'x' form with one value that is stored directly in
// the constructed address bytes without any rearrangement
Inet4Address.ofPosixLiteral("0100401404"); // ==> /1.2.3.4
Inet4Address.ofPosixLiteral("0x1020304"); // ==> /1.2.3.4
Inet4Address.ofPosixLiteral("16909060"); // ==> /1.2.3.4

If the provided IPv4 address literal cannot represent a valid IPv4 address in POSIX form an IllegalArgumentException is thrown.

This method doesn't block, i.e. no hostname lookup is performed.

API Note

This method produces different results compared to Inet4Address#ofLiteral when posixIPAddressLiteral parameter contains address segments with leading zeroes. An address segment with a leading zero is always parsed as an octal number by this method, therefore 0255 (octal) will be parsed as 173 (decimal). On the other hand, Inet4Address.ofLiteral ignores leading zeros, parses all numbers as decimal and produces 255. Where this method would parse 0256.0256.0256.0256 (octal) and produce 174.174.174.174 (decimal) in four dotted quad notation, Inet4Address.ofLiteral will throw IllegalArgumentException.

Parameters
posixIPAddressLiteral:String

a textual representation of an IPv4 address.

Returns:Inet4Address

an Inet4Address object with no hostname set, and constructed from the provided IPv4 address literal.

Exceptions
IllegalArgumentException:
if the posixIPAddressLiteral cannot be parsed as an IPv4 address literal.
NullPointerException:
if the posixIPAddressLiteral is null.
Since
23
parseAddressStringback to summary
pack-priv static Inet4Address parseAddressString(String addressLiteral, boolean throwIAE)

Parses the given string as an IPv4 address literal. If the given addressLiteral string cannot be parsed as an IPv4 address literal and throwIAE is false, null is returned. If the given addressLiteral string cannot be parsed as an IPv4 address literal and throwIAE is true, an IllegalArgumentException is thrown. Otherwise, if it can be considered as an ambiguous literal - IllegalArgumentException is thrown irrelevant to throwIAE value.

API Note

The given addressLiteral string is considered ambiguous if it cannot be parsed as a valid IPv4 address literal using decimal notation, but could be interpreted as an IPv4 address in some other representation (octal, hexadecimal, or mixed).

Parameters
addressLiteral:String

IPv4 address literal to parse

throwIAE:boolean

whether to throw IllegalArgumentException if the given addressLiteral string cannot be parsed as an IPv4 address literal.

Returns:Inet4Address

Inet4Address object constructed from the address literal; or null if the literal cannot be parsed as an IPv4 address

Exceptions
IllegalArgumentException:
if the given addressLiteral string cannot be parsed as an IPv4 address literal and throwIAE is true, or if it is considered ambiguous, regardless of the value of throwIAE.
parseAddressStringPosixback to summary
private static Inet4Address parseAddressStringPosix(String addressLiteral)

Parses the given string as an IPv4 address literal in POSIX form.

If the given addressLiteral string cannot be parsed as an IPv4 address literal in POSIX form and throwIAE is false, null is returned. If the given addressLiteral string cannot be parsed as an IPv4 address literal and throwIAE is true, an IllegalArgumentException is thrown.

API Note

This method produces different results compared to Inet4Address#parseAddressString when addressLiteral parameter contains address segments with leading zeroes. An address segment with a leading zero is always parsed as an octal number by this method, therefore 0255 (octal) will be parsed as 173 (decimal). On the other hand, Inet4Address#parseAddressString ignores leading zeros, parses all numbers as decimal and produces 255. Where this method would parse 0256.0256.0256.0256 (octal) and produce 174.174.174.174 (decimal) in four dotted quad notation, Inet4Address#parseAddressString will either throw IllegalArgumentException or return null, depending on the value of throwIAE.

Parameters
addressLiteral:String

IPv4 address literal to parse

Returns:Inet4Address

Inet4Address object constructed from the address literal; or null if the literal cannot be parsed as an IPv4 address

Exceptions
IllegalArgumentException:
if the given addressLiteral string cannot be parsed as an IPv4 address literal and throwIAE is true.
writeReplaceback to summary
private Object writeReplace() throws ObjectStreamException

Replaces the object to be serialized with an InetAddress object.

Returns:Object

the alternate object to be serialized.

Annotations
@Serial
Exceptions
ObjectStreamException:
if a new object replacing this object could not be created