Package org.eclipse.jetty.client.api

Interface Request

All Known Implementing Classes:

CoreClientUpgradeRequest, HttpProxy.TunnelRequest, HttpRequest, JakartaClientUpgradeRequest, JettyClientUpgradeRequest

public interface Request

Request represents an 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 via HttpClient.newRequest(String) and you can send them using either send() for a blocking semantic, or send(Response.CompleteListener) for an asynchronous semantic.

Request objects cannot be reused for other requests, not even for requests that have identical URI and headers.

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.Content	A reactive model to produce request content, similar to Flow.Publisher.
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

Modifier and Type	Method	Description
boolean	abort(Throwable cause)	Attempts to abort the send of this request.
Request	accept(String... accepts)
Request	agent(String agent)
Request	attribute(String name, Object value)
Request	body(Request.Content content)
Request	content(ContentProvider content)	Deprecated. use body(Content) instead
Request	content(ContentProvider content, String contentType)	Deprecated. use body(Content) instead
Request	cookie(HttpCookie cookie)
Request	file(Path file)	Shortcut method to specify a file as a content for this request, with the default content type of "application/octet-stream".
Request	file(Path file, String contentType)	Shortcut method to specify a file as a content for this request, with the given content type.
Request	followRedirects(boolean follow)
Throwable	getAbortCause()
String	getAgent()
Map<String,Object>	getAttributes()
Request.Content	getBody()
default Connection	getConnection()	Returns the connection associated with this request.
ContentProvider	getContent()	Deprecated. use getBody() instead
List<HttpCookie>	getCookies()
HttpFields	getHeaders()
String	getHost()
long	getIdleTimeout()
String	getMethod()
Fields	getParams()
String	getPath()
int	getPort()
String	getQuery()
<T extends Request.RequestListener> List<T>	getRequestListeners(Class<T> listenerClass)
String	getScheme()
Object	getTag()
long	getTimeout()
URI	getURI()
HttpVersion	getVersion()
Request	header(String name, String value)	Deprecated. use headers(Consumer) instead
Request	header(HttpHeader header, String value)	Deprecated. use headers(Consumer) instead
Request	headers(Consumer<HttpFields.Mutable> consumer)	Modifies the headers of this request.
default Request	host(String host)
Request	idleTimeout(long timeout, TimeUnit unit)
boolean	isFollowRedirects()
Request	listener(Request.Listener listener)
Request	method(String method)
Request	method(HttpMethod method)
Request	onComplete(Response.CompleteListener listener)
Request	onRequestBegin(Request.BeginListener listener)
Request	onRequestCommit(Request.CommitListener listener)
Request	onRequestContent(Request.ContentListener listener)
Request	onRequestFailure(Request.FailureListener listener)
Request	onRequestHeaders(Request.HeadersListener listener)
Request	onRequestQueued(Request.QueuedListener listener)
Request	onRequestSuccess(Request.SuccessListener listener)
Request	onResponseBegin(Response.BeginListener listener)
Request	onResponseContent(Response.ContentListener listener)
Request	onResponseContentAsync(Response.AsyncContentListener listener)
Request	onResponseContentDemanded(Response.DemandedContentListener listener)
Request	onResponseFailure(Response.FailureListener listener)
Request	onResponseHeader(Response.HeaderListener listener)
Request	onResponseHeaders(Response.HeadersListener listener)	Registers a listener for the headers event.
Request	onResponseSuccess(Response.SuccessListener listener)
Request	param(String name, String value)	Adds a URI query parameter with the given name and value.
Request	path(String path)	Specifies the URI path - and possibly the query - of this request.
default Request	port(int port)
Request	scheme(String scheme)
ContentResponse	send()	Sends this request and returns the response.
void	send(Response.CompleteListener listener)	Sends this request and asynchronously notifies the given listener for response events.
Request	tag(Object tag)	Tags this request with the given metadata tag.
Request	timeout(long timeout, TimeUnit unit)
Request	version(HttpVersion version)

Method Details

getConnection

default Connection getConnection()

Returns the connection associated with this request.

The connection is available only starting from the request begin event, when a connection is associated with the request to be sent, otherwise null is returned.

Returns:

the connection associated with this request, or null if there is no connection associated with this request

getScheme

String getScheme()

Returns:

the URI scheme of this request, such as "http" or "https"

scheme

