xUtils 中的BitmapUtils 全面注释

原文地址：http://yangguangfu.iteye.com/blog/2212847

/** 
 * 加载图片工具类 
 * @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;  
        }  
    }  
}