Package com.kazforge.jsonapi.mapping

Interface IdentifierConverter

Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface IdentifierConverter
Converts a domain identifier value to its JSON:API string representation, and back.

One conversion authority serves both identity roles: the id role mapped by @JsonApiId and the lid role mapped by @JsonApiLocalId. Their Java scalar conversion semantics are equivalent; only the JSON:API member they land on differs.

Write side: implementations receive the raw identifier value from the mapped identity property and return the string used as "id" or "lid" in the resource object. Return null to signal a missing identifier, which causes a JsonApiMappingException with MappingDiagnostic.MISSING_IDENTIFIER at that role's wire location.

Read side: parse(String) inverts convert(Object). The flat DTO binder passes the wire identifier string to parse(String) and coerces the returned value to the identity property's Java type. The default implementation returns the wire string unchanged; custom converters that alter the wire form must override parse(String) to invert that form.

Use defaults() for the built-in toString() conversion.

  • Method Summary

    Modifier and Type
    Method
    Description
    @Nullable String
    convert(@Nullable Object identifierValue)
    Converts a raw identifier value to its string form.
    static IdentifierConverter
    defaults()
    Returns the built-in converter that delegates to Object.toString().
    default @Nullable Object
    parse(@Nullable String wireIdentifier)
    Parses a JSON:API identifier string back into a value for the identifier property.

  • Method Details

    • convert

      @Nullable String convert(@Nullable Object identifierValue)
      Converts a raw identifier value to its string form. A null return signals a missing identifier.

    • parse

      default @Nullable Object parse(@Nullable String wireIdentifier)
      Parses a JSON:API identifier string back into a value for the identifier property.

      Called only when the resource object carries an identifier (id or lid). The returned value is coerced to the identifier property's Java type by the binder. A null return fails the bind with MappingDiagnostic.IDENTIFIER_CONVERSION_FAILED.

    • defaults

      static IdentifierConverter defaults()
      Returns the built-in converter that delegates to Object.toString().