Interface Request
-
- All Known Implementing Classes:
HttpRequest
public interface Request
Request
represents a HTTP request, and offers a fluent interface to customize various attributes such as the path, the headers, the content, etc.You can create
Request
objects viaHttpClient.newRequest(String)
and you can send them using eithersend()
for a blocking semantic, orsend(Response.CompleteListener)
for an asynchronous semantic.- See Also:
Response
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static interface
Request.BeginListener
Listener for the request begin event.static interface
Request.CommitListener
Listener for the request committed event.static interface
Request.ContentListener
Listener for the request content event.static interface
Request.FailureListener
Listener for the request failed event.static interface
Request.HeadersListener
Listener for the request headers event.static interface
Request.Listener
Listener for all request events.static interface
Request.QueuedListener
Listener for the request queued event.static interface
Request.RequestListener
Common, empty, super-interface for request listeners.static interface
Request.SuccessListener
Listener for the request succeeded event.
-
Method Summary
-
-
-
Method Detail
-
getScheme
String getScheme()
- Returns:
- the scheme of this request, such as "http" or "https"
-
scheme
Request scheme(String scheme)
- Parameters:
scheme
- the scheme of this request, such as "http" or "https"- Returns:
- this request object
-
getHost
String getHost()
- Returns:
- the host of this request, such as "127.0.0.1" or "google.com"
-
getPort
int getPort()
- Returns:
- the port of this request such as 80 or 443
-
getMethod
String getMethod()
- Returns:
- the method of this request, such as GET or POST, as a String
-
method
Request method(HttpMethod method)
- Parameters:
method
- the method of this request, such as GET or POST- Returns:
- this request object
-
method
Request method(String method)
- Parameters:
method
- the method of this request, such as GET or POST- Returns:
- this request object
-
getPath
String getPath()
- Returns:
- the path of this request, such as "/" or "/path" - without the query
- See Also:
getQuery()
-
path
Request path(String path)
Specifies the path - and possibly the query - of this request. If the query part is specified, parameter values must be properlyUTF-8 URL encoded
. For example, if the value for parameter "currency" is the euro symbol € then the query string for this parameter must be "currency=%E2%82%AC". For transparent encoding of parameter values, useparam(String, String)
.- Parameters:
path
- the path of this request, such as "/" or "/path?param=1"- Returns:
- this request object
-
getQuery
String getQuery()
- Returns:
- the query string of this request such as "param=1"
- See Also:
getPath()
,getParams()
-
getURI
URI getURI()
- Returns:
- the full URI of this request such as "http://host:port/path?param=1"
-
getVersion
HttpVersion getVersion()
- Returns:
- the HTTP version of this request, such as "HTTP/1.1"
-
version
Request version(HttpVersion version)
- Parameters:
version
- the HTTP version of this request, such as "HTTP/1.1"- Returns:
- this request object
-
getParams
org.eclipse.jetty.util.Fields getParams()
- Returns:
- the query parameters of this request
-
param
Request param(String name, String value)
Adds a query parameter with the given name and value. The value isUTF-8 URL encoded
.- Parameters:
name
- the name of the query parametervalue
- the value of the query parameter- Returns:
- this request object
-
getHeaders
HttpFields getHeaders()
- Returns:
- the headers of this request
-
header
Request header(String name, String value)
- Parameters:
name
- the name of the headervalue
- the value of the header- Returns:
- this request object
- See Also:
header(HttpHeader, String)
-
header
Request header(HttpHeader header, String value)
Adds the given
value
to the specifiedheader
.Multiple calls with the same parameters will add multiple values; use the value
null
to remove the header completely.- Parameters:
header
- the header namevalue
- the value of the header- Returns:
- this request object
-
getCookies
List<HttpCookie> getCookies()
- Returns:
- the cookies associated with this request
-
cookie
Request cookie(HttpCookie cookie)
- Parameters:
cookie
- a cookie for this request- Returns:
- this request object
-
attribute
Request attribute(String name, Object value)
- Parameters:
name
- the name of the attributevalue
- the value of the attribute- Returns:
- this request object
-
getContent
ContentProvider getContent()
- Returns:
- the content provider of this request
-
content
Request content(ContentProvider content)
- Parameters:
content
- the content provider of this request- Returns:
- this request object
-
content
Request content(ContentProvider content, String contentType)
- Parameters:
content
- the content provider of this requestcontentType
- the content type- Returns:
- this request object
-
file
Request file(Path file) throws IOException
Shortcut method to specify a file as a content for this request, with the default content type of "application/octect-stream".- Parameters:
file
- the file to upload- Returns:
- this request object
- Throws:
IOException
- if the file does not exist or cannot be read
-
file
Request file(Path file, String contentType) throws IOException
Shortcut method to specify a file as a content for this request, with the given content type.- Parameters:
file
- the file to uploadcontentType
- the content type of the file- Returns:
- this request object
- Throws:
IOException
- if the file does not exist or cannot be read
-
getAgent
String getAgent()
- Returns:
- the user agent for this request
-
agent
Request agent(String agent)
- Parameters:
agent
- the user agent for this request (corresponds to theUser-Agent
header)- Returns:
- this request object
-
accept
Request accept(String... accepts)
- Parameters:
accepts
- the media types that are acceptable in the response, such as "text/plain;q=0.5" or "text/html" (corresponds to theAccept
header)- Returns:
- this request object
-
getIdleTimeout
long getIdleTimeout()
- Returns:
- the idle timeout for this request, in milliseconds
-
idleTimeout
Request idleTimeout(long timeout, TimeUnit unit)
- Parameters:
timeout
- the idle timeout for this requestunit
- the idle timeout unit- Returns:
- this request object
-
getTimeout
long getTimeout()
- Returns:
- the total timeout for this request, in milliseconds
-
timeout
Request timeout(long timeout, TimeUnit unit)
- Parameters:
timeout
- the total timeout for the request/response conversationunit
- the timeout unit- Returns:
- this request object
-
isFollowRedirects
boolean isFollowRedirects()
- Returns:
- whether this request follows redirects
-
followRedirects
Request followRedirects(boolean follow)
- Parameters:
follow
- whether this request follows redirects- Returns:
- this request object
-
getRequestListeners
<T extends Request.RequestListener> List<T> getRequestListeners(Class<T> listenerClass)
- Type Parameters:
T
- the type of listener class- Parameters:
listenerClass
- the class of the listener, or null for all listeners classes- Returns:
- the listeners for request events of the given class
-
listener
Request listener(Request.Listener listener)
- Parameters:
listener
- a listener for request events- Returns:
- this request object
-
onRequestQueued
Request onRequestQueued(Request.QueuedListener listener)
- Parameters:
listener
- a listener for request queued event- Returns:
- this request object
-
onRequestBegin
Request onRequestBegin(Request.BeginListener listener)
- Parameters:
listener
- a listener for request begin event- Returns:
- this request object
-
onRequestHeaders
Request onRequestHeaders(Request.HeadersListener listener)
- Parameters:
listener
- a listener for request headers event- Returns:
- this request object
-
onRequestCommit
Request onRequestCommit(Request.CommitListener listener)
- Parameters:
listener
- a listener for request commit event- Returns:
- this request object
-
onRequestContent
Request onRequestContent(Request.ContentListener listener)
- Parameters:
listener
- a listener for request content events- Returns:
- this request object
-
onRequestSuccess
Request onRequestSuccess(Request.SuccessListener listener)
- Parameters:
listener
- a listener for request success event- Returns:
- this request object
-
onRequestFailure
Request onRequestFailure(Request.FailureListener listener)
- Parameters:
listener
- a listener for request failure event- Returns:
- this request object
-
onResponseBegin
Request onResponseBegin(Response.BeginListener listener)
- Parameters:
listener
- a listener for response begin event- Returns:
- this request object
-
onResponseHeader
Request onResponseHeader(Response.HeaderListener listener)
- Parameters:
listener
- a listener for response header event- Returns:
- this request object
-
onResponseHeaders
Request onResponseHeaders(Response.HeadersListener listener)
- Parameters:
listener
- a listener for response headers event- Returns:
- this request object
-
onResponseContent
Request onResponseContent(Response.ContentListener listener)
- Parameters:
listener
- a consuming listener for response content events- Returns:
- this request object
-
onResponseContentAsync
Request onResponseContentAsync(Response.AsyncContentListener listener)
- Parameters:
listener
- an asynchronous listener for response content events- Returns:
- this request object
-
onResponseSuccess
Request onResponseSuccess(Response.SuccessListener listener)
- Parameters:
listener
- a listener for response success event- Returns:
- this request object
-
onResponseFailure
Request onResponseFailure(Response.FailureListener listener)
- Parameters:
listener
- a listener for response failure event- Returns:
- this request object
-
onComplete
Request onComplete(Response.CompleteListener listener)
- Parameters:
listener
- a listener for complete event- Returns:
- this request object
-
send
ContentResponse send() throws InterruptedException, TimeoutException, ExecutionException
Sends this request and returns the response.This method should be used when a simple blocking semantic is needed, and when it is known that the response content can be buffered without exceeding memory constraints.
For example, this method is not appropriate to download big files from a server; consider using
send(Response.CompleteListener)
instead, passing your ownResponse.Listener
or a utility listener such asInputStreamResponseListener
.The method returns when the
complete event
is fired.- Returns:
- a
ContentResponse
for this request - Throws:
InterruptedException
- if send thread is interruptedTimeoutException
- if send times outExecutionException
- if execution fails- See Also:
Response.CompleteListener.onComplete(Result)
-
send
void send(Response.CompleteListener listener)
Sends this request and asynchronously notifies the given listener for response events.
This method should be used when the application needs to be notified of the various response events as they happen, or when the application needs to efficiently manage the response content.
The listener passed to this method may implement not only
Response.CompleteListener
but also other response listener interfaces, and all the events implemented will be notified. This allows application code to write a single listener class to handle all relevant events.- Parameters:
listener
- the listener that receives response events
-
abort
boolean abort(Throwable cause)
Attempts to abort the send of this request.- Parameters:
cause
- the abort cause, must not be null- Returns:
- whether the abort succeeded
-
getAbortCause
Throwable getAbortCause()
- Returns:
- the abort cause passed to
abort(Throwable)
, or null if this request has not been aborted
-
-