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 6786226..a1ec36b 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 @@ -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 对象时抛出, 需说明失败原因. */ - SingleCacheStore newSingleCacheStore(String identify, StringConverter converter); + SingleCacheStore newSingleCacheStore(String identify, StringConverter converter) throws GetCacheStoreException; /** * 获取一个新的有序列表缓存存储容器. @@ -41,8 +43,9 @@ public interface CacheStoreFactory { * @param converter 元素类型与 String 的转换器. * @param 元素类型. * @return 返回新的有序列表缓存存储容器. + * @throws GetCacheStoreException 当 Factory 无法返回 CacheStore 对象时抛出, 需说明失败原因. */ - ListCacheStore newListCacheStore(String identify, StringConverter converter); + ListCacheStore newListCacheStore(String identify, StringConverter converter) throws GetCacheStoreException; /** * 获取一个新的无序集合缓存存储容器. @@ -50,8 +53,9 @@ public interface CacheStoreFactory { * @param converter 元素类型与 String 的转换器. * @param 元素类型. * @return 返回新的无序集合缓存存储容器. + * @throws GetCacheStoreException 当 Factory 无法返回 CacheStore 对象时抛出, 需说明失败原因. */ - SetCacheStore newSetCacheStore(String identify, StringConverter converter); + SetCacheStore newSetCacheStore(String identify, StringConverter converter) throws GetCacheStoreException; /** * 获取一个新的映射表缓存存储容器. @@ -59,6 +63,21 @@ public interface CacheStoreFactory { * @param converter 字段值类型与 String 的转换器. * @param 字段值类型. * @return 返回新的映射表缓存存储容器. + * @throws GetCacheStoreException 当 Factory 无法返回 CacheStore 对象时抛出, 需说明失败原因. */ - MapCacheStore newMapCacheStore(String identify, StringConverter converter); + MapCacheStore newMapCacheStore(String identify, StringConverter converter) throws GetCacheStoreException; + + /** + * 当前是否可以创建 {@link CacheStore} + * + *

如果返回 true, 将会使用该 Factory. + * 如果返回 false 或抛出异常, 将不会通过该 Factory 创建 CacheStore, + * + *

除非模块能保证 Factory 正常情况下一定能提供 CacheStore 对象, + * 否则请不要尝试永远返回 true 来向应用保证 Factory 一定能创建 CacheStore, 保持 Factory 的有效性, + * 一旦后续创建 CacheStore 时发生异常, 将视为无法创建. + * @return 如果可以, 返回 true. + */ + boolean canGetCacheStore(); + } diff --git a/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/Factory.java b/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/Factory.java new file mode 100644 index 0000000..ead8fbc --- /dev/null +++ b/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 . + */ + +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 优先级. + *

最终所使用的 CacheStoreFactory 将会根据其优先级进行选择. + * 当优先级高的 Factory 表示无法创建 CacheStore 时, 将会寻找比该 Factory 优先级较低的下一个 Factory 并尝试获取, + * 重复该过程直到找到能使用的 Factory, 或者使用缺省的 CacheStore-local. + * + *

注意: 即使优先级超过 {@linkplain FactoryPriority#PRIORITY_HIGHEST 10} 也会被视为 10, + * 同样的, 即使优先级低于 {@linkplain FactoryPriority#PRIORITY_LOWEST 0} 也会被视为 0. + * @return 返回优先级, 最低优先级为 0, 优先级越高, 越会优先选择, 除非无法使用. + */ + int priority() default FactoryPriority.PRIORITY_NORMAL; + +} diff --git a/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/FactoryPriority.java b/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/FactoryPriority.java new file mode 100644 index 0000000..62e049f --- /dev/null +++ b/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 . + */ + +package net.lamgc.cgj.bot.cache; + +/** + * Factory 优先级常量. + * @author LamGC + */ +public final class FactoryPriority { + + /** + * 最高优先级 + *

优先级数值: 10 + */ + public final static int PRIORITY_HIGHEST = 10; + + /** + * 较高优先级 + *

优先级数值: 8 + */ + public final static int PRIORITY_HIGHER = 8; + + /** + * 普通优先级 + *

优先级数值: 5 + */ + public final static int PRIORITY_NORMAL = 5; + + /** + * 较低优先级 + *

优先级数值: 3 + */ + public final static int PRIORITY_LOWER = 3; + + /** + * 最高优先级 + *

优先级数值: 0 + */ + public final static int PRIORITY_LOWEST = 0; + +} diff --git a/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/exception/GetCacheStoreException.java b/ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/exception/GetCacheStoreException.java new file mode 100644 index 0000000..d2774d7 --- /dev/null +++ b/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 . + */ + +package net.lamgc.cgj.bot.cache.exception; + +/** + * 获取 CacheStore 异常. + *

当无法获取 CacheStore 时抛出. + * @author LamGC + */ +public class GetCacheStoreException extends RuntimeException { + + public GetCacheStoreException(String message) { + super(message); + } + + public GetCacheStoreException(String message, Throwable cause) { + super(message, cause); + } +}