Package org.evolvis.tartools.rfc822

Class IPAddress

java.lang.Object
org.evolvis.tartools.rfc822.IPAddress
public class IPAddress extends Object

Represents an IP address (including Legacy IP) for use in eMail on the public Internet (no scoped addresses / IPv6 Zone ID).

The main entry points are either the from(String) method or both the v6(String) and v4(String) methods. The parser does not trim surrounding whitespace by itself.

Author:
mirabilos (t.glaser@tarent.de)

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    IPAddress(String input)
    Private constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected final int
    accept()
    Advances the current position to the next character.
    InetAddress
    asIPv4Address()
    Parses the given address as Legacy IP address (IPv4).
    InetAddress
    asIPv6Address()
    Parses the given address as IP address (IPv6), excluding Zone ID (scope).
    protected final int
    bra(int deltapos)
    Jumps to a specified input character position, relative jump.
    protected final int
    cur()
    Returns the wide character at the current position.
    static InetAddress
    from(String address)
    Parses the passed string as IP address (IPv6 or Legacy IPv4), IPv6 “scope” (Zone ID) excluded.
    protected final int
    jmp(int pos)
    Jumps to a specified input character position, absolute jump.
    protected static <T extends org.evolvis.tartools.rfc822.Parser>
    T
    of(Class<T> cls, String input)
    Constructs a parser.
    static IPAddress
    of(String address)
    Creates and initialises a new IP address parser.
    protected final int
    peek()
    Returns the wide character after the one at the current position.
    protected byte[]
    pIPv4Address()
     
    protected byte[]
    pIPv6Address()
     
    protected final int
    pos()
    Returns the current input character position.
    protected final String
    s()
    Returns the input string, for use with substring comparisons.
    protected final int
    skip(ContextlessMatcher matcher)
    Advances the current position using a regular matcher.
    protected final int
    skipPeek(LookaheadMatcher matcher)
    Advances the current position using a peeking matcher.
    static InetAddress
    v4(String address)
    Parses the passed string as Legacy IP address (IPv4).
    static InetAddress
    v6(String address)
    Parses the passed string as IP address (IPv6), excluding Zone ID (scope).

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • IPAddress

      protected IPAddress(String input)
      Private constructor. Use the factory method of(String) instead.
      Parameters:
      input - string to analyse

  • Method Details

    • of

      public static IPAddress of(String address)

      Creates and initialises a new IP address parser.

      Use with asIPv6Address() and asIPv4Address() to validate IPv6 and IPv4 addresses, excluding IPv6 Zone IDs (“scope”).

      Parameters:
      address - to parse (protocol depends on parser method called)
      Returns:
      null if address was null or much too large, the new parser instance otherwise

    • asIPv6Address

      public InetAddress asIPv6Address()

      Parses the given address as IP address (IPv6), excluding Zone ID (scope).

      Note that the returned InetAddress object can be an Inet4Address object, for example if the passed address represents a v4-mapped address; in most cases it will be an Inet6Address object though. In either case, if the address is no valid IPv6 address (e.g. because it is an IPv4 address), null will be returned instead, so the return value can be used to distinguish the address families, even if a v4-mapped address occurs.

      Calling the InetAddress.getHostName() method on the result will return the original string in all cases anyway.

      Returns:
      InetAddress representing the address, or null on failure (including if an IPv4 address is passed)
      See Also:

    • asIPv4Address

      public InetAddress asIPv4Address()

      Parses the given address as Legacy IP address (IPv4).

      Calling the InetAddress.getHostName() method on the result will return the original string.

      Returns:
      InetAddress representing the address, or null on failure (including if an IPv6 address is passed)
      See Also:

    • v6

      public static InetAddress v6(String address)

      Parses the passed string as IP address (IPv6), excluding Zone ID (scope).

      Note that the returned InetAddress object can be an Inet4Address object, for example if the passed address represents a v4-mapped address; in most cases it will be an Inet6Address object though. In either case, if the address is no valid IPv6 address (e.g. because it is an IPv4 address), null will be returned instead, so the return value can be used to distinguish the address families, even if a v4-mapped address occurs.

      Calling the InetAddress.getHostName() method on the result will return the original address string in all cases anyway.

      Parameters:
      address - string to parse as IPv6 address
      Returns:
      InetAddress representing the address string, or null on failure (including if an IPv4 address is passed)
      See Also:

    • v4

      public static InetAddress v4(String address)

      Parses the passed string as Legacy IP address (IPv4).

      Calling the InetAddress.getHostName() method on the result will return the original address string.

      Parameters:
      address - to parse as IPv4 address
      Returns:
      InetAddress representing the address string, or null on failure (including if an IPv6 address is passed)
      See Also:

    • from

      public static InetAddress from(String address)

      Parses the passed string as IP address (IPv6 or Legacy IPv4), IPv6 “scope” (Zone ID) excluded. A valid address is intended to be used on the public Internet, such as for eMail.

      Note that the result can be an Inet4Address for both IPv4 and (some) IPv6 addresses such as v4-mapped but will be Inet6Address for a “regular” IPv6 address — this means this method cannot be used to determine the kind of address passed. Calling the InetAddress.getHostName() method on the result will return the original address string in all cases anyway.

      Parameters:
      address - String to parse as IP or Legacy IP address
      Returns:
      InetAddress representing address, or null on failure
      See Also:

    • pIPv4Address

      protected byte[] pIPv4Address()

    • pIPv6Address

      protected byte[] pIPv6Address()

    • of

      protected static <T extends org.evolvis.tartools.rfc822.Parser> T of(Class<T> cls, String input)

      Constructs a parser. Intended to be used by subclasses from static factory methods *only*; see Path.of(String) for an example.

      Type Parameters:
      T - subclass of Parser to construct
      Parameters:
      cls - subclass of Parser to construct
      input - user-provided String to parse
      Returns:
      null if input was null or too large, the new parser subclass instance otherwise

    • jmp

      protected final int jmp(int pos)
      Jumps to a specified input character position, absolute jump.
      Parameters:
      pos - to jump to
      Returns:
      the codepoint at that position
      Throws:
      IndexOutOfBoundsException - if pos is not in or just past the input

    • bra

      protected final int bra(int deltapos)
      Jumps to a specified input character position, relative jump.
      Parameters:
      deltapos - to add to the current position
      Returns:
      the codepoint at that position
      Throws:
      IndexOutOfBoundsException - if pos is not in or just past the input

    • pos

      protected final int pos()
      Returns the current input character position. Useful for saving and restoring (with jmp(int)) and for error messages.
      Returns:
      position

    • s

      protected final String s()
      Returns the input string, for use with substring comparisons. (This is safe because Java™ strings are immutable.)
      Returns:
      String input

    • cur

      protected final int cur()
      Returns the wide character at the current position.
      Returns:
      UCS-4 codepoint, or -1 if end of input is reached

    • peek

      protected final int peek()
      Returns the wide character after the one at the current position.
      Returns:
      UCS-4 codepoint, or -1 if end of input is reached

    • accept

      protected final int accept()
      Advances the current position to the next character.
      Returns:
      codepoint of the next character, or -1 if end of input is reached
      Throws:
      IndexOutOfBoundsException - if end of input was already reached

    • skipPeek

      protected final int skipPeek(LookaheadMatcher matcher)
      Advances the current position using a peeking matcher. Continues as long as the matcher returns true and end of input is not yet reached.
      Parameters:
      matcher - LookaheadMatcher called with cur() and peek() as arguments to determine whether to skip ahead
      Returns:
      codepoint of the first character for which the matcher returned false, or -1 if end of input is reached
      See Also:

    • skip

      protected final int skip(ContextlessMatcher matcher)
      Advances the current position using a regular matcher. Continues as long as the matcher returns true and end of input is not yet reached.
      Parameters:
      matcher - ContextlessMatcher called with just cur() as argument to determine whether to skip ahead
      Returns:
      codepoint of the first character for which the matcher returned false, or -1 if end of input is reached
      See Also: