Subversion Repositories SmartDukaan

/**

 * Copyright (C) 2013 The Android Open Source Project

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.

 * You may obtain a copy of the License at

 *

 *      http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

package com.android.volley.toolbox;

import android.graphics.Bitmap;

import android.graphics.Bitmap.Config;

import android.os.Handler;

import android.os.Looper;

import android.widget.ImageView;

import android.widget.ImageView.ScaleType;

import com.android.volley.Request;

import com.android.volley.RequestQueue;

import com.android.volley.Response.ErrorListener;

import com.android.volley.Response.Listener;

import com.android.volley.VolleyError;

import java.util.HashMap;

import java.util.LinkedList;

/**

 * Helper that handles loading and caching images from remote URLs.

 *

 * The simple way to use this class is to call {@link ImageLoader#get(String, ImageListener)}

 * and to pass in the default image listener provided by

 * {@link ImageLoader#getImageListener(ImageView, int, int)}. Note that all function calls to

 * this class must be made from the main thead, and all responses will be delivered to the main

 * thread as well.

 */

public class ImageLoader {

    /** RequestQueue for dispatching ImageRequests onto. */

    private final RequestQueue mRequestQueue;

    /** Amount of time to wait after first response arrives before delivering all responses. */

    private int mBatchResponseDelayMs = 100;

    /** The cache implementation to be used as an L1 cache before calling into volley. */

    private final ImageCache mCache;

    /**

     * HashMap of Cache keys -> BatchedImageRequest used to track in-flight requests so

     * that we can coalesce multiple requests to the same URL into a single network request.

     */

    private final HashMap<String, BatchedImageRequest> mInFlightRequests =

            new HashMap<String, BatchedImageRequest>();

    /** HashMap of the currently pending responses (waiting to be delivered). */

    private final HashMap<String, BatchedImageRequest> mBatchedResponses =

            new HashMap<String, BatchedImageRequest>();

    /** Handler to the main thread. */

    private final Handler mHandler = new Handler(Looper.getMainLooper());

    /** Runnable for in-flight response delivery. */

    private Runnable mRunnable;

    /**

     * Simple cache adapter interface. If provided to the ImageLoader, it

     * will be used as an L1 cache before dispatch to Volley. Implementations

     * must not block. Implementation with an LruCache is recommended.

     */

    public interface ImageCache {

        public Bitmap getBitmap(String url);

        public void putBitmap(String url, Bitmap bitmap);

    }

    /**

     * Constructs a new ImageLoader.

     * @param queue The RequestQueue to use for making image requests.

     * @param imageCache The cache to use as an L1 cache.

     */

    public ImageLoader(RequestQueue queue, ImageCache imageCache) {

        mRequestQueue = queue;

        mCache = imageCache;

    }

    /**

     * The default implementation of ImageListener which handles basic functionality

     * of showing a default image until the network response is received, at which point

     * it will switch to either the actual image or the error image.

     * @param view The imageView that the listener is associated with.

     * @param defaultImageResId Default image resource ID to use, or 0 if it doesn't exist.

     * @param errorImageResId Error image resource ID to use, or 0 if it doesn't exist.

     */

    public static ImageListener getImageListener(final ImageView view,

            final int defaultImageResId, final int errorImageResId) {

        return new ImageListener() {

            @Override

            public void onErrorResponse(VolleyError error) {

                if (errorImageResId != 0) {

                    view.setImageResource(errorImageResId);

                }

            }

            @Override

            public void onResponse(ImageContainer response, boolean isImmediate) {

                if (response.getBitmap() != null) {

                    view.setImageBitmap(response.getBitmap());

                } else if (defaultImageResId != 0) {

                    view.setImageResource(defaultImageResId);

                }

            }

        };

    }

    /**

     * Interface for the response handlers on image requests.

     *

     * The call flow is this:

     * 1. Upon being  attached to a request, onResponse(response, true) will

     * be invoked to reflect any cached data that was already available. If the

     * data was available, response.getBitmap() will be non-null.

     *

     * 2. After a network response returns, only one of the following cases will happen:

     *   - onResponse(response, false) will be called if the image was loaded.

     *   or

     *   - onErrorResponse will be called if there was an error loading the image.

     */

