Class Inet


  • public final class Inet
    extends java.lang.Object
    Utilities relating to Internet protocol (a.k.a. "INET" or "IP") address manipulation.
    Author:
    David M. Lloyd
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.net.Inet4Address INET4_ANY
      The "any" address for IPv4.
      static java.net.Inet4Address INET4_BROADCAST
      The broadcast-all address for IPv4.
      static java.net.Inet4Address INET4_LOOPBACK
      The traditional loopback address for IPv4.
      static java.net.Inet6Address INET6_ANY
      The "any" address for IPv6.
      static java.net.Inet6Address INET6_LOOPBACK
      The loopback address for IPv6.
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static java.net.NetworkInterface findInterfaceWithScopeId​(java.lang.String scopeName)  
      static <T extends java.net.InetAddress>
      T
      getAddressByNameAndType​(java.lang.String hostName, java.lang.Class<T> addressType)
      Resolve the given host name, returning the first answer with the given address type.
      static <T extends java.net.InetAddress>
      T[]
      getAllAddressesByNameAndType​(java.lang.String hostName, java.lang.Class<T> addressType)
      Resolve the given host name, returning all answers with the given address type.
      static java.lang.String getHostNameIfResolved​(java.net.InetAddress inetAddress)
      Get the host name of the given address, if it is resolved.
      static java.lang.String getHostNameIfResolved​(java.net.InetSocketAddress socketAddress)
      Get the host name of the given address, if it is resolved.
      static java.net.Inet4Address getInet4Address​(int s1, int s2, int s3, int s4)
      Get an IPv4 address from four integer segments.
      static java.net.Inet6Address getInet6Address​(int s1, int s2, int s3, int s4, int s5, int s6, int s7, int s8)
      Get an IPv6 address from eight integer segments.
      static java.net.InetSocketAddress getResolved​(java.net.InetSocketAddress address)
      Get a copy of the given socket address, but with a resolved address component.
      static java.net.InetSocketAddress getResolved​(java.net.InetSocketAddress address, java.lang.Class<? extends java.net.InetAddress> addressType)
      Get a copy of the given socket address, but with a resolved address component of the given type.
      static java.net.InetSocketAddress getResolved​(java.net.URI uri, int defaultPort)
      Get the resolved socket address from the given URI.
      static java.net.InetSocketAddress getResolved​(java.net.URI uri, int defaultPort, java.lang.Class<? extends java.net.InetAddress> addressType)
      Get a resolved socket address from the given URI.
      static java.net.InetAddress getResolvedInetAddress​(java.net.URI uri)
      Get an Internet address for a URI destination, resolving the host name if necessary.
      static <T extends java.net.InetAddress>
      T
      getResolvedInetAddress​(java.net.URI uri, java.lang.Class<T> addressType)
      Get an Internet address for a URI destination, resolving the host name if necessary.
      static int getScopeId​(java.lang.String scopeName)
      Attempt to get the scope ID of the given string.
      static int getScopeId​(java.lang.String scopeName, java.net.InetAddress compareWith)
      Attempt to get the scope ID of the given string.
      static int getScopeId​(java.net.InetAddress address)
      Get the scope ID of the given address (if it is an IPv6 address).
      static int getScopeId​(java.net.NetworkInterface networkInterface)  
      static int getScopeId​(java.net.NetworkInterface networkInterface, java.net.InetAddress compareWith)  
      static java.net.URI getURIFromAddress​(java.lang.String scheme, java.net.InetSocketAddress socketAddress, int defaultPort)
      Extract a base URI from the given scheme and socket address.
      static boolean isInet4Address​(java.lang.String address)
      Checks whether given String is a valid IPv4 address.
      static boolean isInet6Address​(java.lang.String address)
      Checks whether given String is a valid IPv6 address.
      static CidrAddress parseCidrAddress​(java.lang.String address)
      Parse a CIDR address into a CidrAddress object.
      static java.net.Inet4Address parseInet4Address​(java.lang.String address)
      Parse an IPv4 address into an Inet4Address object.
      static java.net.Inet4Address parseInet4Address​(java.lang.String address, java.lang.String hostName)
      Parse an IPv4 address into an Inet4Address object.
      static java.net.Inet4Address parseInet4AddressOrFail​(java.lang.String address)
      Parse an IPv4 address into an Inet4Address object, throwing an exception on failure.
      static java.net.Inet4Address parseInet4AddressOrFail​(java.lang.String address, java.lang.String hostName)
      Parse an IPv4 address into an Inet4Address object.
      static byte[] parseInet4AddressToBytes​(java.lang.String address)
      Converts IPv4 address from textual representation to bytes.
      static java.net.Inet6Address parseInet6Address​(java.lang.String address)
      Parse an IPv6 address into an Inet6Address object.
      static java.net.Inet6Address parseInet6Address​(java.lang.String address, java.lang.String hostName)
      Parse an IPv6 address into an Inet6Address object.
      static java.net.Inet6Address parseInet6AddressOrFail​(java.lang.String address)
      Parse an IPv6 address into an Inet6Address object, throwing an exception on failure.
      static java.net.Inet6Address parseInet6AddressOrFail​(java.lang.String address, java.lang.String hostName)
      Parse an IPv6 address into an Inet6Address object.
      static byte[] parseInet6AddressToBytes​(java.lang.String address)
      Converts IPv6 address from textual representation to bytes.
      static java.net.InetAddress parseInetAddress​(java.lang.String address)
      Parse an IP address into an InetAddress object.
      static java.net.InetAddress parseInetAddress​(java.lang.String address, java.lang.String hostName)
      Parse an IP address into an InetAddress object.
      static java.net.InetAddress parseInetAddressOrFail​(java.lang.String address)
      Parse an IP address into an InetAddress object, throwing an exception on failure.
      static java.net.InetAddress parseInetAddressOrFail​(java.lang.String address, java.lang.String hostName)
      Parse an IP address into an InetAddress object.
      static byte[] parseInetAddressToBytes​(java.lang.String address)
      Converts an IP address from textual representation to bytes.
      static java.net.Inet6Address toInet6Address​(java.net.InetAddress inetAddress)
      Get the IPv6 equivalent of the given address.
      static java.lang.String toOptimalString​(byte[] addressBytes)
      Get the optimal string representation of the bytes of an IP address.
      static java.lang.String toOptimalString​(java.net.InetAddress inetAddress)
      Get the optimal string representation of an IP address.
      static java.lang.String toURLString​(byte[] addressBytes)
      Get a string representation of the given address bytes which is suitable for use as the host component of a URL.
      static java.lang.String toURLString​(java.net.InetAddress inetAddress, boolean useHostNameIfPresent)
      Get a string representation of the given address which is suitable for use as the host component of a URL.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • INET4_ANY

        public static final java.net.Inet4Address INET4_ANY
        The "any" address for IPv4.
      • INET4_LOOPBACK

        public static final java.net.Inet4Address INET4_LOOPBACK
        The traditional loopback address for IPv4.
      • INET4_BROADCAST

        public static final java.net.Inet4Address INET4_BROADCAST
        The broadcast-all address for IPv4.
      • INET6_ANY

        public static final java.net.Inet6Address INET6_ANY
        The "any" address for IPv6.
      • INET6_LOOPBACK

        public static final java.net.Inet6Address INET6_LOOPBACK
        The loopback address for IPv6.
    • Method Detail

      • toOptimalString

        public static java.lang.String toOptimalString​(java.net.InetAddress inetAddress)
        Get the optimal string representation of an IP address. For IPv6 addresses, this representation will be more compact that the default.
        Parameters:
        inetAddress - the address (must not be null)
        Returns:
        the string representation (not null)
      • toOptimalString

        public static java.lang.String toOptimalString​(byte[] addressBytes)
        Get the optimal string representation of the bytes of an IP address.
        Parameters:
        addressBytes - the address bytes (must not be null)
        Returns:
        the string representation (not null)
      • toURLString

        public static java.lang.String toURLString​(java.net.InetAddress inetAddress,
                                                   boolean useHostNameIfPresent)
        Get a string representation of the given address which is suitable for use as the host component of a URL.
        Parameters:
        inetAddress - the address (must not be null)
        useHostNameIfPresent - true to preserve the host name string in the address, false to always give an IP address string
        Returns:
        the string representation (not null)
      • toURLString

        public static java.lang.String toURLString​(byte[] addressBytes)
        Get a string representation of the given address bytes which is suitable for use as the host component of a URL.
        Parameters:
        addressBytes - the address bytes (must not be null)
        Returns:
        the string representation (not null)
      • toInet6Address

        public static java.net.Inet6Address toInet6Address​(java.net.InetAddress inetAddress)
        Get the IPv6 equivalent of the given address. If the address is IPv4 then it is returned as a compatibility address.
        Parameters:
        inetAddress - the address to convert (must not be null)
        Returns:
        the converted address (not null)
      • getHostNameIfResolved

        public static java.lang.String getHostNameIfResolved​(java.net.InetAddress inetAddress)
        Get the host name of the given address, if it is resolved. Otherwise, return null.
        Parameters:
        inetAddress - the address to check (must not be null)
        Returns:
        the host name, or null if the address has no host name and is unresolved
      • getHostNameIfResolved

        public static java.lang.String getHostNameIfResolved​(java.net.InetSocketAddress socketAddress)
        Get the host name of the given address, if it is resolved. Otherwise, return null.
        Parameters:
        socketAddress - the socket address to check (must not be null)
        Returns:
        the host name, or null if the address has no host name and is unresolved
      • getResolved

        public static java.net.InetSocketAddress getResolved​(java.net.URI uri,
                                                             int defaultPort,
                                                             java.lang.Class<? extends java.net.InetAddress> addressType)
                                                      throws java.net.UnknownHostException
        Get a resolved socket address from the given URI.
        Parameters:
        uri - the URI (must not be null)
        defaultPort - the default port to use if none is given (must be in the range 1 ≤ n ≤ 65535
        addressType - the class of the InetAddress to search for (must not be null)
        Returns:
        the socket address, or null if the URI does not have a host component
        Throws:
        java.net.UnknownHostException - if address resolution failed
      • getResolved

        public static java.net.InetSocketAddress getResolved​(java.net.URI uri,
                                                             int defaultPort)
                                                      throws java.net.UnknownHostException
        Get the resolved socket address from the given URI.
        Parameters:
        uri - the URI (must not be null)
        defaultPort - the default port to use if none is given (must be in the range 1 ≤ n ≤ 65535
        Returns:
        the socket address, or null if the URI does not have a host component
        Throws:
        java.net.UnknownHostException - if address resolution failed
      • getResolvedInetAddress

        public static <T extends java.net.InetAddress> T getResolvedInetAddress​(java.net.URI uri,
                                                                                java.lang.Class<T> addressType)
                                                                         throws java.net.UnknownHostException
        Get an Internet address for a URI destination, resolving the host name if necessary.
        Type Parameters:
        T - the type of the InetAddress to search for
        Parameters:
        uri - the destination URI
        Returns:
        the address, or null if no authority is present in the URI
        Throws:
        java.net.UnknownHostException - if the URI host was existent but could not be resolved to a valid address
      • getResolvedInetAddress

        public static java.net.InetAddress getResolvedInetAddress​(java.net.URI uri)
                                                           throws java.net.UnknownHostException
        Get an Internet address for a URI destination, resolving the host name if necessary.
        Parameters:
        uri - the destination URI
        Returns:
        the address, or null if no authority is present in the URI
        Throws:
        java.net.UnknownHostException - if the URI host was existent but could not be resolved to a valid address
      • getResolved

        public static java.net.InetSocketAddress getResolved​(java.net.InetSocketAddress address)
                                                      throws java.net.UnknownHostException
        Get a copy of the given socket address, but with a resolved address component.
        Parameters:
        address - the (possibly unresolved) address (must not be null)
        Returns:
        the resolved address (not null)
        Throws:
        java.net.UnknownHostException - if address resolution failed
      • getResolved

        public static java.net.InetSocketAddress getResolved​(java.net.InetSocketAddress address,
                                                             java.lang.Class<? extends java.net.InetAddress> addressType)
                                                      throws java.net.UnknownHostException
        Get a copy of the given socket address, but with a resolved address component of the given type.
        Parameters:
        address - the (possibly unresolved) address (must not be null)
        addressType - the class of the InetAddress to search for (must not be null)
        Returns:
        the resolved address (not null)
        Throws:
        java.net.UnknownHostException - if address resolution failed, or if no addresses of the given type were found, or if the given address was already resolved but is not of the given address type
      • getAddressByNameAndType

        public static <T extends java.net.InetAddress> T getAddressByNameAndType​(java.lang.String hostName,
                                                                                 java.lang.Class<T> addressType)
                                                                          throws java.net.UnknownHostException
        Resolve the given host name, returning the first answer with the given address type.
        Type Parameters:
        T - the type of the InetAddress to search for
        Parameters:
        hostName - the host name to resolve (must not be null)
        addressType - the class of the InetAddress to search for (must not be null)
        Returns:
        the resolved address (not null)
        Throws:
        java.net.UnknownHostException - if address resolution failed or if no addresses of the given type were found
      • getAllAddressesByNameAndType

        public static <T extends java.net.InetAddress> T[] getAllAddressesByNameAndType​(java.lang.String hostName,
                                                                                        java.lang.Class<T> addressType)
                                                                                 throws java.net.UnknownHostException
        Resolve the given host name, returning all answers with the given address type.
        Type Parameters:
        T - the type of the InetAddress to search for
        Parameters:
        hostName - the host name to resolve (must not be null)
        addressType - the class of the InetAddress to search for (must not be null)
        Returns:
        the resolved addresses (not null)
        Throws:
        java.net.UnknownHostException - if address resolution failed or if no addresses of the given type were found
      • getInet4Address

        public static java.net.Inet4Address getInet4Address​(int s1,
                                                            int s2,
                                                            int s3,
                                                            int s4)
        Get an IPv4 address from four integer segments. Each segment must be between 0 and 255.
        Parameters:
        s1 - the first segment
        s2 - the second segment
        s3 - the third segment
        s4 - the fourth segment
        Returns:
        the address (not null)
      • getInet6Address

        public static java.net.Inet6Address getInet6Address​(int s1,
                                                            int s2,
                                                            int s3,
                                                            int s4,
                                                            int s5,
                                                            int s6,
                                                            int s7,
                                                            int s8)
        Get an IPv6 address from eight integer segments. Each segment must be between 0 and 65535 (0xffff).
        Parameters:
        s1 - the first segment
        s2 - the second segment
        s3 - the third segment
        s4 - the fourth segment
        s5 - the fifth segment
        s6 - the sixth segment
        s7 - the seventh segment
        s8 - the eighth segment
        Returns:
        the address (not null)
      • isInet6Address

        public static boolean isInet6Address​(java.lang.String address)
        Checks whether given String is a valid IPv6 address.
        Parameters:
        address - address textual representation
        Returns:
        true if address is a valid IPv6 address, false otherwise
      • parseInet6Address

        public static java.net.Inet6Address parseInet6Address​(java.lang.String address)
        Parse an IPv6 address into an Inet6Address object.
        Parameters:
        address - the address to parse
        Returns:
        the parsed address, or null if the address is not valid
      • parseInet6Address

        public static java.net.Inet6Address parseInet6Address​(java.lang.String address,
                                                              java.lang.String hostName)
        Parse an IPv6 address into an Inet6Address object.
        Parameters:
        address - the address to parse (must not be null)
        hostName - the host name to use in the resultant object, or null to use the string representation of the address
        Returns:
        the parsed address, or null if the address is not valid
      • parseInet6AddressOrFail

        public static java.net.Inet6Address parseInet6AddressOrFail​(java.lang.String address)
        Parse an IPv6 address into an Inet6Address object, throwing an exception on failure.
        Parameters:
        address - the address to parse
        Returns:
        the parsed address (not null)
        Throws:
        java.lang.IllegalArgumentException - if the address is not valid
      • parseInet6AddressOrFail

        public static java.net.Inet6Address parseInet6AddressOrFail​(java.lang.String address,
                                                                    java.lang.String hostName)
        Parse an IPv6 address into an Inet6Address object.
        Parameters:
        address - the address to parse (must not be null)
        hostName - the host name to use in the resultant object, or null to use the string representation of the address
        Returns:
        the parsed address (not null)
        Throws:
        java.lang.IllegalArgumentException - if the address is not valid
      • isInet4Address

        public static boolean isInet4Address​(java.lang.String address)
        Checks whether given String is a valid IPv4 address.
        Parameters:
        address - address textual representation
        Returns:
        true if address is a valid IPv4 address, false otherwise
      • parseInet4Address

        public static java.net.Inet4Address parseInet4Address​(java.lang.String address)
        Parse an IPv4 address into an Inet4Address object.
        Parameters:
        address - the address to parse
        Returns:
        the parsed address, or null if the address is not valid
      • parseInet4Address

        public static java.net.Inet4Address parseInet4Address​(java.lang.String address,
                                                              java.lang.String hostName)
        Parse an IPv4 address into an Inet4Address object.
        Parameters:
        address - the address to parse
        hostName - the host name to use in the resultant object, or null to use the string representation of the address
        Returns:
        the parsed address, or null if the address is not valid
      • parseInet4AddressOrFail

        public static java.net.Inet4Address parseInet4AddressOrFail​(java.lang.String address)
        Parse an IPv4 address into an Inet4Address object, throwing an exception on failure.
        Parameters:
        address - the address to parse
        Returns:
        the parsed address (not null)
        Throws:
        java.lang.IllegalArgumentException - if the address is not valid
      • parseInet4AddressOrFail

        public static java.net.Inet4Address parseInet4AddressOrFail​(java.lang.String address,
                                                                    java.lang.String hostName)
        Parse an IPv4 address into an Inet4Address object.
        Parameters:
        address - the address to parse (must not be null)
        hostName - the host name to use in the resultant object, or null to use the string representation of the address
        Returns:
        the parsed address (not null)
        Throws:
        java.lang.IllegalArgumentException - if the address is not valid
      • parseInetAddress

        public static java.net.InetAddress parseInetAddress​(java.lang.String address)
        Parse an IP address into an InetAddress object.
        Parameters:
        address - the address to parse
        Returns:
        the parsed address, or null if the address is not valid
      • parseInetAddress

        public static java.net.InetAddress parseInetAddress​(java.lang.String address,
                                                            java.lang.String hostName)
        Parse an IP address into an InetAddress object.
        Parameters:
        address - the address to parse
        hostName - the host name to use in the resultant object, or null to use the string representation of the address
        Returns:
        the parsed address, or null if the address is not valid
      • parseInetAddressOrFail

        public static java.net.InetAddress parseInetAddressOrFail​(java.lang.String address)
        Parse an IP address into an InetAddress object, throwing an exception on failure.
        Parameters:
        address - the address to parse
        Returns:
        the parsed address (not null)
        Throws:
        java.lang.IllegalArgumentException - if the address is not valid
      • parseInetAddressOrFail

        public static java.net.InetAddress parseInetAddressOrFail​(java.lang.String address,
                                                                  java.lang.String hostName)
        Parse an IP address into an InetAddress object.
        Parameters:
        address - the address to parse (must not be null)
        hostName - the host name to use in the resultant object, or null to use the string representation of the address
        Returns:
        the parsed address (not null)
        Throws:
        java.lang.IllegalArgumentException - if the address is not valid
      • parseCidrAddress

        public static CidrAddress parseCidrAddress​(java.lang.String address)
        Parse a CIDR address into a CidrAddress object.
        Parameters:
        address - the address to parse
        Returns:
        the parsed address, or null if the address is not valid
      • parseInet6AddressToBytes

        public static byte[] parseInet6AddressToBytes​(java.lang.String address)
        Converts IPv6 address from textual representation to bytes.

        If given string doesn't represent valid IPv6 address, the method returns null.

        Parameters:
        address - address textual representation
        Returns:
        byte array representing the address, or null if the address is not valid
      • parseInet4AddressToBytes

        public static byte[] parseInet4AddressToBytes​(java.lang.String address)
        Converts IPv4 address from textual representation to bytes.

        If given string doesn't represent valid IPv4 address, the method returns null.

        This only supports decimal notation.

        Parameters:
        address - address textual representation
        Returns:
        byte array representing the address, or null if the address is not valid
      • parseInetAddressToBytes

        public static byte[] parseInetAddressToBytes​(java.lang.String address)
        Converts an IP address from textual representation to bytes.

        If given string doesn't represent valid IP address, the method returns null.

        Parameters:
        address - address textual representation
        Returns:
        byte array representing the address, or null if the address is not valid
      • getScopeId

        public static int getScopeId​(java.net.InetAddress address)
        Get the scope ID of the given address (if it is an IPv6 address).
        Returns:
        the scope ID, or 0 if there is none or the address is an IPv4 address
      • getScopeId

        public static int getScopeId​(java.lang.String scopeName)
        Attempt to get the scope ID of the given string. If the string is numeric then the number is parsed and returned as-is. If the scope is a string, then a search for the matching network interface will occur.
        Parameters:
        scopeName - the scope number or name as a string (must not be null)
        Returns:
        the scope ID, or 0 if no matching scope could be found
      • getScopeId

        public static int getScopeId​(java.lang.String scopeName,
                                     java.net.InetAddress compareWith)
        Attempt to get the scope ID of the given string. If the string is numeric then the number is parsed and returned as-is. If the scope is a string, then a search for the matching network interface will occur.
        Parameters:
        scopeName - the scope number or name as a string (must not be null)
        compareWith - the address to compare with, to ensure that the wrong local scope is not selected (may be null)
        Returns:
        the scope ID, or 0 if no matching scope could be found
      • findInterfaceWithScopeId

        public static java.net.NetworkInterface findInterfaceWithScopeId​(java.lang.String scopeName)
      • getScopeId

        public static int getScopeId​(java.net.NetworkInterface networkInterface)
      • getScopeId

        public static int getScopeId​(java.net.NetworkInterface networkInterface,
                                     java.net.InetAddress compareWith)
      • getURIFromAddress

        public static java.net.URI getURIFromAddress​(java.lang.String scheme,
                                                     java.net.InetSocketAddress socketAddress,
                                                     int defaultPort)
                                              throws java.net.URISyntaxException
        Extract a base URI from the given scheme and socket address. The address is not resolved.
        Parameters:
        scheme - the URI scheme
        socketAddress - the host socket address
        defaultPort - the protocol default port, or -1 if there is none
        Returns:
        the URI instance
        Throws:
        java.net.URISyntaxException - if the URI failed to be constructed for some reason