Package com.jcabi.http

Interface Request

  • All Known Implementing Classes:
    ApacheRequest, BaseRequest, FakeRequest, JdkRequest
    @Immutable
public interface Request
    RESTful request.

    Instance of this class is supposed to be used this way: 

     String name = new ApacheRequest("https://www.example.com:8080")
   .uri().path("/users").queryParam("id", 333).back()
   .method(Request.GET)
   .header(HttpHeaders.ACCEPT, MediaType.TEXT_XML)
   .fetch()
   .as(RestResponse.class)
   .assertStatus(HttpURLConnection.HTTP_OK)
   .as(XmlResponse.class)
   .assertXPath("/page/links/link[@rel='see']")
   .rel("/page/links/link[@rel='see']/@href")
   .header(HttpHeaders.ACCEPT, MediaType.APPLICATION_JSON)
   .fetch()
   .as(JsonResponse.class)
   .json().getJsonObject().getString("name");

    Since version 0.10 it is recommended to use RetryWire decorator to avoid accidental IOException when connection is weak or unstable, for example: 

     String body = new JdkRequest("https://www.google.com")
   .through(RetryWire.class)
   .fetch()
   .body();

    Instances of this interface are immutable and thread-safe.

    You can use either ApacheRequest or JdkRequest, according to your needs. JdkRequest won't require any additional dependencies, while ApacheRequest will properly support all possible HTTP methods (JdkRequest doesn't support PATCH, for example).

    Since:
    0.8
    See Also:
    JdkRequest, ApacheRequest

    • Method Detail

      • uri

        RequestURI uri()
        Get destination URI.
        Returns:
        The destination it is currently pointing to

      • body

        RequestBody body()
        Get request body.
        Returns:
        New alternated request

      • multipartBody

        RequestBody multipartBody()
        Get multipart form (multipart/form-data) body.
        Returns:
        New altered request

      • header

        Request header​(String name,
               Object value)
        Set request header.
        Parameters:
        name - ImmutableHeader name
        value - Value of the header to set
        Returns:
        New alternated request

      • reset

        Request reset​(String name)
        Remove all headers with this name.
        Parameters:
        name - ImmutableHeader name
        Returns:
        New alternated request
        Since:
        0.10

      • method

        Request method​(String method)
        Use this method.
        Parameters:
        method - The method to use
        Returns:
        New alternated request

      • timeout

        Request timeout​(int connect,
                int read)
        Use this timeout values.
        Parameters:
        connect - The connect timeout to use in ms
        read - The read timeout to use in ms
        Returns:
        New alternated request

      • fetch

        Response fetch()
        throws IOException
        Execute it with a specified HTTP method.
        Returns:
        Response
        Throws:
        IOException - If fails to fetch HTTP request

      • fetch

        Response fetch​(InputStream stream)
        throws IOException
        Execute this request using the content provided by the InputStream being passed as the request body. Note that the request MUST have an empty body when this method is being invoked, or it will throw an IllegalStateException.
        Parameters:
        stream - The input stream to use
        Returns:
        Response
        Throws:
        IOException - If fails to fetch HTTP request
        Since:
        1.8

      • through

        <T extends Wire> Request through​(Class<T> type,
                                 Object... args)
        Send it through a decorating Wire.
        Type Parameters:
        T - Type to use
        Parameters:
        type - Type of wire to use
        args - Optional arguments for the wire constructor
        Returns:
        New request with a wire decorated
        Since:
        0.10

      • through

        Request through​(Wire wire)
        Send it through a decorating Wire.
        Parameters:
        wire - Wire to use
        Returns:
        New request with a wire decorated
        Since:
        0.10