/usr/share/doc/libcommons-httpclient-java/docs/exception-handling.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>HttpClient - HttpClient exception handling guide</title><style type="text/css" media="all">
          @import url("./style/maven-base.css");
          
          @import url("./style/maven-theme.css");@import url("./style/project.css");</style><link rel="stylesheet" href="./style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta><meta name="author" content="Oleg Kalnichevski"></meta><meta name="email" content="oleg -at- ural.ru"></meta></head><body class="composite"><div id="banner"><a href="http://jakarta.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src=""></img></a><a href="http://jakarta.apache.org/httpcomponents/httpclient-3.x/" id="projectLogo"><img alt="HttpClient" src="./images/httpclient_logo.png"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">Last published: 18 August 2007
                <span class="separator">|</span> Doc for  3.1
                </div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuOverview"><h5>Overview</h5><ul><li class="none"><a href="features.html">Features</a></li><li class="none"><a href="news.html">News</a></li><li class="none"><a href="status.html">Status</a></li><li class="none"><a href="downloads.html">Download</a></li><li class="none"><a href="http://wiki.apache.org/jakarta-httpclient/" class="externalLink" title="External Link">Wiki</a></li><li class="expanded"><a href="userguide.html">User Guide</a><ul><li class="none"><a href="authentication.html">Authentication Guide</a></li><li class="none"><a href="charencodings.html">Character Encodings</a></li><li class="none"><a href="cookies.html">Cookies</a></li><li class="none"><strong><a href="exception-handling.html">Exception Handling</a></strong></li><li class="none"><a href="logging.html">Logging Guide</a></li><li class="none"><a href="methods.html">Methods</a></li><li class="none"><a href="performance.html">Optimization Guide</a></li><li class="none"><a href="preference-api.html">Preference Architecture</a></li><li class="none"><a href="redirects.html">Redirects Handling</a></li><li class="none"><a href="http://svn.apache.org/viewvc/jakarta/httpcomponents/oac.hc3x/trunk/src/examples/" class="externalLink" title="External Link">Sample Code</a></li><li class="none"><a href="sslguide.html">SSL Guide</a></li><li class="none"><a href="threading.html">Threading</a></li><li class="none"><a href="troubleshooting.html">Trouble Shooting</a></li><li class="none"><a href="tutorial.html">Tutorial</a></li></ul></li><li class="none"><a href="developerguide.html">Developer Guide</a></li></ul></div><div id="menuProject_Documentation"><h5>Project Documentation</h5><ul><li class="none"><a href="index.html">About</a></li><li class="collapsed"><a href="project-info.html">Project Info</a></li><li class="collapsed"><a href="maven-reports.html">Project Reports</a></li><li class="none"><a href="development-process.html">Development Process</a></li></ul></div><div id="legend"><h5>Legend</h5><ul><li class="externalLink">External Link</li><li class="newWindow">Opens in a new window</li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="./images/logos/mavenlogo_builtby_w.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Exception_handling"></a><h2>Exception handling</h2>
        <p>
            There are two main type of exceptions that the user of HttpClient may encounter 
            when executing HTTP methods:
            <ol>
                <li><strong>transport exceptions</strong></li>
                <li><strong>protocol exceptions</strong></li>
            </ol>
            Not all of these exceptions will be propagated to the user in regular HttpClient use.  
            Exceptions handled internally by HttpClient are marked below as <b>INTERNAL</b>.
        </p>
        <ul>
            <li><a href="#Transport_exceptions">Transport exceptions</a></li>
            <li><a href="#Protocol_exceptions">Protocol exceptions</a></li>
            <li><a href="#HTTP_transport_safety">HTTP transport safety</a></li>
            <li><a href="#Automatic_exception_recovery">Automatic exception recovery</a></li>
            <li><a href="#Custom_exception_handler">Custom exception handler</a></li>
        </ul>
    </div><div class="section"><a name="Transport_exceptions"></a><h2>Transport exceptions</h2>
     <p>
      Transport exceptions are those caused by input/output failures such as an unreliable connection 
      or an inability to complete the execution of an HTTP method within the given time constraint 
      (socket timeout). Generally transport exceptions are non-fatal and may be recovered from by 
      retrying the failed method. However, special care must be taken when recovering from 
      exceptions in non-idempotent methods (refer to <a href="#HTTP_transport_safety">HTTP transport safety</a> 
      for details). 
     </p>
     <div class="subsection"><a name="java_io_IOException"></a><h3>java.io.IOException</h3>
     <p>
      Generic transport exceptions in HttpClient are represented by the standard Java 
      java.io.IOException class or its sub classes such as java.net.SocketException and
      java.net.InterruptedIOException.
     </p>
     <p>
      In addition to standard input/output exception classes HttpClient defines several custom transport 
      exceptions that convey HttpClient specific information.
     </p>
     </div>
     <div class="subsection"><a name="org_apache_commons_httpclient_NoHttpResponseException"></a><h3>org.apache.commons.httpclient.NoHttpResponseException</h3>
      
    <div class="source"><pre>
