HttpClient入门指南

概述

本指南旨在提供一个如何使用HttpClient的一个入门指南，完成此教程后，你将能够使用HttpClient编写一个下载页面的简单例子。我们假定你已经了解如何用java编程，并且熟悉你所有使用的开发环境。

 

准备

第一，获取HttpClient以及HttpClient的相关依赖包，本教程为HttpClient3.0编写的，需JDK1.3或以上版本。

第二，把下载的HttpClient及其依赖包加入到类路径中。在JSSE使用HTTS连接，还需要一个可选的依赖；在此教程中并不是必须的。

 

概念

使用HttpClient的一般流程包括如下步骤：

1，创建HttpClient的实例

2，创建方法（Method）的实例（在本教程中是GetMethod）.连接的URL作为构造方法的参数。

3，HttpClient执行这个方法（Method）。

4，读取响应。

5，释放连接。

6，处理响应。

本教程包括了如何完成以上所示的步骤，请注意，我们关注HttpClient整个流程但是忽略服务端返回错误的情况，但是这非常重要是因为HTTP1.1允许同一个连接多次请求，只需要一个接着一个发送请求即可。很显然，如果我们不能在第一请求中读取整个响应，那么余下的数据将会影响第二个响应HttpClient试图去处理以避免这样的问题，记得总是释放连接是非常的重要的。

释放连接才能够确保HttpClient连接的重复利用。

总是关闭连接而不管服务器放回错误与否是非常重要的。

 

实例化HttpClinet

HttpClient无参的构造方法为大多数情况提供了一个适当的默认的设置参数，以方便我们的使用。

HttpClient client = new HttpClient();

 

创建Method

HTTP规范定义的各种方法与HttpClient实现了HttpMethod接口的类对应。这些类都可以在org.apache.commons.httpclient.methods包中找到

我们使用Get方法，通过URL获取URL关联的文档的简单的方法。

HttpMethod method = new GetMethod("http://www.apache.org/");

 

执行方法

方法的实际执行是通过调用Client的executeMethod方法，并以Method作为参数。因为网络连接是不可靠的，所以我们需要处理发生的任何错误。

在执行executeMethod方法可能会抛出两种类型的异常：HttpException and IOException.

另外一个有用的信息为服务器返回的状态码，在执行executeMethod方法以int类型返回，它能用于确定请求成功还是失败，有时候也用来指明客户端是否需要下一步的工作，比如提供身份认证凭证。

 

HttpException 

HttpException 代表一个逻辑错误，当请求无法发出或是响应的不能处理导致HTTP规范中定义的致命的冲突。通常这种异常是无法恢复的。有关协议异常的详细讨论请参考HttpClient异常处理指南。

注意，HttpException实际继承自IOException，你可以忽略它而只捕获IOException，在应用程序不区分协议和传输异常的情况下。

 

IOException

原始IOException代表了一个传输错误，类似如IO已关闭时，错误将会抛出。通常请求还有可能在第二次尝试中成功，HttpClient尝试自动恢复请求。有关传输异常的详细讨论请参考HttpClient异常处理指南。

 

Method恢复

默认的HttpClient将会自动尝试从非致命的错误的恢复，也就是说，当一个IOException 抛出时。HttpClient将会重试执行方法三次只要请求未完全到达服务器。就是Http method恢复的详细讨论请参考HttpClient异常处理指南

// set per default
client.getParams().setParameter(HttpMethodParams.RETRY_HANDLER, new DefaultHttpMethodRetryHandler());

默认的恢复处理能够实现自定义，可以增加自动重试的次数，即使客户端请求被服务器处理，HttpClient还是可以去执行方法，只是当接受响应时，将会抛出IOException异常。开启方法自动恢复时，请慎重。只有已知method是幕等方法的，也就是说，多次重试不会导致数据损坏或是不一致。

经验是GET method通常是安全的，而实体包含Method像POST,PUT通常是不安全的。

 

DefaultMethodRetryHandler retryhandler = new DefaultMethodRetryHandler(10, true);
client.getParams().setParameter(HttpMethodParams.RETRY_HANDLER, retryhandler);

 

读取响应

不管服务端返回的状态，总是去读取响应体是非常重要的。请看下面三种读取方法：

调用method.getResponseBody(). 这将返回一个包含响应正文中的数据的字节数组。

调用method.getResponseBodyAsString()。返回包含响应正文的字符串。警告：字节转换成字符串使用默认的编码，所以此方法可能不能在多个平台上移植。

调用method.getResponseBodyAsStream()读取整个内容流后调用stream.close()。处理接受缓冲至文件或者读取处理的大量数据是最合适的。在读取整个流之后，记得关闭输入流。

在指南中，为了简单，我们使用了getResponseBody()

byte[] responseBody = method.getResponseBody();

 

释放连接

这是让HttpClient持续运行的关键的一步，我们必须告诉HttpClient已经使用完连接，能够回收了。如果没有关闭连接，HttpClient将会无限期的等待连接的释放，来重用它。 

method.releaseConnection();

 

处理响应

现在完成了与HttpClient的交互，我们专注于处理需要的数据。在例子中，我们将直接打印到控制台。在我们需要读取返回的响应流情况下，我们就需要特别注意了。读取需要结合连接使用，当我们处理完所有的数据，就可以关闭输入流并释放连接。

注意，这里我们应该重视字符编码来代替系统默认。

System.out.println(new String(responseBody));

最终代码

用相关代码组合以上所有的代码片段，我们得到了下面的例子：

import org.apache.commons.httpclient.*;
import org.apache.commons.httpclient.methods.*;
import org.apache.commons.httpclient.params.HttpMethodParams;

import java.io.*;

public class HttpClientTutorial {
  
  private static String url = "http://www.apache.org/";

  public static void main(String[] args) {
    // Create an instance of HttpClient.
    HttpClient client = new HttpClient();

    // Create a method instance.
    GetMethod method = new GetMethod(url);
    
    // Provide custom retry handler is necessary
    method.getParams().setParameter(HttpMethodParams.RETRY_HANDLER, 
    		new DefaultHttpMethodRetryHandler(3, false));

    try {
      // Execute the method.
      int statusCode = client.executeMethod(method);

      if (statusCode != HttpStatus.SC_OK) {
        System.err.println("Method failed: " + method.getStatusLine());
      }

      // Read the response body.
      byte[] responseBody = method.getResponseBody();

      // Deal with the response.
      // Use caution: ensure correct character encoding and is not binary data
      System.out.println(new String(responseBody));

    } catch (HttpException e) {
      System.err.println("Fatal protocol violation: " + e.getMessage());
      e.printStackTrace();
    } catch (IOException e) {
      System.err.println("Fatal transport error: " + e.getMessage());
      e.printStackTrace();
    } finally {
      // Release the connection.
      method.releaseConnection();
    }  
  }
}