HttpExchange (Jetty :: Aggregate :: All core Jetty 7.6.8.v20121106 API)
Date: 2012-11-06

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
    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()`

  - ### 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)

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