Package org.apache.juneau.bean.jsonapi

Class JsonApiDocument

java.lang.Object

org.apache.juneau.bean.jsonapi.JsonApiDocument

@Marshalled
public class JsonApiDocument
extends Object

Represents the top-level JSON:API document as defined by JSON:API v1.1 § Document Structure.

Carries the standard six top-level members: data, errors, meta, jsonapi, links, included.

Mutual exclusion

Per spec, a document MUST contain at least one of data/errors/meta, and data and errors MUST NOT coexist. The validate() helper checks both rules and throws IllegalStateException on violation.

The polymorphic data member

The top-level data can be null, a single JsonApiResource, or an array of them. We model data as a plain Object property; the writer chooses single-vs-array shape based on which value was set. Typed setters setData(JsonApiResource) and setData(List) are provided for convenience.

See Also:

• juneau-bean-jsonapi

Constructor Summary

Constructors

Constructor	Description
JsonApiDocument()	Default constructor.

Method Summary

Modifier and Type	Method	Description
JsonApiDocument	addErrors(Collection<JsonApiError> value)	Bean property appender: errors.
JsonApiDocument	addErrors(JsonApiError... value)	Bean property appender: errors.
JsonApiDocument	addIncluded(Collection<JsonApiResource> value)	Bean property appender: included.
JsonApiDocument	addIncluded(JsonApiResource... value)	Bean property appender: included.
Object	getData()	Bean property getter: data.
List<JsonApiError>	getErrors()	Bean property getter: errors.
List<JsonApiResource>	getIncluded()	Bean property getter: included.
JsonApiVersion	getJsonapi()	Bean property getter: jsonapi.
Map<String,Object>	getLinks()	Bean property getter: links.
Map<String,Object>	getMeta()	Bean property getter: meta.
JsonApiDocument	putLink(String name, Object value)	Convenience method to add a single link.
JsonApiDocument	putMeta(String name, Object value)	Convenience method to add a single meta entry.
JsonApiDocument	setData(Object value)	Bean property setter: data.
JsonApiDocument	setData(List<JsonApiResource> value)	Typed setter for to-many primary data.
JsonApiDocument	setData(JsonApiResource value)	Typed setter for single-resource primary data.
JsonApiDocument	setErrors(List<JsonApiError> value)	Bean property setter: errors.
JsonApiDocument	setErrors(JsonApiError... value)	Bean property setter: errors.
JsonApiDocument	setIncluded(List<JsonApiResource> value)	Bean property setter: included.
JsonApiDocument	setIncluded(JsonApiResource... value)	Bean property setter: included.
JsonApiDocument	setJsonapi(JsonApiVersion value)	Bean property setter: jsonapi.
JsonApiDocument	setLinks(Map<String,Object> value)	Bean property setter: links.
JsonApiDocument	setMeta(Map<String,Object> value)	Bean property setter: meta.
String	toString()
JsonApiDocument	validate()	Validates document-level invariants per the JSON:API spec.

Methods inherited from class java.lang.Object

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

Constructor Details

JsonApiDocument

public JsonApiDocument()

Default constructor.

Method Details

getData

public Object getData()

Bean property getter: data.

Top-level resource linkage. May be null, a single JsonApiResource, or a List<JsonApiResource>.

Returns:

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

setData

public JsonApiDocument setData(Object value)

Bean property setter: data.

Parameters:

value - The new value (single resource, list of resources, or null to unset).

Returns:

This object.

setData

public JsonApiDocument setData(JsonApiResource value)

Typed setter for single-resource primary data.

Parameters:

value - The resource. Can be null to unset the property.

Returns:

This object.

setData

public JsonApiDocument setData(List<JsonApiResource> value)

Typed setter for to-many primary data.

Parameters:

value - The list of resources. Can be null to unset the property.

Returns:

This object.

getErrors

public List<JsonApiError> getErrors()

Bean property getter: errors.

Returns:

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

setErrors

public JsonApiDocument setErrors(List<JsonApiError> value)

Bean property setter: errors.

Parameters:

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

Returns:

This object.

setErrors

public JsonApiDocument setErrors(JsonApiError... value)

Bean property setter: errors.

Parameters:

value - The new value for this property.

Returns:

This object.

addErrors

public JsonApiDocument addErrors(JsonApiError... value)

Bean property appender: errors.

Parameters:

value - The error objects to append.

Returns:

This object.

addErrors

public JsonApiDocument addErrors(Collection<JsonApiError> value)

Bean property appender: errors.

Parameters:

value - The error objects to append.

Returns:

This object.

getMeta

public Map<String,Object> getMeta()

Bean property getter: meta.

Returns:

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

setMeta

public JsonApiDocument setMeta(Map<String,Object> value)

Bean property setter: meta.

Parameters:

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

Returns:

This object.

putMeta

public JsonApiDocument putMeta(String name,
 Object value)

Convenience method to add a single meta entry.

Parameters:

name - The meta key. Can be null (LinkedHashMap tolerates a null key).

value - The meta value. Can be null (stored as null).

Returns:

This object.

getJsonapi

public JsonApiVersion getJsonapi()

Bean property getter: jsonapi.

Returns:

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

setJsonapi

public JsonApiDocument setJsonapi(JsonApiVersion value)

Bean property setter: jsonapi.

Parameters:

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

Returns:

This object.

getLinks

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

Bean property getter: links.

Per spec, each links value can be either a JSON string URL or a JsonApiLink object.

Returns:

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

setLinks

@BeanProp("links")
@Swap(JsonApiLinkOrStringSwap.class)
public JsonApiDocument setLinks(Map<String,Object> value)

Bean property setter: links.

Parameters:

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

Returns:

This object.

putLink

public JsonApiDocument putLink(String name,
 Object value)

Convenience method to add a single link.

Parameters:

name - The link name. Can be null (LinkedHashMap tolerates a null key).

value - The link value (a String URL or a JsonApiLink object). Can be null (stored as null).

Returns:

This object.

getIncluded

public List<JsonApiResource> getIncluded()

Bean property getter: included.

Returns:

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

setIncluded

public JsonApiDocument setIncluded(List<JsonApiResource> value)

Bean property setter: included.

Parameters:

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

Returns:

This object.

setIncluded

public JsonApiDocument setIncluded(JsonApiResource... value)

Bean property setter: included.

Parameters:

value - The new value for this property.

Returns:

This object.

addIncluded

public JsonApiDocument addIncluded(JsonApiResource... value)

Bean property appender: included.

Parameters:

value - The resource objects to append.

Returns:

This object.

addIncluded

public JsonApiDocument addIncluded(Collection<JsonApiResource> value)

Bean property appender: included.

Parameters:

value - The resource objects to append.

Returns:

This object.

validate

public JsonApiDocument validate()

Validates document-level invariants per the JSON:API spec.

Throws if data and errors are both present, or if none of data/errors/meta is present.

Returns:

This object.

Throws:

IllegalStateException - If the document violates a top-level invariant.

toString

public String toString()

Overrides:

toString in class Object