    public interface ImageListener extends ErrorListener {

        /**

         * Listens for non-error changes to the loading of the image request.

         *

         * @param response Holds all information pertaining to the request, as well

         * as the bitmap (if it is loaded).

         * @param isImmediate True if this was called during ImageLoader.get() variants.

         * This can be used to differentiate between a cached image loading and a network

         * image loading in order to, for example, run an animation to fade in network loaded

         * images.

         */

        public void onResponse(ImageContainer response, boolean isImmediate);

    }

    /**

     * Checks if the item is available in the cache.

     * @param requestUrl The url of the remote image

     * @param maxWidth The maximum width of the returned image.

     * @param maxHeight The maximum height of the returned image.

     * @return True if the item exists in cache, false otherwise.

     */

    public boolean isCached(String requestUrl, int maxWidth, int maxHeight) {

        return isCached(requestUrl, maxWidth, maxHeight, ScaleType.CENTER_INSIDE);

    }

    /**

     * Checks if the item is available in the cache.

     *

     * @param requestUrl The url of the remote image

     * @param maxWidth   The maximum width of the returned image.

     * @param maxHeight  The maximum height of the returned image.

     * @param scaleType  The scaleType of the imageView.

     * @return True if the item exists in cache, false otherwise.

     */

    public boolean isCached(String requestUrl, int maxWidth, int maxHeight, ScaleType scaleType) {

        throwIfNotOnMainThread();

        String cacheKey = getCacheKey(requestUrl, maxWidth, maxHeight, scaleType);

        return mCache.getBitmap(cacheKey) != null;

    }

    /**

     * Returns an ImageContainer for the requested URL.

     *

     * The ImageContainer will contain either the specified default bitmap or the loaded bitmap.

     * If the default was returned, the {@link ImageLoader} will be invoked when the

     * request is fulfilled.

     *

     * @param requestUrl The URL of the image to be loaded.

     */

    public ImageContainer get(String requestUrl, final ImageListener listener) {

        return get(requestUrl, listener, 0, 0);

    }

    /**

     * Equivalent to calling {@link #get(String, ImageListener, int, int, ScaleType)} with

     * {@code Scaletype == ScaleType.CENTER_INSIDE}.

     */

    public ImageContainer get(String requestUrl, ImageListener imageListener,

            int maxWidth, int maxHeight) {

        return get(requestUrl, imageListener, maxWidth, maxHeight, ScaleType.CENTER_INSIDE);

    }

    /**

     * Issues a bitmap request with the given URL if that image is not available

     * in the cache, and returns a bitmap container that contains all of the data

     * relating to the request (as well as the default image if the requested

     * image is not available).

     * @param requestUrl The url of the remote image

     * @param imageListener The listener to call when the remote image is loaded

     * @param maxWidth The maximum width of the returned image.

     * @param maxHeight The maximum height of the returned image.

     * @param scaleType The ImageViews ScaleType used to calculate the needed image size.

     * @return A container object that contains all of the properties of the request, as well as

     *     the currently available image (default if remote is not loaded).

     */

    public ImageContainer get(String requestUrl, ImageListener imageListener,

            int maxWidth, int maxHeight, ScaleType scaleType) {

        // only fulfill requests that were initiated from the main thread.

        throwIfNotOnMainThread();

        final String cacheKey = getCacheKey(requestUrl, maxWidth, maxHeight, scaleType);

        // Try to look up the request in the cache of remote images.

        Bitmap cachedBitmap = mCache.getBitmap(cacheKey);

        if (cachedBitmap != null) {

            // Return the cached bitmap.

            ImageContainer container = new ImageContainer(cachedBitmap, requestUrl, null, null);

            imageListener.onResponse(container, true);

            return container;

        }

        // The bitmap did not exist in the cache, fetch it!

        ImageContainer imageContainer =

                new ImageContainer(null, requestUrl, cacheKey, imageListener);

        // Update the caller to let them know that they should use the default bitmap.

        imageListener.onResponse(imageContainer, true);

        // Check to see if a request is already in-flight.

        BatchedImageRequest request = mInFlightRequests.get(cacheKey);

        if (request != null) {

            // If it is, add this request to the list of listeners.

            request.addContainer(imageContainer);

            return imageContainer;

        }

        // The request is not already in flight. Send the new request to the network and

        // track it.

        Request<Bitmap> newRequest = makeImageRequest(requestUrl, maxWidth, maxHeight, scaleType,

                cacheKey);

        mRequestQueue.add(newRequest);

        mInFlightRequests.put(cacheKey,

                new BatchedImageRequest(newRequest, imageContainer));

        return imageContainer;

    }

