[Add][Change] CacheStore-api 调整 CacheStoreFactory 的方法信息;

[Add] Factory 添加注解以设置固定信息;
[Add] FactoryPriority 添加优先级常量类;
[Add] GetCacheStoreException 增加异常以表示无法获取 CacheStore 对象;
[Change] CacheStoreFactory 增加'canGetCacheStore'方法, 调整方法签名以允许抛出异常;

ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/CacheStoreFactory.java

@@ -18,6 +18,7 @@
 package net.lamgc.cgj.bot.cache;
 
 import net.lamgc.cgj.bot.cache.convert.StringConverter;
+import net.lamgc.cgj.bot.cache.exception.GetCacheStoreException;
 
 /**
  * 缓存存储容器构造工厂.
@@ -32,8 +33,9 @@ public interface CacheStoreFactory {
      * @param identify 缓存标识.
      * @param converter 类型的转换器.
      * @return 返回 CacheStore 对象.
+     * @throws GetCacheStoreException 当 Factory 无法返回 CacheStore 对象时抛出, 需说明失败原因.
      */
-    <V> SingleCacheStore<V> newSingleCacheStore(String identify, StringConverter<V> converter);
+    <V> SingleCacheStore<V> newSingleCacheStore(String identify, StringConverter<V> converter) throws GetCacheStoreException;
 
     /**
      * 获取一个新的有序列表缓存存储容器.
@@ -41,8 +43,9 @@ public interface CacheStoreFactory {
      * @param converter 元素类型与 String 的转换器.
      * @param <E> 元素类型.
      * @return 返回新的有序列表缓存存储容器.
+     * @throws GetCacheStoreException 当 Factory 无法返回 CacheStore 对象时抛出, 需说明失败原因.
      */
-    <E> ListCacheStore<E> newListCacheStore(String identify, StringConverter<E> converter);
+    <E> ListCacheStore<E> newListCacheStore(String identify, StringConverter<E> converter) throws GetCacheStoreException;
 
     /**
      * 获取一个新的无序集合缓存存储容器.
@@ -50,8 +53,9 @@ public interface CacheStoreFactory {
      * @param converter 元素类型与 String 的转换器.
      * @param <E> 元素类型.
      * @return 返回新的无序集合缓存存储容器.
+     * @throws GetCacheStoreException 当 Factory 无法返回 CacheStore 对象时抛出, 需说明失败原因.
      */
-    <E> SetCacheStore<E> newSetCacheStore(String identify, StringConverter<E> converter);
+    <E> SetCacheStore<E> newSetCacheStore(String identify, StringConverter<E> converter) throws GetCacheStoreException;
 
     /**
      * 获取一个新的映射表缓存存储容器.
@@ -59,6 +63,21 @@ public interface CacheStoreFactory {
      * @param converter 字段值类型与 String 的转换器.
      * @param <V> 字段值类型.
      * @return 返回新的映射表缓存存储容器.
+     * @throws GetCacheStoreException 当 Factory 无法返回 CacheStore 对象时抛出, 需说明失败原因.
      */
-    <V> MapCacheStore<V> newMapCacheStore(String identify, StringConverter<V> converter);
+    <V> MapCacheStore<V> newMapCacheStore(String identify, StringConverter<V> converter) throws GetCacheStoreException;
+
+    /**
+     * 当前是否可以创建 {@link CacheStore}
+     *
+     * <p> 如果返回 true, 将会使用该 Factory.
+     *     如果返回 false 或抛出异常, 将不会通过该 Factory 创建 CacheStore,
+     *
+     * <p> 除非模块能保证 Factory 正常情况下一定能提供 CacheStore 对象,
+     *     否则请不要尝试永远返回 true 来向应用保证 Factory 一定能创建 CacheStore, 保持 Factory 的有效性,
+     *     一旦后续创建 CacheStore 时发生异常, 将视为无法创建.
+     * @return 如果可以, 返回 true.
+     */
+    boolean canGetCacheStore();
+
 }

ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/Factory.java

@@ -0,0 +1,50 @@
+/*
+ * Copyright (C) 2020  LamGC
+ *
+ * ContentGrabbingJi is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * ContentGrabbingJi is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package net.lamgc.cgj.bot.cache;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * @author LamGC
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Factory {
+
+    /**
+     * Cache 模块名称.
+     * @return 返回实现模块名称.
+     */
+    String name();
+
+    /**
+     * CacheStore 优先级.
+     * <p>最终所使用的 CacheStoreFactory 将会根据其优先级进行选择.
+     * 当优先级高的 Factory 表示无法创建 CacheStore 时, 将会寻找比该 Factory 优先级较低的下一个 Factory 并尝试获取,
+     * 重复该过程直到找到能使用的 Factory, 或者使用缺省的 CacheStore-local.
+     *
+     * <p>注意: 即使优先级超过 {@linkplain FactoryPriority#PRIORITY_HIGHEST 10} 也会被视为 10,
+     * 同样的, 即使优先级低于 {@linkplain FactoryPriority#PRIORITY_LOWEST 0} 也会被视为 0.
+     * @return 返回优先级, 最低优先级为 0, 优先级越高, 越会优先选择, 除非无法使用.
+     */
+    int priority() default FactoryPriority.PRIORITY_NORMAL;
+
+}

ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/FactoryPriority.java

@@ -0,0 +1,56 @@
+/*
+ * Copyright (C) 2020  LamGC
+ *
+ * ContentGrabbingJi is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * ContentGrabbingJi is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package net.lamgc.cgj.bot.cache;
+
+/**
+ * Factory 优先级常量.
+ * @author LamGC
+ */
+public final class FactoryPriority {
+
+    /**
+     * 最高优先级
+     * <p> 优先级数值: 10
+     */
+    public final static int PRIORITY_HIGHEST = 10;
+
+    /**
+     * 较高优先级
+     * <p> 优先级数值: 8
+     */
+    public final static int PRIORITY_HIGHER = 8;
+
+    /**
+     * 普通优先级
+     * <p> 优先级数值: 5
+     */
+    public final static int PRIORITY_NORMAL = 5;
+
+    /**
+     * 较低优先级
+     * <p> 优先级数值: 3
+     */
+    public final static int PRIORITY_LOWER = 3;
+
+    /**
+     * 最高优先级
+     * <p> 优先级数值: 0
+     */
+    public final static int PRIORITY_LOWEST = 0;
+    
+}

ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/exception/GetCacheStoreException.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright (C) 2020  LamGC
+ *
+ * ContentGrabbingJi is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * ContentGrabbingJi is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package net.lamgc.cgj.bot.cache.exception;
+
+/**
+ * 获取 CacheStore 异常.
+ * <p>当无法获取 CacheStore 时抛出.
+ * @author LamGC
+ */
+public class GetCacheStoreException extends RuntimeException {
+
+    public GetCacheStoreException(String message) {
+        super(message);
+    }
+
+    public GetCacheStoreException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}