Request scheme(String scheme)

Parameters:

scheme - the URI scheme of this request, such as "http" or "https"

Returns:

this request object

getHost

String getHost()

Returns:

the URI host of this request, such as "127.0.0.1" or "google.com"

host

default Request host(String host)

Parameters:

host - the URI host of this request, such as "127.0.0.1" or "google.com"

Returns:

this request object

getPort

int getPort()

Returns:

the URI port of this request such as 80 or 443

port

default Request port(int port)

Parameters:

port - the URI port of this request such as 80 or 443

Returns:

this request object

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 URI path of this request, such as "/" or "/path" - without the query

See Also:

• getQuery()

path

Request path(String path)

Specifies the URI path - and possibly the query - of this request. If the query part is specified, parameter values must be properly UTF-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, use param(String, String).

Parameters:

path - the URI path of this request, such as "/" or "/path?param=1"

Returns:

this request object

getQuery

String getQuery()

Returns:

the URI 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

Fields getParams()

Returns:

the URI query parameters of this request

param

Request param(String name,
 String value)

Adds a URI query parameter with the given name and value. The value is UTF-8 URL encoded.

Parameters:

name - the name of the query parameter

value - the value of the query parameter

Returns:

this request object

getHeaders

HttpFields getHeaders()

Returns:

the headers of this request

headers

Request headers(Consumer<HttpFields.Mutable> consumer)

Modifies the headers of this request.

Parameters:

consumer - the code that modifies the headers of this request

Returns:

this request object

header

@Deprecated
Request header(String name,
 String value)

Deprecated.

use headers(Consumer) instead

Parameters:

name - the name of the header

value - the value of the header

Returns:

this request object

See Also:

• header(HttpHeader, String)

header

@Deprecated
Request header(HttpHeader header,
 String value)

Deprecated.

use headers(Consumer) instead

Adds the given value to the specified header.

Multiple calls with the same parameters will add multiple values; use the value null to remove the header completely.

Parameters:

header - the header name

value - 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

tag

Request tag(Object tag)

Tags this request with the given metadata tag.

Each different tag will create a different destination, even if the destination origin is the same.

This is particularly useful in proxies, where requests for the same origin but from different clients may be tagged with client's metadata (e.g. the client remote address).

The tag metadata class must correctly implement Object.hashCode() and Object.equals(Object) so that it can be used, along with the origin, to identify a destination.

Parameters:

tag - the metadata to tag the request with

Returns:

this request object

getTag

Object getTag()

Returns:

the metadata this request has been tagged with

attribute

Request attribute(String name,
 Object value)

Parameters:

name - the name of the attribute

value - the value of the attribute

Returns:

this request object

getAttributes

Map<String,Object> getAttributes()

Returns:

the attributes of this request

getContent

@Deprecated
ContentProvider getContent()

Deprecated.

use getBody() instead

Returns:

the content provider of this request

content

@Deprecated
Request content(ContentProvider content)

Deprecated.

use body(Content) instead

Parameters:

content - the content provider of this request

Returns:

this request object

content

@Deprecated
Request content(ContentProvider content,
 String contentType)

Deprecated.

use body(Content) instead

Parameters:

content - the content provider of this request

contentType - the content type

Returns:

this request object

getBody

Request.Content getBody()

Returns:

the request content of this request

body

Request body(Request.Content content)

Parameters:

content - the request content of this request

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/octet-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 upload

contentType - 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 the User-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 the Accept 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 request

unit - the idle timeout unit

Returns:

this request object

getTimeout

long getTimeout()

Returns:

the total timeout for this request, in milliseconds; zero or negative if the timeout is disabled

timeout

Request timeout(long timeout,
 TimeUnit unit)

Parameters:

timeout - the total timeout for the request/response conversation; use zero or a negative value to disable the timeout

unit - 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)

Registers a listener for the headers event.

Note that the response headers at this event may be different from the headers received in onResponseHeader(Response.HeaderListener) as specified in Response.getHeaders().

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

onResponseContentDemanded

Request onResponseContentDemanded(Response.DemandedContentListener 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 own Response.Listener or a utility listener such as InputStreamResponseListener.

The method returns when the complete event is fired.

Returns:

a ContentResponse for this request

Throws:

InterruptedException - if send thread is interrupted

TimeoutException - if send times out

ExecutionException - 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