仅自己使用，原文：http://hc.apache.org/httpcomponents-client-ga/tutorial/html/

Chapter 1. Fundamentals

1.1. Request execution

The most essential function of HttpClient is to execute HTTP methods.

HTTP客户端最常见的功能是执行Http方法

Quite naturally, the main entry point of the HttpClient API is the HttpClient interface that defines the contract described above.

Here is an example of request execution process in its simplest form:

理所当然的，HTTP客户端的最主要的入口是上面定义的约定。这里是一个请求执行的描述：
CloseableHttpClient httpclient = HttpClients.createDefault();
HttpGet httpget = new HttpGet("http://localhost/");
CloseableHttpResponse response = httpclient.execute(httpget);
try {
    <...>
} finally {
    response.close();
}

1.1.1. HTTP request

All HTTP requests have a request line consisting a method name, a request URI and an HTTP protocol version.

HttpClient supports out of the box all HTTP methods defined in the HTTP/1.1 specification: GET, HEAD, POST, PUT, DELETE, TRACE and OPTIONS. There is a specific class for each method type.: HttpGet, HttpHead, HttpPost, HttpPut, HttpDelete, HttpTrace, and HttpOptions.

The Request-URI is a Uniform Resource Identifier that identifies the resource upon which to apply the request. HTTP request URIs consist of a protocol scheme, host name, optional port, resource path, optional query, and optional fragment.

所有的HTTP请求有一个请求行包含了方法名，一个请求URI和HTTP协议版本
HTTP客户端支持HTTP1.1版的规范：xxxx7个方法。
每个方法对应一个类。
请求URI是一个统一资源标识符，定义了请求那个资源。HTTP请求URIs包含了一个协议、主机、端口xxx
HttpGet httpget = new HttpGet(
     "http:///search?hl=en&q=httpclient&btnG=Google+Search&aq=f&oq=");
HttpClient provides URIBuilder utility class to simplify creation and modification of request URIs.
URI uri = new URIBuilder()
        .setScheme("http")
        .setHost("")
        .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());

stdout >

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

1.1.2. HTTP response

HTTP response is a message sent by the server back to the client after having received and interpreted a request message. The first line of that message consists of the protocol version followed by a numeric status code and its associated textual phrase.
HTTP responsehi一个服务器返回的响应。第一行包含了协议版本，数字状态码及相关的文本短语。

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

1.1.3. Working with message headers

An HTTP message can contain a number of headers describing properties of the message such as the content length, content type and so on. HttpClient provides methods to retrieve, add, remove and enumerate headers.

一个HTTP信息包含了大量的头信息描述消息的熟悉，如长度，内容类型等。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\"");
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);

stdout >

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

The most efficient way to obtain all headers of a given type is by using the HeaderIterator interface.
获得所有的头信息效率最高的方式是用HeaderIterator接口
It also provides convenience methods to parse HTTP messages into individual header elements.
也提供了方便的方法把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]);
    }
}

stdout >

c1 = a
path=/
domain=localhost
c2 = b
path=/
c3 = c
domain=localhost

1.1.4. HTTP entity

HTTP messages can carry a content entity associated with the request or response. Entities can be found in some requests and in some responses, as they are optional. Requests that use entities are referred to as entity enclosing requests. The HTTP specification defines two entity enclosing request methods: POST and PUT. Responses are usually expected to enclose a content entity. There are exceptions to this rule such as responses to HEAD method and 204 No Content, 304 Not Modified, 205 Reset Content responses.
HTTP消息能够携带一个与请求或相应相关联的内容提。实体能够在一些请求和相应中找到，他们是可选的。使用实体的请求被称为实体封装请求。HTTP规范定义了两种实体封装方法：POST和PUT。响应通常期望是一个封装的内容体。也有例外情况：比如响应HEAD方法和204没有内容，304无修改，205重置内容响应。

HttpClient distinguishes three kinds of entities, depending on where their content originates:
HTTP客户端区分三种实体，取决于内容来源：

