《HttpClient官方文档》1.1 执行请求

所有HTTP请求都有由方法名，请求URI和HTTP协议版本组成的请求行。

HttpClient支持开箱即用HTTP/1.1规范中定义的所有HTTP方法：GET, HEAD,POST, PUT, DELETE,TRACE and OPTIONS。它们都有一个特定的类对应这些方法类型: HttpGet,HttpHead, HttpPost,HttpPut, HttpDelete,HttpTrace, and HttpOptions.

请求的URI是统一资源定位符，它标识了应用于哪个请求之上的资源。HTTP请求的URI包含协议方案，主机名，可选的端口，资源路径，可选查询和可选片段。

HttpGet httpget = new HttpGet(
     "http://www.google.com/search?hl=en&q=httpclient&btnG=Google+Search&aq=f&oq=");

HttpClient 提供 URIBuilder 实用类来简化请求 URL的创建和修改.

URI uri = new URIBuilder()
        .setScheme("http")
        .setHost("www.google.com")
        .setPath("/search")
        .setParameter("q", "httpclient")
        .setParameter("btnG", "Google Search")
        .setParameter("aq", "f")
        .setParameter("oq", "")
        .build();
HttpGet httpget = new HttpGet(uri);
System.out.println(httpget.getURI());

输出内容为 >

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

HTTP响应是服务器端在接收和解释客户端请求消息后，返回客户端的消息。该消息的第一行包含协议版本以及后面跟着的数字形式的状态代码和相关的文本段。

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());

输出内容为 >

HTTP/1.1
200
OK
HTTP/1.1 200 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", 
    "c2=b; path=/"//", c3=c; domain=/"localhost/"");
Header h1 = response.getFirstHeader("Set-Cookie");
System.out.println(h1);
Header h2 = response.getLastHeader("Set-Cookie");
System.out.println(h2);
Header[] hs = response.getHeaders("Set-Cookie");
System.out.println(hs.length);

输出内容为 >

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

获得所有头部给定类型的最有效的方法是使用
HeaderIterator 接口.

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()) {
    System.out.println(it.next());
}

输出内容为 >

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");
response.addHeader("Set-Cookie", 
    "c1=a; path=/; domain=localhost");
