Package org.gcube.common.gxrest.request

Class GXWebTargetAdapterRequest

java.lang.Object
org.gcube.common.gxrest.request.GXWebTargetAdapterRequest
All Implemented Interfaces:
AutoCloseable, org.gcube.common.gxhttp.reference.GXHTTP<jakarta.ws.rs.client.Entity<?>,GXInboundResponse>
public class GXWebTargetAdapterRequest extends Object implements org.gcube.common.gxhttp.reference.GXHTTP<jakarta.ws.rs.client.Entity<?>,GXInboundResponse>, AutoCloseable
A GX request based on JAX-RS. It requires a runtime implementation of JAX-RS on the classpath (e.g. Jersey) to work.

Each request builds its own JAX-RS client when it is created, with the connect and read timeouts given to the factory method or, when none are given, with gx-http's default ones (GXConnection.getDefaultConnectTimeout(), GXConnection.getDefaultReadTimeout()), which the system properties "gxhttp.connectTimeout" and "gxhttp.readTimeout" override.

The timeouts of a JAX-RS client cannot be changed once it is built, so they are fixed for the lifetime of the request. setRetryConnectTimeout(int) and setRetryReadTimeout(int) are only a convenience for retrying a failed call with different timeouts without rebuilding the request by hand: they do rebuild it internally. Timeouts known in advance must be passed to the factory method.

close() releases the JAX-RS clients of the request, once its responses are no longer in use.

