Fundamentals
7
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.
1.1.7.1. HTML forms
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.
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);
The 
UrlEncodedFormEntity
instance will use the so called URL encoding to encode parameters and
produce the following content:
param1=value1&param2=value2
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.
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);
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.
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();
Convert pdf to powerpoint online - SDK application service:C# Create PDF from PowerPoint Library to convert pptx, ppt to PDF in C#.net, ASP.NET MVC, WinForms, WPF
Online C# Tutorial for Creating PDF from Microsoft PowerPoint Presentation
www.rasteredge.com
Convert pdf to powerpoint online - SDK application service:VB.NET Create PDF from PowerPoint Library to convert pptx, ppt to PDF in vb.net, ASP.NET MVC, WinForms, WPF
VB.NET Tutorial for Export PDF file from Microsoft Office PowerPoint
www.rasteredge.com
Fundamentals
8
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);
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.
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.
ConnectionKeepAliveStrategy keepAliveStrat = new DefaultConnectionKeepAliveStrategy() {
@Override
public long getKeepAliveDuration(
HttpResponse response,
HttpContext context) {
long keepAlive = super.getKeepAliveDuration(response, context);
if (keepAlive == -1) {
// Keep connections alive 5 seconds if a keep-alive value
// has not be explicitly set by the server
keepAlive = 5000;
}
return keepAlive;
}
};
CloseableHttpClient httpclient = HttpClients.custom()
.setKeepAliveStrategy(keepAliveStrat)
.build();
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.
SDK application service:Online Convert PowerPoint to PDF file. Best free online export
Online Powerpoint to PDF Converter. Download Free Trial. Convert a PPTX/PPT File to PDF. Just upload your file by clicking on the blue
www.rasteredge.com
SDK application service:VB.NET PDF - Convert PDF Online with VB.NET HTML5 PDF Viewer
RasterEdge. PRODUCTS: ONLINE DEMOS: Online HTML5 Document Viewer; Online XDoc.PDF Word to PDF; Convert Excel to PDF; Convert PowerPoint to PDF; Convert Image
www.rasteredge.com
Fundamentals
9
1.2.2. HttpClient resource deallocation
When  an  instance 
CloseableHttpClient
is  no  longer  needed  and  is  about  to  go  out
of  scope  the  connection  manager  associated  with  it  must  be  shut  down  by  calling  the
CloseableHttpClient#close()
method.
CloseableHttpClient httpclient = HttpClients.createDefault();
try {
<...>
} finally {
httpclient.close();
}
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<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.
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.
In the course of HTTP request execution HttpClient adds the following attributes to the execution
context:
HttpConnection
instance representing the actual connection to the target server.
HttpHost
instance representing the connection target.
HttpRoute
instance representing the complete connection route
HttpRequest
instance representing the actual HTTP request. The final HttpRequest object in the
execution context always represents the state of the message exactly as it was sent to the target
server. Per default HTTP/1.0 and HTTP/1.1 use relative request URIs. However if the request is
sent via a proxy in a non-tunneling mode then the URI will be absolute.
HttpResponse
instance representing the actual HTTP response.
java.lang.Boolean
object representing the flag indicating whether the actual request has been fully
transmitted to the connection target.
RequestConfig
object representing the actual request configuation.
java.util.List<URI>
object representing a collection of all redirect locations received in the
process of request execution.
One can use 
HttpClientContext
adaptor class to simplify interractions with the context state.
SDK application service:C# HTML5 PDF Viewer SDK to convert and export PDF document to
RasterEdge. PRODUCTS: ONLINE DEMOS: Online HTML5 Document Viewer; Online XDoc.PDF Word to PDF; Convert Excel to PDF; Convert PowerPoint to PDF; Convert Image
www.rasteredge.com
SDK application service:XDoc.HTML5 Viewer for .NET, Zero Footprint AJAX Document Image
View, Convert, Edit, Sign Documents and Images. Online Demo See the HTML5 Viewer SDK for .NET in powerful & profession imaging controls, PDF document, image to
www.rasteredge.com
Fundamentals
10
HttpContext context = <...>
HttpClientContext clientContext = HttpClientContext.adapt(context);
HttpHost target = clientContext.getTargetHost();
HttpRequest request = clientContext.getRequest();
HttpResponse response = clientContext.getResponse();
RequestConfig config = clientContext.getRequestConfig();
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.
CloseableHttpClient httpclient = HttpClients.createDefault();
RequestConfig requestConfig = RequestConfig.custom()
.setSocketTimeout(1000)
.setConnectTimeout(1000)
.build();
HttpGet httpget1 = new HttpGet("http://localhost/1");
httpget1.setConfig(requestConfig);
CloseableHttpResponse response1 = httpclient.execute(httpget1, context);
try {
HttpEntity entity1 = response1.getEntity();
} finally {
response1.close();
}
HttpGet httpget2 = new HttpGet("http://localhost/2");
CloseableHttpResponse response2 = httpclient.execute(httpget2, context);
try {
HttpEntity entity2 = response2.getEntity();
} finally {
response2.close();
}
1.4. HTTP protocol interceptors
The 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 one specific header or a group of
related headers. Protocol interceptors can also 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.
Protocol interceptors can collaborate by sharing information - such as a processing state - through the
HTTP execution context. Protocol interceptors can use HTTP context to store a processing state for
one request or several consecutive requests.
Usually the order in which interceptors are executed should not matter as long as they do not depend on
a particular state of the execution context. If protocol interceptors have interdependencies and therefore
must be executed in a particular order, they should be added to the protocol processor in the same
sequence as their expected execution order.
Protocol interceptors must be implemented as thread-safe. Similarly to servlets, protocol interceptors
should not use instance variables unless access to those variables is synchronized.
SDK application service:C# PDF Convert to Jpeg SDK: Convert PDF to JPEG images in C#.net
NET library to batch convert PDF files to jpg image files. Turn multiple pages PDF into single jpg files respectively online.
www.rasteredge.com
SDK application service:VB.NET PDF Convert to Jpeg SDK: Convert PDF to JPEG images in vb.
RasterEdge. PRODUCTS: ONLINE DEMOS: Online HTML5 Document Viewer; Online XDoc.PDF Word to PDF; Convert Excel to PDF; Convert PowerPoint to PDF; Convert Image
www.rasteredge.com
Fundamentals
11
This is an example of how local context can be used to persist a processing state between consecutive
requests:
CloseableHttpClient httpclient = HttpClients.custom()
.addInterceptorLast(new HttpRequestInterceptor() {
public void process(
final HttpRequest request,
final HttpContext context) throws HttpException, IOException {
AtomicInteger count = (AtomicInteger) context.getAttribute("count");
request.addHeader("Count", Integer.toString(count.getAndIncrement()));
}
})
.build();
AtomicInteger count = new AtomicInteger(1);
HttpClientContext localContext = HttpClientContext.create();
localContext.setAttribute("count", count);
HttpGet httpget = new HttpGet("http://localhost/");
for (int i = 0; i < 10; i++) {
CloseableHttpResponse response = httpclient.execute(httpget, localContext);
try {
HttpEntity entity = response.getEntity();
} finally {
response.close();
}
}
1.5. Exception handling
HTTP protocol processors 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. Please
note that 
HttpClient 
implementations re-throw 
HttpException
s as 
ClientProtocolException
,
which is a subclass of 
java.io.IOException
. This enables the users of 
HttpClient
to handle both I/
O errors and protocol violations from a single catch clause.
1.5.1. HTTP transport safety
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 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 once. In
some cases this may lead to application data corruption or inconsistent application state.
Even though HTTP has never been designed to support transactional processing, it can still be used
as a transport protocol for mission critical applications provided certain conditions are met. To ensure
HTTP transport layer safety the system must ensure the idempotency of HTTP methods on the
application layer.
SDK application service:C# HTML5 PDF Viewer SDK to view PDF document online in C#.NET
RasterEdge. PRODUCTS: ONLINE DEMOS: Online HTML5 Document Viewer; Online XDoc.PDF Word to PDF; Convert Excel to PDF; Convert PowerPoint to PDF; Convert Image
www.rasteredge.com
SDK application service:VB.NET PDF Convert to HTML SDK: Convert PDF to html files in vb.
Convert PDF to HTML. |. Home ›› XDoc.PDF ›› VB.NET PDF: PDF to HTML. Convert PDF to HTML in VB.NET Demo Code. Add necessary references:
www.rasteredge.com
Fundamentals
12
1.5.2. Idempotent methods
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 identical requests is the same as for a single request]
In other words the application ought to ensure that it is prepared to deal with the implications of multiple
execution of the same method. This can be achieved, for instance, by providing a unique transaction
id and by other means of avoiding execution of the same logical operation.
Please note that this problem is not specific to HttpClient. Browser based applications are subject to
exactly the same issues related to HTTP methods non-idempotency.
By default HttpClient assumes only non-entity enclosing methods such as 
GET
and 
HEAD
to be
idempotent and entity enclosing methods such as 
POST
and 
PUT
to be not for compatibility reasons.
1.5.3. Automatic exception recovery
By default HttpClient attempts to automatically recover from I/O exceptions. The default auto-recovery
mechanism is limited to just a few exceptions that are known to be safe.
• HttpClient will make no attempt to recover from any logical or HTTP protocol errors (those derived
from 
HttpException
class).
• HttpClient will automatically retry those methods that are assumed to be idempotent.
• HttpClient will automatically retry those methods that fail with a transport exception while the HTTP
request is still being transmitted to the target server (i.e. the request has not been fully transmitted
to the server).
1.5.4. Request retry handler
In order to enable a custom exception recovery mechanism one should provide an implementation of
the 
HttpRequestRetryHandler
interface.
HttpRequestRetryHandler myRetryHandler = new HttpRequestRetryHandler() {
public boolean retryRequest(
IOException exception,
int executionCount,
HttpContext context) {
if (executionCount >= 5) {
// Do not retry if over max retry count
return false;
}
if (exception instanceof InterruptedIOException) {
// Timeout
return false;
}
if (exception instanceof UnknownHostException) {
// Unknown host
return false;
}
if (exception instanceof ConnectTimeoutException) {
// Connection refused
return false;
Fundamentals
13
}
if (exception instanceof SSLException) {
// SSL handshake exception
return false;
}
HttpClientContext clientContext = HttpClientContext.adapt(context);
HttpRequest request = clientContext.getRequest();
boolean idempotent = !(request instanceof HttpEntityEnclosingRequest);
if (idempotent) {
// Retry if the request is considered idempotent
return true;
}
return false;
}
};
CloseableHttpClient httpclient = HttpClients.custom()
.setRetryHandler(myRetryHandler)
.build();
Please note that one can use 
StandardHttpRequestRetryHandler
instead of the one used by default in
order to treat those request methods defined as idempotent by RFC-2616 as safe to retry automatically:
GET
HEAD
PUT
DELETE
OPTIONS
, and 
TRACE
.
1.6. 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
1.7. Redirect handling
HttpClient handles all types of redirects automatically, except those explicitly prohibited by the HTTP
specification as requiring user intervention. 
See Other
(status code 303) redirects on 
POST
and 
PUT
requests are converted to 
GET
requests as required by the HTTP specification. One can use a custom
redirect strategy to relaxe restrictions on automatic redirection of POST methods imposed by the HTTP
specification.
LaxRedirectStrategy redirectStrategy = new LaxRedirectStrategy();
CloseableHttpClient httpclient = HttpClients.custom()
.setRedirectStrategy(redirectStrategy)
.build();
HttpClient often has to rewrite the request message in the process of its execution. Per default HTTP/1.0
and HTTP/1.1 generally use relative request URIs. Likewise, original request may get redirected from
location to another multiple times. The final interpreted absolute HTTP location can be built using
the original request and the context. The utility method 
URIUtils#resolve
can be used to build the
interpreted absolute URI used to generate the final request. This method includes the last fragment
identifier from the redirect requests or the original request.
Fundamentals
14
CloseableHttpClient httpclient = HttpClients.createDefault();
HttpClientContext context = HttpClientContext.create();
HttpGet httpget = new HttpGet("http://localhost:8080/");
CloseableHttpResponse response = httpclient.execute(httpget, context);
try {
HttpHost target = context.getTargetHost();
List<URI> redirectLocations = context.getRedirectLocations();
URI location = URIUtils.resolve(httpget.getURI(), target, redirectLocations);
System.out.println("Final HTTP location: " + location.toASCIIString());
// Expected to be an absolute URI
} finally {
response.close();
}
15
Chapter 2. Connection management
2.1. Connection persistence
The process of establishing a connection from one host to another is quite complex and involves
multiple packet exchanges between two endpoints, which can be quite time consuming. The overhead
of connection handshaking can be significant, especially for small HTTP messages. One can achieve
a much higher data throughput if open connections can be re-used to execute multiple requests.
HTTP/1.1 states that HTTP connections can be re-used for multiple requests per default. HTTP/1.0
compliant endpoints can also use a mechanism to explicitly communicate their preference to keep
connection alive and use it for multiple requests. HTTP agents can also keep idle connections alive for
a certain period time in case a connection to the same target host is needed for subsequent requests.
The ability to keep connections alive is usually refered to as connection persistence. HttpClient fully
supports connection persistence.
2.2. HTTP connection routing
HttpClient is capable of establishing connections to the target host either directly or via a route that
may involve multiple intermediate connections - also referred to as hops. HttpClient differentiates
connections of a route into plain, tunneled and layered. The use of multiple intermediate proxies to
tunnel connections to the target host is referred to as proxy chaining.
Plain routes are established by connecting to the target or the first and only proxy. Tunnelled routes
are established by connecting to the first and tunnelling through a chain of proxies to the target. Routes
without a proxy cannot be tunnelled. Layered routes are established by layering a protocol over an
existing connection. Protocols can only be layered over a tunnel to the target, or over a direct connection
without proxies.
2.2.1. Route computation
The 
RouteInfo
interface represents information about a definitive route to a target host involving
one or more intermediate steps or hops. 
HttpRoute
is a concrete implementation of the 
RouteInfo
,
which cannot be changed (is immutable). 
HttpTracker
is a mutable 
RouteInfo
implementation used
internally by HttpClient to track the remaining hops to the ultimate route target. 
HttpTracker
can be
updated after a successful execution of the next hop towards the route target. 
HttpRouteDirector
is
a helper class that can be used to compute the next step in a route. This class is used internally by
HttpClient.
HttpRoutePlanner
is an interface representing a strategy to compute a complete route to a given target
based on the execution context. HttpClient ships with two default 
HttpRoutePlanner
implementations.
SystemDefaultRoutePlanner
is based on 
java.net.ProxySelector
. By default, it will pick up the
proxy settings of the JVM, either from system properties or from the browser running the application.
The 
DefaultProxyRoutePlanner
implementation does not make use of any Java system properties,
nor any system or browser proxy settings. It always computes routes via the same default proxy.
2.2.2. Secure HTTP connections
HTTP connections can be considered secure if information transmitted between two connection
endpoints cannot be read or tampered with by an unauthorized third party. The SSL/TLS protocol
Connection management
16
is the most widely used technique to ensure HTTP transport security. However, other encryption
techniques could be employed as well. Usually, HTTP transport is layered over the SSL/TLS encrypted
connection.
2.3. HTTP connection managers
2.3.1. Managed connections and connection managers
HTTP connections are complex, stateful, thread-unsafe objects which need to be properly managed to
function correctly. HTTP connections can only be used by one execution thread at a time. HttpClient
employs a special entity to manage access to HTTP connections called HTTP connection manager
and represented by the 
HttpClientConnectionManager
interface. The purpose of an HTTP connection
manager is to serve as a factory for new HTTP connections, to manage life cycle of persistent
connections and to synchronize access to persistent connections making sure that only one thread can
have access to a connection at a time. Internally HTTP connection managers work with instances of
ManagedHttpClientConnection
acting as a proxy for a real connection that manages connection state
and controls execution of I/O operations. If a managed connection is released or get explicitly closed
by its consumer the underlying connection gets detached from its proxy and is returned back to the
manager. Even though the service consumer still holds a reference to the proxy instance, it is no longer
able to execute any I/O operations or change the state of the real connection either intentionally or
unintentionally.
This is an example of acquiring a connection from a connection manager:
HttpClientContext context = HttpClientContext.create();
HttpClientConnectionManager connMrg = new BasicHttpClientConnectionManager();
HttpRoute route = new HttpRoute(new HttpHost("localhost", 80));
// Request new connection. This can be a long process
ConnectionRequest connRequest = connMrg.requestConnection(route, null);
// Wait for connection up to 10 sec
HttpClientConnection conn = connRequest.get(10, TimeUnit.SECONDS);
try {
// If not open
if (!conn.isOpen()) {
// establish connection based on its route info
connMrg.connect(conn, route, 1000, context);
// and mark it as route complete
connMrg.routeComplete(conn, route, context);
}
// Do useful things with the connection.
} finally {
connMrg.releaseConnection(conn, null, 1, TimeUnit.MINUTES);
}
The connection request can be terminated prematurely by calling 
ConnectionRequest#cancel()
if
necessary. This will unblock the thread blocked in the 
ConnectionRequest#get()
method.
2.3.2. Simple connection manager
BasicHttpClientConnectionManager
is  a  simple  connection  manager  that  maintains  only one
connection at a time. Even though this class is thread-safe it ought to be used by one execution thread
only. 
BasicHttpClientConnectionManager
will make an effort to reuse the connection for subsequent
requests with the same route. It will, however, close the existing connection and re-open it for the
given route, if the route of the persistent connection does not match that of the connection request. If
the connection has been already been allocated, then 
java.lang.IllegalStateException
is thrown.
Documents you may be interested
Documents you may be interested