Package com.kazforge.jsonapi.api

Interface JsonApiResources

public interface JsonApiResources
Backend-independent Level-1 ordinary resource operations: strict homogeneous reads, single/collection writes, and create/update document authoring. The current Jackson adapters implement these operations through caller-configured Jackson.

Reads bind directly to the caller-supplied target type and never require a resource-type registry. readOne requires primary data that is exactly one resource object; readCreate requires one resource object validated as a create request; readMany requires a resource collection. Null, absent, identifier, error, and cross-shape document states are never silently coerced. The Class overloads cover ordinary DTOs; the Type overloads cover generic targets whose fidelity genuinely requires a full type. Generic typed-document envelopes and heterogeneous binding remain advanced.

Writes coordinate mapping, configured decoration, mapped-document validation, and document emission internally. writeCreateDocument selects core CREATE_REQUEST validation and writeUpdateDocument selects core UPDATE_REQUEST validation; neither reimplements core rules. Where the caller has expected-identity context for an update, it is supplied explicitly as an EndpointIdentity. Operation names express JSON:API semantics and encode no HTTP transport.

Configured Jackson remains the sole property-naming authority; id and lid stay independent roles; ordinary relationships stay linkage-oriented with a present data member. Failures retain the document-read, core validation, and mapping diagnostic families.

  • Method Details

    • readOne

      <T> T readOne(String json, Class<T> type)
      Reads exactly one resource DTO. Requires single-resource primary data.

    • readOne

      <T> T readOne(InputStream json, Class<T> type)
      Stream variant of readOne(String, Class). The stream is not closed.

    • readOne

      Object readOne(String json, Type type)
      Reads exactly one resource DTO using a full generic type. The caller ensures type denotes T.

    • readOne

      Object readOne(InputStream json, Type type)
      Stream variant of readOne(String, Type). The stream is not closed. The caller ensures type denotes the returned value.

    • readCreate

      <T> T readCreate(String json, Class<T> type)
      Reads exactly one primary resource DTO using core CREATE_REQUEST validation. The primary id may be absent; lid remains independent and may identify a matching primary self-reference. Supplied primary relationships require data. The complete document, including included-resource identities and full linkage, is validated before binding; included is not used to hydrate DTO relationships. Response reads retain their ordinary validation semantics.

    • readCreate

      <T> T readCreate(InputStream json, Class<T> type)
      Stream variant of readCreate(String, Class). The stream is not closed.

    • readCreate

      Object readCreate(String json, Type type)
      Generic-target variant of readCreate(String, Class). The caller ensures type denotes the returned value.

    • readCreate

      Object readCreate(InputStream json, Type type)
      Stream variant of readCreate(String, Type). The stream is not closed.

    • readMany

      <T> List<T> readMany(String json, Class<T> type)
      Reads a resource collection. Requires collection primary data; never coerces one resource, null, identifiers, or absent data into a collection.

    • readMany

      <T> List<T> readMany(InputStream json, Class<T> type)
      Stream variant of readMany(String, Class). The stream is not closed.

    • readMany

      List<Object> readMany(String json, Type type)
      Reads a resource collection using a full generic element type. The caller ensures type denotes the collection element type.

    • readMany

      List<Object> readMany(InputStream json, Type type)
      Stream variant of readMany(String, Type). The stream is not closed. The caller ensures type denotes the collection element type.

    • readOneDocument

      <T> ResourceDocument<T> readOneDocument(String json, Class<T> type)
      Reads one resource DTO together with top-level document state. Requires single-resource primary data.

    • readOneDocument

      <T> ResourceDocument<T> readOneDocument(InputStream json, Class<T> type)
      Stream variant of readOneDocument(String, Class). The stream is not closed.

    • readManyDocument

      <T> ResourceCollectionDocument<T> readManyDocument(String json, Class<T> type)
      Reads a resource collection together with top-level document state. Requires collection primary data.

    • readManyDocument

      <T> ResourceCollectionDocument<T> readManyDocument(InputStream json, Class<T> type)
      Stream variant of readManyDocument(String, Class). The stream is not closed.

    • writeOne

      String writeOne(Object resource)
      Writes one resource with default options and returns the JSON document.

    • writeOne

      String writeOne(Object resource, ResourceWriteOptions options)
      Writes one resource with the given options and returns the JSON document.

    • writeOne

      void writeOne(Object resource, OutputStream out)
      Writes one resource with default options to the given stream. The stream is not closed.

    • writeOne

      void writeOne(Object resource, ResourceWriteOptions options, OutputStream out)
      Writes one resource with the given options to the given stream. The stream is not closed.

    • writeMany

      String writeMany(Iterable<?> resources)
      Writes a resource collection with default options and returns the JSON document.

    • writeMany

      String writeMany(Iterable<?> resources, ResourceWriteOptions options)
      Writes a resource collection with the given options and returns the JSON document.

    • writeMany

      void writeMany(Iterable<?> resources, OutputStream out)
      Writes a resource collection with default options to the given stream. The stream is not closed.

    • writeMany

      void writeMany(Iterable<?> resources, ResourceWriteOptions options, OutputStream out)
      Writes a resource collection with the given options to the given stream. The stream is not closed.

    • writeCreateDocument

      String writeCreateDocument(Object resource)
      Authors a create-request document for one resource with default options and returns its JSON. Selects core CREATE_REQUEST validation.

    • writeCreateDocument

      String writeCreateDocument(Object resource, ResourceWriteOptions options)
      Authors a create-request document for one resource with the given options and returns its JSON. Selects core CREATE_REQUEST validation.

    • writeCreateDocument

      void writeCreateDocument(Object resource, OutputStream out)
      Authors a create-request document for one resource with default options to the given stream. The stream is not closed. Selects core CREATE_REQUEST validation.

    • writeCreateDocument

      void writeCreateDocument(Object resource, ResourceWriteOptions options, OutputStream out)
      Authors a create-request document for one resource with the given options to the given stream. The stream is not closed. Selects core CREATE_REQUEST validation.

    • writeUpdateDocument

      String writeUpdateDocument(Object resource, @Nullable com.kazforge.jsonapi.core.validation.EndpointIdentity expectedIdentity)
      Authors an update-request document for one resource with default options and returns its JSON. Selects core UPDATE_REQUEST validation. A null expectedIdentity disables the endpoint-identity comparison.

    • writeUpdateDocument

      String writeUpdateDocument(Object resource, @Nullable com.kazforge.jsonapi.core.validation.EndpointIdentity expectedIdentity, ResourceWriteOptions options)
      Authors an update-request document for one resource with the given options and returns its JSON. Selects core UPDATE_REQUEST validation. A null expectedIdentity disables the endpoint-identity comparison.

    • writeUpdateDocument

      void writeUpdateDocument(Object resource, @Nullable com.kazforge.jsonapi.core.validation.EndpointIdentity expectedIdentity, OutputStream out)
      Authors an update-request document for one resource with default options to the given stream. The stream is not closed. Selects core UPDATE_REQUEST validation. A null expectedIdentity disables the endpoint-identity comparison.

    • writeUpdateDocument

      void writeUpdateDocument(Object resource, @Nullable com.kazforge.jsonapi.core.validation.EndpointIdentity expectedIdentity, ResourceWriteOptions options, OutputStream out)
      Authors an update-request document for one resource with the given options to the given stream. The stream is not closed. Selects core UPDATE_REQUEST validation. A null expectedIdentity disables the endpoint-identity comparison.