Wrapper library around Android's HttpUrlConnection.
Switch branches/tags
Nothing to show
Clone or download

README.markdown

A basic Http client for Android 2.1+ devices using HttpURLConnection

Copyright (C) 2012 Pixmob (http://github.com/pixmob)

Android provides two methods for making Http(s) requests: HttpURLConnection and Apache HttpClient.

The Android development team recommends the use of HttpURLConnection for new applications, as this interface is getting better over Android releases.

However, using HttpURLConnection on earlier Android devices (before ICS) is troublesome because of the underlying implementation bugs:

  1. connection pool poisoning
  2. missing SSL certificates on some Android devices
  3. slow POST requests
  4. headers in lower-case
  5. incomplete read
  6. transparent Gzip compression
  7. broken Http authentication

The framework Pixmob HttpClient (PHC) provides a clean interface to HttpURLConnection, with workarounds for known bugs, from Android 2.1 to Android 4.0.

Using PHC will make your code easier to understand, while leveraging the Android native network layer.

Usage

Making Http requests is easy:

HttpClient hc = new HttpClient();
hc.get("http://www.google.com").execute();

Downloading a file is obvious:

File logoFile = new File(context.getCacheDir(), "logo.png");
hc.get("http://www.mysite.com/logo.png").to(logoFile).execute();

You may want to send POST requests:

// the response buffer is reusable across requests (GC friendly)
final StringBuilder buf = new StringBuilder(64);
hc.post("http://www.mysite.com/query").param("q", "hello").to(
    new HttpResponseHandler() {
        public void onResponse(HttpResponse response) throws Exception {
            response.read(buf);
            System.out.println(buf);
        }
    }
).execute();

The same request with fewer lines:

final HttpResponse response = hc.post("http://www.mysite.com/query").param("q", "hello").execute();
final StringBuilder buf = new StringBuilder(64);
response.read(buf);
System.out.println(buf);

Send an authenticated request (using Http Basic Authentication) this way:

// reuse the same authenticator instance across requests
final HttpBasicAuthenticator auth = new HttpBasicAuthenticator("admin", "secret");
hc.delete("https://www.mysite.com/item/12").with(auth).execute();

Google App Engine authentication is supported as well:

final String gaeHost = "myapp.appspot.com";
final GoogleAppEngineAuthenticator auth = new GoogleAppEngineAuthenticator(context, account, gaeHost);
try {
    hc.get("http://" + gaeHost).with(auth).execute();
} catch(UserInteractionRequiredException e) {
    // user authorization is required:
    // open system activity for granting access to user credentials
    // (user password is never stored nor known by this library)
    context.startActivityForResult(e.getUserIntent(), USER_AUTH);
}

Use the AbstractAccountAuthenticator class to create new authenticators using the AccountManager API from Android, without asking for the user password.

Pixmob HttpClient is not thread safe: create a HttpClient instance when you need to make network requests. Network resources are automatically freed by the framework.

Please read JavaDoc and source code for advanced use.

A sample application (with source code) is available in this repository. Get this app on Google Play!

License

All of the source code in this project is licensed under the Apache 2.0 license except as noted.

How to use this library in my project?

This project is actually a library project.