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

static class	HttpExchange.CachedExchange Deprecated. use CachedExchange instead
static class	HttpExchange.ContentExchange Deprecated. use ContentExchange instead

Field Summary

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

HttpExchange()

Method Summary

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)