Package com.toedter.spring.hateoas.jsonapi

Class JsonApiModelBuilder

java.lang.Object

com.toedter.spring.hateoas.jsonapi.JsonApiModelBuilder

public class JsonApiModelBuilder
extends java.lang.Object

Builder API to create complex JSON:API representations exposing a JSON:API idiomatic API. It includes building JSON:API relationships and included.

Method Summary

Modifier and Type	Method	Description
org.springframework.hateoas.RepresentationModel<?>	build()	Transform the entities, Links, relationships and included into a RepresentationModel.
JsonApiModelBuilder	fields(java.lang.String jsonapiType, java.lang.String... fields)	Adds a sparse fieldset for the given JSON:API type.
JsonApiModelBuilder	included(java.lang.Object object)	Adds the given Object to the included RepresentationModels.
JsonApiModelBuilder	included(java.util.Collection<?> collection)	Adds the given Collection to the included RepresentationModels.
JsonApiModelBuilder	included(org.springframework.hateoas.RepresentationModel<?> representationModel)	Adds the given RepresentationModel to the included RepresentationModels.
static JsonApiModelBuilder	jsonApiModel()	Creates a new JsonApiModelBuilder.
JsonApiModelBuilder	link(java.lang.String href, org.springframework.hateoas.LinkRelation relation)	Adds a Link with the given href and LinkRelation to the RepresentationModel to be built.
JsonApiModelBuilder	link(org.springframework.hateoas.Link link)	Adds a Link to the RepresentationModel to be built.
JsonApiModelBuilder	links(java.lang.Iterable<org.springframework.hateoas.Link> links)	Adds the given Links to the RepresentationModel to be built.
JsonApiModelBuilder	meta(java.lang.String key, java.lang.Object value)	Adds the given key/value pair to the JSON:API meta.
JsonApiModelBuilder	model(java.lang.Object object)	Creates an EntityModel from the object as the base for the RepresentationModel to be built.
JsonApiModelBuilder	model(org.springframework.hateoas.RepresentationModel<?> model)	Sets the RepresentationModel as the base for the RepresentationModel to be built.
JsonApiModelBuilder	pageLinks(java.lang.String linkBase)	Creates all pagination links with JSON:API default request parameters for page number page[number] and page size page[size].
JsonApiModelBuilder	pageLinks(java.lang.String linkBase, java.lang.String pageNumberRequestParam, java.lang.String pageSizeRequestParam)	Creates all pagination links.
JsonApiModelBuilder	pageMeta()	Adds the paging information to the JSON:API meta.
JsonApiModelBuilder	relationship(java.lang.String name, java.lang.Object dataObject)	Adds or updates a relationship based on the Object.
JsonApiModelBuilder	relationship(java.lang.String name, java.lang.Object dataObject, java.util.Map<java.lang.String,java.lang.Object> resourceIdentifierMeta)	Adds or updates a relationship based on the meta to the RepresentationModel to be built.
JsonApiModelBuilder	relationship(java.lang.String name, java.lang.String selfLink, java.lang.String relatedLink, org.springframework.hateoas.Links otherLinks)	Adds or updates a relationship based on the links to the RepresentationModel to be built.
JsonApiModelBuilder	relationship(java.lang.String name, java.util.Collection<?> collection)	Adds or updates a relationship based on the Collection.
JsonApiModelBuilder	relationship(java.lang.String name, java.util.Map<java.lang.String,java.lang.Object> meta)	Adds or updates a relationship based on the meta to the RepresentationModel to be built.
JsonApiModelBuilder	relationship(java.lang.String name, org.springframework.hateoas.EntityModel<?> entityModel)	Adds or updates a relationship based on the given EntityModel to the RepresentationModel to be built.
JsonApiModelBuilder	relationship(java.lang.String name, org.springframework.hateoas.EntityModel<?> entityModel, java.lang.String selfLink, java.lang.String relatedLink)	Adds or updates a relationship based on the given EntityModel and links.
JsonApiModelBuilder	relationshipWithDataArray(java.lang.String name)	If called (anywhere in the builder sequence), the data portion of this relationship will be always rendered as an array, even if the data is not set or is one single element, e.g.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

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(java.lang.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(java.lang.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(java.lang.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(java.lang.String name,
                                        java.lang.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 https://toedter.github.io/spring-hateoas-jsonapi/#_annotations. If there is already a relationship for the given name defined, the new data object will be added to the existing relationship.

Parameters:

name - must not be null.

dataObject - must not be null.

Returns:

will never be null.

relationship

public JsonApiModelBuilder relationship(java.lang.String name,
                                        java.util.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 https://toedter.github.io/spring-hateoas-jsonapi/#_annotations. 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(java.lang.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(java.lang.String name,
                                        @Nullable
                                        org.springframework.hateoas.EntityModel<?> entityModel,
                                        @Nullable
                                        java.lang.String selfLink,
                                        @Nullable
                                        java.lang.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(java.lang.String name,
                                        java.util.Map<java.lang.String,java.lang.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(java.lang.String name,
                                        java.lang.Object dataObject,
                                        java.util.Map<java.lang.String,java.lang.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(java.lang.String name,
                                        @Nullable
                                        java.lang.String selfLink,
                                        @Nullable
                                        java.lang.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(java.lang.String name)

If called (anywhere in the builder sequence), the data portion of this relationship will be always 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(java.lang.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(java.util.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(java.lang.String key,
                                java.lang.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(java.lang.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(java.lang.String linkBase,
                                     java.lang.String pageNumberRequestParam,
                                     java.lang.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(java.lang.String jsonapiType,
                                  java.lang.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.