Package kong.unirest.core
Interface HttpRequest<R extends HttpRequest>
-
- All Known Subinterfaces:
GetRequest
,HttpRequestWithBody
,JsonPatchRequest
,MultipartBody
,RequestBodyEntity
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
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description R
accept(String value)
The 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[]>>
asBytesAsync()
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[]HttpResponse<Empty>
asEmpty()
Executes the request and returns the response without parsing the bodyCompletableFuture<HttpResponse<Empty>>
asEmptyAsync()
Executes the request asynchronously and returns the response without parsing the bodyCompletableFuture<HttpResponse<Empty>>
asEmptyAsync(Callback<Empty> callback)
Executes the request asynchronously and returns a empty response which is passed to a callbackHttpResponse<File>
asFile(String path, CopyOption... copyOptions)
Executes the request and writes the contents into a fileCompletableFuture<HttpResponse<File>>
asFileAsync(String path, CopyOption... copyOptions)
asynchronously executes the request and writes the contents into a fileCompletableFuture<HttpResponse<File>>
asFileAsync(String path, Callback<File> callback, CopyOption... copyOptions)
asynchronously executes the request and writes the contents into a fileHttpResponse<JsonNode>
asJson()
Executes the request and returns the response with the body mapped into a JsonNodeCompletableFuture<HttpResponse<JsonNode>>
asJsonAsync()
Executes the request asynchronously and returns the response with the body mapped into a JsonNodeCompletableFuture<HttpResponse<JsonNode>>
asJsonAsync(Callback<JsonNode> callback)
Executes the request asynchronously and returns the response with the body mapped into a JsonNode<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<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.HttpResponse<String>
asString()
Executes the request and returns the response with the body mapped into a StringCompletableFuture<HttpResponse<String>>
asStringAsync()
Executes the request asynchronously and returns the response with the body mapped into a StringCompletableFuture<HttpResponse<String>>
asStringAsync(Callback<String> callback)
Executes the request asynchronously and returns the response with the body mapped into a StringR
basicAuth(String username, String password)
Basic auth credentialsR
connectTimeout(int millies)
Set a connect timeout for this requestR
cookie(String name, String value)
Add a simple cookie headerR
cookie(Collection<Cookie> cookies)
Add a collection of cookie headersR
cookie(Cookie cookie)
Add a simple cookie headerR
downloadMonitor(ProgressMonitor monitor)
sets a download monitor for monitoring the response.default Optional<Body>
getBody()
int
getConnectTimeout()
Instant
getCreationTime()
Headers
getHeaders()
HttpMethod
getHttpMethod()
String
getUrl()
HttpClient.Version
getVersion()
gets the version for the request, or null if not set.R
header(String name, String value)
Add a http header, HTTP supports multiple of the same header.R
headerReplace(String name, String value)
Replace a header value or add it if it doesn't existR
headers(Map<String,String> headerMap)
Add headers as a mapR
headersReplace(Map<String,String> headerMap)
Replace headers as a mapR
queryString(String name, Object value)
add a query param to the url.R
queryString(String name, Collection<?> value)
Add multiple param with the same param name.R
queryString(Map<String,Object> parameters)
Add query params as a map of name value pairsR
responseEncoding(String encoding)
The encoding to expect the response to be for cases where the server fails to respond with the proper encodingR
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/{name} to https://localhost/users/fredR
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/{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.HttpRequestSummary
toSummary()
R
version(HttpClient.Version version)
sets the HTTP version for the request.R
withObjectMapper(ObjectMapper mapper)
Pass a ObjectMapper for the request.
-
-
-
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/{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
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/{name} 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 usernamepassword
- the password- Returns:
- this request builder
-
accept
default R accept(ContentType value)
The Accept header to send (e.g. application/json)- Parameters:
value
- a valid mime type for the Accept header- 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 headervalue
- 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 headervalue
- 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
-
headersReplace
R headersReplace(Map<String,String> headerMap)
Replace 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 cookievalue
- 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 paramvalue
- 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 paramvalue
- 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
-
version
R version(HttpClient.Version 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
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 tocallback
- 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 typecallback
- 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 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
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
-
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).
-
getVersion
HttpClient.Version getVersion()
gets the version for the request, or null if not set.- Returns:
- the version
-
-