From 7448379da06b03271951318915ad79d35cf48cd1 Mon Sep 17 00:00:00 2001 From: LamGC Date: Fri, 4 Sep 2020 00:25:01 +0800 Subject: [PATCH] =?UTF-8?q?[Document]=20=E4=BC=98=E5=8C=96=E6=96=87?= =?UTF-8?q?=E6=A1=A3;?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [Document] 优化 CacheStore-Api 模块的文档; --- .../net/lamgc/cgj/bot/cache/CacheStore.java | 12 +++++--- .../cgj/bot/cache/CacheStoreFactory.java | 3 +- .../cgj/bot/cache/CollectionCacheStore.java | 4 ++- .../lamgc/cgj/bot/cache/ListCacheStore.java | 29 ++++++++++++------- .../lamgc/cgj/bot/cache/SingleCacheStore.java | 6 ++-- 5 files changed, 34 insertions(+), 20 deletions(-) diff --git a/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/CacheStore.java b/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/CacheStore.java index 1ec905e..bdb2520 100644 --- a/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/CacheStore.java +++ b/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/CacheStore.java @@ -28,7 +28,8 @@ public interface CacheStore { /** * 设置指定缓存的生存时间. - * 当该缓存项的 TTL 为 0 时, 该缓存项将会失效, 并被删除. + * + *

当该缓存项的 TTL 为 0 时, 该缓存项将会失效, 并被删除. * 关于删除失效缓存项的时机在此并不特别规定, 依照各实现自行处理. * @param key 欲设置过期时间的缓存项键名. * @param ttl 有效期时间, 如果设为 -1 则代表清除缓存项的 TTL, 缓存项不会因为 TTL 为 0 而失效. 单位"毫秒(ms)". @@ -59,9 +60,12 @@ public interface CacheStore { /** * 检查指定缓存项是否存在. - * 如果缓存项不存在或失效(比如因 TTL 为 0 而失效), 则会判定为不存在. - * 缓存项失效不代表不存在(因为根据实现的不同, 可能还没来得及清理失效缓存项), 但缓存项不存在一定是失效的(即便如此, 缓存项一旦失效, 便不可获取). - * 故后续除特殊情况使用"缓存项 失效"描述, 文档将以"缓存项不存在"描述缓存项失效或不存在的情况. + * + *

如果缓存项不存在或失效(比如因 TTL 为 0 而失效), 则会判定为不存在. + * 缓存项失效不代表不存在(因为根据实现的不同, 可能还没来得及清理失效缓存项), + * 但缓存项不存在一定是失效的(即便如此, 缓存项一旦失效, 便不可获取). + * + *

故后续除特殊情况使用"缓存项 失效"描述, 文档将以"缓存项不存在"描述缓存项失效或不存在的情况. * @param key 缓存项键名 * @return 如果存在, 返回 true, 如果不存在或失效, 返回 false. * @throws NullPointerException 当 key 为 null 时抛出. diff --git a/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/CacheStoreFactory.java b/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/CacheStoreFactory.java index 51aabf9..e44fc1f 100644 --- a/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/CacheStoreFactory.java +++ b/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/CacheStoreFactory.java @@ -21,7 +21,8 @@ import net.lamgc.cgj.bot.cache.convert.StringConverter; /** * 缓存存储容器构造工厂. - * 可支持不同实现缓存存储容器. + * + *

可支持不同实现缓存存储容器. * @author LamGC */ public interface CacheStoreFactory { diff --git a/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/CollectionCacheStore.java b/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/CollectionCacheStore.java index ec7baf0..1be4353 100644 --- a/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/CollectionCacheStore.java +++ b/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/CollectionCacheStore.java @@ -75,15 +75,17 @@ public interface CollectionCacheStore> extends CacheS * 清空集合中的所有元素. * @param key 欲清空集合的缓存项键名. * @return 操作成功返回 true. + * @throws NullPointerException 当 key 为 null 时抛出. */ boolean clearCollection(String key); /** * 删除缓存项中指定的元素. - * 该方法与 {@link CacheStore#remove(String)} 不同, 该方法仅删除缓存项中的指定元素, 即使删除后缓存项中没有元素, 也不会删除缓存项. + *

该方法与 {@link CacheStore#remove(String)} 不同, 该方法仅删除缓存项中的指定元素, 即使删除后缓存项中没有元素, 也不会删除缓存项. * @param key 待操作的缓存项键名. * @param element 欲删除的元素. * @return 如果元素存在且删除成功, 返回 true. + * @throws NullPointerException 当 key 为 null 时抛出. */ boolean removeElement(String key, E element); diff --git a/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/ListCacheStore.java b/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/ListCacheStore.java index 8fa6642..74989e2 100644 --- a/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/ListCacheStore.java +++ b/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/ListCacheStore.java @@ -21,7 +21,7 @@ import java.util.List; /** * List 类型的缓存存储容器. - * 该存储容器内的 List 与 {@link List} 概念相同, 即"有序列表". + *

该存储容器内的 List 与 {@link List} 概念相同, 即"有序列表". * @param 值类型. * @author LamGC */ @@ -30,8 +30,9 @@ public interface ListCacheStore extends CollectionCacheStore> { /** * 获取缓存项中的指定元素. * @param key 欲取值的缓存项键名. - * @param index 元素索引. - * @return 如果缓存项存在, 返回缓存项的值, 否则返回 null. + * @param index 元素索引, 从 0 开始. + * @return 如果缓存项存在, 且指定索引存在元素, 则返回元素, + * 如果缓存项不存在, 或索引超出范围(超出长度或低于 0)等导致获取失败, 返回 null. * @throws NullPointerException 当 key 为 null 时抛出. */ E getElement(String key, int index); @@ -39,33 +40,39 @@ public interface ListCacheStore extends CollectionCacheStore> { /** * 根据返回获取部分元素. * @param key 欲取值的缓存项键值. - * @param index 起始元素索引. + * @param index 起始元素索引, 从 0 开始. * @param length 获取长度. * @return 如果成功, 返回成功获取到的元素数量, 失败返回 null. - * 对于起始元素索引超出范围, 或获取长度与实际能获取的长度不同的情况, 不允许返回 null, + *

对于起始元素索引超出范围, 或获取长度与实际能获取的长度不同的情况, 不允许返回 null, * 相反, 返回的 List 中的元素数量应反映实际所可获取的元素数量, 例如: - * 因 index 超出范围而无法获取元素, 则返回无元素 List 对象; - * 如果从起始元素开始获取无法获取 length 数量的元素, 则直接返回包含已成功获取元素的 List 对象. + *

* 但需要注意的是: 获取异常不包括在上述范围, 因此如果在获取中出现错误导致获取失败, 应以失败返回 null. + * @throws NullPointerException 当 key 为 null 时抛出. */ List getElementsByRange(String key, int index, int length); /** * 删除指定索引的元素. - * 该方法与 {@link CacheStore#remove(String)} 不同, 该方法仅删除缓存项中的指定元素, 即使删除后缓存项中没有元素, 也不会删除缓存项. + * + *

该方法与 {@link CacheStore#remove(String)} 不同, 该方法仅删除缓存项中的指定元素, 即使删除后缓存项中没有元素, 也不会删除缓存项. * @param key 待操作的缓存项键名. - * @param index 欲删除元素的索引. + * @param index 欲删除元素的索引, 从 0 开始. * @return 如果元素存在且删除成功, 返回 true. + * @throws NullPointerException 当 key 为 null 时抛出. */ boolean removeElement(String key, int index); /** * 删除缓存项中指定的元素. - * 当 List 存在多个该元素时, 删除第一个匹配到的元素. - * 该方法与 {@link CacheStore#remove(String)} 不同, 该方法仅删除缓存项中的指定元素, 即使删除后缓存项中没有元素, 也不会删除缓存项. + *

当 List 存在多个该元素时, 删除第一个匹配到的元素. + *

该方法与 {@link CacheStore#remove(String)} 不同, 该方法仅删除缓存项中的指定元素, 即使删除后缓存项中没有元素, 也不会删除缓存项. * @param key 待操作的缓存项键名. * @param element 欲删除的元素. * @return 如果元素存在且删除成功, 返回 true. + * @throws NullPointerException 当 key 为 null 时抛出. */ @Override boolean removeElement(String key, E element); diff --git a/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/SingleCacheStore.java b/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/SingleCacheStore.java index 8bab916..30f13eb 100644 --- a/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/SingleCacheStore.java +++ b/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/SingleCacheStore.java @@ -19,7 +19,7 @@ package net.lamgc.cgj.bot.cache; /** * 单项存取的缓存存储容器. - * 该缓存存储容器在存储上, 一个键对应一个值, 不存在一对多的情况. + *

该缓存存储容器在存储上, 一个键对应一个值, 不存在一对多的情况. * @param 值类型. * @author LamGC */ @@ -28,7 +28,7 @@ public interface SingleCacheStore extends CacheStore { /** * 设置指定键为指定值. * 如果缓存项不存在, 则新建缓存并存储, 如果存在, 则覆盖原缓存; - * 覆盖缓存相当于是"删除"该缓存并重新创建, "删除"意味着原缓存项的相关设置将会丢失(例如"过期时间"). + *

覆盖缓存相当于是"删除"该缓存并重新创建, "删除"意味着原缓存项的相关设置将会丢失(例如"过期时间"). * @param key 缓存项键名. * @param value 缓存值. * @return 如果成功返回 true. @@ -38,7 +38,7 @@ public interface SingleCacheStore extends CacheStore { /** * 设置指定键为指定值. - * 该方法与 {@link #set(String, Object)} 类似, 但如果该 key 已经存在缓存, 则不执行 set 操作并返回 false. + *

该方法与 {@link #set(String, Object)} 类似, 但如果该 key 已经存在缓存, 则不执行 set 操作并返回 false. * @param key 缓存项键名. * @param value 缓存值. * @return 如果成功返回 true, 当 key 已存在, 或设置失败时返回 false.