Package name.martingeisse.grumpyjson.builtin.record

Class RecordConverter<T>

java.lang.Object
name.martingeisse.grumpyjson.builtin.record.RecordConverter<T>
Type Parameters:
T - the record type
All Implemented Interfaces:
JsonDeserializer, JsonSerializer<T>
public final class RecordConverter<T> extends Object implements JsonSerializer<T>, JsonDeserializer
Maps a record class to and from a JSON object.

A RecordConverter is built for the raw type (class) of a record, so a single instance handles all parameterized types for that raw type.

Serialization is based on the run-time classes of all values and so is straightforward.

For deserialization, at run time (potential optimization: at selection time) the deserializer is used for a concrete parameterized type. This type must be concrete in the sense that it cannot contain type variables anymore (nor wildcards -- we do not support those anyway). If the field that uses the record type *did* use type variables, then these must have been replaced by concrete types before passing on to this deserializer. So at this point the record type has an ordered list of named type parameters, and the concrete type binds them to an ordered list of concrete type arguments.

This deserializer then goes through the record fields. Each field potentially uses type variables, and all these must have been declared as type parameters by the record -- type variables (as opposed to the types they are bound to) do not cross the boundaries of a single record definition, and fields cannot define their own type variables.

For each record field, the field type is "concretized" -- replaced by a like-structured type in which type variables have been replaced by the types they are bound to. A single type variable is looked up in the record's type parameters by name, then the type argument at the same index is bound to the variable.

Finally, the fields get deserialized from the JSON fields using the deserializers for the resulting concrete types.

  • Constructor Details

    • RecordConverter

      public RecordConverter(Class<T> clazz, JsonRegistries registries)
      Application code usually does not have to call this constructor because instances of this class will be auto-generated for unknown records, and this constructor does not add any features on top of that.
      Parameters:
      clazz - the record class
      registries - the JSON registries -- needed to fetch the converters for field types at run-time

    • RecordConverter

      public RecordConverter(Class<T> clazz, JsonRegistries registries, RecordConverter.Options options)
      This constructor adds extra options. Application code can create custom record converters manually using this constructor in cases where the auto-generated ones are not sufficient.
      Parameters:
      clazz - the record class
      registries - the JSON registries -- needed to fetch the converters for field types at run-time
      options - options that control the conversion from and to JSON

  • Method Details

    • supportsTypeForDeserialization

      public boolean supportsTypeForDeserialization(Type type)
      Description copied from interface: JsonDeserializer
      Checks if this deserializer supports the specified type.
      Specified by:
      supportsTypeForDeserialization in interface JsonDeserializer
      Parameters:
      type - the type to check
      Returns:
      true if supported, false if not

    • deserialize

      public T deserialize(com.google.gson.JsonElement json, Type recordType) throws JsonDeserializationException
      Description copied from interface: JsonDeserializer
      Converts a value from JSON.

      This method must not be called with a type for which JsonDeserializer.supportsTypeForDeserialization(Type) returns false. Calling it with such types anyway results in undefined behavior.

      Specified by:
      deserialize in interface JsonDeserializer
      Parameters:
      json - the JSON
      recordType - the type to deserialize
      Returns:
      the deserialized value
      Throws:
      JsonDeserializationException - if the JSON does not match the expected structure

    • supportsClassForSerialization

      public boolean supportsClassForSerialization(Class<?> clazz)
      Description copied from interface: JsonSerializer
      Checks if this serializer supports the specified class.
      Specified by:
      supportsClassForSerialization in interface JsonSerializer<T>
      Parameters:
      clazz - the class to check
      Returns:
      true if supported, false if not

    • serialize

      public com.google.gson.JsonElement serialize(T record)
      Description copied from interface: JsonSerializer
      Converts a value to JSON.

      This method must not be called with values for whose class JsonSerializer.supportsClassForSerialization(Class) returns false. Calling it with such values anyway results in undefined behavior.

      This method is not supported for values that can vanish during serialization, such as OptionalField -- JsonSerializer.serializeOptional(Object) should be called instead. If this method is called with such values anyway, it should always fail, even when the value does not vanish, to capture bugs early. Examples where this happens: - in a list of OptionalFields. While we could simply remove vanishing elements, doing so is just a weird way of filtering the list before serialization, which can be done the usual way. Moreover, there is no useful interpretation of a list-of-OptionalField during deserialization since all elements found in the JSON are known to be present, and vanishing elements cannot be found. - when turning a top-level OptionalField to JSON - when nesting two OptionalFields

      Specified by:
      serialize in interface JsonSerializer<T>
      Parameters:
      record - the value to convert to JSON
      Returns:
      the generated JSON