de.otto.edison.hal

Class Links.Builder

java.lang.Object

de.otto.edison.hal.Links.Builder

Enclosing class:

Links

public static class Links.Builder
extends java.lang.Object

A Builder used to build Links instances.

Since:

0.2.0

Constructor Summary

Constructors

Constructor and Description
Builder()

Method Summary

Modifier and Type	Method and Description
Links.Builder	array(Link link, Link... more) Adds one or more Links.
Links.Builder	array(java.util.List<Link> links) Adds a list of links to the builder that will be rendered as an array of link-objects Equivalent links are NOT added but silently ignored.
Links	build() Creates a Links instance from all added links.
Links.Builder	collection(java.lang.String href) Adds a single link with link-relation type 'collection' to the builder.
Links.Builder	curi(java.lang.String name, java.lang.String relTemplate) Adds a 'curies' link (compact URI) with name and a URI template for the link-relation type.
Links.Builder	item(java.lang.String href) Adds an 'item' link to the builder.
Links.Builder	replace(java.lang.String rel, java.util.List<Link> links) Replaces the link(s) currently associated with rel by a list of links to the builder that will be rendered as an array of link-objects.
Links.Builder	self(java.lang.String href) Adds a 'self' link and returns the Builder.
Links.Builder	single(Link link, Link... more) Adds one or more link to the builder that will be rendered as a single link-object instead of an array of link-objects.
Links.Builder	single(java.util.List<Link> singleLinkObjects) Adds a list of links to the builder that will be rendered as a single link-object instead of an array of link-objects.
Links.Builder	using(Curies curies)
Links.Builder	with(Links moreLinks) Adds all links from Links to the builder.
Links.Builder	without(java.lang.String rel) Removes registered links from the builder.

Methods inherited from class java.lang.Object

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

Constructor Detail

Builder

public Builder()

Method Detail

self

public Links.Builder self(java.lang.String href)

Adds a 'self' link and returns the Builder.

Using this method is equivalent to single(Link.self(href))

Parameters:

href - href of the linked resource

Returns:

Builder

Since:

2.0.0

See Also:

IANA link-relations

curi

public Links.Builder curi(java.lang.String name,
                          java.lang.String relTemplate)

Adds a 'curies' link (compact URI) with name and a URI template for the link-relation type.

Curies may be used for brevity for custom link-relation type URIs. Curies are established within a HAL document via a set of Link Objects with the relation type "curies" on the root Resource Object. These links contain a URI template with the token 'rel', and are named via the "name" property.

     {
       "_links": {
         "self": { "href": "/orders" },
         "curies": [{
           "name": "acme",
           "href": "http://docs.acme.com/relations/{rel}",
           "templated": true
         }],
         "acme:widgets": { "href": "/widgets" }
       }
     }
 

Using this method is equivalent to array(Link.curi(name, relTemplate))

Parameters:

name - the short name of the CURI

relTemplate - the template used to build link-relation types. Must contain a {rel} placeholder

Returns:

Link

Since:

2.0.0

See Also:

IANA link-relations, draft-kelly-json-hal-08#section-8.2

collection

public Links.Builder collection(java.lang.String href)

Adds a single link with link-relation type 'collection' to the builder.

If href is an URI template, the added link is templated.

Using this method is equivalent to single(Link.collection(href))

Parameters:

href - the linked collection resource

Returns:

this

Throws:

java.lang.IllegalStateException - if a collection link is already present

Since:

2.1.0

See Also:

IANA link-relations

item

public Links.Builder item(java.lang.String href)

Adds an 'item' link to the builder.

If href is an URI template, the added link is templated.

Links will be appended to already existing items, if the builder already has an array of item links.

Using this method is equivalent to array(Link.item(href))

Parameters:

href - the linked item

Returns:

this

Throws:

java.lang.IllegalStateException - if a single link with link-relation type item is already present

Since:

2.0.0

See Also:

IANA link-relations

single

public Links.Builder single(Link link,
                            Link... more)

Adds one or more link to the builder that will be rendered as a single link-object instead of an array of link-objects.

The links must have different Link-Relation Types, otherwise it would not be possible to render them as single link-objects. If two or more links have the same Link-Relation Type, an IllegalArgumentException is thrown.

