Package kong.unirest

Interface HttpRequest<R extends HttpRequest>

    • Method Detail

      • routeParam

        R routeParam​(String name,
             String value)
        add a route param that replaces the matching {name} For example routeParam("name", "fred") will replace {name} in https://localhost/users/{user} to https://localhost/users/fred
        Parameters:
        name - the name of the param (do not include curly braces {}
        value - the value to replace the placeholder with
        Returns:
        this request builder

      • routeParam

        R routeParam​(Map<String,​Object> params)
        add a route param map that replaces the matching {name} For example routeParam(Map.of("name", "fred")) will replace {name} in https://localhost/users/{user} to https://localhost/users/fred
        Parameters:
        params - a map of path params
        Returns:
        this request builder

      • basicAuth

        R basicAuth​(String username,
            String password)
        Basic auth credentials
        Parameters:
        username - the username
        password - the password
        Returns:
        this request builder

      • accept

        R accept​(String value)
        The Accept header to send (e.g. application/json
        Parameters:
        value - a valid mime type for the Accept header
        Returns:
        this request builder

      • responseEncoding

        R responseEncoding​(String encoding)
        The encoding to expect the response to be for cases where the server fails to respond with the proper encoding
        Parameters:
        encoding - a valid mime type for the Accept header
        Returns:
        this request builder

      • header

        R header​(String name,
         String value)
        Add a http header, HTTP supports multiple of the same header. This will continue to append new values
        Parameters:
        name - name of the header
        value - value for the header
        Returns:
        this request builder

      • headerReplace

        R headerReplace​(String name,
                String value)
        Replace a header value or add it if it doesn't exist
        Parameters:
        name - name of the header
        value - value for the header
        Returns:
        this request builder

      • headers

        R headers​(Map<String,​String> headerMap)
        Add headers as a map
        Parameters:
        headerMap - a map of headers
        Returns:
        this request builder

      • cookie

        R cookie​(String name,
         String value)
        Add a simple cookie header
        Parameters:
        name - the name of the cookie
        value - the value of the cookie
        Returns:
        this request builder

      • cookie

        R cookie​(Cookie cookie)
        Add a simple cookie header
        Parameters:
        cookie - a cookie
        Returns:
        this request builder

      • cookie

        R cookie​(Collection<Cookie> cookies)
        Add a collection of cookie headers
        Parameters:
        cookies - a cookie
        Returns:
        this request builder

      • queryString

        R queryString​(String name,
              Object value)
        add a query param to the url. The value will be URL-Encoded
        Parameters:
        name - the name of the param
        value - the value of the param
        Returns:
        this request builder

      • queryString

        R queryString​(String name,
              Collection<?> value)
        Add multiple param with the same param name. queryString("name", Arrays.asList("bob", "linda")) will result in ?name=bob&name=linda
        Parameters:
        name - the name of the param
        value - a collection of values
        Returns:
        this request builder

      • queryString

        R queryString​(Map<String,​Object> parameters)
        Add query params as a map of name value pairs
        Parameters:
        parameters - a map of params
        Returns:
        this request builder

      • withObjectMapper

        R withObjectMapper​(ObjectMapper mapper)
        Pass a ObjectMapper for the request. This will override any globally configured ObjectMapper
        Parameters:
        mapper - the ObjectMapper
        Returns:
        this request builder

      • connectTimeout

        R connectTimeout​(int millies)
        Set a connect timeout for this request
        Parameters:
        millies - the time in millies
        Returns:
        this request builder

      • downloadMonitor

        R downloadMonitor​(ProgressMonitor monitor)
        sets a download monitor for monitoring the response. this could be used for drawing a progress bar
        Parameters:
        monitor - a ProgressMonitor
        Returns:
        this request builder

      • asString

        HttpResponse<String> asString()
        Executes the request and returns the response with the body mapped into a String
        Returns:
        response

      • asStringAsync

        CompletableFuture<HttpResponse<String>> asStringAsync()
        Executes the request asynchronously and returns the response with the body mapped into a String
        Returns:
        a CompletableFuture of a response

      • asStringAsync

        CompletableFuture<HttpResponse<String>> asStringAsync​(Callback<String> callback)
        Executes the request asynchronously and returns the response with the body mapped into a String
        Parameters:
        callback - a callback handler
        Returns:
        a CompletableFuture of a response

      • asBytes

        HttpResponse<byte[]> asBytes()
        Executes the request and returns the response with the body mapped into a byte[]
        Returns:
        response

      • asBytesAsync

        CompletableFuture<HttpResponse<byte[]>> asBytesAsync()
        Executes the request asynchronously and returns the response with the body mapped into a byte[]
        Returns:
        a CompletableFuture of a response

      • asBytesAsync

        CompletableFuture<HttpResponse<byte[]>> asBytesAsync​(Callback<byte[]> callback)
        Executes the request asynchronously and returns the response with the body mapped into a byte[]
        Parameters:
        callback - a callback handler
        Returns:
        a CompletableFuture of a response

      • asJson

        HttpResponse<JsonNode> asJson()
        Executes the request and returns the response with the body mapped into a JsonNode
        Returns:
        response

      • asJsonAsync

        CompletableFuture<HttpResponse<JsonNode>> asJsonAsync()
        Executes the request asynchronously and returns the response with the body mapped into a JsonNode
        Returns:
        a CompletableFuture of a response

      • asJsonAsync

        CompletableFuture<HttpResponse<JsonNode>> asJsonAsync​(Callback<JsonNode> callback)
        Executes the request asynchronously and returns the response with the body mapped into a JsonNode
        Parameters:
        callback - a callback handler
        Returns:
        a CompletableFuture of a response

      • asObject

        <T> HttpResponse<T> asObject​(Class<? extends T> responseClass)
        Executes the request and returns the response with the body mapped into T by a configured ObjectMapper
        Type Parameters:
        T - the return type
        Parameters:
        responseClass - the class to return. This will be passed to the ObjectMapper
        Returns:
        a response

      • asObject

        <T> HttpResponse<T> asObject​(GenericType<T> genericType)
        Executes the request and returns the response with the body mapped into T by a configured ObjectMapper
        Type Parameters:
        T - the return type
        Parameters:
        genericType - the genertic type to return. This will be passed to the ObjectMapper
        Returns:
        a response

      • asObject

        <T> HttpResponse<T> asObject​(Function<RawResponse,​T> function)
        Execute the request and pass the raw response to a function for mapping. This raw response contains the original InputStream and is suitable for reading large responses.
        Type Parameters:
        T - The type of the response mapping
        Parameters:
        function - the function to map the response into a object of T
        Returns:
        A HttpResponse containing T as the body

      • asObjectAsync

        <T> CompletableFuture<HttpResponse<T>> asObjectAsync​(Class<? extends T> responseClass)
        Executes the request asynchronously and returns response with the body mapped into T by a configured ObjectMapper
        Type Parameters:
        T - the return type
        Parameters:
        responseClass - the class type to map to
        Returns:
        a CompletableFuture of a response

      • asObjectAsync

        <T> CompletableFuture<HttpResponse<T>> asObjectAsync​(Class<? extends T> responseClass,
                                                     Callback<T> callback)
        Executes the request asynchronously, mapping to a type via the configured object mapper and then passed to a callback handler.
        Type Parameters:
        T - the return type
        Parameters:
        responseClass - the type for the ObjectMapper to map to
        callback - a callback for handling the body post mapping
        Returns:
        a CompletableFuture of a HttpResponse containing the body of T

      • asObjectAsync

        <T> CompletableFuture<HttpResponse<T>> asObjectAsync​(GenericType<T> genericType)
        Executes the request asynchronously, and use a GenericType with the ObjectMapper
        Type Parameters:
        T - the type of the response
        Parameters:
        genericType - the generic type containing the type
        Returns:
        a CompletableFuture of a HttpResponse containing the body of T

      • asObjectAsync

        <T> CompletableFuture<HttpResponse<T>> asObjectAsync​(GenericType<T> genericType,
                                                     Callback<T> callback)
        Executes the request asynchronously, and use a GenericType with the ObjectMapper
        Type Parameters:
        T - the type of the response
        Parameters:
        genericType - the generic type containing the type
        callback - a callback for handling the body post mapping
        Returns:
        a CompletableFuture of a HttpResponse containing the body of T

      • asObjectAsync

        <T> CompletableFuture<HttpResponse<T>> asObjectAsync​(Function<RawResponse,​T> function)
        Executes the request asynchronously, and pass the raw response to a function for mapping. This raw response contains the original InputStream and is suitable for reading large responses
        Type Parameters:
        T - the type of the response
        Parameters:
        function - a function to map the raw request into a object
        Returns:
        a CompletableFuture of a HttpResponse containing the body of T

      • asFile

        HttpResponse<File> asFile​(String path,
                          CopyOption... copyOptions)
        Executes the request and writes the contents into a file
        Parameters:
        path - The path to the file.
        copyOptions - options specifying how the copy should be done
        Returns:
        a HttpResponse with the file containing the results

      • asFileAsync

        CompletableFuture<HttpResponse<File>> asFileAsync​(String path,
                                                  CopyOption... copyOptions)
        asynchronously executes the request and writes the contents into a file
        Parameters:
        path - The path to the file.
        copyOptions - options specifying how the copy should be done
        Returns:
        a file containing the results

      • asFileAsync

        CompletableFuture<HttpResponse<File>> asFileAsync​(String path,
                                                  Callback<File> callback,
                                                  CopyOption... copyOptions)
        asynchronously executes the request and writes the contents into a file
        Parameters:
        path - The path to the file.
        callback - a callback for handling the body post mapping
        copyOptions - options specifying how the copy should be done
        Returns:
        a file containing the results

      • asPaged

        <T> PagedList<T> asPaged​(Function<HttpRequest,​HttpResponse> mappingFunction,
                         Function<HttpResponse<T>,​String> linkExtractor)
        Allows for following paging links common in many APIs. Each request will result in the same request (headers, etc) but will use the "next" link provided by the extract function.
        Type Parameters:
        T - the type of response.
        Parameters:
        mappingFunction - a function to return the desired return type leveraging one of the as* methods (asString, asObject, etc).
        linkExtractor - a function to extract a "next" link to follow. Retuning a null or empty string ends the paging
        Returns:
        a PagedList of your type

      • asEmpty

        HttpResponse asEmpty()
        Executes the request and returns the response without parsing the body
        Returns:
        the basic HttpResponse

      • asEmptyAsync

        CompletableFuture<HttpResponse<Empty>> asEmptyAsync()
        Executes the request asynchronously and returns the response without parsing the body
        Returns:
        a CompletableFuture of a HttpResponse

      • asEmptyAsync

        CompletableFuture<HttpResponse<Empty>> asEmptyAsync​(Callback<Empty> callback)
        Executes the request asynchronously and returns a empty response which is passed to a callback
        Parameters:
        callback - the callback* Executes the request asynchronously and returns the response without parsing the body
        Returns:
        a CompletableFuture of a HttpResponse

      • thenConsume

        void thenConsume​(Consumer<RawResponse> consumer)
        Execute the request and pass the raw response to a consumer. This raw response contains the original InputStream and is suitable for reading large responses
        Parameters:
        consumer - a consumer function

      • thenConsumeAsync

        void thenConsumeAsync​(Consumer<RawResponse> consumer)
        Execute the request asynchronously and pass the raw response to a consumer. This raw response contains the original InputStream and is suitable for reading large responses
        Parameters:
        consumer - a consumer function

      • getHttpMethod

        HttpMethod getHttpMethod()
        Returns:
        The HTTP method of the request

      • getUrl

        String getUrl()
        Returns:
        The current URL string for the request

      • getHeaders

        Headers getHeaders()
        Returns:
        the current headers for the request

      • getBody

        default Optional<Body> getBody()
        Returns:
        if the request has a body it will be here.

      • getConnectTimeout

        int getConnectTimeout()
        Returns:
        the connect timeout for this request

      • toSummary

        HttpRequestSummary toSummary()
        Returns:
        a summary for the response, used in metrics

      • getCreationTime

        Instant getCreationTime()
        Returns:
        the instant the request object was created in UTC (not when it was sent).