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 point is the isDomain(String) method. 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 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 int	bra(int deltapos)	Jumps to a specified input character position, relative jump.
protected 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 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 int	peek()	Returns the wide character after the one at the current position.
protected int	pos()	Returns the current input character position.
protected String	s()	Returns the input string, for use with substring comparisons.
protected int	skip(ContextlessMatcher matcher)	Advances the current position using a regular matcher.
protected 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 Detail

FQDN

protected FQDN(String input)

Private constructor. Use the factory method of(String) instead.

Parameters:

input - string to analyse

Method Detail

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 (‘.’).

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 (‘.’).

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 the trailing dot commonly seen in DNS data files.

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(ContextlessMatcher)

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:

skipPeek(LookaheadMatcher)