httpclient4中文API和使用

httpclient4 中文版帮助文档，最新官方版翻译版

前言

超文本传输协议（HTTP）也许是当今互联网上使用的最重要的协议了。Web 服务，有网络

功能的设备和网络计算的发展，都持续扩展了 HTTP 协议的角色，超越了用户使用的 Web

浏览器范畴，同时，也增加了需要 HTTP 协议支持的应用程序的数量。

尽管 java.net 包提供了基本通过 HTTP 访问资源的功能，但它没有提供全面的灵活性和其它

很多应用程序需要的功能。HttpClient 就是寻求弥补这项空白的组件，通过提供一个有效的，

保持更新的，功能丰富的软件包来实现客户端最新的 HTTP 标准和建议。

为扩展而设计，同时为基本的 HTTP 协议提供强大的支持，HttpClient 组件也许就是构建

基于经典（阻塞）I/O

内容无关

2. 什么是 HttpClient 不能做的

HttpClient 不是一个浏览器。它是一个客户端的 HTTP 通信实现库。HttpClient 的目标是发

送和接收 HTTP 报文。HttpClient 不会去缓存内容，执行 嵌入在 HTML 页面中的 javascript

代码，猜测内容类型，重新格式化请求/重定向 URI，或者其它和 HTTP 运输无关的功能。

第一章 基础

很自然地，HttpClient API 的主要切入点就是定义描述上述规约的 HttpClient 接口。

这里有一个很简单的请求执行过程的示例：

HttpClient httpclient = new DefaultHttpClient();

HttpGet httpget = new HttpGet("http://localhost/");

HttpResponse response = httpclient.execute(httpget);

HttpEntity entity = response.getEntity();

if (entity != null) {

InputStream instream = entity.getContent();

int l;

byte[] tmp = new byte[2048];

HttpClient 支持所有定义在 HTTP/1.1 版本中的 HTTP 方法：GET，HEAD，POST，PUT，

DELETE，TRACE 和 OPTIONS。对于每个方法类 型都有一个特殊的类：HttpGet，HttpHead，

HttpPost，HttpPut，HttpDelete，HttpTrace 和 HttpOptions。

请求的 URI 是统一资源定位符，它标识了应用于哪个请求之上的资源。HTTP 请求 URI 包含

一个协议模式，主机名称，可选的端口，资源路径，可选的查询和可选的片段。

HttpGet httpget = new HttpGet(

"http://www.google.com/search?hl=en&q=httpclient&btnG=Google+Search&aq=f&oq="

);

HttpClient 提供很多工具方法来简化创建和修改执行 URI。

URI 也可以编程来拼装：

查询字符串也可以从独立的参数中来生成：

List<NameValuePair> qparams = new ArrayList<NameValuePair>();

qparams.add(new BasicNameValuePair("q", "httpclient"));

qparams.add(new BasicNameValuePair("btnG", "Google Search"));

qparams.add(new BasicNameValuePair("aq", "f"));

qparams.add(new BasicNameValuePair("oq", null));

URI uri = URIUtils.createURI("http", "www.google.com", -1, "/search",

URLEncodedUtils.format(qparams, "UTF-8"), null);

HttpGet httpget = new HttpGet(uri);

System.out.println(httpget.getURI());

HttpResponse response = new BasicHttpResponse(HttpVersion.HTTP_1_1,

HttpStatus.SC_OK, "OK");

System.out.println(response.getProtocolVersion());

System.out.println(response.getStatusLine().getStatusCode());

System.out.println(response.getStatusLine().getReasonPhrase());

System.out.println(response.getStatusLine().toString());

输出内容为：

OK

一个 HTTP 报文可以包含很多描述如内容长度，内容类型等信息属性的头部信息。

HttpClient 提供获取，添加，移除和枚举头部信息的方法。

HttpResponse response = new BasicHttpResponse(HttpVersion.HTTP_1_1,

HttpStatus.SC_OK, "OK");

response.addHeader("Set-Cookie",

"c1=a; path=/; domain=localhost");

response.addHeader("Set-Cookie",

Set-Cookie: c2=b; path="/", c3=c; domain="localhost"

HttpResponse response = new BasicHttpResponse(HttpVersion.HTTP_1_1,

HttpStatus.SC_OK, "OK");

response.addHeader("Set-Cookie",

"c1=a; path=/; domain=localhost");

response.addHeader("Set-Cookie",

"c2=b; path=\"/\", c3=c; domain=\"localhost\"");

HeaderIterator it = response.headerIterator("Set-Cookie");

while (it.hasNext()) {

}

输出内容为：

Set-Cookie: c1=a; path=/; domain=localhost

Set-Cookie: c2=b; path="/", c3=c; domain="localhost"

它也提供解析 HTTP 报文到独立头部信息元素的方法方法。

HttpResponse response = new BasicHttpResponse(HttpVersion.HTTP_1_1,

HttpStatus.SC_OK, "OK");

"c1=a; path=/; domain=localhost");

response.addHeader("Set-Cookie",

while (it.hasNext()) {

System.out.println(elem.getName() + " = " + elem.getValue());

NameValuePair[] params = elem.getParameters();

for (int i = 0; i < params.length; i++) {

System.out.println(" " + params[i]);

}

}

输出内容为：

c1 = a

path=/

为它们也是可选的。使用了实体的请求被称为封闭实体请求。HTTP 规范定义 了两种封闭

式的实体是可以重复生成的。这种类型的实体会经常用于封闭 HTTP 请求的实体。

wrapping 包装式：内容从另外一个实体中获得。

当从一个 HTTP 响应中获取流式内容时，这个区别对于连接管理很重要。对于由应用程序创

情况下，建议考虑如流式这种不能重复的实体，和可以重复的自我包含式实体。

1.1.4.2 使用 HTTP 实体

因为一个实体既可以代表二进制内容又可以代表字符内容，它也支持字符编码（支持后者也

就是字符内容）。

实体是当使用封闭内容执行请求，或当请求已经成功执行，或当响应体结果发功到客户端时

创建的。

要 从实体中读取内容，可以通过 HttpEntity#getContent()方法从输入流中获取，这会返回

一个 java.io.InputStream对 象，或者提供一个输出流到 HttpEntity#writeTo(OutputStream)

方法中，这会一次返回所有写入到给定流中的内容。

文本 MIME 类型的字符编码，比如 text/plain 或 text /html，HttpEntity#getContentEncoding()

方法用来读取这个信息。如果头部信息不可用，那么就返回长度-1，而对于内 容类型返回

NULL。如果头部信息 Content-Type 是可用的，那么就会返回一个 Header 对象。

当为一个传出报文创建实体时，这个元数据不得不通过实体创建器来提供。

StringEntity myEntity = new StringEntity("important message",

"UTF-8");

System.out.println(myEntity.getContentType());

System.out.println(myEntity.getContentLength());

理器。HttpEntity#consumeContent()方法调用多次也是安全的。

也可能会有特殊情况，当整个响应内容的一小部分需要获取，消耗剩余内容而损失性能，还

有重用连接的代价太高，则可以仅仅通过调用 HttpUriRequest#abort()方法来中止请求。

HttpGet httpget = new HttpGet("http://localhost/");

HttpEntity entity = response.getEntity();

InputStream instream = entity.getContent();

int byteOne = instream.read();

int byteTwo = instream.read();

// Do not need the rest

httpget.abort();

}

连接不会被重用，但是由它持有的所有级别的资源将会被正确释放。