java.io.IOException
  +- org.apache.commons.httpclient.NoHttpResponseException</pre></div>
  
     <p>
      In some circumstances, usually when under heavy load, the web server may be able to receive 
      requests but unable to process them.  A lack of sufficient resources like worker threads is a good
      example. This may cause the server to drop the connection to the client 
      without giving any response. HttpClient throws NoHttpResponseException when it encounters 
      such a condition. In most cases it is safe to retry a method that failed with 
      NoHttpResponseException.
     </p>
     </div>
     <div class="subsection"><a name="org_apache_commons_httpclient_ConnectTimeoutException"></a><h3>org.apache.commons.httpclient.ConnectTimeoutException</h3>
      
    <div class="source"><pre>
java.io.IOException
  +- java.io.InterruptedIOException
    +- org.apache.commons.httpclient.ConnectTimeoutException</pre></div>
  
     <p>
      This exception signals that HttpClient is unable to establish a connection with the target 
      server or proxy server within the given period of time.
     </p>
     </div>
     <div class="subsection"><a name="org_apache_commons_httpclient_ConnectionPoolTimeoutException"></a><h3>org.apache.commons.httpclient.ConnectionPoolTimeoutException</h3>
      
    <div class="source"><pre>
java.io.IOException
  +- java.io.InterruptedIOException
    +- org.apache.commons.httpclient.ConnectTimeoutException
      +- org.apache.commons.httpclient.ConnectionPoolTimeoutException</pre></div>
  
     <p>
      This exception can only occur when using the multithreaded connection manager. The exception 
      signals that the connection manager fails to obtain a free connection from the connection pool 
      within the given period of time.
     </p>
     </div>
     <div class="subsection"><a name="org_apache_commons_httpclient_HttpRecoverableException"></a><h3>org.apache.commons.httpclient.HttpRecoverableException</h3>
      
    <div class="source"><pre>
java.io.IOException
  +- org.apache.commons.httpclient.HttpException
    +- org.apache.commons.httpclient.HttpRecoverableException</pre></div>
  
     <p>
      Deprecated and no longer thrown any of the standard HttpClient classes.
     </p>
     </div>
    </div><div class="section"><a name="Protocol_exceptions"></a><h2>Protocol exceptions</h2>
     <p>
      Protocol exceptions generally indicate logical errors caused by a mismatch between the client 
      and the server (web server or proxy server) in their interpretation of the HTTP specification. 
      Usually protocol exceptions cannot be recovered from without making adjustments to either 
      the client request or the server. Some aspects of the HTTP specification allow for different, 
      at times conflicting, interpretations. HttpClient can be configured to support different degrees 
      of HTTP specification compliance varying from very lenient to very strict. 
     </p>
     <div class="subsection"><a name="org_apache_commons_httpclient_HttpException"></a><h3>org.apache.commons.httpclient.HttpException</h3>
      
    <div class="source"><pre>
java.io.IOException
  +- org.apache.commons.httpclient.HttpException</pre></div>
  
     <p>
      HttpException represents an abstract logical error in HttpClient. Generally this kind of exception
      cannot be automatically recovered from.
     </p>
     </div>
     <div class="subsection"><a name="org_apache_commons_httpclient_ProtocolException"></a><h3>org.apache.commons.httpclient.ProtocolException</h3>
      
    <div class="source"><pre>
