From 819abb59df6d53fd5f16da22ccb08609535f58c7 Mon Sep 17 00:00:00 2001 From: Flyge Date: Mon, 30 Oct 2017 00:55:03 +0800 Subject: [PATCH] :art: Optimize javadoc --- docs/logs/log_2.6.0_p1.md | 6 ++ .../java/me/xiaopan/sketch/Configuration.java | 6 +- .../java/me/xiaopan/sketch/Identifier.java | 4 +- .../sketch/display/ImageDisplayer.java | 1 + .../me/xiaopan/sketch/http/HttpStack.java | 50 +++++++--- .../me/xiaopan/sketch/http/HurlStack.java | 12 +-- .../xiaopan/sketch/http/ImageDownloader.java | 98 ++++++++++--------- .../sketch/optionsfilter/OptionsFilter.java | 5 + .../optionsfilter/OptionsFilterManager.java | 59 +++++++++-- .../sketch/process/ImageProcessor.java | 10 +- .../xiaopan/sketch/request/DisplayHelper.java | 4 +- .../me/xiaopan/sketch/request/LoadHelper.java | 4 +- .../xiaopan/sketch/request/LoadOptions.java | 6 +- .../sketch/shaper/CircleImageShaper.java | 2 +- .../me/xiaopan/sketch/shaper/ImageShaper.java | 15 +++ .../sketch/shaper/RoundRectImageShaper.java | 2 +- .../sketch/state/DrawableStateImage.java | 2 +- .../xiaopan/sketch/state/MakerStateImage.java | 3 +- .../sketch/state/MemoryCacheStateImage.java | 2 +- .../xiaopan/sketch/state/OldStateImage.java | 3 +- .../me/xiaopan/sketch/state/StateImage.java | 11 ++- .../java/me/xiaopan/sketch/uri/UriModel.java | 25 +++-- .../xiaopan/sketch/uri/UriModelManager.java | 49 +++++++++- 23 files changed, 267 insertions(+), 112 deletions(-) diff --git a/docs/logs/log_2.6.0_p1.md b/docs/logs/log_2.6.0_p1.md index a4f4515c74..4cbe2ec7fe 100644 --- a/docs/logs/log_2.6.0_p1.md +++ b/docs/logs/log_2.6.0_p1.md @@ -8,6 +8,12 @@ * :hammer: 所有 tile 相关的名字 全部改成了 block * :hammer: UriModelRegistry 重命名为 UriModelManager * :hammer: OptionsFilterRegistry 重命名为 OptionsFilterManager +* :hammer: HttpStack.ImageHttpResponse 重命名为 HttpStack.Response +* :hammer: HttpStack.getHttpResponse(String). 重命名为 HttpStack.getResponse(String) +* :hammer: HttpStack.ImageHttpResponse.getResponseCode() 重命名为 HttpStack.Response.getCode() +* :hammer: HttpStack.ImageHttpResponse.getResponseMessage() 重命名为 HttpStack.Response.getMessage() +* :hammer: HttpStack.ImageHttpResponse.getResponseHeadersString() 重命名为 HttpStack.Response.getHeadersString() +* :hammer: HttpStack.ImageHttpResponse.getResponseHeader() 重命名为 HttpStack.Response.getHeader() sample app: * :bug: 修复 UNSPLASH 页面没有加载完数据就切换到别的页面时崩溃的 BUG diff --git a/sketch/src/main/java/me/xiaopan/sketch/Configuration.java b/sketch/src/main/java/me/xiaopan/sketch/Configuration.java index 5a91ec7238..347f783b5f 100644 --- a/sketch/src/main/java/me/xiaopan/sketch/Configuration.java +++ b/sketch/src/main/java/me/xiaopan/sketch/Configuration.java @@ -701,7 +701,7 @@ public Configuration setLowQualityImageEnabled(boolean lowQualityImageEnabled) { } /** - * 全局解码时优先质量？ + * 全局解码时优先考虑速度还是质量 (默认优先考虑速度) * * @return true：质量优先；false：速度优先 */ @@ -711,9 +711,9 @@ public boolean isInPreferQualityOverSpeedEnabled() { } /** - * 设置全局解码时优先考虑质量 (默认优先考虑速度) + * 全局解码时优先考虑速度还是质量 (默认优先考虑速度) * - * @param inPreferQualityOverSpeedEnabled true：质量；false：速度 + * @param inPreferQualityOverSpeedEnabled true：质量优先；false：速度优先 * @return {@link Configuration}. 为了支持链式调用 */ @NonNull diff --git a/sketch/src/main/java/me/xiaopan/sketch/Identifier.java b/sketch/src/main/java/me/xiaopan/sketch/Identifier.java index 16ef332a1f..213f42f46a 100644 --- a/sketch/src/main/java/me/xiaopan/sketch/Identifier.java +++ b/sketch/src/main/java/me/xiaopan/sketch/Identifier.java @@ -4,9 +4,9 @@ public interface Identifier { /** - * 用来生成缓存key，或者在log中标识一个组件 + * 用来生成缓存 key，或者在 log 中标识一个组件 *
- * 通常key是由组件名称和组件属性组成的，例如 String.format("%s(radius=%d,maskColor=%d)", "GaussianBlurImageProcessor", radius, maskColor) + * 通常 key 是由组件名称和组件属性组成的，例如 String.format("%s(radius=%d,maskColor=%d)", "GaussianBlurImageProcessor", radius, maskColor) */ @NonNull String getKey(); diff --git a/sketch/src/main/java/me/xiaopan/sketch/display/ImageDisplayer.java b/sketch/src/main/java/me/xiaopan/sketch/display/ImageDisplayer.java index a787244c81..cda76951f3 100644 --- a/sketch/src/main/java/me/xiaopan/sketch/display/ImageDisplayer.java +++ b/sketch/src/main/java/me/xiaopan/sketch/display/ImageDisplayer.java @@ -25,6 +25,7 @@ /** * 图片显示器，用来在加载完成后显示图片 */ +// TODO: 2017/10/30 继续完善 javadoc public interface ImageDisplayer extends Identifier { int DEFAULT_ANIMATION_DURATION = 400; diff --git a/sketch/src/main/java/me/xiaopan/sketch/http/HttpStack.java b/sketch/src/main/java/me/xiaopan/sketch/http/HttpStack.java index c90af268b1..d597cbd803 100644 --- a/sketch/src/main/java/me/xiaopan/sketch/http/HttpStack.java +++ b/sketch/src/main/java/me/xiaopan/sketch/http/HttpStack.java @@ -34,52 +34,60 @@ public interface HttpStack extends Identifier { int DEFAULT_MAX_RETRY_COUNT = 0; // 默认最大重试次数 /** - * 获取最大重试次数 + * 获取最大重试次数，默认值是 {@link HttpStack#DEFAULT_MAX_RETRY_COUNT} */ int getMaxRetryCount(); /** - * 设置最大重试次数（默认HttpStack.DEFAULT_MAX_RETRY_COUNT） + * 设置最大重试次数 + * + * @param maxRetryCount 最大重试次数 */ @SuppressWarnings("unused") @NonNull HttpStack setMaxRetryCount(int maxRetryCount); /** - * 获取连接超时时间（默认HttpStack.DEFAULT_CONNECT_TIMEOUT） + * 获取连接超时时间，单位毫秒，默认值是 {@link HttpStack#DEFAULT_CONNECT_TIMEOUT} */ @SuppressWarnings("unused") int getConnectTimeout(); /** - * 设置连接超时时间（默认HttpStack.DEFAULT_CONNECT_TIMEOUT） + * 设置连接超时时间 + * + * @param connectTimeout 连接超时时间，单位毫秒 */ @SuppressWarnings("unused") @NonNull HttpStack setConnectTimeout(int connectTimeout); /** - * 获取读取超时时间（默认HttpStack.DEFAULT_READ_TIMEOUT） + * 获取读取超时时间，单位毫秒，默认值是 {@link HttpStack#DEFAULT_READ_TIMEOUT} */ @SuppressWarnings("unused") int getReadTimeout(); /** - * 设置读取超时时间（默认HttpStack.DEFAULT_READ_TIMEOUT） + * 设置读取超时时间 + * + * @param readTimeout 读取超时时间，单位毫秒 */ @SuppressWarnings("unused") @NonNull HttpStack setReadTimeout(int readTimeout); /** - * 获取User-Agent + * 获取自定义请求头中的 User-Agent 属性 */ @SuppressWarnings("unused") @Nullable String getUserAgent(); /** - * 设置User-Agent + * 设置请求头中的 User-Agent 属性 + * + * @param userAgent 请求头中的 User-Agent 属性 */ @SuppressWarnings("unused") @NonNull @@ -93,7 +101,9 @@ public interface HttpStack extends Identifier { Map getExtraHeaders(); /** - * 设置扩展请求属性 + * 设置扩展请求属性集 + * + * @param extraHeaders 扩展请求属性集 */ @SuppressWarnings("unused") @NonNull @@ -108,29 +118,37 @@ public interface HttpStack extends Identifier { /** * 添加可存在多个的请求属性 + * + * @param extraHeaders 扩展请求属性集 */ @SuppressWarnings("unused") @NonNull HttpStack addExtraHeaders(Map extraHeaders); /** - * 获取响应 + * 发送请求并获取响应 + * + * @param uri http uri + * @return {@link Response} */ @NonNull - ImageHttpResponse getHttpResponse(String uri) throws IOException; + Response getResponse(String uri) throws IOException; /** * 是否可以重试 */ boolean canRetry(Throwable throwable); - interface ImageHttpResponse { + /** + * 统一响应接口 + */ + interface Response { /** * 获取响应状态码 * * @throws IOException IO */ - int getResponseCode() throws IOException; + int getCode() throws IOException; /** * 获取响应消息 @@ -139,7 +157,7 @@ interface ImageHttpResponse { */ @SuppressWarnings("unused") @Nullable - String getResponseMessage() throws IOException; + String getMessage() throws IOException; /** * 获取内容长度 @@ -155,13 +173,13 @@ interface ImageHttpResponse { * 获取响应头 */ @Nullable - String getResponseHeader(@NonNull String name); + String getHeader(@NonNull String name); /** * 获取所有的响应头 */ @Nullable - String getResponseHeadersString(); + String getHeadersString(); /** * 获取内容输入流 diff --git a/sketch/src/main/java/me/xiaopan/sketch/http/HurlStack.java b/sketch/src/main/java/me/xiaopan/sketch/http/HurlStack.java index 29dbd843e7..d72b9054a0 100644 --- a/sketch/src/main/java/me/xiaopan/sketch/http/HurlStack.java +++ b/sketch/src/main/java/me/xiaopan/sketch/http/HurlStack.java @@ -126,7 +126,7 @@ public String getKey() { @NonNull @Override - public ImageHttpResponse getHttpResponse(String uri) throws IOException { + public Response getResponse(String uri) throws IOException { HttpURLConnection connection = (HttpURLConnection) new URL(uri).openConnection(); connection.setConnectTimeout(connectTimeout); @@ -165,7 +165,7 @@ protected void processRequest(@SuppressWarnings("UnusedParameters") String uri, } - private static class HurlResponse implements ImageHttpResponse { + private static class HurlResponse implements Response { private HttpURLConnection connection; HurlResponse(HttpURLConnection connection) { @@ -173,12 +173,12 @@ private static class HurlResponse implements ImageHttpResponse { } @Override - public int getResponseCode() throws IOException { + public int getCode() throws IOException { return connection.getResponseCode(); } @Override - public String getResponseMessage() throws IOException { + public String getMessage() throws IOException { return connection.getResponseMessage(); } @@ -188,7 +188,7 @@ public long getContentLength() { } @Override - public String getResponseHeadersString() { + public String getHeadersString() { Map> headers = connection.getHeaderFields(); if (headers == null || headers.size() == 0) { return null; @@ -247,7 +247,7 @@ public boolean isContentChunked() { @Nullable @Override - public String getResponseHeader(@NonNull String name) { + public String getHeader(@NonNull String name) { return connection.getHeaderField(name); } } diff --git a/sketch/src/main/java/me/xiaopan/sketch/http/ImageDownloader.java b/sketch/src/main/java/me/xiaopan/sketch/http/ImageDownloader.java index 645ce51d56..e28a836841 100644 --- a/sketch/src/main/java/me/xiaopan/sketch/http/ImageDownloader.java +++ b/sketch/src/main/java/me/xiaopan/sketch/http/ImageDownloader.java @@ -38,16 +38,19 @@ import me.xiaopan.sketch.util.DiskLruCache; import me.xiaopan.sketch.util.SketchUtils; +/** + * 负责下载并缓存图片 + */ public class ImageDownloader implements Identifier { private static final String NAME = "ImageDownloader"; /** - * Download image + * 此方法是下载图片的入口，并主要负责下载缓存锁的申请和释放 * - * @param request DownloadRequest - * @return DownloadResult - * @throws CanceledException canceled - * @throws DownloadException download failed + * @param request {@link DownloadRequest} + * @return {@link DownloadResult} + * @throws CanceledException 已取消 + * @throws DownloadException 下载失败 */ @NonNull public DownloadResult download(@NonNull DownloadRequest request) throws CanceledException, DownloadException { @@ -88,14 +91,14 @@ public DownloadResult download(@NonNull DownloadRequest request) throws Canceled } /** - * Download exception retry + * 此方法负责下载的失败重试逻辑 * - * @param request DownloadRequest - * @param diskCache DiskCache - * @param diskCacheKey disk cache key - * @return DownloadResult - * @throws CanceledException canceled - * @throws DownloadException download failed + * @param request {@link DownloadRequest} + * @param diskCache {@link DiskCache}. 用来写出并缓存数据 + * @param diskCacheKey 磁盘缓存 key + * @return {@link DownloadResult} + * @throws CanceledException 已取消 + * @throws DownloadException 下载失败 */ @NonNull private DownloadResult loopRetryDownload(@NonNull DownloadRequest request, @NonNull DiskCache diskCache, @@ -137,17 +140,18 @@ private DownloadResult loopRetryDownload(@NonNull DownloadRequest request, @NonN } /** - * Real execute download + * 真正的下载核心逻辑方法，发送 http 请求并读取响应 * - * @param request DownloadRequest - * @param uri image uri - * @param httpStack HttpStack - * @param diskCache DiskCache - * @param diskCacheKey disk cache key - * @return DownloadResult - * @throws IOException because io - * @throws CanceledException canceled - * @throws DownloadException download failed + * @param request {@link DownloadRequest} + * @param uri 图片 uri + * @param httpStack {@link HttpStack}. 用来发送 http 请求并且获取响应 + * @param diskCache {@link DiskCache}. 用来写出并缓存数据 + * @param diskCacheKey 磁盘缓存 key + * @return {@link DownloadResult} + * @throws IOException 发生 IO 异常 + * @throws CanceledException 已取消 + * @throws DownloadException 下载失败 + * @throws RedirectsException 图片地址重定向了 */ @NonNull private DownloadResult doDownload(@NonNull DownloadRequest request, @NonNull String uri, @NonNull HttpStack httpStack, @@ -155,17 +159,17 @@ private DownloadResult doDownload(@NonNull DownloadRequest request, @NonNull Str throws IOException, CanceledException, DownloadException, RedirectsException { // Opening http connection request.setStatus(BaseRequest.Status.CONNECTING); - HttpStack.ImageHttpResponse httpResponse; + HttpStack.Response response; //noinspection CaughtExceptionImmediatelyRethrown try { - httpResponse = httpStack.getHttpResponse(uri); + response = httpStack.getResponse(uri); } catch (IOException e) { throw e; } // Check canceled if (request.isCanceled()) { - httpResponse.releaseConnection(); + response.releaseConnection(); if (SLog.isLoggable(SLog.LEVEL_DEBUG | SLog.TYPE_FLOW)) { SLog.d(NAME, "Download canceled after opening the connection. %s. %s", request.getThreadName(), request.getKey()); } @@ -175,20 +179,20 @@ private DownloadResult doDownload(@NonNull DownloadRequest request, @NonNull Str // Check response code, must be 200 int responseCode; try { - responseCode = httpResponse.getResponseCode(); + responseCode = response.getCode(); } catch (IOException e) { - httpResponse.releaseConnection(); + response.releaseConnection(); String message = String.format("Get response code exception. responseHeaders: %s. %s. %s", - httpResponse.getResponseHeadersString(), request.getThreadName(), request.getKey()); + response.getHeadersString(), request.getThreadName(), request.getKey()); SLog.w(NAME, e, message); throw new DownloadException(message, e, ErrorCause.DOWNLOAD_GET_RESPONSE_CODE_EXCEPTION); } if (responseCode != 200) { - httpResponse.releaseConnection(); + response.releaseConnection(); // redirects if (responseCode == 301 || responseCode == 302) { - String newUri = httpResponse.getResponseHeader("Location"); + String newUri = response.getHeader("Location"); if (!TextUtils.isEmpty(newUri)) { // To prevent infinite redirection if (uri.equals(request.getUri())) { @@ -205,17 +209,17 @@ private DownloadResult doDownload(@NonNull DownloadRequest request, @NonNull Str } String message = String.format("Response code exception. responseHeaders: %s. %s. %s", - httpResponse.getResponseHeadersString(), request.getThreadName(), request.getKey()); + response.getHeadersString(), request.getThreadName(), request.getKey()); SLog.e(NAME, message); throw new DownloadException(message, ErrorCause.DOWNLOAD_RESPONSE_CODE_EXCEPTION); } // Check content length, must be greater than 0 or is chunked - long contentLength = httpResponse.getContentLength(); - if (contentLength <= 0 && !httpResponse.isContentChunked()) { - httpResponse.releaseConnection(); + long contentLength = response.getContentLength(); + if (contentLength <= 0 && !response.isContentChunked()) { + response.releaseConnection(); String message = String.format("Content length exception. contentLength: %d, responseHeaders: %s. %s. %s", - contentLength, httpResponse.getResponseHeadersString(), request.getThreadName(), request.getKey()); + contentLength, response.getHeadersString(), request.getThreadName(), request.getKey()); SLog.e(NAME, message); throw new DownloadException(message, ErrorCause.DOWNLOAD_CONTENT_LENGTH_EXCEPTION); } @@ -223,9 +227,9 @@ private DownloadResult doDownload(@NonNull DownloadRequest request, @NonNull Str // Get content InputStream inputStream; try { - inputStream = httpResponse.getContent(); + inputStream = response.getContent(); } catch (IOException e) { - httpResponse.releaseConnection(); + response.releaseConnection(); throw e; } @@ -281,7 +285,7 @@ private DownloadResult doDownload(@NonNull DownloadRequest request, @NonNull Str } // Check content fully and commit the disk cache - boolean readFully = (contentLength <= 0 && httpResponse.isContentChunked()) || completedLength == contentLength; + boolean readFully = (contentLength <= 0 && response.isContentChunked()) || completedLength == contentLength; if (readFully) { if (diskCacheEditor != null) { try { @@ -297,7 +301,7 @@ private DownloadResult doDownload(@NonNull DownloadRequest request, @NonNull Str diskCacheEditor.abort(); } String message = String.format("The data is not fully read. contentLength:%d, completedLength:%d, ContentChunked:%s. %s. %s", - contentLength, completedLength, httpResponse.isContentChunked(), request.getThreadName(), request.getKey()); + contentLength, completedLength, response.isContentChunked(), request.getThreadName(), request.getKey()); SLog.e(NAME, message); throw new DownloadException(message, ErrorCause.DOWNLOAD_DATA_NOT_FULLY_READ); } @@ -326,15 +330,15 @@ private DownloadResult doDownload(@NonNull DownloadRequest request, @NonNull Str } /** - * Read data and call update progress + * 读取数据并回调下载进度 * - * @param request DownloadRequest - * @param inputStream InputStream - * @param outputStream OutputStream - * @param contentLength content length - * @return completed length - * @throws IOException because io - * @throws CanceledException canceled + * @param request {@link DownloadRequest} + * @param inputStream {@link InputStream} + * @param outputStream {@link OutputStream} + * @param contentLength 数据长度 + * @return 已读取数据长度 + * @throws IOException IO 异常 + * @throws CanceledException 已取消 */ private int readData(@NonNull DownloadRequest request, @NonNull InputStream inputStream, @NonNull OutputStream outputStream, int contentLength) throws IOException, CanceledException { diff --git a/sketch/src/main/java/me/xiaopan/sketch/optionsfilter/OptionsFilter.java b/sketch/src/main/java/me/xiaopan/sketch/optionsfilter/OptionsFilter.java index 96031cfc93..23afcb4b9f 100644 --- a/sketch/src/main/java/me/xiaopan/sketch/optionsfilter/OptionsFilter.java +++ b/sketch/src/main/java/me/xiaopan/sketch/optionsfilter/OptionsFilter.java @@ -22,5 +22,10 @@ * 选项过滤器，用于统一修改 Options */ public interface OptionsFilter { + /** + * 过滤 Options + * + * @param options {@link DownloadOptions} + */ void filter(DownloadOptions options); } diff --git a/sketch/src/main/java/me/xiaopan/sketch/optionsfilter/OptionsFilterManager.java b/sketch/src/main/java/me/xiaopan/sketch/optionsfilter/OptionsFilterManager.java index 74f195e6ce..49d3d65df6 100644 --- a/sketch/src/main/java/me/xiaopan/sketch/optionsfilter/OptionsFilterManager.java +++ b/sketch/src/main/java/me/xiaopan/sketch/optionsfilter/OptionsFilterManager.java @@ -23,8 +23,21 @@ import me.xiaopan.sketch.Configuration; import me.xiaopan.sketch.Identifier; +import me.xiaopan.sketch.Sketch; +import me.xiaopan.sketch.SketchView; import me.xiaopan.sketch.request.DownloadOptions; - +import me.xiaopan.sketch.request.LoadListener; + +/** + * 负责管理 {@link OptionsFilter} 和过滤 Options，内置了以下选项过滤器

+ *

    + *
  • 全局暂停下载功能 -> {@link PauseDownloadOptionsFilter}
    • + *
  • 全局暂停加载功能 -> {@link PauseLoadOptionsFilter}
    • + *
  • 全局使用低质量图片功能 -> {@link LowQualityOptionsFilter}
    • + *
  • 全局解码时质量优先功能 -> {@link InPreferQualityOverSpeedOptionsFilter}
    • + *
  • 全局移动数据下暂停下载功能 -> {@link MobileDataPauseDownloadController}
    • + *
+ */ public class OptionsFilterManager implements Identifier { private PauseDownloadOptionsFilter pauseDownloadOptionsFilter; @@ -34,6 +47,12 @@ public class OptionsFilterManager implements Identifier { private MobileDataPauseDownloadController mobileDataPauseDownloadController; private List extrasFilters; + /** + * 添加一个 {@link OptionsFilter} + * + * @param optionsFilter {@link OptionsFilter} + * @return {@link OptionsFilterManager}. 为了支持链式调用 + */ @NonNull public OptionsFilterManager add(@NonNull OptionsFilter optionsFilter) { //noinspection ConstantConditions @@ -46,6 +65,13 @@ public OptionsFilterManager add(@NonNull OptionsFilter optionsFilter) { return this; } + /** + * 添加一个 {@link OptionsFilter} 到指定位置 + * + * @param index 指定位置 + * @param optionsFilter {@link OptionsFilter} + * @return {@link OptionsFilterManager}. 为了支持链式调用 + */ @NonNull public OptionsFilterManager add(int index, @NonNull OptionsFilter optionsFilter) { //noinspection ConstantConditions @@ -58,11 +84,22 @@ public OptionsFilterManager add(int index, @NonNull OptionsFilter optionsFilter) return this; } + /** + * 删除一个 {@link OptionsFilter} + * + * @param optionsFilter {@link OptionsFilter} + * @return true：存在指定 {@link OptionsFilter} 并已删除 + */ public boolean remove(@NonNull OptionsFilter optionsFilter) { //noinspection ConstantConditions return optionsFilter != null && extrasFilters != null && extrasFilters.remove(optionsFilter); } + /** + * 过滤指定 Options + * + * @param options {@link DownloadOptions} + */ public void filter(@NonNull DownloadOptions options) { //noinspection ConstantConditions if (options == null) { @@ -91,14 +128,16 @@ public void filter(@NonNull DownloadOptions options) { /** - * 全局暂停下载图片？开启后将不再从网络下载图片，只影响 display 请求和 load 请求 + * 全局暂停下载图片？开启后将不再从网络下载图片，只影响 {@link Sketch#display(String, SketchView)} 方法和 {@link Sketch#load(String, LoadListener)} 方法 */ public boolean isPauseDownloadEnabled() { return pauseDownloadOptionsFilter != null; } /** - * 设置全局暂停下载图片，开启后将不再从网络下载图片，只影响 display 请求和 load 请求 + * 设置全局暂停下载图片，开启后将不再从网络下载图片，只影响 {@link Sketch#display(String, SketchView)} 方法和 {@link Sketch#load(String, LoadListener)} 方法 + * + * @param pauseDownloadEnabled 全局暂停下载新图片 */ public void setPauseDownloadEnabled(boolean pauseDownloadEnabled) { if (isPauseDownloadEnabled() != pauseDownloadEnabled) { @@ -107,14 +146,16 @@ public void setPauseDownloadEnabled(boolean pauseDownloadEnabled) { } /** - * 全局暂停加载新图片？开启后将只从内存缓存中找寻图片，只影响 display 请求 + * 全局暂停加载新图片？开启后将只从内存缓存中找寻图片，只影响 {@link Sketch#display(String, SketchView)} 方法 */ public boolean isPauseLoadEnabled() { return pauseLoadOptionsFilter != null; } /** - * 设置全局暂停加载新图片，开启后将只从内存缓存中找寻图片，只影响 display 请求 + * 设置全局暂停加载新图片，开启后将只从内存缓存中找寻图片，只影响 {@link Sketch#display(String, SketchView)} 方法 + * + * @param pauseLoadEnabled 全局暂停加载新图片 */ public void setPauseLoadEnabled(boolean pauseLoadEnabled) { if (isPauseLoadEnabled() != pauseLoadEnabled) { @@ -131,6 +172,8 @@ public boolean isLowQualityImageEnabled() { /** * 设置全局使用低质量的图片 + * + * @param lowQualityImageEnabled 全局使用低质量图片 */ public void setLowQualityImageEnabled(boolean lowQualityImageEnabled) { if (isLowQualityImageEnabled() != lowQualityImageEnabled) { @@ -150,7 +193,7 @@ public boolean isInPreferQualityOverSpeedEnabled() { /** * 开启全局解码时优先考虑速度还是质量 (默认优先考虑速度) * - * @param inPreferQualityOverSpeedEnabled true：质量；false：速度 + * @param inPreferQualityOverSpeedEnabled true：质量优先；false：速度优先 */ public void setInPreferQualityOverSpeedEnabled(boolean inPreferQualityOverSpeedEnabled) { if (isInPreferQualityOverSpeedEnabled() != inPreferQualityOverSpeedEnabled) { @@ -167,7 +210,9 @@ public boolean isMobileDataPauseDownloadEnabled() { } /** - * 开启全局移动数据或有流量限制的 WIFI 下暂停下载的功能，只影响 display 请求和 load 请求 + * 开启全局移动数据或有流量限制的 WIFI 下暂停下载的功能，只影响 {@link Sketch#display(String, SketchView)} 方法和 {@link Sketch#load(String, LoadListener)} 方法 + * + * @param mobileDataPauseDownloadEnabled 全局移动数据下暂停下载 */ public void setMobileDataPauseDownloadEnabled(Configuration configuration, boolean mobileDataPauseDownloadEnabled) { if (isMobileDataPauseDownloadEnabled() != mobileDataPauseDownloadEnabled) { diff --git a/sketch/src/main/java/me/xiaopan/sketch/process/ImageProcessor.java b/sketch/src/main/java/me/xiaopan/sketch/process/ImageProcessor.java index 07b0e93b40..b1ffe90045 100644 --- a/sketch/src/main/java/me/xiaopan/sketch/process/ImageProcessor.java +++ b/sketch/src/main/java/me/xiaopan/sketch/process/ImageProcessor.java @@ -25,11 +25,17 @@ import me.xiaopan.sketch.request.Resize; /** - * {@link ImageProcessor} 可以修改图片 + * 用于在图片读取到内存后对图片进行修改 */ public interface ImageProcessor extends Identifier { /** - * 处理 + * 修改图片并返回修改后的图片，请不要回收原图片 + * + * @param sketch {@link Sketch} + * @param bitmap {@link Bitmap}. 原图片 + * @param resize {@link Resize}. resize 决定了新图片的尺寸 + * @param lowQualityImage 是否使用低质量的图片 + * @return {@link Bitmap}. 修改后的图片，可以是一个新的 {@link Bitmap}，也可以在原 {@link Bitmap} 基础上修改 */ @NonNull Bitmap process(@NonNull Sketch sketch, @NonNull Bitmap bitmap, @Nullable Resize resize, boolean lowQualityImage); diff --git a/sketch/src/main/java/me/xiaopan/sketch/request/DisplayHelper.java b/sketch/src/main/java/me/xiaopan/sketch/request/DisplayHelper.java index 783991d050..21b72b1b10 100644 --- a/sketch/src/main/java/me/xiaopan/sketch/request/DisplayHelper.java +++ b/sketch/src/main/java/me/xiaopan/sketch/request/DisplayHelper.java @@ -240,9 +240,9 @@ public DisplayHelper lowQualityImage() { } /** - * 设置图片处理器，可以修改图片 + * 设置图片处理器，在图片读取到内存后对图片进行修改 * - * @param processor 图片处理器 + * @param processor {@link ImageProcessor} * @return {@link DisplayHelper}. 为了支持链式调用 */ @NonNull diff --git a/sketch/src/main/java/me/xiaopan/sketch/request/LoadHelper.java b/sketch/src/main/java/me/xiaopan/sketch/request/LoadHelper.java index c5717b06dc..56ec93dcb2 100644 --- a/sketch/src/main/java/me/xiaopan/sketch/request/LoadHelper.java +++ b/sketch/src/main/java/me/xiaopan/sketch/request/LoadHelper.java @@ -185,9 +185,9 @@ public LoadHelper lowQualityImage() { } /** - * 设置图片处理器，可以修改图片 + * 设置图片处理器，在图片读取到内存后对图片进行修改 * - * @param processor 图片处理器 + * @param processor {@link ImageProcessor} * @return {@link LoadHelper}. 为了支持链式调用 */ @NonNull diff --git a/sketch/src/main/java/me/xiaopan/sketch/request/LoadOptions.java b/sketch/src/main/java/me/xiaopan/sketch/request/LoadOptions.java index be7eb22baa..a7d5cadc1c 100644 --- a/sketch/src/main/java/me/xiaopan/sketch/request/LoadOptions.java +++ b/sketch/src/main/java/me/xiaopan/sketch/request/LoadOptions.java @@ -64,7 +64,7 @@ public class LoadOptions extends DownloadOptions { private boolean thumbnailMode; /** - * 图片处理器，可以修改图片 + * 图片处理器，在图片读取到内存后对图片进行修改 */ private ImageProcessor processor; @@ -203,7 +203,7 @@ public LoadOptions setResize(int reWidth, int reHeight, @Nullable ImageView.Scal } /** - * 获取图片处理器，可以修改图片 + * 获取图片处理器，在图片读取到内存后对图片进行修改 * * @return {@link ImageProcessor} */ @@ -213,7 +213,7 @@ public ImageProcessor getProcessor() { } /** - * 设置图片处理器，可以修改图片 + * 设置图片处理器，在图片读取到内存后对图片进行修改 * * @param processor {@link ImageProcessor} * @return {@link LoadOptions}. 为了支持链式调用 diff --git a/sketch/src/main/java/me/xiaopan/sketch/shaper/CircleImageShaper.java b/sketch/src/main/java/me/xiaopan/sketch/shaper/CircleImageShaper.java index 73d9fa7084..53b4397c2f 100644 --- a/sketch/src/main/java/me/xiaopan/sketch/shaper/CircleImageShaper.java +++ b/sketch/src/main/java/me/xiaopan/sketch/shaper/CircleImageShaper.java @@ -27,7 +27,7 @@ import me.xiaopan.sketch.request.ShapeSize; /** - * 圆形的图片整形器，还可以有描边 + * 圆形的绘制时图片整形器，还可以有描边 */ public class CircleImageShaper implements ImageShaper { private int strokeWidth; diff --git a/sketch/src/main/java/me/xiaopan/sketch/shaper/ImageShaper.java b/sketch/src/main/java/me/xiaopan/sketch/shaper/ImageShaper.java index 97e369ece7..1f10baf273 100644 --- a/sketch/src/main/java/me/xiaopan/sketch/shaper/ImageShaper.java +++ b/sketch/src/main/java/me/xiaopan/sketch/shaper/ImageShaper.java @@ -21,6 +21,7 @@ import android.graphics.Paint; import android.graphics.Path; import android.graphics.Rect; +import android.graphics.Shader; import android.support.annotation.NonNull; import android.support.annotation.Nullable; @@ -36,10 +37,24 @@ public interface ImageShaper { @NonNull Path getPath(@NonNull Rect bounds); + /** + * {@link Shader} 的 {@link Matrix} 更新时回调 + * + * @param matrix {@link Shader} 的 {@link Matrix} + * @param bounds {@link Rect}. 绘制区域的边界位置 + * @param bitmapWidth bitmap 宽 + * @param bitmapHeight bitmap 高 + * @param shapeSize {@link ShapeSize} + * @param srcRect {@link Rect}. 原图中的位置 + */ void onUpdateShaderMatrix(@NonNull Matrix matrix, @NonNull Rect bounds, int bitmapWidth, int bitmapHeight, @Nullable ShapeSize shapeSize, @NonNull Rect srcRect); /** * 绘制 + * + * @param canvas {@link Canvas} + * @param paint {@link Paint} + * @param bounds {@link Rect}. 绘制区域的边界位置 */ void draw(@NonNull Canvas canvas, @NonNull Paint paint, @NonNull Rect bounds); } diff --git a/sketch/src/main/java/me/xiaopan/sketch/shaper/RoundRectImageShaper.java b/sketch/src/main/java/me/xiaopan/sketch/shaper/RoundRectImageShaper.java index c1a462222d..0e5a03f837 100644 --- a/sketch/src/main/java/me/xiaopan/sketch/shaper/RoundRectImageShaper.java +++ b/sketch/src/main/java/me/xiaopan/sketch/shaper/RoundRectImageShaper.java @@ -28,7 +28,7 @@ import me.xiaopan.sketch.request.ShapeSize; /** - * 圆角矩形的图片，还可以有描边 + * 圆角矩形的绘制时图片整形器，还可以有描边 */ @SuppressWarnings("unused") public class RoundRectImageShaper implements ImageShaper { diff --git a/sketch/src/main/java/me/xiaopan/sketch/state/DrawableStateImage.java b/sketch/src/main/java/me/xiaopan/sketch/state/DrawableStateImage.java index f48d895b0e..9b1446d6f4 100644 --- a/sketch/src/main/java/me/xiaopan/sketch/state/DrawableStateImage.java +++ b/sketch/src/main/java/me/xiaopan/sketch/state/DrawableStateImage.java @@ -29,7 +29,7 @@ import me.xiaopan.sketch.shaper.ImageShaper; /** - * 给什么图片显示什么图片，支持ShapeSize和ImageShaper + * 给什么图片显示什么图片，支持 {@link ShapeSize} 和 {@link ImageShaper} */ @SuppressWarnings("unused") public class DrawableStateImage implements StateImage { diff --git a/sketch/src/main/java/me/xiaopan/sketch/state/MakerStateImage.java b/sketch/src/main/java/me/xiaopan/sketch/state/MakerStateImage.java index e739503229..929e5255a7 100644 --- a/sketch/src/main/java/me/xiaopan/sketch/state/MakerStateImage.java +++ b/sketch/src/main/java/me/xiaopan/sketch/state/MakerStateImage.java @@ -46,8 +46,9 @@ import me.xiaopan.sketch.util.SketchUtils; /** - * 可以利用Options中配置的ImageProcessor和resize修改原图片，同样支持ShapeSize和ImageShaper + * 可以使用 Options 中配置的 {@link ImageProcessor} 和 {@link Resize} 修改原图片，同样支持 {@link ShapeSize} 和 {@link ImageShaper} */ +// TODO: 2017/10/30 重命名为 MakerDrawableStateImage 并像 DrawableStateImage 一样支持 drawable @SuppressWarnings("unused") public class MakerStateImage implements StateImage { private int resId; diff --git a/sketch/src/main/java/me/xiaopan/sketch/state/MemoryCacheStateImage.java b/sketch/src/main/java/me/xiaopan/sketch/state/MemoryCacheStateImage.java index 9dc7c6ef60..f2d9ba8feb 100644 --- a/sketch/src/main/java/me/xiaopan/sketch/state/MemoryCacheStateImage.java +++ b/sketch/src/main/java/me/xiaopan/sketch/state/MemoryCacheStateImage.java @@ -33,7 +33,7 @@ import me.xiaopan.sketch.shaper.ImageShaper; /** - * 从内存中获取图片作为状态图片，支持ShapeSize和ImageShaper + * 从内存缓存中获取图片作为状态图片，支持 {@link ShapeSize} 和 {@link ImageShaper} */ @SuppressWarnings("unused") public class MemoryCacheStateImage implements StateImage { diff --git a/sketch/src/main/java/me/xiaopan/sketch/state/OldStateImage.java b/sketch/src/main/java/me/xiaopan/sketch/state/OldStateImage.java index 49471d5afe..4a0f51befe 100644 --- a/sketch/src/main/java/me/xiaopan/sketch/state/OldStateImage.java +++ b/sketch/src/main/java/me/xiaopan/sketch/state/OldStateImage.java @@ -21,6 +21,7 @@ import android.graphics.drawable.Drawable; import android.support.annotation.NonNull; import android.support.annotation.Nullable; +import android.widget.ImageView; import me.xiaopan.sketch.SketchView; import me.xiaopan.sketch.drawable.SketchLoadingDrawable; @@ -31,7 +32,7 @@ import me.xiaopan.sketch.util.SketchUtils; /** - * 使用当前ImageView正在显示的图片作为状态图片 + * 使用当前 {@link ImageView} 正在显示的图片作为状态图片 */ @SuppressWarnings("unused") public class OldStateImage implements StateImage { diff --git a/sketch/src/main/java/me/xiaopan/sketch/state/StateImage.java b/sketch/src/main/java/me/xiaopan/sketch/state/StateImage.java index 7c67b54587..2caa2018ce 100644 --- a/sketch/src/main/java/me/xiaopan/sketch/state/StateImage.java +++ b/sketch/src/main/java/me/xiaopan/sketch/state/StateImage.java @@ -25,9 +25,18 @@ import me.xiaopan.sketch.request.DisplayOptions; /** - * 专门用于加载中、失败、暂停图片 + * 用于为加载中、失败、暂停状态提供占位图片 */ public interface StateImage { + + /** + * 获取图片 + * + * @param context {@link Context} + * @param sketchView {@link SketchView} + * @param displayOptions {@link DisplayOptions} + * @return {@link Drawable} + */ @Nullable Drawable getDrawable(@NonNull Context context, @NonNull SketchView sketchView, @NonNull DisplayOptions displayOptions); } diff --git a/sketch/src/main/java/me/xiaopan/sketch/uri/UriModel.java b/sketch/src/main/java/me/xiaopan/sketch/uri/UriModel.java index 9d4be5aed7..a74704c9ec 100644 --- a/sketch/src/main/java/me/xiaopan/sketch/uri/UriModel.java +++ b/sketch/src/main/java/me/xiaopan/sketch/uri/UriModel.java @@ -26,16 +26,16 @@ import me.xiaopan.sketch.request.DownloadResult; /** - * 负责某一类型 URI 的全部功能，你可通过此类实现扩展 Sketch 支持的 uri + * 负责解析某一特定类型的 uri */ public abstract class UriModel { /** - * 根据 uri 匹配能处理它的 UriModel + * 匹配可以解析指定 uri 的 {@link UriModel} * - * @param sketch Sketch + * @param sketch {@link Sketch} * @param uri 图片 uri - * @return 能够处理这种 uri 的 UriModel + * @return {@link UriModel}. 能够解析这种 uri 的 {@link UriModel} */ @Nullable public static UriModel match(@NonNull Sketch sketch, @NonNull String uri) { @@ -43,11 +43,11 @@ public static UriModel match(@NonNull Sketch sketch, @NonNull String uri) { } /** - * 根据 uri 匹配能处理它的 UriModel + * 匹配可以解析指定 uri 的 {@link UriModel} * - * @param context Context + * @param context {@link Context} * @param uri 图片 uri - * @return 能够处理这种 uri 的 UriModel + * @return {@link UriModel}. 能够解析这种 uri 的 {@link UriModel} */ @Nullable public static UriModel match(@NonNull Context context, @NonNull String uri) { @@ -55,19 +55,18 @@ public static UriModel match(@NonNull Context context, @NonNull String uri) { } /** - * 如果返回true，那么后续将使用这个 UriModel 来处理 uri + * 当前 {@link UriModel} 是否能够解析指定 uri * * @param uri 图片 uri - * @return true：能处理 */ protected abstract boolean match(@NonNull String uri); /** * 获取指定 uri 的数据，用于后续解码读取图片 * - * @param context Context + * @param context {@link Context} * @param uri 图片 uri - * @param downloadResult 下载结果，只对 {@link #isFromNet()} 为 true 的 UriModel 有用 + * @param downloadResult 下载结果，只对 {@link #isFromNet()} 为 true 的 {@link UriModel} 有用 * @return DataSource */ @NonNull @@ -75,7 +74,7 @@ public abstract DataSource getDataSource(@NonNull Context context, @NonNull Stri @Nullable DownloadResult downloadResult) throws GetDataSourceException; /** - * 获取 uri 中的内容部分，默认是它自己 + * 获取 uri 中的内容部分，默认是它自己。例如对于 http 类型的 uri，内容部分就是它自己，而对于 asset://sample.jpg 类型的 uri，内容部分就是 sample.jpg * * @param uri 图片 uri * @return uri 中的内容部分，默认是它自己 @@ -86,7 +85,7 @@ public String getUriContent(@NonNull String uri) { } /** - * 获取指定 uri 的磁盘缓存key，默认返回 uri 自己 + * 获取指定 uri 的磁盘缓存 key，默认返回 uri 自己 * * @param uri 图片 uri * @return 指定 uri 的磁盘缓存 key diff --git a/sketch/src/main/java/me/xiaopan/sketch/uri/UriModelManager.java b/sketch/src/main/java/me/xiaopan/sketch/uri/UriModelManager.java index dc52c70d17..86e88f10aa 100644 --- a/sketch/src/main/java/me/xiaopan/sketch/uri/UriModelManager.java +++ b/sketch/src/main/java/me/xiaopan/sketch/uri/UriModelManager.java @@ -26,9 +26,29 @@ import me.xiaopan.sketch.Identifier; /** - * 负责管理和匹配 {@link UriModel} + * 负责管理和匹配 {@link UriModel}，默认支持以下 uri 和 {@link UriModel} + *

+ *

    + *
  • http:// -> {@link HttpUriModel}
    • + *
  • https:// -> {@link HttpsUriModel}
    • + *
  • /sdcard/test.jpg -> {@link FileUriModel}
    • + *
  • file:// -> {@link FileVariantUriModel}
    • + *
  • asset:// -> {@link AssetUriModel}
    • + *
  • drawable:// -> {@link DrawableUriModel}
    • + *
  • content:// -> {@link ContentUriModel}
    • + *
  • android.resource:// -> {@link AndroidResUriModel}
    • + *
  • apk.icon:// -> {@link ApkIconUriModel}
    • + *
  • app.icon:// -> {@link AppIconUriModel}
    • + *
  • data:image/ -> {@link Base64UriModel}
    • + *
  • data:img/ -> {@link Base64VariantUriModel}
    • + *
+ *

+ * 还可以通过 {@link #add(UriModel)} 方法扩展支持新的 uri + *

+ * 通过 {@link #match(String)} 方法可以为指定 uri 匹配对应的 {@link UriModel} */ -public class UriModelManager implements Identifier{ +public class UriModelManager implements Identifier { + private List uriModelList = new LinkedList<>(); public UriModelManager() { @@ -46,6 +66,12 @@ public UriModelManager() { this.uriModelList.add(new Base64VariantUriModel()); } + /** + * 添加一个 {@link UriModel} + * + * @param uriModel {@link UriModel} + * @return {@link UriModelManager}. 为了支持链式调用 + */ @NonNull public UriModelManager add(@NonNull UriModel uriModel) { //noinspection ConstantConditions @@ -55,6 +81,13 @@ public UriModelManager add(@NonNull UriModel uriModel) { return this; } + /** + * 添加一个 {@link UriModel} 到指定位置 + * + * @param index 指定位置 + * @param uriModel {@link UriModel} + * @return {@link UriModelManager}. 为了支持链式调用 + */ @NonNull public UriModelManager add(int index, @NonNull UriModel uriModel) { //noinspection ConstantConditions @@ -64,11 +97,23 @@ public UriModelManager add(int index, @NonNull UriModel uriModel) { return this; } + /** + * 删除一个 {@link UriModel} + * + * @param uriModel {@link UriModel} + * @return true：存在指定 {@link UriModel} 并已删除 + */ public boolean remove(@NonNull UriModel uriModel) { //noinspection ConstantConditions return uriModel != null && uriModelList.remove(uriModel); } + /** + * 寻找一个能解析指定 uri 的 {@link UriModel} + * + * @param uri 指定 uri + * @return {@link UriModel} + */ @Nullable public UriModel match(@NonNull String uri) { if (!TextUtils.isEmpty(uri)) {