Package com.globalmentor.net

Class ResourceRecord

java.lang.Object
com.globalmentor.net.ResourceRecord
public class ResourceRecord extends Object
Encapsulation of information that appears in the resource record of a DNS zone file.
Author:
Garret Wilson
API Note:
This is an entity type, not a value type. In particular equality is not defined based upon the contents of the record.
Implementation Specification:
This implementation does not support raw TXT records that begin and end with double-quote characters as if they were quoted. It is likely such values do not exist in real-world scenarios,, This implementation does not handle escaped characters other than '\"' and '\\'. as quoted strings as per RFC 1035 indicate escaping.
See Also:

  • Field Details

    • CHARACTER_STRING_QUOTE_CHAR

      public static final char CHARACTER_STRING_QUOTE_CHAR
      The character for quoting a string designated as a character-string in RFC 1035 containing spaces.
      See Also:

    • CHARACTER_STRING_ESCAPE_CHAR

      public static final char CHARACTER_STRING_ESCAPE_CHAR
      The character for escaping a quote character in a string designated as a character-string in RFC 1035.
      See Also:

  • Constructor Details

    • ResourceRecord

      public ResourceRecord(@Nonnull ResourceRecord.Type type, @Nullable DomainName name, @Nonnull String value, @Nonnegative long ttl)
      Constructor using a known type.
      API Note:
      The given value must be in its unencoded form. If storing use-entered information, it may be desirable to call decodeCharactString(String) on the value first.
      Parameters:
      type - The type of resource record.
      name - The domain name of the resource record, which may be absolute or relative if the name should be resolved against the origin; or null to indicate the origin should be used.
      value - The value to store in the resource record, encoded as a appropriate for the resource record type.
      ttl - The resource record cache time to live, in seconds; or -1 if not specified, indicating the default TTL should be used.
      Throws:
      IllegalArgumentException - if the given TTL is a negative value other than -1.
      See Also:

    • ResourceRecord

      public ResourceRecord(@Nonnull String type, @Nullable DomainName name, @Nonnull String value, @Nonnegative long ttl)
      Constructor.
      API Note:
      The given value must be in its unencoded form. If storing use-entered information, it may be desirable to call decodeCharactString(String) on the value first.
      Parameters:
      type - The type of resource record.
      name - The domain name of the resource record, which may be absolute or relative if the name should be resolved against the origin; or null to indicate the origin should be used.
      value - The value to store in the resource record, encoded as a appropriate for the resource record type.
      ttl - The resource record cache time to live, in seconds; or -1 if not specified, indicating the default TTL should be used.
      Throws:
      IllegalArgumentException - if the given TTL is a negative value other than -1.
      See Also:

  • Method Details

    • getType

      public String getType()
      Returns:
      The type of resource record.

    • getName

      public Optional<DomainName> getName()
      Returns:
      The domain name of the resource record, which may be absolute or relative if the name should be resolved against the origin; or empty to indicate the origin should be used.

    • getValue

      public String getValue()
      Returns:
      The resource record value encoded as a appropriate for the resource record type.

    • getTtl

      public OptionalLong getTtl()
      Returns:
      The resource record cache time to live, in seconds; or empty if not specified, indicating the default TTL should be used.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • detectCharacterStringEncoded

      public static boolean detectCharacterStringEncoded(@Nonnull String string)
      Attempts to determine whether a string designated as a character-string in RFC 1035 is already encoded (quoted) as per RFC 1035.
      API Note:
      Not all string values are "character string" value; this only applies to the values of some types of records in RFC 1035, notably ResourceRecord.Type.TXT.
      Implementation Note:
      This method has no way of knowing with certainty whether a value is encoded, because a string with surrounding double-quote characters could simply be a string itself needing encoding. However such a situation is very rare and unlikely to be found in practice.
      Parameters:
      string - A "character string" value that may or may not already be encoded.
      Returns:
      true if the given "character string" is in quoted, encoded form.
      Throws:
      IllegalArgumentException - if the given value is incorrectly encoded, for example starting but not ending with a double quote.
      See Also:

    • normalizeCharacterString

      public static String normalizeCharacterString(@Nonnull String string)
      Encodes (quotes) as needed a resource record string designated as a character-string in RFC 1035. If the value is detected as already encoded, the string is returned unchanged. Otherwise the string is quoted only as necessary (i.e. if it contains one or more spaces) unless always quoting is requested.
      API Note:
      This method may be useful for normalizing an RFC 1035 character string entered by a user.
      Implementation Specification:
      This method delegates to normalizeCharacterString(String, boolean).
      Implementation Note:
      This method has no way of knowing with certainty whether a value is encoded, because a string with surrounding double-quote characters could simply be a string itself needing encoding. However such a situation is very rare and unlikely to be found in practice.
      Parameters:
      string - A "character string" value that may or may not already be encoded.
      Returns:
      The value encoded as necessary for a "character string".
      See Also:

    • normalizeCharacterString

      public static String normalizeCharacterString(@Nonnull String string, boolean alwaysQuote)
      Encodes (quotes) as needed a resource record string designated as a character-string in RFC 1035. If the value is detected as already encoded, the string is returned unchanged. Otherwise the string is quoted only as necessary (i.e. if it contains one or more spaces).
      API Note:
      This method may be useful for normalizing an RFC 1035 character string entered by a user.
      Implementation Note:
      This method has no way of knowing with certainty whether a value is encoded, because a string with surrounding double-quote characters could simply be a string itself needing encoding. However such a situation is very rare and unlikely to be found in practice.
      Parameters:
      string - A "character string" value that may or may not already be encoded.
      alwaysQuote - true if the string should always be quoted, even if it contains no characters that require quoting by RFC 1035.
      Returns:
      The value encoded as necessary for a "character string".
      See Also:

    • encodeCharacterString

      public static String encodeCharacterString(@Nonnull String string)
      Encodes (quotes) a resource record string designated as a character-string in RFC 1035. The string is quoted only as necessary (i.e. if it contains one or more spaces).
      API Note:
      Calling this method multiple times on a string that needs encoding will result in a string that is multiply-encoded.
      Implementation Specification:
      This method delegates to encodeCharacterString(String, boolean).
      Parameters:
      string - A raw, unencoded resource record string value.
      Returns:
      The value encoded as necessary for a "character string".

    • encodeCharacterString

      public static String encodeCharacterString(@Nonnull String string, boolean alwaysQuote)
      Encodes (quotes) a resource record string designated as a character-string in RFC 1035. The string is quoted only as necessary (i.e. if it contains one or more spaces) unless always quoting is requested.
      API Note:
      Calling this method multiple times on a string that needs encoding will result in a string that is multiply-encoded.
      Parameters:
      string - A raw, unencoded resource record string value.
      alwaysQuote - true if the string should always be quoted, even if it contains no characters that require quoting by RFC 1035.
      Returns:
      The value encoded as necessary for a "character string".

    • decodeCharactString

      public static String decodeCharactString(@Nonnull String characterString)
      Decodes a resource record string designated as a character-string in RFC 1035 if it is quoted. If the value is not quoted, the string is returned unchanged.
      API Note:
      In theory calling this method multiple times on a string that was doubly quoted would result in different strings; that is, if a quoted string itself had been encoded.
      Parameters:
      characterString - A resource record "character string" value in encoded form, potentially quoted.
      Returns:
      The character string decoded as appropriate.
      Throws:
      IllegalArgumentException - if the given value is incorrectly encoded, for example starting but not ending with a double quote.