response.addHeader("Set-Cookie", 
    "c2=b; path=/"//", c3=c; domain=/"localhost/"");

HeaderElementIterator it = new BasicHeaderElementIterator(
    response.headerIterator("Set-Cookie"));

while (it.hasNext()) {
    HeaderElement elem = it.nextElement(); 
    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=/
domain=localhost
c2 = b
path=/
c3 = c
domain=localhost

HTTP 消息可以携带与其相关联的请求或响应的内容实体。实体可以在一些请求和响应中找到，因为它们也是可选的。使用了实体的请求被称为封闭实体请求。HTTP规范定义了两种封闭实体的方法: POST 和
PUT。响应通常期望包含一个内容实体。 这个规则也有特例，就像
HEAD 方法和 204 No Content,
304 Not Modified, 205 Reset Content
响应。

HttpClient根据其内容来源以此区分三种类型的实体：

当一个HTTP请求中正在流式输出内容时，这个区分对于连接管理来说很重要。而对于由应用程序创建，并且只使用 HttpClient 发送的请求实体，流式和自包含的区分是没有多大意义的。在这种情况下，建议考虑如流式这样的非可重复的实体，或者是像自包含式那样的可重复实体。

StringEntity myEntity = new StringEntity("important message", 
   ContentType.create("text/plain", "UTF-8"));

System.out.println(myEntity.getContentType());
System.out.println(myEntity.getContentLength());
System.out.println(EntityUtils.toString(myEntity));
System.out.println(EntityUtils.toByteArray(myEntity).length);

Content-Type: text/plain; charset=utf-8
17
important message
17

为了确保能够系统资源的正确释放，必须关闭实体或响应自身相关的内容流。

CloseableHttpClient httpclient = HttpClients.createDefault();
HttpGet httpget = new HttpGet("http://localhost/");
CloseableHttpResponse response = httpclient.execute(httpget);
try {
    HttpEntity entity = response.getEntity();
    if (entity != null) {
        InputStream instream = entity.getContent();
        try {
            // do something useful
        } finally {
            instream.close();
        }
    }
} finally {
    response.close();
}

关闭内容流和关闭响应之间的差别在于，前者将试图通过消耗实体内容来维持底层连接可用，而后者将立即关闭和丢弃连接。

请注意， HttpEntity#writeTo(OutputStream)
方法也同样确保系统资源在实体被全部写出的时候必须正确的释放，如果该方法获得的实例通过类
java.io.InputStream 调用了
HttpEntity#getContent()方法, 那么它会被预期在finally子句关闭流。

当流实体工作时, 能够使用
EntityUtils#consume(HttpEntity) 方法确保
实体内容被充分的消耗和关闭底层流.

有可能出现这样的特殊情况，只需要获取响应内容的其中一小部分或者是通过消耗剩余内容来使连接可重用造成性能损失太高，这样的情况下可以通过关闭响应来终止内容流。

CloseableHttpClient httpclient = HttpClients.createDefault();
HttpGet httpget = new HttpGet("http://localhost/");
CloseableHttpResponse response = httpclient.execute(httpget);
try {
    HttpEntity entity = response.getEntity();
    if (entity != null) {
        InputStream instream = entity.getContent();
        int byteOne = instream.read();
        int byteTwo = instream.read();
        // Do not need the rest
    }
} finally {
    response.close();
}

这样做了之后，连接将不能被重用，而且其所持有的所有级别资源会被正确释放.

通常推荐消耗实体内容的方式是使用
HttpEntity#getContent() 或是
HttpEntity#writeTo(OutputStream) 方法。 HttpClient
同样也配备了 EntityUtils 类, 它公开了一些静态方法，这些方法能够更容易地从实体中读取内容或信息，
替代通过 java.io.InputStream 类这样直接读取的方式，并且也可以使用这个类中的方法以字符串/字节数组的形式获取整个内容体。
但是, EntityUtils 这个类只有在响应实体来自受信任的 HTTP 服务器和长度是已知和有限的情况下才推荐使用。

CloseableHttpClient httpclient = HttpClients.createDefault();
HttpGet httpget = new HttpGet("http://localhost/");
CloseableHttpResponse response = httpclient.execute(httpget);
try {
    HttpEntity entity = response.getEntity();
    if (entity != null) {
        long len = entity.getContentLength();
        if (len != -1 && len < 2048) {
            System.out.println(EntityUtils.toString(entity));
        } else {
            // Stream content out
        }
    }
} finally {
    response.close();
}

在某些情况下可能需要能够读取的实体内容超过一次。在这种情况下的实体内容必须以某种方式缓存在内存或磁盘上。解决这个问题最简单的方式是通过
the BufferedHttpEntity 类来包装源实体。这将使源实体的内容被读入到内存缓冲区。其他任何方式的实体包装都会包含源实体。

CloseableHttpResponse response = <...>
HttpEntity entity = response.getEntity();
if (entity != null) {
    entity = new BufferedHttpEntity(entity);
}

HttpClient提供了一些可以通过 HTTP 连接来高效地流出内容的类。 这些类的实例可以与封闭像 POST 和 PUT请求的实体相关联，
使得实体内容装入流出的HTTP 请求。HttpClient为大多数的通用的数据容器比如字符串，字节数组，输入流和文件提供了一些类: StringEntity,
ByteArrayEntity,
InputStreamEntity, 和
FileEntity.

File file = new File("somefile.txt");
FileEntity entity = new FileEntity(file, 
    ContentType.create("text/plain", "UTF-8"));        

HttpPost httppost = new HttpPost("http://localhost/action.do");
httppost.setEntity(entity);

请注意， InputStreamEntity 是不可重复的，因为它仅能从底层数据流中读取一次内容。
通常建议来实现一个自定义 HttpEntity 类， 这个是自包含式的类来替代通用类 InputStreamEntity.
FileEntity 也是一个很不错的点子.

List<NameValuePair> formparams = new ArrayList<NameValuePair>();
formparams.add(new BasicNameValuePair("param1", "value1"));
formparams.add(new BasicNameValuePair("param2", "value2"));
UrlEncodedFormEntity entity = new UrlEncodedFormEntity(formparams, Consts.UTF_8);
HttpPost httppost = new HttpPost("http://localhost/handler.do");
httppost.setEntity(entity);

param1=value1&param2=value2

StringEntity entity = new StringEntity("important message",
        ContentType.create("plain/text", Consts.UTF_8));
entity.setChunked(true);
HttpPost httppost = new HttpPost("http://localhost/acrtion.do");
httppost.setEntity(entity);

处理响应最简单方便的方式是使用 ResponseHandler 接口, 它包含了
handleResponse(HttpResponse response) 方法。
这个方法彻底的解决了用户对于连接管理的困扰。当使用
ResponseHandler接口时, 无论是否请求执行成功或引发异常，HttpClient都会自动关注来确保释放的连接返回到连接管理器。

CloseableHttpClient httpclient = HttpClients.createDefault();
HttpGet httpget = new HttpGet("http://localhost/json");

ResponseHandler<MyJsonObject> rh = new ResponseHandler<MyJsonObject>() {

    @Override
    public JsonObject handleResponse(
            final HttpResponse response) throws IOException {
        StatusLine statusLine = response.getStatusLine();
        HttpEntity entity = response.getEntity();
        if (statusLine.getStatusCode() >= 300) {
            throw new HttpResponseException(
                    statusLine.getStatusCode(),
                    statusLine.getReasonPhrase());
        }
        if (entity == null) {
            throw new ClientProtocolException("Response contains no content");
        }
        Gson gson = new GsonBuilder().create();
        ContentType contentType = ContentType.getOrDefault(entity);
        Charset charset = contentType.getCharset();
        Reader reader = new InputStreamReader(entity.getContent(), charset);
        return gson.fromJson(reader, MyJsonObject.class);
    }
};
MyJsonObject myjson = client.execute(httpget, rh);