Package org.gcube.common.gxhttp.request

Class GXRequest

  • public class GXRequest
extends Object
    An HTTP request to a remote service, sent with HttpURLConnection. Every method takes the same path, and the body, when set, is sent with any of them. 
     GXResponse response = GXRequest.newRequest(address).path("instances").path(uuid)
                .header("Content-Type", GXRequest.APPLICATION_JSON_CHARSET_UTF_8).withBody(json).put();

    The request carries the credentials of the current gCube session, the UMA token held by AccessTokenProvider as Authorization: Bearer and the legacy gCube token held by SecurityTokenProvider in its own header, unless the caller sets one of those headers itself or declares the call external. A gCube request without any credential fails with IllegalStateException.

    PATCH and PURGE are not available: HttpURLConnection refuses them, so patch() and purge() throw UnsupportedOperationException.

    A request that never reached the server (refused connection, unknown host, connect timeout) fails with the original exception. A request sent but left without a response (read timeout, connection closed while waiting) fails with GXResponseException: the server may have processed it.

    Author:
    Luca Frosini (ISTI-CNR)

    • Method Detail

      • newRequest

        public static GXRequest newRequest​(String address)
        Creates a request.
        Parameters:
        address - the address of the remote service
        Returns:
        the request

      • getDefaultConnectTimeout

        public static int getDefaultConnectTimeout()
        Gets the default connect timeout: "gxhttp.connectTimeout" when set, otherwise 30000.
        Returns:
        the timeout in milliseconds; 0 means infinite

      • getDefaultReadTimeout

        public static int getDefaultReadTimeout()
        Gets the default read timeout: "gxhttp.readTimeout" when set, otherwise 300000.
        Returns:
        the timeout in milliseconds; 0 means infinite

      • from

        public GXRequest from​(String agent)
        Sets the agent sent as User-Agent.
        Parameters:
        agent - the agent
        Returns:
        this request

      • path

        public GXRequest path​(String pathPart)
        Appends a part to the path; each segment is encoded.
        Parameters:
        pathPart - the path part, possibly with several segments separated by "/"
        Returns:
        this request

      • queryParams

        public GXRequest queryParams​(Map<String,​String> parameters)
        Sets the query parameters; names and values are encoded.
        Parameters:
        parameters - the parameters
        Returns:
        this request

      • pathParams

        public GXRequest pathParams​(String pathParameters)
        Sets path parameters, appended as they are after the path (e.g. ;name=value).
        Parameters:
        pathParameters - the already encoded path parameters
        Returns:
        this request

      • queryString

        public GXRequest queryString​(String queryParameters)
        Sets the query string as it is.
        Parameters:
        queryParameters - the already encoded query string, without "?"
        Returns:
        this request

      • header

        public GXRequest header​(String name,
                        String value)
        Sets a header. An Authorization or gCube token header set here replaces the one the request would take from the current session.
        Parameters:
        name - the header name
        value - the header value
        Returns:
        this request

      • external

        public GXRequest external​(boolean external)
        Declares whether the call goes to a service outside gCube: an external call carries no credential of the current session.
        Parameters:
        external - true for a service outside gCube
        Returns:
        this request

      • withBody

        public GXRequest withBody​(String body)
        Sets the body as text, sent in UTF-8.
        Parameters:
        body - the body
        Returns:
        this request

      • withBody

        public GXRequest withBody​(InputStream body)
        Sets the body as a stream, read while the request is sent.
        Parameters:
        body - the body
        Returns:
        this request

      • connectTimeout

        public GXRequest connectTimeout​(int connectTimeout)
        Sets the connect timeout of this request.
        Parameters:
        connectTimeout - the timeout in milliseconds; 0 means infinite
        Returns:
        this request

      • readTimeout

        public GXRequest readTimeout​(int readTimeout)
        Sets the read timeout of this request: the time allowed, once connected, between two reads from the server, the wait for the response status and headers included.
        Parameters:
        readTimeout - the timeout in milliseconds; 0 means infinite
        Returns:
        this request

      • clear

        public void clear()
        Clears path, path parameters, query parameters and body, so that the request can be reused with the same address, headers and timeouts.

      • getURI

        public URI getURI()
        Returns:
        the URI the request is sent to