Module org.refcodes.hal
Package org.refcodes.hal

Interface HalClient

All Superinterfaces:
org.refcodes.web.OauthTokenAccessor, org.refcodes.web.OauthTokenAccessor.OauthTokenBuilder<HalClient>, org.refcodes.web.OauthTokenAccessor.OauthTokenMutator, org.refcodes.web.OauthTokenAccessor.OauthTokenProperty
All Known Implementing Classes:
HalClientImpl
public interface HalClient extends org.refcodes.web.OauthTokenAccessor.OauthTokenProperty, org.refcodes.web.OauthTokenAccessor.OauthTokenBuilder<HalClient>
The HalClient lets you comfortably introspect and manage (in terms of CRUD) HAL resources. You may use it reflect the data structures of entities accessible by remote HAL endpoints as well as apply CRUD operations on the introspected entities. This means that you interact completely dynamically with the HAL resource at runtime instead of having to provide static data structures at compile time. Still you may go wit static data types as we use the CanonicalMap (as well as the CanonicalMap.CanonicalMapBuilder) to operate upon the dynamic data structures. Implementations may use the HttpRestServer and it's implementations such as the HttpRestServerImpl. See also "https://en.wikipedia.org/wiki/Hypertext_Application_Language".

  • Nested Class Summary

    Nested classes/interfaces inherited from interface org.refcodes.web.OauthTokenAccessor

    org.refcodes.web.OauthTokenAccessor.OauthTokenBuilder<B extends org.refcodes.web.OauthTokenAccessor.OauthTokenBuilder<B>>, org.refcodes.web.OauthTokenAccessor.OauthTokenMutator, org.refcodes.web.OauthTokenAccessor.OauthTokenProperty

  • Method Summary

    Modifier and Type
    Method
    Description
    default HalData
    create(String aEntity, Object aObj)
    Creates a new entitie's element (row) at the HAL resource consisting of the properties as of the provided CanonicalMap.
    HalData
    create(String aEntity, HalData aProperties)
    Creates a new entitie's element (row) at the HAL resource consisting of the properties as of the provided CanonicalMap.
    boolean
    delete(String aEntity, String aId)
    Deletes an entitie's element (row) from the HAL resource.
    String[]
    entities()
    Determines the entities provided by the HAL resource.
    String[]
    getExcludeEntities()
    Gets the names of the entities to be excluded by the HalClient.
    String[]
    getIncludeEntities()
    Gets the names of the entities to be included by the HalClient.
    default HalStruct
    introspect(String aEntity)
    Introspects the provided entity at the HAL resource and returns an instance of the CanonicalMap representing the reflected data structure.
    HalStruct
    introspect(String aEntity, TraversalMode aMode)
    Introspects the provided entity at the HAL resource and returns an instance of the CanonicalMap representing the reflected data structure.
    default HalData
    read(String aEntity, Long aId)
    Retrieves the properties with the according values for the given entity with the given TID from the HAL resource.
    default HalData
    read(String aEntity, Long aId, TraversalMode aMode)
    Retrieves the properties with the according values for the given entity with the given TID from the HAL resource.
    HalData
    read(String aEntity, Long aId, TraversalMode aMode, org.refcodes.web.FormFields aQueryFields)
    Retrieves the properties with the according values for the given entity with the given TID from the HAL resource.
    default HalData
    read(String aEntity, Long aId, org.refcodes.web.FormFields aQueryFields)
    Retrieves the properties with the according values for the given entity with the given TID from the HAL resource.
    default HalDataPage
    readAll(String aEntity)
    Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource.
    default HalDataPage
    readAll(String aEntity, TraversalMode aMode)
    Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource.
    HalDataPage
    readAll(String aEntity, TraversalMode aMode, org.refcodes.web.FormFields aQueryFields)
    Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource.
    default HalDataPage
    readAll(String aEntity, org.refcodes.web.FormFields aQueryFields)
    Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource.
    default HalDataPage
    readPage(String aEntity, int aPage, int aPageSize)
    Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource.
    default HalDataPage
    readPage(String aEntity, int aPage, int aPageSize, TraversalMode aMode)
    Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource.
    default HalDataPage
    readPage(String aEntity, int aPage, int aPageSize, TraversalMode aMode, org.refcodes.web.FormFields aQueryFields)
    Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource.
    default HalDataPage
    readPage(String aEntity, int aPage, int aPageSize, org.refcodes.web.FormFields aQueryFields)
    Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource.
    void
    setExcludeEntities(String[] entities)
    Sets the names of the entities to be excluded by the HalClient.
    void
    setIncludeEntities(String[] entities)
    Sets the names of the entities to be included by the HalClient.
    default HalData
    update(String aEntity, Object aObj)
    Creates a new entitie's element (row) at the HAL resource consisting of the properties as of the provided CanonicalMap.
    HalData
    update(String aEntity, String aId, HalData aProperties)
    Updates an existing entitie's element (row) at the HAL resource using the properties as of the provided CanonicalMap.
    default HalClient
    withExcludeEntities(String[] entities)
    Sets the names of the entities to be excluded by the HalClient.
    default HalClient
    withIncludeEntities(String[] entities)
    Sets the names of the entities to be included by the HalClient.
    default HalClient
    withOAuthToken(org.refcodes.web.OauthToken aOauthToken)

    Methods inherited from interface org.refcodes.web.OauthTokenAccessor

    getOauthToken

    Methods inherited from interface org.refcodes.web.OauthTokenAccessor.OauthTokenMutator

    setOauthToken

    Methods inherited from interface org.refcodes.web.OauthTokenAccessor.OauthTokenProperty

    letOauthToken

  • Method Details

    • withOAuthToken

      default HalClient withOAuthToken(org.refcodes.web.OauthToken aOauthToken)
      Specified by:
      withOAuthToken in interface org.refcodes.web.OauthTokenAccessor.OauthTokenBuilder<HalClient>

    • getExcludeEntities

      String[] getExcludeEntities()
      Gets the names of the entities to be excluded by the HalClient.
      Returns:
      The entities to be excluded.

    • setExcludeEntities

      void setExcludeEntities(String[] entities)
      Sets the names of the entities to be excluded by the HalClient.
      Parameters:
      entities - The entities to be excluded.

    • withExcludeEntities

      default HalClient withExcludeEntities(String[] entities)
      Sets the names of the entities to be excluded by the HalClient.
      Parameters:
      entities - The entities to be excluded.
      Returns:
      This instance ass of the builder pattern.

    • getIncludeEntities

      String[] getIncludeEntities()
      Gets the names of the entities to be included by the HalClient.
      Returns:
      The entities to be included.

    • setIncludeEntities

      void setIncludeEntities(String[] entities)
      Sets the names of the entities to be included by the HalClient.
      Parameters:
      entities - The entities to be included.

    • withIncludeEntities

      default HalClient withIncludeEntities(String[] entities)
      Sets the names of the entities to be included by the HalClient.
      Parameters:
      entities - The entities to be included.
      Returns:
      This instance ass of the builder pattern.

    • entities

      String[] entities() throws org.refcodes.web.HttpStatusException
      Determines the entities provided by the HAL resource.
      Returns:
      A String array with the according entity names.
      Throws:
      org.refcodes.web.HttpStatusException - Thrown in case a HTTP response was of an erroneous status.

    • introspect

      default HalStruct introspect(String aEntity) throws org.refcodes.web.HttpStatusException
      Introspects the provided entity at the HAL resource and returns an instance of the CanonicalMap representing the reflected data structure. By default, Meta-Data is included in the result. If otherwise required, use introspect(String, TraversalMode).
      Parameters:
      aEntity - The entity to be introspected.
      Returns:
      A CanonicalMap instance representing the structure of the entity, e.g. providing the attribute names and the data types as well as other constraints representing the layout of the entity (think of a class defining the layout of its instances).
      Throws:
      org.refcodes.web.HttpStatusException - Thrown in case a HTTP response was of an erroneous status.

    • introspect

      HalStruct introspect(String aEntity, TraversalMode aMode) throws org.refcodes.web.HttpStatusException
      Introspects the provided entity at the HAL resource and returns an instance of the CanonicalMap representing the reflected data structure.
      Parameters:
      aEntity - The entity to be introspected.
      aMode - The mode of operation whilst introspecting an entity: You may include MetaData as of TraversalMode.IMPORT_CHILDREN_KEEP_DANGLING_HREFS or just retrieve the plain data structure without Meta-Data as of TraversalMode.IMPORT_CHILDREN.
      Returns:
      A CanonicalMap instance representing the structure of the entity, e.g. providing the attribute names and the data types as well as other constraints representing the layout of the entity (think of a class defining the layout of its instances).
      Throws:
      org.refcodes.web.HttpStatusException - Thrown in case a HTTP response was of an erroneous status.

    • create

      HalData create(String aEntity, HalData aProperties) throws org.refcodes.web.HttpStatusException
      Creates a new entitie's element (row) at the HAL resource consisting of the properties as of the provided CanonicalMap.
      Parameters:
      aEntity - The entity for which to create the element (row).
      aProperties - The CanonicalMap containing the properties of the entity be created.
      Returns:
      A HalData with the newly created element (row).
      Throws:
      org.refcodes.web.HttpStatusException - Thrown in case a HTTP response was of an erroneous status.

    • create

      default HalData create(String aEntity, Object aObj) throws org.refcodes.web.HttpStatusException
      Creates a new entitie's element (row) at the HAL resource consisting of the properties as of the provided CanonicalMap.
      Parameters:
      aEntity - The entity for which to create the element (row).
      aObj - The Object from which the properties are retrieved by means of reflection for the entity be created.
      Returns:
      A HalData with the newly created element (row).
      Throws:
      org.refcodes.web.HttpStatusException - Thrown in case a HTTP response was of an erroneous status.

    • read

      default HalData read(String aEntity, Long aId) throws org.refcodes.web.HttpStatusException
      Retrieves the properties with the according values for the given entity with the given TID from the HAL resource. Any HREF resources are ignored put the link is preserved, e.g. as of TraversalMode.IMPORT_CHILDREN_KEEP_DANGLING_HREFS.
      Parameters:
      aEntity - The entity for which to retrieve the properties.
      aId - The TID of the entity for which to retrieve the properties.
      Returns:
      A CanonicalMap with the property names assigned to the according values.
      Throws:
      org.refcodes.web.HttpStatusException - Thrown in case a HTTP response was of an erroneous status.

    • read

      default HalData read(String aEntity, Long aId, org.refcodes.web.FormFields aQueryFields) throws org.refcodes.web.HttpStatusException
      Retrieves the properties with the according values for the given entity with the given TID from the HAL resource. Any HREF resources are ignored put the link is preserved, e.g. as of TraversalMode.IMPORT_CHILDREN_KEEP_DANGLING_HREFS.
      Parameters:
      aEntity - The entity for which to retrieve the properties.
      aId - The TID of the entity for which to retrieve the properties.
      aQueryFields - The query fields to be appended to the requesting URL.
      Returns:
      A CanonicalMap with the property names assigned to the according values.
      Throws:
      org.refcodes.web.HttpStatusException - Thrown in case a HTTP response was of an erroneous status.

    • read

      default HalData read(String aEntity, Long aId, TraversalMode aMode) throws org.refcodes.web.HttpStatusException
      Retrieves the properties with the according values for the given entity with the given TID from the HAL resource.
      Parameters:
      aEntity - The entity for which to retrieve the properties.
      aId - The TID of the entity for which to retrieve the properties.
      aMode - The mode for handling HREF resources, e.g. load them as well or ignore them.
      Returns:
      A CanonicalMap with the property names assigned to the according values.
      Throws:
      org.refcodes.web.HttpStatusException - Thrown in case a HTTP response was of an erroneous status.

    • read

      HalData read(String aEntity, Long aId, TraversalMode aMode, org.refcodes.web.FormFields aQueryFields) throws org.refcodes.web.HttpStatusException
      Retrieves the properties with the according values for the given entity with the given TID from the HAL resource.
      Parameters:
      aEntity - The entity for which to retrieve the properties.
      aId - The TID of the entity for which to retrieve the properties.
      aMode - The mode for handling HREF resources, e.g. load them as well or ignore them.
      aQueryFields - The query fields to be appended to the requesting URL.
      Returns:
      A CanonicalMap with the property names assigned to the according values.
      Throws:
      org.refcodes.web.HttpStatusException - Thrown in case a HTTP response was of an erroneous status.

    • readAll

      default HalDataPage readAll(String aEntity) throws org.refcodes.web.HttpStatusException
      Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource. Any HREF resources are ignored put the link is preserved, e.g. as of TraversalMode.IMPORT_CHILDREN_KEEP_DANGLING_HREFS.
      Parameters:
      aEntity - The entity for which to retrieve the properties of all elements (rows).
      Returns:
      A HalData list of type HalDataPage containing one HalData instance per element (row).
      Throws:
      org.refcodes.web.HttpStatusException - Thrown in case a HTTP response was of an erroneous status.

    • readAll

      default HalDataPage readAll(String aEntity, org.refcodes.web.FormFields aQueryFields) throws org.refcodes.web.HttpStatusException
      Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource. Any HREF resources are ignored put the link is preserved, e.g. as of TraversalMode.IMPORT_CHILDREN_KEEP_DANGLING_HREFS.
      Parameters:
      aEntity - The entity for which to retrieve the properties of all elements (rows).
      aQueryFields - The query fields to be appended to the requesting URL.
      Returns:
      A HalData list of type HalDataPage containing one HalData instance per element (row).
      Throws:
      org.refcodes.web.HttpStatusException - Thrown in case a HTTP response was of an erroneous status.

    • readAll

      default HalDataPage readAll(String aEntity, TraversalMode aMode) throws org.refcodes.web.HttpStatusException
      Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource.
      Parameters:
      aEntity - The entity for which to retrieve the properties of all elements (rows).
      aMode - The mode for handling HREF resources, e.g. load them as well or ignore them.
      Returns:
      A HalData list of type HalDataPage containing one HalData instance per element (row).
      Throws:
      org.refcodes.web.HttpStatusException - Thrown in case a HTTP response was of an erroneous status.

    • readAll

      HalDataPage readAll(String aEntity, TraversalMode aMode, org.refcodes.web.FormFields aQueryFields) throws org.refcodes.web.HttpStatusException
      Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource.
      Parameters:
      aEntity - The entity for which to retrieve the properties of all elements (rows).
      aMode - The mode for handling HREF resources, e.g. load them as well or ignore them.
      aQueryFields - The query fields to be appended to the requesting URL.
      Returns:
      A HalData list of type HalDataPage containing one HalData instance per element (row).
      Throws:
      org.refcodes.web.HttpStatusException - Thrown in case a HTTP response was of an erroneous status.

    • readPage

      default HalDataPage readPage(String aEntity, int aPage, int aPageSize) throws org.refcodes.web.HttpStatusException
      Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource. Any HREF resources are ignored put the link is preserved, e.g. as of TraversalMode.IMPORT_CHILDREN_KEEP_DANGLING_HREFS. The HAL-Browser must support pagination for the requested result set's page number and a page's size to function as intended. In Spring Boot you usually use a repository of type PagingAndSortingRepository.
      Parameters:
      aEntity - The entity for which to retrieve the properties of all elements (rows).
      aPage - The page as of pagination to retrieve.
      aPageSize - The page's size as of pagination for the page to retrieve.
      Returns:
      A HalData list of type HalDataPage containing one HalData instance per element (row).
      Throws:
      org.refcodes.web.HttpStatusException - Thrown in case a HTTP response was of an erroneous status.

    • readPage

      default HalDataPage readPage(String aEntity, int aPage, int aPageSize, TraversalMode aMode) throws org.refcodes.web.HttpStatusException
      Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource. The HAL-Browser must support pagination for the requested result set's page number and a page's size to function as intended. In Spring Boot you usually use a repository of type PagingAndSortingRepository.
      Parameters:
      aEntity - The entity for which to retrieve the properties of all elements (rows).
      aPage - The page as of pagination to retrieve.
      aPageSize - The page's size as of pagination for the page to retrieve.
      aMode - The mode for handling HREF resources, e.g. load them as well or ignore them.
      Returns:
      A HalData list of type HalDataPage containing one HalData instance per element (row).
      Throws:
      org.refcodes.web.HttpStatusException - Thrown in case a HTTP response was of an erroneous status.

    • readPage

      default HalDataPage readPage(String aEntity, int aPage, int aPageSize, org.refcodes.web.FormFields aQueryFields) throws org.refcodes.web.HttpStatusException
      Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource. Any HREF resources are ignored put the link is preserved, e.g. as of TraversalMode.IMPORT_CHILDREN_KEEP_DANGLING_HREFS. The HAL-Browser must support pagination for the requested result set's page number and a page's size to function as intended. In Spring Boot you usually use a repository of type PagingAndSortingRepository.
      Parameters:
      aEntity - The entity for which to retrieve the properties of all elements (rows).
      aPage - The page as of pagination to retrieve.
      aPageSize - The page's size as of pagination for the page to retrieve.
      aQueryFields - The query fields to be appended to the requesting URL.
      Returns:
      A HalData list of type HalDataPage containing one HalData instance per element (row).
      Throws:
      org.refcodes.web.HttpStatusException - Thrown in case a HTTP response was of an erroneous status.

    • readPage

      default HalDataPage readPage(String aEntity, int aPage, int aPageSize, TraversalMode aMode, org.refcodes.web.FormFields aQueryFields) throws org.refcodes.web.HttpStatusException
      Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource. The HAL-Browser must support pagination for the requested result set's page number and a page's size to function as intended. In Spring Boot you usually use a repository of type PagingAndSortingRepository.
      Parameters:
      aEntity - The entity for which to retrieve the properties of all elements (rows).
      aPage - The page as of pagination to retrieve.
      aPageSize - The page's size as of pagination for the page to retrieve.
      aMode - The mode for handling HREF resources, e.g. load them as well or ignore them.
      aQueryFields - The query fields to be appended to the requesting URL.
      Returns:
      A HalData list of type HalDataPage containing one HalData instance per element (row).
      Throws:
      org.refcodes.web.HttpStatusException - Thrown in case a HTTP response was of an erroneous status.

    • update

      default HalData update(String aEntity, Object aObj) throws org.refcodes.web.HttpStatusException
      Creates a new entitie's element (row) at the HAL resource consisting of the properties as of the provided CanonicalMap.
      Parameters:
      aEntity - The entity for which to create the element (row).
      aObj - The Object from which the properties are retrieved by means of reflection for the entity be created.
      Returns:
      A HalData with the newly created element (row).
      Throws:
      org.refcodes.web.HttpStatusException - Thrown in case a HTTP response was of an erroneous status.

    • update

      HalData update(String aEntity, String aId, HalData aProperties) throws org.refcodes.web.HttpStatusException
      Updates an existing entitie's element (row) at the HAL resource using the properties as of the provided CanonicalMap.
      Parameters:
      aEntity - The entity for which to update the element (row).
      aId - The TID of the element (row) of the entity to be updated.
      aProperties - The CanonicalMap containing the properties of the entity to be updated.
      Returns:
      The updated representation of the entitie's element (row).
      Throws:
      org.refcodes.web.HttpStatusException - Thrown in case a HTTP response was of an erroneous status.

    • delete

      boolean delete(String aEntity, String aId) throws org.refcodes.web.HttpStatusException
      Deletes an entitie's element (row) from the HAL resource.
      Parameters:
      aEntity - The entity for which to delete the element (row).
      aId - The TID of the element (row) of the entity to be deleted.
      Returns:
      True in case the element (row) has been deleted, false if there was none such element (row) at the HAL resource (the expectation is satisfied now as there is no element (row) with the given TID in the HAL resource after the operation).
      Throws:
      org.refcodes.web.HttpStatusException - Thrown in case a HTTP response was of an erroneous status.