hc-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Httpcomponents Wiki] Update of "HttpClientTutorial" by OlegKalnichevski
Date Tue, 17 Mar 2009 21:03:36 GMT
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: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org


Mime
View raw message