Module nbbrd.design
Package nbbrd.design

Annotation Type RepresentableAsString

@Target(TYPE) @Retention(CLASS) @Documented public @interface RepresentableAsString
Indicates that a class can be represented unambiguously by a String.

The annotated class must satisfy the following contracts:

  • Parser: It must have a public static factory method (named by parseMethodName()) that accepts a single CharSequence parameter, returns the enclosing type, and does not throw any checked exception. An invalid input should raise an IllegalArgumentException (or a subclass thereof).
  • Formatter: It must have a public non-static, no-arg method (named by formatMethodName()) that returns a String and does not throw any checked exception.
  • Short formatter (optional): When hasShortFormat() is true, the class must also have a public non-static, no-arg method (named by shortFormatMethodName()) that returns a String and does not throw any checked exception.

The string representation should be consistent: formatting an object to a string and parsing that string back should yield an equal object.

Author:
Philippe Charles

  • Element Details

    • parseMethodName

      String parseMethodName
      Name of the static factory method used to parse a CharSequence into an instance of the annotated class.

      The method must be public static, accept a single CharSequence parameter, return the annotated type, and not throw any checked exception.

      Returns:
      the parse method name; defaults to "parse"
      Default:
      "parse"

    • formatMethodName

      String formatMethodName
      Name of the instance method used to format the object as a String.

      The method must be public, non-static, accept no parameters, return a String, and not throw any checked exception.

      Returns:
      the format method name; defaults to "toString"
      Default:
      "toString"

    • hasShortFormat

      boolean hasShortFormat
      Whether to enforce the presence of a short format method.

      When true, the annotated class must also have a public, non-static, no-arg method named shortFormatMethodName() that returns a String and does not throw any checked exception. The method may be inherited from a parent class.

      Returns:
      true to enforce a short format method; defaults to false
      Default:
      false

    • shortFormatMethodName

      String shortFormatMethodName
      Name of the short format method used to produce an abbreviated string representation.

      This property is only effective when hasShortFormat() is true. The referenced method must be public, non-static, accept no parameters, return a String, and not throw any checked exception. The method may be inherited from a parent class.

      Returns:
      the short format method name; defaults to "toShortString"
      Default:
      "toShortString"