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:setAddress(Address)
, or setURI(URI)
, or setURL(String)
)
setMethod(String)
, setRequestURI(String)
, and setVersion(int)
)
addRequestHeader(String, String)
or setRequestHeader(String, String)
)
setRequestContent(Buffer)
or setRequestContentSource(InputStream)
)
getStatus()
)
onRequestComplete()
or onResponseComplete()
)
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.
Modifier and Type | Class and Description |
---|---|
static class |
HttpExchange.CachedExchange
Deprecated.
use
CachedExchange instead |
static class |
HttpExchange.ContentExchange
Deprecated.
use
ContentExchange instead |
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 and Description |
---|
HttpExchange() |
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 |
public static final int STATUS_START
public static final int STATUS_WAITING_FOR_CONNECTION
public static final int STATUS_WAITING_FOR_COMMIT
public static final int STATUS_SENDING_REQUEST
public static final int STATUS_WAITING_FOR_RESPONSE
public static final int STATUS_PARSING_HEADERS
public static final int STATUS_PARSING_CONTENT
public static final int STATUS_COMPLETED
public static final int STATUS_EXPIRED
public static final int STATUS_EXCEPTED
public static final int STATUS_CANCELLING
public static final int STATUS_CANCELLED
protected void expire(HttpDestination destination)
public int getStatus()
@Deprecated public void waitForStatus(int status) throws InterruptedException
waitForDone()
insteadstatus
- the status to wait forInterruptedException
- if the waiting thread is interruptedpublic int waitForDone() throws InterruptedException
SecurityListener
. Done status is thus defined as:
done == onConnectionFailed || onException || onExpire || onRequestComplete && onResponseComplete
InterruptedException
public void reset()
public boolean isDone()
@Deprecated public boolean isDone(int status)
public HttpEventListener getEventListener()
public void setEventListener(HttpEventListener listener)
public void setTimeout(long timeout)
public long getTimeout()
public void setURL(String url)
url
- an absolute URL (for example 'http://localhost/foo/bar?a=1')public void setAddress(Address address)
address
- the address of the serverpublic Address getAddress()
public Address getLocalAddress()
public void setScheme(Buffer scheme)
scheme
- the scheme of the URL (for example 'http')public void setScheme(String scheme)
scheme
- the scheme of the URL (for example 'http')public Buffer getScheme()
public void setVersion(int version)
version
- the HTTP protocol version as integer, 9, 10 or 11 for 0.9, 1.0 or 1.1public void setVersion(String version)
version
- the HTTP protocol version as stringpublic int getVersion()
setVersion(int)
public void setMethod(String method)
method
- the HTTP method (for example 'GET')public String getMethod()
@Deprecated public String getURI()
getRequestURI()
public String getRequestURI()
@Deprecated public void setURI(String uri)
uri
- new request URIsetRequestURI(String)
public void setRequestURI(String uri)
uri
- new request URIpublic void setURI(URI uri)
uri
- an absolute URI (for example 'http://localhost/foo/bar?a=1')public void addRequestHeader(String name, String value)
name
- the header namevalue
- the header valuepublic void addRequestHeader(Buffer name, Buffer value)
name
- the header namevalue
- the header valuepublic void setRequestHeader(String name, String value)
name
- the header namevalue
- the header valuepublic void setRequestHeader(Buffer name, Buffer value)
name
- the header namevalue
- the header valuepublic void setRequestContentType(String value)
value
- the content type of the requestpublic HttpFields getRequestFields()
public void setRequestContent(Buffer requestContent)
requestContent
- the request contentpublic void setRequestContentSource(InputStream stream)
stream
- the request content as a streampublic InputStream getRequestContentSource()
public Buffer getRequestContentChunk(Buffer buffer) throws IOException
IOException
public Buffer getRequestContent()
public boolean getRetryStatus()
public void setRetryStatus(boolean retryStatus)
retryStatus
- whether a retry will be attempted or notpublic void cancel()
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()
.public static String toState(int s)
protected Connection onSwitchProtocol(EndPoint endp) throws IOException
IOException
protected void onRequestCommitted() throws IOException
IOException
- allowed to be thrown by overriding codeprotected void onRequestComplete() throws IOException
IOException
- allowed to be thrown by overriding codeprotected void onResponseStatus(Buffer version, int status, Buffer reason) throws IOException
version
- the HTTP versionstatus
- the HTTP status codereason
- the HTTP status reason stringIOException
- allowed to be thrown by overriding codeprotected void onResponseHeader(Buffer name, Buffer value) throws IOException
name
- the header namevalue
- the header valueIOException
- allowed to be thrown by overriding codeprotected void onResponseHeaderComplete() throws IOException
IOException
- allowed to be thrown by overriding codeprotected void onResponseContent(Buffer content) throws IOException
content
- the buffer holding the content chunkIOException
- allowed to be thrown by overriding codeprotected void onResponseComplete() throws IOException
IOException
- allowed to be thrown by overriding codeprotected void onConnectionFailed(Throwable x)
x
- the exception thrown attempting to establish the connection with the serverprotected void onException(Throwable x)
x
- the exception thrown during the handling of this exchangeprotected void onExpire()
protected void onRetry() throws IOException
IOException
- allowed to be thrown by overriding codepublic boolean configureListeners()
setConfigureListeners(boolean)
public void setConfigureListeners(boolean autoConfigure)
autoConfigure
- whether the listeners are configured by the destination or elsewhereprotected void scheduleTimeout(HttpDestination destination)
protected void cancelTimeout(HttpClient httpClient)
Copyright © 1995-2013 Mort Bay Consulting. All Rights Reserved.