org.eclipse.jetty.client

## Class HttpExchange

- java.lang.Object
- - org.eclipse.jetty.client.HttpExchange

Direct Known Subclasses:
  CachedExchange, PropfindExchange, WebdavSupportedExchange

    public class HttpExchange
    extends Object

An HTTP client API that encapsulates an exchange (a request and its response) with a HTTP server.

This object encapsulates:

- The HTTP server address, see `setAddress(Address)`, or `setURI(URI)`, or `setURL(String)`)
- The HTTP request method, URI and HTTP version (see `setMethod(String)`, `setRequestURI(String)`, and `setVersion(int)`)
- The request headers (see `addRequestHeader(String, String)` or `setRequestHeader(String, String)`)
- The request content (see `setRequestContent(Buffer)` or `setRequestContentSource(InputStream)`)
- The status of the exchange (see `getStatus()`)
- Callbacks to handle state changes (see the onXxx methods such as `onRequestComplete()` or `onResponseComplete()`)
- The ability to intercept callbacks (see `setEventListener(HttpEventListener)`

The HttpExchange class is intended to be used by a developer wishing to have close asynchronous interaction with the the exchange.
Typically a developer will extend the HttpExchange class with a derived class that overrides some or all of the onXxx callbacks.
There are also some predefined HttpExchange subtypes that can be used as a basis, see `ContentExchange` and `CachedExchange`.

Typically the HttpExchange is passed to the `HttpClient.send(HttpExchange)` method, which in turn selects a `HttpDestination` and calls its `HttpDestination.send(HttpExchange)`, which then creates or selects a `AbstractHttpConnection` and calls its `AbstractHttpConnection.send(HttpExchange)`. A developer may wish to directly call send on the destination or connection if they wish to bypass some handling provided (eg Cookie handling in the HttpDestination).

In some circumstances, the HttpClient or HttpDestination may wish to retry a HttpExchange (eg. failed pipeline request, authentication retry or redirection). In such cases, the HttpClient and/or HttpDestination may insert their own HttpExchangeListener to intercept and filter the call backs intended for the HttpExchange.

### Nested Class Summary

Nested Classes
`static class` `HttpExchange.CachedExchange` Deprecated. use `CachedExchange` instead
`static class` `HttpExchange.ContentExchange` Deprecated. use `ContentExchange` instead

### Field Summary

Fields
`static int` `STATUS_CANCELLED`
`static int` `STATUS_CANCELLING`
`static int` `STATUS_COMPLETED`
`static int` `STATUS_EXCEPTED`
`static int` `STATUS_EXPIRED`
`static int` `STATUS_PARSING_CONTENT`
`static int` `STATUS_PARSING_HEADERS`
`static int` `STATUS_SENDING_REQUEST`
`static int` `STATUS_START`
`static int` `STATUS_WAITING_FOR_COMMIT`
`static int` `STATUS_WAITING_FOR_CONNECTION`
`static int` `STATUS_WAITING_FOR_RESPONSE`

### Constructor Summary

Constructors
Constructor and Description
`HttpExchange()`

### Method Summary

Methods
`void` `addRequestHeader(Buffer name, Buffer value)` Adds the specified request header
`void` `addRequestHeader(String name, String value)` Adds the specified request header
`void` `cancel()` Initiates the cancelling of this exchange.
`protected void` `cancelTimeout(HttpClient httpClient)`
`boolean` `configureListeners()`
`protected void` `expire(HttpDestination destination)`
`Address` `getAddress()`
`HttpEventListener` `getEventListener()`
`Address` `getLocalAddress()` the local address used by the connection Note: this method will not be populated unless the exchange has been executed by the HttpClient
`String` `getMethod()`
`Buffer` `getRequestContent()`
`Buffer` `getRequestContentChunk(Buffer buffer)`
`InputStream` `getRequestContentSource()`
`HttpFields` `getRequestFields()`
`String` `getRequestURI()`
`boolean` `getRetryStatus()`
`Buffer` `getScheme()`
`int` `getStatus()`
`long` `getTimeout()`
`String` `getURI()` Deprecated.
`int` `getVersion()`
`boolean` `isDone()`
`boolean` `isDone(int status)` Deprecated.
`protected void` `onConnectionFailed(Throwable x)` Callback called when an exception was thrown during an attempt to establish the connection with the server (for example the server is not listening).
`protected void` `onException(Throwable x)` Callback called when any other exception occurs during the handling of this exchange.
`protected void` `onExpire()` Callback called when no response has been received within the timeout.
`protected void` `onRequestCommitted()` Callback called when the request headers have been sent to the server.
`protected void` `onRequestComplete()` Callback called when the request and its body have been sent to the server.
`protected void` `onResponseComplete()` Callback called when the entire response has been received from the server This implementation does nothing.
`protected void` `onResponseContent(Buffer content)` Callback called for each chunk of the response content received from the server.
`protected void` `onResponseHeader(Buffer name, Buffer value)` Callback called for each response header received from the server.
`protected void` `onResponseHeaderComplete()` Callback called when the response headers have been completely received from the server.
`protected void` `onResponseStatus(Buffer version, int status, Buffer reason)` Callback called when a response status line has been received from the server.
`protected void` `onRetry()` Callback called when the request is retried (due to failures or authentication).
`protected Connection` `onSwitchProtocol(EndPoint endp)`
`void` `reset()`
`protected void` `scheduleTimeout(HttpDestination destination)`
`void` `setAddress(Address address)`
`void` `setConfigureListeners(boolean autoConfigure)`
`void` `setEventListener(HttpEventListener listener)`
`void` `setMethod(String method)`
`void` `setRequestContent(Buffer requestContent)`
`void` `setRequestContentSource(InputStream stream)`
`void` `setRequestContentType(String value)`
`void` `setRequestHeader(Buffer name, Buffer value)` Sets the specified request header
`void` `setRequestHeader(String name, String value)` Sets the specified request header
`void` `setRequestURI(String uri)` Set the request URI Per RFC 2616 sec5, Request-URI = "*" | absoluteURI | abs_path | authority where: "*" - request applies to server itself absoluteURI - required for proxy requests, e.g.
`void` `setRetryStatus(boolean retryStatus)`
`void` `setScheme(Buffer scheme)`
`void` `setScheme(String scheme)`
`void` `setTimeout(long timeout)`
`void` `setURI(String uri)` Deprecated.
`void` `setURI(URI uri)`
`void` `setURL(String url)`
`void` `setVersion(int version)`
`void` `setVersion(String version)`
`static String` `toState(int s)`
`String` `toString()`
`int` `waitForDone()` Wait until the exchange is "done".
`void` `waitForStatus(int status)` Deprecated. Use `waitForDone()` instead

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

### Field Detail

#### STATUS_START

    public static final int STATUS_START

See Also:
  Constant Field Values

#### STATUS_WAITING_FOR_CONNECTION

    public static final int STATUS_WAITING_FOR_CONNECTION

See Also:
  Constant Field Values

#### STATUS_WAITING_FOR_COMMIT

    public static final int STATUS_WAITING_FOR_COMMIT

See Also:
  Constant Field Values

#### STATUS_SENDING_REQUEST

    public static final int STATUS_SENDING_REQUEST

See Also:
  Constant Field Values

#### STATUS_WAITING_FOR_RESPONSE

    public static final int STATUS_WAITING_FOR_RESPONSE

See Also:
  Constant Field Values

#### STATUS_PARSING_HEADERS

    public static final int STATUS_PARSING_HEADERS

See Also:
  Constant Field Values

#### STATUS_PARSING_CONTENT

    public static final int STATUS_PARSING_CONTENT

See Also:
  Constant Field Values

#### STATUS_COMPLETED

    public static final int STATUS_COMPLETED

See Also:
  Constant Field Values

#### STATUS_EXPIRED

    public static final int STATUS_EXPIRED

See Also:
  Constant Field Values

#### STATUS_EXCEPTED

    public static final int STATUS_EXCEPTED

See Also:
  Constant Field Values

#### STATUS_CANCELLING

    public static final int STATUS_CANCELLING

See Also:
  Constant Field Values

#### STATUS_CANCELLED

    public static final int STATUS_CANCELLED

See Also:
  Constant Field Values

### Constructor Detail

#### HttpExchange

    public HttpExchange()

### Method Detail

#### expire

    protected void expire(HttpDestination destination)

#### getStatus

    public int getStatus()

#### waitForStatus

    @Deprecated
    public void waitForStatus(int status)
                       throws InterruptedException

Deprecated. Use `waitForDone()` instead

Parameters:
  `status` - the status to wait for
Throws:
  `InterruptedException` - if the waiting thread is interrupted

#### waitForDone

    public int waitForDone()
                    throws InterruptedException

Wait until the exchange is "done". Done is defined as when a final state has been passed to the HttpExchange via the associated onXxx call. Note that an exchange can transit a final state when being used as part of a dialog (eg `SecurityListener`. Done status is thus defined as:

     done == onConnectionFailed || onException || onExpire || onRequestComplete && onResponseComplete

Returns:
  the done status
Throws:
  `InterruptedException`

#### reset

    public void reset()

#### isDone

    public boolean isDone()

#### isDone

    @Deprecated
    public boolean isDone(int status)

Deprecated.

#### getEventListener

    public HttpEventListener getEventListener()

#### setEventListener

    public void setEventListener(HttpEventListener listener)

#### setTimeout

    public void setTimeout(long timeout)

#### getTimeout

    public long getTimeout()

#### setURL

    public void setURL(String url)

Parameters:
  `url` - an absolute URL (for example 'http://localhost/foo/bar?a=1')

#### setAddress

    public void setAddress(Address address)

Parameters:
  `address` - the address of the server

#### getAddress

    public Address getAddress()

Returns:
  the address of the server

#### getLocalAddress

    public Address getLocalAddress()

the local address used by the connection Note: this method will not be populated unless the exchange has been executed by the HttpClient

Returns:
  the local address used for the running of the exchange if available, null otherwise.

#### setScheme

    public void setScheme(Buffer scheme)

Parameters:
  `scheme` - the scheme of the URL (for example 'http')

#### setScheme

    public void setScheme(String scheme)

Parameters:
  `scheme` - the scheme of the URL (for example 'http')

#### getScheme

    public Buffer getScheme()

Returns:
  the scheme of the URL

#### setVersion

    public void setVersion(int version)

Parameters:
  `version` - the HTTP protocol version as integer, 9, 10 or 11 for 0.9, 1.0 or 1.1

#### setVersion

    public void setVersion(String version)

Parameters:
  `version` - the HTTP protocol version as string

#### getVersion

    public int getVersion()

Returns:
  the HTTP protocol version as integer
See Also:
  `setVersion(int)`

#### setMethod

    public void setMethod(String method)

Parameters:
  `method` - the HTTP method (for example 'GET')

#### getMethod

    public String getMethod()

Returns:
  the HTTP method

#### getURI

    @Deprecated
    public String getURI()

Deprecated.

Returns:
  request URI
See Also:
  `getRequestURI()`

#### getRequestURI

    public String getRequestURI()

Returns:
  request URI

#### setURI

    @Deprecated
    public void setURI(String uri)

Deprecated.
Set the request URI

Parameters:
  `uri` - new request URI
See Also:
  `setRequestURI(String)`

#### setRequestURI

    public void setRequestURI(String uri)

Set the request URI Per RFC 2616 sec5, Request-URI = "*" | absoluteURI | abs_path | authority
where:
"*" - request applies to server itself
absoluteURI - required for proxy requests, e.g. http://localhost:8080/context
(this form is generated automatically by HttpClient)
abs_path - used for most methods, e.g. /context
authority - used for CONNECT method only, e.g. localhost:8080
For complete definition of URI components, see RFC 2396 sec3.

Parameters:
  `uri` - new request URI

#### setURI

    public void setURI(URI uri)

Parameters:
  `uri` - an absolute URI (for example 'http://localhost/foo/bar?a=1')

#### addRequestHeader

    public void addRequestHeader(String name,
                        String value)

Adds the specified request header

Parameters:
  `name` - the header name
  `value` - the header value

#### addRequestHeader

    public void addRequestHeader(Buffer name,
                        Buffer value)

Adds the specified request header

Parameters:
  `name` - the header name
  `value` - the header value

#### setRequestHeader

    public void setRequestHeader(String name,
                        String value)

Sets the specified request header

Parameters:
  `name` - the header name
  `value` - the header value

#### setRequestHeader

    public void setRequestHeader(Buffer name,
                        Buffer value)

Sets the specified request header

Parameters:
  `name` - the header name
  `value` - the header value

#### setRequestContentType

    public void setRequestContentType(String value)

Parameters:
  `value` - the content type of the request

#### getRequestFields

    public HttpFields getRequestFields()

Returns:
  the request headers

#### setRequestContent

    public void setRequestContent(Buffer requestContent)

Parameters:
  `requestContent` - the request content

#### setRequestContentSource

    public void setRequestContentSource(InputStream stream)

Parameters:
  `stream` - the request content as a stream

#### getRequestContentSource

    public InputStream getRequestContentSource()

Returns:
  the request content as a stream

#### getRequestContentChunk

    public Buffer getRequestContentChunk(Buffer buffer)
                                  throws IOException

Throws:
  `IOException`

#### getRequestContent

    public Buffer getRequestContent()

Returns:
  the request content

#### getRetryStatus

    public boolean getRetryStatus()

Returns:
  whether a retry will be attempted or not

#### setRetryStatus

    public void setRetryStatus(boolean retryStatus)

Parameters:
  `retryStatus` - whether a retry will be attempted or not

#### cancel

    public void cancel()

Initiates the cancelling of this exchange. The status of the exchange is set to `STATUS_CANCELLING`. Cancelling the exchange is an asynchronous operation with respect to the request/response, and as such checking the request/response status of a cancelled exchange may return undefined results (for example it may have only some of the response headers being sent by the server). The cancelling of the exchange is completed when the exchange status (see `getStatus()`) is `STATUS_CANCELLED`, and this can be waited using `waitForDone()`.

#### toState

    public static String toState(int s)

#### toString

    public String toString()

Overrides:
  `toString` in class `Object`

#### onSwitchProtocol

    protected Connection onSwitchProtocol(EndPoint endp)
                                   throws IOException

Throws:
  `IOException`

#### onRequestCommitted

    protected void onRequestCommitted()
                               throws IOException

Callback called when the request headers have been sent to the server. This implementation does nothing.

Throws:
  `IOException` - allowed to be thrown by overriding code

#### onRequestComplete

    protected void onRequestComplete()
                              throws IOException

Callback called when the request and its body have been sent to the server. This implementation does nothing.

Throws:
  `IOException` - allowed to be thrown by overriding code

#### onResponseStatus

    protected void onResponseStatus(Buffer version,
                        int status,
                        Buffer reason)
                             throws IOException

Callback called when a response status line has been received from the server. This implementation does nothing.

Parameters:
  `version` - the HTTP version
  `status` - the HTTP status code
  `reason` - the HTTP status reason string
Throws:
  `IOException` - allowed to be thrown by overriding code

#### onResponseHeader

    protected void onResponseHeader(Buffer name,
                        Buffer value)
                             throws IOException

Callback called for each response header received from the server. This implementation does nothing.

Parameters:
  `name` - the header name
  `value` - the header value
Throws:
  `IOException` - allowed to be thrown by overriding code

#### onResponseHeaderComplete

    protected void onResponseHeaderComplete()
                                     throws IOException

Callback called when the response headers have been completely received from the server. This implementation does nothing.

Throws:
  `IOException` - allowed to be thrown by overriding code

#### onResponseContent

    protected void onResponseContent(Buffer content)
                              throws IOException

Callback called for each chunk of the response content received from the server. This implementation does nothing.

Parameters:
  `content` - the buffer holding the content chunk
Throws:
  `IOException` - allowed to be thrown by overriding code

#### onResponseComplete

    protected void onResponseComplete()
                               throws IOException

Callback called when the entire response has been received from the server This implementation does nothing.

Throws:
  `IOException` - allowed to be thrown by overriding code

#### onConnectionFailed

    protected void onConnectionFailed(Throwable x)

Callback called when an exception was thrown during an attempt to establish the connection with the server (for example the server is not listening). This implementation logs a warning.

Parameters:
  `x` - the exception thrown attempting to establish the connection with the server

#### onException

    protected void onException(Throwable x)

Callback called when any other exception occurs during the handling of this exchange. This implementation logs a warning.

Parameters:
  `x` - the exception thrown during the handling of this exchange

#### onExpire

    protected void onExpire()

Callback called when no response has been received within the timeout. This implementation logs a warning.

#### onRetry

    protected void onRetry()
                    throws IOException

Callback called when the request is retried (due to failures or authentication). Implementations must reset any consumable content that needs to be sent.

Throws:
  `IOException` - allowed to be thrown by overriding code

#### configureListeners

    public boolean configureListeners()

Returns:
  true if the exchange should have listeners configured for it by the destination, false if this is being managed elsewhere
See Also:
  `setConfigureListeners(boolean)`

#### setConfigureListeners

    public void setConfigureListeners(boolean autoConfigure)

Parameters:
  `autoConfigure` - whether the listeners are configured by the destination or elsewhere

#### scheduleTimeout

    protected void scheduleTimeout(HttpDestination destination)

#### cancelTimeout

    protected void cancelTimeout(HttpClient httpClient)