LamGC/ContentGrabbingJi
1
0
Fork 0
mirror of https://github.com/LamGC/ContentGrabbingJi.git synced 2025-04-29 22:27:33 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

[Document] 优化文档;

Browse Source 
[Document] 优化 CacheStore-Api 模块的文档;
This commit is contained in:
LamGC 2020-09-04 00:25:01 +08:00
parent 7461376141
commit 7448379da0
Signed by: LamGC
GPG Key ID: 6C5AE2A913941E1D
5 changed files with 34 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/CacheStore.java vendored
View File

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

3
ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/CacheStoreFactory.java vendored
View File

@ -21,7 +21,8 @@ import net.lamgc.cgj.bot.cache.convert.StringConverter;
/**
* 缓存存储容器构造工厂.
* 可支持不同实现缓存存储容器.
*
* <p>可支持不同实现缓存存储容器.
* @author LamGC
*/
public interface CacheStoreFactory {

4
ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/CollectionCacheStore.java vendored
View File

@ -75,15 +75,17 @@ public interface CollectionCacheStore<E, C extends Collection<E>> extends CacheS
* 清空集合中的所有元素.
* @param key 欲清空集合的缓存项键名.
* @return 操作成功返回 true.
* @throws NullPointerException 当 key 为 null 时抛出.
*/
boolean clearCollection(String key);
/**
* 删除缓存项中指定的元素.
* 该方法与 {@link CacheStore#remove(String)} 不同, 该方法仅删除缓存项中的指定元素, 即使删除后缓存项中没有元素, 也不会删除缓存项.
* <p>该方法与 {@link CacheStore#remove(String)} 不同, 该方法仅删除缓存项中的指定元素, 即使删除后缓存项中没有元素, 也不会删除缓存项.
* @param key 待操作的缓存项键名.
* @param element 欲删除的元素.
* @return 如果元素存在且删除成功, 返回 true.
* @throws NullPointerException 当 key 为 null 时抛出.
*/
boolean removeElement(String key, E element);

29
ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/ListCacheStore.java vendored
View File

@ -21,7 +21,7 @@ import java.util.List;
/**
* List 类型的缓存存储容器.
* 该存储容器内的 List 与 {@link List} 概念相同, 即"有序列表".
* <p>该存储容器内的 List 与 {@link List} 概念相同, 即"有序列表".
* @param <E> 值类型.
* @author LamGC
*/
@ -30,8 +30,9 @@ public interface ListCacheStore<E> extends CollectionCacheStore<E, List<E>> {
/**
* 获取缓存项中的指定元素.
* @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<E> extends CollectionCacheStore<E, List<E>> {
/**
* 根据返回获取部分元素.
* @param key 欲取值的缓存项键值.
* @param index 起始元素索引.
* @param index 起始元素索引, 从 0 开始.
* @param length 获取长度.
* @return 如果成功, 返回成功获取到的元素数量, 失败返回 null.
* 对于起始元素索引超出范围, 或获取长度与实际能获取的长度不同的情况, 不允许返回 null,
* <p>对于起始元素索引超出范围, 或获取长度与实际能获取的长度不同的情况, 不允许返回 null,
* 相反, 返回的 List 中的元素数量应反映实际所可获取的元素数量, 例如:
* 因 index 超出范围而无法获取元素, 则返回无元素 List 对象;
* 如果从起始元素开始获取无法获取 length 数量的元素, 则直接返回包含已成功获取元素的 List 对象.
* <ul>
* <li>因 index 超出范围(包括 index 低于 0, 也是如此)而无法获取元素, 则返回无元素 List 对象;
* <li>如果从起始元素开始获取无法获取 length 数量的元素, 则直接返回包含已成功获取元素的 List 对象.
* </ul>
* 但需要注意的是: 获取异常不包括在上述范围, 因此如果在获取中出现错误导致获取失败, 应以失败返回 null.
* @throws NullPointerException 当 key 为 null 时抛出.
*/
List<E> getElementsByRange(String key, int index, int length);
/**
* 删除指定索引的元素.
* 该方法与 {@link CacheStore#remove(String)} 不同, 该方法仅删除缓存项中的指定元素, 即使删除后缓存项中没有元素, 也不会删除缓存项.
*
* <p>该方法与 {@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)} 不同, 该方法仅删除缓存项中的指定元素, 即使删除后缓存项中没有元素, 也不会删除缓存项.
* <p>当 List 存在多个该元素时, 删除第一个匹配到的元素.
* <p>该方法与 {@link CacheStore#remove(String)} 不同, 该方法仅删除缓存项中的指定元素, 即使删除后缓存项中没有元素, 也不会删除缓存项.
* @param key 待操作的缓存项键名.
* @param element 欲删除的元素.
* @return 如果元素存在且删除成功, 返回 true.
* @throws NullPointerException 当 key 为 null 时抛出.
*/
@Override
boolean removeElement(String key, E element);

6
ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/SingleCacheStore.java vendored
View File

@ -19,7 +19,7 @@ package net.lamgc.cgj.bot.cache;
/**
* 单项存取的缓存存储容器.
* 该缓存存储容器在存储上, 一个键对应一个值, 不存在一对多的情况.
* <p>该缓存存储容器在存储上, 一个键对应一个值, 不存在一对多的情况.
* @param <V> 值类型.
* @author LamGC
*/
@ -28,7 +28,7 @@ public interface SingleCacheStore<V> extends CacheStore<V> {
/**
* 设置指定键为指定值.
* 如果缓存项不存在, 则新建缓存并存储, 如果存在, 则覆盖原缓存;
* 覆盖缓存相当于是"删除"该缓存并重新创建, "删除"意味着原缓存项的相关设置将会丢失(例如"过期时间").
* <p>覆盖缓存相当于是"删除"该缓存并重新创建, "删除"意味着原缓存项的相关设置将会丢失(例如"过期时间").
* @param key 缓存项键名.
* @param value 缓存值.
* @return 如果成功返回 true.
@ -38,7 +38,7 @@ public interface SingleCacheStore<V> extends CacheStore<V> {
/**
* 设置指定键为指定值.
* 该方法与 {@link #set(String, Object)} 类似, 但如果该 key 已经存在缓存, 则不执行 set 操作并返回 false.
* <p>该方法与 {@link #set(String, Object)} 类似, 但如果该 key 已经存在缓存, 则不执行 set 操作并返回 false.
* @param key 缓存项键名.
* @param value 缓存值.
* @return 如果成功返回 true, 当 key 已存在, 或设置失败时返回 false.