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 raw HttpURLConnection response 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. on a HEAD call).
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. on a HEAD call).
static <C> C	getResponse(Class<C> clz, HttpURLConnection connection)	Reads and interprets the response of an already-executed HttpURLConnection request, deserializing it into the expected type or raising the mapped ResourceRegistryException on error.
static <C> ResourceRegistryResponse<C>	getResponseWithMetadata(Class<C> clz, HttpURLConnection connection)	Reads a successful response 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 Details

HTTPUtility

public HTTPUtility()

Method Details

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. an HTTP connection's body or error stream)

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,
 HttpURLConnection connection)
                         throws Exception

Reads and interprets the response of an already-executed HttpURLConnection request, deserializing it into the expected type or raising the mapped ResourceRegistryException on error. On HEAD requests, a 204 No Content yields null, and 404/403 are translated via getElementNotFoundException(Class)/getElementAvailableInAnotherContextException(Class) since a HEAD response carries no error body to unmarshal. The connection 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

connection - the connection whose request has already been sent

Returns:

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

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,
 HttpURLConnection connection)
                                                               throws Exception

Reads a successful response together with immutable HTTP metadata, or attaches the same metadata to a mapped ResourceRegistryException for an unsuccessful response. The connection 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

connection - executed connection

Returns:

immutable response containing the deserialized body and HTTP metadata

Throws:

Exception - if the response is unsuccessful or cannot be read