xUtils 中的BitmapUtils 全面註釋

/**  * 加載圖片工具類  * @author afu  *  */ public class BitmapUtils implements TaskHandler {     /**      * 判斷任務是否暫停      */     private boolean pauseTask = false;     /**      * 是否取消全部任務      */     private boolean cancelAllTask = false;     private final Object pauseTaskLock = new Object();     /**      * Android上下文      */     private Context context;     private BitmapGlobalConfig globalConfig;     private BitmapDisplayConfig defaultDisplayConfig;     /////////////////////////////////////////////// create ///////////////////////////////////////////////////     /**      *      * @param context 上下文      */     public BitmapUtils(Context context) {         this(context, null);     }     /**      *      * @param context 上下文      * @param diskCachePath 磁盤高速緩存路徑      */     public BitmapUtils(Context context, String diskCachePath) {         if (context == null) {             throw new IllegalArgumentException("context may not be null");         }         this.context = context.getApplicationContext();         globalConfig = BitmapGlobalConfig.getInstance(this.context, diskCachePath);         defaultDisplayConfig = new BitmapDisplayConfig();     }     /**      *      * @param context 上下文      * @param diskCachePath 磁盤高速緩存路徑      * @param memoryCacheSize 內存緩存空間大小      */     public BitmapUtils(Context context, String diskCachePath, int memoryCacheSize) {         this(context, diskCachePath);         globalConfig.setMemoryCacheSize(memoryCacheSize);     }     /**      *      * @param context 上下文      * @param diskCachePath 磁盤高速緩存路徑      * @param memoryCacheSize 內存緩存空間大小      * @param diskCacheSize 磁盤高速緩存空間大小      */     public BitmapUtils(Context context, String diskCachePath, int memoryCacheSize, int diskCacheSize) {         this(context, diskCachePath);         globalConfig.setMemoryCacheSize(memoryCacheSize);         globalConfig.setDiskCacheSize(diskCacheSize);     }     /**      *      * @param context 上下文      * @param diskCachePath 磁盤高速緩存路徑      * @param memoryCachePercent 內存緩存百分比      */     public BitmapUtils(Context context, String diskCachePath, float memoryCachePercent) {         this(context, diskCachePath);         globalConfig.setMemCacheSizePercent(memoryCachePercent);     }     /**      *      * @param context 上下文      * @param diskCachePath  磁盤高速緩存路徑      * @param memoryCachePercent 內存緩存百分比      * @param diskCacheSize 磁盤緩存空間大小      */     public BitmapUtils(Context context, String diskCachePath, float memoryCachePercent, int diskCacheSize) {         this(context, diskCachePath);         globalConfig.setMemCacheSizePercent(memoryCachePercent);         globalConfig.setDiskCacheSize(diskCacheSize);     }     //////////////////////////////////////// config  配置////////////////////////////////////////////////////////////////////     /**      * 配置默認加載drawable類型資源圖片      * @param drawable      * @return      */     public BitmapUtils configDefaultLoadingImage(Drawable drawable) {         defaultDisplayConfig.setLoadingDrawable(drawable);         return this;     }     /**      * 配置默認加載資源id類型資源圖片      * @param resId      * @return      */     public BitmapUtils configDefaultLoadingImage(int resId) {         defaultDisplayConfig.setLoadingDrawable(context.getResources().getDrawable(resId));         return this;     }     /**      * 配置默認加載圖片      * @param bitmap bitmap類中的資源圖片      * @return      */     public BitmapUtils configDefaultLoadingImage(Bitmap bitmap) {         defaultDisplayConfig.setLoadingDrawable(new BitmapDrawable(context.getResources(), bitmap));         return this;     }     /**      * 設置默認加載失敗的圖片      * @param drawable drawable類型的資源圖片      * @return      */     public BitmapUtils configDefaultLoadFailedImage(Drawable drawable) {         defaultDisplayConfig.setLoadFailedDrawable(drawable);         return this;     }     /**      * 配置默認加載失敗圖片，加載id類型資源圖片      * @param resId      * @return      */     public BitmapUtils configDefaultLoadFailedImage(int resId) {         defaultDisplayConfig.setLoadFailedDrawable(context.getResources().getDrawable(resId));         return this;     }     /**      * 配置默認加載失敗圖片，加載Bitmap類型資源圖片      * @param bitmap      * @return      */     public BitmapUtils configDefaultLoadFailedImage(Bitmap bitmap) {         defaultDisplayConfig.setLoadFailedDrawable(new BitmapDrawable(context.getResources(), bitmap));         return this;     }     /**      * 配置默認圖片最大寬和高      * @param maxWidth 最大寬      * @param maxHeight 最大高      * @return      */     public BitmapUtils configDefaultBitmapMaxSize(int maxWidth, int maxHeight) {         defaultDisplayConfig.setBitmapMaxSize(new BitmapSize(maxWidth, maxHeight));         return this;     }     /**      * 配置默認位圖最大圖片參數      * @param maxSize 最大圖片參數類      * @return      */     public BitmapUtils configDefaultBitmapMaxSize(BitmapSize maxSize) {         defaultDisplayConfig.setBitmapMaxSize(maxSize);         return this;     }     /**      * 配置默認圖片加載動畫      * @param animation 動畫      * @return      */     public BitmapUtils configDefaultImageLoadAnimation(Animation animation) {         defaultDisplayConfig.setAnimation(animation);         return this;     }     /**      * 配置默認自動旋轉動畫      * @param autoRotation      * @return      */     public BitmapUtils configDefaultAutoRotation(boolean autoRotation) {         defaultDisplayConfig.setAutoRotation(autoRotation);         return this;     }     /**      * 配置默認是否顯示原始圖片      * @param showOriginal true:顯示原始圖片，false：將會對圖片壓縮處理      * @return      */     public BitmapUtils configDefaultShowOriginal(boolean showOriginal) {         defaultDisplayConfig.setShowOriginal(showOriginal);         return this;     }     /**      * 配置默認圖片配置，傳入Bitmap.Config類型      * @param config      * @return      */     public BitmapUtils configDefaultBitmapConfig(Bitmap.Config config) {         defaultDisplayConfig.setBitmapConfig(config);         return this;     }     /**      * 配置默認顯示配置      * @param displayConfig      * @return      */     public BitmapUtils configDefaultDisplayConfig(BitmapDisplayConfig displayConfig) {         defaultDisplayConfig = displayConfig;         return this;     }     /**      * 配置下載參數      * @param downloader      * @return      */     public BitmapUtils configDownloader(Downloader downloader) {         globalConfig.setDownloader(downloader);         return this;     }     /**      * 配置默認緩存失效      * @param defaultExpiry      * @return      */     public BitmapUtils configDefaultCacheExpiry(long defaultExpiry) {         globalConfig.setDefaultCacheExpiry(defaultExpiry);         return this;     }     /**      * 配置默認連接時間超時時間      * @param connectTimeout  毫秒單位      * @return      */     public BitmapUtils configDefaultConnectTimeout(int connectTimeout) {         globalConfig.setDefaultConnectTimeout(connectTimeout);         return this;     }     /**      * 配置默認讀取超時時間      * @param readTimeout 毫秒      * @return      */     public BitmapUtils configDefaultReadTimeout(int readTimeout) {         globalConfig.setDefaultReadTimeout(readTimeout);         return this;     }     /**      * 配置線程池多少      * @param threadPoolSize 線程池數      * 此參數沒有設置，默認是設置5個核心線程池      * @return      */     public BitmapUtils configThreadPoolSize(int threadPoolSize) {         globalConfig.setThreadPoolSize(threadPoolSize);         return this;     }     /**      * 配置內存緩存是否啓用，默認是啓用的      * @param enabled      * @return      */     public BitmapUtils configMemoryCacheEnabled(boolean enabled) {         globalConfig.setMemoryCacheEnabled(enabled);         return this;     }     /**      * 配置磁盤緩存功能，默認是啓用的      * @param enabled      * @return      */     public BitmapUtils configDiskCacheEnabled(boolean enabled) {         globalConfig.setDiskCacheEnabled(enabled);         return this;     }     /**      * 配置原始磁盤緩存文件名稱      * @param fileNameGenerator      * @return      */     public BitmapUtils configDiskCacheFileNameGenerator(FileNameGenerator fileNameGenerator) {         globalConfig.setFileNameGenerator(fileNameGenerator);         return this;     }     /**      * 配置位圖緩存監聽      * @param listener      * @return      */     public BitmapUtils configBitmapCacheListener(BitmapCacheListener listener) {         globalConfig.setBitmapCacheListener(listener);         return this;     }     ////////////////////////// display  顯示////////////////////////////////////     /**      * 根據圖片路徑，顯示到具體的View上      * @param container 要把圖片顯示到的View      * @param uri 圖片路徑      */     public <T extends View> void display(T container, String uri) {         display(container, uri, null, null);     }     /**      * 根據圖片路徑，顯示到具體的View上      * @param container 要把圖片顯示到的View      * @param uri 圖片路徑      * @param displayConfig      */     public <T extends View> void display(T container, String uri, BitmapDisplayConfig displayConfig) {         display(container, uri, displayConfig, null);     }     /**      * 根據圖片路徑，顯示到具體的View上      * @param container 要把圖片顯示到的View      * @param uri 圖片路徑      * @param callBack 加載過程回調各類狀態      */     public <T extends View> void display(T container, String uri, BitmapLoadCallBack<T> callBack) {         display(container, uri, null, callBack);     }     /**      * 根據圖片路徑，顯示到具體的View上      * @param container 要把圖片顯示到的View      * @param uri 圖片路徑      * @param displayConfig 位圖顯示配置      * @param callBack      */     public <T extends View> void display(T container, String uri, BitmapDisplayConfig displayConfig, BitmapLoadCallBack<T> callBack) {         if (container == null) {             return;         }         if (callBack == null) {             callBack = new DefaultBitmapLoadCallBack<T>();         }         if (displayConfig == null || displayConfig == defaultDisplayConfig) {             displayConfig = defaultDisplayConfig.cloneNew();         }         // Optimize Max Size         BitmapSize size = displayConfig.getBitmapMaxSize();         displayConfig.setBitmapMaxSize(BitmapCommonUtils.optimizeMaxSizeByView(container, size.getWidth(), size.getHeight()));         container.clearAnimation();         if (TextUtils.isEmpty(uri)) {             callBack.onLoadFailed(container, uri, displayConfig.getLoadFailedDrawable());             return;         }         // start loading         callBack.onPreLoad(container, uri, displayConfig);         // find bitmap from mem cache.         Bitmap bitmap = globalConfig.getBitmapCache().getBitmapFromMemCache(uri, displayConfig);         if (bitmap != null) {             callBack.onLoadStarted(container, uri, displayConfig);             callBack.onLoadCompleted(                     container,                     uri,                     bitmap,                     displayConfig,                     BitmapLoadFrom.MEMORY_CACHE);         } else if (!bitmapLoadTaskExist(container, uri, callBack)) {             final BitmapLoadTask<T> loadTask = new BitmapLoadTask<T>(container, uri, displayConfig, callBack);             // get executor             PriorityExecutor executor = globalConfig.getBitmapLoadExecutor();             File diskCacheFile = this.getBitmapFileFromDiskCache(uri);             boolean diskCacheExist = diskCacheFile != null && diskCacheFile.exists();             if (diskCacheExist && executor.isBusy()) {                 executor = globalConfig.getDiskCacheExecutor();             }             // set loading image             Drawable loadingDrawable = displayConfig.getLoadingDrawable();             callBack.setDrawable(container, new AsyncDrawable<T>(loadingDrawable, loadTask));             loadTask.setPriority(displayConfig.getPriority());             loadTask.executeOnExecutor(executor);         }     }     /////////////////////////////////////////////// cache  緩存相關/////////////////////////////////////////////////////////////////     /**      * 清除內存和磁盤緩存      */     public void clearCache() {         globalConfig.clearCache();     }     /**      * 清除內存緩存      */     public void clearMemoryCache() {         globalConfig.clearMemoryCache();     }     /**      * 清除磁盤緩存      */     public void clearDiskCache() {         globalConfig.clearDiskCache();     }     /**      * 根據uri清除內存緩存和磁盤緩存      * @param uri      */     public void clearCache(String uri) {         globalConfig.clearCache(uri);     }     /**      * 根據uri清除內存緩存      * @param uri      */     public void clearMemoryCache(String uri) {         globalConfig.clearMemoryCache(uri);     }     /**      * 根據uri清除磁盤緩存      * @param uri      */     public void clearDiskCache(String uri) {         globalConfig.clearDiskCache(uri);     }     /**      * 刷新緩存      */     public void flushCache() {         globalConfig.flushCache();     }     /**      * 關閉緩存      */     public void closeCache() {         globalConfig.closeCache();     }     /**      * 根據uri從磁盤緩存獲得位圖文件      * @param uri      * @return      */     public File getBitmapFileFromDiskCache(String uri) {         return globalConfig.getBitmapCache().getBitmapFileFromDiskCache(uri);     }     /**      * 根據uri和位圖顯示配置從磁盤緩存獲得位圖文件      * @param uri      * @param config      * @return      */     public Bitmap getBitmapFromMemCache(String uri, BitmapDisplayConfig config) {         if (config == null) {             config = defaultDisplayConfig;         }         return globalConfig.getBitmapCache().getBitmapFromMemCache(uri, config);     }     ////////////////////////////////////////// tasks  任務//////////////////////////////////////////////////////////////////////     /**      * 支持暫停      */     @Override     public boolean supportPause() {         return true;     }     /**      * 支持從新開始      */     @Override     public boolean supportResume() {         return true;     }     /**      * 支持取消      */     @Override     public boolean supportCancel() {         return true;     }     /**      * 暫停      */     @Override     public void pause() {         pauseTask = true;         flushCache();     }     /**      * 刷新      */     @Override     public void resume() {         pauseTask = false;         synchronized (pauseTaskLock) {             pauseTaskLock.notifyAll();         }     }     /**      * 取消      */     @Override     public void cancel() {         pauseTask = true;         cancelAllTask = true;         synchronized (pauseTaskLock) {             pauseTaskLock.notifyAll();         }     }     /**      * 是否暫停      */     @Override     public boolean isPaused() {         return pauseTask;     }     /**      * 是不是取消了      */     @Override     public boolean isCancelled() {         return cancelAllTask;     }     ////////////////////////////////////////////////下面這些方法是否沒有提供給開發者使用的///////////////////////////////////////////////////////////////     @SuppressWarnings("unchecked")     private static <T extends View> BitmapLoadTask<T> getBitmapTaskFromContainer(T container, BitmapLoadCallBack<T> callBack) {         if (container != null) {             final Drawable drawable = callBack.getDrawable(container);             if (drawable instanceof AsyncDrawable) {                 final AsyncDrawable<T> asyncDrawable = (AsyncDrawable<T>) drawable;                 return asyncDrawable.getBitmapWorkerTask();             }         }         return null;     }     private static <T extends View> boolean bitmapLoadTaskExist(T container, String uri, BitmapLoadCallBack<T> callBack) {         final BitmapLoadTask<T> oldLoadTask = getBitmapTaskFromContainer(container, callBack);         if (oldLoadTask != null) {             final String oldUrl = oldLoadTask.uri;             if (TextUtils.isEmpty(oldUrl) || !oldUrl.equals(uri)) {                 oldLoadTask.cancel(true);             } else {                 return true;             }         }         return false;     }     public class BitmapLoadTask<T extends View> extends PriorityAsyncTask<Object, Object, Bitmap> {         private final String uri;         private final WeakReference<T> containerReference;         private final BitmapLoadCallBack<T> callBack;         private final BitmapDisplayConfig displayConfig;         private BitmapLoadFrom from = BitmapLoadFrom.DISK_CACHE;         public BitmapLoadTask(T container, String uri, BitmapDisplayConfig config, BitmapLoadCallBack<T> callBack) {             if (container == null || uri == null || config == null || callBack == null) {                 throw new IllegalArgumentException("args may not be null");             }             this.containerReference = new WeakReference<T>(container);             this.callBack = callBack;             this.uri = uri;             this.displayConfig = config;         }         @Override         protected Bitmap doInBackground(Object... params) {             synchronized (pauseTaskLock) {                 while (pauseTask && !this.isCancelled()) {                     try {                         pauseTaskLock.wait();                         if (cancelAllTask) {                             return null;                         }                     } catch (Throwable e) {                     }                 }             }             Bitmap bitmap = null;             // get cache from disk cache             if (!this.isCancelled() && this.getTargetContainer() != null) {                 this.publishProgress(PROGRESS_LOAD_STARTED);                 bitmap = globalConfig.getBitmapCache().getBitmapFromDiskCache(uri, displayConfig);             }             // download image             if (bitmap == null && !this.isCancelled() && this.getTargetContainer() != null) {                 bitmap = globalConfig.getBitmapCache().downloadBitmap(uri, displayConfig, this);                 from = BitmapLoadFrom.URI;             }             return bitmap;         }         public void updateProgress(long total, long current) {             this.publishProgress(PROGRESS_LOADING, total, current);         }         private static final int PROGRESS_LOAD_STARTED = 0;         private static final int PROGRESS_LOADING = 1;         @Override         protected void onProgressUpdate(Object... values) {             if (values == null || values.length == 0) return;             final T container = this.getTargetContainer();             if (container == null) return;             switch ((Integer) values[0]) {                 case PROGRESS_LOAD_STARTED:                     callBack.onLoadStarted(container, uri, displayConfig);                     break;                 case PROGRESS_LOADING:                     if (values.length != 3) return;                     callBack.onLoading(container, uri, displayConfig, (Long) values[1], (Long) values[2]);                     break;                 default:                     break;             }         }         @Override         protected void onPostExecute(Bitmap bitmap) {             final T container = this.getTargetContainer();             if (container != null) {                 if (bitmap != null) {                     callBack.onLoadCompleted(                             container,                             this.uri,                             bitmap,                             displayConfig,                             from);                 } else {                     callBack.onLoadFailed(                             container,                             this.uri,                             displayConfig.getLoadFailedDrawable());                 }             }         }         @Override         protected void onCancelled(Bitmap bitmap) {             synchronized (pauseTaskLock) {                 pauseTaskLock.notifyAll();             }         }         public T getTargetContainer() {             final T container = containerReference.get();             final BitmapLoadTask<T> bitmapWorkerTask = getBitmapTaskFromContainer(container, callBack);             if (this == bitmapWorkerTask) {                 return container;             }             return null;         }     } }