Because curies must always be array links, it is not possible to add links with rel='curies' to the builder using single(Link, Link...) or single(List).

As specified in Section 4.1.1 of the HAL specification, the _links object "is an object whose property names are link relation types (as defined by [RFC5988]) and values are either a Link Object or an array of Link Objects".

Adding a link using single(Link) will result in a representation, where the link is rendered as a Link Object.

Calling single(Link) with a link-relation type that is already present, an IllegalStateException is thrown.

Parameters:

link - the added link. The Link-Relation Type of the link must not yet be added to the builder.

more - optionally more links having different Link-Relation Types

Returns:

this

Throws:

java.lang.IllegalStateException - if the Link-Relation Type of the link is already associated with another Link.

Since:

2.0.0

See Also:

IANA link-relations

single

public Links.Builder single(java.util.List<Link> singleLinkObjects)

Adds a list of links to the builder that will be rendered as a single link-object instead of an array of link-objects.

As specified in Section 4.1.1 of the HAL specification, the _links object "is an object whose property names are link relation types (as defined by [RFC5988]) and values are either a Link Object or an array of Link Objects".

Adding a link using single(Link) will result in a representation, where the link is rendered as a Link Object.

The List of links must not contain multiple links having the same link-relation type, otherwise an IllegalArgumentException is thrown.

Because curies must always be array links, it is not possible to add links with rel='curies' to the builder using single(Link, Link...) or single(List).

Calling single(List<Link>) with link-relation types that are already present, an IllegalStateException is thrown.

Parameters:

singleLinkObjects - the added link. The Link-Relation Type of the link must not yet be added to the builder.

Returns:

this

Throws:

java.lang.IllegalArgumentException - if the list contains multiple links having the same Link-Relation Type.

java.lang.IllegalStateException - if the Link-Relation Type of the link is already associated with another Link.

Since:

2.0.0

See Also:

IANA link-relations

array

public Links.Builder array(Link link,
                           Link... more)

Adds one or more Links.

Equivalent links are NOT added but silently ignored.

As specified in Section 4.1.1 of the HAL specification, the _links object "is an object whose property names are link relation types (as defined by [RFC5988]) and values are either a Link Object or an array of Link Objects".

Adding a link using array(Link, Link...) will result in a representation, where the links are rendered as an array of Link Objects, even if there are only single links for a given Link-Relation Type.

Parameters:

link - a Link

more - more links

Returns:

this

Since:

2.0.0

array

public Links.Builder array(java.util.List<Link> links)

Adds a list of links to the builder that will be rendered as an array of link-objects

Equivalent links are NOT added but silently ignored.

As specified in Section 4.1.1 of the HAL specification, the _links object "is an object whose property names are link relation types (as defined by [RFC5988]) and values are either a Link Object or an array of Link Objects".

Adding a link using array(List<Link>) will result in a representation, where the links are rendered as an array of Link Objects, even if there are only single links for a given Link-Relation Type.

Parameters:

links - the list of links.

Returns:

this

Since:

2.0.0

replace

public Links.Builder replace(java.lang.String rel,
                             java.util.List<Link> links)

Replaces the link(s) currently associated with rel by a list of links to the builder that will be rendered as an array of link-objects.

All links must have the Link-Relation Type specified in rel, otherwise an IllegalArgumentException is thrown.

As specified in Section 4.1.1 of the HAL specification, the _links object "is an object whose property names are link relation types (as defined by [RFC5988]) and values are either a Link Object or an array of Link Objects".

Replacing links using replace(List<Link>) will result in a representation, where the links are rendered as an array of Link Objects, even if there are only single links for a given Link-Relation Type.

Parameters:

rel - the Link-Relation Type that is replaced by the links

links - the list of links.

Returns:

this

Since:

2.0.0

with

public Links.Builder with(Links moreLinks)

Adds all links from Links to the builder.

Equivalent links are NOT added but silently ignored in order to avoid duplicate links.

Parameters:

moreLinks - the added links.

Returns:

this

Since:

2.0.0

without

public Links.Builder without(java.lang.String rel)

Removes registered links from the builder.

Parameters:

rel - Link-Relation Type of the links that should be removed.

Returns:

this

Since:

2.0.0

using

public Links.Builder using(Curies curies)

build

public Links build()

Creates a Links instance from all added links.

Returns:

Links