net.i2p.util

## Class Addresses

- java.lang.Object
- - net.i2p.util.Addresses

-     public abstract class Addresses
      extends Object

  Methods to get the local addresses, and other IP utilities.

  Performance Warning: Many methods in this class are very slow on Windows (approximately 200ms + 50ms per interface). Consider caching results when possible.

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `clearCaches()` Clears all internal caches.
    `static SortedSet<String>` | `getAddresses()` Gets all non-IPv6 addresses excluding local, broadcast, and multicast addresses.
    `static SortedSet<String>` | `getAddresses(boolean includeLocal, boolean includeIPv6)` Warning: When includeLocal is false, all returned addresses should be routable, but they are not necessarily appropriate for external use.
    `static SortedSet<String>` | `getAddresses(boolean includeSiteLocal, boolean includeLoopbackAndWildcard, boolean includeIPv6)` Warning: When includeSiteLocal and includeLoopbackAndWildcard are false, all returned addresses should be routable, but they are not necessarily appropriate for external use.
    `static SortedSet<String>` | `getAddresses(boolean includeSiteLocal, boolean includeLoopbackAndWildcard, boolean includeIPv6, boolean includeIPv6Temporary)` Warning: When includeSiteLocal and includeLoopbackAndWildcard are false, all returned addresses should be routable, but they are not necessarily appropriate for external use.
    `static SortedSet<String>` | `getAllAddresses()` Gets all addresses excluding only link-local and multicast addresses.
    `static String` | `getAnyAddress()` Gets the first non-local IPv4 address found.
    `static Set<AddressType>` | `getConnectedAddressTypes()` Efficiently get all connected address types in one pass.
    `static byte[]` | `getIP(String host)` Caching version of InetAddress.getByName(host).getAddress(), which is slow.
    `static byte[]` | `getIP(String host, boolean preferIPv6)` For literal IP addresses, same as getIP(String).
    `static byte[]` | `getIPOnly(String host)` Caching version of InetAddress.getByName(host).getAddress(), which is slow.
    `static List<byte[]>` | `getIPs(String host)` For literal IP addresses, same as getIP(String).
    `static int` | `getPort(String port)` Convenience method to convert and validate a port String without throwing an exception.
    `static byte[]` | `getYggdrasilAddress()` Caller should cache results for better performance.
    `static boolean` | `isConnected()` Do we have any non-loop, non-wildcard IPv4 address at all? Use getConnectedAddressTypes() to get all types at once for better performance.
    `static boolean` | `isConnected(AddressType type)` Do we have any address of this type? Use getConnectedAddressTypes() to get all types at once for better performance.
    `static boolean` | `isConnectedIPv6()` Do we have any non-loop, non-wildcard IPv6 address at all? Use getConnectedAddressTypes() to get all types at once for better performance.
    `static boolean` | `isDeprecated(Inet6Address addr)` Determines if an IPv6 address is deprecated.
    `static boolean` | `isDynamic(Inet6Address addr)` Determines if an IPv6 address is dynamic.
    `static boolean` | `isIPAddress(String host)` Checks if the host is a valid IP address (IPv4 or IPv6).
    `static boolean` | `isIPv4Address(String host)` Checks if the host is a valid IPv4 address.
    `static boolean` | `isIPv6Address(String host)` Checks if the host is a valid IPv6 address.
    `static boolean` | `isTemporary(Inet6Address addr)` Determines if an IPv6 address is temporary.
    `static void` | `main(String[] args)` Print out the local addresses
    `static String` | `toCanonicalString(byte[] addr)` Same as toString() but returns IPv6 in compressed form per RFC 5952.
    `static String` | `toCanonicalString(byte[] addr, int port)` Same as toString() but returns IPv6 in compressed form per RFC 5952.
    `static String` | `toCanonicalString(String host)` Converts IPv6 to compressed form per RFC 5952.
    `static String` | `toString(byte[] addr)` Convenience method to convert an IP address to a String without throwing an exception.
    `static String` | `toString(byte[] addr, int port)` Convenience method to convert an IP address and port to a String without throwing an exception.
    `static String` | `useIPv6TempAddresses()` Checks if temporary IPv6 addresses are enabled system-wide.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### clearCaches

          public static void clearCaches()

      Clears all internal caches.

    - #### getAddresses

          public static SortedSet<String> getAddresses()

      Gets all non-IPv6 addresses excluding local, broadcast, and multicast addresses.
      Returns:
        a sorted set of all addresses, excluding IPv6, local, broadcast, multicast, etc.

    - #### getAddresses

          public static SortedSet<String> getAddresses(boolean includeLocal,
                                                       boolean includeIPv6)

      Warning: When includeLocal is false, all returned addresses should be routable, but they are not necessarily appropriate for external use. For example, Teredo and 6to4 addresses are included with IPv6 results. Additional validation is recommended. See e.g. TransportUtil.isPubliclyRoutable().
      Parameters:
        `includeLocal` - whether to include local addresses and deprecated IPv6 addresses
        `includeIPv6` - whether to include IPv6 addresses
      Returns:
        a sorted set of all addresses including wildcard

    - #### getAddresses

          public static SortedSet<String> getAddresses(boolean includeSiteLocal,
                                                       boolean includeLoopbackAndWildcard,
                                                       boolean includeIPv6)

      Warning: When includeSiteLocal and includeLoopbackAndWildcard are false, all returned addresses should be routable, but they are not necessarily appropriate for external use. For example, Teredo and 6to4 addresses are included with IPv6 results. Additional validation is recommended. See e.g. TransportUtil.isPubliclyRoutable().
      Parameters:
        `includeSiteLocal` - whether to include private addresses like 192.168.x.x and deprecated IPv6 addresses
        `includeLoopbackAndWildcard` - whether to include loopback addresses (127.x.x.x) and wildcard (0.0.0.0)
        `includeIPv6` - whether to include IPv6 addresses
      Returns:
        a sorted set of all addresses

    - #### getAddresses

          public static SortedSet<String> getAddresses(boolean includeSiteLocal,
                                                       boolean includeLoopbackAndWildcard,
                                                       boolean includeIPv6,
                                                       boolean includeIPv6Temporary)

      Warning: When includeSiteLocal and includeLoopbackAndWildcard are false, all returned addresses should be routable, but they are not necessarily appropriate for external use. For example, Teredo and 6to4 addresses are included with IPv6 results. Additional validation is recommended. See e.g. TransportUtil.isPubliclyRoutable().
      Parameters:
        `includeSiteLocal` - whether to include private addresses like 192.168.x.x and deprecated IPv6 addresses
        `includeLoopbackAndWildcard` - whether to include loopback addresses (127.x.x.x) and wildcard (0.0.0.0)
        `includeIPv6` - whether to include IPv6 addresses
        `includeIPv6Temporary` - whether to include IPv6 temporary addresses
      Returns:
        a sorted set of all addresses

    - #### getAllAddresses

          public static SortedSet<String> getAllAddresses()

      Gets all addresses excluding only link-local and multicast addresses.
      Returns:
        a sorted set of all addresses, excluding only link local and multicast

    - #### getAnyAddress

          public static String getAnyAddress()

      Gets the first non-local IPv4 address found.
      Returns:
        the first non-local address IPv4 address it finds, or null

    - #### getConnectedAddressTypes

          public static Set<AddressType> getConnectedAddressTypes()

      Efficiently get all connected address types in one pass. Caller should cache results for better performance.
      Returns:
        the set of connected address types, non-null

    - #### getIP

          public static byte[] getIP(String host)

      Caching version of InetAddress.getByName(host).getAddress(), which is slow. Caches numeric addresses only. Will resolve but not cache DNS addresses. DEPRECATED for IPs in RouterAddresses, blocklists, etc.; use getIPOnly() instead. Behavior differences from InetAddress.getByName():
      - Does not allow numeric IPs of the form d.d.d, d.d, or d (considered mistakes)
      - Returns null for null or empty host (vs. 127.0.0.1 in InetAddress)
      Parameters:
        `host` - DNS or IPv4 or IPv6 address; if null or empty returns null
      Returns:
        IP address bytes or null

    - #### getIP

          public static byte[] getIP(String host,
                                     boolean preferIPv6)

      For literal IP addresses, same as getIP(String). For hostnames, returns the preferred type (IPv4/v6) if available, else the other type. Will resolve but not cache DNS hostnames. Behavior differences from InetAddress.getByName():
      - Returns null for null or empty host (vs. 127.0.0.1 in InetAddress)
      Parameters:
        `host` - DNS or IPv4 or IPv6 address; if null returns null
        `preferIPv6` - whether to prefer IPv6 addresses
      Returns:
        IP address bytes or null

    - #### getIPOnly

          public static byte[] getIPOnly(String host)

      Caching version of InetAddress.getByName(host).getAddress(), which is slow. Resolves literal IP addresses only without DNS lookups. Returns null for hostnames. PREFERRED for IPs in RouterAddresses, blocklists, etc. over getIP() because it avoids getByName() in most cases. Behavior differences from InetAddress.getByName():
      - Does not allow numeric IPs of the form d.d.d, d.d, or d (considered mistakes)
      - Returns null for null or empty host (vs. 127.0.0.1 in InetAddress)
      Parameters:
        `host` - literal IPv4 or IPv6 address; if null returns null
      Returns:
        IP address bytes or null

    - #### getIPs

          public static List<byte[]> getIPs(String host)

      For literal IP addresses, same as getIP(String). For hostnames, may return multiple addresses (both IPv4 and IPv6), even if unreachable. Will resolve but not cache DNS hostnames. Note: Order and number of results are platform-specific and depend on JVM options (java.net.preferIPv4Stack, java.net.preferIPv6Addresses) and caching layers. Behavior differences from InetAddress.getByName():
      - Returns null for null or empty host (vs. 127.0.0.1 in InetAddress)
      Parameters:
        `host` - DNS or IPv4 or IPv6 address; if null returns null
      Returns:
        non-empty list of IP addresses, or null if none

    - #### getPort

          public static int getPort(String port)

      Convenience method to convert and validate a port String without throwing an exception. Does not trim.
      Parameters:
        `port` - the port string to convert
      Returns:
        1-65535 or 0 if invalid

    - #### getYggdrasilAddress

          public static byte[] getYggdrasilAddress()

      Caller should cache results for better performance.
      Returns:
        the IPv6 address with prefix 02xx: or 03xx:, or null

    - #### isConnected

          public static boolean isConnected()

      Do we have any non-loop, non-wildcard IPv4 address at all? Use getConnectedAddressTypes() to get all types at once for better performance.
      Returns:
        true if connected to IPv4

    - #### isConnected

          public static boolean isConnected(AddressType type)

      Do we have any address of this type? Use getConnectedAddressTypes() to get all types at once for better performance.
      Parameters:
        `type` - the address type to check
      Returns:
        true if connected to the specified address type

    - #### isConnectedIPv6

          public static boolean isConnectedIPv6()

      Do we have any non-loop, non-wildcard IPv6 address at all? Use getConnectedAddressTypes() to get all types at once for better performance.
      Returns:
        true if connected to IPv6

    - #### isDeprecated

          public static boolean isDeprecated(Inet6Address addr)

      Determines if an IPv6 address is deprecated. Reliable on Linux. Returns false on Windows, Mac, and BSD.
      Parameters:
        `addr` - IPv6 address of a local interface, as returned from getAddresses()
      Returns:
        true if address is deprecated

    - #### isDynamic

          public static boolean isDynamic(Inet6Address addr)

      Determines if an IPv6 address is dynamic. Reliable on Linux. Best guess on Windows, Mac, and BSD (only valid for global scope).
      Parameters:
        `addr` - IPv6 address of a local interface, as returned from getAddresses()
      Returns:
        true if address is dynamic

    - #### isIPAddress

          public static boolean isIPAddress(String host)

      Checks if the host is a valid IP address (IPv4 or IPv6).
      Parameters:
        `host` - the host to check
      Returns:
        true if either IPv4 or IPv6

    - #### isIPv4Address

          public static boolean isIPv4Address(String host)

      Checks if the host is a valid IPv4 address.
      Parameters:
        `host` - the host to check
      Returns:
        true if IPv4 address

    - #### isIPv6Address

          public static boolean isIPv6Address(String host)

      Checks if the host is a valid IPv6 address.
      Parameters:
        `host` - the host to check
      Returns:
        true if IPv6 address

    - #### isTemporary

          public static boolean isTemporary(Inet6Address addr)

      Determines if an IPv6 address is temporary. Reliable on Linux. Best guess on Windows, Mac, and BSD (only valid for global scope).
      Parameters:
        `addr` - IPv6 address of a local interface, as returned from getAddresses()
      Returns:
        true if address is temporary

    - #### main

          public static void main(String[] args)

      Print out the local addresses
      Parameters:
        `args` - command line arguments

    - #### toCanonicalString

          public static String toCanonicalString(byte[] addr)

      Same as toString() but returns IPv6 in compressed form per RFC 5952.
      Parameters:
        `addr` - the IP address as byte array
      Returns:
        canonical string representation, or "null" for null input, or "bad IP length x" if length is invalid

    - #### toCanonicalString

          public static String toCanonicalString(byte[] addr,
                                                 int port)

      Same as toString() but returns IPv6 in compressed form per RFC 5952.
      Parameters:
        `addr` - the IP address as byte array
        `port` - the port number
      Returns:
        canonical string representation with port, or error message for invalid input

    - #### toCanonicalString

          public static String toCanonicalString(String host)

      Converts IPv6 to compressed form per RFC 5952. IPv4 returned unchanged.
      Parameters:
        `host` - the host string to convert
      Returns:
        canonical string representation, or "null" for null input

    - #### toString

          public static String toString(byte[] addr)

      Convenience method to convert an IP address to a String without throwing an exception.
      Parameters:
        `addr` - the IP address as byte array
      Returns:
        string representation, or "null" for null input, or "Bad IP length x" if length is invalid

    - #### toString

          public static String toString(byte[] addr,
                                        int port)

      Convenience method to convert an IP address and port to a String without throwing an exception.
      Parameters:
        `addr` - the IP address as byte array
        `port` - the port number
      Returns:
        formatted string as "ipv4:port" or "[ipv6]:port", or error message for invalid input

    - #### useIPv6TempAddresses

          public static String useIPv6TempAddresses()

      Checks if temporary IPv6 addresses are enabled system-wide.
      Returns:
        "true", "false", or "unknown" (for Windows/Mac where detection is not supported)