com.xtremelabs.imageutils
Class AbstractImageLoader

java.lang.Object
  extended by com.xtremelabs.imageutils.AbstractImageLoader
Direct Known Subclasses:
ImageLoader, ImageLoaderSupport

public abstract class AbstractImageLoader
extends java.lang.Object


Nested Class Summary
static class AbstractImageLoader.Options
          This class provides all the options that can be set when making loadImage calls.
 
Field Summary
static java.lang.String TAG
           
 
Method Summary
 void clearMemCache()
          Forces the memory cache to release all references to bitmaps.
 void destroy()
          When implementing the ImageLoader in an Activity, this method MUST BE CALLED from the Activity's onDestroy method.
static void invalidateFileSystemUri(Context applicationContext, java.lang.String uri)
          This method will remove all information regarding this image from the cache.
 void loadImage(ImageView imageView, java.lang.String uri)
          Loads the image located at the provided URI into the provided ImageView.

If the URI is referring to a location on the web, the image will be cached both on disk and in memory.
 void loadImage(ImageView imageView, java.lang.String uri, AbstractImageLoader.Options options)
          This call is identical to loadImage(ImageView, String), only it allows the developer to provide custom options for the request.
 void loadImage(ImageView imageView, java.lang.String uri, AbstractImageLoader.Options options, ImageLoaderListener listener)
          Loads the image located at the provided URI.
 void loadImageFromResource(ImageView imageView, int resourceId)
          This method will load the selected resource into the ImageView and cancel any previous requests that have been made to the ImageView.
 void precacheImageToDisk(java.lang.String uri)
          Caches the image at the provided URI into the disk cache.
static void precacheImageToDisk(java.lang.String uri, Context applicationContext)
          Caches the image at the provided URI into the disk cache.
 void precacheImageToDiskAndMemory(java.lang.String uri, Context applicationContext, java.lang.Integer width, java.lang.Integer height)
          Deprecated. 
 void precacheImageToDiskAndMemory(java.lang.String uri, Dimensions bounds, AbstractImageLoader.Options options)
          This method must be called from the UI thread.

Caches the image at the provided URL into both the disk cache and into the memory cache.

This method call is useful for pre-caching smaller images.
 void setDefaultOptions(AbstractImageLoader.Options options)
          The ImageLoader will default to the options provided here if no other options are provided.
 void setMaximumDiskCacheSize(long maxSizeInBytes)
          Sets the maximum disk cache size.
 void setMaximumMemCacheSize(long maxSizeInBytes)
          Sets the maximum size of the memory cache in bytes.

WARNING: Setting the memory cache size value too high will result in OutOfMemory exceptions.
static void setNetworkRequestCreator(Context appContext, NetworkRequestCreator networkRequestCreator)
          Allows the usage of custom network libraries.
 boolean stopLoadingImage(ImageView imageView)
          This call prevents any previous loadImage call from loading a Bitmap into the provided ImageView.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

TAG

public static final java.lang.String TAG
See Also:
Constant Field Values
Method Detail

destroy

public void destroy()
When implementing the ImageLoader in an Activity, this method MUST BE CALLED from the Activity's onDestroy method. When implementing the ImageLoader in a Fragment, this method MUST BE CALLED from the Fragment's onDestroyView method.

Throws:
ThreadChecker.CalledFromWrongThreadException - This is thrown if the method is called from off the UI thread.

setDefaultOptions

public void setDefaultOptions(AbstractImageLoader.Options options)
The ImageLoader will default to the options provided here if no other options are provided.

Parameters:
options - If set to null, the ImageLoader will automatically select the system's default options set.

setNetworkRequestCreator

public static void setNetworkRequestCreator(Context appContext,
                                            NetworkRequestCreator networkRequestCreator)
Allows the usage of custom network libraries. If a NetworkRequestCreator is provided to the image system, all network calls will go through that interface.

Parameters:
appContext -
networkRequestCreator -

loadImage

public void loadImage(ImageView imageView,
                      java.lang.String uri)
Loads the image located at the provided URI into the provided ImageView.

If the URI is referring to a location on the web, the image will be cached both on disk and in memory. If the URI is a local file system URI, the image will be cached in memory.

If loadImage is called for an ImageView multiple times, only the most recently requested image will be loaded into the view.

This method uses the ImageLoader's default options. The default options can be changed using the "setDefaultOptions" method.

Parameters:
imageView - The bitmap will automatically be loaded to this view.
uri - Location of the image. The URI can refer to an image located either on the local file system or on the web (URL).

The URI scheme for local file system requests is "file".
File system URI example: "file:///this/is/the/image/path/image.jpg".
If using a file system URI, the image will be cached in the memory cache.

loadImage

public void loadImage(ImageView imageView,
                      java.lang.String uri,
                      AbstractImageLoader.Options options)
This call is identical to loadImage(ImageView, String), only it allows the developer to provide custom options for the request. See AbstractImageLoader.Options.

Parameters:
imageView - The bitmap will automatically be loaded to this view.

uri - Location of the image. The URI can refer to an image located either on the local file system or on the web (URL).

The URI scheme for local file system requests is "file".
File system URI example: "file:///this/is/the/image/path/image.jpg".
If using a file system URI, the image will be cached in the memory cache.

options - If options is set to null, the ImageLoader will use the default options. The default options can be modified by calling setDefaultOptions(Options). See the AbstractImageLoader.Options docs for additional details.

loadImage

public void loadImage(ImageView imageView,
                      java.lang.String uri,
                      AbstractImageLoader.Options options,
                      ImageLoaderListener listener)
