Android Asynchronous Http Client

「爱情、让人受尽委屈。」 2022-06-11 08:30 182阅读 0赞

原文： [http://loopj.com/android-async-http/][http_loopj.com_android-async-http]

## Overview ##

An asynchronous callback-based Http client for Android built on top of Apache’s [HttpClient][] libraries. All requests are made outside of your app’s main UI thread, but any callback logic will be executed on the same thread as the callback was created using Android’s Handler message passing.

## Features ##

*  Make asynchronous HTTP requests, handle responses in anonymous callbacks
 *  HTTP requests happen outside the UI thread
 *  Requests use a threadpool to cap concurrent resource usage
 *  GET/POST params builder (RequestParams)
 *  Multipart file uploads with no additional third party libraries
 *  Tiny size overhead to your application, only 25kb for everything
 *  Automatic smart request retries optimized for spotty mobile connections
 *  Automatic gzip response decoding support for super-fast requests
 *  Binary file (images etc) downloading with `BinaryHttpResponseHandler`
 *  Built-in response parsing into JSON with `JsonHttpResponseHandler`
 *  Persistent cookie store, saves cookies into your app’s SharedPreferences

## Who is Using It? ##

[Heyzap][]

Social game discovery app with millions of users

[DoubanFM][]

Popular personal online music radio service

[Pose][]

Pose is the \#1 fashion app for sharing and discovering new styles

[Pocket Salsa][]

Pocket Salsa is the easiest way to learn how to dance salsa.

Send me a [message][] on github to let me know if you are using this library in a released android application!

## Installation & Basic Usage ##

Download the latest .jar file from github and place it in your Android app’s `libs/` folder.

Import the http package.

import com.loopj.android.http.*;

Create a new `AsyncHttpClient` instance and make a request:

AsyncHttpClient client = new AsyncHttpClient();
    client.get("http://www.google.com", new AsyncHttpResponseHandler() { 
        @Override
        public void onSuccess(String response) { 
            System.out.println(response);
        }
    });

## Recommended Usage: Make a Static Http Client ##

In this example, we’ll make a http client class with static accessors to make it easy to communicate with Twitter’s API.

import com.loopj.android.http.*;
    
    public class TwitterRestClient { 
      private static final String BASE_URL = "http://api.twitter.com/1/";
    
      private static AsyncHttpClient client = new AsyncHttpClient();
    
      public static void get(String url, RequestParams params, AsyncHttpResponseHandler responseHandler) { 
          client.get(getAbsoluteUrl(url), params, responseHandler);
      }
    
      public static void post(String url, RequestParams params, AsyncHttpResponseHandler responseHandler) { 
          client.post(getAbsoluteUrl(url), params, responseHandler);
      }
    
      private static String getAbsoluteUrl(String relativeUrl) { 
          return BASE_URL + relativeUrl;
      }
    }

This then makes it very easy to work with the Twitter API in your code:

import org.json.*;
    import com.loopj.android.http.*;
    
    class TwitterRestClientUsage { 
        public void getPublicTimeline() throws JSONException { 
            TwitterRestClient.get("statuses/public_timeline.json", null, new JsonHttpResponseHandler() { 
                @Override
                public void onSuccess(JSONArray response) { 
                    // Pull out the first event on the public timeline
                    JSONObject firstEvent = timeline.get(0);
                    String tweetText = firstEvent.getString("text");
    
                    // Do something with the response
                    System.out.println(tweetText);
                }
            });
        }
    }

Check out the [AsyncHttpClient][], [RequestParams][] and [AsyncHttpResponseHandler][]Javadocs for more details.

## Persistent Cookie Storage with `PersistentCookieStore` ##

This library also includes a `PersistentCookieStore` which is an implementation of the Apache HttpClient `CookieStore` interface that automatically saves cookies to `SharedPreferences` storage on the Android device.

This is extremely useful if you want to use cookies to manage authentication sessions, since the user will remain logged in even after closing and re-opening your app.

First, create an instance of `AsyncHttpClient`:

AsyncHttpClient myClient = new AsyncHttpClient();

Now set this client’s cookie store to be a new instance of`PersistentCookieStore`, constructed with an activity or application context (usually `this` will suffice):

PersistentCookieStore myCookieStore = new PersistentCookieStore(this);
    myClient.setCookieStore(myCookieStore);

Any cookies received from servers will now be stored in the persistent cookie store.

To add your own cookies to the store, simply construct a new cookie and call `addCookie`:

BasicClientCookie newCookie = new BasicClientCookie("cookiesare", "awesome");
    newCookie.setVersion(1);
    newCookie.setDomain("mydomain.com");
    newCookie.setPath("/");
    myCookieStore.addCookie(newCookie);

See the [PersistentCookieStore Javadoc][] for more information.

## Adding GET/POST Parameters with `RequestParams` ##

The `RequestParams` class is used to add optional GET or POST parameters to your requests. `RequestParams` can be built and constructed in various ways:

Create empty `RequestParams` and immediately add some parameters:

RequestParams params = new RequestParams();
    params.put("key", "value");
    params.put("more", "data");

Create `RequestParams` for a single parameter:

RequestParams params = new RequestParams("single", "value");

Create `RequestParams` from an existing `Map` of key/value strings:

HashMap<String, String> paramMap = new HashMap<String, String>();
    paramMap.put("key", "value");
    RequestParams params = new RequestParams(paramMap);

See the [RequestParams Javadoc][RequestParams] for more information.

## Uploading Files with `RequestParams` ##

The `RequestParams` class additionally supports multipart file uploads as follows:

Add an `InputStream` to the `RequestParams` to upload:

InputStream myInputStream = blah;
    RequestParams params = new RequestParams();
    params.put("secret_passwords", myInputStream, "passwords.txt");

Add a `File` object to the `RequestParams` to upload:

File myFile = new File("/path/to/file.png");
    RequestParams params = new RequestParams();
    try { 
        params.put("profile_picture", myFile);
    } catch(FileNotFoundException e) {}

Add a byte array to the `RequestParams` to upload:

byte[] myByteArray = blah;
    RequestParams params = new RequestParams();
    params.put("soundtrack", new ByteArrayInputStream(myByteArray), "she-wolf.mp3");

See the [RequestParams Javadoc][RequestParams] for more information.

## Downloading Binary Data with `BinaryHttpResponseHandler` ##

The `BinaryHttpResponseHandler` class can be used to fetch binary data such as images and other files. For example:

AsyncHttpClient client = new AsyncHttpClient();
    String[] allowedContentTypes = new String[] {  "image/png", "image/jpeg" };
    client.get("http://example.com/file.png", new BinaryHttpResponseHandler(allowedContentTypes) { 
        @Override
        public void onSuccess(byte[] fileData) { 
            // Do something with the file
        }
    });

See the [BinaryHttpResponseHandler Javadoc][] for more information.

## Adding HTTP Basic Auth credentials ##

Some requests may need username/password credentials when dealing with API services that use HTTP Basic Access Authentication requests. You can use the method `setBasicAuth()` to provide your credentials.

Set username/password for any host and realm for a particular request. By default the Authentication Scope is for any host, port and realm.

AsyncHttpClient client = new AsyncHttpClient();
    client.setBasicAuth("username","password/token");
    client.get("http://example.com");

You can also provide a more specific Authentication Scope (recommended)

AsyncHttpClient client = new AsyncHttpClient();
    client.setBasicAuth("username","password", new AuthScope("example.com", 80, AuthScope.ANY_REALM));
    client.get("http://example.com");

See the [RequestParams Javadoc][AsyncHttpClient] for more information.

## Building from Source ##

To build a `.jar` file from source, first make a clone of the android-async-http github repository. You’ll then need to copy the `local.properties.dist` file to `local.properties` and edit the `sdk.dir` setting to point to where you have the android sdk installed. You can then run:

ant package

This will generate a file named `android-async-http-version.jar`.

## Reporting Bugs or Feature Requests ##

Please report any bugs or feature requests on the github issues page for this project here:

[https://github.com/loopj/android-async-http/issues][https_github.com_loopj_android-async-http_issues]

## Credits & Contributors ##

James Smith ( [http://github.com/loopj][http_github.com_loopj])

Creator and Maintainer

Micah Fivecoate ( [http://github.com/m5][http_github.com_m5])

Major Contributor, including the original  `RequestParams`

The Droid Fu Project ( [https://github.com/kaeppler/droid-fu][https_github.com_kaeppler_droid-fu])

Inspiration and code for better http retries

Rafael Sanches ( [http://blog.rafaelsanches.com][http_blog.rafaelsanches.com])

Original  `SimpleMultipartEntity` code

Anthony Persaud ( [http://github.com/apersaud][http_github.com_apersaud])

Added support for HTTP Basic Authentication requests.

Linden Darling ( [http://github.com/coreform][http_github.com_coreform])

Added support for binary/image responses

## License ##

The Android Asynchronous Http Client is released under the Android-friendly Apache License, Version 2.0. Read the full license here:

[http://www.apache.org/licenses/LICENSE-2.0][http_www.apache.org_licenses_LICENSE-2.0]

## About the Author ##

I'm James Smith, CTO of [heyzap.com][]. Originally from London, UK I now live in San Francisco.

[http_loopj.com_android-async-http]: http://loopj.com/android-async-http/
[HttpClient]: http://hc.apache.org/httpcomponents-client-ga/
[Heyzap]: https://market.android.com/details?id=com.heyzap.android
[DoubanFM]: https://market.android.com/details?id=com.douban.radio
[Pose]: https://market.android.com/details?id=com.pose
[Pocket Salsa]: https://play.google.com/store/apps/details?id=com.addicted2salsa.pocketsalsa&hl=en
[message]: https://github.com/inbox/new?to=loopj
[AsyncHttpClient]: http://loopj.com/android-async-http/doc/com/loopj/android/http/AsyncHttpClient.html
[RequestParams]: http://loopj.com/android-async-http/doc/com/loopj/android/http/RequestParams.html
[AsyncHttpResponseHandler]: http://loopj.com/android-async-http/doc/com/loopj/android/http/AsyncHttpResponseHandler.html
[PersistentCookieStore Javadoc]: http://loopj.com/android-async-http/doc/com/loopj/android/http/PersistentCookieStore.html
[BinaryHttpResponseHandler Javadoc]: http://loopj.com/android-async-http/doc/com/loopj/android/http/BinaryHttpResponseHandler.html
[https_github.com_loopj_android-async-http_issues]: https://github.com/loopj/android-async-http/issues
[http_github.com_loopj]: http://github.com/loopj
[http_github.com_m5]: http://github.com/m5
[https_github.com_kaeppler_droid-fu]: https://github.com/kaeppler/droid-fu
[http_blog.rafaelsanches.com]: http://blog.rafaelsanches.com/
[http_github.com_apersaud]: http://github.com/apersaud
[http_github.com_coreform]: http://github.com/coreform
[http_www.apache.org_licenses_LICENSE-2.0]: http://www.apache.org/licenses/LICENSE-2.0
[heyzap.com]: http://www.heyzap.com/