Package org.apache.juneau.bean.hal

Class HalResource

java.lang.Object

org.apache.juneau.bean.hal.HalResource

@Marshalled
public class HalResource
extends Object

Represents a HAL Resource Object as defined by draft-kelly-json-hal-08 § 4.

A HAL Resource carries three pieces of state:

• The reserved _links member - a map of relation name to either a single HalLink or a HalLinkArray.
• The reserved _embedded member - a map of relation name to either a single HalResource or a HalResourceArray (sub-resources). HAL embeddings are conceptually a tree; cyclic _embedded graphs are rejected by Juneau's BeanTraverseContext by default.
• Arbitrary payload fields, set via the dynamic set(String,Object) method (uses the @BeanProp("*") extra-properties triplet, the same pattern used by OpenApiElement and SwaggerElement).

Example:

HalResource order = new HalResource() .addLink("self", new HalLink().setHref("/orders/123")) .addLinks("curies", new HalLink().setName("acme").setHref("https://acme.example/{rel}").setTemplated(true)) .set("total", 99.50); String json = JsonSerializer.DEFAULT.write(order);

See Also:

• HAL Specification
• draft-kelly-json-hal-08
• juneau-bean-hal

Constructor Summary

Constructors

Constructor	Description
HalResource()	Default constructor.

Method Summary

Modifier and Type	Method	Description
HalResource	addEmbedded(String relation, HalResource value)	Convenience method that embeds a single sub-resource under the given relation.
HalResource	addEmbedded(String relation, HalResource... values)	Convenience method that appends one or more sub-resources to a HalResourceArray stored under relation.
HalResource	addLink(String relation, HalLink value)	Convenience method that adds a single link under the given relation.
HalResource	addLinks(String relation, HalLink... values)	Convenience method that appends one or more links to a HalLinkArray stored under relation.
Set<String>	extraKeys()	Generic property keyset.
Object	get(String property)	Generic property getter.
Map<String,Object>	getEmbedded()	Bean property getter: _embedded.
Map<String,Object>	getLinks()	Bean property getter: _links.
HalResource	set(String property, Object value)	Generic property setter.
HalResource	setEmbedded(Map<String,Object> value)	Bean property setter: _embedded.
HalResource	setLinks(Map<String,Object> value)	Bean property setter: _links.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Details

HalResource

public HalResource()

Default constructor.

Method Details

getLinks

@BeanProp("_links")
@Swap(HalLinkOrArraySwap.class)
public Map<String,Object> getLinks()

Bean property getter: _links.

The reserved _links member. Each map value is either a single HalLink (rendered as a JSON object on the wire) or a HalLinkArray (rendered as a JSON array).

Returns:

The value of the _links property, or null if it is not set.

setLinks

@BeanProp("_links")
@Swap(HalLinkOrArraySwap.class)
public HalResource setLinks(Map<String,Object> value)

Bean property setter: _links.

Parameters:

value - The new value for this property. Can be null to unset.

Returns:

This object.

addLink

public HalResource addLink(String relation,
 HalLink value)

Convenience method that adds a single link under the given relation.

If a value already exists for relation, it is replaced with the supplied single link. To accumulate multiple links under the same relation use addLinks(String, HalLink...) instead.

Parameters:

relation - The link relation (e.g. "self", "next", "curies"). Must not be null, or an IllegalArgumentException is thrown.

value - The link to set. Can be null (stored as a null entry under the relation).

Returns:

This object.

addLinks

public HalResource addLinks(String relation,
 HalLink... values)

Convenience method that appends one or more links to a HalLinkArray stored under relation.

If the current value at relation is a single HalLink, it is promoted to a HalLinkArray containing the original link and the appended ones.

Parameters:

relation - The link relation. Must not be null, or an IllegalArgumentException is thrown.

values - The links to append.

Returns:

This object.

getEmbedded

@BeanProp("_embedded")
@Swap(HalResourceOrArraySwap.class)
public Map<String,Object> getEmbedded()

Bean property getter: _embedded.

The reserved _embedded member. Each map value is either a single HalResource or a HalResourceArray.

Returns:

The value of the _embedded property, or null if it is not set.

setEmbedded

@BeanProp("_embedded")
@Swap(HalResourceOrArraySwap.class)
public HalResource setEmbedded(Map<String,Object> value)

Bean property setter: _embedded.

Note: HAL embeddings are conceptually a tree, not a graph. Juneau's BeanTraverseContext throws on cyclic references by default, which matches the spec.

Parameters:

value - The new value for this property. Can be null to unset.

Returns:

This object.

addEmbedded

public HalResource addEmbedded(String relation,
 HalResource value)

Convenience method that embeds a single sub-resource under the given relation.

Parameters:

relation - The relation name. Must not be null, or an IllegalArgumentException is thrown.

value - The sub-resource. Can be null (stored as a null entry under the relation).

Returns:

This object.

addEmbedded

public HalResource addEmbedded(String relation,
 HalResource... values)

Convenience method that appends one or more sub-resources to a HalResourceArray stored under relation.

Parameters:

relation - The relation name. Must not be null, or an IllegalArgumentException is thrown.

values - The sub-resources to append.

Returns:

This object.

extraKeys

@BeanProp("*")
public Set<String> extraKeys()

Generic property keyset.

Returns:

All the payload (non-_links, non-_embedded) property names on this resource. Never null.

get

@BeanProp("*")
public Object get(String property)

Generic property getter.

Parameters:

property - The property name. Must not be null, or an IllegalArgumentException is thrown.

Returns:

The property value, or null if the property is not set.

set

@BeanProp("*")
public HalResource set(String property,
 Object value)

Generic property setter.

Use this to set arbitrary payload fields alongside _links and _embedded.

Parameters:

property - The property name. Must not be null, or an IllegalArgumentException is thrown.

value - The new value for the property. Can be null (stored as null).

Returns:

This object.

toString

public String toString()

Overrides:

toString in class Object