Package org.dspace.app.rest.projection

Interface Projection

All Known Implementing Classes:

AbstractProjection, CompositeProjection, DefaultProjection, EmbedRelsProjection, FullProjection, SpecificLevelProjection

public interface Projection

A pluggable, uniquely-named Component that provides a way to change how a domain object is represented, at one or more points in its lifecycle on the way to its being exposed via the REST API.

The object lifecycle

While fulfilling a typical REST request, a DSpace domain object takes three major forms, in order:

• A model object provided by some service. This is typically a JPA Entity.
• A RestModel object provided by a DSpaceRestRepository.
• A HALResource object provided by the RestController to Spring, which then serializes it as JSON for the client to consume.

What a projection can modify, and when

A Projection implementation is capable of adding to or omitting information from the object in any of these forms, at the following points in time:

• Before it is converted to a RestModel, the projection may modify it via transformModel(Object).
• After it is converted to a RestModel, the projection may modify it via transformRest(RestModel).
• During conversion to a HALResource, the projection may opt in to certain annotation-discovered HAL embeds and links via allowEmbedding(HALResource, LinkRest, Link...) and allowLinking(HALResource, LinkRest)
• After conversion to a HALResource, the projection may modify it via transformResource(HALResource).

How a projection is chosen

See Utils.obtainProjection().

Field Summary

Fields

Modifier and Type	Field	Description
static Projection	DEFAULT	The default projection.

Method Summary

Modifier and Type	Method	Description
boolean	allowEmbedding(HALResource<? extends RestAddressableModel> halResource, LinkRest linkRest, org.springframework.hateoas.Link... oldLinks)	Tells whether this projection permits the embedding of a particular embeddable subresource.
boolean	allowLinking(HALResource halResource, LinkRest linkRest)	Tells whether this projection permits the linking of a particular linkable subresource.
String	getName()	Gets the projection name.
org.springframework.data.domain.PageRequest	getPagingOptions(String rel, HALResource<? extends RestAddressableModel> resource, org.springframework.hateoas.Link... oldLinks)	This method will return the PageRequest object for a specific given rel
<T> T	transformModel(T modelObject)	Transforms the original model object (e.g.
<T extends HALResource> T	transformResource(T halResource)	Transforms the resource object after it has been constructed and any constructor or annotation-based links and embeds have been added.
<T extends RestModel> T	transformRest(T restObject)	Transforms the rest object after it was converted from a model object.

Field Detail

DEFAULT

static final Projection DEFAULT

The default projection.

Method Detail

getName

String getName()

Gets the projection name.

Returns:

the name, which is a unique alphanumeric string.

transformModel

<T> T transformModel(T modelObject)

Transforms the original model object (e.g. JPA entity) before conversion to a RestModel. This is a good place to omit data for certain properties that should not be included in the object's representation as a HALResource. Omitting these properties early helps to prevent unnecessary database calls for lazy-loaded properties that are unwanted for the projection.

Type Parameters:

T - the return type, which must be the same type as the given model object.

Parameters:

modelObject - the original model object, which may be of any type.

Returns:

the transformed model object, or the original, if the projection does not modify it.

transformRest

<T extends RestModel> T transformRest(T restObject)

Transforms the rest object after it was converted from a model object. This may add data to, or omit data from the rest representation of the object.

Type Parameters:

T - the return type, which must be of the same type as the given rest object.

Parameters:

restObject - the rest object.

Returns:

the transformed rest object, or the original, if the projection does not modify it.

transformResource

<T extends HALResource> T transformResource(T halResource)

Transforms the resource object after it has been constructed and any constructor or annotation-based links and embeds have been added. This may add data to, or omit data from the HAL resource representation of the object.

Type Parameters:

T - the return type, which must be of the same type as the given resource object.

Parameters:

halResource - the resource object.

Returns:

the transformed resource object, or the original, if the projection does not modify it.

allowEmbedding

boolean allowEmbedding(HALResource<? extends RestAddressableModel> halResource,
                       LinkRest linkRest,
                       org.springframework.hateoas.Link... oldLinks)

Tells whether this projection permits the embedding of a particular embeddable subresource. This gives the projection an opportunity to opt in to to certain embeds, by returning true. Note: If this method returns true for a given subresource, it will be automatically linked regardless of what allowLinking(HALResource, LinkRest) returns.

Parameters:

halResource - the resource from which the embed may or may not be made.

linkRest - the LinkRest annotation through which the related resource was discovered on the rest object.

oldLinks - The previously traversed links

Returns:

true if allowed, false otherwise.

allowLinking

boolean allowLinking(HALResource halResource,
                     LinkRest linkRest)

Tells whether this projection permits the linking of a particular linkable subresource. This gives the projection an opportunity to opt in to to certain links, by returning true. Note: If allowEmbedding(HALResource, LinkRest, Link...) returns true for a given subresource, it will be automatically linked regardless of what this method returns.

Parameters:

halResource - the resource from which the link may or may not be made.

linkRest - the LinkRest annotation through which the related resource was discovered on the rest object.

Returns:

true if allowed, false otherwise.

getPagingOptions

org.springframework.data.domain.PageRequest getPagingOptions(String rel,
                                                             HALResource<? extends RestAddressableModel> resource,
                                                             org.springframework.hateoas.Link... oldLinks)

This method will return the PageRequest object for a specific given rel

Parameters:

rel - The rel for which the PageRequest object will be made

resource - the resource from which the embed may or may not be made.

oldLinks - The previously traversed links

Returns:

The PageRequest object for the given rel