Jakarta Commons HttpClient 学习笔记

HttpClient的功能

1:基于标准，纯正java，实现了http1.0和1.1。
2:在一个可扩展的OO框架内，实现了HTTP的全部方法(GET, POST,
PUT, DELETE, HEAD, OPTIONS, and TRACE)
3:支持HTTPS(ssl上的HTTP)的加密操作
4:透明地穿过HTTP代理建立连接
5:通过CONNECT方法，利用通过建立穿过HTTP代理的HTTPS连接
6:利用本地Java socket，透明地穿过SOCKS(版本5和4）代理建立连接
7:支持利用Basic、Digest和NTLM加密的认证
8:支持用于上传大文件的Multi-Part表单POST方法
9:插件式安全socket实现，易于使用第三方的解决方案
10:连接管理，支持多线程应用，支持设定单个主机总连接和最高连接数量,自动检测和关闭失效连接
11:直接将请求信息流送到服务器的端口
12:直接读取从服务器的端口送出的应答信息
13:支持HTTP/1.0中用KeepAlive和HTTP/1.1中用persistance设置的持久连接
14:直接访问由服务器送出的应答代码和头部信息
15:可设置连接超时时间

16:HttpMethods 实现Command Pattern，以允许并行请求或高效连接复用
17:遵循the Apache Software License协议，源码免费可得

使用HttpClient编程的基本步聚:
1:创建 HttpClient 的一个实例.
2:创建某个方法（DeleteMethod，EntityEnclosingMethod，
ExpectContinueMethod，GetMethod，HeadMethod，
MultipartPostMethod，OptionsMethod，PostMethod，
PutMethod，TraceMethod）的一个实例，一般可用要目标URL为
参数。
3:设置这个方法实例的相关参数，例如MultipartPostMethod里
面的addParameter()和addPart()设置要上传的文件参数。有的
方法则不需要这一步。
4:让 HttpClient 执行这个方法.
5:读取应答信息.
6:释放连接.
7:处理应答.

　　在执行方法的过程中，有两种异常，一种是
HttpRecoverableException，表示偶然性错误发生，一般再试可
能成功，另一种是IOException，严重错误。

HTTP方法

　　HttpClient支持的HTTP方法有8种，下面分述之。
　　1、Options
　　HTTP方法Options用来向服务器发送请求，希望获得针对由
请求URL(request url)标志的资源在请求/应答的通信过程可以
使用的功能选项。通过这个方法，客户端可以在采取具体行动之
前，就可对某一资源决定采取什么动作和/或以及一些必要条件
，或者了解服务器提供的功能。这个方法最典型的应用，就是用
来获取服务器支持哪些HTTP方法。
　　HttpClient中有一个类叫OptionsMethod，来支持这个HTTP
方法，利用这个类的getAllowedMethods方法，就可以很简单地
实现上述的典型应用。

OptionsMethod options = new
OptionsMethod("http://jakarta.apache.org");
// 执行方法并做相应的异常处理
...
Enumeration allowedMethods =
options.getAllowedMethods();
options.releaseConnection();
　　2、Get
　　 HTTP方法GET用来取回请求URI（request-URI）标志的任何
信息（以实体(entity)的形式），"get"这个单词本意就是”获
取“的意思。如果请求URI指向的一个数据处理过程，那这个过
程生成的数据，在应答中以实体的形式被返回，而不是将这个过
程的代码的返回。
　　如果HTTP包中含有If-ModifiedSince,
If-Unmodified-Since, If-Match, If-None-Match, 或
If-Range等头字段，则GET也就变成了”条件GET“，即只有满足
上述字段描述的条件的实体才被取回，这样可以减少一些非必需
的网络传输，或者减少为获取某一资源的多次请求（如第一次检
查，第二次下载）。（一般的浏览器，都有一个临时目录，用来
缓存一些网页信息，当再次浏览某个页面的时候，只下载那些修
改过的内容，以加快浏览速度，就是这个道理。至于检查，则常
用比GET更好的方法HEAD来实现。）如果HTTP包中含有Range头字
段，那么请求URI指定的实体中，只有决定范围条件的那部分才
被取回来。（用过多线程下载工具的朋友，可能比较容易理解这
一点）
　　这个方法的典型应用，用来从web服务器下载文档。
HttpClient定义了一个类叫GetMethod来支持这个方法，用
GetMethod类中getResponseBody, getResponseBodyAsStream 或
getResponseBodyAsString函数就可以取到应答包包体中的文档
（如HTML页面）信息。这这三个函数中，
getResponseBodyAsStream通常是最好的方法，主要是因为它可
以避免在处理下载的文档之前缓存所有的下载的数据。
GetMethod get = new
GetMethod("http://jakarta.apache.org");
// 执行方法，并处理失败的请求.
...
InputStream in = get.getResponseBodyAsStream();
// 利用输入流来处理信息。
get.releaseConnection();
　　对GetMethod的最常见的不正确的使用，是没有将全部的应
答主体的数据读出来。还有，必须注意要手工明确地将链接释放
。
　　3、Head
　　HTTP的Head方法，与Get方法完全一致，唯一的差别是服务
器不能在应答包中包含主体(message-body)，而且一定不能包含
主体。使用这个方法，可以使得客户无需将资源下载回就可就以
得到一些关于它的基本信息。这个方法常用来检查超链的可访问
性以及资源最近有没有被修改。
　　HTTP的head方法最典型的应用，是获取资源的基本信息。
HttpClient定义了HeadMethod类支持这个方法，HeadMethod类与
其它*Method类一样，用 getResponseHeaders()取回头部信息，
而没有自己的特殊方法。
HeadMethod head = new
HeadMethod("http://jakarta.apache.org");
// 执行方法，并处理失败的请求.
...
// 取回应答包的头字段信息.
Header[] headers = head.getResponseHeaders();
// 只取回最后修改日期字段的信息.
String lastModified =
head.getResponseHeader("last-modified").getValue();

　　4、Post
　　Post在英文有“派驻”的意思，HTTP方法POST就是要求服务
器接受请求包中的实体，并将其作为请求URI的下属资源。从本
质上说，这意味着服务器要保存这个实体信息，而且通常由服务
器端的程序进行处理。Post方法的设计意图，是要以一种统一的
方式实现下列功能：
对已有的资源做评注
将信息发布到BBS、新闻组、邮件列表，或类似的文章组中
将一块数据，提交给数据处理进程
通过追加操作，来扩展一个数据库
　　这些都操作期待着在服务器端产生一定的“副作用”，如修
改了数据库等。
　　HttpClient定义PostMethod类以支持该HTTP方法，在
httpclient中，使用post方法有两个基本的步骤：为请求包准备
数据，然后读取服务器来的应答包的信息。通过调用
setRequestBody()函数，来为请求包提供数据，它可以接收三类
参数：输入流、名值对数组或字符串。至于读取应答包需要调用
getResponseBody* 那一系列的方法，与GET方法处理应答包的方
法相同。
　　常见问题是，没有将全部应答读取（无论它对程序是否有用
），或没有释放链接资源
5. multipart post
Introduction
The multipart post method is a different request body format for a POST method. The media-type multipart/form-data follows the rules of all multipart MIME data streams as outlined in RFC 1521. It is intended for use in returning the data that comes about from filling out a form, particularly when the form requires binary data to be uploaded such as the contents of a file.
Typical Usage
Like for the standard POST method, there are two main steps to using the multipart post method, setting the request data and retrieving the response data.
The request data is specified by adding parameters to the method, these are defined by the org.apache.commons.httpclient.methods.multipart.Part class and it's various subclasses. A description of each of these is below.
Typical Usage
Like for the standard POST method, there are two main steps to using the multipart post method, setting the request data and retrieving the response data.
The request data is specified by adding parameters to the method, these are defined by the org.apache.commons.httpclient.methods.multipart.Part class and it's various subclasses. A description of each of these is below.
Part Description
StringPart： The string part is a simple part that takes a name for the part and the value of the part as a string. This is typically used for standard form elements such as a text area within a multipart form.
FilePart： The file part is actually a very generic type of part that can contain any type of data and specify a name, content type and charset for the data. In it's simplest form, it takes just a name and a File object and uploads the contents of the file, however it can also be passed a PartSource object to upload. See the part source section below for more information.
Part Sources
The PartSource interface provides a generic container for providing data to the FilePart class. There are two concrete implementations of PartSource provided with HttpClient (described below) but you can also provide your own implementation easily. The input for the multipart post could come from anywhere, perhaps it's being received from another server or process, and all that the PartSource class needs to be able to do is provide the length of the data that will be provided, an input stream to retrieve the data from and a file name (or some name identifying the data).
The two concrete implementations of PartSource are FilePartSource and ByteArrayPartSource. FilePartSource simply takes a File to upload whereas ByteArrayPartSource allows for the case where the data has been cached in memory and takes a file name and a byte array to upload.
Common Problems
The most common problem people run into with multipart uploads is that the length of the data must be known before hand. If the length of the data can not be determined in advance, it needs to be cached either in memory or to a file and then uploaded using either ByteArrayPartSource or FilePartSource. The HTTP specification does not allow for POST data to be of an unknown length.