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 and Description
static interface	HalModelBuilder.PreviewBuilder

Method Summary

Modifier and Type	Method and Description
RepresentationModel<?>	build() Transform the entities and Links into a RepresentationModel.
HalModelBuilder	embed(Collection<?> collection)
HalModelBuilder	embed(Collection<?> collection, Class<?> type)
HalModelBuilder	embed(Collection<?> collection, LinkRelation relation) Embeds the given collection in the RepresentationModel for the given LinkRelation.
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.
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(Link link) Add a Link to the whole thing.
HalModelBuilder	link(String href, LinkRelation relation) Adds a Link with the given href and LinkRelation to the RepresentationModel to be built.
HalModelBuilder	links(Iterable<Link> links) Adds the given Links to the RepresentationModel to be built.
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.
HalModelBuilder.PreviewBuilder	preview(Object entity) Initiates the setup of a preview given the current payload.

Methods inherited from class java.lang.Object

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

Method Detail

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)

embed

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

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.

Parameters:

collection - must not be null.

relation - must not be null.

Returns:

will never be null.

See Also:

#embed(Collection, LinkRelation, Class)

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 EntityPreviewBuilder#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 Model.Builder 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 RepresentationModel<?> 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.