    protected Request<Bitmap> makeImageRequest(String requestUrl, int maxWidth, int maxHeight,

            ScaleType scaleType, final String cacheKey) {

        return new ImageRequest(requestUrl, new Listener<Bitmap>() {

            @Override

            public void onResponse(Bitmap response) {

                onGetImageSuccess(cacheKey, response);

            }

        }, maxWidth, maxHeight, scaleType, Config.RGB_565, new ErrorListener() {

            @Override

            public void onErrorResponse(VolleyError error) {

                onGetImageError(cacheKey, error);

            }

        });

    }

    /**

     * Sets the amount of time to wait after the first response arrives before delivering all

     * responses. Batching can be disabled entirely by passing in 0.

     * @param newBatchedResponseDelayMs The time in milliseconds to wait.

     */

    public void setBatchedResponseDelay(int newBatchedResponseDelayMs) {

        mBatchResponseDelayMs = newBatchedResponseDelayMs;

    }

    /**

     * Handler for when an image was successfully loaded.

     * @param cacheKey The cache key that is associated with the image request.

     * @param response The bitmap that was returned from the network.

     */

    protected void onGetImageSuccess(String cacheKey, Bitmap response) {

        // cache the image that was fetched.

        mCache.putBitmap(cacheKey, response);

        // remove the request from the list of in-flight requests.

        BatchedImageRequest request = mInFlightRequests.remove(cacheKey);

        if (request != null) {

            // Update the response bitmap.

            request.mResponseBitmap = response;

            // Send the batched response

            batchResponse(cacheKey, request);

        }

    }

    /**

     * Handler for when an image failed to load.

     * @param cacheKey The cache key that is associated with the image request.

     */

    protected void onGetImageError(String cacheKey, VolleyError error) {

        // Notify the requesters that something failed via a null result.

        // Remove this request from the list of in-flight requests.

        BatchedImageRequest request = mInFlightRequests.remove(cacheKey);

        if (request != null) {

            // Set the error for this request

            request.setError(error);

            // Send the batched response

            batchResponse(cacheKey, request);

        }

    }

    /**

     * Container object for all of the data surrounding an image request.

     */

    public class ImageContainer {

        /**

         * The most relevant bitmap for the container. If the image was in cache, the

         * Holder to use for the final bitmap (the one that pairs to the requested URL).

         */

        private Bitmap mBitmap;

        private final ImageListener mListener;

        /** The cache key that was associated with the request */

        private final String mCacheKey;

        /** The request URL that was specified */

        private final String mRequestUrl;

        /**

         * Constructs a BitmapContainer object.

         * @param bitmap The final bitmap (if it exists).

         * @param requestUrl The requested URL for this container.

         * @param cacheKey The cache key that identifies the requested URL for this container.

         */

        public ImageContainer(Bitmap bitmap, String requestUrl,

                String cacheKey, ImageListener listener) {

            mBitmap = bitmap;

            mRequestUrl = requestUrl;

            mCacheKey = cacheKey;

            mListener = listener;

        }

        /**

         * Releases interest in the in-flight request (and cancels it if no one else is listening).

         */

        public void cancelRequest() {

            if (mListener == null) {

                return;

            }

            BatchedImageRequest request = mInFlightRequests.get(mCacheKey);

            if (request != null) {

                boolean canceled = request.removeContainerAndCancelIfNecessary(this);

                if (canceled) {

                    mInFlightRequests.remove(mCacheKey);

                }

            } else {

                // check to see if it is already batched for delivery.

                request = mBatchedResponses.get(mCacheKey);

                if (request != null) {

                    request.removeContainerAndCancelIfNecessary(this);

                    if (request.mContainers.size() == 0) {

                        mBatchedResponses.remove(mCacheKey);

                    }

                }

            }

        }

