Package com.toedter.spring.hateoas.jsonapi

Class JsonApiModelBuilder

java.lang.Object
com.toedter.spring.hateoas.jsonapi.JsonApiModelBuilder
public class JsonApiModelBuilder extends Object
Builder API to create complex JSON:API representations exposing a JSON:API idiomatic API. It includes building JSON:API relationships and included.

  • Method Details

    • model

      public JsonApiModelBuilder model(org.springframework.hateoas.RepresentationModel<?> model)
      Sets the RepresentationModel as the base for the RepresentationModel to be built.

      NOTE: If the model is already set, an IllegalStateException will be thrown.

      Parameters:
      model - must not be null.
      Returns:
      will never be null.

    • model

      public JsonApiModelBuilder model(Object object)
      Creates an EntityModel from the object as the base for the RepresentationModel to be built.

      NOTE: If the model is already set, an IllegalStateException will be thrown.

      Parameters:
      object - must not be null.
      Returns:
      will never be null.

    • link

      public JsonApiModelBuilder link(org.springframework.hateoas.Link link)
      Adds a Link to the RepresentationModel to be built.

      NOTE: This adds it to the top level. If you need a link inside the model you added with model(RepresentationModel) method, add it directly to the model.

      Parameters:
      link - must not be null.
      Returns:
      will never be null.

    • link

      public JsonApiModelBuilder link(String href, org.springframework.hateoas.LinkRelation relation)
      Adds a Link with the given href and LinkRelation to the RepresentationModel to be built.
      Parameters:
      href - must not be null.
      relation - must not be null.
      Returns:
      will never be null.

    • links

      public JsonApiModelBuilder links(Iterable<org.springframework.hateoas.Link> links)
      Adds the given Links to the RepresentationModel to be built.
      Parameters:
      links - must not be null.
      Returns:
      will never be 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.

    • 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.