Package org.springframework.hateoas.mediatype.hal

Class HalModelBuilder

java.lang.Object

org.springframework.hateoas.mediatype.hal.HalModelBuilder

public class HalModelBuilder
extends Object

Builder API to create complex HAL representations exposing a HAL idiomatic API. It's built around the notion of a the representation consisting of an optional primary entity and e set of embeds. There's also explicit API for common HAL patterns like previews contained in _embedded for links present in the representation.

Since:

1.1

Author:

Greg Turnquist, Oliver Drotbohm

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	HalModelBuilder.PreviewBuilder

Method Summary

Modifier and Type	Method	Description
<T extends RepresentationModel<T>> RepresentationModel<T>	build()	Transform the entities and Links into a RepresentationModel.
HalModelBuilder	embed(Object entity)	Embeds the given entity into the RepresentationModel.
HalModelBuilder	embed(Object entity, LinkRelation linkRelation)	Embed the entity and associate it with the LinkRelation.
HalModelBuilder	embed(Collection<?> collection)	Embeds the given collection in the RepresentationModel.
HalModelBuilder	embed(Collection<?> collection, Class<?> type)	Embeds the given collection in the RepresentationModel and the LinkRelation derived from the given type.
HalModelBuilder	embed(Collection<?> collection, LinkRelation relation)	Embeds the given collection in the RepresentationModel for the given LinkRelation.
HalModelBuilder	embed(Stream<?> stream)	Embeds the given Stream in the RepresentationModel.
HalModelBuilder	embed(Stream<?> stream, Class<?> type)	Embeds the given Stream in the RepresentationModel and the LinkRelation derived from the given type.
HalModelBuilder	embed(Stream<?> stream, LinkRelation relation)	Embeds the given Stream in the RepresentationModel for the given LinkRelation.
static HalModelBuilder	emptyHalModel()	Creates a new HalModelBuilder without a primary payload.
HalModelBuilder	entity(Object entity)	Embed the entity, but with no relation.
static HalModelBuilder	halModel()	Creates a new HalModelBuilder.
static HalModelBuilder	halModel(EmbeddedWrappers wrappers)	Creates a new HalModelBuilder using the given EmbeddedWrappers.
static HalModelBuilder	halModelOf(Object entity)	Creates a new HalModelBuilder with the given entity as primary payload.
HalModelBuilder	link(String href, LinkRelation relation)	Adds a Link with the given href and LinkRelation to the RepresentationModel to be built.
HalModelBuilder	link(Link link)	Add a Link to the whole thing.
HalModelBuilder	links(Iterable<Link> links)	Adds the given Links to the RepresentationModel to be built.
HalModelBuilder.PreviewBuilder	preview(Object entity)	Initiates the setup of a preview given the current payload.
HalModelBuilder.PreviewBuilder	preview(Collection<?> collection)	Starts a preview setup for the given Collection as preview.
HalModelBuilder.PreviewBuilder	preview(Collection<?> collection, Class<?> type)	Starts a preview setup for the given Collection as preview falling back to the given type if the Collection is empty.

Methods inherited from class java.lang.Object

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

Method Details

halModel

public static HalModelBuilder halModel()

Creates a new HalModelBuilder.

Returns:

will never be null.

halModel

public static HalModelBuilder halModel(EmbeddedWrappers wrappers)

Creates a new HalModelBuilder using the given EmbeddedWrappers.

Parameters:

wrappers - must not be null.

Returns:

will never be null.

halModelOf

public static HalModelBuilder halModelOf(Object entity)

Creates a new HalModelBuilder with the given entity as primary payload.

Parameters:

entity - must not be null.

Returns:

emptyHalModel

public static HalModelBuilder emptyHalModel()

Creates a new HalModelBuilder without a primary payload.

Returns:

entity

public HalModelBuilder entity(Object entity)

Embed the entity, but with no relation.

Parameters:

entity -

Returns:

embed

public HalModelBuilder embed(Object entity,
 LinkRelation linkRelation)

Embed the entity and associate it with the LinkRelation.

Parameters:

entity - must not be null.

linkRelation - must not be null.

Returns:

will never be null.

embed

public HalModelBuilder embed(Object entity)

Embeds the given entity into the RepresentationModel.

Parameters:

entity - must not be null.

Returns:

will never be null.

embed

