Package kong.unirest.core
Interface HttpRequest<R extends HttpRequest>
- All Known Subinterfaces:
GetRequest
,HttpRequestWithBody
,JsonPatchRequest
,MultipartBody
,RequestBodyEntity
- All Known Implementing Classes:
BaseRequest
,HttpRequestBody
,HttpRequestJsonPatch
,HttpRequestMultiPart
,HttpRequestNoBody
,HttpRequestUniBody
public interface HttpRequest<R extends HttpRequest>
The primary request builder used to create a request. This will be completed after calling one of
the "as**" methods like asString()
-
Method Summary
Modifier and TypeMethodDescriptionThe Accept header to send (e.g.default R
accept
(ContentType value) The Accept header to send (e.g.HttpResponse
<byte[]> asBytes()
Executes the request and returns the response with the body mapped into a byte[]CompletableFuture
<HttpResponse<byte[]>> Executes the request asynchronously and returns the response with the body mapped into a byte[]CompletableFuture
<HttpResponse<byte[]>> asBytesAsync
(Callback<byte[]> callback) Executes the request asynchronously and returns the response with the body mapped into a byte[]asEmpty()
Executes the request and returns the response without parsing the bodyExecutes the request asynchronously and returns the response without parsing the bodyasEmptyAsync
(Callback<Empty> callback) Executes the request asynchronously and returns a empty response which is passed to a callbackasFile
(String path, CopyOption... copyOptions) Executes the request and writes the contents into a fileasFileAsync
(String path, CopyOption... copyOptions) asynchronously executes the request and writes the contents into a fileasFileAsync
(String path, Callback<File> callback, CopyOption... copyOptions) asynchronously executes the request and writes the contents into a fileasJson()
Executes the request and returns the response with the body mapped into a JsonNodeExecutes the request asynchronously and returns the response with the body mapped into a JsonNodeasJsonAsync
(Callback<JsonNode> callback) Executes the request asynchronously and returns the response with the body mapped into a JsonNode<T> HttpResponse
<T> Executes the request and returns the response with the body mapped into T by a configured ObjectMapper<T> HttpResponse
<T> asObject
(Function<RawResponse, T> function) Execute the request and pass the raw response to a function for mapping.<T> HttpResponse
<T> asObject
(GenericType<T> genericType) Executes the request and returns the response with the body mapped into T by a configured ObjectMapper<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<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.<T> CompletableFuture
<HttpResponse<T>> asObjectAsync
(Function<RawResponse, T> function) Executes the request asynchronously, and pass the raw response to a function for mapping.<T> CompletableFuture
<HttpResponse<T>> asObjectAsync
(GenericType<T> genericType) Executes the request asynchronously, and use a GenericType with the ObjectMapper<T> CompletableFuture
<HttpResponse<T>> asObjectAsync
(GenericType<T> genericType, Callback<T> callback) Executes the request asynchronously, and use a GenericType with the ObjectMapper<T> PagedList
<T> asPaged
(Function<HttpRequest, HttpResponse> mappingFunction, Function<HttpResponse<T>, String> linkExtractor) Allows for following paging links common in many APIs.asString()
Executes the request and returns the response with the body mapped into a StringExecutes the request asynchronously and returns the response with the body mapped into a StringasStringAsync
(Callback<String> callback) Executes the request asynchronously and returns the response with the body mapped into a StringBasic auth credentialsAdd a simple cookie headercookie
(Collection<Cookie> cookies) Add a collection of cookie headersAdd a simple cookie headerdownloadMonitor
(ProgressMonitor monitor) sets a download monitor for monitoring the response.getBody()
getUrl()
gets the version for the request, or null if not set.Add a http header, HTTP supports multiple of the same header.headerReplace
(String name, String value) Replace a header value or add it if it doesn't existAdd headers as a mapheadersReplace
(Map<String, String> headerMap) Replace headers as a mapqueryString
(String name, Object value) add a query param to the url.queryString
(String name, Collection<?> value) Add multiple param with the same param name.queryString
(Map<String, Object> parameters) Add query params as a map of name value pairsrequestTimeout
(int millies) Set a timeout for this requestresponseEncoding
(String encoding) The encoding to expect the response to be for cases where the server fails to respond with the proper encodingrouteParam
(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/{name} to https://localhost/users/fredrouteParam
(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/{name} to https://localhost/users/fredvoid
thenConsume
(Consumer<RawResponse> consumer) Execute the request and pass the raw response to a consumer.void
thenConsumeAsync
(Consumer<RawResponse> consumer) Execute the request asynchronously and pass the raw response to a consumer.version
(HttpClient.Version version) sets the HTTP version for the request.withObjectMapper
(ObjectMapper mapper) Pass a ObjectMapper for the request.
-
Method Details
-
routeParam
add a route param that replaces the matching {name} For example routeParam("name", "fred") will replace {name} in https://localhost/users/{name} 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
add a route param map that replaces the matching {name} For example routeParam(Map.of("name", "fred")) will replace {name} in https://localhost/users/{name} to https://localhost/users/fred- Parameters:
params
- a map of path params- Returns:
- this request builder
-
basicAuth
Basic auth credentials- Parameters:
username
- the usernamepassword
- the password- Returns:
- this request builder
-
accept
The Accept header to send (e.g. application/json)- Parameters:
value
- a valid mime type for the Accept header- Returns:
- this request builder
-
accept
The Accept header to send (e.g. application/json)- Parameters:
value
- a valid mime type for the Accept header- Returns:
- this request builder
-
responseEncoding
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
Add a http header, HTTP supports multiple of the same header. This will continue to append new values- Parameters:
name
- name of the headervalue
- value for the header- Returns:
- this request builder
-
headerReplace
Replace a header value or add it if it doesn't exist- Parameters:
name
- name of the headervalue
- value for the header- Returns:
- this request builder
-
headers
Add headers as a map- Parameters:
headerMap
- a map of headers- Returns:
- this request builder
-
headersReplace
Replace headers as a map- Parameters:
headerMap
- a map of headers- Returns:
- this request builder
-
cookie
Add a simple cookie header- Parameters:
name
- the name of the cookievalue
- the value of the cookie- Returns:
- this request builder
-
cookie
Add a simple cookie header- Parameters:
cookie
- a cookie- Returns:
- this request builder
-
cookie
Add a collection of cookie headers- Parameters:
cookies
- a cookie- Returns:
- this request builder
-
queryString
add a query param to the url. The value will be URL-Encoded- Parameters:
name
- the name of the paramvalue
- the value of the param- Returns:
- this request builder
-
queryString
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 paramvalue
- a collection of values- Returns:
- this request builder
-
queryString
Add query params as a map of name value pairs- Parameters:
parameters
- a map of params- Returns:
- this request builder
-
withObjectMapper
Pass a ObjectMapper for the request. This will override any globally configured ObjectMapper- Parameters:
mapper
- the ObjectMapper- Returns:
- this request builder
-
requestTimeout
Set a timeout for this request- Parameters:
millies
- the time in millies- Returns:
- this request builder
-
downloadMonitor
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
-
version
sets the HTTP version for the request. This will override any global config- Parameters:
version
- the version- 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
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
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
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
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
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
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
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 tocallback
- a callback for handling the body post mapping- Returns:
- a CompletableFuture of a HttpResponse containing the body of T
-
asObjectAsync
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 typecallback
- a callback for handling the body post mapping- Returns:
- a CompletableFuture of a HttpResponse containing the body of T
-
asObjectAsync
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
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
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 mappingcopyOptions
- 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<Empty> 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
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
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
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
- Returns:
- if the request has a body it will be here.
-
getRequestTimeout
Integer getRequestTimeout()- 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).
-
getVersion
HttpClient.Version getVersion()gets the version for the request, or null if not set.- Returns:
- the version
-