Loads the image located at the provided URI. If the image is located on the web, it will be cached on disk and in memory. If the image is located on the file system, it will be cached in memory.

The image WILL NOT BE AUTOMATICALLY LOADED to the ImageView. Instead, the ImageLoaderListener will have its onImageAvailable() method called on the UI thread with a reference to both the ImageView and the bitmap. It is up to the developer to load the bitmap to the view.

This method should be used if the app needs to:
- perform additional logic when the bitmap is returned
- manually handle image failures
- animate the bitmap.

Parameters:
imageView - The view that will be displaying the image. The bitmap will not be loaded directly into this view. Rather, a reference to the bitmap and to the ImageView will be passed back to the ImageLoaderListener.

uri - Location of the image. The URI can refer to an image located either on the local file system or on the web (URL).

The URI scheme for local file system requests is "file".
File system URI example: "file:///this/is/the/image/path/image.jpg".
If using a file system URI, the image will be cached in the memory cache.

options - If options is set to null, the ImageLoader will use the default options. The default options can be modified by calling setDefaultOptions(Options). See the AbstractImageLoader.Options docs for additional details.

listener - This listener will be called once the image request is complete. If the bitmap was retrieved successfully, the ImageLoaderListener#onImageAvailable(ImageView, android.graphics.Bitmap, ImageReturnedFrom) method will be called.

loadImageFromResource

public void loadImageFromResource(ImageView imageView,
                                  int resourceId)
This method will load the selected resource into the ImageView and cancel any previous requests that have been made to the ImageView.

Parameters:
imageView -
resourceId -

stopLoadingImage

public boolean stopLoadingImage(ImageView imageView)
This call prevents any previous loadImage call from loading a Bitmap into the provided ImageView. Please note it will not prevent any future loadImage calls from loading an image into that view. This is useful if you have a ListView that occasionally needs images from the ImageLoader, and other times from a resources file. Before loading the resource file's image, you would call this method.

Parameters:
imageView -

invalidateFileSystemUri

public static void invalidateFileSystemUri(Context applicationContext,
                                           java.lang.String uri)
This method will remove all information regarding this image from the cache. This includes any bitmaps currently saved in the memory cache.

Parameters:
uri - The file system URI to remove.

clearMemCache

public void clearMemCache()
Forces the memory cache to release all references to bitmaps. NOTE: The images in the memcache will not be garbage collected if the app still has references to the bitmaps. For example, if the bitmap is loaded to an ImageView and the ImageView is still being referenced.


setMaximumMemCacheSize

public void setMaximumMemCacheSize(long maxSizeInBytes)
Sets the maximum size of the memory cache in bytes.

WARNING: Setting the memory cache size value too high will result in OutOfMemory exceptions. Developers should test their apps thoroughly and modify the value set using this method based on memory consumption and app performance. A larger cache size means better performance but worse memory usage. A smaller cache size means worse performance but better memory usage.

The image system will only violate the maximum size specified if a single image is loaded that is larger than the specified maximum size.

Parameters:
maxSizeInBytes -

setMaximumDiskCacheSize

public void setMaximumDiskCacheSize(long maxSizeInBytes)
Sets the maximum disk cache size. This value defaults to 50MB. Most applications will probably need much less space.

Parameters:
maxSizeInBytes -

precacheImageToDisk

public void precacheImageToDisk(java.lang.String uri)
Caches the image at the provided URI into the disk cache. This call is asynchronous and cannot be cancelled once called.

Ideal use cases for this method:
- Pre-cache large images when the user is likely to display them shortly. This will not increase memory usage, but will drastically speed up image load times.
- Pre-cache ListView images.

File system URIs will be ignored by the caching system, as these images are already on disk.

Parameters:
uri -
applicationContext -

precacheImageToDisk

public static void precacheImageToDisk(java.lang.String uri,
                                       Context applicationContext)
Caches the image at the provided URI into the disk cache. This call is asynchronous and cannot be cancelled once called.

Ideal use cases for this method:
- Pre-cache large images when the user is likely to display them shortly. This will not increase memory usage, but will drastically speed up image load times.
- Pre-cache ListView images.

File system URIs will be ignored by the caching system, as these images are already on disk.

Parameters:
uri -
applicationContext -

precacheImageToDiskAndMemory

public void precacheImageToDiskAndMemory(java.lang.String uri,
                                         Dimensions bounds,
                                         AbstractImageLoader.Options options)
This method must be called from the UI thread.

Caches the image at the provided URL into both the disk cache and into the memory cache.

This method call is useful for pre-caching smaller images. If used for a ListView that has many small images, the quality of scrolling will be vastly improved.

The Width and Height allow you to specify the size of the view that the image will be loaded to. If the image is significantly larger than the provided width and/or height, the image will be scaled down in memory, allowing for significant improvements to memory usage and performance, at no cost to image detail.

Parameters:
uri -
bounds - The expected dimensions of the view in pixels. The width and/or height can be set to null.
options - The options used to customize how the view gets precached. Please note that all options relating the image bounds are ignored during this precaching call. The "bounds" object is used instead. Otherwise, the options should be identical to the image request that will be performed by the app.
Throws:
ThreadChecker.CalledFromWrongThreadException - This is thrown if the method is called from off the UI thread.

precacheImageToDiskAndMemory

@Deprecated
public void precacheImageToDiskAndMemory(java.lang.String uri,
                                                    Context applicationContext,
                                                    java.lang.Integer width,
                                                    java.lang.Integer height)
Deprecated. 

Please use #precacheImageToDiskAndMemory(String, Integer, Integer).