Package org.eclipse.jetty.client.api

Interface Request

All Known Implementing Classes:
CoreClientUpgradeRequest, HttpProxy.TunnelRequest, HttpRequest, JavaxClientUpgradeRequest, 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:

  • 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:

    • 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:

    • 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

      @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:

    • 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