Package com.toedter.spring.hateoas.jsonapi

Class JsonApiModelBuilder

java.lang.Object
com.toedter.spring.hateoas.jsonapi.JsonApiModelBuilder
public class JsonApiModelBuilder extends Object
Fluent builder API for creating complex JSON:API representations with relationships and included resources.

This builder provides a type-safe, idiomatic way to construct JSON:API documents including:

  • Primary data (single resources or collections)
  • Relationships between resources
  • Included resources for compound documents
  • Links at document and resource levels
  • Meta information
  • Sparse fieldsets for attribute filtering
  • Pagination metadata

The builder ensures compliance with the JSON:API specification and integrates seamlessly with Spring HATEOAS representation models.

Example usage: 


 JsonApiModel jsonApiModel = JsonApiModelBuilder.jsonApiModel()
   .model(EntityModel.of(movie))
   .relationship("directors", directors)
   .included(directors)
   .build();
See Also:

  • Method Details

    • model

      public JsonApiModelBuilder model(org.springframework.hateoas.RepresentationModel<?> model)
      Sets the RepresentationModel as the primary data for the JSON:API document to be built.

      The model can be an EntityModel, CollectionModel, or PagedModel. This forms the main content of the JSON:API data field.

      Note: If a model is already set, an IllegalStateException will be thrown to prevent accidental overwriting.

      Parameters:
      model - the representation model to use as primary data; must not be null
      Returns:
      this builder instance for method chaining; will never be null
      Throws:
      IllegalArgumentException - if model is null
      IllegalStateException - if a model has already been set on this builder

    • model

      public JsonApiModelBuilder model(Object object)
      Creates an EntityModel from the given object as the primary data for the JSON:API document.

      This is a convenience method that automatically wraps the object in an EntityModel before setting it as the model. Equivalent to calling model(EntityModel.of(object)).

      Note: If a model is already set, an IllegalStateException will be thrown.

      Parameters:
      object - the object to wrap in an EntityModel; must not be null
      Returns:
      this builder instance for method chaining; will never be null
      Throws:
      IllegalArgumentException - if object is null
      IllegalStateException - if a model has already been set on this builder

    • link

      public JsonApiModelBuilder link(org.springframework.hateoas.Link link)
      Adds a Link to the top level of the JSON:API document.

      This link will be rendered in the document-level links object, not inside the resource object itself. If you need to add a link to the resource, add it directly to the model passed to model(RepresentationModel).

      Parameters:
      link - the link to add; must not be null
      Returns:
      this builder instance for method chaining; will never be null
      Throws:
      IllegalArgumentException - if link is null

    • link

      public JsonApiModelBuilder link(String href, org.springframework.hateoas.LinkRelation relation)
      Adds a Link with the given href and LinkRelation to the top level of the JSON:API document.

      This is a convenience method equivalent to link(Link.of(href, relation)).

      Parameters:
      href - the link href; must not be null
      relation - the link relation; must not be null
      Returns:
      this builder instance for method chaining; will never be null
      Throws:
      IllegalArgumentException - if href or relation is null

    • links

      public JsonApiModelBuilder links(Iterable<org.springframework.hateoas.Link> links)
      Adds multiple Links to the top level of the JSON:API document.
      Parameters:
      links - the links to add; must not be null
      Returns:
      this builder instance for method chaining; will never be null
      Throws:
      IllegalArgumentException - if links is null

    • relationship

      public JsonApiModelBuilder relationship(String name, @Nullable Object dataObject)
      Adds or updates a relationship based on the Object. It must be possible to extract the JSON:API id of this object, see reference doc. If there is already a relationship for the given name defined, the new data object will be added to the existing relationship. If the dataObject is null, an empty to-one relationship is created, see JSON:API doc.
      Parameters:
      name - must not be null.
      dataObject - must not be null.
      Returns:
      will never be null.

    • relationship

      public JsonApiModelBuilder relationship(String name, Collection<?> collection)
      Adds or updates a relationship based on the Collection. It must be possible to extract the JSON:API id of all elements of this collection, see reference doc. If there is already a relationship for the given name defined, the elements of the collection will be added to the existing relationship.
      Parameters:
      name - must not be null.
      collection - must not be null.
      Returns:
      will never be null.

    • relationship

      public JsonApiModelBuilder relationship(String name, org.springframework.hateoas.EntityModel<?> entityModel)
      Adds or updates a relationship based on the given EntityModel to the RepresentationModel to be built. If there is already a relationship for the given name defined, the new EntityModel will be added to the existing relationship.
      Parameters:
      name - must not be null.
      entityModel - must not be null.
      Returns:
      will never be null.

    • relationship

      public JsonApiModelBuilder relationship(String name, @Nullable org.springframework.hateoas.EntityModel<?> entityModel, @Nullable String selfLink, @Nullable String relatedLink)
      Adds or updates a relationship based on the given EntityModel and links. A self link of the relation and a related link (to the related resource) can also be added. While entityModel, selfLink, and relatedLink can be null, at least one of them has to be not null.
      Parameters:
      name - must not be null.
      entityModel - can be null.
      selfLink - can be null.
      relatedLink - can be null.
      Returns:
      will never be null.

    • relationship

      public JsonApiModelBuilder relationship(String name, Map<String,Object> meta)
      Adds or updates a relationship based on the meta to the RepresentationModel to be built. If there is already a relationship for the given name defined, the meta will overwrite the existing relationship.
      Parameters:
      name - must not be null.
      meta - must not be null.
      Returns:
      will never be null.

    • relationship

      public JsonApiModelBuilder relationship(String name, Object dataObject, Map<String,Object> resourceIdentifierMeta)
      Adds or updates a relationship based on the meta to the RepresentationModel to be built. If there is already a relationship for the given name defined, the meta will overwrite the existing relationship.
      Parameters:
      name - must not be null.
      dataObject - must not be null.
      resourceIdentifierMeta - can be null.
      Returns:
      will never be null.

    • relationship

      public JsonApiModelBuilder relationship(String name, @Nullable String selfLink, @Nullable String relatedLink, @Nullable org.springframework.hateoas.Links otherLinks)
      Adds or updates a relationship based on the links to the RepresentationModel to be built. If there is already a relationship for the given name defined, the new links will overwrite the existing ones.
      Parameters:
      name - must not be null.
      selfLink - can be null.
      relatedLink - can be null.
      otherLinks - can be null.
      Returns:
      will never be null.

    • relationshipWithDataArray

      public JsonApiModelBuilder relationshipWithDataArray(String name)
      If called (anywhere in the builder sequence), the data portion of this relationship will always be rendered as an array, even if the data is not set or is one single element, e.g. "data": [] or "data" : [{"id":"1", "type":"movies"}]. This is convenient if the consumer always expects a (one to many) relationship to be rendered as an array rather than having to check for null values or single objects.
      Parameters:
      name - must not be null.
      Returns:
      will never be null.

    • relationshipWithNullData

      public JsonApiModelBuilder relationshipWithNullData(String name)
      Adds or updates a relationship with explicit null data. This will be serialized as "data": null in JSON:API format, representing an empty to-one relationship as per the JSON:API specification. If there is already a relationship for the given name defined, the data will be replaced with null while preserving links and meta.
      Parameters:
      name - must not be null.
      Returns:
      will never be null.

    • relationshipWithEmptyData

      public JsonApiModelBuilder relationshipWithEmptyData(String name)
      Adds or updates a relationship with explicit empty array data. This will be serialized as "data": [] in JSON:API format, representing an empty to-many relationship as per the JSON:API specification. If there is already a relationship for the given name defined, the data will be replaced with an empty array while preserving links and meta.
      Parameters:
      name - must not be null.
      Returns:
      will never be null.

    • included

      public JsonApiModelBuilder included(org.springframework.hateoas.RepresentationModel<?> representationModel)
      Adds the given RepresentationModel to the included RepresentationModels. It will appear then top level in the JSON:API included entities. Duplicates with same id and type will be eliminated.
      Parameters:
      representationModel - must not be null.
      Returns:
      will never be null.

    • included

      public JsonApiModelBuilder included(Object object)
      Adds the given Object to the included RepresentationModels. The object is automatically wrapped into an EntityModel. It will appear then top level in the JSON:API included entities. Duplicates with same id and type will be eliminated.
      Parameters:
      object - must not be null.
      Returns:
      will never be null.

    • included

      public JsonApiModelBuilder included(Collection<?> collection)
      Adds the given Collection to the included RepresentationModels. The objects of the collection are automatically wrapped into an EntityModel, if they are not already RepresentationModels. The members of the collection will appear then top level in the JSON:API included entities. Duplicates with same id and type will be eliminated.
      Parameters:
      collection - must not be null.
      Returns:
      will never be null.

    • meta

      public JsonApiModelBuilder meta(String key, Object value)
      Adds the given key/value pair to the JSON:API meta.
      Parameters:
      key - the json key
      value - the json value
      Returns:
      will never be null.

    • pageMeta

      public JsonApiModelBuilder pageMeta()
      Adds the paging information to the JSON:API meta. Preconditions are: - the model has been added before - the model is a paged model - the model contains a Pageable
      Returns:
      will never be null.

    • pageLinks

      public JsonApiModelBuilder pageLinks(String linkBase)
      Creates all pagination links with JSON:API default request parameters for page number page[number] and page size page[size].

      Preconditions are:

      • the model has been added before
      • the model is a PagedModel
      • the model contains PageMetadata
      Parameters:
      linkBase - the prefix of all pagination links, e.g. the base URL of the collection resource
      Returns:
      will never be null.

    • pageLinks

      public JsonApiModelBuilder pageLinks(String linkBase, String pageNumberRequestParam, String pageSizeRequestParam)
      Creates all pagination links.

      Preconditions are:

      • the model has been added before
      • the model is a PagedModel
      • the model contains PageMetadata
      Parameters:
      linkBase - the prefix of all pagination links, e.g. the base URL of the collection resource
      pageNumberRequestParam - the request parameter for page number
      pageSizeRequestParam - the request parameter for page size
      Returns:
      will never be null.

    • fields

      public JsonApiModelBuilder fields(String jsonapiType, String... fields)
      Adds a sparse fieldset for the given JSON:API type. Only the resource objects attributes that are in the fields parameters will be serialized to JSON. THis will apply to data attributes and attributes of included resources. This will not exclude relationships, if the name of a relationship for the given JSON:API type is not part of the fields parameters.
      Parameters:
      jsonapiType - the JSON:API type
      fields - the attributes that should be included
      Returns:
      ill never be null.

    • build

      public org.springframework.hateoas.RepresentationModel<?> build()
      Transform the entities, Links, relationships and included into a RepresentationModel.
      Returns:
      will never be null.

    • jsonApiModel

      public static JsonApiModelBuilder jsonApiModel()
      Creates a new JsonApiModelBuilder.
      Returns:
      will never be null.