java.lang.Object
org.refcodes.hal.HalClient
- All Implemented Interfaces:
org.refcodes.web.OauthTokenAccessor,org.refcodes.web.OauthTokenAccessor.OauthTokenBuilder<HalClient>,org.refcodes.web.OauthTokenAccessor.OauthTokenMutator,org.refcodes.web.OauthTokenAccessor.OauthTokenProperty
public class HalClient
extends Object
implements 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
RestfulHttpServer and it's implementations such as the
HttpRestServer. 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 -
Constructor Summary
ConstructorsConstructorDescriptionInstantiates theHalClientwith no authorization credentials passed.HalClient(String aHalUrl, String aOauthUrl, String aOauthClientId, String aOauthClientSecret, String aOauthUserName, String aOauthUserSecret) Instantiates theHalClientwith no authorization credentials passed.Instantiates theHalClientwith a validOauthTokenpassed.HalClient(org.refcodes.web.Url aHalUrl) Instantiates theHalClientwith no authorization credentials passed.HalClient(org.refcodes.web.Url aHalUrl, org.refcodes.web.OauthToken aOauthToken) Instantiates theHalClientwith a validOauthTokenpassed.HalClient(org.refcodes.web.Url aHalUrl, org.refcodes.web.Url aOauthUrl, String aOauthClientId, String aOauthClientSecret, String aOauthUserName, String aOauthUserSecret) Instantiates theHalClientwith no authorization credentials passed. -
Method Summary
Modifier and TypeMethodDescriptionCreates a new entitie's element (row) at the HAL resource consisting of the properties as of the providedCanonicalMap.Creates a new entitie's element (row) at the HAL resource consisting of the properties as of the providedCanonicalMap.booleanDeletes an entitie's element (row) from the HAL resource.String[]entities()Determines the entities provided by the HAL resource.String[]Gets the names of the entities to be excluded by theHalClient.String[]Gets the names of the entities to be included by theHalClient.org.refcodes.web.OauthTokenintrospect(String aEntity) Introspects the provided entity at the HAL resource and returns an instance of theCanonicalMaprepresenting the reflected data structure.introspect(String aEntity, TraversalMode aMode) Introspects the provided entity at the HAL resource and returns an instance of theCanonicalMaprepresenting the reflected data structure.Retrieves the properties with the according values for the given entity with the given TID from the HAL resource.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.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.Retrieves the properties with the according values for the given entity with the given TID from the HAL resource.Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource.readAll(String aEntity, TraversalMode aMode) Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource.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.Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource.Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource.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.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.Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource.voidsetExcludeEntities(String[] theEntities) Sets the names of the entities to be excluded by theHalClient.voidsetIncludeEntities(String[] theEntities) Sets the names of the entities to be included by theHalClient.voidsetOauthToken(org.refcodes.web.OauthToken aOauthToken) Creates a new entitie's element (row) at the HAL resource consisting of the properties as of the providedCanonicalMap.Updates an existing entitie's element (row) at the HAL resource using the properties as of the providedCanonicalMap.withExcludeEntities(String[] entities) Sets the names of the entities to be excluded by theHalClient.withIncludeEntities(String[] entities) Sets the names of the entities to be included by theHalClient.withOAuthToken(org.refcodes.web.OauthToken aOauthToken) Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitMethods inherited from interface org.refcodes.web.OauthTokenAccessor.OauthTokenProperty
letOauthToken
-
Constructor Details
-
HalClient
Instantiates theHalClientwith no authorization credentials passed.- Parameters:
aHalUrl- The URL pointing to the HAL-Endpoint.- Throws:
MalformedURLException- Thrown to indicate that a malformed OAuth URL has occurred.
-
HalClient
public HalClient(String aHalUrl, org.refcodes.web.OauthToken aOauthToken) throws MalformedURLException Instantiates theHalClientwith a validOauthTokenpassed.- Parameters:
aHalUrl- The URL pointing to the HAL-Endpoint.aOauthToken- The OAuth-Token to be used when authorizing against the HAL-Endpoint.- Throws:
MalformedURLException- Thrown to indicate that a malformed OAuth URL has occurred.
-
HalClient
public HalClient(String aHalUrl, String aOauthUrl, String aOauthClientId, String aOauthClientSecret, String aOauthUserName, String aOauthUserSecret) throws org.refcodes.web.HttpStatusException, MalformedURLException Instantiates theHalClientwith no authorization credentials passed.- Parameters:
aHalUrl- The URL pointing to the HAL-Endpoint.aOauthUrl- The URL pointing to the OAuth authentication endpoint.aOauthClientId- The assigned OAuth client TID.aOauthClientSecret- The client's OAuth secret.aOauthUserName- The OAuth authorization user name.aOauthUserSecret- The OAuth authorization user secret.- Throws:
org.refcodes.web.HttpStatusException- Thrown in case a HTTP response was of an erroneous status when requesting the OAuth URL.MalformedURLException- Thrown to indicate that a malformed OAuth URL has occurred.
-
HalClient
Instantiates theHalClientwith no authorization credentials passed.- Parameters:
aHalUrl- The URL pointing to the HAL-Endpoint.- Throws:
MalformedURLException- Thrown to indicate that a malformed OAuth URL has occurred.
-
HalClient
public HalClient(org.refcodes.web.Url aHalUrl, org.refcodes.web.OauthToken aOauthToken) throws MalformedURLException Instantiates theHalClientwith a validOauthTokenpassed.- Parameters:
aHalUrl- The URL pointing to the HAL-Endpoint.aOauthToken- The OAuth-Token to be used when authorizing against the HAL-Endpoint.- Throws:
MalformedURLException- Thrown to indicate that a malformed OAuth URL has occurred.
-
HalClient
public HalClient(org.refcodes.web.Url aHalUrl, org.refcodes.web.Url aOauthUrl, String aOauthClientId, String aOauthClientSecret, String aOauthUserName, String aOauthUserSecret) throws org.refcodes.web.HttpStatusException, MalformedURLException Instantiates theHalClientwith no authorization credentials passed.- Parameters:
aHalUrl- The URL pointing to the HAL-Endpoint.aOauthUrl- The URL pointing to the OAuth authentication endpoint.aOauthClientId- The assigned OAuth client TID.aOauthClientSecret- The client's OAuth secret.aOauthUserName- The OAuth authorization user name.aOauthUserSecret- The OAuth authorization user secret.- Throws:
org.refcodes.web.HttpStatusException- Thrown in case a HTTP response was of an erroneous status when requesting the OAuth URL.MalformedURLException- Thrown to indicate that a malformed OAuth URL has occurred.
-
-
Method Details
-
introspect
Introspects the provided entity at the HAL resource and returns an instance of theCanonicalMaprepresenting the reflected data structure. By default, Meta-Data is included in the result. If otherwise required, useintrospect(String, TraversalMode).- Parameters:
aEntity- The entity to be introspected.- Returns:
- A
CanonicalMapinstance 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.
-
withOAuthToken
- Specified by:
withOAuthTokenin interfaceorg.refcodes.web.OauthTokenAccessor.OauthTokenBuilder<HalClient>
-
withExcludeEntities
Sets the names of the entities to be excluded by theHalClient.- Parameters:
entities- The entities to be excluded.- Returns:
- This instance ass of the builder pattern.
-
withIncludeEntities
Sets the names of the entities to be included by theHalClient.- Parameters:
entities- The entities to be included.- Returns:
- This instance ass of the builder pattern.
-
create
public 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 providedCanonicalMap.- Parameters:
aEntity- The entity for which to create the element (row).aProperties- TheCanonicalMapcontaining the properties of the entity be created.- Returns:
- A
HalDatawith the newly created element (row). - Throws:
org.refcodes.web.HttpStatusException- Thrown in case a HTTP response was of an erroneous status.
-
create
Creates a new entitie's element (row) at the HAL resource consisting of the properties as of the providedCanonicalMap.- Parameters:
aEntity- The entity for which to create the element (row).aObj- TheObjectfrom which the properties are retrieved by means of reflection for the entity be created.- Returns:
- A
HalDatawith the newly created element (row). - Throws:
org.refcodes.web.HttpStatusException- Thrown in case a HTTP response was of an erroneous status.
-
read
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 ofTraversalMode.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
CanonicalMapwith 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
public 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 ofTraversalMode.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
CanonicalMapwith 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
public 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
CanonicalMapwith 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
public 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
CanonicalMapwith 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
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 ofTraversalMode.IMPORT_CHILDREN_KEEP_DANGLING_HREFS.- Parameters:
aEntity- The entity for which to retrieve the properties of all elements (rows).- Returns:
- A
HalDatalist of typeHalDataPagecontaining oneHalDatainstance per element (row). - Throws:
org.refcodes.web.HttpStatusException- Thrown in case a HTTP response was of an erroneous status.
-
readAll
public 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 ofTraversalMode.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
HalDatalist of typeHalDataPagecontaining oneHalDatainstance per element (row). - Throws:
org.refcodes.web.HttpStatusException- Thrown in case a HTTP response was of an erroneous status.
-
readAll
public 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
HalDatalist of typeHalDataPagecontaining oneHalDatainstance per element (row). - Throws:
org.refcodes.web.HttpStatusException- Thrown in case a HTTP response was of an erroneous status.
-
readAll
public 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
HalDatalist of typeHalDataPagecontaining oneHalDatainstance per element (row). - Throws:
org.refcodes.web.HttpStatusException- Thrown in case a HTTP response was of an erroneous status.
-
readPage
public 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 ofTraversalMode.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 typePagingAndSortingRepository.- 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
HalDatalist of typeHalDataPagecontaining oneHalDatainstance per element (row). - Throws:
org.refcodes.web.HttpStatusException- Thrown in case a HTTP response was of an erroneous status.
-
readPage
public 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 typePagingAndSortingRepository.- 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
HalDatalist of typeHalDataPagecontaining oneHalDatainstance per element (row). - Throws:
org.refcodes.web.HttpStatusException- Thrown in case a HTTP response was of an erroneous status.
-
readPage
public 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 ofTraversalMode.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 typePagingAndSortingRepository.- 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
HalDatalist of typeHalDataPagecontaining oneHalDatainstance per element (row). - Throws:
org.refcodes.web.HttpStatusException- Thrown in case a HTTP response was of an erroneous status.
-
readPage
public 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 typePagingAndSortingRepository.- 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
HalDatalist of typeHalDataPagecontaining oneHalDatainstance per element (row). - Throws:
org.refcodes.web.HttpStatusException- Thrown in case a HTTP response was of an erroneous status.
-
update
Creates a new entitie's element (row) at the HAL resource consisting of the properties as of the providedCanonicalMap.- Parameters:
aEntity- The entity for which to create the element (row).aObj- TheObjectfrom which the properties are retrieved by means of reflection for the entity be created.- Returns:
- A
HalDatawith the newly created element (row). - Throws:
org.refcodes.web.HttpStatusException- Thrown in case a HTTP response was of an erroneous status.
-
update
public 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 providedCanonicalMap.- 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- TheCanonicalMapcontaining 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
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.
-
entities
Determines the entities provided by the HAL resource.- Returns:
- A
Stringarray with the according entity names. - Throws:
org.refcodes.web.HttpStatusException- Thrown in case a HTTP response was of an erroneous status.
-
introspect
public HalStruct introspect(String aEntity, TraversalMode aMode) throws org.refcodes.web.HttpStatusException Introspects the provided entity at the HAL resource and returns an instance of theCanonicalMaprepresenting 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 ofTraversalMode.IMPORT_CHILDREN_KEEP_DANGLING_HREFSor just retrieve the plain data structure without Meta-Data as ofTraversalMode.IMPORT_CHILDREN.- Returns:
- A
CanonicalMapinstance 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.
-
getExcludeEntities
Gets the names of the entities to be excluded by theHalClient.- Returns:
- The entities to be excluded.
-
getIncludeEntities
Gets the names of the entities to be included by theHalClient.- Returns:
- The entities to be included.
-
getOauthToken
public org.refcodes.web.OauthToken getOauthToken()- Specified by:
getOauthTokenin interfaceorg.refcodes.web.OauthTokenAccessor
-
setExcludeEntities
Sets the names of the entities to be excluded by theHalClient.- Parameters:
theEntities- the new exclude entities
-
setIncludeEntities
Sets the names of the entities to be included by theHalClient.- Parameters:
theEntities- the new include entities
-
setOauthToken
public void setOauthToken(org.refcodes.web.OauthToken aOauthToken) - Specified by:
setOauthTokenin interfaceorg.refcodes.web.OauthTokenAccessor.OauthTokenMutator
-