Migrating from HttpClient 3.1 to HttpClient 4.0

  • Post author:
  • Post category:Java

We were using Apache HttpClient 3.1 for some time now and have decide to bite the bullet and migrate over to HttpClient 4.0.3. It’s usually painless to¬†update Apache libraries, but HttpClient 4 was a complete rewrite and is not backward compatible. It’s also now a top level Apache project and no longer part of Apache Commons. Here are the things we had to change to migrate over to the latest HttpClient. This is a mini HttpClient 4 tutorial for those moving to the latest version. The time it takes you to migrate depends on how many references you have to change. It took us less than 30 minutes to do it on our project.

1. Replace commons-httpclient-3.1.jar with the latest httpclient-4.0.3.jar and httpmime-4.0.3.jar. You will also need httpcore-4.0.1.jar.

2. Change your import statements from org.apache.commons.httpclient.* to import org.apache.http.*. For example, change:

import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.HttpStatus;
import org.apache.commons.httpclient.HttpException;
import org.apache.commons.httpclient.methods.GetMethod;
import org.apache.commons.httpclient.ConnectTimeoutException;


import org.apache.http.client.HttpClient;
import org.apache.http.HttpStatus;
import org.apache.http.HttpException;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.conn.ConnectTimeoutException;
import org.apache.http.HttpResponse;
import org.apache.http.impl.client.DefaultHttpClient;

Notice the addition of HttpResponse and DefaultHttpClient, which will be used next.

3. Change your code from the old HttpClient interface to the new.

HttpClient 3.1:

HttpClient client = new HttpClient();
GetMethod method = new GetMethod(url);
int statusCode = client.executeMethod(method);
if (statusCode == HttpStatus.SC_OK) {
	InputStream is = method.getResponseBodyAsStream();
	// do something with the input stream

HttpClient 4.0:

HttpClient client = new DefaultHttpClient();
HttpGet method = new HttpGet(url);
HttpResponse httpResponse = client.execute(method);
int statusCode = httpResponse.getStatusLine().getStatusCode();
if (statusCode == HttpStatus.SC_OK) {
	InputStream is = httpResponse.getEntity().getContent();
	// do something with the input stream

We certainly did not use the full functionality of HttpClient, and most of our changes were similar to those listed above. For a complete examples on how to use HttpClient 4, visit the HttpClient 4.0.3 Tutorial. Do you have any other tips for HttpClient 3 to 4 migration?

This Post Has 9 Comments

  1. Triguna

    How to migrate setRequestEntity or setRequestBody of a PostMethod to HttpPost? Please help.


  2. eyuzwa

    @Triguna, you have to use the 4.0 lingo of “entities”. You need to basically create a list of name,value pairs. There’s more details in the link referenced in this post (the 4.0.3 Tutorial).

    Here’s a snippet:
    List formparams = new ArrayList();
    formparams.add(new BasicNameValuePair(“param1”, “value1”));
    formparams.add(new BasicNameValuePair(“param2”, “value2”));
    UrlEncodedFormEntity entity = new UrlEncodedFormEntity(formparams, “UTF-8”);
    HttpPost httppost = new HttpPost(“http://localhost/handler.do”);


  3. mirchi9

    What is the replacement for ProtocolSocketFactory in version 4.0?

  4. Eduardo Rodrigues

    I used to have the code below.
    How do I set the HttpVersion on the new API?

    client = new HttpClient();
    if (StringUtils.isEmpty(httpVersion) || “HTTP/1.1”.equals(httpVersion)) {
    } else {

  5. Binh Thanh Nguyen

    Thanks so much, this post is so useful. It saved me.

  6. Or Kazaz

    Eduardo Rodrigues, you will need to set it like this:
    SocketConfig socketConfig = SocketConfig.custom().setTcpNoDelay(true).setSoTimeout(10000).build();
    HttpClient httpClient = HttpClientBuilder.create().setDefaultSocketConfig(socketConfig).build();
    HttpUriRequest request = RequestBuilder.post()
    .addHeader(HttpHeaders.ACCEPT, “value”)
    try {
    } catch (IOException e) {

  7. Hema

    Hi All,

    How to migrate addParameter , removeParameter and getParameter of a PostMethod to HttpPost?

  8. Carl

    Did you ever get an answer on how to port these functions?

  9. Eswar

    why should we migrate from Commons HttpClient 3.x to HttpClient 4.1.what happens if we don’t upgrade it?

Comments are closed.