From 4f877a03c2c0738dbd3e81b8fc6a1dce9bf878c0 Mon Sep 17 00:00:00 2001 From: LamGC Date: Sat, 12 Sep 2020 02:58:59 +0800 Subject: [PATCH] =?UTF-8?q?[Add][Change]=20CacheStore-api=20=E8=B0=83?= =?UTF-8?q?=E6=95=B4=20CacheStoreFactory=20=E7=9A=84=E6=96=B9=E6=B3=95?= =?UTF-8?q?=E4=BF=A1=E6=81=AF;?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [Add] Factory 添加注解以设置固定信息; [Add] FactoryPriority 添加优先级常量类; [Add] GetCacheStoreException 增加异常以表示无法获取 CacheStore 对象; [Change] CacheStoreFactory 增加'canGetCacheStore'方法, 调整方法签名以允许抛出异常; --- .../cgj/bot/cache/CacheStoreFactory.java | 27 +++++++-- .../java/net/lamgc/cgj/bot/cache/Factory.java | 50 +++++++++++++++++ .../lamgc/cgj/bot/cache/FactoryPriority.java | 56 +++++++++++++++++++ .../exception/GetCacheStoreException.java | 34 +++++++++++ 4 files changed, 163 insertions(+), 4 deletions(-) create mode 100644 ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/Factory.java create mode 100644 ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/FactoryPriority.java create mode 100644 ContentGrabbingJi-CacheStore-api/src/main/java/net/lamgc/cgj/bot/cache/exception/GetCacheStoreException.java 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); + } +}