流：这个种内容来自于一个流或者在运行中产生。尤其，这种类型包括从HTTP响应中接受到的实体。流类型的实体通常不会重复。
自包含类型：这种内容通常位于内存或者通过一个连接或者别的实体获得。自包含实体通常是可以重复的。这种类型的实体大多用于实体封装的HTTP请求。
封装：这种内容来自于另一个实体。
This distinction is important for connection management when streaming out content from an HTTP response. For request entities that are created by an application and only sent using HttpClient, the difference between streamed and self-contained is of little importance. In that case, it is suggested to consider non-repeatable entities as streamed, and those that are repeatable as self-contained.

当从HTTP响应中获取流时，这个区别对于连接管理来讲十分重要。对于应用创建的仅仅用于HTTP客户端发送的请求实体，流和自包含的内容的区别并不重要。在这种情况下，对于不可重复的实体建议使用流，而可以重复的建议使用自包含。

1.1.4.1. Repeatable entities

An entity can be repeatable, meaning its content can be read more than once. This is only possible with self contained entities (like ByteArrayEntity or StringEntity)
一个实体如果是可重复的，意味着实体内容可以被多次读取。只有自包含的实体是可重复的。

当为外发消息创建一个实体时，也必须为实体创建元数据。

1.1.5. Ensuring release of low level resources

In order to ensure proper release of system resources one must close either the content stream associated with the entity or the response itself

为了保证合理释放系统资源我们必须关闭与实体相关的内容流或者响应本身相关联的内容流
xxxx

The difference between closing the content stream and closing the response is that the former will attempt to keep the underlying connection alive by consuming the entity content while the latter immediately shuts down and discards the connection.

Please note that the HttpEntity#writeTo(OutputStream) method is also required to ensure proper release of system resources once the entity has been fully written out. If this method obtains an instance of java.io.InputStream by calling HttpEntity#getContent(), it is also expected to close the stream in a finally clause.

When working with streaming entities, one can use the EntityUtils#consume(HttpEntity) method to ensure that the entity content has been fully consumed and the underlying stream has been closed.

There can be situations, however, when only a small portion of the entire response content needs to be retrieved and the performance penalty for consuming the remaining content and making the connection reusable is too high, in which case one can terminate the content stream by closing the response.

关闭内容流和关闭相应不同的地方时前者试图聪哥消耗实体内容保持底层连接，而后者直接关闭并且丢弃连接。
提示：writeTo方法也需要确保合理的释放系统资源一旦实体被完全写完。如果这个方法通过调用getContent方法包含了InputStream一个实例，也希望最终关闭流。
当用流类型的实体时，我们能够使用consume方法确保实体内容被完全消耗掉，并且关闭潜在的流。
但是会有这种情况：只需要获取返回内容的一小部分内容，消耗剩余内容会使该连接可重复使用的性能损失过高?????这种情况下我们可以通过关闭相应中断内容流。
xxxxx
The connection will not be reused, but all level resources held by it will be correctly deallocated.
连接不会被重复利用，但是所有被占用的资源会被合理分配。

1.1.6. Consuming entity content

The recommended way to consume the content of an entity is by using its HttpEntity#getContent() or HttpEntity#writeTo(OutputStream) methods. HttpClient also comes with the EntityUtils class, which exposes several static methods to more easily read the content or information from an entity. Instead of reading the java.io.InputStream directly, one can retrieve the whole content body in a string / byte array by using the methods from this class. However, the use of EntityUtils is strongly discouraged unless the response entities originate from a trusted HTTP server and are known to be of limited length.
推荐使用getContent方法或者writeTo方法区消耗实体内容。HTTP客户端还配备了EntityUtils类，提供了几个方便从实体中读取内容和消息的静态方法。我们不需要直接使用InputStream，就能够用这个类从字符串或者字节数组中直接获取整个内容。但是强烈不建议使用EntityUtils，除非响应实体来自于一个可以信任的HTTP服务器并且知道长度限制。

xxxx
In some situations it may be necessary to be able to read entity content more than once. In this case entity content must be buffered in some way, either in memory or on disk. The simplest way to accomplish that is by wrapping the original entity with the BufferedHttpEntity class. This will cause the content of the original entity to be read into a in-memory buffer. In all other ways the entity wrapper will be have the original one.
子一些情况下可能需要多次读取实体内容。这种情况下实体内容必须采用某种方式缓存，内存或者硬盘上。最简单的实现方式是用BufferedHttpEntity打包原始实体。这样原始内容会被读到内存中。其他方式的实体包装会包含原始实体。
xxxxx

1.1.7. Producing entity content

HttpClient provides several classes that can be used to efficiently stream out content throught HTTP connections. Instances of those classes can be associated with entity enclosing requests such as POST and PUT in order to enclose entity content into outgoing HTTP requests. HttpClient provides several classes for most common data containers such as string, byte array, input stream, and file: StringEntity, ByteArrayEntity, InputStreamEntity, and FileEntity.
Http客户端提供几个能够高效的从HTTP连接中读取内容的类。这些类的实体与封装实体请求POST和PUT相关联，以便实体内容通过HTTP请求传输出去。HTTP客户端提供几个常见数据容器的类，例如：.....。

xxxxxxx

Please note InputStreamEntity is not repeatable, because it can only read from the underlying data stream once. Generally it is recommended to implement a custom HttpEntity class which is self-contained instead of using the generic InputStreamEntity. FileEntity can be a good starting point.
请注意InputStreamEntity是不可重复的，因为他只能从底层数据流读取一次。通常推荐实现一个自定义的HttpEntity类

Many applications need to simulate the process of submitting an HTML form, for instance, in order to log in to a web application or submit input data. HttpClient provides the entity class UrlEncodedFormEntity to facilitate the process.
许多应用需要模拟处理HTML表单，例如为了登陆一个web应用或者提交录入的数据。HTTP客户端提供了实体类UrlEncodedFormEntity帮助处理。

xxxxx
The UrlEncodedFormEntity instance will use the so called URL encoding to encode parameters and produce the following content:
UrlEncodedFormEntity实例使用所谓的URL encoding对参数编码生成如下内容
xxxx

1.1.7.2. Content chunking

Generally it is recommended to let HttpClient choose the most appropriate transfer encoding based on the properties of the HTTP message being transferred. It is possible, however, to inform HttpClient that chunk coding is preferred by setting HttpEntity#setChunked() to true. Please note that HttpClient will use this flag as a hint only. This value will be ignored when using HTTP protocol versions that do not support chunk coding, such as HTTP/1.0.

通常建议让HTTP客户端选择根据HTTP消息属性最适合的传输编码。但是，通过setChunked设置为true通知HTTP优先使用chunk的编码。请注意：HTTP客户端只是使用这个标识作为一个示意。如果协议版本不支持，如HTTP1.0，则这个值会被忽略。
xxxxx

1.1.8. Response handlers

The simplest and the most convenient way to handle responses is by using the ResponseHandler interface, which includes the handleResponse(HttpResponse response) method. This method completely relieves the user from having to worry about connection management. When using a ResponseHandler, HttpClient will automatically take care of ensuring release of the connection back to the connection manager regardless whether the request execution succeeds or causes an exception.
处理相应最简单最方便的方式是使用ResponseHandler接口，有一个handleResponse方法。这个方法完全消除了用户对连接管理的担心。当使用一个ResponseHandler时，HTTP客户端会自己把连接还给连接管理器而忽略请求是否执行成功。

1.2. HttpClient interface

HttpClient interface represents the most essential contract for HTTP request execution. It imposes no restrictions or particular details on the request execution process and leaves the specifics of connection management, state management, authentication and redirect handling up to individual implementations. This should make it easier to decorate the interface with additional functionality such as response content caching.
HTTP客户端接口展示了最基本的HTTP请求执行规范。他没有限定请求执行的具体的细节，把连接管理，状态管理，鉴权和重定向处理的细节留给了个人实现。这样就很容易去给接口加一些额外功能，例如响应缓存。

Generally HttpClient implementations act as a facade to a number of special purpose handler or strategy interface implementations responsible for handling of a particular aspect of the HTTP protocol such as redirect or authentication handling or making decision about connection persistence and keep alive duration. This enables the users to selectively replace default implementation of those aspects with custom, application specific ones.
通常HTTP客户端充当一个处理大量具体用途（负责处理HTTP协议的某个具体方面，比如重定向、鉴权处理、连接持久化、保活时间）的处理程序的外壳。这使用户能够有选择的个性化的去替换某些方面的实现，为应用做定制。

xxxx

1.2.1. HttpClient thread safety

HttpClient implementations are expected to be thread safe. It is recommended that the same instance of this class is reused for multiple request executions.
HttpClient实现是线程安全的。推荐这个类的实例被多线程的请求重复使用。

xxxxx

1.3. HTTP execution context

Originally HTTP has been designed as a stateless, response-request oriented protocol. However, real world applications often need to be able to persist state information through several logically related request-response exchanges. In order to enable applications to maintain a processing state HttpClient allows HTTP requests to be executed within a particular execution context, referred to as HTTP context. Multiple logically related requests can participate in a logical session if the same context is reused between consecutive requests. HTTP context functions similarly to a java.util.Map. It is simply a collection of arbitrary named values. An application can populate context attributes prior to request execution or examine the context after the execution has been completed.
原始的HTTP是无状态的。但是现实应用需要通过持久化状态信息。为了让应用维护一个可处理的状态，HTTP客户端运行请求带上上下文，作为HTTP的上下文。多个逻辑相关的请求可以参与到一个逻辑session如果在持续的请求中上下文相同。HTTP上下文函数有点像java.util.Map。不过是一个无序键值的集合。应用可以在执行请求前设置上下文和执行后检查上下文。

HttpContext can contain arbitrary objects and therefore may be unsafe to share between multiple threads. It is recommended that each thread of execution maintains its own context.
HttpContext能包含任意对象因此如果多线程共享是不安全的，推荐每个线程维护自己的上下文。

In the course of HTTP request execution HttpClient adds the following attributes to the execution context:
在执行请求的过程HTTP客户端增加了下列属性执行上下文

One can use HttpClientContext adaptor class to simplify interractions with the context state.
我们可以使用HttpClientContext适配器简化和上下文状态的交互。??????

xxxxx

Multiple request sequences that represent a logically related session should be executed with the same HttpContext instance to ensure automatic propagation of conversation context and state information between requests.

In the following example the request configuration set by the initial request will be kept in the execution context and get propagated to the consecutive requests sharing the same context.
同一个逻辑对话的session请求应该被相同的Http上下文执行，确保会话上下文和状态信息在请求中自动切换。
下面的例子中初始化的请求配置会在执行上下文中中保持，并且在连续的请求中共享相同的上下文。

xxxxxx

1.4. Exception handling

HttpClient can throw two types of exceptions: java.io.IOException in case of an I/O failure such as socket timeout or an socket reset and HttpException that signals an HTTP failure such as a violation of the HTTP protocol. Usually I/O errors are considered non-fatal and recoverable, whereas HTTP protocol errors are considered fatal and cannot be automatically recovered from.
HttpClient能够抛出两种类型的异常：IOException/HttpException。

xxxxx

1.5. Aborting requests

In some situations HTTP request execution fails to complete within the expected time frame due to high load on the target server or too many concurrent requests issued on the client side. In such cases it may be necessary to terminate the request prematurely and unblock the execution thread blocked in a I/O operation. HTTP requests being executed by HttpClient can be aborted at any stage of execution by invoking HttpUriRequest#abort() method. This method is thread-safe and can be called from any thread. When an HTTP request is aborted its execution thread - even if currently blocked in an I/O operation - is guaranteed to unblock by throwing a InterruptedIOException

有时候HTTP请求会在期望的时间内无法完成，因为目标服务的高负荷或者客户端有太多的并发请求。这时，可能需要去过早的中断请求和解锁被IO操作阻塞的线程。HttpClient能够用HttpUriRequest#abort()方法在任何执行阶段丢弃HTTP请求。这个方法是县城安全的，并且可以被任何线程调用。当一个请求被丢弃，他的执行线程应该保证解锁并抛出一个InterruptedIOException异常。

1.6.2. HTTP parameters beans

The HttpParams interface allows for a great deal of flexibility in handling configuration of components. Most importantly, new parameters can be introduced without affecting binary compatibility with older versions. However, HttpParams also has a certain disadvantage compared to regular Java beans: HttpParams cannot be assembled using a DI framework. To mitigate the limitation, HttpClient includes a number of bean classes that can used in order to initialize HttpParams objects using standard Java bean conventions.
HTTP 参数beans接口允许灵活处理大量组件配置。最重要的是新组件能够被引入，而且不影响与旧版本二进制文件的兼容性？？？？但是HttpParams与普通Java Bean相比也有一个明显的缺点：HttpParams不能用DI框架组装。为了减少限制，HTTP客户端使用了大量bean为了能够用标准的Java规范初始化HttpParams对象。

1.7. HTTP request execution parameters

These are parameters that can impact the process of request execution:

这些参数能够影响请求的执行：
PROTOCOL_VERSION 定义HTTP协议版本。默认用1.1
HTTP_ELEMENT_CHARSET定义了用于HTTP协议编码的字符集。默认用US-ASCII。
HTTP_CONTENT_CHARSET定义了内容提编码的字符集。默认使用ISO-8859-1。
USER_AGENT定义了User-Agent头信息的内容？？？？HTTP客户端会自动生成默认值。

• CoreProtocolPNames.STRICT_TRANSFER_ENCODING='http.protocol.strict-transfer-encoding':  defines whether responses with an invalid Transfer-Encoding header should be rejected. This parameter expects a value of type java.lang.Boolean. If this parameter is not set, invalid Transfer-Encoding values will be ignored.

• CoreProtocolPNames.USE_EXPECT_CONTINUE='http.protocol.expect-continue':  activates the Expect: 100-Continue handshake for the entity enclosing methods. The purpose of the Expect: 100-Continue handshake is to allow the client that is sending a request message with a request body to determine if the origin server is willing to accept the request (based on the request headers) before the client sends the request body. The use of the Expect: 100-continue handshake can result in a noticeable performance improvement for entity enclosing requests (such as POST and PUT) that require the target server's authentication. The Expect: 100-continue handshake should be used with caution, as it may cause problems with HTTP servers and proxies that do not support HTTP/1.1 protocol. This parameter expects a value of type java.lang.Boolean. If this parameter is not set, HttpClient will not attempt to use the handshake.

• CoreProtocolPNames.WAIT_FOR_CONTINUE='http.protocol.wait-for-continue':  defines the maximum period of time in milliseconds the client should spend waiting for a 100-continue response. This parameter expects a value of type java.lang.Integer. If this parameter is not set HttpClient will wait 3 seconds for a confirmation before resuming the transmission of the request body.

STRICT_TRANSFER_ENCODING 定义了，当响应信息携带了不合法的传输编码消息头是否要丢弃返回信息。默认不合法的传输编码会被忽略。
USE_EXPECT_CONTINUE 触发期望：为了封装实体方法的100继续握手。Expect的目的：100继续握手允许客户端继续发送一个请求信息和请求体去确定源端服务是否愿意接受请求（基于请求消息头）在客户端发送请求体之前。使用100继续握手能够有效的提高需要目标服务器健全的封装实体方法的请求（如POST和PUT）。100继续握手需要小心使用，因为对于不支持1.1协议的HTTP服务器和代理服务器可能会产生问题。这个参数如果不设置，HTTP客户端不会尝试去使用握手。
WAIT_FOR_CONTINUE定义了客户端等待100继续相应的最大毫秒时间。如果不设置，默认是3秒。