java.io.IOException
  +- org.apache.commons.httpclient.HttpException
    +- org.apache.commons.httpclient.ProtocolException</pre></div>
  
     <p>
      ProtocolException signals a violation of the HTTP specification. It is important to note that HTTP 
      proxies and HTTP servers can have different level of HTTP specification compliance. It may be 
      possible to recover from some HTTP protocol exceptions by configuring HttpClient to be more 
      lenient about non-fatal protocol violations.
     </p>
     </div>
     <div class="subsection"><a name="org_apache_commons_httpclient_auth_MalformedChallengeException"></a><h3>org.apache.commons.httpclient.auth.MalformedChallengeException</h3>
      
    <div class="source"><pre>
java.io.IOException
  +- org.apache.commons.httpclient.HttpException
    +- org.apache.commons.httpclient.ProtocolException
      +- org.apache.commons.httpclient.auth.MalformedChallengeException</pre></div>
  
     <p><b>INTERNAL</b></p>
     <p>
      MalformedChallengeException signals that an authentication challenge is in some way invalid or 
      illegal in the given authentication context.
     </p>
     </div>
     <div class="subsection"><a name="org_apache_commons_httpclient_auth_AuthenticationException"></a><h3>org.apache.commons.httpclient.auth.AuthenticationException</h3>
      
    <div class="source"><pre>
java.io.IOException
  +- org.apache.commons.httpclient.HttpException
    +- org.apache.commons.httpclient.ProtocolException
      +- org.apache.commons.httpclient.auth.AuthenticationException</pre></div>
  
     <p><b>INTERNAL</b></p>
     <p>
      AuthenticationException signals a failure in the authentication process. Usually authentication 
      exceptions are handled internally when executing HTTP methods and are not propagated to the 
      caller.
     </p>
     </div>
     <div class="subsection"><a name="org_apache_commons_httpclient_auth_AuthChallengeException"></a><h3>org.apache.commons.httpclient.auth.AuthChallengeException</h3>
      
    <div class="source"><pre>
java.io.IOException
  +- org.apache.commons.httpclient.HttpException
    +- org.apache.commons.httpclient.ProtocolException
      +- org.apache.commons.httpclient.auth.AuthenticationException
        +- org.apache.commons.httpclient.auth.AuthChallengeException</pre></div>
  
     <p><b>INTERNAL</b></p>
     <p>
      AuthenticationException is thrown when HttpClient is unable to respond to any of the authentication 
      challenges sent by the server.
     </p>
     </div>
     <div class="subsection"><a name="org_apache_commons_httpclient_auth_CredentialsNotAvailableException"></a><h3>org.apache.commons.httpclient.auth.CredentialsNotAvailableException</h3>
      
    <div class="source"><pre>
java.io.IOException
  +- org.apache.commons.httpclient.HttpException
    +- org.apache.commons.httpclient.ProtocolException
      +- org.apache.commons.httpclient.auth.AuthenticationException
        +- org.apache.commons.httpclient.auth.CredentialsNotAvailableException</pre></div>
  
     <p><b>INTERNAL</b></p>
     <p>
      CredentialsNotAvailableException indicates that credentials required to respond to the authentication
      challenge are not available.
     </p>
     </div>
     <div class="subsection"><a name="org_apache_commons_httpclient_auth_InvalidCredentialsException"></a><h3>org.apache.commons.httpclient.auth.InvalidCredentialsException</h3>
      
    <div class="source"><pre>
java.io.IOException
  +- org.apache.commons.httpclient.HttpException
    +- org.apache.commons.httpclient.ProtocolException
      +- org.apache.commons.httpclient.auth.AuthenticationException
        +- org.apache.commons.httpclient.auth.InvalidCredentialsException</pre></div>
  
     <p><b>INTERNAL</b></p>
     <p>
      InvalidCredentialsException indicates that the credentials used to respond to the authentication
      challenge have been rejected by the server.
     </p>
     </div>
     <div class="subsection"><a name="org_apache_commons_httpclient_cookie_MalformedCookieException"></a><h3>org.apache.commons.httpclient.cookie.MalformedCookieException</h3>
      
    <div class="source"><pre>
