Interface ResourceCodec<R>

All Known Subinterfaces:
JsonResourceCodec<R>
All Known Implementing Classes:
ExtensionPointResourceCodec, GsonResourceCodec, JsonResourceCodecWrapper

public interface ResourceCodec<R>
Responsible for encoding and decoding configuration Resource objects.
  • Method Summary

    Modifier and Type
    Method
    Description
    decode(Resource resource)
    Decodes a resource's config object from its serialized form.
    Decodes a resource if it is valid (able to be decoded without exception), otherwise returns an empty optional (if decoding throws an exception).
    void
    encode(R config, ResourceBuilder builder)
    Encodes a resource's config object, and stores it in the resource in the appropriate location.
  • Method Details

    • encode

      void encode(R config, ResourceBuilder builder)
      Encodes a resource's config object, and stores it in the resource in the appropriate location.
    • decode

      DecodedResource<R> decode(Resource resource) throws DecodingException
      Decodes a resource's config object from its serialized form.

      Common practice is to choose an immutable POJO style class such as a record class or kotlin data class, one which is built to be naturally GSON-serializable. Then, use GSON to serialize and deserialize instances of this type to/from a data file on the resource called "config.json".

      Note that it is not recommended to store the resource's name in this object, as the name is the key of the resource, and it is encoded in the resource's path. For this reason, many methods in this interface and the various "handlers" that use this interface will provide the object returned from this method in an envelope class that also contains the Resource itself: DecodedResource.

      Similarly, in is not necessary to encode auxiliary data files in this config object, since they can/should be retrieved directly from the Resource object available in the DecodedResource envelope.

      If for any reason the resource cannot be decoded (mal-formed configuration, for example), this method should throw a DecodingException with a helpful message.

      Parameters:
      resource - The resource to decode.
      Returns:
      The decoded resource.
      Throws:
      DecodingException - If the resource cannot be decoded.
      See Also:
    • decodeIfValid

      default Optional<DecodedResource<R>> decodeIfValid(Resource resource)
      Decodes a resource if it is valid (able to be decoded without exception), otherwise returns an empty optional (if decoding throws an exception).