Package com.squareup.okhttp.internal.http

Class HttpEngine

  • public final class HttpEngine
extends Object
    Handles a single HTTP request/response pair. Each HTTP engine follows this lifecycle:
    1. It is created.
    2. The HTTP request message is sent with sendRequest(). Once the request is sent it is an error to modify the request headers. After sendRequest() has been called the request body can be written to if it exists.
    3. The HTTP response message is read with readResponse(). After the response has been read the response headers and body can be read. All responses have a response body input stream, though in some instances this stream is empty.

    The request and response may be served by the HTTP response cache, by the network, or by both in the event of a conditional GET.

    • Field Detail

      • MAX_FOLLOW_UPS

        public static final int MAX_FOLLOW_UPS
        How many redirects and auth challenges should we attempt? Chrome follows 21 redirects; Firefox, curl, and wget follow 20; Safari follows 16; and HTTP/1.0 recommends 5.
        See Also:
        Constant Field Values

      • bufferRequestBody

        public final boolean bufferRequestBody
        True if the request body must be completely buffered before transmission; false if it can be streamed. Buffering has two advantages: we don't need the content-length in advance and we can retransmit if necessary. The upside of streaming is that we can save memory.

    • Constructor Detail

      • HttpEngine

        public HttpEngine​(OkHttpClient client,
                  Request request,
                  boolean bufferRequestBody,
                  boolean callerWritesRequestBody,
                  boolean forWebSocket,
                  Connection connection,
                  RouteSelector routeSelector,
                  RetryableSink requestBodyOut,
                  Response priorResponse)
        Parameters:
        request - the HTTP request without a body. The body must be written via the engine's request body stream.
        callerWritesRequestBody - true for the HttpURLConnection-style interaction model where control flow is returned to the calling application to write the request body before the response body is readable.
        connection - the connection used for an intermediate response immediately prior to this request/response pair, such as a same-host redirect. This engine assumes ownership of the connection and must release it when it is unneeded.
        routeSelector - the route selector used for a failed attempt immediately preceding this

    • Method Detail

      • writingRequestHeaders

        public void writingRequestHeaders()
        Called immediately before the transport transmits HTTP request headers. This is used to observe the sent time should the request be cached.

      • getRequestBody

        public Sink getRequestBody()
        Returns the request body or null if this request doesn't have a body.

      • getBufferedRequestBody

        public BufferedSink getBufferedRequestBody()

      • hasResponse

        public boolean hasResponse()

      • getRequest

        public Request getRequest()

      • getResponse

        public Response getResponse()
        Returns the engine's response.

      • getConnection

        public Connection getConnection()

      • recover

        public HttpEngine recover​(RouteException e)
        Attempt to recover from failure to connect via a route. Returns a new HTTP engine that should be used for the retry if there are other routes to try, or null if there are no more routes to try.

      • recover

        public HttpEngine recover​(IOException e,
                          Sink requestBodyOut)
        Report and attempt to recover from a failure to communicate with a server. Returns a new HTTP engine that should be used for the retry if e is recoverable, or null if the failure is permanent. Requests with a body can only be recovered if the body is buffered.

      • getRoute

        public Route getRoute()
        Returns the route used to retrieve the response. Null if we haven't connected yet, or if no connection was necessary.

      • releaseConnection

        public void releaseConnection()
                       throws IOException
        Configure the socket connection to be either pooled or closed when it is either exhausted or closed. If it is unneeded when this is called, it will be released immediately.
        Throws:
        IOException

      • disconnect

        public void disconnect()
        Immediately closes the socket connection if it's currently held by this engine. Use this to interrupt an in-flight request from any thread. It's the caller's responsibility to close the request body and response body streams; otherwise resources may be leaked.

        This method is safe to be called concurrently, but provides limited guarantees. If a transport layer connection has been established (such as a HTTP/2 stream) that is terminated. Otherwise if a socket connection is being established, that is terminated.

      • close

        public Connection close()
        Release any resources held by this engine. If a connection is still held by this engine, it is returned.

      • hasBody

        public static boolean hasBody​(Response response)
        Returns true if the response must have a (possibly 0-length) body. See RFC 2616 section 4.3.

      • readResponse

        public void readResponse()
                  throws IOException
        Flushes the remaining request header and body, parses the HTTP response headers and starts reading the HTTP response body if it exists.
        Throws:
        IOException

      • followUpRequest

        public Request followUpRequest()
                        throws IOException
        Figures out the HTTP request to make in response to receiving this engine's response. This will either add authentication headers or follow redirects. If a follow-up is either unnecessary or not applicable, this returns null.
        Throws:
        IOException

      • sameConnection

        public boolean sameConnection​(HttpUrl followUp)
        Returns true if an HTTP request for followUp can reuse the connection used by this engine.