Dear Wiki user, You have subscribed to a wiki page or wiki category on "Httpcomponents Wiki" for change notification.
The following page has been changed by OlegKalnichevski: http://wiki.apache.org/HttpComponents/HttpClientTutorial ------------------------------------------------------------------------------ == What HttpClient is NOT == - * HttpClient is NOT a browser. It is a client side HTTP transport library. HttpClient's purpose is to transmit and receive HTTP messages. HttpClient will not attempt to cache content, perform content transformation of any kind, execute javascript embedded in HTML pages, try to guess content type, or reformat request / redirect location URIs. + * HttpClient is NOT a browser. It is a client side HTTP transport library. HttpClient's purpose is to transmit and receive HTTP messages. HttpClient will not attempt to cache content, execute javascript embedded in HTML pages, try to guess content type, or reformat request / redirect location URIs. = Fundamentals = @@ -159, +159 @@ Set-Cookie: c2=b; path="/", c3=c; domain="localhost" }}} - It also provides convenience methods to parse HTTP messages into individual header elements. + It also provides convenience methods to parse HTTP messages into individual header elements. {{{ HttpResponse response = new BasicHttpResponse(HttpVersion.HTTP_1_1, @@ -318, +318 @@ public void writeTo(OutputStream outstream) throws IOException { Writer writer = new OutputStreamWriter(outstream, "UTF-8"); writer.write("<response>"); - writer.write("<content>"); + writer.write(" <content>"); - writer.write("important stuff"); + writer.write(" important stuff"); - writer.write("<c/ontent>"); + writer.write(" </content>"); writer.write("</response>"); writer.flush(); } @@ -385, +385 @@ === Exception handling === - Fatal and recoverable exceptions. - + HttpClient can throw two types of exceptions: IOException in case of an I/O failure such as socket timeout or an socket reset and HttpException that signals an HTTP failure such as a violation of the HTTP protocol. Usually I/O errors are considered non-fatal and recoverable, whereas HTTP protocol errors are considered fatal and cannot be automatically recovered from. + + ==== HTTP transport safety ==== + + It is important to understand that the HTTP protocol is not well suited for all types of applications. HTTP is a simple request/response oriented protocol which was initially designed to support static or dynamically generated content retrieval. It has never been intended to support transactional operations. For instance, the HTTP server will consider its part of the contract fulfilled if it succeeds in receiving and processing the request, generating a response and sending a status code back to the client. The server will make no attempts to roll back the transaction if the client fails to receive the response in its entirety due to a read timeout, a request cancellation or a system crash. If the client decides to retry the same request, the server will inevitably end up executing the same transaction more than once. In some cases this may lead to application data corruption or inconsistent application state. + + Even though HTTP has never been designed to support transactional processing, it can still be used as a transport protocol for mission critical applications provided certain conditions are met. To ensure HTTP transport layer safety the system must ensure the idempotency of HTTP methods on the application layer. + + ==== Idempotent methods ==== + + HTTP/1.1 specification defines idempotent method as + + {{{ + Methods can also have the property of "idempotence" in that (aside from error or expiration issues) + the side-effects of N > 0 identical requests is the same as for a single request + }}} + + In other words the application ought to ensure that it is prepared to deal with the implications of multiple execution of the same method. This can be achieved, for instance, by providing a unique transaction id and by other means of avoiding execution of the same logical operation. + + Please note that this problem is not specific to HttpClient. Browser based applications are subject to exactly the same issues related to HTTP methods non-idempotency. + + HttpClient assumes non-entity enclosing methods such as GET and HEAD to be idempotent and entity enclosing methods such as POST and PUT to be not. + + ==== Automatic exception recovery ==== + + By default HttpClient attempts to automatically recover from I/O exceptions. The default auto-recovery mechanism is limited to just a few exceptions that are known to be safe. + + * HttpClient will make no attempt to recover from any logical or HTTP protocol errors (those derived from HttpException class). + + * HttpClient will automatically retry those methods that are assumed to be idempotent. + + * HttpClient will automatically retry those methods that fail with a transport exception while the HTTP request is still being transmitted to the target server (i.e. the request has not been fully transmitted to the server). + + * HttpClient will automatically retry those methods that have been fully transmitted to the server, but the server failed to respond with an HTTP status code (the server simply drops the connection without sending anything back). In this case it is assumed that the request has not been processed by the server and the application state has not changed. If this assumption may not hold true for the web server your application is targeting it is highly recommended to provide a custom exception handler. + - Request retry handler + ==== Request retry handler ==== + + In order to enable a custom exception recovery mechanism one should provide an implementation of the HttpRequestRetryHandler interface. + + {{{ + DefaultHttpClient httpclient = new DefaultHttpClient(); + + HttpRequestRetryHandler myRetryHandler = new HttpRequestRetryHandler() { + + public boolean retryRequest( + IOException exception, + int executionCount, + HttpContext context) { + if (executionCount >= 5) { + // Do not retry if over max retry count + return false; + } + if (exception instanceof NoHttpResponseException) { + // Retry if the server dropped connection on us + return true; + } + if (exception instanceof SSLHandshakeException) { + // Do not retry on SSL handshake exception + return false; + } + HttpRequest request = (HttpRequest) context.getAttribute( + ExecutionContext.HTTP_REQUEST); + boolean idempotent = !(request instanceof HttpEntityEnclosingRequest); + if (idempotent) { + // Retry if the request is considered idempotent + return true; + } + return false; + } + + }; + + httpclient.setHttpRequestRetryHandler(myRetryHandler); + }}} === Aborting requests === + + In some situations HTTP request execution fail to complete within the expected time frame due to high load on the target server or too many concurrent requests executed on the client side. In such cases it may be necessary to terminate the request prematurely and unblock the execution thread blocked in a I/O operation. HTTP requests being executed by HttpClient can be aborted at any stage of execution by invoking HttpUriRequest#abort method. This method is thread-safe and can be called from any thread. When an HTTP request is aborted its execution thread blocked in an I/O operation is guaranteed to unblock by throwing a InterruptedIOException == HTTP execution context == --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
