diff --git a/library/src/main/java/com/qiniu/android/bigdata/Configuration.java b/library/src/main/java/com/qiniu/android/bigdata/Configuration.java index 42e1a29b5..e52c9cf5c 100644 --- a/library/src/main/java/com/qiniu/android/bigdata/Configuration.java +++ b/library/src/main/java/com/qiniu/android/bigdata/Configuration.java @@ -7,8 +7,15 @@ */ public final class Configuration implements Cloneable { + + /** + * pipelineHost + */ public String pipelineHost = "https://pipeline.qiniu.com"; + /** + * 请求 proxy + */ public ProxyConfiguration proxy; @@ -22,6 +29,12 @@ public final class Configuration implements Cloneable { */ public int responseTimeout = 10; + /** + * Configuration copy + * + * @param config 待 copy 对象 + * @return Configuration + */ public static Configuration copy(Configuration config) { if (config == null) { return new Configuration(); @@ -33,6 +46,11 @@ public static Configuration copy(Configuration config) { } } + /** + * Configuration clone + * + * @return Configuration + */ public Configuration clone() throws CloneNotSupportedException { return (Configuration) super.clone(); } diff --git a/library/src/main/java/com/qiniu/android/bigdata/client/Client.java b/library/src/main/java/com/qiniu/android/bigdata/client/Client.java index db378a2ae..7f947eb30 100644 --- a/library/src/main/java/com/qiniu/android/bigdata/client/Client.java +++ b/library/src/main/java/com/qiniu/android/bigdata/client/Client.java @@ -43,17 +43,45 @@ * Created by bailong on 15/11/12. */ public final class Client { + /** + * HTTP 请求头：Content-Type + */ public static final String ContentTypeHeader = "Content-Type"; + + /** + * HTTP 请求默认的 MimeType + */ public static final String DefaultMime = "application/octet-stream"; + + /** + * HTTP 请求 Json 的 MimeType + */ public static final String JsonMime = "application/json"; + + /** + * HTTP 请求 FormMime 的 MimeType + */ public static final String FormMime = "application/x-www-form-urlencoded"; + private final UrlConverter converter; private OkHttpClient httpClient; + /** + * 构造方法 + */ public Client() { this(null, 10, 30, null, null); } + /** + * 构造函数 + * + * @param proxy 请求代理 + * @param connectTimeout 请求建立连接超时时间 + * @param responseTimeout 请求接收数据超时时间 + * @param converter 请求 Url 拦截器 + * @param dns 请求的 Dns 解析器 + */ public Client(ProxyConfiguration proxy, int connectTimeout, int responseTimeout, UrlConverter converter, final Dns dns) { this.converter = converter; OkHttpClient.Builder builder = new OkHttpClient.Builder(); @@ -71,9 +99,9 @@ public List lookup(String hostname) throws UnknownHostException { List networkAddressList = DnsPrefetcher.getInstance().getInetAddressByHost(hostname); if (networkAddressList != null && networkAddressList.size() > 0) { List inetAddressList = new ArrayList<>(); - for (IDnsNetworkAddress networkAddress : networkAddressList){ + for (IDnsNetworkAddress networkAddress : networkAddressList) { InetAddress address = null; - if (networkAddress.getIpValue() != null && (address = InetAddress.getByName(networkAddress.getIpValue())) != null){ + if (networkAddress.getIpValue() != null && (address = InetAddress.getByName(networkAddress.getIpValue())) != null) { inetAddressList.add(address); } } @@ -266,6 +294,20 @@ public void asyncPost(String url, byte[] body, asyncPost(url, body, 0, body.length, headers, upToken, totalSize, progressHandler, completionHandler, c); } + /** + * 异步 POST 请求 + * + * @param url 请求 Url + * @param body 请求体 + * @param offset 请求体偏移量 + * @param size 请求体大小 + * @param headers 请求 Header + * @param upToken 上传 Token + * @param totalSize 请求体总大小 + * @param progressHandler 进度回调 + * @param completionHandler 完成回调 + * @param c 取消回调 + */ public void asyncPost(String url, byte[] body, int offset, int size, StringMap headers, final UpToken upToken, final long totalSize, ProgressHandler progressHandler, @@ -295,6 +337,16 @@ public void asyncPost(String url, byte[] body, int offset, int size, asyncSend(requestBuilder, headers, upToken, totalSize, completionHandler); } + /** + * 异步表单请求 + * + * @param url 请求 Url + * @param args 请求参数 + * @param upToken 上传的 Token + * @param progressHandler 进度回调 + * @param completionHandler 完成回答 + * @param c 取消回调 + */ public void asyncMultipartPost(String url, PostArgs args, final UpToken upToken, @@ -343,12 +395,27 @@ public void accept(String key, Object value) { asyncSend(requestBuilder, null, upToken, totalSize, completionHandler); } + /** + * 异步 GET 请求 + * + * @param url 请求 Url + * @param headers 请求 Header + * @param upToken 上传的 Token + * @param completionHandler 请求完成回调 + */ public void asyncGet(String url, StringMap headers, final UpToken upToken, CompletionHandler completionHandler) { Request.Builder requestBuilder = new Request.Builder().get().url(url); asyncSend(requestBuilder, headers, upToken, 0, completionHandler); } + /** + * 同步 GET 请求 + * + * @param url 请求 Url + * @param headers 请求 Header + * @return ResponseInfo + */ public ResponseInfo syncGet(String url, StringMap headers) { Request.Builder requestBuilder = new Request.Builder().get().url(url); return send(requestBuilder, headers); @@ -379,8 +446,15 @@ public void accept(String key, Object value) { return buildResponseInfo(res, tag.ip, tag.duration, null, 0); } - public ResponseInfo syncMultipartPost(String url, PostArgs args, - final UpToken upToken) { + /** + * 同步表单请求 + * + * @param url 请求 Url + * @param args 请求参数 + * @param upToken 上传 Token + * @return ResponseInfo + */ + public ResponseInfo syncMultipartPost(String url, PostArgs args, final UpToken upToken) { RequestBody file; long totalSize; if (args.file != null) { @@ -414,6 +488,15 @@ public void accept(String key, Object value) { return syncSend(requestBuilder, null, upToken, totalSize); } + /** + * 同步请求 + * + * @param requestBuilder 请求构造器 + * @param headers 请求 Header + * @param upToken 上传的 Token + * @param totalSize 请求体大小 + * @return ResponseInfo + */ public ResponseInfo syncSend(final Request.Builder requestBuilder, StringMap headers, final UpToken upToken, final long totalSize) { if (headers != null) { diff --git a/library/src/main/java/com/qiniu/android/common/AutoZone.java b/library/src/main/java/com/qiniu/android/common/AutoZone.java index 21f958ac1..6194f4bc3 100644 --- a/library/src/main/java/com/qiniu/android/common/AutoZone.java +++ b/library/src/main/java/com/qiniu/android/common/AutoZone.java @@ -40,23 +40,44 @@ public final class AutoZone extends Zone { .setVersion("v1") .builder(); - //私有云可能改变ucServer + /** + * 配置 UC 域名，此 UC 域名用于根据上传 bucket 查询对应的区域。 + * 公有云不用配置 + * + * @param ucServer UC 域名 + */ public void setUcServer(String ucServer) { if (ucServer != null) { this.ucServers = new String[]{ucServer}; } } + /** + * 配置 UC 域名，此 UC 域名用于根据上传 bucket 查询对应的区域。 + * 公有云不用配置 + * + * @param ucServers UC 域名，可以是多个，多个会进行主备重试 + */ public void setUcServers(String[] ucServers) { if (ucServers != null && ucServers.length > 0) { this.ucServers = ucServers; } } + /** + * 配置默认区域，在使用 AutoZone 进行上传时，当根据 bucket 查询 Zone 信息失败时如果默认区域存在会尝试使用默认区域进行上传。 + * + * @param zones 默认区域，可以是多个 + */ public void setDefaultZones(FixedZone[] zones) { defaultZone = FixedZone.combineZones(zones); } + /** + * 获取 UC 域名列表 + * + * @return UC 域名列表 + */ public List getUcServerList() { if (ucServers != null && ucServers.length > 0) { ArrayList serverList = new ArrayList<>(); @@ -67,6 +88,9 @@ public List getUcServerList() { } } + /** + * 清除区域存储缓存 + */ public static void clearCache() { zoneCache.clearMemoryCache(); zoneCache.clearDiskCache(); @@ -106,7 +130,7 @@ public void preQuery(final UpToken token, final QueryHandler completeHandler) { UploadRegionRequestMetrics localMetrics = new UploadRegionRequestMetrics(null); localMetrics.start(); - final String cacheKey = makeCacheKey(token.index()) ; + final String cacheKey = makeCacheKey(token.index()); ZonesInfo zonesInfo = null; Cache.Object object = zoneCache.cacheForKey(cacheKey); @@ -197,7 +221,7 @@ private String makeCacheKey(String akAndBucket) { hosts.append(host).append(":"); } - return UrlSafeBase64.encodeToString(hosts+akAndBucket); + return UrlSafeBase64.encodeToString(hosts + akAndBucket); } private RequestTransaction createUploadRequestTransaction(UpToken token) { diff --git a/library/src/main/java/com/qiniu/android/common/Config.java b/library/src/main/java/com/qiniu/android/common/Config.java index dc02e3bca..6422a1343 100644 --- a/library/src/main/java/com/qiniu/android/common/Config.java +++ b/library/src/main/java/com/qiniu/android/common/Config.java @@ -49,7 +49,7 @@ public final class Config { /** * 记录上传信息文件最大值，单位：字节。 - * + *

* 记录文件大于此值后暂停记录上传信息。 */ public static int maxRecordFileSize = 20 * 1024 * 1024; @@ -69,10 +69,27 @@ public final class Config { * preQuery host */ public static String preQueryHost00 = "uc.qiniuapi.com"; + + /** + * preQuery host + */ public static String preQueryHost01 = "kodo-config.qiniuapi.com"; + + /** + * preQuery host + */ public static String preQueryHost02 = "uc.qbox.me"; + + /** + * preQuery host + */ public static String preQueryHost03 = "api.qiniu.com"; + /** + * 获取 preQuery hosts + * + * @return preQuery hosts + */ public static String[] preQueryHosts() { return new String[]{preQueryHost00, preQueryHost01, preQueryHost02, preQueryHost03}; } @@ -85,8 +102,11 @@ public static void quick() { interval = 2; } + /** + * 标准设置 + */ public static void normal() { - uploadThreshold = 4 * 1024; + uploadThreshold = 16 * 1024; interval = 10; } diff --git a/library/src/main/java/com/qiniu/android/common/Constants.java b/library/src/main/java/com/qiniu/android/common/Constants.java index 98a7f5e60..8d71795e3 100644 --- a/library/src/main/java/com/qiniu/android/common/Constants.java +++ b/library/src/main/java/com/qiniu/android/common/Constants.java @@ -1,8 +1,18 @@ package com.qiniu.android.common; +/** + * 常量定义 + */ public final class Constants { + + /** + * SDK 版本号 + */ public static final String VERSION = "8.7.0"; + /** + * UTF-8 编码 + */ public static final String UTF_8 = "utf-8"; } diff --git a/library/src/main/java/com/qiniu/android/common/FixedZone.java b/library/src/main/java/com/qiniu/android/common/FixedZone.java index 37e9716da..c291f3d43 100644 --- a/library/src/main/java/com/qiniu/android/common/FixedZone.java +++ b/library/src/main/java/com/qiniu/android/common/FixedZone.java @@ -89,6 +89,11 @@ public static FixedZone createWithRegionId(String regionId) { private ZonesInfo zonesInfo; + /** + * 获取 SDK 中使用的 zone，用于重试，外部不可使用 + * + * @return FixedZone + */ @Deprecated public static FixedZone localsZoneInfo() { FixedZone[] localsZone = new FixedZone[]{ @@ -121,20 +126,41 @@ public static FixedZone combineZones(FixedZone[] zones) { return new FixedZone(zonesInfo); } + /** + * 构造方法 + * + * @param zoneInfo zone 信息 + */ public FixedZone(ZoneInfo zoneInfo) { ArrayList zoneInfoList = new ArrayList<>(); zoneInfoList.add(zoneInfo); this.zonesInfo = new ZonesInfo(zoneInfoList); } + /** + * 构造方法 + * + * @param zonesInfo zones 信息 + */ public FixedZone(ZonesInfo zonesInfo) { this.zonesInfo = zonesInfo; } + /** + * 构造方法 + * + * @param upDomains 上传域名 + */ public FixedZone(String[] upDomains) { this(upDomains, null); } + /** + * 构造方法 + * + * @param upDomains 上传域名 + * @param regionId 区域 ID + */ public FixedZone(String[] upDomains, String regionId) { this(upDomains, null, regionId); } diff --git a/library/src/main/java/com/qiniu/android/common/Zone.java b/library/src/main/java/com/qiniu/android/common/Zone.java index 9b92e883b..5fd652898 100644 --- a/library/src/main/java/com/qiniu/android/common/Zone.java +++ b/library/src/main/java/com/qiniu/android/common/Zone.java @@ -9,10 +9,25 @@ */ public abstract class Zone { + /** + * 根据上传 token 获取 zone + * + * @param token 上传 token + * @return 区域信息 + */ public abstract ZonesInfo getZonesInfo(UpToken token); + /** + * 根据上传 token 对区域进行预查询 + * + * @param token 上传 token + * @param completeHandler 预查询结束回调 + */ public abstract void preQuery(UpToken token, QueryHandler completeHandler); + /** + * 预查询结束回调 + */ public interface QueryHandler { void complete(int code, ResponseInfo responseInfo, UploadRegionRequestMetrics metrics); } diff --git a/library/src/main/java/com/qiniu/android/http/CancellationHandler.java b/library/src/main/java/com/qiniu/android/http/CancellationHandler.java index 7f5bc6d05..7e1ad8951 100644 --- a/library/src/main/java/com/qiniu/android/http/CancellationHandler.java +++ b/library/src/main/java/com/qiniu/android/http/CancellationHandler.java @@ -2,6 +2,9 @@ import java.io.IOException; +/** + * 取消对调定义 + */ public interface CancellationHandler { /** @@ -11,6 +14,9 @@ public interface CancellationHandler { */ boolean isCancelled(); + /** + * 取消异常 + */ class CancellationException extends IOException { } } diff --git a/library/src/main/java/com/qiniu/android/http/Headers.java b/library/src/main/java/com/qiniu/android/http/Headers.java index 2153c8dae..db8a4f139 100644 --- a/library/src/main/java/com/qiniu/android/http/Headers.java +++ b/library/src/main/java/com/qiniu/android/http/Headers.java @@ -73,6 +73,9 @@ private static String get(String[] namesAndValues, String name) { /** * Returns headers for the alternating header names and values. There must be an even number of * arguments, and they must alternate between header names and values. + * + * @param namesAndValues header + * @return Headers */ public static Headers of(String... namesAndValues) { if (namesAndValues == null) throw new NullPointerException("namesAndValues == null"); @@ -101,9 +104,11 @@ public static Headers of(String... namesAndValues) { } - /** * Returns headers for the header names and values in the {@link Map}. + * + * @param headers headers + * @return Headers */ public static Headers of(Map headers) { if (headers == null) throw new NullPointerException("headers == null"); @@ -128,7 +133,12 @@ public static Headers of(Map headers) { return new Headers(namesAndValues); } - /** Returns the last value corresponding to the specified field, or null. */ + /** + * Returns the last value corresponding to the specified field, or null. + * + * @param name head name + * @return head value + */ public String get(String name) { return get(namesAndValues, name); } @@ -136,27 +146,48 @@ public String get(String name) { /** * Returns the last value corresponding to the specified field parsed as an HTTP date, or null if * either the field is absent or cannot be parsed as a date. + * + * @param name head name + * @return Date */ public Date getDate(String name) { return HttpDate.parse(get(name)); } - /** Returns the number of field values. */ + /** + * Returns the number of field values. + * + * @return the number of field values. + */ public int size() { return namesAndValues.length / 2; } - /** Returns the field at {@code position}. */ + /** + * Returns the field at {@code position}. + * + * @param index index + * @return the field at {@code position}. + */ public String name(int index) { return namesAndValues[index * 2]; } - /** Returns the value at {@code index}. */ + /** + * Returns the value at {@code index}. + * + * @param index index + * @return the value at {@code index}. + */ public String value(int index) { return namesAndValues[index * 2 + 1]; } - /** Returns an immutable case-insensitive set of header names. */ + /** + * Returns an immutable case-insensitive set of header names. + * + * @return an immutable case-insensitive set of header names. + */ public Set names() { TreeSet result = new TreeSet<>(String.CASE_INSENSITIVE_ORDER); for (int i = 0, size = size(); i < size; i++) { @@ -165,7 +196,12 @@ public Set names() { return Collections.unmodifiableSet(result); } - /** Returns an immutable list of the header values for {@code name}. */ + /** + * Returns an immutable list of the header values for {@code name}. + * + * @param name head name + * @return an immutable list of the header values for {@code name}. + */ public List values(String name) { List result = null; for (int i = 0, size = size(); i < size; i++) { @@ -183,6 +219,8 @@ public List values(String name) { * Returns the number of bytes required to encode these headers using HTTP/1.1. This is also the * approximate size of HTTP/2 headers before they are compressed with HPACK. This value is * intended to be used as a metric: smaller headers are more efficient to encode and transmit. + * + * @return the number of bytes required to encode these headers using HTTP/1.1. */ public long byteCount() { // Each header name has 2 bytes of overhead for ': ' and every header value has 2 bytes of @@ -196,6 +234,11 @@ public long byteCount() { return result; } + /** + * newBuilder + * + * @return newBuilder + */ public Builder newBuilder() { Builder result = new Builder(); Collections.addAll(result.namesAndValues, namesAndValues); @@ -224,9 +267,11 @@ public Builder newBuilder() { * Content-Type: text/html * Content-Length: 050 * } - * * Applications that require semantically equal headers should convert them into a canonical form * before comparing them for equality. + * + * @param other other + * @return equals */ @Override public boolean equals(Object other) { @@ -234,11 +279,21 @@ public boolean equals(Object other) { && Arrays.equals(((Headers) other).namesAndValues, namesAndValues); } + /** + * hashCode + * + * @return hashCode + */ @Override public int hashCode() { return Arrays.hashCode(namesAndValues); } + /** + * toString + * + * @return toString + */ @Override public String toString() { StringBuilder result = new StringBuilder(); @@ -248,6 +303,11 @@ public String toString() { return result.toString(); } + /** + * toMultimap + * + * @return Map> + */ public Map> toMultimap() { Map> result = new TreeMap<>(String.CASE_INSENSITIVE_ORDER); for (int i = 0, size = size(); i < size; i++) { @@ -262,6 +322,9 @@ public Map> toMultimap() { return result; } + /** + * Builder + */ public static final class Builder { final List namesAndValues = new ArrayList<>(20); @@ -282,7 +345,12 @@ Builder addLenient(String line) { } } - /** Add an header line containing a field name, a literal colon, and a value. */ + /** + * Add an header line containing a field name, a literal colon, and a value. + * + * @param line line + * @return Builder + */ public Builder add(String line) { int index = line.indexOf(":"); if (index == -1) { @@ -293,6 +361,10 @@ public Builder add(String line) { /** * Add a header with the specified name and value. Does validation of header names and values. + * + * @param name name + * @param value value + * @return Builder */ public Builder add(String name, String value) { checkNameAndValue(name, value); @@ -301,6 +373,9 @@ public Builder add(String name, String value) { /** * Adds all headers from an existing collection. + * + * @param headers headers + * @return Builder */ public Builder addAll(Headers headers) { int size = headers.size(); @@ -314,6 +389,10 @@ public Builder addAll(Headers headers) { /** * Add a field with the specified value without any validation. Only appropriate for headers * from the remote peer or cache. + * + * @param name name + * @param value value + * @return Builder */ Builder addLenient(String name, String value) { namesAndValues.add(name); @@ -321,6 +400,12 @@ Builder addLenient(String name, String value) { return this; } + /** + * removeAll + * + * @param name name + * @return Builder + */ public Builder removeAll(String name) { for (int i = 0; i < namesAndValues.size(); i += 2) { if (name.equalsIgnoreCase(namesAndValues.get(i))) { @@ -335,6 +420,10 @@ public Builder removeAll(String name) { /** * Set a field with the specified value. If the field is not found, it is added. If the field is * found, the existing values are replaced. + * + * @param name name + * @param value value + * @return Builder */ public Builder set(String name, String value) { checkNameAndValue(name, value); @@ -364,7 +453,12 @@ private void checkNameAndValue(String name, String value) { } } - /** Equivalent to {@code build().get(name)}, but potentially faster. */ + /** + * Equivalent to {@code build().get(name)}, but potentially faster. + * + * @param name name + * @return value + */ public String get(String name) { for (int i = namesAndValues.size() - 2; i >= 0; i -= 2) { if (name.equalsIgnoreCase(namesAndValues.get(i))) { @@ -374,6 +468,11 @@ public String get(String name) { return null; } + /** + * build + * + * @return Headers + */ public Headers build() { return new Headers(this); } diff --git a/library/src/main/java/com/qiniu/android/http/HttpDate.java b/library/src/main/java/com/qiniu/android/http/HttpDate.java index f592fda17..fa836ef03 100644 --- a/library/src/main/java/com/qiniu/android/http/HttpDate.java +++ b/library/src/main/java/com/qiniu/android/http/HttpDate.java @@ -99,7 +99,11 @@ public static Date parse(String value) { return null; } - /** Returns the string for {@code value}. */ + /** + * Returns the string for {@code value}. + * + * @return the string for {@code value}. + */ public static String format(Date value) { return STANDARD_DATE_FORMAT.get().format(value); } diff --git a/library/src/main/java/com/qiniu/android/http/connectCheck/ConnectChecker.java b/library/src/main/java/com/qiniu/android/http/connectCheck/ConnectChecker.java index e36d336a1..7f4228f9d 100644 --- a/library/src/main/java/com/qiniu/android/http/connectCheck/ConnectChecker.java +++ b/library/src/main/java/com/qiniu/android/http/connectCheck/ConnectChecker.java @@ -17,15 +17,29 @@ import java.util.concurrent.ScheduledExecutorService; import java.util.concurrent.TimeUnit; +/** + * 网络连接检查器 + */ public class ConnectChecker { private static ScheduledExecutorService executorService = Executors.newSingleThreadScheduledExecutor(); private static SingleFlight singleFlight = new SingleFlight<>(); + /** + * 根据请求 metrics 判断网络是否正常连接 + * + * @param metrics 请求 metrics + * @return 网络是否正常连接 + */ public static boolean isConnected(UploadSingleRequestMetrics metrics) { return metrics != null && metrics.getResponse() != null && metrics.getResponse().statusCode > 99; } + /** + * 检查网络是否正常连接 + * + * @return 网络是否正常连接 + */ public static UploadSingleRequestMetrics check() { final CheckResult result = new CheckResult(); diff --git a/library/src/main/java/com/qiniu/android/http/dns/Dns.java b/library/src/main/java/com/qiniu/android/http/dns/Dns.java index ecc3f91c6..d19a1b968 100644 --- a/library/src/main/java/com/qiniu/android/http/dns/Dns.java +++ b/library/src/main/java/com/qiniu/android/http/dns/Dns.java @@ -7,5 +7,13 @@ * Created by sxci on 03/04/2018. */ public interface Dns { + + /** + * Dns 解析 host 域名 + * + * @param hostname host 域名 + * @return 解析结果 + * @throws UnknownHostException 异常信息 + */ List lookup(String hostname) throws UnknownHostException; } diff --git a/library/src/main/java/com/qiniu/android/http/dns/DnsCacheFile.java b/library/src/main/java/com/qiniu/android/http/dns/DnsCacheFile.java index 46eed4ddb..e06b55010 100644 --- a/library/src/main/java/com/qiniu/android/http/dns/DnsCacheFile.java +++ b/library/src/main/java/com/qiniu/android/http/dns/DnsCacheFile.java @@ -1,4 +1,5 @@ package com.qiniu.android.http.dns; + import com.qiniu.android.storage.Recorder; import java.io.File; @@ -12,9 +13,22 @@ public class DnsCacheFile implements Recorder { + /** + * dns 缓存路径 + */ public String directory; + + /** + * dns 缓存文件句柄 + */ public File f; + /** + * DnsCacheFile 构造函数 + * + * @param directory dns 缓存路径 + * @throws IOException 异常信息 + */ public DnsCacheFile(String directory) throws IOException { if (directory == null) { throw new IOException("directory invalid"); diff --git a/library/src/main/java/com/qiniu/android/http/dns/DnsCacheInfo.java b/library/src/main/java/com/qiniu/android/http/dns/DnsCacheInfo.java index e9f0133a9..0af6b3ee6 100644 --- a/library/src/main/java/com/qiniu/android/http/dns/DnsCacheInfo.java +++ b/library/src/main/java/com/qiniu/android/http/dns/DnsCacheInfo.java @@ -18,6 +18,12 @@ public class DnsCacheInfo implements java.io.Serializable { private String localIp; private ConcurrentHashMap> info; + /** + * 根据 json 数据构造 DnsCacheInfo + * + * @param jsonData json 数据 + * @return DnsCacheInfo + */ public static DnsCacheInfo createDnsCacheInfoByData(byte[] jsonData) { if (jsonData == null) { return null; @@ -49,7 +55,7 @@ public static DnsCacheInfo createDnsCacheInfoByData(byte[] jsonData) { } catch (Exception ignored) { } - if (currentTime == null || localIp == null || infoMapJSONObject == null){ + if (currentTime == null || localIp == null || infoMapJSONObject == null) { return null; } @@ -62,7 +68,7 @@ public static DnsCacheInfo createDnsCacheInfoByData(byte[] jsonData) { DnsNetworkAddress address = DnsNetworkAddress.address(addressJSONArray.getJSONObject(i)); addressList.add(address); } - if (addressList.size() > 0){ + if (addressList.size() > 0) { info.put(key, addressList); } } catch (Exception ignored) { @@ -72,9 +78,19 @@ public static DnsCacheInfo createDnsCacheInfoByData(byte[] jsonData) { return new DnsCacheInfo(currentTime, localIp, info); } + /** + * 构造方法 + */ public DnsCacheInfo() { } + /** + * 构造方法 + * + * @param currentTime 当前时间 + * @param localIp 本地 IP + * @param info DNS 缓存数据 + */ public DnsCacheInfo(String currentTime, String localIp, ConcurrentHashMap> info) { this.currentTime = currentTime; this.localIp = localIp; @@ -89,6 +105,11 @@ String getLocalIp() { return localIp; } + /** + * 获取缓存数据 + * + * @return 缓存数据 + */ public ConcurrentHashMap> getInfo() { return info; } @@ -101,14 +122,29 @@ void setLocalIp(String localIp) { this.localIp = localIp; } + /** + * 设置缓存数据 + * + * @param info 缓存数据 + */ public void setInfo(ConcurrentHashMap> info) { this.info = info; } + /** + * 获取缓存的 key + * + * @return 缓存的 key + */ public String cacheKey() { return localIp; } + /** + * 获取缓存的 json byte 数据 + * + * @return 缓存的 json byte 数据 + */ public byte[] toJsonData() { JSONObject cacheInfoJSONObject = new JSONObject(); try { @@ -150,6 +186,11 @@ public byte[] toJsonData() { return cacheInfoJSONObject.toString().getBytes(); } + /** + * toString + * + * @return String 信息 + */ @Override public String toString() { return "{\"currentTime\":\"" + currentTime + "\", \"localIp\":\"" + localIp + "\"}"; diff --git a/library/src/main/java/com/qiniu/android/http/dns/DnsPrefetchTransaction.java b/library/src/main/java/com/qiniu/android/http/dns/DnsPrefetchTransaction.java index d2c9b664e..e93f11728 100644 --- a/library/src/main/java/com/qiniu/android/http/dns/DnsPrefetchTransaction.java +++ b/library/src/main/java/com/qiniu/android/http/dns/DnsPrefetchTransaction.java @@ -11,6 +11,11 @@ public class DnsPrefetchTransaction { private static boolean isDnsLoaded = false; + /** + * 将 SDK 内部使用域名的 Dns 预解析操作添加到周期性的事务中 + * + * @return 添加是否成功 + */ public static synchronized boolean addDnsLocalLoadTransaction() { if (isDnsLoaded) { return false; @@ -33,7 +38,13 @@ public void run() { return true; } - + /** + * 将 zone 中使用域名的 Dns 预解析操作添加到周期性的事务中 + * + * @param currentZone zone + * @param token 上传 token + * @return 添加是否成功 + */ public static synchronized boolean addDnsCheckAndPrefetchTransaction(final Zone currentZone, final UpToken token) { if (!DnsPrefetcher.getInstance().isDnsOpen()) { return false; @@ -58,6 +69,12 @@ public void run() { return true; } + /** + * 将 hosts 中域名的 Dns 预解析操作添加到周期性的事务中 + * + * @param hosts 域名 + * @return 添加是否成功 + */ public static synchronized boolean addDnsCheckAndPrefetchTransaction(final String[] hosts) { if (!DnsPrefetcher.getInstance().isDnsOpen()) { return false; @@ -78,7 +95,11 @@ public void run() { return true; } - + /** + * 将检查缓存是否有效的操作添加到周期性事务中，无效则重新拉取 + * + * @return 添加是否成功 + */ public static synchronized boolean setDnsCheckWhetherCachedValidTransactionAction() { if (!DnsPrefetcher.getInstance().isDnsOpen()) { return false; diff --git a/library/src/main/java/com/qiniu/android/http/dns/DnsPrefetcher.java b/library/src/main/java/com/qiniu/android/http/dns/DnsPrefetcher.java index 433b2db78..ec355d371 100644 --- a/library/src/main/java/com/qiniu/android/http/dns/DnsPrefetcher.java +++ b/library/src/main/java/com/qiniu/android/http/dns/DnsPrefetcher.java @@ -40,12 +40,25 @@ private DnsPrefetcher() { systemDns = new SystemDns(GlobalConfiguration.getInstance().dnsResolveTimeout); } + /** + * 获取 DnsPrefetcher 单例 + * + * @return DnsPrefetcher 单例 + */ public static DnsPrefetcher getInstance() { return dnsPrefetcher; } + /** + * Dns 解析的最后一次异常信息 + */ public String lastPrefetchErrorMessage; + /** + * 从本地恢复缓存信息 + * + * @return 是否恢复成功 + */ public boolean recoverCache() { DnsCacheFile recorder = getDiskCache(); @@ -66,14 +79,30 @@ public boolean recoverCache() { return recoverDnsCache(data); } + /** + * 对 SDK 默认使用的域名进行 Dns 解析 + */ public void localFetch() { addPreFetchHosts(getLocalPreHost()); } + /** + * 周期性的对 Zone 内的域名进行 Dns 解析 + * + * @param currentZone zone + * @param token 上传 Token + * @return 是否配置成功 + */ public boolean checkAndPrefetchDnsIfNeed(Zone currentZone, UpToken token) { return addPreFetchHosts(getCurrentZoneHosts(currentZone, token)); } + /** + * 周期性的对 hosts 进行 Dns 解析 + * + * @param hosts 域名 + * @return 是否配置成功 + */ public boolean addPreFetchHosts(String[] hosts) { if (hosts == null) { return false; @@ -98,6 +127,11 @@ public boolean addPreFetchHosts(String[] hosts) { } } + /** + * 将内存中 address 对应的缓存设置为无效 + * + * @param address host dns 解析记录 + */ public void invalidNetworkAddress(IDnsNetworkAddress address) { if (address == null || address.getHostValue() == null) { return; @@ -125,6 +159,12 @@ private void invalidNetworkAddressOfHost(String host) { addressDictionary.remove(host); } + /** + * 获取 host 的 Dns 预解析结果 + * + * @param host 域名 + * @return Dns 预解析结果 + */ public List getInetAddressByHost(String host) { if (!isDnsOpen()) { return null; @@ -141,6 +181,13 @@ public List getInetAddressByHost(String host) { return null; } + /** + * 通过安全的 Dns 解析对 host 进行预解析并返回解析的方式 + * + * @param hostname 域名 + * @return 解析的方式 + * @throws UnknownHostException 异常信息 + */ public String lookupBySafeDns(String hostname) throws UnknownHostException { if (hostname == null || hostname.length() == 0) { return null; @@ -173,11 +220,19 @@ public String lookupBySafeDns(String hostname) throws UnknownHostException { return null; } + /** + * 清除 Dns 解析缓存 + * + * @throws IOException 异常信息 + */ public void clearDnsCache() throws IOException { clearMemoryCache(); clearDiskCache(); } + /** + * 检查 Host Dns 预解析的缓存信息是否有效 + */ public void checkWhetherCachedDnsValid() { if (!prepareToPreFetch()) { return; @@ -358,10 +413,18 @@ private boolean recorderDnsCache() { return true; } + /** + * 清除内存缓存 + */ public void clearMemoryCache() { addressDictionary.clear(); } + /** + * 清除磁盘缓存 + * + * @throws IOException 异常信息 + */ public void clearDiskCache() throws IOException { DnsCacheFile recorder = getDiskCache(); if (recorder == null) { @@ -407,10 +470,19 @@ private String[] getCacheHosts() { return prefetchHosts.toArray(new String[0]); } + /** + * 获取 Dns 配置是否打开 + * @return Dns 配置是否打开 + */ public boolean isDnsOpen() { return GlobalConfiguration.getInstance().isDnsOpen; } + /** + * 获取是否正在进行 Dns 预解析操作 + * + * @return 是否正在进行 Dns 预解析操作 + */ public synchronized boolean isPrefetching() { return isPrefetching; } diff --git a/library/src/main/java/com/qiniu/android/http/dns/DnsSource.java b/library/src/main/java/com/qiniu/android/http/dns/DnsSource.java index 3f502363f..8640d3858 100644 --- a/library/src/main/java/com/qiniu/android/http/dns/DnsSource.java +++ b/library/src/main/java/com/qiniu/android/http/dns/DnsSource.java @@ -1,29 +1,86 @@ package com.qiniu.android.http.dns; +/** + * Dns 解析源 + */ public class DnsSource { + + /** + * Doh 解析源 + */ public static final String Doh = "doh"; + + /** + * udp 方式的解析源 + */ public static final String Udp = "dns"; + + /** + * DnsPod 解析源 + */ public static final String Dnspod = "dnspod"; + + /** + * System 解析源 + */ public static final String System = "system"; + + /** + * 自定义解析源 + */ public static final String Custom = "customized"; + + /** + * 未知解析源 + */ public static final String None = "none"; + /** + * 判断解析源是否为 Doh + * + * @param source 解析源 + * @return 解析源是否为 Doh + */ public static boolean isDoh(String source) { return source != null && source.contains(Doh); } + /** + * 判断解析源是否为 Udp + * + * @param source 解析源 + * @return 解析源是否为 Udp + */ public static boolean isUdp(String source) { return source != null && source.contains(Udp); } + /** + * 判断解析源是否为 DnsPod + * + * @param source 解析源 + * @return 解析源是否为 DnsPod + */ public static boolean isDnspod(String source) { return source != null && source.contains(Dnspod); } + /** + * 判断解析源是否为系统的 + * + * @param source 解析源 + * @return 解析源是否为系统的 + */ public static boolean isSystem(String source) { return source != null && source.contains(System); } + /** + * 判断解析源是否为自定义的 + * + * @param source 解析源 + * @return 解析源是否为自定义的 + */ public static boolean isCustom(String source) { return source != null && source.contains(Custom); } diff --git a/library/src/main/java/com/qiniu/android/http/dns/HappyDns.java b/library/src/main/java/com/qiniu/android/http/dns/HappyDns.java index ae1d72953..548bab967 100644 --- a/library/src/main/java/com/qiniu/android/http/dns/HappyDns.java +++ b/library/src/main/java/com/qiniu/android/http/dns/HappyDns.java @@ -18,13 +18,16 @@ public class HappyDns implements Dns { private DnsQueryErrorHandler errorHandler; - public HappyDns(){ + /** + * 构造函数 + */ + public HappyDns() { int dnsTimeout = GlobalConfiguration.getInstance().dnsResolveTimeout; systemDns = new SystemDns(dnsTimeout); customDns = GlobalConfiguration.getInstance().dns; } - void setQueryErrorHandler(DnsQueryErrorHandler handler){ + void setQueryErrorHandler(DnsQueryErrorHandler handler) { errorHandler = handler; } diff --git a/library/src/main/java/com/qiniu/android/http/dns/IDnsNetworkAddress.java b/library/src/main/java/com/qiniu/android/http/dns/IDnsNetworkAddress.java index a0a44909e..a743ce3f9 100644 --- a/library/src/main/java/com/qiniu/android/http/dns/IDnsNetworkAddress.java +++ b/library/src/main/java/com/qiniu/android/http/dns/IDnsNetworkAddress.java @@ -1,19 +1,43 @@ package com.qiniu.android.http.dns; +/** + * Dns 预解析信息 + */ public interface IDnsNetworkAddress { - /// 域名 + + /** + * 预解析的域名 + * + * @return 预解析的域名 + */ String getHostValue(); - /// 地址IP信息 + /** + * 预解析域名的 IP 信息 + * + * @return 预解析域名的 IP 信息 + */ String getIpValue(); - /// ip有效时间 单位：秒 + /** + * 预解析域名的 IP 有效时间 单位：秒 + * + * @return 预解析域名的 IP 有效时间 + */ Long getTtlValue(); - /// ip预取来源, 自定义dns返回 "customized" + /** + * 预解析的源，自定义dns返回 "customized" + * + * @return 预解析的源 + */ String getSourceValue(); - /// 解析到host时的时间戳 单位：秒 + /** + * 解析到 host 时的时间戳，单位：秒 + * + * @return 解析到 host 时的时间戳 + */ Long getTimestampValue(); } diff --git a/library/src/main/java/com/qiniu/android/http/request/IRequestClient.java b/library/src/main/java/com/qiniu/android/http/request/IRequestClient.java index a640501ce..8088a3532 100644 --- a/library/src/main/java/com/qiniu/android/http/request/IRequestClient.java +++ b/library/src/main/java/com/qiniu/android/http/request/IRequestClient.java @@ -6,33 +6,94 @@ import org.json.JSONObject; - +/** + * 请求 Client 抽象 + */ public abstract class IRequestClient { + /** + * 请求进度协议 + */ public interface Progress { + + /** + * 请求进度回调 + * + * @param totalBytesWritten totalBytesWritten + * @param totalBytesExpectedToWrite totalBytesExpectedToWrite + */ void progress(long totalBytesWritten, long totalBytesExpectedToWrite); } + /** + * 请求完成回调 + */ public interface CompleteHandler { + + /** + * 请求完成回调 + * + * @param responseInfo 请求响应信息 + * @param metrics 请求指标 + * @param response 请求响应信息 + */ void complete(ResponseInfo responseInfo, UploadSingleRequestMetrics metrics, JSONObject response); } + /** + * 触发请求 + * + * @param request 请求信息 + * @param options 可选信息 + * @param progress 进度回调 + * @param complete 完成回调 + */ public abstract void request(Request request, Options options, Progress progress, CompleteHandler complete); + /** + * 取消 + */ public abstract void cancel(); + /** + * 获取 ClientId + * + * @return ClientId + */ public String getClientId() { return "customized"; } + /** + * 可选信息 + */ public static class Options { + + /** + * 上传请求的 Server + */ public final IUploadServer server; + + /** + * 是否使用异步 + */ public final boolean isAsync; + + /** + * 请求的代理 + */ public final ProxyConfiguration connectionProxy; + /** + * 构造函数 + * + * @param server 上传请求的 Server + * @param isAsync 是否使用异步 + * @param connectionProxy 请求的代理 + */ public Options(IUploadServer server, boolean isAsync, ProxyConfiguration connectionProxy) { this.server = server; this.isAsync = isAsync; diff --git a/library/src/main/java/com/qiniu/android/http/request/IUploadRegion.java b/library/src/main/java/com/qiniu/android/http/request/IUploadRegion.java index f9f595928..5730a0972 100644 --- a/library/src/main/java/com/qiniu/android/http/request/IUploadRegion.java +++ b/library/src/main/java/com/qiniu/android/http/request/IUploadRegion.java @@ -3,17 +3,54 @@ import com.qiniu.android.common.ZoneInfo; import com.qiniu.android.http.ResponseInfo; +/** + * 上传区域仇晓 + */ public interface IUploadRegion { + /** + * 是否有效 + * + * @return 是否有效 + */ boolean isValid(); + /** + * 是否和另一个 region 相等 + * + * @param region 另一个 region + * @return 是否和另一个 region 相等 + */ boolean isEqual(IUploadRegion region); + /** + * 获取 ZoneInfo + * + * @return ZoneInfo + */ ZoneInfo getZoneInfo(); + /** + * 配置 ZoneInfo + * + * @param zoneInfo ZoneInfo + */ void setupRegionData(ZoneInfo zoneInfo); + /** + * 获取下一个上传的 Server 信息 + * + * @param requestState 请求状态 + * @param responseInfo 请求响应信息 + * @param freezeServer 冻结的 Server 信息 + * @return 下一个上传的 Server 信息 + */ IUploadServer getNextServer(UploadRequestState requestState, ResponseInfo responseInfo, IUploadServer freezeServer); + /** + * 更新 host 的 IP 缓存信息 + * + * @param host host + */ void updateIpListFormHost(String host); } diff --git a/library/src/main/java/com/qiniu/android/http/request/IUploadServer.java b/library/src/main/java/com/qiniu/android/http/request/IUploadServer.java index f712a705c..b39f314ff 100644 --- a/library/src/main/java/com/qiniu/android/http/request/IUploadServer.java +++ b/library/src/main/java/com/qiniu/android/http/request/IUploadServer.java @@ -3,11 +3,30 @@ import java.net.InetAddress; +/** + * upload server 信息 + */ public abstract class IUploadServer { + + /** + * HTTP/1.1 + */ public static String HttpVersion1 = "http_version_1"; + + /** + * HTTP/2 + */ public static String HttpVersion2 = "http_version_2"; + + /** + * HTTP/3 + */ public static String HttpVersion3 = "http_version_3"; + /** + * 是否使用 HTTP/3 + * @return 是否使用 HTTP/3 + */ public boolean isHttp3() { String httpVersion = getHttpVersion(); if (httpVersion == null) { @@ -16,6 +35,10 @@ public boolean isHttp3() { return httpVersion.equals(IUploadServer.HttpVersion3); } + /** + * 是否使用 HTTP/2 + * @return 是否使用 HTTP/2 + */ public boolean isHttp2() { String httpVersion = getHttpVersion(); if (httpVersion == null) { @@ -24,18 +47,46 @@ public boolean isHttp2() { return httpVersion.equals(IUploadServer.HttpVersion2); } + /** + * 获取 ServerId + * @return ServerId + */ public abstract String getServerId(); + /** + * 获取 HttpVersion + * @return HttpVersion + */ public abstract String getHttpVersion(); + /** + * 获取 Host + * @return Host + */ public abstract String getHost(); + /** + * 获取 IP + * @return IP + */ public abstract String getIp(); + /** + * 获取 DNS 解析 Source + * @return DNS 解析 Source + */ public abstract String getSource(); + /** + * 获取 DNS 解析时间戳 + * @return DNS 解析时间戳 + */ public abstract Long getIpPrefetchedTime(); + /** + * 获取 DNS 解析信息 + * @return DNS 解析信息 + */ public InetAddress getInetAddress(){ String ip = getIp(); String host = getHost(); diff --git a/library/src/main/java/com/qiniu/android/http/request/handler/CheckCancelHandler.java b/library/src/main/java/com/qiniu/android/http/request/handler/CheckCancelHandler.java index cabda10d7..43e333db2 100644 --- a/library/src/main/java/com/qiniu/android/http/request/handler/CheckCancelHandler.java +++ b/library/src/main/java/com/qiniu/android/http/request/handler/CheckCancelHandler.java @@ -1,5 +1,14 @@ package com.qiniu.android.http.request.handler; +/** + * CheckCancelHandler + */ public interface CheckCancelHandler { + + /** + * 查看是否取消 + * + * @return 是否取消 + */ boolean checkCancel(); } diff --git a/library/src/main/java/com/qiniu/android/http/request/httpclient/ByteBody.java b/library/src/main/java/com/qiniu/android/http/request/httpclient/ByteBody.java index 4e9a7de3f..1c9a18fc5 100644 --- a/library/src/main/java/com/qiniu/android/http/request/httpclient/ByteBody.java +++ b/library/src/main/java/com/qiniu/android/http/request/httpclient/ByteBody.java @@ -12,13 +12,18 @@ */ public class ByteBody extends RequestBody { - private static final int SEGMENT_SIZE = 1024*16; // okio.Segment.SIZE + private static final int SEGMENT_SIZE = 1024 * 16; // okio.Segment.SIZE private final MediaType mediaType; private final byte[] body; - public ByteBody(MediaType mediaType, - byte[] body){ + /** + * 请求体 + * + * @param mediaType mediaType + * @param body 请求体 byte 数组 + */ + public ByteBody(MediaType mediaType, byte[] body) { this.mediaType = mediaType; this.body = body; @@ -39,7 +44,7 @@ public void writeTo(BufferedSink bufferedSink) throws IOException { int byteOffset = 0; int byteSize = SEGMENT_SIZE; - while (byteOffset < body.length){ + while (byteOffset < body.length) { byteSize = Math.min(byteSize, body.length - byteOffset); RequestBody requestBody = getRequestBodyWithRange(byteOffset, byteSize); requestBody.writeTo(bufferedSink); @@ -50,7 +55,7 @@ public void writeTo(BufferedSink bufferedSink) throws IOException { } - private RequestBody getRequestBodyWithRange(int location, int size){ + private RequestBody getRequestBodyWithRange(int location, int size) { byte[] data = Arrays.copyOfRange(body, location, location + size); return RequestBody.create(contentType(), data); } diff --git a/library/src/main/java/com/qiniu/android/http/request/httpclient/CountingRequestBody.java b/library/src/main/java/com/qiniu/android/http/request/httpclient/CountingRequestBody.java index e7e546ee1..fcd3e96ed 100644 --- a/library/src/main/java/com/qiniu/android/http/request/httpclient/CountingRequestBody.java +++ b/library/src/main/java/com/qiniu/android/http/request/httpclient/CountingRequestBody.java @@ -26,6 +26,14 @@ public final class CountingRequestBody extends RequestBody { private final long totalSize; private final CancellationHandler cancellationHandler; + /** + * CountingRequestBody 构造函数 + * + * @param body 请求体 + * @param progress 请求进度回调 + * @param totalSize 请求体总大小 + * @param cancellationHandler 取消函数 + */ public CountingRequestBody(RequestBody body, ProgressHandler progress, long totalSize, CancellationHandler cancellationHandler) { this.body = body; @@ -34,16 +42,33 @@ public CountingRequestBody(RequestBody body, ProgressHandler progress, long tota this.cancellationHandler = cancellationHandler; } + /** + * 获取请求体大小 + * + * @return 请求体大小 + * @throws IOException 异常 + */ @Override public long contentLength() throws IOException { return body.contentLength(); } + /** + * 获取请求 ContentType + * + * @return 请求 ContentType + */ @Override public MediaType contentType() { return body.contentType(); } + /** + * 写入数据 + * + * @param sink BufferedSink + * @throws IOException 异常 + */ @Override public void writeTo(BufferedSink sink) throws IOException { BufferedSink bufferedSink; @@ -56,14 +81,29 @@ public void writeTo(BufferedSink sink) throws IOException { bufferedSink.flush(); } + /** + * 请求进度 Sink + */ protected final class CountingSink extends ForwardingSink { private int bytesWritten = 0; + /** + * 构造方法 + * + * @param delegate Sink + */ public CountingSink(Sink delegate) { super(delegate); } + /** + * 写入数据 + * + * @param source Buffer + * @param byteCount byteCount + * @throws IOException 异常 + */ @Override public void write(Buffer source, long byteCount) throws IOException { if (cancellationHandler == null && progress == null) { diff --git a/library/src/main/java/com/qiniu/android/http/serverRegion/HttpServerManager.java b/library/src/main/java/com/qiniu/android/http/serverRegion/HttpServerManager.java index 2bf54a65b..631fec727 100644 --- a/library/src/main/java/com/qiniu/android/http/serverRegion/HttpServerManager.java +++ b/library/src/main/java/com/qiniu/android/http/serverRegion/HttpServerManager.java @@ -5,19 +5,29 @@ import java.util.Locale; import java.util.concurrent.ConcurrentHashMap; +/** + * HttpServerManager + */ public class HttpServerManager { private ConcurrentHashMap serversInfo = new ConcurrentHashMap<>(); private final static HttpServerManager manager = new HttpServerManager(); + /** + * 单例对象 + * + * @return 单例对象 + */ public static HttpServerManager getInstance() { return manager; } /** * 添加支持 http3 的 Host/ip 组合 - * @param host 支持 http3 的 Host - * @param ip 支持 http3 Host 对应的 ip + * + * @param host 支持 http3 的 Host + * @param ip 支持 http3 Host 对应的 ip * @param liveDuration 有效时间 单位: 秒 + * @return 是否添加 */ public boolean addHttp3Server(String host, String ip, int liveDuration) { if (host == null || host.length() == 0 || ip == null || ip.length() == 0 || liveDuration < 0) { @@ -32,8 +42,10 @@ public boolean addHttp3Server(String host, String ip, int liveDuration) { /** * Host/ip 组合是否支持 http3 + * * @param host host - * @param ip ip + * @param ip ip + * @return 否支持 http3 */ public boolean isServerSupportHttp3(String host, String ip) { if (host == null || host.length() == 0 || ip == null || ip.length() == 0) { diff --git a/library/src/main/java/com/qiniu/android/storage/Configuration.java b/library/src/main/java/com/qiniu/android/storage/Configuration.java index cd4aa651b..cbcfbffdf 100644 --- a/library/src/main/java/com/qiniu/android/storage/Configuration.java +++ b/library/src/main/java/com/qiniu/android/storage/Configuration.java @@ -8,6 +8,9 @@ import java.io.File; +/** + * 上传配置信息 + */ public final class Configuration { /** @@ -179,6 +182,9 @@ public String gen(String key, String sourceId) { return keyGen; } + /** + * Configuration Builder + */ public static class Builder { private IRequestClient requestClient = null; private Zone zone = null; @@ -190,7 +196,7 @@ public static class Builder { private int chunkSize = 2 * 1024 * 1024; private int putThreshold = 4 * 1024 * 1024; private int connectTimeout = 10; - private int writeTimeout = 30; + private int writeTimeout = 30; private int responseTimeout = 10; private int retryMax = 1; private int retryInterval = 500; @@ -200,97 +206,212 @@ public static class Builder { private int resumeUploadVersion = RESUME_UPLOAD_VERSION_V1; private int concurrentTaskCount = 3; + /** + * Builder 构造方法 + * + * @param requestClient 请求的客户端 + * @return Builder + */ public Builder requestClient(IRequestClient requestClient) { this.requestClient = requestClient; return this; } + /** + * 配置请求的 Zone + * + * @param zone 请求的 Zone + * @return Builder + */ public Builder zone(Zone zone) { this.zone = zone; return this; } + /** + * 配置上传的 Recorder，Recorder 可以记录上传的进度，使上传支持断点续传 + * + * @param recorder 请求的 Recorder + * @return Builder + */ public Builder recorder(Recorder recorder) { this.recorder = recorder; return this; } + /** + * 配置上传的 Recorder，Recorder 可以记录上传的进度，使上传支持断点续传 + * + * @param recorder 请求的 Recorder + * @param keyGen 上传记录 key 的生成器 + * @return Builder + */ public Builder recorder(Recorder recorder, KeyGenerator keyGen) { this.recorder = recorder; this.keyGen = keyGen; return this; } + /** + * 配置请求的 ProxyConfiguration + * + * @param proxy 请求的代理配置 + * @return Builder + */ public Builder proxy(ProxyConfiguration proxy) { this.proxy = proxy; return this; } + /** + * 配置分片上传时的分片大小 + * + * @param size 分片大小，单位：B + * @return Builder + */ public Builder chunkSize(int size) { this.chunkSize = size; return this; } + /** + * 配置分片上传的阈值，大于此值会使用分片上传，小于等于此值会使用表单上传 + * + * @param size 阈值，单位：B + * @return Builder + */ public Builder putThreshold(int size) { this.putThreshold = size; return this; } + /** + * 配置请求建立连接的超时时间 + * + * @param timeout 超时时间，单位：秒 + * @return Builder + */ public Builder connectTimeout(int timeout) { this.connectTimeout = timeout; return this; } + /** + * 配置请求发送数据的超时时间 + * + * @param timeout 超时时间，单位：秒 + * @return Builder + */ public Builder writeTimeout(int timeout) { this.writeTimeout = timeout; return this; } + /** + * 配置请求接收数据的超时时间 + * + * @param timeout 超时时间，单位：秒 + * @return Builder + */ public Builder responseTimeout(int timeout) { this.responseTimeout = timeout; return this; } + /** + * 配置请求单个域名最大的重试次数，一个上传请求可能会有多个主备域名 + * + * @param times 请求单个域名最大的重试次数 + * @return Builder + */ public Builder retryMax(int times) { this.retryMax = times; return this; } + /** + * 配置请求重试时间间隔 + * + * @param retryInterval 请求重试时间间隔，单位：秒 + * @return Builder + */ public Builder retryInterval(int retryInterval) { this.retryInterval = retryInterval; return this; } + /** + * 配置是否允许使用备用域名，如果不允许则仅会使用一个域名进行上传 + * 注：如果配置为 false 可能会影响上传的成功率 + * + * @param isAllow 是否允许使用备用域名 + * @return Builder + */ public Builder allowBackupHost(boolean isAllow) { this.allowBackupHost = isAllow; return this; } + /** + * 配置请求 Url 的拦截器 + * + * @param converter 请求 Url 的拦截器 + * @return Builder + */ public Builder urlConverter(UrlConverter converter) { this.urlConverter = converter; return this; } + /** + * 配置上传是否允许使用并发分片方式 + * + * @param useConcurrentResumeUpload 上传是否允许使用并发分片方式 + * @return Builder + */ public Builder useConcurrentResumeUpload(boolean useConcurrentResumeUpload) { this.useConcurrentResumeUpload = useConcurrentResumeUpload; return this; } + /** + * 配置分片上传的版本 + * + * @param resumeUploadVersion 分片上传的版本 + * @return Builder + */ public Builder resumeUploadVersion(int resumeUploadVersion) { this.resumeUploadVersion = resumeUploadVersion; return this; } + /** + * 配置分片上传的并发度 + * + * @param concurrentTaskCount 分片上传的并发度 + * @return Builder + */ public Builder concurrentTaskCount(int concurrentTaskCount) { this.concurrentTaskCount = concurrentTaskCount; return this; } + /** + * 配置是否使用 HTTP 请求 + * + * @param useHttps 是否使用 HTTP 请求 + * @return Builder + */ public Builder useHttps(boolean useHttps) { this.useHttps = useHttps; return this; } + /** + * 生成 Configuration + * + * @return Configuration + */ public Configuration build() { return new Configuration(this); } diff --git a/library/src/main/java/com/qiniu/android/storage/FileRecorder.java b/library/src/main/java/com/qiniu/android/storage/FileRecorder.java index 0566e998b..1abb03c0c 100644 --- a/library/src/main/java/com/qiniu/android/storage/FileRecorder.java +++ b/library/src/main/java/com/qiniu/android/storage/FileRecorder.java @@ -18,8 +18,17 @@ */ public final class FileRecorder implements Recorder { + /** + * 记录路径 + */ public String directory; + /** + * 构造方法 + * + * @param directory 记录路径 + * @throws IOException 异常 + */ public FileRecorder(String directory) throws IOException { this.directory = directory; File f = new File(directory); @@ -129,6 +138,9 @@ public void del(String key) { f.delete(); } + /** + * 删除所有路径 + */ public void deleteAll() { try { File folder = new File(directory); @@ -157,6 +169,11 @@ private void deleteDirectoryLegacyIO(File file) { file.delete(); } + /** + * 获取文件名 + * + * @return 文件名 + */ @Override public String getFileName() { return null; diff --git a/library/src/main/java/com/qiniu/android/storage/GlobalConfiguration.java b/library/src/main/java/com/qiniu/android/storage/GlobalConfiguration.java index 8154e83b2..e771c2574 100644 --- a/library/src/main/java/com/qiniu/android/storage/GlobalConfiguration.java +++ b/library/src/main/java/com/qiniu/android/storage/GlobalConfiguration.java @@ -10,6 +10,9 @@ import org.json.JSONException; import org.json.JSONObject; +/** + * 上传全局配置 + */ public class GlobalConfiguration { /** @@ -198,6 +201,11 @@ public String[] getDohIpv4Servers() { } } + /** + * 获取 Doh 方式进行 Dns 预解析使用的 Server + * + * @return Server 列表 + */ public String[] getDohIpv6Servers() { if (dohIpv6Servers != null) { return dohIpv6Servers; @@ -206,6 +214,11 @@ public String[] getDohIpv6Servers() { } } + /** + * 获取网络状态检测使用的 Url + * + * @return Url 列表 + */ public String[] getConnectCheckUrls() { if (connectCheckURLStrings != null) { return connectCheckURLStrings; @@ -214,6 +227,11 @@ public String[] getConnectCheckUrls() { } } + /** + * 解析 Base64 数据为字符串数组 + * + * @return 字符串数组 + */ public static String[] parseBase64Array(String data) { try { byte[] jsonBytes = UrlSafeBase64.decode(data); diff --git a/library/src/main/java/com/qiniu/android/storage/Recorder.java b/library/src/main/java/com/qiniu/android/storage/Recorder.java index 9bd218cb2..4620d3117 100644 --- a/library/src/main/java/com/qiniu/android/storage/Recorder.java +++ b/library/src/main/java/com/qiniu/android/storage/Recorder.java @@ -28,5 +28,10 @@ public interface Recorder { */ void del(String key); + /** + * 获取记录的文件名 + * + * @return 记录的文件名 + */ String getFileName(); } diff --git a/library/src/main/java/com/qiniu/android/storage/UploadManager.java b/library/src/main/java/com/qiniu/android/storage/UploadManager.java index 4bfd91af9..c08c6944a 100644 --- a/library/src/main/java/com/qiniu/android/storage/UploadManager.java +++ b/library/src/main/java/com/qiniu/android/storage/UploadManager.java @@ -174,7 +174,7 @@ public void put(final InputStream inputStream, } /** - * 同步上传文件。使用 form 表单方式上传，建议只在数据较小情况下使用此方式，如 file.size() < 1024 * 1024。 + * 同步上传文件。使用 form 表单方式上传，建议只在数据较小情况下使用此方式，如 file.size() 小于 1024 * 1024。 * 注：切勿在主线程调用 * * @param data 上传的数据 @@ -215,7 +215,7 @@ public void complete(String key, ResponseInfo info, JSONObject response) { } /** - * 同步上传文件。使用 form 表单方式上传，建议只在文件较小情况下使用此方式，如 file.size() < 1024 * 1024。 + * 同步上传文件。使用 form 表单方式上传，建议只在文件较小情况下使用此方式，如 file.size() 小于 1024 * 1024。 * 注：切勿在主线程调用 * * @param file 上传的文件绝对路径 @@ -229,7 +229,7 @@ public ResponseInfo syncPut(String file, String key, String token, UploadOptions } /** - * 同步上传文件。使用 form 表单方式上传，建议只在文件较小情况下使用此方式，如 file.size() < 1024 * 1024。 + * 同步上传文件。使用 form 表单方式上传，建议只在文件较小情况下使用此方式，如 file.size() 小于 1024 * 1024。 * 注：切勿在主线程调用 * * @param file 上传的文件对象 @@ -243,7 +243,7 @@ public ResponseInfo syncPut(File file, String key, String token, UploadOptions o } /** - * 同步上传文件。使用 form 表单方式上传，建议只在文件较小情况下使用此方式，如 file.size() < 1024 * 1024。 + * 同步上传文件。使用 form 表单方式上传，建议只在文件较小情况下使用此方式，如 file.size() 小于 1024 * 1024。 * 注：切勿在主线程调用 * * @param uri 上传的文件对象 Uri @@ -265,7 +265,7 @@ public ResponseInfo syncPut(Uri uri, } /** - * 同步上传文件。使用 form 表单方式上传，建议只在文件较小情况下使用此方式，如 file.size() < 1024 * 1024。 + * 同步上传文件。使用 form 表单方式上传，建议只在文件较小情况下使用此方式，如 file.size() 小于 1024 * 1024。 * 注：切勿在主线程调用 * * @param inputStream 上传的资源流 diff --git a/library/src/main/java/com/qiniu/android/utils/AndroidNetwork.java b/library/src/main/java/com/qiniu/android/utils/AndroidNetwork.java index 6d8390794..c321d8de2 100644 --- a/library/src/main/java/com/qiniu/android/utils/AndroidNetwork.java +++ b/library/src/main/java/com/qiniu/android/utils/AndroidNetwork.java @@ -28,6 +28,12 @@ * Created by bailong on 16/9/7. */ public final class AndroidNetwork { + + /** + * 网络是否正常连接 + * + * @return 网络是否连接 + */ public static boolean isNetWorkReady() { Context c = ContextGetter.applicationContext(); if (c == null) { @@ -48,7 +54,7 @@ public static boolean isNetWorkReady() { * 使用DNS解析某地址时，可能会同时返回IPv4和IPv6的地址。 * 如果同时拥有IPv4和IPv6的地址，是会默认优先上报IPv6的地址 * - * @return + * @return IP */ public static String getHostIP() { String hostIp = null; @@ -77,6 +83,18 @@ public static String getHostIP() { return hostIp; } + /** + * 网络类型 + * {@link Constants#NETWORK_CLASS_UNKNOWN} + * {@link Constants#NETWORK_WIFI} + * {@link Constants#NETWORK_CLASS_2_G} + * {@link Constants#NETWORK_CLASS_3_G} + * {@link Constants#NETWORK_CLASS_4_G} + * ... + * + * @param context context + * @return 网络类型 + */ public static String networkType(Context context) { try { return networkTypeWithException(context); @@ -87,7 +105,7 @@ public static String networkType(Context context) { } private static String networkTypeWithException(Context context) throws Exception { - if (context == null){ + if (context == null) { return Constants.NETWORK_CLASS_UNKNOWN; } @@ -116,7 +134,7 @@ private static String getNetWorkClass(Context context) { } TelephonyManager telephonyManager = (TelephonyManager) context.getSystemService(Context.TELEPHONY_SERVICE); - if (telephonyManager == null){ + if (telephonyManager == null) { return Constants.NETWORK_CLASS_UNKNOWN; } diff --git a/library/src/main/java/com/qiniu/android/utils/AsyncRun.java b/library/src/main/java/com/qiniu/android/utils/AsyncRun.java index a55e868f1..e37e1a3b1 100644 --- a/library/src/main/java/com/qiniu/android/utils/AsyncRun.java +++ b/library/src/main/java/com/qiniu/android/utils/AsyncRun.java @@ -25,8 +25,13 @@ public final class AsyncRun { 1000L, TimeUnit.MILLISECONDS, new LinkedBlockingQueue()); + /** + * 主线程执行任务 + * + * @param r 执行体 + */ public static void runInMain(Runnable r) { - if (Looper.getMainLooper() == Looper.myLooper()){ + if (Looper.getMainLooper() == Looper.myLooper()) { r.run(); } else { mainThreadHandler.post(r); @@ -34,10 +39,12 @@ public static void runInMain(Runnable r) { } /** - * delay: delay in milliseconds before task is to be executed. + * 延迟执行任务 + * + * @param delay 延迟执行时间，单位：ms + * @param r 执行体 */ - public static void runInMain(int delay, - final Runnable r){ + public static void runInMain(int delay, final Runnable r) { delayTimerTask(delay, new TimerTask() { @Override @@ -48,15 +55,22 @@ public void run() { }); } + /** + * 后台执行任务 + * + * @param r 执行体 + */ public static void runInBack(Runnable r) { executorService.submit(r); } /** - * delay: delay in milliseconds before task is to be executed. + * 延迟执行任务 + * + * @param delay 延迟执行时间，单位：ms + * @param r 执行体 */ - public static void runInBack(int delay, - final Runnable r) { + public static void runInBack(int delay, final Runnable r) { delayTimerTask(delay, new TimerTask() { @Override @@ -67,7 +81,7 @@ public void run() { }); } - private static void delayTimerTask(int delay, TimerTask timerTask){ + private static void delayTimerTask(int delay, TimerTask timerTask) { Timer timer = new Timer(); timer.schedule(timerTask, delay); } diff --git a/library/src/main/java/com/qiniu/android/utils/BytesUtils.java b/library/src/main/java/com/qiniu/android/utils/BytesUtils.java index 20fbc3496..acf6294ee 100644 --- a/library/src/main/java/com/qiniu/android/utils/BytesUtils.java +++ b/library/src/main/java/com/qiniu/android/utils/BytesUtils.java @@ -2,7 +2,20 @@ import java.io.IOException; +/** + * Bytes 工具 + */ public class BytesUtils { + + /** + * 获取 byte 数组的子数组 + * + * @param source 源 byte 数组 + * @param from 子数组开始位置 + * @param length 子数组长度 + * @return 子数组 + * @throws IOException 异常 + */ public static byte[] subBytes(byte[] source, int from, int length) throws IOException { if (length + from > source.length) { throw new IOException("copy bytes out of range"); diff --git a/library/src/main/java/com/qiniu/android/utils/Cache.java b/library/src/main/java/com/qiniu/android/utils/Cache.java index d8ece7dd3..78f94ae82 100644 --- a/library/src/main/java/com/qiniu/android/utils/Cache.java +++ b/library/src/main/java/com/qiniu/android/utils/Cache.java @@ -10,6 +10,9 @@ import java.util.Map; import java.util.concurrent.ConcurrentHashMap; +/** + * 缓存对象 + */ public class Cache { // 当 cache 修改数量到达这个值时，就会 flush，默认是 1 @@ -63,7 +66,7 @@ private void load() { try { JSONObject jsonObject = cacheJson.getJSONObject(key); Constructor constructor = (Constructor) objectClass.getConstructor(JSONObject.class); - Object object = (Object)constructor.newInstance(jsonObject); + Object object = (Object) constructor.newInstance(jsonObject); this.memCache.put(key, object); } catch (Exception e) { e.printStackTrace(); @@ -75,14 +78,36 @@ private void load() { } } + /** + * 缓存的 Object 协议定义 + */ public interface Object { + + /** + * 转 json + * + * @return JSONObject + */ JSONObject toJson(); } + /** + * 根据缓存的 key 获取缓存对象 + * + * @param cacheKey 缓存的 key + * @return 缓存对象 + */ public Object cacheForKey(String cacheKey) { return this.memCache.get(cacheKey); } + /** + * 缓存对象方法 + * + * @param cacheKey 缓存的 key + * @param object 缓存对象 + * @param atomically 是否同步缓存 + */ public void cache(String cacheKey, Object object, boolean atomically) { if (StringUtils.isNullOrEmpty(cacheKey) || object == null) { return; @@ -98,10 +123,20 @@ public void cache(String cacheKey, Object object, boolean atomically) { } } + /** + * 获取所有的内存缓存 + * + * @return 所有的内存缓存 + */ public Map allMemoryCache() { return new HashMap<>(this.memCache); } + /** + * 内存缓存写入硬盘 + * + * @param atomically 是否同步写入 + */ public void flush(boolean atomically) { synchronized (this) { if (this.isFlushing) { @@ -159,15 +194,23 @@ private void flushCache(Map flushCache) { } } + /** + * 清理内存缓存 + */ public void clearMemoryCache() { this.memCache.clear(); } + /** + * 清理磁盘缓存 + */ public void clearDiskCache() { this.diskCache.deleteAll(); } - + /** + * Cache Builder + */ public static class Builder { // 当 cache 修改数量到达这个值时，就会 flush，默认是 1 private int flushCount = 1; @@ -178,20 +221,42 @@ public static class Builder { // 存储对象的类型 private final Class objectClass; + /** + * Builder 构造方法 + * + * @param objectClass 缓存对象的 class 类型 + */ public Builder(Class objectClass) { this.objectClass = objectClass; } + /** + * 设置当内存改变多少次后进行内存刷入磁盘操作 + * + * @param flushCount 次数 + * @return Builder + */ public Builder setFlushCount(int flushCount) { this.flushCount = flushCount; return this; } + /** + * 设置缓存版本信息 + * + * @param version 版本信息 + * @return Builder + */ public Builder setVersion(String version) { this.version = version; return this; } + /** + * 构造 Cache + * + * @return Cache + */ public Cache builder() { return new Cache(this.objectClass, this.flushCount, this.version); } diff --git a/library/src/main/java/com/qiniu/android/utils/Constants.java b/library/src/main/java/com/qiniu/android/utils/Constants.java index 01be0179b..17b6196d2 100644 --- a/library/src/main/java/com/qiniu/android/utils/Constants.java +++ b/library/src/main/java/com/qiniu/android/utils/Constants.java @@ -1,6 +1,10 @@ package com.qiniu.android.utils; +/** + * 常量定义 + */ public class Constants { + /** * Unknown network class */ diff --git a/library/src/main/java/com/qiniu/android/utils/ContextGetter.java b/library/src/main/java/com/qiniu/android/utils/ContextGetter.java index 11d065d8e..33213f243 100644 --- a/library/src/main/java/com/qiniu/android/utils/ContextGetter.java +++ b/library/src/main/java/com/qiniu/android/utils/ContextGetter.java @@ -11,6 +11,11 @@ public final class ContextGetter { private static Context context = applicationContext(); + /** + * application Context + * + * @return Context + */ public static Context applicationContext() { if (context != null) { return context; diff --git a/library/src/main/java/com/qiniu/android/utils/FastDatePrinter.java b/library/src/main/java/com/qiniu/android/utils/FastDatePrinter.java index 1ba6c51e9..dc70771f5 100644 --- a/library/src/main/java/com/qiniu/android/utils/FastDatePrinter.java +++ b/library/src/main/java/com/qiniu/android/utils/FastDatePrinter.java @@ -32,35 +32,28 @@ /** *

FastDatePrinter is a fast and thread-safe version of * {@link java.text.SimpleDateFormat}.

- *

*

Since FastDatePrinter is thread safe, you can use a static member instance:

* * private static final DatePrinter DATE_PRINTER = FastDateFormat.getInstance("yyyy-MM-dd"); * - *

*

This class can be used as a direct replacement to * {@code SimpleDateFormat} in most formatting situations. * This class is especially useful in multi-threaded server environments. * {@code SimpleDateFormat} is not thread-safe in any JDK version, * nor will it be as Sun have closed the bug/RFE. *

- *

*

Only formatting is supported by this class, but all patterns are compatible with * SimpleDateFormat (except time zones and some year patterns - see below).

- *

*

Java 1.4 introduced a new pattern letter, {@code 'Z'}, to represent * time zones in RFC822 format (eg. {@code +0800} or {@code -1100}). * This pattern letter can be used here (on all JDK versions).

- *

*

In addition, the pattern {@code 'ZZ'} has been made to represent * ISO 8601 extended format time zones (eg. {@code +08:00} or {@code -11:00}). * This introduces a minor incompatibility with Java 1.4, but at a gain of * useful functionality.

- *

*

Starting with JDK7, ISO 8601 support was added using the pattern {@code 'X'}. * To maintain compatibility, {@code 'ZZ'} will continue to be supported, but using * one of the {@code 'X'} formats is recommended. - *

*

Javadoc cites for the year pattern: For formatting, if the number of * pattern letters is 2, the year is truncated to 2 digits; otherwise it is * interpreted as a number. Starting with Java 1.7 a pattern of 'Y' or @@ -508,10 +501,12 @@ String format(final Object obj) { } } - /* (non-Javadoc) - * @see org.apache.commons.lang3.time.DatePrinter#format(java.util.Date) + /** + * format + * + * @param millis 时间戳 + * @return format 信息 */ - public String format(final long millis) { final Calendar c = newCalendar(); c.setTimeInMillis(millis); @@ -549,6 +544,12 @@ private Calendar newCalendar() { * @see org.apache.commons.lang3.time.DatePrinter#format(java.util.Date, java.lang.StringBuffer) */ + /** + * format + * + * @param date date + * @return String + */ public String format(final Date date) { final Calendar c = newCalendar(); c.setTime(date); @@ -559,6 +560,12 @@ public String format(final Date date) { * @see org.apache.commons.lang3.time.DatePrinter#format(java.util.Calendar, java.lang.StringBuffer) */ + /** + * format + * + * @param calendar calendar + * @return String + */ public String format(final Calendar calendar) { return format(calendar, new StringBuilder(mMaxLengthEstimate)).toString(); } @@ -567,6 +574,13 @@ public String format(final Calendar calendar) { * @see org.apache.commons.lang3.time.DatePrinter#format(long, java.lang.Appendable) */ + /** + * format + * + * @param millis millis + * @param buf buf + * @return StringBuffer + */ public StringBuffer format(final long millis, final StringBuffer buf) { final Calendar c = newCalendar(); c.setTimeInMillis(millis); @@ -577,6 +591,13 @@ public StringBuffer format(final long millis, final StringBuffer buf) { * @see org.apache.commons.lang3.time.DatePrinter#format(java.util.Date, java.lang.Appendable) */ + /** + * format + * + * @param date date + * @param buf buf + * @return StringBuffer + */ public StringBuffer format(final Date date, final StringBuffer buf) { final Calendar c = newCalendar(); c.setTime(date); @@ -587,23 +608,54 @@ public StringBuffer format(final Date date, final StringBuffer buf) { * @see org.apache.commons.lang3.time.DatePrinter#format(java.util.Calendar, java.lang.Appendable) */ + /** + * format + * + * @param calendar calendar + * @param buf buf + * @return StringBuffer + */ public StringBuffer format(final Calendar calendar, final StringBuffer buf) { // do not pass in calendar directly, this will cause TimeZone of FastDatePrinter to be ignored return format(calendar.getTime(), buf); } + /** + * format + * + * @param millis millis + * @param buf buf + * @param buf class + * @return Appendable + */ public B format(final long millis, final B buf) { final Calendar c = newCalendar(); c.setTimeInMillis(millis); return applyRules(c, buf); } + /** + * format + * + * @param date date + * @param buf buf + * @param buf class + * @return Appendable + */ public B format(final Date date, final B buf) { final Calendar c = newCalendar(); c.setTime(date); return applyRules(c, buf); } + /** + * format + * + * @param calendar calendar + * @param buf buf + * @param buf class + * @return Appendable + */ public B format(Calendar calendar, final B buf) { // do not pass in calendar directly, this will cause TimeZone of FastDatePrinter to be ignored if (!calendar.getTimeZone().equals(mTimeZone)) { @@ -656,6 +708,12 @@ private B applyRules(final Calendar calendar, final B buf /* (non-Javadoc) * @see org.apache.commons.lang3.time.DatePrinter#getPattern() */ + + /** + * getPattern + * + * @return Pattern + */ public String getPattern() { return mPattern; } @@ -666,10 +724,21 @@ public String getPattern() { /* (non-Javadoc) * @see org.apache.commons.lang3.time.DatePrinter#getTimeZone() */ + + /** + * get TimeZone + * + * @return TimeZone + */ public TimeZone getTimeZone() { return mTimeZone; } + /** + * get Locale + * + * @return Locale + */ public Locale getLocale() { return mLocale; } @@ -677,7 +746,6 @@ public Locale getLocale() { /** *

Gets an estimate for the maximum string length that the * formatter will produce.

- *

*

The actual formatted length will almost always be less than or * equal to this amount.

* @@ -696,7 +764,6 @@ public int getMaxLengthEstimate() { * @param obj the object to compare to * @return {@code true} if equal */ - public boolean equals(final Object obj) { if (obj instanceof FastDatePrinter == false) { return false; @@ -712,7 +779,6 @@ public boolean equals(final Object obj) { * * @return a hash code compatible with equals */ - public int hashCode() { return mPattern.hashCode() + 13 * (mTimeZone.hashCode() + 13 * mLocale.hashCode()); } @@ -722,7 +788,6 @@ public int hashCode() { * * @return a debugging string */ - public String toString() { return "FastDatePrinter[" + mPattern + "," + mLocale + "," + mTimeZone.getID() + "]"; } @@ -797,7 +862,6 @@ private static class CharacterLiteral implements Rule { /** * {@inheritDoc} */ - public int estimateLength() { return 1; } @@ -805,7 +869,6 @@ public int estimateLength() { /** * {@inheritDoc} */ - public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException { buffer.append(mValue); } @@ -830,7 +893,6 @@ private static class StringLiteral implements Rule { /** * {@inheritDoc} */ - public int estimateLength() { return mValue.length(); } @@ -838,7 +900,6 @@ public int estimateLength() { /** * {@inheritDoc} */ - public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException { buffer.append(mValue); } @@ -866,7 +927,6 @@ private static class TextField implements Rule { /** * {@inheritDoc} */ - public int estimateLength() { int max = 0; for (int i = mValues.length; --i >= 0; ) { @@ -881,7 +941,6 @@ public int estimateLength() { /** * {@inheritDoc} */ - public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException { buffer.append(mValues[calendar.get(mField)]); } @@ -905,7 +964,6 @@ private static class UnpaddedNumberField implements NumberRule { /** * {@inheritDoc} */ - public int estimateLength() { return 4; } @@ -913,7 +971,6 @@ public int estimateLength() { /** * {@inheritDoc} */ - public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException { appendTo(buffer, calendar.get(mField)); } @@ -921,7 +978,6 @@ public void appendTo(final Appendable buffer, final Calendar calendar) throws IO /** * {@inheritDoc} */ - public final void appendTo(final Appendable buffer, final int value) throws IOException { if (value < 10) { buffer.append((char) (value + '0')); @@ -949,7 +1005,6 @@ private static class UnpaddedMonthField implements NumberRule { /** * {@inheritDoc} */ - public int estimateLength() { return 2; } @@ -957,7 +1012,6 @@ public int estimateLength() { /** * {@inheritDoc} */ - public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException { appendTo(buffer, calendar.get(Calendar.MONTH) + 1); } @@ -965,7 +1019,6 @@ public void appendTo(final Appendable buffer, final Calendar calendar) throws IO /** * {@inheritDoc} */ - public final void appendTo(final Appendable buffer, final int value) throws IOException { if (value < 10) { buffer.append((char) (value + '0')); @@ -1000,7 +1053,6 @@ private static class PaddedNumberField implements NumberRule { /** * {@inheritDoc} */ - public int estimateLength() { return mSize; } @@ -1008,7 +1060,6 @@ public int estimateLength() { /** * {@inheritDoc} */ - public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException { appendTo(buffer, calendar.get(mField)); } @@ -1016,7 +1067,6 @@ public void appendTo(final Appendable buffer, final Calendar calendar) throws IO /** * {@inheritDoc} */ - public final void appendTo(final Appendable buffer, final int value) throws IOException { appendFullDigits(buffer, value, mSize); } @@ -1040,7 +1090,6 @@ private static class TwoDigitNumberField implements NumberRule { /** * {@inheritDoc} */ - public int estimateLength() { return 2; } @@ -1048,7 +1097,6 @@ public int estimateLength() { /** * {@inheritDoc} */ - public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException { appendTo(buffer, calendar.get(mField)); } @@ -1056,7 +1104,6 @@ public void appendTo(final Appendable buffer, final Calendar calendar) throws IO /** * {@inheritDoc} */ - public final void appendTo(final Appendable buffer, final int value) throws IOException { if (value < 100) { appendDigits(buffer, value); @@ -1082,7 +1129,6 @@ private static class TwoDigitYearField implements NumberRule { /** * {@inheritDoc} */ - public int estimateLength() { return 2; } @@ -1090,7 +1136,6 @@ public int estimateLength() { /** * {@inheritDoc} */ - public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException { appendTo(buffer, calendar.get(Calendar.YEAR) % 100); } @@ -1098,7 +1143,6 @@ public void appendTo(final Appendable buffer, final Calendar calendar) throws IO /** * {@inheritDoc} */ - public final void appendTo(final Appendable buffer, final int value) throws IOException { appendDigits(buffer, value); } @@ -1120,7 +1164,6 @@ private static class TwoDigitMonthField implements NumberRule { /** * {@inheritDoc} */ - public int estimateLength() { return 2; } @@ -1128,7 +1171,6 @@ public int estimateLength() { /** * {@inheritDoc} */ - public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException { appendTo(buffer, calendar.get(Calendar.MONTH) + 1); } @@ -1136,7 +1178,6 @@ public void appendTo(final Appendable buffer, final Calendar calendar) throws IO /** * {@inheritDoc} */ - public final void appendTo(final Appendable buffer, final int value) throws IOException { appendDigits(buffer, value); } @@ -1161,7 +1202,6 @@ private static class TwelveHourField implements NumberRule { /** * {@inheritDoc} */ - public int estimateLength() { return mRule.estimateLength(); } @@ -1169,7 +1209,6 @@ public int estimateLength() { /** * {@inheritDoc} */ - public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException { int value = calendar.get(Calendar.HOUR); if (value == 0) { @@ -1181,7 +1220,6 @@ public void appendTo(final Appendable buffer, final Calendar calendar) throws IO /** * {@inheritDoc} */ - public void appendTo(final Appendable buffer, final int value) throws IOException { mRule.appendTo(buffer, value); } @@ -1206,7 +1244,6 @@ private static class TwentyFourHourField implements NumberRule { /** * {@inheritDoc} */ - public int estimateLength() { return mRule.estimateLength(); } @@ -1214,7 +1251,6 @@ public int estimateLength() { /** * {@inheritDoc} */ - public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException { int value = calendar.get(Calendar.HOUR_OF_DAY); if (value == 0) { @@ -1226,7 +1262,6 @@ public void appendTo(final Appendable buffer, final Calendar calendar) throws IO /** * {@inheritDoc} */ - public void appendTo(final Appendable buffer, final int value) throws IOException { mRule.appendTo(buffer, value); } @@ -1243,17 +1278,36 @@ private static class DayInWeekField implements NumberRule { } + /** + * estimateLength + * + * @return estimateLength + */ public int estimateLength() { return mRule.estimateLength(); } + /** + * append + * + * @param buffer the output buffer + * @param calendar calendar to be appended + * @throws IOException IOException + */ public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException { final int value = calendar.get(Calendar.DAY_OF_WEEK); mRule.appendTo(buffer, value != Calendar.SUNDAY ? value - 1 : 7); } + /** + * appendTo + * + * @param buffer the output buffer + * @param value the value to be appended + * @throws IOException IOException + */ public void appendTo(final Appendable buffer, final int value) throws IOException { mRule.appendTo(buffer, value); } @@ -1357,7 +1411,6 @@ private static class TimeZoneNumberRule implements Rule { /** * {@inheritDoc} */ - public int estimateLength() { return 5; } @@ -1365,7 +1418,6 @@ public int estimateLength() { /** * {@inheritDoc} */ - public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException { int offset = calendar.get(Calendar.ZONE_OFFSET) + calendar.get(Calendar.DST_OFFSET); @@ -1435,7 +1487,6 @@ static Iso8601_Rule getRule(final int tokenLen) { /** * {@inheritDoc} */ - public int estimateLength() { return length; } @@ -1443,7 +1494,6 @@ public int estimateLength() { /** * {@inheritDoc} */ - public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException { int offset = calendar.get(Calendar.ZONE_OFFSET) + calendar.get(Calendar.DST_OFFSET); if (offset == 0) { diff --git a/library/src/main/java/com/qiniu/android/utils/GZipUtil.java b/library/src/main/java/com/qiniu/android/utils/GZipUtil.java index 01d2f2988..776018f95 100644 --- a/library/src/main/java/com/qiniu/android/utils/GZipUtil.java +++ b/library/src/main/java/com/qiniu/android/utils/GZipUtil.java @@ -6,20 +6,33 @@ import java.util.zip.GZIPInputStream; import java.util.zip.GZIPOutputStream; +/** + * GZip 工具 + */ public class GZipUtil { - public static byte[] gZip(String string){ - if (string == null){ + /** + * 压缩字符串 + * @param string 带压缩数据 + * @return 压缩后的数据 + */ + public static byte[] gZip(String string) { + if (string == null) { return null; } return gZip(string.getBytes()); } - public static byte[] gZip(byte[] bytes){ - if (bytes == null){ + /** + * 压缩 byte 数组 + * @param bytes 带压缩数据 + * @return 压缩后的数据 + */ + public static byte[] gZip(byte[] bytes) { + if (bytes == null) { return null; } - if (bytes.length == 0){ + if (bytes.length == 0) { return bytes; } @@ -28,12 +41,12 @@ public static byte[] gZip(byte[] bytes){ try { gzip = new GZIPOutputStream(out); gzip.write(bytes); - } catch (IOException e){ + } catch (IOException e) { } finally { - if (gzip != null){ + if (gzip != null) { try { gzip.close(); - } catch (IOException e){ + } catch (IOException e) { } } } @@ -41,11 +54,16 @@ public static byte[] gZip(byte[] bytes){ return out.toByteArray(); } + /** + * 解压缩 byte 数组 + * @param bytes 待解压缩数据 + * @return 解压缩后的数据 + */ public static byte[] gUnzip(byte[] bytes) { - if (bytes == null){ + if (bytes == null) { return null; } - if (bytes.length == 0){ + if (bytes.length == 0) { return bytes; } diff --git a/library/src/main/java/com/qiniu/android/utils/GroupTaskThread.java b/library/src/main/java/com/qiniu/android/utils/GroupTaskThread.java index 5022ea5e1..93302bbd4 100644 --- a/library/src/main/java/com/qiniu/android/utils/GroupTaskThread.java +++ b/library/src/main/java/com/qiniu/android/utils/GroupTaskThread.java @@ -2,21 +2,35 @@ import java.util.ArrayList; +/** + * 组任务线程 + */ public class GroupTaskThread extends Thread { + /** + * 组任务执行完成回调 + */ public final GroupTaskCompleteHandler completeHandler; private ArrayList tasks = new ArrayList(); + /** + * 构造函数 + * + * @param completeHandler 组任务执行完成回调 + */ public GroupTaskThread(GroupTaskCompleteHandler completeHandler) { this.completeHandler = completeHandler; } + /** + * 组任务开始执行 + */ @Override public void run() { super.run(); - while (!isInterrupted()){ + while (!isInterrupted()) { boolean isAllTasksCompleted = false; synchronized (this) { isAllTasksCompleted = isAllTasksCompleted(); @@ -28,17 +42,23 @@ public void run() { } GroupTask task = getNextWaitingTask(); - if (task != null){ + if (task != null) { task.state = GroupTask.State.Running; task.run(task); } else { try { sleep(10); - } catch (InterruptedException e) {} + } catch (InterruptedException e) { + } } } } + /** + * 添加任务 + * + * @param task 任务 + */ public void addTask(GroupTask task) { synchronized (this) { if (!isAllTasksCompleted()) { @@ -47,66 +67,100 @@ public void addTask(GroupTask task) { } } - private GroupTask getNextWaitingTask(){ + private GroupTask getNextWaitingTask() { GroupTask task = null; for (int i = 0; i < tasks.size(); i++) { GroupTask taskP = tasks.get(i); - if (taskP.state == GroupTask.State.Waiting){ + if (taskP.state == GroupTask.State.Waiting) { task = taskP; break; } } return task; } - private boolean isAllTasksCompleted(){ - if (tasks.size() == 0){ + + private boolean isAllTasksCompleted() { + if (tasks.size() == 0) { return false; } boolean ret = true; for (int i = 0; i < tasks.size(); i++) { GroupTask task = tasks.get(i); - if (task.state != GroupTask.State.Complete){ + if (task.state != GroupTask.State.Complete) { ret = false; break; } } return ret; } - private void completeAction(){ - if (completeHandler != null){ + + private void completeAction() { + if (completeHandler != null) { completeHandler.complete(); } } - - public abstract static class GroupTask{ + /** + * 组任务 + */ + public abstract static class GroupTask { protected enum State { Waiting, Running, Complete - }; + } + + ; protected State state = State.Waiting; + + /** + * 任务 ID + */ public final String id; + /** + * 构造函数 + */ public GroupTask() { this.id = null; } + + /** + * 构造函数 + * + * @param id 任务 ID + */ public GroupTask(String id) { this.id = id; } + /** + * 执行任务 + * + * @param task 任务 + */ public abstract void run(GroupTask task); - public void taskComplete(){ + + /** + * 任务执行结束 + */ + public void taskComplete() { state = State.Complete; } } - + /** + * 任务执行结束回调 + */ public interface GroupTaskCompleteHandler { + + /** + * 任务执行结束回调 + */ void complete(); } } diff --git a/library/src/main/java/com/qiniu/android/utils/IPAddressUtil.java b/library/src/main/java/com/qiniu/android/utils/IPAddressUtil.java index 4d3f46968..bebc8ea2c 100644 --- a/library/src/main/java/com/qiniu/android/utils/IPAddressUtil.java +++ b/library/src/main/java/com/qiniu/android/utils/IPAddressUtil.java @@ -5,7 +5,7 @@ public class IPAddressUtil { private final static int INADDR16SZ = 16; private final static int INT16SZ = 2; - /* + /** * Converts IPv4 address in its textual presentation form * into its numeric binary form. * @@ -13,8 +13,7 @@ public class IPAddressUtil { * @return a byte array representing the IPv4 numeric address */ @SuppressWarnings("fallthrough") - public static byte[] textToNumericFormatV4(String src) - { + public static byte[] textToNumericFormatV4(String src) { byte[] res = new byte[INADDR4SZ]; long tmpValue = 0; @@ -75,9 +74,9 @@ public static byte[] textToNumericFormatV4(String src) case 1: res[1] = (byte) ((tmpValue >> 16) & 0xff); case 2: - res[2] = (byte) ((tmpValue >> 8) & 0xff); + res[2] = (byte) ((tmpValue >> 8) & 0xff); case 3: - res[3] = (byte) ((tmpValue >> 0) & 0xff); + res[3] = (byte) ((tmpValue >> 0) & 0xff); } return res; } @@ -92,8 +91,7 @@ public static byte[] textToNumericFormatV4(String src) * @param src a String representing an IPv6 address in textual format * @return a byte array representing the IPv6 numeric address */ - public static byte[] textToNumericFormatV6(String src) - { + public static byte[] textToNumericFormatV6(String src) { // Shortest valid string is "::", hence at least 2 chars if (src.length() < 2) { return null; @@ -107,8 +105,8 @@ public static byte[] textToNumericFormatV6(String src) byte[] dst = new byte[INADDR16SZ]; int srcb_length = srcb.length; - int pc = src.indexOf ("%"); - if (pc == srcb_length -1) { + int pc = src.indexOf("%"); + if (pc == srcb_length - 1) { return null; } @@ -157,10 +155,10 @@ public static byte[] textToNumericFormatV6(String src) if (ch == '.' && ((j + INADDR4SZ) <= INADDR16SZ)) { String ia4 = src.substring(curtok, srcb_length); /* check this IPv4 address has 3 dots, ie. A.B.C.D */ - int dot_count = 0, index=0; - while ((index = ia4.indexOf ('.', index)) != -1) { - dot_count ++; - index ++; + int dot_count = 0, index = 0; + while ((index = ia4.indexOf('.', index)) != -1) { + dot_count++; + index++; } if (dot_count != 3) { return null; @@ -206,6 +204,8 @@ public static byte[] textToNumericFormatV6(String src) } /** + * isIPv4LiteralAddress + * * @param src a String representing an IPv4 address in textual format * @return a boolean indicating whether src is an IPv4 literal address */ @@ -214,6 +214,8 @@ public static boolean isIPv4LiteralAddress(String src) { } /** + * isIPv6LiteralAddress + * * @param src a String representing an IPv6 address in textual format * @return a boolean indicating whether src is an IPv6 literal address */ @@ -221,11 +223,11 @@ public static boolean isIPv6LiteralAddress(String src) { return textToNumericFormatV6(src) != null; } - /* + /** * Convert IPv4-Mapped address to IPv4 address. Both input and * returned value are in network order binary form. * - * @param src a String representing an IPv4-Mapped address in textual format + * @param addr a String representing an IPv4-Mapped address in textual format * @return a byte array representing the IPv4 numeric address */ public static byte[] convertFromIPv4MappedAddress(byte[] addr) { @@ -253,8 +255,8 @@ private static boolean isIPv4MappedAddress(byte[] addr) { (addr[4] == 0x00) && (addr[5] == 0x00) && (addr[6] == 0x00) && (addr[7] == 0x00) && (addr[8] == 0x00) && (addr[9] == 0x00) && - (addr[10] == (byte)0xff) && - (addr[11] == (byte)0xff)) { + (addr[10] == (byte) 0xff) && + (addr[11] == (byte) 0xff)) { return true; } return false; diff --git a/library/src/main/java/com/qiniu/android/utils/Json.java b/library/src/main/java/com/qiniu/android/utils/Json.java index 8d0762b6e..7787820d3 100644 --- a/library/src/main/java/com/qiniu/android/utils/Json.java +++ b/library/src/main/java/com/qiniu/android/utils/Json.java @@ -9,13 +9,25 @@ /** * Created by long on 2017/7/25. */ - public final class Json { + + /** + * map 转 json + * + * @param map map + * @return json string + */ public static String encodeMap(Map map) { JSONObject obj = new JSONObject(map); return obj.toString(); } + /** + * Collection 转 json + * + * @param collection Collection + * @return json string + */ public static String encodeList(Collection collection) { JSONArray array = new JSONArray(collection); return array.toString(); diff --git a/library/src/main/java/com/qiniu/android/utils/ListVector.java b/library/src/main/java/com/qiniu/android/utils/ListVector.java index 5b203a651..d84745518 100644 --- a/library/src/main/java/com/qiniu/android/utils/ListVector.java +++ b/library/src/main/java/com/qiniu/android/utils/ListVector.java @@ -6,16 +6,35 @@ import java.util.Vector; import java.util.concurrent.CopyOnWriteArrayList; +/** + * ListVector + * + * @param 元素类型 + */ public class ListVector extends Vector { + /** + * 构造函数 + */ public ListVector() { super(); } + /** + * 构造函数 + * + * @param initialCapacity initialCapacity + * @param capacityIncrement capacityIncrement + */ public ListVector(int initialCapacity, int capacityIncrement) { super(initialCapacity, capacityIncrement); } + /** + * 对象遍历 + * + * @param handler handler + */ public synchronized void enumerateObjects(EnumeratorHandler handler) { if (handler == null) { return; @@ -30,6 +49,13 @@ public synchronized void enumerateObjects(EnumeratorHandler handler) } } + /** + * create subList + * + * @param fromIndex low endpoint (inclusive) of the subList + * @param toIndex high endpoint (exclusive) of the subList + * @return subList + */ @Override public synchronized ListVector subList(int fromIndex, int toIndex) { ListVector listVector = new ListVector(); @@ -44,6 +70,10 @@ public synchronized ListVector subList(int fromIndex, int toIndex) { return listVector; } + /** + * EnumeratorHandler + * @param enumerate 对象的类型 + */ public interface EnumeratorHandler { boolean enumerate(T t); } diff --git a/library/src/main/java/com/qiniu/android/utils/LogUtil.java b/library/src/main/java/com/qiniu/android/utils/LogUtil.java index 7331b9593..6f9e9f97c 100644 --- a/library/src/main/java/com/qiniu/android/utils/LogUtil.java +++ b/library/src/main/java/com/qiniu/android/utils/LogUtil.java @@ -15,22 +15,47 @@ public class LogUtil { private static boolean enableFile = true; private static boolean enableFunction = false; + /** + * 开启日志 + * + * @param enable 是否开启日志 + */ public static void enableLog(boolean enable) { enableLog = enable; } + /** + * 日志中是否包含 Date + * + * @param enable 是否包含 Date + */ public static void enableDate(boolean enable) { enableDate = enable; } + /** + * 日志中是否包含 File + * + * @param enable 是否包含 File + */ public static void enableFile(boolean enable) { enableFile = enable; } + /** + * 日志中是否包含 Function + * + * @param enable 是否包含 Function + */ public static void enableFunction(boolean enable) { enableFunction = enable; } + /** + * 设置日志等级 + * + * @param level 日志等级 + */ public static void setLogLevel(int level) { logLevel = level; } @@ -39,6 +64,7 @@ public static void setLogLevel(int level) { * Send a VERBOSE log message. * * @param msg The message you would like logged. + * @return int */ public static int v(String msg) { return println(Log.VERBOSE, null, msg, null); @@ -50,6 +76,7 @@ public static int v(String msg) { * @param tag Used to identify the source of a log message. It usually identifies * the class or activity where the log call occurs. * @param msg The message you would like logged. + * @return int */ public static int v(String tag, String msg) { return println(Log.VERBOSE, tag, msg, null); @@ -62,6 +89,7 @@ public static int v(String tag, String msg) { * the class or activity where the log call occurs. * @param msg The message you would like logged. * @param tr An exception to log + * @return int */ public static int v(String tag, String msg, Throwable tr) { return println(Log.VERBOSE, tag, msg, tr); @@ -71,6 +99,7 @@ public static int v(String tag, String msg, Throwable tr) { * Send a DEBUG log message. * * @param msg The message you would like logged. + * @return int */ public static int d(String msg) { return println(Log.DEBUG, null, msg, null); @@ -82,6 +111,7 @@ public static int d(String msg) { * @param tag Used to identify the source of a log message. It usually identifies * the class or activity where the log call occurs. * @param msg The message you would like logged. + * @return int */ public static int d(String tag, String msg) { return println(Log.DEBUG, tag, msg, null); @@ -94,6 +124,7 @@ public static int d(String tag, String msg) { * the class or activity where the log call occurs. * @param msg The message you would like logged. * @param tr An exception to log + * @return int */ public static int d(String tag, String msg, Throwable tr) { return println(Log.DEBUG, tag, msg, tr); @@ -103,6 +134,7 @@ public static int d(String tag, String msg, Throwable tr) { * Send an INFO log message. * * @param msg The message you would like logged. + * @return int */ public static int i(String msg) { return println(Log.INFO, null, msg, null); @@ -114,6 +146,7 @@ public static int i(String msg) { * @param tag Used to identify the source of a log message. It usually identifies * the class or activity where the log call occurs. * @param msg The message you would like logged. + * @return int */ public static int i(String tag, String msg) { return println(Log.INFO, tag, msg, null); @@ -126,6 +159,7 @@ public static int i(String tag, String msg) { * the class or activity where the log call occurs. * @param msg The message you would like logged. * @param tr An exception to log + * @return int */ public static int i(String tag, String msg, Throwable tr) { return println(Log.INFO, tag, msg, tr); @@ -135,6 +169,7 @@ public static int i(String tag, String msg, Throwable tr) { * Send a WARN log message. * * @param msg The message you would like logged. + * @return int */ public static int w(String msg) { return println(Log.WARN, null, msg, null); @@ -146,6 +181,7 @@ public static int w(String msg) { * @param tag Used to identify the source of a log message. It usually identifies * the class or activity where the log call occurs. * @param msg The message you would like logged. + * @return int */ public static int w(String tag, String msg) { return println(Log.WARN, tag, msg, null); @@ -158,16 +194,19 @@ public static int w(String tag, String msg) { * the class or activity where the log call occurs. * @param msg The message you would like logged. * @param tr An exception to log + * @return int */ public static int w(String tag, String msg, Throwable tr) { return println(Log.WARN, tag, msg, tr); } - /* + /** * Send a WARN log message and log the exception. + * * @param tag Used to identify the source of a log message. It usually identifies - * the class or activity where the log call occurs. - * @param tr An exception to log + * the class or activity where the log call occurs. + * @param tr An exception to log + * @return int */ public static int w(String tag, Throwable tr) { return println(Log.WARN, tag, null, tr); @@ -177,6 +216,7 @@ public static int w(String tag, Throwable tr) { * Send an ERROR log message. * * @param msg The message you would like logged. + * @return int */ public static int e(String msg) { return println(Log.ERROR, null, msg, null); @@ -188,6 +228,7 @@ public static int e(String msg) { * @param tag Used to identify the source of a log message. It usually identifies * the class or activity where the log call occurs. * @param msg The message you would like logged. + * @return int */ public static int e(String tag, String msg) { return println(Log.ERROR, tag, msg, null); @@ -200,6 +241,7 @@ public static int e(String tag, String msg) { * the class or activity where the log call occurs. * @param msg The message you would like logged. * @param tr An exception to log + * @return int */ public static int e(String tag, String msg, Throwable tr) { return println(Log.ERROR, tag, msg, tr); diff --git a/mvn_push.gradle b/mvn_push.gradle index 5a3cf79b2..5cced192d 100644 --- a/mvn_push.gradle +++ b/mvn_push.gradle @@ -39,12 +39,18 @@ def getRepositoryPassword() { return hasProperty('NEXUS_PASSWORD') ? NEXUS_PASSWORD : "" } -task androidJavadocs(type: Javadoc) { +task androidJavadocs(type: Javadoc, dependsOn: 'assembleRelease') { failOnError = false - source = android.sourceSets.main.java.srcDirs options.encoding = "UTF-8" options.charSet = 'UTF-8' classpath += project.files(android.getBootClasspath().join(File.pathSeparator)) + android.libraryVariants.all { variant -> + if (variant.name == 'release') { + owner.classpath += variant.javaCompile.classpath + } + } + source = android.sourceSets.main.java.srcDirs + exclude '**/R.html', '**/R.*.html', '**/index.html' } task androidJavadocsJar(type: Jar, dependsOn: androidJavadocs) {