HttpExchange (Jetty :: Project 8.1.5.v20120716 API)

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
Modifier and Type	Class and Description
`static class`	`HttpExchange.CachedExchange` Deprecated. use `CachedExchange` instead
`static class`	`HttpExchange.ContentExchange` Deprecated. use `ContentExchange` instead

Field Summary

Fields
Modifier and Type	Field and Description
`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()

Constructors
Constructor and Description
`HttpExchange()`

Method Summary

Methods
Modifier and Type	Method and Description
`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)
```

Class HttpExchange

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

STATUS_START

STATUS_WAITING_FOR_CONNECTION

STATUS_WAITING_FOR_COMMIT

STATUS_SENDING_REQUEST

STATUS_WAITING_FOR_RESPONSE

STATUS_PARSING_HEADERS

STATUS_PARSING_CONTENT

STATUS_COMPLETED

STATUS_EXPIRED

STATUS_EXCEPTED

STATUS_CANCELLING

STATUS_CANCELLED

Constructor Detail

HttpExchange

Method Detail

expire

getStatus

waitForStatus

waitForDone

reset

isDone

isDone

getEventListener

setEventListener

setTimeout

getTimeout

setURL

setAddress

getAddress

getLocalAddress

setScheme

setScheme

getScheme

setVersion

setVersion

getVersion

setMethod

getMethod

getURI

getRequestURI

setURI

setRequestURI

setURI

addRequestHeader

addRequestHeader

setRequestHeader

setRequestHeader

setRequestContentType

getRequestFields

setRequestContent

setRequestContentSource

getRequestContentSource

getRequestContentChunk

getRequestContent

getRetryStatus

setRetryStatus

cancel

toState

toString

onSwitchProtocol

onRequestCommitted

onRequestComplete

onResponseStatus

onResponseHeader

onResponseHeaderComplete

onResponseContent

onResponseComplete

onConnectionFailed

onException

onExpire

onRetry

configureListeners

setConfigureListeners