Package org.dspace.app.rest.projection

Interface Projection

  • All Known Implementing Classes:
    AbstractProjection, DefaultProjection, FullProjection
    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:

    How a projection is chosen

    When a REST request is made, the projection argument, if present, is used to look up the projection to use, by name. If no argument is present, DefaultProjection will be used.

    • Field Summary

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

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      boolean allowEmbedding​(HALResource halResource, LinkRest linkRest)
      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.
      <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 halResource,
                       LinkRest linkRest)
        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.
        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) 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.