Package org.refcodes.hal
Interface HalClient
-
- All Superinterfaces:
org.refcodes.net.OauthTokenAccessor
,org.refcodes.net.OauthTokenAccessor.OauthTokenBuilder<HalClient>
,org.refcodes.net.OauthTokenAccessor.OauthTokenMutator
,org.refcodes.net.OauthTokenAccessor.OauthTokenProperty
- All Known Implementing Classes:
HalClientImpl
public interface HalClient extends org.refcodes.net.OauthTokenAccessor.OauthTokenProperty, org.refcodes.net.OauthTokenAccessor.OauthTokenBuilder<HalClient>
TheHalClient
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 theCanonicalMap
(as well as theCanonicalMap.CanonicalMapBuilder
) to operate upon the dynamic data structures. Implementations may use theHttpRestServer
and it's implementations such as theHttpRestServerImpl
. See also "https://en.wikipedia.org/wiki/Hypertext_Application_Language".
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from interface org.refcodes.net.OauthTokenAccessor
org.refcodes.net.OauthTokenAccessor.OauthTokenBuilder<B extends org.refcodes.net.OauthTokenAccessor.OauthTokenBuilder<B>>, org.refcodes.net.OauthTokenAccessor.OauthTokenMutator, org.refcodes.net.OauthTokenAccessor.OauthTokenProperty
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description default HalData
create(java.lang.String aEntity, java.lang.Object aObj)
Creates a new entitie's element (row) at the HAL resource consisting of the properties as of the providedCanonicalMap
.HalData
create(java.lang.String aEntity, HalData aProperties)
Creates a new entitie's element (row) at the HAL resource consisting of the properties as of the providedCanonicalMap
.boolean
delete(java.lang.String aEntity, java.lang.String aId)
Deletes an entitie's element (row) from the HAL resource.java.lang.String[]
entities()
Determines the entities provided by the HAL resource.java.lang.String[]
getExcludeEntities()
Gets the names of the entities to be excluded by theHalClient
.java.lang.String[]
getIncludeEntities()
Gets the names of the entities to be included by theHalClient
.default HalStruct
introspect(java.lang.String aEntity)
Introspects the provided entity at the HAL resource and returns an instance of theCanonicalMap
representing the reflected data structure.HalStruct
introspect(java.lang.String aEntity, TraversalMode aMode)
Introspects the provided entity at the HAL resource and returns an instance of theCanonicalMap
representing the reflected data structure.default HalData
read(java.lang.String aEntity, java.lang.Long aId)
Retrieves the properties with the according values for the given entity with the given ID from the HAL resource.default HalData
read(java.lang.String aEntity, java.lang.Long aId, TraversalMode aMode)
Retrieves the properties with the according values for the given entity with the given ID from the HAL resource.HalData
read(java.lang.String aEntity, java.lang.Long aId, TraversalMode aMode, org.refcodes.net.FormFields aQueryFields)
Retrieves the properties with the according values for the given entity with the given ID from the HAL resource.default HalData
read(java.lang.String aEntity, java.lang.Long aId, org.refcodes.net.FormFields aQueryFields)
Retrieves the properties with the according values for the given entity with the given ID from the HAL resource.default java.util.List<HalData>
readAll(java.lang.String aEntity)
Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource.default java.util.List<HalData>
readAll(java.lang.String aEntity, TraversalMode aMode)
Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource.java.util.List<HalData>
readAll(java.lang.String aEntity, TraversalMode aMode, org.refcodes.net.FormFields aQueryFields)
Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource.default java.util.List<HalData>
readAll(java.lang.String aEntity, org.refcodes.net.FormFields aQueryFields)
Retrieves the properties with the according values of all elements (rows) for the given entity from the HAL resource.void
setExcludeEntities(java.lang.String[] entities)
Sets the names of the entities to be excluded by theHalClient
.void
setIncludeEntities(java.lang.String[] entities)
Sets the names of the entities to be included by theHalClient
.default HalData
update(java.lang.String aEntity, java.lang.Object aObj)
Creates a new entitie's element (row) at the HAL resource consisting of the properties as of the providedCanonicalMap
.HalData
update(java.lang.String aEntity, java.lang.String aId, HalData aProperties)
Updates an existing entitie's element (row) at the HAL resource using the properties as of the providedCanonicalMap
.default HalClient
withExcludeEntities(java.lang.String[] entities)
Sets the names of the entities to be excluded by theHalClient
.default HalClient
withIncludeEntities(java.lang.String[] entities)
Sets the names of the entities to be included by theHalClient
.default HalClient
withOAuthToken(org.refcodes.net.OauthToken aOauthToken)
-
-
-
Method Detail
-
withOAuthToken
default HalClient withOAuthToken(org.refcodes.net.OauthToken aOauthToken)
- Specified by:
withOAuthToken
in interfaceorg.refcodes.net.OauthTokenAccessor.OauthTokenBuilder<HalClient>
-
getExcludeEntities
java.lang.String[] getExcludeEntities()
Gets the names of the entities to be excluded by theHalClient
.- Returns:
- The entities to be excluded.
-
setExcludeEntities
void setExcludeEntities(java.lang.String[] entities)
Sets the names of the entities to be excluded by theHalClient
.- Parameters:
entities
- The entities to be excluded.
-
withExcludeEntities
default HalClient withExcludeEntities(java.lang.String[] entities)
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.
-
getIncludeEntities
java.lang.String[] getIncludeEntities()
Gets the names of the entities to be included by theHalClient
.- Returns:
- The entities to be included.
-
setIncludeEntities
void setIncludeEntities(java.lang.String[] entities)
Sets the names of the entities to be included by theHalClient
.- Parameters:
entities
- The entities to be included.
-
withIncludeEntities
default HalClient withIncludeEntities(java.lang.String[] entities)
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.
-
entities
java.lang.String[] entities() throws org.refcodes.net.HttpStatusException
Determines the entities provided by the HAL resource.- Returns:
- A
String
array with the according entity names. - Throws:
org.refcodes.net.HttpStatusException
- Thrown in case a HTTP response was of an erroneous status.
-
introspect
default HalStruct introspect(java.lang.String aEntity) throws org.refcodes.net.HttpStatusException
Introspects the provided entity at the HAL resource and returns an instance of theCanonicalMap
representing 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
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.net.HttpStatusException
- Thrown in case a HTTP response was of an erroneous status.
-
introspect
HalStruct introspect(java.lang.String aEntity, TraversalMode aMode) throws org.refcodes.net.HttpStatusException
Introspects the provided entity at the HAL resource and returns an instance of theCanonicalMap
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 ofTraversalMode.IMPORT_CHILDREN_KEEP_DANGLING_HREFS
or just retrieve the plain data structure without Meta-Data as ofTraversalMode.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.net.HttpStatusException
- Thrown in case a HTTP response was of an erroneous status.
-
create
HalData create(java.lang.String aEntity, HalData aProperties) throws org.refcodes.net.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
- TheCanonicalMap
containing the properties of the entity be created.- Returns:
- A
HalData
with the newly created element (row). - Throws:
org.refcodes.net.HttpStatusException
- Thrown in case a HTTP response was of an erroneous status.
-
create
default HalData create(java.lang.String aEntity, java.lang.Object aObj) throws org.refcodes.net.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).aObj
- TheObject
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.net.HttpStatusException
- Thrown in case a HTTP response was of an erroneous status.
-
read
default HalData read(java.lang.String aEntity, java.lang.Long aId) throws org.refcodes.net.HttpStatusException
Retrieves the properties with the according values for the given entity with the given ID 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 ID of the entity for which to retrieve the properties.- Returns:
- A
CanonicalMap
with the property names assigned to the according values. - Throws:
org.refcodes.net.HttpStatusException
- Thrown in case a HTTP response was of an erroneous status.
-
read
default HalData read(java.lang.String aEntity, java.lang.Long aId, org.refcodes.net.FormFields aQueryFields) throws org.refcodes.net.HttpStatusException
Retrieves the properties with the according values for the given entity with the given ID 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 ID 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.net.HttpStatusException
- Thrown in case a HTTP response was of an erroneous status.
-
read
default HalData read(java.lang.String aEntity, java.lang.Long aId, TraversalMode aMode) throws org.refcodes.net.HttpStatusException
Retrieves the properties with the according values for the given entity with the given ID from the HAL resource.- Parameters:
aEntity
- The entity for which to retrieve the properties.aId
- The ID 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.net.HttpStatusException
- Thrown in case a HTTP response was of an erroneous status.
-
read
HalData read(java.lang.String aEntity, java.lang.Long aId, TraversalMode aMode, org.refcodes.net.FormFields aQueryFields) throws org.refcodes.net.HttpStatusException
Retrieves the properties with the according values for the given entity with the given ID from the HAL resource.- Parameters:
aEntity
- The entity for which to retrieve the properties.aId
- The ID 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.net.HttpStatusException
- Thrown in case a HTTP response was of an erroneous status.
-
readAll
default java.util.List<HalData> readAll(java.lang.String aEntity) throws org.refcodes.net.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).- Returns:
- A
CanonicalMap
array with the property names assigned to the according values. oneCanonicalMap
instance per element (row). - Throws:
org.refcodes.net.HttpStatusException
- Thrown in case a HTTP response was of an erroneous status.
-
readAll
default java.util.List<HalData> readAll(java.lang.String aEntity, org.refcodes.net.FormFields aQueryFields) throws org.refcodes.net.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
CanonicalMap
array with the property names assigned to the according values. oneCanonicalMap
instance per element (row). - Throws:
org.refcodes.net.HttpStatusException
- Thrown in case a HTTP response was of an erroneous status.
-
readAll
default java.util.List<HalData> readAll(java.lang.String aEntity, TraversalMode aMode) throws org.refcodes.net.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
CanonicalMap
array with the property names assigned to the according values. oneCanonicalMap
instance per element (row). - Throws:
org.refcodes.net.HttpStatusException
- Thrown in case a HTTP response was of an erroneous status.
-
readAll
java.util.List<HalData> readAll(java.lang.String aEntity, TraversalMode aMode, org.refcodes.net.FormFields aQueryFields) throws org.refcodes.net.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
CanonicalMap
array with the property names assigned to the according values. oneCanonicalMap
instance per element (row). - Throws:
org.refcodes.net.HttpStatusException
- Thrown in case a HTTP response was of an erroneous status.
-
update
default HalData update(java.lang.String aEntity, java.lang.Object aObj) throws org.refcodes.net.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).aObj
- TheObject
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.net.HttpStatusException
- Thrown in case a HTTP response was of an erroneous status.
-
update
HalData update(java.lang.String aEntity, java.lang.String aId, HalData aProperties) throws org.refcodes.net.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 ID of the element (row) of the entity to be updated.aProperties
- TheCanonicalMap
containing the properties of the entity to be updated.- Returns:
- The updated representation of the entitie's element (row).
- Throws:
org.refcodes.net.HttpStatusException
- Thrown in case a HTTP response was of an erroneous status.
-
delete
boolean delete(java.lang.String aEntity, java.lang.String aId) throws org.refcodes.net.HttpStatusException
Deletes an entitie's element (row) from the HAL resource.- Parameters:
aEntity
- The entity for which to delete the element (row).aId
- The ID 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 ID in the HAL resource after the operation).
- Throws:
org.refcodes.net.HttpStatusException
- Thrown in case a HTTP response was of an erroneous status.
-
-