Package org.gcube.informationsystem.resourceregistry.api.rest.httputils

Class HTTPUtility

java.lang.Object

org.gcube.informationsystem.resourceregistry.api.rest.httputils.HTTPUtility

public class HTTPUtility
extends Object

Client-side helper shared by the Resource Registry client libraries to translate a GXResponse into either a deserialized model element or the appropriate ResourceRegistryException subclass.

Author:

Luca Frosini (ISTI - CNR)

Constructor Summary

Constructors

Constructor	Description
HTTPUtility()

Method Summary

Modifier and Type	Method	Description
protected static <C> AvailableInAnotherContextException	getElementAvailableInAnotherContextException(Class<C> clz)	Builds the most specific AvailableInAnotherContextException subclass for the given model class, used when the server returned 403 Forbidden for a request whose response body could not be otherwise mapped (e.g.
protected static <C> NotFoundException	getElementNotFoundException(Class<C> clz)	Builds the most specific NotFoundException subclass for the given model class, used when the server returned 404 Not Found for a request whose response body could not be otherwise mapped (e.g.
static <C> C	getHeadResponse(Class<C> clz, org.gcube.common.gxhttp.request.GXResponse response)	Reads and interprets the response to a HEAD request, which carries no body: a 204 No Content yields null, and 404/403 are translated via getElementNotFoundException(Class)/getElementAvailableInAnotherContextException(Class).
static <C> C	getResponse(Class<C> clz, org.gcube.common.gxhttp.request.GXResponse response)	Reads and interprets the response to a request sent with any method but HEAD, deserializing it into the expected type or raising the mapped ResourceRegistryException on error.
static <C> ResourceRegistryResponse<C>	getResponseWithMetadata(Class<C> clz, org.gcube.common.gxhttp.request.GXResponse response)	Reads a successful response to a request sent with any method but HEAD, together with immutable HTTP metadata, or attaches the same metadata to a mapped ResourceRegistryException for an unsuccessful response.
protected static StringBuilder	getStringBuilder(InputStream inputStream)	Reads an input stream fully into a StringBuilder, line by line.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HTTPUtility

public HTTPUtility()

Method Detail

getElementNotFoundException

protected static <C> NotFoundException getElementNotFoundException(Class<C> clz)
                                                            throws NotFoundException,
                                                                   ResourceRegistryException

Builds the most specific NotFoundException subclass for the given model class, used when the server returned 404 Not Found for a request whose response body could not be otherwise mapped (e.g. on a HEAD call).

Type Parameters:

C - the expected model class of the missing element

Parameters:

clz - Resource, Facet, Relation, or another element class

Returns:

ResourceNotFoundException, FacetNotFoundException, or RelationNotFoundException for a matching clz, otherwise a generic NotFoundException

Throws:

NotFoundException - never thrown directly; declared for symmetry with the exception being built

ResourceRegistryException - never thrown directly; declared for symmetry with the exception being built

getElementAvailableInAnotherContextException

protected static <C> AvailableInAnotherContextException getElementAvailableInAnotherContextException(Class<C> clz)

Builds the most specific AvailableInAnotherContextException subclass for the given model class, used when the server returned 403 Forbidden for a request whose response body could not be otherwise mapped (e.g. on a HEAD call).

Type Parameters:

C - the expected model class of the out-of-scope element

Parameters:

clz - Resource, Facet, Relation, or another element class

Returns:

ResourceAvailableInAnotherContextException, FacetAvailableInAnotherContextException, or RelationAvailableInAnotherContextException for a matching clz, otherwise a generic AvailableInAnotherContextException

getStringBuilder

protected static StringBuilder getStringBuilder(InputStream inputStream)
                                         throws IOException

Reads an input stream fully into a StringBuilder, line by line.

Parameters:

inputStream - the stream to read (e.g. the body of an HTTP response)

Returns:

the full content of inputStream, decoded as text

Throws:

IOException - if reading from inputStream fails

getResponse

public static <C> C getResponse(Class<C> clz,
                                org.gcube.common.gxhttp.request.GXResponse response)
                         throws Exception

Reads and interprets the response to a request sent with any method but HEAD, deserializing it into the expected type or raising the mapped ResourceRegistryException on error. The response is always closed before returning.

Type Parameters:

C - the expected response type: Boolean, an Element subtype, or String for the raw body

Parameters:

clz - the expected response class

response - the response received from the server

Returns:

the response body deserialized as a C

Throws:

Exception - the mapped ResourceRegistryException on an HTTP error status, or any lower-level I/O/deserialization failure

getHeadResponse

public static <C> C getHeadResponse(Class<C> clz,
                                    org.gcube.common.gxhttp.request.GXResponse response)
                             throws Exception

Reads and interprets the response to a HEAD request, which carries no body: a 204 No Content yields null, and 404/403 are translated via getElementNotFoundException(Class)/getElementAvailableInAnotherContextException(Class). Any other status is interpreted as getResponse(Class, GXResponse) does. The response is always closed before returning.

Type Parameters:

C - the expected response type: Boolean, an Element subtype, or String for the raw body

Parameters:

clz - the expected response class

response - the response received from the server

Returns:

null for a 204 No Content response, otherwise the response body deserialized as a C

Throws:

Exception - the mapped ResourceRegistryException on an HTTP error status, or any lower-level I/O/deserialization failure

getResponseWithMetadata

public static <C> ResourceRegistryResponse<C> getResponseWithMetadata(Class<C> clz,
                                                                      org.gcube.common.gxhttp.request.GXResponse response)
                                                               throws Exception

Reads a successful response to a request sent with any method but HEAD, together with immutable HTTP metadata, or attaches the same metadata to a mapped ResourceRegistryException for an unsuccessful response. The response is always closed after its status, headers, URI, and body have been captured.

Type Parameters:

C - expected response body type

Parameters:

clz - expected response class

response - the response received from the server

Returns:

immutable response containing the deserialized body and HTTP metadata

Throws:

Exception - if the response is unsuccessful or cannot be read