        /**

         * Returns the bitmap associated with the request URL if it has been loaded, null otherwise.

         */

        public Bitmap getBitmap() {

            return mBitmap;

        }

        /**

         * Returns the requested URL for this container.

         */

        public String getRequestUrl() {

            return mRequestUrl;

        }

    }

    /**

     * Wrapper class used to map a Request to the set of active ImageContainer objects that are

     * interested in its results.

     */

    private class BatchedImageRequest {

        /** The request being tracked */

        private final Request<?> mRequest;

        /** The result of the request being tracked by this item */

        private Bitmap mResponseBitmap;

        /** Error if one occurred for this response */

        private VolleyError mError;

        /** List of all of the active ImageContainers that are interested in the request */

        private final LinkedList<ImageContainer> mContainers = new LinkedList<ImageContainer>();

        /**

         * Constructs a new BatchedImageRequest object

         * @param request The request being tracked

         * @param container The ImageContainer of the person who initiated the request.

         */

        public BatchedImageRequest(Request<?> request, ImageContainer container) {

            mRequest = request;

            mContainers.add(container);

        }

        /**

         * Set the error for this response

         */

        public void setError(VolleyError error) {

            mError = error;

        }

        /**

         * Get the error for this response

         */

        public VolleyError getError() {

            return mError;

        }

        /**

         * Adds another ImageContainer to the list of those interested in the results of

         * the request.

         */

        public void addContainer(ImageContainer container) {

            mContainers.add(container);

        }

        /**

         * Detatches the bitmap container from the request and cancels the request if no one is

         * left listening.

         * @param container The container to remove from the list

         * @return True if the request was canceled, false otherwise.

         */

        public boolean removeContainerAndCancelIfNecessary(ImageContainer container) {

            mContainers.remove(container);

            if (mContainers.size() == 0) {

                mRequest.cancel();

                return true;

            }

            return false;

        }

    }

    /**

     * Starts the runnable for batched delivery of responses if it is not already started.

     * @param cacheKey The cacheKey of the response being delivered.

     * @param request The BatchedImageRequest to be delivered.

     */

    private void batchResponse(String cacheKey, BatchedImageRequest request) {

        mBatchedResponses.put(cacheKey, request);

        // If we don't already have a batch delivery runnable in flight, make a new one.

        // Note that this will be used to deliver responses to all callers in mBatchedResponses.

        if (mRunnable == null) {

            mRunnable = new Runnable() {

                @Override

                public void run() {

                    for (BatchedImageRequest bir : mBatchedResponses.values()) {

                        for (ImageContainer container : bir.mContainers) {

                            // If one of the callers in the batched request canceled the request

                            // after the response was received but before it was delivered,

                            // skip them.

                            if (container.mListener == null) {

                                continue;

                            }

                            if (bir.getError() == null) {

                                container.mBitmap = bir.mResponseBitmap;

                                container.mListener.onResponse(container, false);

                            } else {

                                container.mListener.onErrorResponse(bir.getError());

                            }

                        }

                    }

                    mBatchedResponses.clear();

                    mRunnable = null;

                }

            };

            // Post the runnable.

            mHandler.postDelayed(mRunnable, mBatchResponseDelayMs);

        }

    }

    private void throwIfNotOnMainThread() {

        if (Looper.myLooper() != Looper.getMainLooper()) {

            throw new IllegalStateException("ImageLoader must be invoked from the main thread.");

        }

    }

    /**

     * Creates a cache key for use with the L1 cache.

     * @param url The URL of the request.

     * @param maxWidth The max-width of the output.

     * @param maxHeight The max-height of the output.

     * @param scaleType The scaleType of the imageView.

     */

    private static String getCacheKey(String url, int maxWidth, int maxHeight, ScaleType scaleType) {

        return new StringBuilder(url.length() + 12).append("#W").append(maxWidth)

                .append("#H").append(maxHeight).append("#S").append(scaleType.ordinal()).append(url)

                .toString();

    }

}