Author:
Manuele Simi (ISTI CNR), Luca Frosini (ISTI-CNR)

  • Method Details

    • newRequest

      public static GXWebTargetAdapterRequest newRequest(String address)
      Creates a new request, with the default timeouts (see the class description).
      Parameters:
      address - the address of the web app to call
      Returns:
      the request

    • newRequest

      public static GXWebTargetAdapterRequest newRequest(String address, int connectTimeout, int readTimeout)
      Creates a new request, with the given timeouts.
      Parameters:
      address - the address of the web app to call
      connectTimeout - the connect timeout in milliseconds (0 means no timeout)
      readTimeout - the read timeout in milliseconds (0 means no timeout)
      Returns:
      the request

    • newHTTPSRequest

      public static GXWebTargetAdapterRequest newHTTPSRequest(String address, String tslprotocol)
      Creates a new secure request, with the default timeouts (see the class description).
      Parameters:
      address - the address of the web app to call
      tslprotocol - the secure socket protocol to use in the call
      Returns:
      the request

    • newHTTPSRequest

      public static GXWebTargetAdapterRequest newHTTPSRequest(String address, String tslprotocol, int connectTimeout, int readTimeout)
      Creates a new secure request, with the given timeouts.
      Parameters:
      address - the address of the web app to call
      tslprotocol - the secure socket protocol to use in the call
      connectTimeout - the connect timeout in milliseconds (0 means no timeout)
      readTimeout - the read timeout in milliseconds (0 means no timeout)
      Returns:
      the request

    • newHTTPSRequest

      public static GXWebTargetAdapterRequest newHTTPSRequest(String address)
      Creates a new secure request, with the default timeouts (see the class description).
      Parameters:
      address - the address of the web app to call
      Returns:
      the request

    • newHTTPSRequest

      public static GXWebTargetAdapterRequest newHTTPSRequest(String address, int connectTimeout, int readTimeout)
      Creates a new secure request, with the given timeouts.
      Parameters:
      address - the address of the web app to call
      connectTimeout - the connect timeout in milliseconds (0 means no timeout)
      readTimeout - the read timeout in milliseconds (0 means no timeout)
      Returns:
      the request

    • setRetryConnectTimeout

      public GXWebTargetAdapterRequest setRetryConnectTimeout(int connectTimeout)
      Rebuilds this request with a new connect timeout, for retrying a failed call.

      The timeouts of a request cannot be changed: this method is only a convenience that avoids rebuilding the request by hand. It recreates the request internally (a new JAX-RS client, with the same address, path, query parameters, properties, components and headers). A timeout known in advance must be passed to the factory method, e.g. newRequest(String, int, int), not set with this method after the creation.

      Parameters:
      connectTimeout - the connect timeout in milliseconds (0 means no timeout)
      Returns:
      the request

    • setRetryReadTimeout

      public GXWebTargetAdapterRequest setRetryReadTimeout(int readTimeout)
      Rebuilds this request with a new read timeout, for retrying a failed call.

      The timeouts of a request cannot be changed: this method is only a convenience that avoids rebuilding the request by hand. It recreates the request internally (a new JAX-RS client, with the same address, path, query parameters, properties, components and headers). A timeout known in advance must be passed to the factory method, e.g. newRequest(String, int, int), not set with this method after the creation.

      Parameters:
      readTimeout - the read timeout in milliseconds (0 means no timeout)
      Returns:
      the request

    • from

      public GXWebTargetAdapterRequest from(String agent)
      Sets the identity user agent associated to the request, in place of the default one.
      Parameters:
      agent - the agent
      Returns:
      the request

    • close

      public void close()
      Releases the JAX-RS clients built for this request, the one in use and those replaced by setRetryConnectTimeout(int) or setRetryReadTimeout(int). The responses obtained through the request must not be used after it is closed, nor the request itself. Closing a request already closed has no effect.
      Specified by:
      close in interface AutoCloseable

    • configProperty

      public GXWebTargetAdapterRequest configProperty(String name, String value)
      Sets a new property in the request.
      Parameters:
      name - the name of the property
      value - the value of the property
      Returns:
      the request

    • register

      public GXWebTargetAdapterRequest register(Object component)
      Registers an instance of a custom JAX-RS component (such as an extension provider or a feature meta-provider) to be instantiated and used in the scope of this request.
      Parameters:
      component - the component to register
      Returns:
      the request

    • register

      public GXWebTargetAdapterRequest register(Class<?> component)
      Registers a class of a custom JAX-RS component (such as an extension provider or a feature meta-provider) to be instantiated and used in the scope of this request.
      Parameters:
      component - the class of the component to register
      Returns:
      the request

    • path

      public GXWebTargetAdapterRequest path(String path) throws UnsupportedEncodingException
      Adds a positional path parameter to the request.
      Parameters:
      path - the new token in the path
      Returns:
      the request
      Throws:
      UnsupportedEncodingException - if the encoding is not supported

    • queryParams

      public GXWebTargetAdapterRequest queryParams(Map<String,Object[]> parameters) throws UnsupportedEncodingException
      Sets the query parameters for the request.
      Parameters:
      parameters - the parameters that go in the URL after the address and the path params.
      Returns:
      the request
      Throws:
      UnsupportedEncodingException - if the encoding is not supported

    • setAcceptedResponseType

      public GXWebTargetAdapterRequest setAcceptedResponseType(jakarta.ws.rs.core.MediaType... acceptedResponseTypes)
      Defines the accepted response media types.
      Parameters:
      acceptedResponseTypes - accepted response media types.
      Returns:
      builder for a request targeted at the URI referenced by this target instance.

    • delete

      public GXInboundResponse delete() throws Exception
      Specified by:
      delete in interface org.gcube.common.gxhttp.reference.GXHTTP<jakarta.ws.rs.client.Entity<?>,GXInboundResponse>
      Throws:
      Exception

    • purge

      public GXInboundResponse purge() throws Exception
      Specified by:
      purge in interface org.gcube.common.gxhttp.reference.GXHTTP<jakarta.ws.rs.client.Entity<?>,GXInboundResponse>
      Throws:
      Exception

    • head

      public GXInboundResponse head() throws Exception
      Specified by:
      head in interface org.gcube.common.gxhttp.reference.GXHTTP<jakarta.ws.rs.client.Entity<?>,GXInboundResponse>
      Throws:
      Exception

    • get

      public GXInboundResponse get() throws Exception
      Specified by:
      get in interface org.gcube.common.gxhttp.reference.GXHTTP<jakarta.ws.rs.client.Entity<?>,GXInboundResponse>
      Throws:
      Exception

    • header

      public GXWebTargetAdapterRequest header(String name, Object value)
      Add an arbitrary header.
      Parameters:
      name - the name of the header
      value - the value of the header
      Returns:
      the builder

    • put

      public GXInboundResponse put(jakarta.ws.rs.client.Entity<?> body) throws Exception
      Specified by:
      put in interface org.gcube.common.gxhttp.reference.GXHTTP<jakarta.ws.rs.client.Entity<?>,GXInboundResponse>
      Throws:
      Exception

    • put

      public GXInboundResponse put() throws Exception
      Specified by:
      put in interface org.gcube.common.gxhttp.reference.GXHTTP<jakarta.ws.rs.client.Entity<?>,GXInboundResponse>
      Throws:
      Exception

    • post

      public GXInboundResponse post(jakarta.ws.rs.client.Entity<?> body) throws Exception
      Specified by:
      post in interface org.gcube.common.gxhttp.reference.GXHTTP<jakarta.ws.rs.client.Entity<?>,GXInboundResponse>
      Throws:
      Exception

    • post

      public GXInboundResponse post() throws Exception
      Specified by:
      post in interface org.gcube.common.gxhttp.reference.GXHTTP<jakarta.ws.rs.client.Entity<?>,GXInboundResponse>
      Throws:
      Exception

    • patch

      public GXInboundResponse patch(jakarta.ws.rs.client.Entity<?> body) throws Exception
      Specified by:
      patch in interface org.gcube.common.gxhttp.reference.GXHTTP<jakarta.ws.rs.client.Entity<?>,GXInboundResponse>
      Throws:
      Exception

    • patch

      public GXInboundResponse patch() throws Exception
      Specified by:
      patch in interface org.gcube.common.gxhttp.reference.GXHTTP<jakarta.ws.rs.client.Entity<?>,GXInboundResponse>
      Throws:
      Exception

    • trace

      public GXInboundResponse trace() throws Exception
      Specified by:
      trace in interface org.gcube.common.gxhttp.reference.GXHTTP<jakarta.ws.rs.client.Entity<?>,GXInboundResponse>
      Throws:
      Exception

    • options

      public GXInboundResponse options() throws Exception
      Specified by:
      options in interface org.gcube.common.gxhttp.reference.GXHTTP<jakarta.ws.rs.client.Entity<?>,GXInboundResponse>
      Throws:
      Exception

    • connect

      public GXInboundResponse connect() throws Exception
      Specified by:
      connect in interface org.gcube.common.gxhttp.reference.GXHTTP<jakarta.ws.rs.client.Entity<?>,GXInboundResponse>
      Throws:
      Exception