Package org.evolvis.tartools.rfc822

Class FQDN

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

Represents an FQDN (“domain” production) for use in eMail.

The main entry points are the isDomain(String) and asDomain(String) methods. The parser does not trim surrounding whitespace by itself.

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

  • Constructor Summary

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

  • Method Summary

    Modifier and Type
    Method
    Description
    protected final int
    accept()
    Advances the current position to the next character.
    static String
    asDomain(String hostname)
    Checks if a supposed hostname is a valid Fully-Qualified Domain Name and retrieves a more canonical form.
    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.
    boolean
    isDomain()
    Checks if a supposed hostname is a valid Fully-Qualified Domain Name.
    static boolean
    isDomain(String hostname)
    Checks if a supposed hostname is a valid Fully-Qualified Domain Name.
    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 FQDN
    of(String hostname)
    Creates and initialises a new parser for Fully-Qualified Domain Names.
    protected final int
    peek()
    Returns the wide character after the one at the current position.
    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.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • FQDN

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

  • Method Details

    • of

      public static FQDN of(String hostname)
      Creates and initialises a new parser for Fully-Qualified Domain Names.
      Parameters:
      hostname - to parse
      Returns:
      null if hostname was null or longer than 253 characters, the new parser instance otherwise

    • isDomain

      public boolean isDomain()

      Checks if a supposed hostname is a valid Fully-Qualified Domain Name.

      Valid FQDNs are up to 253 octets in length, comprised only of labels (letters, digits and hyphen-minus, but not beginning or ending with a hyphen-minus) one up to 63 octets long, separated by dots (‘.’). This method accepts the dot-atom form only, without trailing dot.

      Strictly speaking an FQDN could be 255 octets in length, but these will not work with DNS (the separating dots are matched by the length octets of their succeeding label, but two extra octets are needed for the length octet of the first label and of the root (i.e. nil) domain; SMTP has a 254-octet limit for the Forward-path (in RFC5321) as well.

      Returns:
      true if the hostname passed during construction is valid, else false

    • isDomain

      public static boolean isDomain(String hostname)

      Checks if a supposed hostname is a valid Fully-Qualified Domain Name.

      Valid FQDNs are up to 253 octets in length, comprised only of labels (letters, digits and hyphen-minus, but not beginning or ending with a hyphen-minus) one up to 63 octets long, separated by dots (‘.’). This method accepts the dot-atom form only, without trailing dot.

      Strictly speaking an FQDN could be 255 octets in length, but these will not work with DNS (the separating dots are matched by the length octets of their succeeding label, but two extra octets are needed for the length octet of the first label and of the root (i.e. nil) domain; SMTP has a 254-octet limit for the Forward-path (in RFC5321) as well.

      Parameters:
      hostname - to check
      Returns:
      true if hostname is valid, false otherwise

    • asDomain

      public static String asDomain(String hostname)

      Checks if a supposed hostname is a valid Fully-Qualified Domain Name and retrieves a more canonical form.

      Valid FQDNs are up to 253 octets in length, comprised only of labels (letters, digits and hyphen-minus, but not beginning or ending with a hyphen-minus) one up to 63 octets long, separated by dots (‘.’). This method accepts an optional additional trailing dot as commonly seen in DNS data files, and which may be valid for some contexts; if present, the input may be 254 octets long.

      Strictly speaking an FQDN could be 255 octets in length, but these will not work with DNS (the separating dots are matched by the length octets of their succeeding label, but two extra octets are needed for the length octet of the first label and of the root (i.e. nil) domain; SMTP has a 254-octet limit for the Forward-path (in RFC5321) as well.

      This method returns the dot-atom form: a trailing dot is removed, if any existed. To get the canonical form from there, normalise letter case.

      Parameters:
      hostname - to check
      Returns:
      dot-atom form of hostname if valid, null otherwise

    • 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: