HTTP request

HTTP request All HTTP requests have a request line consisting a method name, a request URI and - a HTTP protocol version. + 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 special + TRACE and OPTIONS. There is a specific class for each method type.: HttpGet, HttpHead, HttpPost, HttpPut, HttpDelete, @@ -202,7 +202,7 @@ domain=localhost 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 methods: POST and + 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, @@ -310,7 +310,7 @@ if (entity != null) { } } ]]> - Please note that HttpEntity#writeTo(OutputStream) + 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 @@ -322,7 +322,8 @@ if (entity != null) { 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, one can simply + remaining content and making the connection reusable is too high, in which case + one can simply terminate the request by calling HttpUriRequest#abort() method.

Consuming entity content - The recommended way to consume content of an entity is by using its + 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 @@ -401,13 +402,13 @@ httppost.setEntity(entity); 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 generic InputStreamEntity. + self-contained instead of using the generic InputStreamEntity. FileEntity can be a good starting point.

Dynamic content entities Often HTTP entities need to be generated dynamically based a particular execution context. HttpClient provides support for dynamic entities by using - EntityTemplate entity class and + the EntityTemplate entity class and ContentProducer interface. Content producers are objects which produce their content on demand, by writing it out to an output stream. They are expected to be able produce their content every time @@ -433,9 +434,9 @@ httppost.setEntity(entity);

HTML forms - Many applications frequently need to simulate the process of submitting an + 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 special entity class + data. HttpClient provides the entity class UrlEncodedFormEntity to facilitate the process. - This UrlEncodedFormEntity instance will use the so + The UrlEncodedFormEntity instance will use the so called URL encoding to encode parameters and produce the following content: 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 the chunk coding is preferred + 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 well be ignored + 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. Response handlers The simplest and the most convenient way to handle responses is by using - ResponseHandler interface. This method completely + 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 + 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. java.util.Map<String, Object>. It is - simply a collection of arbitrary named values. Application can populate context - attributes prior to a request execution or examine the context after the execution has + a java.util.Map<String, Object>. 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. In the course of HTTP request execution HttpClient adds the following attributes to the execution context: @@ -594,13 +597,13 @@ Final target: http://www.google.ch and cannot be automatically recovered from.

HTTP transport safety - It is important to understand that the HTTP protocol is not well suited for all + It is important to understand that the HTTP protocol is not well suited to all types of applications. HTTP is a simple request/response oriented protocol which was initially designed to support static or dynamically generated content retrieval. It has never been intended to support transactional operations. For instance, the HTTP server will consider its part of the contract fulfilled if it succeeds in receiving and processing the request, generating a response and sending a status code back to - the client. The server will make no attempts to roll back the transaction if the + the client. The server will make no attempt to roll back the transaction if the client fails to receive the response in its entirety due to a read timeout, a request cancellation or a system crash. If the client decides to retry the same request, the server will inevitably end up executing the same transaction more than @@ -613,7 +616,7 @@ Final target: http://www.google.ch

Idempotent methods - HTTP/1.1 specification defines idempotent method as + HTTP/1.1 specification defines an idempotent method as Methods can also have the property of "idempotence" in that (aside from error or expiration issues) the side-effects of N > 0 @@ -706,23 +709,23 @@ httpclient.setHttpRequestRetryHandler(my

Aborting requests - In some situations HTTP request execution fail to complete within the expected time + 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 - blocked in an I/O operation is guaranteed to unblock by throwing a + - even if currently blocked in an I/O operation - is guaranteed to unblock by throwing a InterruptedIOException

HTTP protocol interceptors - HTTP protocol interceptor is a routine that implements a specific aspect of the HTTP + Th HTTP protocol interceptor is a routine that implements a specific aspect of the HTTP protocol. Usually protocol interceptors are expected to act upon one specific header or - a group of related headers of the incoming message or populate the outgoing message with + a group of related headers of the incoming message, or populate the outgoing message with one specific header or a group of related headers. Protocol interceptors can also - manipulate content entities enclosed with messages, transparent content compression / + manipulate content entities enclosed with messages - transparent content compression / decompression being a good example. Usually this is accomplished by using the 'Decorator' pattern where a wrapper entity class is used to decorate the original entity. Several protocol interceptors can be combined to form one logical unit. @@ -770,7 +773,7 @@ for (int i = 0; i < 10; i++) {

HTTP parameters - HttpParams interface represents a collection of immutable values that define a runtime + Thw HttpParams interface represents a collection of immutable values that define a runtime behavior of a component. In many ways HttpParams is similar to HttpContext. The main distinction between the two lies in their use at runtime. Both interfaces represent a collection of objects that @@ -811,13 +814,13 @@ for (int i = 0; i < 10; i++) {

HTTP parameters beans - HttpParams interface allows for a great deal of + 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 @@ -928,14 +931,14 @@ null 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 + If this parameter is not set, invalid Transfer-Encoding values will be ignored. 'http.protocol.expect-continue': - activates Expect: 100-Continue handshake for the entity + 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 @@ -944,11 +947,11 @@ null 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. - Expect: 100-continue handshake should be used with + 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 attempt to use the handshake. + java.lang.Boolean. If this parameter is not set, + HttpClient will not attempt to use the handshake.