Universal Image Loader - Deployment and Usage Guide

Prerequisites

• Android Development Environment

  • Android Studio (recommended) or Eclipse with ADT
  • Android SDK with API level 16 (Android 4.1) or higher
  • Java Development Kit (JDK) 8 or higher

• Dependencies

  • Gradle 4.1+ (for modern Android projects)
  • Android Support Library (for sample app)

Installation

Adding to Your Project

Using Gradle (Recommended)

Add the following dependency to your build.gradle file:

dependencies {
    implementation 'com.nostra13.universalimageloader:universal-image-loader:1.9.5'
}

Using Maven

Add to your pom.xml:

<dependency>
    <groupId>com.nostra13.universalimageloader</groupId>
    <artifactId>universal-image-loader</artifactId>
    <version>1.9.5</version>
</dependency>

Manual Download

Download the JAR file directly:

• universal-image-loader-1.9.5.jar

Configuration

Basic Configuration

Initialize the ImageLoader in your Application class or Activity:

ImageLoaderConfiguration config = new ImageLoaderConfiguration.Builder(context)
    .threadPoolSize(3) // default
    .threadPriority(Thread.NORM_PRIORITY - 2) // default
    .denyCacheImageMultipleSizesInMemory()
    .memoryCache(new LruMemoryCache(2 * 1024 * 1024)) // 2MB cache
    .memoryCacheSize(2 * 1024 * 1024)
    .diskCache(new UnlimitedDiscCache(cacheDir)) // default
    .diskCacheSize(50 * 1024 * 1024) // 50MB cache
    .diskCacheFileCount(100)
    .diskCacheFileNameGenerator(new HashCodeFileNameGenerator()) // default
    .imageDownloader(new BaseImageDownloader(context)) // default
    .imageDecoder(new BaseImageDecoder()) // default
    .defaultDisplayImageOptions(DisplayImageOptions.createSimple()) // default
    .writeDebugLogs() // Remove for release app
    .build();

ImageLoader.getInstance().init(config);

Environment Variables

No specific environment variables are required for this library.

Build & Run

Sample Application

The repository includes a sample application to demonstrate usage:

1. Clone the repository:

git clone https://github.com/nostra13/Android-Universal-Image-Loader.git

2. Open in Android Studio:

   • File → Open → Select the sample directory

3. Build and run the sample app:

   • Connect an Android device or start an emulator
   • Click the "Run" button (green play icon)

Using in Your Application

Simple Usage

// Get singleton instance
ImageLoader imageLoader = ImageLoader.getInstance();

// Load and display image
imageLoader.displayImage("http://site.com/image.png", imageView);

With Custom Options

DisplayImageOptions options = new DisplayImageOptions.Builder()
    .showImageOnLoading(R.drawable.loading) // resource or drawable
    .showImageForEmptyUri(R.drawable.empty) // resource or drawable
    .showImageOnFail(R.drawable.fail) // resource or drawable
    .cacheInMemory(true)
    .cacheOnDisk(true)
    .considerExifParams(true)
    .bitmapConfig(Bitmap.Config.RGB_565) // default
    .build();

imageLoader.displayImage("http://site.com/image.png", imageView, options);

Deployment

Distribution

Since this is a library, deployment involves:

1. Including in Your App

   • The library is included as a dependency in your Android app
   • No separate deployment needed for the library itself

2. Publishing Your App

   • Build your APK using Android Studio
   • Sign the APK for release
   • Upload to Google Play Store or distribute via other channels

Platforms

• Google Play Store - Primary distribution platform for Android apps
• Amazon Appstore - Alternative Android app marketplace
• Direct Distribution - APK files can be distributed directly to users

Troubleshooting

Common Issues and Solutions

1. Image Not Loading

Problem: Images fail to load or display Solution:

• Check network connectivity
• Verify image URL is correct and accessible
• Ensure proper permissions in AndroidManifest.xml:

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

2. OutOfMemoryError

Problem: Application crashes due to memory issues Solution:

• Reduce memory cache size:

.memoryCache(new LruMemoryCache(2 * 1024 * 1024)) // 2MB instead of default

• Use appropriate bitmap configuration:

.bitmapConfig(Bitmap.Config.RGB_565) // instead of ARGB_8888

• Enable disk caching:

.cacheOnDisk(true)

3. Slow Image Loading

Problem: Images take too long to load Solution:

• Increase thread pool size:

.threadPoolSize(5) // default is 3

• Use progressive JPEG loading if supported
• Ensure disk cache is enabled and has sufficient space

4. Images Not Caching

Problem: Images reload every time instead of using cache Solution:

• Verify cache settings:

.cacheInMemory(true)
.cacheOnDisk(true)

• Check disk cache directory permissions
• Clear cache and test again

5. Context Issues

Problem: NullPointerException when initializing ImageLoader Solution:

• Ensure context is valid (use Application context for global initialization)
• Initialize ImageLoader in Application class's onCreate() method

Useful Information

• Acceptable URI Formats:

  • Web: "http://site.com/image.png"
  • File system: "file:///mnt/sdcard/image.png"
  • Content provider: "content://media/external/images/media/13"
  • Assets: "assets://image.png"
  • Drawables: "drawable://" + R.drawable.img

• Performance Tips:

  • Use drawable:// only when necessary; prefer ImageView.setImageResource() for local drawables
  • Configure appropriate cache sizes based on your app's needs
  • Use ImageSize parameter for target dimensions to reduce memory usage

• Debugging:

  • Enable debug logs during development:

.writeDebugLogs()

• Monitor cache usage and hit rates
• Use Android Studio's profiler to track memory usage

For more detailed information, refer to the official documentation.