ImageLoader

ImageLoader is a simple library that helps you fetch, load and cache images in Android apps.
It downloads images away from the UI thread and caches with a two-level in-memory/SD card cache.

Recent changes

1.5.5

• Bug fixes
• New DirectLoader utility to directly download images (do not use on main thread)

1.5.2

• Added support to load a cached small image as the preview for a larger image

1.5.1

• Improved concurrent loader
• Change SD card cache directory to respect Android SDK guidelines
• Improved LruBitmapCache

Using the library

The demo project is a good place to start. Import it in Eclipse and check the task list to see the TODO list.

If you’re lazy, here are the steps :

Overview

In the Application class

Add the following code that initialises the image loader:

@Override
public void onCreate() {
    super.onCreate();
    LoaderSettings settings = new SettingsBuilder()
      .withDisconnectOnEveryCall(true).build(this);
    imageManager = new ImageManager(this, settings);
}

public static final ImageManager getImageManager() {
    return imageManager;
}

This sets up the image loader with size of the images that are taken from the display and the background image use while the image loader is fetching the real image.

The default cache uses soft references. On a memory-constrained system like Android, the system can reclaim space too often. This limits the performance of the cache. To avoid this problem we added an LruCache implementation. This is really useful when you have lots of small images.

...
settings = new SettingsBuilder()
  .withCacheManager(new LruBitmapCache(this)).build(this);
thumbnailImageLoader = new ImageManager(this, settings);

The LruBitmapCache will take 25% of the free memory available for the cache by default. You can change this by using an alternative constructor:

int PERCENTAGE_OF_CACHE = 50;
settings = new SettingsBuilder()
  .withCacheManager(new LruBitmapCache(this, PERCENTAGE_OF_CACHE)).build(this);
thumbnailImageLoader = new ImageManager(this, settings);

Additional settings

Image loader uses UrlConnection to fetch images. There are two important parameters that UrlConnection uses: connectionTimeout and readTimeout.

SettingsBuilder builder = new SettingsBuilder();
Settings settings = builder.withConnectionTimeout(20000)
  .withReadTimeout(30000).build(this);

The connection timeout is the timeout in making the initial connection. The read timeout is the timeout on waiting to read data.

Preview image

Preview image works well when you have a list of items with small images and you display a larger version of the same image when you click through.
ImageLoader will take the small picture in the cache (if available) and load it in place of the large image whilst loading the real image.
This can be implemented in two ways: changing the image tag before calling the load method or changing the ImageTagFactory.

//Image Tag after normal settings... add this: 
imageTag.setPreviewHeight(100);
imageTag.setPreviewHeight(100);
imageTag.setPreviewUrl(previewUrl);
imageView.setTag(imageTag);
getImageManager().getLoader().load(imageView);

//If the small image used as preview has the same url of the big image
//you can use the image tag factory
imageTagFactory = new ImageTagFactory(this, R.drawable.loading);
imageTagFactory.setErrorImageId(R.drawable.image_not_found);
imageTagFactory.usePreviewImage(THUMB_IMAGE_SIZE, THUMB_IMAGE_SIZE, true);
//keep the instance of the tag factory somewhere

//on bind 
ImageView imageView = (ImageView) view;
String url = cursor.getString(columnIndex);
imageView.setTag(imageTagFactory.build(url));
ImgSearch.getImageManager().getLoader().load(imageView);

Cleaning up SD card

If you want ImageLoader to clean up the SD card, you can use the following code in the onCreate of the Application class:

imageManager.getFileManager().clean(this);

In the settings you can override the default expiration period that is set to 7 days.

In the Activity

When you need to load the image in a view object you just need to get the image loader from the Application class and call load.
This is an example of a ListView with the binder setting the url in the ImageView as a tag:

ImageTagFactory imageTagFactory = new ImageTagFactory(this, R.drawable.bg_img_loading);
imageTagFactory.setErrorImageId(R.drawable.bg_img_notfound);
...

private ViewBinder getViewBinder() {
  return new ViewBinder() {
    @Override
    public boolean setViewValue(View view, Cursor cursor, int columnIndex) {
      // TODO add this to your class
      ImageTag tag = imageTagFactory.build(cursor.getString(columnIndex))
      ((ImageView) view).setTag(tag);
      imageLoader.load(view);
      //
      return true;
    }
  };
}

The image loader will fetch the image from the cache (if available), from the SD card, or from the network as a last resort.

In the AndroidManifest.xml

There are two things you need to add: Permissions and the Service to clean up the files.

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<service android:name="com.novoda.imageloader.core.service.CacheCleaner" android:exported="true">
  <intent-filter>
    <action android:name="com.novoda.imageloader.core.action.CLEAN_CACHE" />
  </intent-filter>
</service>

Getting the library

Using Maven

If you are using Maven you need to define the repo and dependency in your POM:

<repositories>
  <repository>
    <id>public-mvn-repo-releases</id>
    <url>https://github.com/novoda/public-mvn-repo/raw/master/releases</url>
  </repository>
</repositories>

<dependency>
  <groupId>com.novoda.imageloader</groupId>
  <artifactId>imageloader-core</artifactId>
 <version>1.5.5</version>
</dependency>

As a .jar

You can also simply include the latest version of the .jar file (v 1.5.5) in you project.

Helping out

Report issues

If you have a problem with the library or want to suggest new features, let us know by creating an issue in GitHub.

ImageLoader projects

• core: Java project
• demo: Android project to test ImageLoader
• acceptance: Android project for Robotium instrumentation tests
• monkey: Example takes snapshots with monkeyrunner (deprecated)

Building the projects:

• Run: mvn clean install -Peclipse

Parent project and core

Importing the projects with maven should be simple and painless.

Demo and acceptance

• Create a new Android project in Eclipse
• Add the necessary jars from the libs folder

Requirements

• Maven 3.0.3+

License

Copyright © 2012 Novoda Ltd.
Released under the Apache License, Version 2.0