java.io.IOException
  +- org.apache.commons.httpclient.HttpException
    +- org.apache.commons.httpclient.ProtocolException
      +- org.apache.commons.httpclient.cookie.MalformedCookieException</pre></div>
  
     <p><b>INTERNAL</b></p>
     <p>
      MalformedCookieException signals that the cookie is in some way invalid or illegal in the given 
      HTTP session context.
     </p>
     <p>
      There are several cookie specifications that are often incompatible. Thus the validity of 
      a cookie is established within a context of a specific cookie specification used to parse 
      and validate the cookie header(s) sent by the server. If the application needs to process cookies
      differently from the commonly used cookie specifications, it may choose to provide a 
      custom cookie policy or extend the existing one.  Please see <a href="cookies.html">cookies</a> 
      for more details.
     </p>
     </div>
     <div class="subsection"><a name="org_apache_commons_httpclient_RedirectException"></a><h3>org.apache.commons.httpclient.RedirectException</h3>
      
    <div class="source"><pre>
java.io.IOException
  +- org.apache.commons.httpclient.HttpException
    +- org.apache.commons.httpclient.ProtocolException
      +- org.apache.commons.httpclient.RedirectException</pre></div>
  
     <p>
      RedirectException signals violation of the HTTP specification caused by an invalid 
      redirect response. If the application that uses HttpClient needs to be more lenient
      about redirect responses, it may choose to disable automatic redirect processing and implement
      a custom redirect strategy.
     </p>
     </div>
     <div class="subsection"><a name="org_apache_commons_httpclient_URIException"></a><h3>org.apache.commons.httpclient.URIException</h3>
      
    <div class="source"><pre>
java.io.IOException
  +- org.apache.commons.httpclient.HttpException
    +- org.apache.commons.httpclient.URIException</pre></div>
  
     <p>
      URIException is thrown when the request URI violates the URI specification.
     </p>
     </div>
   </div><div class="section"><a name="HTTP_transport_safety"></a><h2>HTTP transport safety</h2>
     <p>
     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.
     </p>
     <p>
      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.
     </p>
     <div class="subsection"><a name="Idempotent_methods"></a><h3>Idempotent methods</h3>
       <p>HTTP/1.1 specification defines idempotent method as</p>
        <blockquote> 
         <p>
          Methods can also have the property of "idempotence" in that (aside from error or expiration 
          issues) the side-effects of N &gt; 0 identical requests is the same as for a single request. 
         </p>
        </blockquote>
       <p>
         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.
        </p>
       <p>
         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.
        </p>
     </div>
   </div><div class="section"><a name="Automatic_exception_recovery"></a><h2>Automatic exception recovery</h2>
     <p>
     By default HttpClient attempts to automatically recover from exceptions. The default 
     auto-recovery mechanism is limited to just a few exceptions that are known to be safe.
     </p>
     <p>
     HttpClient will make no attempt to recover from any logical or HTTP protocol error (those derived
     from HttpException class).
     </p>
     <p>
     HttpClient will automatically retry up to 5 times 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).
     </p>
     <p>
     HttpClient will automatically retry up to 5 times 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.
     </p>
   </div><div class="section"><a name="Custom_exception_handler"></a><h2>Custom exception handler</h2>
     <p>
     In order to enable a custom exception recovery mechanism one should provide an implementation
     of the <a href="apidocs/org/apache/commons/httpclient/HttpMethodRetryHandler.html">
     HttpMethodRetryHandler</a> interface.
     </p>
      
    <div class="source"><pre>
HttpClient client = new HttpClient();

HttpMethodRetryHandler myretryhandler = new HttpMethodRetryHandler() {
    public boolean retryMethod(
        final HttpMethod method, 
        final IOException exception, 
        int executionCount) {
        if (executionCount &gt;= 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 (!method.isRequestSent()) {
            // Retry if the request has not been sent fully or
            // if it's OK to retry methods that have been sent
            return true;
        }
        // otherwise do not retry
        return false;
    }
};
        
GetMethod httpget = new GetMethod("http://www.whatever.com/");
httpget.getParams().
    setParameter(HttpMethodParams.RETRY_HANDLER, myretryhandler);
try {
    client.executeMethod(httpget);
    System.out.println(httpget.getStatusLine().toString());
} finally {
    httpget.releaseConnection();
}</pre></div>
  
   </div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2001-2007, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
libcommons-httpclient-java-doc 3.1-14 / usr / share / doc / libcommons-httpclient-java / docs / exception-handling.html
