Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.eclipse.jetty.client
Class HttpExchange

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

Direct Known Subclasses:
  CachedExchange, PropfindExchange, WebdavSupportedExchange

    public class HttpExchange

extends java.lang.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 `setURL(String)`)
- The HTTP request method, URI and HTTP version (see `setMethod(String)`, `setURI(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 `HttpConnection` and calls its `HttpConnection.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(java.lang.String name, java.lang.String value)` Adds the specified request header
`void` | `cancel()` Initiates the cancelling of this exchange.
`boolean` | `configureListeners()`
`Address` | `getAddress()`
`HttpEventListener` | `getEventListener()`
`java.lang.String` | `getMethod()`
`Buffer` | `getRequestContent()`
`Buffer` | `getRequestContentChunk()`
`java.io.InputStream` | `getRequestContentSource()`
`HttpFields` | `getRequestFields()`
`boolean` | `getRetryStatus()`
`Buffer` | `getScheme()`
`int` | `getStatus()`
`long` | `getTimeout()`
`java.lang.String` | `getURI()`
`int` | `getVersion()`
`boolean` | `isDone()`
`boolean` | `isDone(int status)` Deprecated.
`protected void` | `onConnectionFailed(java.lang.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(java.lang.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()`
`void` | `setAddress(Address address)`
`void` | `setConfigureListeners(boolean autoConfigure)`
`void` | `setEventListener(HttpEventListener listener)`
`void` | `setMethod(java.lang.String method)`
`void` | `setRequestContent(Buffer requestContent)`
`void` | `setRequestContentSource(java.io.InputStream stream)`
`void` | `setRequestContentType(java.lang.String value)`
`void` | `setRequestHeader(Buffer name, Buffer value)` Sets the specified request header
`void` | `setRequestHeader(java.lang.String name, java.lang.String value)` Sets the specified request header
`void` | `setRetryStatus(boolean retryStatus)`
`void` | `setScheme(Buffer scheme)`
`void` | `setTimeout(long timeout)`
`void` | `setURI(java.lang.String uri)`
`void` | `setURL(java.lang.String url)`
`void` | `setVersion(int version)`
`void` | `setVersion(java.lang.String version)`
`java.lang.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

### getStatus

    public int getStatus()

### waitForStatus

    @Deprecated
    public void waitForStatus(int status)
                       throws java.lang.InterruptedException

  Deprecated. Use `waitForDone()` instead

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

### waitForDone

    public int waitForDone()
                    throws java.lang.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:
    `java.lang.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(java.lang.String url)

  Parameters:
    `url` - Including protocol, host and port

### setAddress

    public void setAddress(Address address)

  Parameters:
    `address` - the address of the server

### getAddress

    public Address getAddress()

  Returns:
    the address of the server

### setScheme

    public void setScheme(Buffer 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(java.lang.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(java.lang.String method)

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

### getMethod

    public java.lang.String getMethod()

  Returns:
    the HTTP method

### getURI

    public java.lang.String getURI()

  Returns:
    the path of the URL

### setURI

    public void setURI(java.lang.String uri)

  Parameters:
    `uri` - the path of the URL (for example '/foo/bar?a=1')

### addRequestHeader

    public void addRequestHeader(java.lang.String name,
                                 java.lang.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(java.lang.String name,
                                 java.lang.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(java.lang.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(java.io.InputStream stream)

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

### getRequestContentSource

    public java.io.InputStream getRequestContentSource()

  Returns:
    the request content as a stream

### getRequestContentChunk

    public Buffer getRequestContentChunk()
                                  throws java.io.IOException

  Throws:
    `java.io.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()`.

### toString

    public java.lang.String toString()

  Overrides:
    `toString` in class `java.lang.Object`

### onSwitchProtocol

    protected Connection onSwitchProtocol(EndPoint endp)
                                   throws java.io.IOException

  Throws:
    `java.io.IOException`

### onRequestCommitted

    protected void onRequestCommitted()
                               throws java.io.IOException

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

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

### onRequestComplete

    protected void onRequestComplete()
                              throws java.io.IOException

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

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

### onResponseStatus

    protected void onResponseStatus(Buffer version,
                                    int status,
                                    Buffer reason)
                             throws java.io.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:
    `java.io.IOException` - allowed to be thrown by overriding code

### onResponseHeader

    protected void onResponseHeader(Buffer name,
                                    Buffer value)
                             throws java.io.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:
    `java.io.IOException` - allowed to be thrown by overriding code

### onResponseHeaderComplete

    protected void onResponseHeaderComplete()
                                     throws java.io.IOException

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

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

### onResponseContent

    protected void onResponseContent(Buffer content)
                              throws java.io.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:
    `java.io.IOException` - allowed to be thrown by overriding code

### onResponseComplete

    protected void onResponseComplete()
                               throws java.io.IOException

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

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

### onConnectionFailed

    protected void onConnectionFailed(java.lang.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(java.lang.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 java.io.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:
    `java.io.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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 1995-2010 Mort Bay Consulting. All Rights Reserved.