public HalModelBuilder embed(Collection<?> collection)

Embeds the given collection in the RepresentationModel. If the collection is empty nothing will be added to the RepresentationModel.

Parameters:

collection - must not be null.

Returns:

will never be null.

embed

public HalModelBuilder embed(Collection<?> collection,
 Class<?> type)

Embeds the given collection in the RepresentationModel and the LinkRelation derived from the given type. If the collection is empty nothing will be added to the RepresentationModel an empty embed for the derived LinkRelation will be added.

Parameters:

collection - must not be null.

type - the type to derive the LinkRelation to be used, must not be null.

Returns:

will never be null.

See Also:

• embed(Collection, LinkRelation)

embed

public HalModelBuilder embed(Collection<?> collection,
 LinkRelation relation)

Embeds the given collection in the RepresentationModel for the given LinkRelation. If the collection is empty nothing will be added to the RepresentationModel an empty embed for the derived LinkRelation will be added.

Parameters:

collection - must not be null.

relation - must not be null.

Returns:

will never be null.

embed

public HalModelBuilder embed(Stream<?> stream)

Embeds the given Stream in the RepresentationModel. The given Stream will be resolved immediately, i.e. the method acts as mere syntactic sugar to avoid clients having to collect the Stream into a Collection beforehand. If the Stream is empty nothing will be added to the RepresentationModel.

Parameters:

stream - must not be null.

Returns:

will never be null.

embed

public HalModelBuilder embed(Stream<?> stream,
 Class<?> type)

Embeds the given Stream in the RepresentationModel and the LinkRelation derived from the given type. The given Stream will be resolved immediately, i.e. the method acts as mere syntactic sugar to avoid clients having to collect the Stream into a Collection beforehand. If the Stream is empty nothing will be added to the RepresentationModel an empty embed for the derived LinkRelation will be added.

Parameters:

stream - must not be null.

type - the type to derive the LinkRelation to be used, must not be null.

Returns:

will never be null.

See Also:

• embed(Collection, LinkRelation)

embed

public HalModelBuilder embed(Stream<?> stream,
 LinkRelation relation)

Embeds the given Stream in the RepresentationModel for the given LinkRelation. The given Stream will be resolved immediately, i.e. the method acts as mere syntactic sugar to avoid clients having to collect the Stream into a Collection beforehand. If the Stream is empty nothing will be added to the RepresentationModel an empty embed for the derived LinkRelation will be added.

Parameters:

stream - must not be null.

relation - must not be null.

Returns:

will never be null.

preview

public HalModelBuilder.PreviewBuilder preview(Object entity)

Initiates the setup of a preview given the current payload. Clients have to conclude the setup calling any of the HalModelBuilder.PreviewBuilder.forLink(Link) methods. As an example, the call chain of:

 ….preview(…).forLink("…", "relation")
 

will result in the link added to the representation and an embedded being registered for the link's relation:

 {
   "_links" : {
     "relation" : { … }
   },
   "_embedded" : {
     "relation" : …
   }
 }
 

Parameters:

entity -

Returns:

will never be null.

preview

public HalModelBuilder.PreviewBuilder preview(Collection<?> collection)

Starts a preview setup for the given Collection as preview.

Parameters:

collection -

Returns:

will never be null.

See Also:

• preview(Object)

preview

public HalModelBuilder.PreviewBuilder preview(Collection<?> collection,
 Class<?> type)

Starts a preview setup for the given Collection as preview falling back to the given type if the Collection is empty.

Parameters:

collection - must not be null.

type - must not be null.

Returns:

will never be null.

See Also:

• preview(Object)

link

public HalModelBuilder link(Link link)

Add a Link to the whole thing.

NOTE: This adds it to the top level. If you need a link inside an entity, then use the HalModelBuilder to define it as well.

Parameters:

link - must not be null.

Returns:

will never be null.

link

public HalModelBuilder link(String href,
 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 HalModelBuilder links(Iterable<Link> links)

Adds the given Links to the RepresentationModel to be built.

Parameters:

links - must not be null.

Returns:

will never be null.

build

public <T extends RepresentationModel<T>>
RepresentationModel<T> build()

Transform the entities and Links into a RepresentationModel. If there are embedded entries, add a preferred media type of MediaTypes.HAL_JSON and MediaTypes.HAL_FORMS_JSON.

Returns:

will never be null.