Android Networking Made Easy

Features

• Asynchronously download:
  • Images (into ImageViews or Bitmaps)
  • JSON
  • Strings
  • Files
  • Java types using Gson
• Easy to use Fluent API designed for Android
  • Automatically cancels operations when the calling Activity finishes
  • Manages invocation back onto the UI thread
  • ImageView loading, caching, and memory management (including ListView and convertView recycling)
  • All operations return a Future and can be cancelled
• HTTP POST/PUT:
  • text/plain
  • application/json
  • application/x-www-form-urlencoded
  • multipart/form-data
• Transparent usage of HTTP features and optimizations:
  • Caching
  • Gzip/Deflate Compression
  • Connection reuse
  • Cookies
• Request level logging and profiling
• Download progress callbacks
• Supports file:/, http(s):/, and content:/ URIs
• Based on NIO and AndroidAsync

Samples

The included documented ion-sample project includes some samples that demo common Android network operations:

• Twitter Client Sample
  • Download JSON from a server (twitter feed)
  • Populate a ListView Adapter and fetch more data as you scroll to the end
  • Put images from a URLs into ImageViews (twitter profile pictures)
• File Download with Progress Bar Sample

More Examples

Looking for more? Check out the examples below that demonstrate some other common scenarios. You can also take a look at 30+ ion unit tests in the ion-test.

Get JSON

Ion.with(context).load("http://example.com/thing.json")
.asJSONObject()
.setCallback(new FutureCallback<JSONObject>() {
   @Override
    public void onCompleted(Exception e, String result) {
        // do stuff with the result or error
    }
});

Post JSON and read JSON

JSONObject json = new JSONObject();
json.putString("foo", "bar");

Ion.with(context).load("http://example.com/post")
.setJSONObjectBody(json)
.asJSONObject()
.setCallback(new FutureCallback<JSONObject>() {
   @Override
    public void onCompleted(Exception e, String result) {
        // do stuff with the result or error
    }
});

Post application/x-www-form-urlencoded and read a String

Ion.with(getContext())
.load("https://koush.clockworkmod.com/test/echo")
.setBodyParameter("goop", "noop")
.setBodyParameter("foo", "bar")
.asString()
.setCallback(...)

Post multipart/form-data and read JSON

Ion.with(getContext())
.load("https://koush.clockworkmod.com/test/echo")
.setMultipartParameter("goop", "noop")
.setMultipartFile("filename.zip", new File("/sdcard/filename.zip"))
.asJSONObject()
.setCallback(...)

Download a File with a progress bar

Ion.with(context).load("http://example.com/really-big-file.zip")
.progressBar(progressBar)
// can also use a custom callback
.progress(new ProgressCallback() {@Override
   public void onProgress(int downloaded, int total) {
       System.out.println("" + downloaded + " / " + total);
   }
})
.write(new File("/sdcard/cm-11.zip")
.setCallback(new FutureCallback<File>() {
   @Override
    public void onCompleted(Exception e, File file) {
        // download done...
        // do stuff with the File or error
    }
});

Setting Headers

Ion.with(context).load("http://example.com/test.txt")
// set the header
.setHeader("foo", "bar")
.asString()
.setCallback(...)

Load an image into an ImageView

// This is the "long" way to do build an ImageView request... it allows you to set headers, etc.
Ion.with(context)
.load("http://example.com/image.png")
.withBitmap()
.placeholder(R.drawable.placeholder_image)
.error(R.drawable.error_image)
.animateLoad(spinAnimation)
.animateIn(fadeInAnimation)
.intoImageView(imageView);

// but for brevity, use the ImageView specific builder...
Ion.with(imageView)
.placeholder(R.drawable.placeholder_image)
.error(R.drawable.error_image)
.animateLoad(spinAnimation)
.animateIn(fadeInAnimation)
.load("http://example.com/image.png");

The Ion Image load API has the following features:

• Disk and memory caching
• Bitmaps are held via weak references so memory is managed very effeciently
• ListView Adapter recycling support
• Bitmap transformations via the .transform(Transform)
• Animate loading and loaded ImageView states

Futures

All operations return a custom Future that allows you to specify a callback that runs on completion.

public interface Future<T> extends Cancellable, java.util.concurrent.Future<T> {
    /**
     * Set a callback to be invoked when this Future completes.
     * @param callback
     * @return
     */
    public Future<T> setCallback(FutureCallback<T> callback);
}

Future<String> string = Ion.with(context)
    .load("http://example.com/string.txt")
    .asString();

Future<JSONObject> json = Ion.with(context)
    .load("http://example.com/json.json")
    .asJSONObject();

Future<File> file = Ion.with(context)
    .load("http://example.com/file.zip")
    .write(new File("/sdcard/file.zip"));

Future<Bitmap> bitmap = Ion.with(context)
    .load("http://example.com/image.png")
    .intoImageView(imageView);

Cancelling Requests

Futures can be cancelled by calling .cancel():

bitmap.cancel();
json.cancel();

Blocking on Requests

Though you should try to use callbacks for handling requests whenever possible, blocking on requests is possible too. All Futures have a Future.get() method that waits for the result of the request, by blocking if necessary.

JSONObject json = Ion.with(context).load("http://example.com/thing.json").asJSONObject().get();

Seamlessly use your own Java classes with Gson

public static class Tweet {
    public String id;
    public String text;
    public String photo;
}

public void getTweets() throws Exception {
    Ion.with(context)
    .load("http://example.com/api/tweets")
    .as(new TypeToken<List<Tweet>>(){});
    .setCallback(new FutureCallback<List<Tweet>>() {
       @Override
        public void onCompleted(Exception e, List<Tweet> tweets) {
          // chirp chirp
        }
    });
}

Logging

Wondering why your app is slow? Ion lets you do both global and request level logging.

To enable it globally:

Ion.getDefault(getContext()).setLogging("MyLogs", Log.DEBUG);

Or to enable it on just a single request:

Ion.with(context).load("http://example.com/thing.json")
.setLogging("MyLogs", Log.DEBUG)
.asJSONObject();

Log entries will look like this:

D/MyLogs(23153): (0 ms) http://example.com/thing.json: Executing request.
D/MyLogs(23153): (106 ms) http://example.com/thing.json: Connecting socket
D/MyLogs(23153): (2985 ms) http://example.com/thing.json: Response is not cacheable
D/MyLogs(23153): (3003 ms) http://example.com/thing.json: Connection successful