michael@0: /*
michael@0:  * ====================================================================
michael@0:  * Licensed to the Apache Software Foundation (ASF) under one
michael@0:  * or more contributor license agreements.  See the NOTICE file
michael@0:  * distributed with this work for additional information
michael@0:  * regarding copyright ownership.  The ASF licenses this file
michael@0:  * to you under the Apache License, Version 2.0 (the
michael@0:  * "License"); you may not use this file except in compliance
michael@0:  * with the License.  You may obtain a copy of the License at
michael@0:  *
michael@0:  *   http://www.apache.org/licenses/LICENSE-2.0
michael@0:  *
michael@0:  * Unless required by applicable law or agreed to in writing,
michael@0:  * software distributed under the License is distributed on an
michael@0:  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
michael@0:  * KIND, either express or implied.  See the License for the
michael@0:  * specific language governing permissions and limitations
michael@0:  * under the License.
michael@0:  * ====================================================================
michael@0:  *
michael@0:  * This software consists of voluntary contributions made by many
michael@0:  * individuals on behalf of the Apache Software Foundation.  For more
michael@0:  * information on the Apache Software Foundation, please see
michael@0:  * <http://www.apache.org/>.
michael@0:  *
michael@0:  */
michael@0: 
michael@0: package ch.boye.httpclientandroidlib.protocol;
michael@0: 
michael@0: import java.io.IOException;
michael@0: import java.net.ProtocolException;
michael@0: 
michael@0: import ch.boye.httpclientandroidlib.HttpClientConnection;
michael@0: import ch.boye.httpclientandroidlib.HttpEntity;
michael@0: import ch.boye.httpclientandroidlib.HttpEntityEnclosingRequest;
michael@0: import ch.boye.httpclientandroidlib.HttpException;
michael@0: import ch.boye.httpclientandroidlib.HttpRequest;
michael@0: import ch.boye.httpclientandroidlib.HttpResponse;
michael@0: import ch.boye.httpclientandroidlib.HttpStatus;
michael@0: import ch.boye.httpclientandroidlib.HttpVersion;
michael@0: import ch.boye.httpclientandroidlib.ProtocolVersion;
michael@0: import ch.boye.httpclientandroidlib.params.CoreProtocolPNames;
michael@0: 
michael@0: /**
michael@0:  * HttpRequestExecutor is a client side HTTP protocol handler based on the
michael@0:  * blocking I/O model that implements the essential requirements of the HTTP
michael@0:  * protocol for the client side message  processing, as described by RFC 2616.
michael@0:  * <br>
michael@0:  * HttpRequestExecutor relies on {@link HttpProcessor} to generate mandatory
michael@0:  * protocol headers for all outgoing messages and apply common, cross-cutting
michael@0:  * message transformations to all incoming and outgoing messages. Application
michael@0:  * specific processing can be implemented outside HttpRequestExecutor once the
michael@0:  * request has been executed and a response has been received.
michael@0:  * <p>
michael@0:  * The following parameters can be used to customize the behavior of this
michael@0:  * class:
michael@0:  * <ul>
michael@0:  *  <li>{@link ch.boye.httpclientandroidlib.params.CoreProtocolPNames#WAIT_FOR_CONTINUE}</li>
michael@0:  * </ul>
michael@0:  *
michael@0:  * @since 4.0
michael@0:  */
michael@0: public class HttpRequestExecutor {
michael@0: 
michael@0:     /**
michael@0:      * Create a new request executor.
michael@0:      */
michael@0:     public HttpRequestExecutor() {
michael@0:         super();
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Decide whether a response comes with an entity.
michael@0:      * The implementation in this class is based on RFC 2616.
michael@0:      * <br/>
michael@0:      * Derived executors can override this method to handle
michael@0:      * methods and response codes not specified in RFC 2616.
michael@0:      *
michael@0:      * @param request   the request, to obtain the executed method
michael@0:      * @param response  the response, to obtain the status code
michael@0:      */
michael@0:     protected boolean canResponseHaveBody(final HttpRequest request,
michael@0:                                           final HttpResponse response) {
michael@0: 
michael@0:         if ("HEAD".equalsIgnoreCase(request.getRequestLine().getMethod())) {
michael@0:             return false;
michael@0:         }
michael@0:         int status = response.getStatusLine().getStatusCode();
michael@0:         return status >= HttpStatus.SC_OK
michael@0:             && status != HttpStatus.SC_NO_CONTENT
michael@0:             && status != HttpStatus.SC_NOT_MODIFIED
michael@0:             && status != HttpStatus.SC_RESET_CONTENT;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Sends the request and obtain a response.
michael@0:      *
michael@0:      * @param request   the request to execute.
michael@0:      * @param conn      the connection over which to execute the request.
michael@0:      *
michael@0:      * @return  the response to the request.
michael@0:      *
michael@0:      * @throws IOException in case of an I/O error.
michael@0:      * @throws HttpException in case of HTTP protocol violation or a processing
michael@0:      *   problem.
michael@0:      */
michael@0:     public HttpResponse execute(
michael@0:             final HttpRequest request,
michael@0:             final HttpClientConnection conn,
michael@0:             final HttpContext context)
michael@0:                 throws IOException, HttpException {
michael@0:         if (request == null) {
michael@0:             throw new IllegalArgumentException("HTTP request may not be null");
michael@0:         }
michael@0:         if (conn == null) {
michael@0:             throw new IllegalArgumentException("Client connection may not be null");
michael@0:         }
michael@0:         if (context == null) {
michael@0:             throw new IllegalArgumentException("HTTP context may not be null");
michael@0:         }
michael@0: 
michael@0:         try {
michael@0:             HttpResponse response = doSendRequest(request, conn, context);
michael@0:             if (response == null) {
michael@0:                 response = doReceiveResponse(request, conn, context);
michael@0:             }
michael@0:             return response;
michael@0:         } catch (IOException ex) {
michael@0:             closeConnection(conn);
michael@0:             throw ex;
michael@0:         } catch (HttpException ex) {
michael@0:             closeConnection(conn);
michael@0:             throw ex;
michael@0:         } catch (RuntimeException ex) {
michael@0:             closeConnection(conn);
michael@0:             throw ex;
michael@0:         }
michael@0:     }
michael@0: 
michael@0:     private final static void closeConnection(final HttpClientConnection conn) {
michael@0:         try {
michael@0:             conn.close();
michael@0:         } catch (IOException ignore) {
michael@0:         }
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Pre-process the given request using the given protocol processor and
michael@0:      * initiates the process of request execution.
michael@0:      *
michael@0:      * @param request   the request to prepare
michael@0:      * @param processor the processor to use
michael@0:      * @param context   the context for sending the request
michael@0:      *
michael@0:      * @throws IOException in case of an I/O error.
michael@0:      * @throws HttpException in case of HTTP protocol violation or a processing
michael@0:      *   problem.
michael@0:      */
michael@0:     public void preProcess(
michael@0:             final HttpRequest request,
michael@0:             final HttpProcessor processor,
michael@0:             final HttpContext context)
michael@0:                 throws HttpException, IOException {
michael@0:         if (request == null) {
michael@0:             throw new IllegalArgumentException("HTTP request may not be null");
michael@0:         }
michael@0:         if (processor == null) {
michael@0:             throw new IllegalArgumentException("HTTP processor may not be null");
michael@0:         }
michael@0:         if (context == null) {
michael@0:             throw new IllegalArgumentException("HTTP context may not be null");
michael@0:         }
michael@0:         context.setAttribute(ExecutionContext.HTTP_REQUEST, request);
michael@0:         processor.process(request, context);
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Send the given request over the given connection.
michael@0:      * <p>
michael@0:      * This method also handles the expect-continue handshake if necessary.
michael@0:      * If it does not have to handle an expect-continue handshake, it will
michael@0:      * not use the connection for reading or anything else that depends on
michael@0:      * data coming in over the connection.
michael@0:      *
michael@0:      * @param request   the request to send, already
michael@0:      *                  {@link #preProcess preprocessed}
michael@0:      * @param conn      the connection over which to send the request,
michael@0:      *                  already established
michael@0:      * @param context   the context for sending the request
michael@0:      *
michael@0:      * @return  a terminal response received as part of an expect-continue
michael@0:      *          handshake, or
michael@0:      *          <code>null</code> if the expect-continue handshake is not used
michael@0:      *
michael@0:      * @throws IOException in case of an I/O error.
michael@0:      * @throws HttpException in case of HTTP protocol violation or a processing
michael@0:      *   problem.
michael@0:      */
michael@0:     protected HttpResponse doSendRequest(
michael@0:             final HttpRequest request,
michael@0:             final HttpClientConnection conn,
michael@0:             final HttpContext context)
michael@0:                 throws IOException, HttpException {
michael@0:         if (request == null) {
michael@0:             throw new IllegalArgumentException("HTTP request may not be null");
michael@0:         }
michael@0:         if (conn == null) {
michael@0:             throw new IllegalArgumentException("HTTP connection may not be null");
michael@0:         }
michael@0:         if (context == null) {
michael@0:             throw new IllegalArgumentException("HTTP context may not be null");
michael@0:         }
michael@0: 
michael@0:         HttpResponse response = null;
michael@0: 
michael@0:         context.setAttribute(ExecutionContext.HTTP_CONNECTION, conn);
michael@0:         context.setAttribute(ExecutionContext.HTTP_REQ_SENT, Boolean.FALSE);
michael@0: 
michael@0:         conn.sendRequestHeader(request);
michael@0:         if (request instanceof HttpEntityEnclosingRequest) {
michael@0:             // Check for expect-continue handshake. We have to flush the
michael@0:             // headers and wait for an 100-continue response to handle it.
michael@0:             // If we get a different response, we must not send the entity.
michael@0:             boolean sendentity = true;
michael@0:             final ProtocolVersion ver =
michael@0:                 request.getRequestLine().getProtocolVersion();
michael@0:             if (((HttpEntityEnclosingRequest) request).expectContinue() &&
michael@0:                 !ver.lessEquals(HttpVersion.HTTP_1_0)) {
michael@0: 
michael@0:                 conn.flush();
michael@0:                 // As suggested by RFC 2616 section 8.2.3, we don't wait for a
michael@0:                 // 100-continue response forever. On timeout, send the entity.
michael@0:                 int tms = request.getParams().getIntParameter(
michael@0:                         CoreProtocolPNames.WAIT_FOR_CONTINUE, 2000);
michael@0: 
michael@0:                 if (conn.isResponseAvailable(tms)) {
michael@0:                     response = conn.receiveResponseHeader();
michael@0:                     if (canResponseHaveBody(request, response)) {
michael@0:                         conn.receiveResponseEntity(response);
michael@0:                     }
michael@0:                     int status = response.getStatusLine().getStatusCode();
michael@0:                     if (status < 200) {
michael@0:                         if (status != HttpStatus.SC_CONTINUE) {
michael@0:                             throw new ProtocolException(
michael@0:                                     "Unexpected response: " + response.getStatusLine());
michael@0:                         }
michael@0:                         // discard 100-continue
michael@0:                         response = null;
michael@0:                     } else {
michael@0:                         sendentity = false;
michael@0:                     }
michael@0:                 }
michael@0:             }
michael@0:             if (sendentity) {
michael@0:                 conn.sendRequestEntity((HttpEntityEnclosingRequest) request);
michael@0:             }
michael@0:         }
michael@0:         conn.flush();
michael@0:         context.setAttribute(ExecutionContext.HTTP_REQ_SENT, Boolean.TRUE);
michael@0:         return response;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Waits for and receives a response.
michael@0:      * This method will automatically ignore intermediate responses
michael@0:      * with status code 1xx.
michael@0:      *
michael@0:      * @param request   the request for which to obtain the response
michael@0:      * @param conn      the connection over which the request was sent
michael@0:      * @param context   the context for receiving the response
michael@0:      *
michael@0:      * @return  the terminal response, not yet post-processed
michael@0:      *
michael@0:      * @throws IOException in case of an I/O error.
michael@0:      * @throws HttpException in case of HTTP protocol violation or a processing
michael@0:      *   problem.
michael@0:      */
michael@0:     protected HttpResponse doReceiveResponse(
michael@0:             final HttpRequest          request,
michael@0:             final HttpClientConnection conn,
michael@0:             final HttpContext          context)
michael@0:                 throws HttpException, IOException {
michael@0:         if (request == null) {
michael@0:             throw new IllegalArgumentException("HTTP request may not be null");
michael@0:         }
michael@0:         if (conn == null) {
michael@0:             throw new IllegalArgumentException("HTTP connection may not be null");
michael@0:         }
michael@0:         if (context == null) {
michael@0:             throw new IllegalArgumentException("HTTP context may not be null");
michael@0:         }
michael@0: 
michael@0:         HttpResponse response = null;
michael@0:         int statuscode = 0;
michael@0: 
michael@0:         while (response == null || statuscode < HttpStatus.SC_OK) {
michael@0: 
michael@0:             response = conn.receiveResponseHeader();
michael@0:             if (canResponseHaveBody(request, response)) {
michael@0:                 conn.receiveResponseEntity(response);
michael@0:             }
michael@0:             statuscode = response.getStatusLine().getStatusCode();
michael@0: 
michael@0:         } // while intermediate response
michael@0: 
michael@0:         return response;
michael@0: 
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Post-processes the given response using the given protocol processor and
michael@0:      * completes the process of request execution.
michael@0:      * <p>
michael@0:      * This method does <i>not</i> read the response entity, if any.
michael@0:      * The connection over which content of the response entity is being
michael@0:      * streamed from cannot be reused until {@link HttpEntity#consumeContent()}
michael@0:      * has been invoked.
michael@0:      *
michael@0:      * @param response  the response object to post-process
michael@0:      * @param processor the processor to use
michael@0:      * @param context   the context for post-processing the response
michael@0:      *
michael@0:      * @throws IOException in case of an I/O error.
michael@0:      * @throws HttpException in case of HTTP protocol violation or a processing
michael@0:      *   problem.
michael@0:      */
michael@0:     public void postProcess(
michael@0:             final HttpResponse response,
michael@0:             final HttpProcessor processor,
michael@0:             final HttpContext context)
michael@0:                 throws HttpException, IOException {
michael@0:         if (response == null) {
michael@0:             throw new IllegalArgumentException("HTTP response may not be null");
michael@0:         }
michael@0:         if (processor == null) {
michael@0:             throw new IllegalArgumentException("HTTP processor may not be null");
michael@0:         }
michael@0:         if (context == null) {
michael@0:             throw new IllegalArgumentException("HTTP context may not be null");
michael@0:         }
michael@0:         context.setAttribute(ExecutionContext.HTTP_RESPONSE, response);
michael@0:         processor.process(response, context);
michael@0:     }
michael@0: 
michael@0: } // class HttpRequestExecutor