am ddf2040c: am 985f6801: am 5f51b7fb: Bitmapfun Sample: Add some docs and clean up some method naming.

* commit 'ddf2040c2d12d5c1984363aff8ad24744f82b6e7':
  Bitmapfun Sample: Add some docs and clean up some method naming.

samples/training/bitmapfun/src/com/example/android/bitmapfun/util/ImageCache.java

@@ -16,6 +16,8 @@
 
 package com.example.android.bitmapfun.util;
 
+import com.example.android.bitmapfun.BuildConfig;
+
 import android.annotation.TargetApi;
 import android.content.Context;
 import android.graphics.Bitmap;
@@ -30,8 +32,6 @@ import android.support.v4.app.FragmentManager;
 import android.support.v4.util.LruCache;
 import android.util.Log;
 
-import com.example.android.bitmapfun.BuildConfig;
-
 import java.io.File;
 import java.io.FileDescriptor;
 import java.io.FileInputStream;
@@ -45,7 +45,11 @@ import java.util.HashSet;
 import java.util.Iterator;
 
 /**
- * This class holds our bitmap caches (memory and disk).
+ * This class handles disk and memory caching of bitmaps in conjunction with the
+ * {@link ImageWorker} class and its subclasses. Use
+ * {@link ImageCache#getInstance(FragmentManager, ImageCacheParams)} to get an instance of this
+ * class, although usually a cache should be added directly to an {@link ImageWorker} by calling
+ * {@link ImageWorker#addImageCache(FragmentManager, ImageCacheParams)}.
  */
 public class ImageCache {
     private static final String TAG = "ImageCache";
@@ -64,7 +68,6 @@ public class ImageCache {
     // Constants to easily toggle various caches
     private static final boolean DEFAULT_MEM_CACHE_ENABLED = true;
     private static final boolean DEFAULT_DISK_CACHE_ENABLED = true;
-    private static final boolean DEFAULT_CLEAR_DISK_CACHE_ON_START = false;
     private static final boolean DEFAULT_INIT_DISK_CACHE_ON_CREATE = false;
 
     private DiskLruCache mDiskLruCache;
@@ -76,33 +79,26 @@ public class ImageCache {
     private HashSet<SoftReference<Bitmap>> mReusableBitmaps;
 
     /**
-     * Creating a new ImageCache object using the specified parameters.
+     * Create a new ImageCache object using the specified parameters. This should not be
+     * called directly by other classes, instead use
+     * {@link ImageCache#getInstance(FragmentManager, ImageCacheParams)} to fetch an ImageCache
+     * instance.
      *
      * @param cacheParams The cache parameters to use to initialize the cache
      */
-    public ImageCache(ImageCacheParams cacheParams) {
+    private ImageCache(ImageCacheParams cacheParams) {
         init(cacheParams);
     }
 
     /**
-     * Creating a new ImageCache object using the default parameters.
+     * Return an {@link ImageCache} instance. A {@link RetainFragment} is used to retain the
-     *
+     * ImageCache object across configuration changes such as a change in device orientation.
-     * @param context The context to use
-     * @param uniqueName A unique name that will be appended to the cache directory
-     */
-    public ImageCache(Context context, String uniqueName) {
-        init(new ImageCacheParams(context, uniqueName));
-    }
-
-    /**
-     * Find and return an existing ImageCache stored in a {@link RetainFragment}, if not found a new
-     * one is created using the supplied params and saved to a {@link RetainFragment}.
      *
      * @param fragmentManager The fragment manager to use when dealing with the retained fragment.
-     * @param cacheParams The cache parameters to use if creating the ImageCache
+     * @param cacheParams The cache parameters to use if the ImageCache needs instantiation.
      * @return An existing retained ImageCache object or a new one if one did not exist
      */
-    public static ImageCache findOrCreateCache(
+    public static ImageCache getInstance(
             FragmentManager fragmentManager, ImageCacheParams cacheParams) {
 
         // Search for, or create an instance of the non-UI RetainFragment
@@ -452,15 +448,19 @@ public class ImageCache {
         public int compressQuality = DEFAULT_COMPRESS_QUALITY;
         public boolean memoryCacheEnabled = DEFAULT_MEM_CACHE_ENABLED;
         public boolean diskCacheEnabled = DEFAULT_DISK_CACHE_ENABLED;
-        public boolean clearDiskCacheOnStart = DEFAULT_CLEAR_DISK_CACHE_ON_START;
         public boolean initDiskCacheOnCreate = DEFAULT_INIT_DISK_CACHE_ON_CREATE;
 
-        public ImageCacheParams(Context context, String uniqueName) {
+        /**
-            diskCacheDir = getDiskCacheDir(context, uniqueName);
+         * Create a set of image cache parameters that can be provided to
-        }
+         * {@link ImageCache#getInstance(FragmentManager, ImageCacheParams)} or
-
+         * {@link ImageWorker#addImageCache(FragmentManager, ImageCacheParams)}.
-        public ImageCacheParams(File diskCacheDir) {
+         * @param context A context to use.
-            this.diskCacheDir = diskCacheDir;
+         * @param diskCacheDirectoryName A unique subdirectory name that will be appended to the
+         *                               application cache directory. Usually "cache" or "images"
+         *                               is sufficient.
+         */
+        public ImageCacheParams(Context context, String diskCacheDirectoryName) {
+            diskCacheDir = getDiskCacheDir(context, diskCacheDirectoryName);
         }
 
         /**
@@ -616,7 +616,7 @@ public class ImageCache {
      * @return The existing instance of the Fragment or the new instance if just
      *         created.
      */
-    public static RetainFragment findOrCreateRetainFragment(FragmentManager fm) {
+    private static RetainFragment findOrCreateRetainFragment(FragmentManager fm) {
         // Check to see if we have retained the worker fragment.
         RetainFragment mRetainFragment = (RetainFragment) fm.findFragmentByTag(TAG);
 

samples/training/bitmapfun/src/com/example/android/bitmapfun/util/ImageWorker.java

@@ -16,6 +16,8 @@
 
 package com.example.android.bitmapfun.util;
 
+import com.example.android.bitmapfun.BuildConfig;
+
 import android.content.Context;
 import android.content.res.Resources;
 import android.graphics.Bitmap;
@@ -24,12 +26,11 @@ import android.graphics.drawable.BitmapDrawable;
 import android.graphics.drawable.ColorDrawable;
 import android.graphics.drawable.Drawable;
 import android.graphics.drawable.TransitionDrawable;
+import android.support.v4.app.FragmentActivity;
 import android.support.v4.app.FragmentManager;
 import android.util.Log;
 import android.widget.ImageView;
 
-import com.example.android.bitmapfun.BuildConfig;
-
 import java.lang.ref.WeakReference;
 
 /**
@@ -62,11 +63,11 @@ public abstract class ImageWorker {
 
     /**
      * Load an image specified by the data parameter into an ImageView (override
-     * {@link ImageWorker#processBitmap(Object)} to define the processing logic). A memory and disk
+     * {@link ImageWorker#processBitmap(Object)} to define the processing logic). A memory and
-     * cache will be used if an {@link ImageCache} has been set using
+     * disk cache will be used if an {@link ImageCache} has been added using
-     * {@link ImageWorker#setImageCache(ImageCache)}. If the image is found in the memory cache, it
+     * {@link ImageWorker#addImageCache(FragmentManager, ImageCache.ImageCacheParams)}. If the
-     * is set immediately, otherwise an {@link AsyncTask} will be created to asynchronously load the
+     * image is found in the memory cache, it is set immediately, otherwise an {@link AsyncTask}
-     * bitmap.
+     * will be created to asynchronously load the bitmap.
      *
      * @param data The URL of the image to download.
      * @param imageView The ImageView to bind the downloaded image to.
@@ -117,28 +118,29 @@ public abstract class ImageWorker {
     }
 
     /**
-     * Adds an {@link ImageCache} to this worker in the background (to prevent disk access on UI
+     * Adds an {@link ImageCache} to this {@link ImageWorker} to handle disk and memory bitmap
-     * thread).
+     * caching.
      * @param fragmentManager
-     * @param cacheParams
+     * @param cacheParams The cache parameters to use for the image cache.
      */
     public void addImageCache(FragmentManager fragmentManager,
             ImageCache.ImageCacheParams cacheParams) {
         mImageCacheParams = cacheParams;
-        setImageCache(ImageCache.findOrCreateCache(fragmentManager, mImageCacheParams));
+        mImageCache = ImageCache.getInstance(fragmentManager, mImageCacheParams);
         new CacheAsyncTask().execute(MESSAGE_INIT_DISK_CACHE);
     }
 
     /**
-     * Sets the {@link ImageCache} object to use with this ImageWorker. Usually you will not need
+     * Adds an {@link ImageCache} to this {@link ImageWorker} to handle disk and memory bitmap
-     * to call this directly, instead use {@link ImageWorker#addImageCache} which will create and
+     * caching.
-     * add the {@link ImageCache} object in a background thread (to ensure no disk access on the
+     * @param activity
-     * main/UI thread).
+     * @param diskCacheDirectoryName See
-     *
+     * {@link ImageCache.ImageCacheParams#ImageCacheParams(Context, String)}.
-     * @param imageCache
      */
-    public void setImageCache(ImageCache imageCache) {
+    public void addImageCache(FragmentActivity activity, String diskCacheDirectoryName) {
-        mImageCache = imageCache;
+        mImageCacheParams = new ImageCache.ImageCacheParams(activity, diskCacheDirectoryName);
+        mImageCache = ImageCache.getInstance(activity.getSupportFragmentManager(), mImageCacheParams);
+        new CacheAsyncTask().execute(MESSAGE_INIT_DISK_CACHE);
     }
 
     /**