diff --git a/src/main/java/xyz/zhouxy/plusone/commons/base/IWithCode.java b/src/main/java/xyz/zhouxy/plusone/commons/base/IWithCode.java index 5633567..7ff805c 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/base/IWithCode.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/base/IWithCode.java @@ -29,21 +29,50 @@ import javax.annotation.Nullable; * @author ZhouXY */ public interface IWithCode { + + /** + * 获取码值 + * @return 码值 + */ @Nonnull T getCode(); + /** + * 判断 {@code code} 与给定的值是否相等 + * + * @param code 用于判断的值 + * @return 判断结果 + */ default boolean isCodeEquals(@Nullable T code) { return Objects.equals(getCode(), code); } + /** + * 判断是否与给定的 {@link IWithCode} 有着相等的 {@code code} + * + * @param other 用于比较的对象 + * @return 判断结果 + */ default boolean isSameCodeAs(@Nullable IWithCode other) { return other != null && Objects.equals(getCode(), other.getCode()); } + /** + * 判断是否与给定的 {@link IWithIntCode} 有着相等的 {@code code} + * + * @param other 用于比较的对象 + * @return 判断结果 + */ default boolean isSameCodeAs(@Nullable IWithIntCode other) { return other != null && Objects.equals(getCode(), other.getCode()); } + /** + * 判断是否与给定的 {@link IWithLongCode} 有着相等的 {@code code} + * + * @param other 用于比较的对象 + * @return 判断结果 + */ default boolean isSameCodeAs(@Nullable IWithLongCode other) { return other != null && Objects.equals(getCode(), other.getCode()); } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/base/IWithIntCode.java b/src/main/java/xyz/zhouxy/plusone/commons/base/IWithIntCode.java index 3e881cc..34454fb 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/base/IWithIntCode.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/base/IWithIntCode.java @@ -28,20 +28,49 @@ import javax.annotation.Nullable; * @author ZhouXY */ public interface IWithIntCode { + + /** + * 获取码值 + * @return 码值 + */ int getCode(); + /** + * 判断 {@code code} 与给定的值是否相等 + * + * @param code 用于判断的值 + * @return 判断结果 + */ default boolean isCodeEquals(int code) { return getCode() == code; } + /** + * 判断是否与给定的 {@link IWithCode} 有着相等的 {@code code} + * + * @param other 用于比较的对象 + * @return 判断结果 + */ default boolean isSameCodeAs(@Nullable IWithCode other) { return other != null && Objects.equals(getCode(), other.getCode()); } + /** + * 判断是否与给定的 {@link IWithIntCode} 有着相等的 {@code code} + * + * @param other 用于比较的对象 + * @return 判断结果 + */ default boolean isSameCodeAs(@Nullable IWithIntCode other) { return other != null && getCode() == other.getCode(); } + /** + * 判断是否与给定的 {@link IWithLongCode} 有着相等的 {@code code} + * + * @param other 用于比较的对象 + * @return 判断结果 + */ default boolean isSameCodeAs(@Nullable IWithLongCode other) { return other != null && getCode() == other.getCode(); } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/base/IWithLongCode.java b/src/main/java/xyz/zhouxy/plusone/commons/base/IWithLongCode.java index b10d8a2..0cfd9f2 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/base/IWithLongCode.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/base/IWithLongCode.java @@ -28,20 +28,49 @@ import javax.annotation.Nullable; * @author ZhouXY */ public interface IWithLongCode { + + /** + * 获取码值 + * @return 码值 + */ long getCode(); + /** + * 判断 {@code code} 与给定的值是否相等 + * + * @param code 用于判断的值 + * @return 判断结果 + */ default boolean isCodeEquals(long code) { return getCode() == code; } + /** + * 判断是否与给定的 {@link IWithCode} 有着相等的 {@code code} + * + * @param other 用于比较的对象 + * @return 判断结果 + */ default boolean isSameCodeAs(@Nullable IWithCode other) { return other != null && Objects.equals(getCode(), other.getCode()); } + /** + * 判断是否与给定的 {@link IWithIntCode} 有着相等的 {@code code} + * + * @param other 用于比较的对象 + * @return 判断结果 + */ default boolean isSameCodeAs(@Nullable IWithIntCode other) { return other != null && getCode() == other.getCode(); } + /** + * 判断是否与给定的 {@link IWithLongCode} 有着相等的 {@code code} + * + * @param other 用于比较的对象 + * @return 判断结果 + */ default boolean isSameCodeAs(@Nullable IWithLongCode other) { return other != null && getCode() == other.getCode(); } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/base/Ref.java b/src/main/java/xyz/zhouxy/plusone/commons/base/Ref.java index e5243b4..baca94f 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/base/Ref.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/base/Ref.java @@ -79,43 +79,100 @@ public final class Ref { this.value = value; } + /** + * 创建对象引用 + * + * @param 引用的类型 + * @param value 引用的对象 + * @return {@code Ref} 对象 + */ public static Ref of(@Nullable T value) { return new Ref<>(value); } + /** + * 创建空引用 + * + * @param 引用的类型 + * @return 空引用 + */ public static Ref empty() { return new Ref<>(null); } + /** + * 获取引用的对象 + * + * @return 引用的对象 + */ @Nullable public T getValue() { return value; } + /** + * 设置引用的对象 + * + * @param value 要引用的对象 + */ public void setValue(@Nullable T value) { this.value = value; } + /** + * 使用 {@link UnaryOperator} 修改 {@code Ref} 内部引用的对象 + * + * @param operator 修改逻辑 + */ public void transformValue(UnaryOperator operator) { this.value = operator.apply(this.value); } + /** + * 使用 {@link Function} 修改所引用的对象，返回新的 {@code Ref} + * + * @param 结果的引用类型 + * @param function 修改逻辑 + * @return 修改后的对象的引用 + */ public Ref transform(Function function) { return Ref.of(function.apply(this.value)); } + /** + * 使用 {@link Predicate} 检查引用的对象 + * + * @param predicate 判断逻辑 + * @return 判断结果 + */ public boolean checkValue(Predicate predicate) { return predicate.test(this.value); } + /** + * 将引用的对象作为入参，执行 {@link Consumer} 的逻辑 + * + * @param consumer 要执行的逻辑 + */ public void execute(Consumer consumer) { consumer.accept(value); } + /** + * 判断所引用的对象是否为 {@code null} + * + * @return 是否为 {@code null} + */ public boolean isNull() { return this.value == null; } + + /** + * 判断所引用的对象是否不为 {@code null} + * + * @return 是否不为 {@code null} + */ public boolean isNotNull() { return this.value != null; } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/collection/CollectionTools.java b/src/main/java/xyz/zhouxy/plusone/commons/collection/CollectionTools.java index 25d3e73..8ec13b4 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/collection/CollectionTools.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/collection/CollectionTools.java @@ -42,26 +42,62 @@ public class CollectionTools { // #region - isEmpty // ================================ + /** + * 判断集合是否为空 + * + * @param collection 集合 + * @return 是否为空 + */ public static boolean isEmpty(@Nullable Collection collection) { return collection == null || collection.isEmpty(); } + /** + * 判断集合是否为空 + * + * @param map 集合 + * @return 是否为空 + */ public static boolean isEmpty(@Nullable Map map) { return map == null || map.isEmpty(); } + /** + * 判断集合是否为空 + * + * @param table 集合 + * @return 是否为空 + */ public static boolean isEmpty(@Nullable Table table) { return table == null || table.isEmpty(); } + /** + * 判断集合是否为空 + * + * @param map 集合 + * @return 是否为空 + */ public static boolean isEmpty(@Nullable Multimap map) { return map == null || map.isEmpty(); } + /** + * 判断集合是否为空 + * + * @param set 集合 + * @return 是否为空 + */ public static boolean isEmpty(@Nullable Multiset set) { return set == null || set.isEmpty(); } + /** + * 判断集合是否为空 + * + * @param set 集合 + * @return 是否为空 + */ public static boolean isEmpty(@Nullable RangeSet set) { return set == null || set.isEmpty(); } @@ -74,26 +110,62 @@ public class CollectionTools { // #region - isNotEmpty // ================================ + /** + * 判断集合是否不为空 + * + * @param collection 集合 + * @return 是否不为空 + */ public static boolean isNotEmpty(@Nullable Collection collection) { return collection != null && !collection.isEmpty(); } + /** + * 判断集合是否不为空 + * + * @param map 集合 + * @return 是否不为空 + */ public static boolean isNotEmpty(@Nullable Map map) { return map != null && !map.isEmpty(); } + /** + * 判断集合是否不为空 + * + * @param table 集合 + * @return 是否不为空 + */ public static boolean isNotEmpty(@Nullable Table table) { return table != null && !table.isEmpty(); } + /** + * 判断集合是否不为空 + * + * @param map 集合 + * @return 是否不为空 + */ public static boolean isNotEmpty(@Nullable Multimap map) { return map != null && !map.isEmpty(); } + /** + * 判断集合是否不为空 + * + * @param set 集合 + * @return 是否不为空 + */ public static boolean isNotEmpty(@Nullable Multiset set) { return set != null && !set.isEmpty(); } + /** + * 判断集合是否不为空 + * + * @param set 集合 + * @return 是否不为空 + */ public static boolean isNotEmpty(@Nullable RangeSet set) { return set != null && !set.isEmpty(); } @@ -106,16 +178,41 @@ public class CollectionTools { // #region - nullToEmpty // ================================ + /** + * 将 {@code null} 转为空 {@code List} + * + * @param List 元素的类型 + * @param list list + * @return 如果 {@code list} 为 {@code null}，返回空列表； + * 如果 {@code list} 不为 {@code null}，返回 {@code list} 本身 + */ @Nonnull public static List nullToEmptyList(@Nullable List list) { return list == null ? Collections.emptyList() : list; } + /** + * 将 {@code null} 转为空 {@code Set} + * + * @param Set 元素的类型 + * @param set set + * @return 如果 {@code set} 为 {@code null}，返回空集合； + * 如果 {@code set} 不为 {@code null}，返回 {@code set} 本身 + */ @Nonnull public static Set nullToEmptySet(@Nullable Set set) { return set == null ? Collections.emptySet() : set; } + /** + * 将 {@code null} 转为空 {@code Map} + * + * @param Map 的键的类型 + * @param Map 的值的类型 + * @param map map + * @return 如果 {@code map} 为 {@code null}，返回空集合； + * 如果 {@code map} 不为 {@code null}，返回 {@code map} 本身 + */ @Nonnull public static Map nullToEmptyMap(@Nullable Map map) { return map == null ? Collections.emptyMap() : map; diff --git a/src/main/java/xyz/zhouxy/plusone/commons/exception/DataNotExistsException.java b/src/main/java/xyz/zhouxy/plusone/commons/exception/DataNotExistsException.java index 4c6bea0..fb2e915 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/exception/DataNotExistsException.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/exception/DataNotExistsException.java @@ -26,18 +26,40 @@ public final class DataNotExistsException extends Exception { private static final long serialVersionUID = 6536955800679703111L; + /** + * 使用默认 message 构造新的 {@code DataNotExistsException}。 + * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。 + */ public DataNotExistsException() { super(); } + /** + * 使用指定的 {@code message} 构造新的 {@code DataNotExistsException}。 + * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。 + * + * @param message 异常信息 + */ public DataNotExistsException(String message) { super(message); } + /** + * 使用指定的 {@code cause} 构造新的 {@code DataNotExistsException}。 + * {@code message} 为 (cause==null ? null : cause.toString())。 + * + * @param cause 包装的异常 + */ public DataNotExistsException(Throwable cause) { super(cause); } + /** + * 使用指定的 {@code message} 和 {@code cause} 构造新的 {@code DataNotExistsException}。 + * + * @param message 异常信息 + * @param cause 包装的异常 + */ public DataNotExistsException(String message, Throwable cause) { super(message, cause); } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/exception/MultiTypesException.java b/src/main/java/xyz/zhouxy/plusone/commons/exception/MultiTypesException.java index 60156c7..0b5cfd6 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/exception/MultiTypesException.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/exception/MultiTypesException.java @@ -124,26 +124,66 @@ import xyz.zhouxy.plusone.commons.base.IWithCode; */ public interface MultiTypesException> { + /** + * 异常类型 + * + * @return 异常类型。通常是实现了 {@link ExceptionType} 的枚举。 + */ @Nonnull T getType(); + /** + * 获取异常类型编码 + * + * @return 异常类型编码 + */ default @Nonnull String getTypeCode() { return getType().getCode(); } + /** + * 异常类型 + */ public static interface ExceptionType extends IWithCode { + /** + * 默认异常信息 + */ String getDefaultMessage(); + /** + * 创建异常 + * + * @return 异常对象 + */ @Nonnull E create(); + /** + * 使用指定 {@code message} 创建异常 + * + * @param message 异常信息 + * @return 异常对象 + */ @Nonnull E create(String message); + /** + * 使用指定 {@code cause} 创建异常 + * + * @param cause 包装的异常 + * @return 异常对象 + */ @Nonnull E create(Throwable cause); + /** + * 使用指定 {@code message} 和 {@code cause} 创建异常 + * + * @param message 异常信息 + * @param cause 包装的异常 + * @return 异常对象 + */ @Nonnull E create(String message, Throwable cause); diff --git a/src/main/java/xyz/zhouxy/plusone/commons/exception/ParsingFailureException.java b/src/main/java/xyz/zhouxy/plusone/commons/exception/ParsingFailureException.java index af59d7c..6bd080e 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/exception/ParsingFailureException.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/exception/ParsingFailureException.java @@ -59,22 +59,56 @@ public final class ParsingFailureException this.type = type; } + /** + * 创建默认类型的 {@code ParsingFailureException}。 + * {@code type} 为 {@link Type#DEFAULT}， + * {@code message} 为 {@link Type#DEFAULT} 的默认信息。 + * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。 + */ public ParsingFailureException() { this(Type.DEFAULT, Type.DEFAULT.getDefaultMessage()); } + /** + * 使用指定 {@code message} 创建默认类型的 {@code ParsingFailureException}。 + * {@code type} 为 {@link Type#DEFAULT}， + * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。 + * + * @param message 异常信息 + */ public ParsingFailureException(String message) { this(Type.DEFAULT, message); } + /** + * 使用指定的 {@code cause} 创建默认类型的 {@code ParsingFailureException}。 + * {@code type} 为 {@link Type#DEFAULT}， + * {@code message} 为 (cause==null ? null : cause.toString())。 + * + * @param cause 包装的异常 + */ public ParsingFailureException(Throwable cause) { this(Type.DEFAULT, cause); } + /** + * 使用指定的 {@code message} 和 {@code cause} 创建默认类型的 {@code ParsingFailureException}。 + * {@code type} 为 {@link Type#DEFAULT}。 + * + * @param message 异常信息 + * @param cause 包装的异常 + */ public ParsingFailureException(String message, Throwable cause) { this(Type.DEFAULT, message, cause); } + /** + * 将 {@link DateTimeParseException} 包装为 {@link ParsingFailureException}。 + * {@code type} 为 {@link Type#DATE_TIME_PARSING_FAILURE}。 + * + * @param cause 包装的 {@code DateTimeParseException} + * @return ParsingFailureException + */ public static ParsingFailureException of(DateTimeParseException cause) { if (cause == null) { return Type.DATE_TIME_PARSING_FAILURE.create(); @@ -82,10 +116,25 @@ public final class ParsingFailureException return Type.DATE_TIME_PARSING_FAILURE.create(cause.getMessage(), cause); } + /** + * 将 {@link DateTimeParseException} 包装为 {@link ParsingFailureException}。 + * {@code type} 为 {@link Type#DATE_TIME_PARSING_FAILURE}。 + * + * @param message 异常信息 + * @param cause 包装的 {@code DateTimeParseException} + * @return ParsingFailureException + */ public static ParsingFailureException of(String message, DateTimeParseException cause) { return Type.DATE_TIME_PARSING_FAILURE.create(message, cause); } + /** + * 将 {@link NumberFormatException} 包装为 {@link ParsingFailureException}。 + * {@code type} 为 {@link Type#NUMBER_PARSING_FAILURE}。 + * + * @param cause 包装的 {@code NumberFormatException} + * @return ParsingFailureException + */ public static ParsingFailureException of(NumberFormatException cause) { if (cause == null) { return Type.NUMBER_PARSING_FAILURE.create(); @@ -93,6 +142,14 @@ public final class ParsingFailureException return Type.NUMBER_PARSING_FAILURE.create(cause.getMessage(), cause); } + /** + * 将 {@link NumberFormatException} 包装为 {@link ParsingFailureException}。 + * {@code type} 为 {@link Type#NUMBER_PARSING_FAILURE}。 + * + * @param message 异常信息 + * @param cause {@code NumberFormatException} + * @return ParsingFailureException + */ public static ParsingFailureException of(String message, NumberFormatException cause) { return Type.NUMBER_PARSING_FAILURE.create(message, cause); } @@ -103,10 +160,15 @@ public final class ParsingFailureException return type; } + /** 默认类型 */ public static final Type DEFAULT = Type.DEFAULT; + /** 数字转换失败 */ public static final Type NUMBER_PARSING_FAILURE = Type.NUMBER_PARSING_FAILURE; + /** 时间解析失败 */ public static final Type DATE_TIME_PARSING_FAILURE = Type.DATE_TIME_PARSING_FAILURE; + /** JSON 解析失败 */ public static final Type JSON_PARSING_FAILURE = Type.JSON_PARSING_FAILURE; + /** XML 解析失败 */ public static final Type XML_PARSING_FAILURE = Type.XML_PARSING_FAILURE; public enum Type implements ExceptionType { diff --git a/src/main/java/xyz/zhouxy/plusone/commons/exception/business/BizException.java b/src/main/java/xyz/zhouxy/plusone/commons/exception/business/BizException.java index f07b49d..5c91910 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/exception/business/BizException.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/exception/business/BizException.java @@ -33,18 +33,40 @@ public class BizException extends RuntimeException { private static final String DEFAULT_MSG = "业务异常"; + /** + * 使用默认 message 构造新的业务异常。 + * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。 + */ public BizException() { super(DEFAULT_MSG); } + /** + * 使用指定的 {@code message} 构造新的业务异常。 + * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。 + * + * @param message 异常信息 + */ public BizException(String message) { super(message); } + /** + * 使用指定的 {@code cause} 构造新的业务异常。 + * {@code message} 为 (cause==null ? null : cause.toString())。 + * + * @param cause 包装的异常 + */ public BizException(Throwable cause) { super(cause); } + /** + * 使用指定的 {@code message} 和 {@code cause} 构造新的业务异常。 + * + * @param message 异常信息 + * @param cause 包装的异常 + */ public BizException(String message, Throwable cause) { super(message, cause); } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/exception/business/InvalidInputException.java b/src/main/java/xyz/zhouxy/plusone/commons/exception/business/InvalidInputException.java index 53fc682..5cf93d9 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/exception/business/InvalidInputException.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/exception/business/InvalidInputException.java @@ -60,18 +60,45 @@ public final class InvalidInputException this.type = type; } + /** + * 创建默认类型的 {@code InvalidInputException}。 + * {@code type} 为 {@link Type#DEFAULT}， + * {@code message} 为 {@link Type#DEFAULT} 的默认信息。 + * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。 + */ public InvalidInputException() { this(Type.DEFAULT); } + /** + * 使用指定 {@code message} 创建默认类型的 {@code InvalidInputException}。 + * {@code type} 为 {@link Type#DEFAULT}， + * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。 + * + * @param message 异常信息 + */ public InvalidInputException(String message) { this(Type.DEFAULT, message); } + /** + * 使用指定的 {@code cause} 创建默认类型的 {@code InvalidInputException}。 + * {@code type} 为 {@link Type#DEFAULT}， + * {@code message} 为 (cause==null ? null : cause.toString())。 + * + * @param cause 包装的异常 + */ public InvalidInputException(Throwable cause) { this(Type.DEFAULT, cause); } + /** + * 使用指定的 {@code message} 和 {@code cause} 创建默认类型的 {@code InvalidInputException}。 + * {@code type} 为 {@link Type#DEFAULT}。 + * + * @param message 异常信息 + * @param cause 包装的异常 + */ public InvalidInputException(String message, Throwable cause) { this(Type.DEFAULT, message, cause); } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/exception/business/RequestParamsException.java b/src/main/java/xyz/zhouxy/plusone/commons/exception/business/RequestParamsException.java index c6e3638..d2dd209 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/exception/business/RequestParamsException.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/exception/business/RequestParamsException.java @@ -30,18 +30,40 @@ public class RequestParamsException extends BizException { private static final String DEFAULT_MSG = "用户请求参数错误"; + /** + * 使用默认 message 构造新的 {@code RequestParamsException}。 + * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。 + */ public RequestParamsException() { super(DEFAULT_MSG); } + /** + * 使用指定的 {@code message} 构造新的 {@code RequestParamsException}。 + * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。 + * + * @param message 异常信息 + */ public RequestParamsException(String message) { super(message); } + /** + * 使用指定的 {@code cause} 构造新的 {@code RequestParamsException}。 + * {@code message} 为 (cause==null ? null : cause.toString())。 + * + * @param cause 包装的异常 + */ public RequestParamsException(Throwable cause) { super(cause); } + /** + * 使用指定的 {@code message} 和 {@code cause} 构造新的 {@code RequestParamsException}。 + * + * @param message 异常信息 + * @param cause 包装的异常 + */ public RequestParamsException(String message, Throwable cause) { super(message, cause); } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/exception/system/DataOperationResultException.java b/src/main/java/xyz/zhouxy/plusone/commons/exception/system/DataOperationResultException.java index bffbeb0..188d294 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/exception/system/DataOperationResultException.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/exception/system/DataOperationResultException.java @@ -35,18 +35,40 @@ public final class DataOperationResultException extends SysException { private static final String DEFAULT_MSG = "数据操作的结果不符合预期"; + /** + * 使用默认 message 构造新的 {@code DataOperationResultException}。 + * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。 + */ public DataOperationResultException() { super(DEFAULT_MSG); } + /** + * 使用指定的 {@code message} 构造新的 {@code DataOperationResultException}。 + * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。 + * + * @param message 异常信息 + */ public DataOperationResultException(String message) { super(message); } + /** + * 使用指定的 {@code cause} 构造新的 {@code DataOperationResultException}。 + * {@code message} 为 (cause==null ? null : cause.toString())。 + * + * @param cause 包装的异常 + */ public DataOperationResultException(Throwable cause) { super(cause); } + /** + * 使用指定的 {@code message} 和 {@code cause} 构造新的 {@code DataOperationResultException}。 + * + * @param message 异常信息 + * @param cause 包装的异常 + */ public DataOperationResultException(String message, Throwable cause) { super(message, cause); } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/exception/system/NoAvailableMacFoundException.java b/src/main/java/xyz/zhouxy/plusone/commons/exception/system/NoAvailableMacFoundException.java index a02ffc6..d31d89f 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/exception/system/NoAvailableMacFoundException.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/exception/system/NoAvailableMacFoundException.java @@ -29,18 +29,40 @@ package xyz.zhouxy.plusone.commons.exception.system; public class NoAvailableMacFoundException extends SysException { private static final long serialVersionUID = 152827098461071551L; + /** + * 使用默认 message 构造新的 {@code NoAvailableMacFoundException}。 + * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。 + */ public NoAvailableMacFoundException() { super(); } + /** + * 使用指定的 {@code message} 构造新的 {@code NoAvailableMacFoundException}。 + * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。 + * + * @param message 异常信息 + */ public NoAvailableMacFoundException(String message) { super(message); } + /** + * 使用指定的 {@code cause} 构造新的 {@code NoAvailableMacFoundException}。 + * {@code message} 为 (cause==null ? null : cause.toString())。 + * + * @param cause 包装的异常 + */ public NoAvailableMacFoundException(Throwable cause) { super(cause); } + /** + * 使用指定的 {@code message} 和 {@code cause} 构造新的 {@code NoAvailableMacFoundException}。 + * + * @param message 异常信息 + * @param cause 包装的异常 + */ public NoAvailableMacFoundException(String message, Throwable cause) { super(message, cause); } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/exception/system/SysException.java b/src/main/java/xyz/zhouxy/plusone/commons/exception/system/SysException.java index a0e9b3c..a63d11b 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/exception/system/SysException.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/exception/system/SysException.java @@ -30,18 +30,40 @@ public class SysException extends RuntimeException { private static final String DEFAULT_MSG = "系统异常"; + /** + * 使用默认 message 构造新的系统异常。 + * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。 + */ public SysException() { super(DEFAULT_MSG); } + /** + * 使用指定的 {@code message} 构造新的系统异常。 + * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。 + * + * @param message 异常信息 + */ public SysException(String message) { super(message); } + /** + * 使用指定的 {@code cause} 构造新的系统异常。 + * {@code message} 为 (cause==null ? null : cause.toString())。 + * + * @param cause 包装的异常 + */ public SysException(Throwable cause) { super(cause); } + /** + * 使用指定的 {@code message} 和 {@code cause} 构造新的系统异常。 + * + * @param message 异常信息 + * @param cause 包装的异常 + */ public SysException(String message, Throwable cause) { super(message, cause); } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/function/BoolUnaryOperator.java b/src/main/java/xyz/zhouxy/plusone/commons/function/BoolUnaryOperator.java index eccef15..6da0f7e 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/function/BoolUnaryOperator.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/function/BoolUnaryOperator.java @@ -18,11 +18,35 @@ package xyz.zhouxy.plusone.commons.function; import com.google.common.annotations.Beta; +/** + * BoolUnaryOperator + * + *

+ * 一个特殊的 {@link java.util.function.UnaryOperator}。 + * 表示对 {@code boolean} 值的一元操作。 + *

+ * + * @author ZhouXY + * @since 1.0.0 + * @see java.util.function.UnaryOperator + */ @Beta @FunctionalInterface public interface BoolUnaryOperator { + + /** + * 将此函数应用于给定的 {@code boolean} 参数，返回一个 {@code boolean} 结果。 + * + * @param operand 操作数 + * @return 结果 + */ boolean applyAsBool(boolean operand); + /** + * 返回一个 {@code BoolUnaryOperator}，该操作符将给定的操作数取反。 + * + * @return {@code BoolUnaryOperator} + */ static BoolUnaryOperator not() { return b -> !b; } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/function/CharUnaryOperator.java b/src/main/java/xyz/zhouxy/plusone/commons/function/CharUnaryOperator.java index e9ca630..4368c68 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/function/CharUnaryOperator.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/function/CharUnaryOperator.java @@ -18,8 +18,27 @@ package xyz.zhouxy.plusone.commons.function; import com.google.common.annotations.Beta; +/** + * CharUnaryOperator + * + *

+ * 一个特殊的 {@link java.util.function.UnaryOperator}。 + * 表示对 {@code char} 的一元操作。 + *

+ * + * @author ZhouXY + * @since 1.0.0 + * @see java.util.function.UnaryOperator + */ @Beta @FunctionalInterface public interface CharUnaryOperator { + + /** + * 将此函数应用于给定的 {@code char} 参数，返回一个 {@code char} 结果。 + * + * @param operand 操作数 + * @return 结果 + */ char applyAsChar(char operand); } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/function/Executable.java b/src/main/java/xyz/zhouxy/plusone/commons/function/Executable.java index a8677ec..99746ef 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/function/Executable.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/function/Executable.java @@ -16,9 +16,26 @@ package xyz.zhouxy.plusone.commons.function; +/** + * Executable + * + *

+ * 表示一个无入参无返回值的操作，可抛出异常。 + *

+ * + * @param 可抛出的异常类型 + * + * @author ZhouXY + * @since 1.0.0 + */ @FunctionalInterface public interface Executable { + /** + * 执行 + * + * @throws E 可抛出的异常 + */ void execute() throws E; } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/function/OptionalSupplier.java b/src/main/java/xyz/zhouxy/plusone/commons/function/OptionalSupplier.java index ac572b3..fa931bb 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/function/OptionalSupplier.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/function/OptionalSupplier.java @@ -24,6 +24,7 @@ import java.util.function.Supplier; * *

* 返回 {@code Optional<T>} 对象。 + *

* * @author ZhouXY * @since 1.0.0 diff --git a/src/main/java/xyz/zhouxy/plusone/commons/function/ThrowingConsumer.java b/src/main/java/xyz/zhouxy/plusone/commons/function/ThrowingConsumer.java index 51d3984..a05f6c7 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/function/ThrowingConsumer.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/function/ThrowingConsumer.java @@ -16,13 +16,24 @@ package xyz.zhouxy.plusone.commons.function; +/** + * ThrowingConsumer + * + *

+ * 允许抛出异常的消费操作。是一个特殊的 {@link java.util.function.Consumer}。 + *

+ * + * @author ZhouXY + * @since 1.0.0 + * @see java.util.function.Consumer + */ @FunctionalInterface public interface ThrowingConsumer { /** - * Consume the supplied argument, potentially throwing an exception. + * 消费给定的参数，允许抛出异常 * - * @param t the argument to consume + * @param t 要消费的参数 */ void accept(T t) throws E; diff --git a/src/main/java/xyz/zhouxy/plusone/commons/function/ThrowingFunction.java b/src/main/java/xyz/zhouxy/plusone/commons/function/ThrowingFunction.java index 08ed960..4072715 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/function/ThrowingFunction.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/function/ThrowingFunction.java @@ -15,14 +15,29 @@ */ package xyz.zhouxy.plusone.commons.function; +/** + * ThrowingFunction + * + *

+ * 接收一个参数，并返回一个结果，可以抛出异常。 + *

+ * + * @param 入参类型 + * @param 返回结果类型 + * @param 异常类型 + * + * @author ZhouXY + * @since 1.0 + * @see java.util.function.Function + */ @FunctionalInterface public interface ThrowingFunction { /** - * Applies this function to the given argument. + * 接收一个参数，并返回一个结果，可以抛出异常。 * - * @param t the function argument - * @return the function result + * @param t 入参 + * @return 函数结果 */ R apply(T t) throws E; diff --git a/src/main/java/xyz/zhouxy/plusone/commons/function/ThrowingPredicate.java b/src/main/java/xyz/zhouxy/plusone/commons/function/ThrowingPredicate.java index b886db6..09e69b3 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/function/ThrowingPredicate.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/function/ThrowingPredicate.java @@ -16,15 +16,25 @@ package xyz.zhouxy.plusone.commons.function; +/** + * ThrowingPredicate + * + *

+ * 接收一个参数，返回一个布尔值，可抛出异常。 + *

+ * + * @author ZhouXY + * @since 1.0.0 + * @see java.util.function.Predicate + */ @FunctionalInterface public interface ThrowingPredicate { /** - * Evaluates this predicate on the given argument. + * 对给定的参数进行评估 * - * @param t the input argument - * @return {@code true} if the input argument matches the predicate, - * otherwise {@code false} + * @param t 入参 + * @return 入参符合条件时返回 {@code true}，否则返回 {@code false} */ boolean test(T t) throws E; } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/function/ThrowingSupplier.java b/src/main/java/xyz/zhouxy/plusone/commons/function/ThrowingSupplier.java index 8fb335c..a2b2f24 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/function/ThrowingSupplier.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/function/ThrowingSupplier.java @@ -16,13 +16,27 @@ package xyz.zhouxy.plusone.commons.function; +/** + * ThrowingSupplier + * + *

+ * 允许抛出异常的 Supplier 接口。 + *

+ * + * @param 结果类型 + * @param 异常类型 + * + * @author ZhouXY + * @since 1.0.0 + * @see java.util.function.Supplier + */ @FunctionalInterface public interface ThrowingSupplier { /** - * Get a result, potentially throwing an exception. + * 获取一个结果，允许抛出异常。 * - * @return a result + * @return 结果 */ T get() throws E; diff --git a/src/main/java/xyz/zhouxy/plusone/commons/model/Chinese2ndGenIDCardNumber.java b/src/main/java/xyz/zhouxy/plusone/commons/model/Chinese2ndGenIDCardNumber.java index 2506950..c93751a 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/model/Chinese2ndGenIDCardNumber.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/model/Chinese2ndGenIDCardNumber.java @@ -79,6 +79,12 @@ public class Chinese2ndGenIDCardNumber this.birthDate = birthDate; } + /** + * 根据身份证号码创建 {@code Chinese2ndGenIDCardNumber} 对象 + * + * @param idCardNumber 身份证号码值 + * @return {@code Chinese2ndGenIDCardNumber} 对象 + */ public static Chinese2ndGenIDCardNumber of(final String idCardNumber) { try { AssertTools.checkArgument(StringTools.isNotBlank(idCardNumber), "二代居民身份证校验失败：号码为空"); @@ -120,36 +126,71 @@ public class Chinese2ndGenIDCardNumber return value; } + /** + * 所属省份代码 + * + * @return 所属省份代码 + */ @ReaderMethod public String getProvinceCode() { return provinceCode; } + /** + * 所属省份名称 + * + * @return 所属省份名称 + */ @ReaderMethod public String getProvinceName() { return PROVINCE_CODES.get(this.provinceCode); } + /** + * 所属省份完整行政区划代码 + * + * @return 所属省份完整行政区划代码 + */ @ReaderMethod public String getFullProvinceCode() { return Strings.padEnd(this.provinceCode, 12, '0'); } + /** + * 所属市级代码 + * + * @return 所属市级代码 + */ @ReaderMethod public String getCityCode() { return cityCode; } + /** + * 所属市级完整行政区划代码 + * + * @return 所属市级完整行政区划代码 + */ @ReaderMethod public String getFullCityCode() { return Strings.padEnd(this.cityCode, 12, '0'); } + /** + * 所属县级代码 + * + * @return 所属县级代码 + */ @ReaderMethod public String getCountyCode() { return countyCode; } + /** + * 所属县级完整行政区划代码 + * + * @return 所属县级完整行政区划代码 + */ @ReaderMethod public String getFullCountyCode() { return Strings.padEnd(this.countyCode, 12, '0'); diff --git a/src/main/java/xyz/zhouxy/plusone/commons/model/Gender.java b/src/main/java/xyz/zhouxy/plusone/commons/model/Gender.java index 7922305..5fffc82 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/model/Gender.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/model/Gender.java @@ -43,20 +43,41 @@ public enum Gender implements IWithIntCode { this.displayNameZh = displayNameZh; } + /** + * 根据码值获取对应枚举 + * + * @param value 码值 + * @return 枚举值 + */ public static Gender of(int value) { AssertTools.checkCondition(0 <= value && value < VALUES.length, () -> new EnumConstantNotPresentException(Gender.class, String.valueOf(value))); return VALUES[value]; } + /** + * 获取枚举码值 + * + * @return 码值 + */ public int getValue() { return value; } + /** + * 枚举名称 + * + * @return 枚举名称 + */ public String getDisplayName() { return displayName; } + /** + * 枚举中文名称 + * + * @return 枚举中文名称 + */ public String getDisplayNameZh() { return displayNameZh; } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/model/IDCardNumber.java b/src/main/java/xyz/zhouxy/plusone/commons/model/IDCardNumber.java index 2277246..1623650 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/model/IDCardNumber.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/model/IDCardNumber.java @@ -30,20 +30,31 @@ public interface IDCardNumber { static final int DEFAULT_DISPLAY_FRONT = 1; static final int DEFAULT_DISPLAY_END = 2; + /** + * 身份证号 + * + * @return 身份证号 + */ String value(); /** * 根据身份证号判断性别 + * + * @return {@link Gender} 对象 */ Gender getGender(); /** * 获取出生日期 + * + * @return 出生日期 */ LocalDate getBirthDate(); /** * 计算年龄 + * + * @return 年龄 */ default int getAge() { LocalDate now = LocalDate.now(); @@ -54,14 +65,34 @@ public interface IDCardNumber { // #region - toString // ================================ + /** + * 脱敏字符串（前面留 1 位，后面留 2 位） + * + * @return 脱敏字符串 + */ default String toDesensitizedString() { return StringTools.desensitize(value(), DEFAULT_REPLACED_CHAR, DEFAULT_DISPLAY_FRONT, DEFAULT_DISPLAY_END); } + /** + * 脱敏字符串 + * + * @param front 前面保留的字符数 + * @param end 后面保留的字符数 + * @return 脱敏字符串 + */ default String toDesensitizedString(int front, int end) { return StringTools.desensitize(value(), DEFAULT_REPLACED_CHAR, front, end); } + /** + * 脱敏字符串 + * + * @param replacedChar 替换字符 + * @param front 前面保留的字符数 + * @param end 后面保留的字符数 + * @return 脱敏字符串 + */ default String toDesensitizedString(char replacedChar, int front, int end) { return StringTools.desensitize(value(), replacedChar, front, end); } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/model/ValidatableStringRecord.java b/src/main/java/xyz/zhouxy/plusone/commons/model/ValidatableStringRecord.java index 5ab9ee4..9f013de 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/model/ValidatableStringRecord.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/model/ValidatableStringRecord.java @@ -36,7 +36,7 @@ import xyz.zhouxy.plusone.commons.util.AssertTools; * @deprecated 弃用。使用工厂方法创建对象，并在其中进行校验即可。 */ @Deprecated -public abstract class ValidatableStringRecord> +public abstract class ValidatableStringRecord> // NOSONAR 暂不删除 implements Comparable { @Nonnull @@ -44,15 +44,35 @@ public abstract class ValidatableStringRecord errorMessageSupplier) { this(value, pattern, errorMessageSupplier.get()); } + /** + * 构造字符串值对象 + * + * @param value 字符串值 + * @param pattern 正则 + * @param errorMessage 正则不匹配时的错误信息 + */ protected ValidatableStringRecord(String value, Pattern pattern, String errorMessage) { AssertTools.checkArgument(Objects.nonNull(value), "The value cannot be null."); AssertTools.checkArgument(Objects.nonNull(pattern), "The pattern cannot be null."); @@ -99,6 +119,11 @@ public abstract class ValidatableStringRecord { this.total = total; } + /** + * 创建一个分页查询的结果 + * + * @param 内容类型 + * @param content 一页数据 + * @param total 总数据量 + * @return 分页查询的结果 + */ @StaticFactoryMethod(PageResult.class) public static PageResult of(@Nullable final List content, final long total) { return new PageResult<>(content, total); } + /** + * 创建一个空的分页查询的结果 + * + * @param 内容类型 + * @return 空结果 + */ @StaticFactoryMethod(PageResult.class) public static PageResult empty() { return new PageResult<>(Collections.emptyList(), 0L); } + /** + * 总数据量 + * + * @return 总数据量 + */ public long getTotal() { return total; } + /** + * 一页数据 + * + * @return 一页数据 + */ public List getContent() { return content; } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/model/dto/PagingAndSortingQueryParams.java b/src/main/java/xyz/zhouxy/plusone/commons/model/dto/PagingAndSortingQueryParams.java index 0c64f2a..2b3bbd0 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/model/dto/PagingAndSortingQueryParams.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/model/dto/PagingAndSortingQueryParams.java @@ -54,6 +54,11 @@ public class PagingAndSortingQueryParams { private final Map sortableProperties; + /** + * 构造分页排序查询参数 + * + * @param sortableProperties 可排序的属性。不可为空。 + */ public PagingAndSortingQueryParams(Map sortableProperties) { AssertTools.checkArgument(CollectionTools.isNotEmpty(sortableProperties), "Sortable properties can not be empty."); @@ -74,16 +79,31 @@ public class PagingAndSortingQueryParams { this.orderBy = orderBy; } + /** + * 设置每页大小 + * + * @param size 每页大小 + */ public final void setSize(@Nullable Integer size) { this.size = size; } + /** + * 设置页码 + * + * @param pageNum 页码 + */ public final void setPageNum(@Nullable Long pageNum) { this.pageNum = pageNum; } // Setters end + /** + * 构建分页参数 + * + * @return {@code PagingParams} 对象 + */ public final PagingParams buildPagingParams() { final int sizeValue = this.size != null ? this.size : defaultSizeInternal(); final long pageNumValue = this.pageNum != null ? this.pageNum : 1L; @@ -95,6 +115,13 @@ public class PagingAndSortingQueryParams { return new PagingParams(sizeValue, pageNumValue, propertiesToSort); } + /** + * 默认每页大小 + * + *

NOTE: 可覆写此方法

+ * + * @return 默认每页大小 + */ @Virtual protected int defaultSizeInternal() { return DEFAULT_PAGE_SIZE; @@ -124,6 +151,9 @@ public class PagingAndSortingQueryParams { return new SortableProperty(propertyName, columnName, orderType); } + /** + * 可排序属性 + */ public static final class SortableProperty { private final String propertyName; private final String columnName; @@ -140,18 +170,38 @@ public class PagingAndSortingQueryParams { this.sqlSnippet = this.propertyName + " " + this.orderType; } + /** + * 属性名 + * + * @return 属性名 + */ public String getPropertyName() { return propertyName; } + /** + * 对应数据库中列名称 + * + * @return 列名称 + */ public String getColumnName() { return columnName; } + /** + * 排序方式 + * + * @return 排序方式 + */ public String getOrderType() { return orderType; } + /** + * SQL 片段 + * + * @return SQL 片段 + */ public String getSqlSnippet() { return sqlSnippet; } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/model/dto/PagingParams.java b/src/main/java/xyz/zhouxy/plusone/commons/model/dto/PagingParams.java index 180b354..62b82d4 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/model/dto/PagingParams.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/model/dto/PagingParams.java @@ -23,9 +23,13 @@ import xyz.zhouxy.plusone.commons.model.dto.PagingAndSortingQueryParams.Sortable public class PagingParams { + /** 每页大小 */ private final int size; + /** 当前页码 */ private final long pageNum; + /** 偏移量 */ private final long offset; + /** 排序 */ private final List orderBy; PagingParams(int size, long pageNum, List orderBy) { @@ -37,18 +41,38 @@ public class PagingParams { // Getters + /** + * 排序规则 + * + * @return 排序规则 + */ public final List getOrderBy() { return Collections.unmodifiableList(this.orderBy); } + /** + * 每页大小 + * + * @return 每页大小 + */ public final int getSize() { return this.size; } + /** + * 当前页码 + * + * @return 当前页码 + */ public final long getPageNum() { return this.pageNum; } + /** + * 偏移量 + * + * @return 偏移量 + */ public final long getOffset() { return this.offset; } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/model/dto/UnifiedResponse.java b/src/main/java/xyz/zhouxy/plusone/commons/model/dto/UnifiedResponse.java index 83a259e..f5531eb 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/model/dto/UnifiedResponse.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/model/dto/UnifiedResponse.java @@ -35,10 +35,23 @@ public class UnifiedResponse { // #region - Constructors // ================================ + /** + * 构造 {@code UnifiedResponse} + * + * @param code 状态码 + * @param message 响应信息 + */ UnifiedResponse(String code, @Nullable String message) { this(code, message, null); } + /** + * 构造 {@code UnifiedResponse} + * + * @param code 状态码 + * @param message 响应信息 + * @param data 响应数据 + */ UnifiedResponse(String code, @Nullable String message, @Nullable T data) { this.code = Objects.requireNonNull(code); this.message = message == null ? "" : message; @@ -53,14 +66,29 @@ public class UnifiedResponse { // #region - Getters // ================================ + /** + * 状态码 + * + * @return 状态码 + */ public String getCode() { return code; } + /** + * 响应信息 + * + * @return 响应信息 + */ public String getMessage() { return message; } + /** + * 响应数据 + * + * @return 响应数据 + */ @Nullable public T getData() { return data; diff --git a/src/main/java/xyz/zhouxy/plusone/commons/model/dto/UnifiedResponses.java b/src/main/java/xyz/zhouxy/plusone/commons/model/dto/UnifiedResponses.java index 4988dc0..f4d239b 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/model/dto/UnifiedResponses.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/model/dto/UnifiedResponses.java @@ -34,14 +34,36 @@ public class UnifiedResponses { // #region - success // ================================ + /** + * 默认成功响应结果 + * + * @return {@code UnifiedResponse} 对象。 + * {@code code} = "2000000", {@code message} = "SUCCESS", {@code data} = null + */ public static UnifiedResponse success() { return new UnifiedResponse<>(SUCCESS_CODE, DEFAULT_SUCCESS_MSG); } + /** + * 使用指定 {@code message} 创建成功响应结果 + * + * @param message 成功信息 + * @return {@code UnifiedResponse} 对象。 + * {@code code} = "2000000", {@code data} = null + */ public static UnifiedResponse success(@Nullable String message) { return new UnifiedResponse<>(SUCCESS_CODE, message); } + /** + * 使用指定 {@code message} 和 {@code data} 创建成功响应结果 + * + * @param data 类型 + * @param message 成功信息 + * @param data 携带数据 + * @return {@code UnifiedResponse} 对象。 + * {@code code} = "2000000" + */ public static UnifiedResponse success(@Nullable String message, @Nullable T data) { return new UnifiedResponse<>(SUCCESS_CODE, message, data); } @@ -54,14 +76,39 @@ public class UnifiedResponses { // #region - error // ================================ + /** + * 创建错误响应结果 + * + * @param code 错误码 + * @param message 错误信息 + * @return {@code UnifiedResponse} 对象（{@code data} 为 {@code null}） + */ public static UnifiedResponse error(String code, @Nullable String message) { return new UnifiedResponse<>(code, message); } + /** + * 创建错误响应结果 + * + * @param data 类型 + * @param code 错误码 + * @param message 错误信息 + * @param data 携带数据 + * @return {@code UnifiedResponse} 对象 + */ public static UnifiedResponse error(String code, @Nullable String message, @Nullable T data) { return new UnifiedResponse<>(code, message, data); } + /** + * 创建错误响应结果 + * + * @param code 错误码 + * @param e 异常 + * @return {@code UnifiedResponse} 对象。 + * {@code message} 为异常的 {@code message}， + * {@code data} 为 {@code null}。 + */ public static UnifiedResponse error(String code, Throwable e) { return new UnifiedResponse<>(code, e.getMessage()); } @@ -74,10 +121,26 @@ public class UnifiedResponses { // #region - of // ================================ + /** + * 创建响应结果 + * + * @param code 状态码 + * @param message 响应信息 + * @return {@code UnifiedResponse} 对象（{@code data} 为 {@code null}） + */ public static UnifiedResponse of(String code, @Nullable String message) { return new UnifiedResponse<>(code, message); } + /** + * 创建响应结果 + * + * @param data 类型 + * @param code 状态码 + * @param message 响应信息 + * @param data 携带数据 + * @return {@code UnifiedResponse} 对象 + */ public static UnifiedResponse of(String code, @Nullable String message, @Nullable T data) { return new UnifiedResponse<>(code, message, data); } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/time/Quarter.java b/src/main/java/xyz/zhouxy/plusone/commons/time/Quarter.java index 0bccd9d..e05dcce 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/time/Quarter.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/time/Quarter.java @@ -46,6 +46,7 @@ public enum Quarter implements IWithIntCode { /** 季度值 (1/2/3/4) */ private final int value; + /** 月份范围 */ private final Range monthRange; /** 常量值 */ @@ -63,7 +64,9 @@ public enum Quarter implements IWithIntCode { this.monthRange = Range.closed(firstMonth, lastMonth); } - // StaticFactoryMethods + // ================================ + // #region - StaticFactoryMethods + // ================================ /** * 根据给定的月份值返回对应的季度 @@ -114,23 +117,48 @@ public enum Quarter implements IWithIntCode { return ENUMS[checkValidIntValue(value) - 1]; } - // StaticFactoryMethods end + // ================================ + // #endregion - StaticFactoryMethods + // ================================ - // computes + // ================================ + // #region - computes + // ================================ + /** + * 加上指定数量的季度 + * + * @param quarters 所添加的季度数量 + * @return 计算结果 + */ public Quarter plus(long quarters) { final int amount = (int) ((quarters % 4) + 4); return ENUMS[(ordinal() + amount) % 4]; } + /** + * 减去指定数量的季度 + * + * @param quarters 所减去的季度数量 + * @return 计算结果 + */ public Quarter minus(long quarters) { return plus(-(quarters % 4)); } - // computes end + // ================================ + // #endregion - computes + // ================================ - // Getters + // ================================ + // #region - Getters + // ================================ + /** + * 获取季度值 + * + * @return 季度值 + */ public int getValue() { return value; } @@ -140,45 +168,92 @@ public enum Quarter implements IWithIntCode { return getValue(); } + /** + * 该季度的第一个月 + * + * @return {@code Month} 对象 + */ public Month firstMonth() { return Month.of(firstMonthValue()); } + /** + * 该季度的第一个月 + * + * @return 月份值从 1 开始，1 表示 1月，以此类推。 + */ public int firstMonthValue() { return this.monthRange.lowerEndpoint(); } + /** + * 该季度的最后一个月 + * + * @return {@code Month} 对象 + */ public Month lastMonth() { return Month.of(lastMonthValue()); } + /** + * 该季度的最后一个月 + * + * @return 月份值从 1 开始，1 表示 1月，以此类推。 + */ public int lastMonthValue() { return this.monthRange.upperEndpoint(); } + /** + * 该季度的第一天 + * + * @return {@code MonthDay} 对象 + */ public MonthDay firstMonthDay() { return MonthDay.of(firstMonth(), 1); } + /** + * 该季度的最后一天 + * + * @return {@code MonthDay} 对象 + */ public MonthDay lastMonthDay() { // 季度的最后一个月不可能是 2 月 final Month month = lastMonth(); return MonthDay.of(month, month.maxLength()); } + /** + * 计算该季度的第一天为当年的第几天 + * + * @param leapYear 是否为闰年 + * @return day of year + */ public int firstDayOfYear(boolean leapYear) { return firstMonth().firstDayOfYear(leapYear); } - // Getters end + // ================================ + // #endregion - Getters + // ================================ + /** + * 检查给定的季度值是否有效 + * + * @param value 季度值 + * @return 如果给定的季度值有效则返回该值 + * @throws DateTimeException 如果给定的季度值不在有效范围内（1到4），将抛出异常 + */ public static int checkValidIntValue(int value) { AssertTools.checkCondition(value >= 1 && value <= 4, () -> new DateTimeException("Invalid value for Quarter: " + value)); return value; } - // Internal + // ================================ + // #region - Internal + // ================================ /** * 计算给定月份对应的季度值 @@ -189,4 +264,8 @@ public enum Quarter implements IWithIntCode { private static int computeQuarterValueInternal(int monthValue) { return (monthValue - 1) / 3 + 1; } + + // ================================ + // #endregion - Internal + // ================================ } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/time/YearQuarter.java b/src/main/java/xyz/zhouxy/plusone/commons/time/YearQuarter.java index c7a4f3c..c90523f 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/time/YearQuarter.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/time/YearQuarter.java @@ -139,6 +139,11 @@ public final class YearQuarter implements Comparable, Serializable return of(yearMonth.getYear(), Quarter.fromMonth(yearMonth.getMonth())); } + /** + * 根据现在的日期，判断所在的年份与季度，创建 {@link YearQuarter} 实例 + * + * @return {@link YearQuarter} 实例 + */ @StaticFactoryMethod(YearQuarter.class) public static YearQuarter now() { return of(LocalDate.now()); @@ -148,46 +153,101 @@ public final class YearQuarter implements Comparable, Serializable // #region - Getters + /** + * 年份 + * + * @return 年份 + */ public int getYear() { return this.year; } + /** + * 季度 + * + * @return 季度 + */ public Quarter getQuarter() { return this.quarter; } + /** + * 季度值。从 1 开始。 + * + * @return 季度值 + */ public int getQuarterValue() { return this.quarter.getValue(); } + /** + * 该季度第一个月 + * + * @return {@link YearMonth} 对象 + */ public YearMonth firstYearMonth() { return YearMonth.of(this.year, this.quarter.firstMonth()); } + /** + * 该季度第一个月 + * + * @return {@link Month} 对象 + */ public Month firstMonth() { return this.quarter.firstMonth(); } + /** + * 该季度的第一个月 + * + * @return 结果。月份值从 1 开始，1 表示 1月，以此类推。 + */ public int firstMonthValue() { return this.quarter.firstMonthValue(); } + /** + * 该季度的最后一个月 + * + * @return {@link YearMonth} 对象 + */ public YearMonth lastYearMonth() { return YearMonth.of(this.year, this.quarter.lastMonth()); } + /** + * 该季度的最后一个月 + * + * @return {@link Month} 对象 + */ public Month lastMonth() { return this.quarter.lastMonth(); } + /** + * 该季度的最后一个月 + * + * @return 结果。月份值从 1 开始，1 表示 1月，以此类推。 + */ public int lastMonthValue() { return this.quarter.lastMonthValue(); } + /** + * 该季度的第一天 + * + * @return {@link LocalDate} 对象 + */ public LocalDate firstDate() { return firstDate; } + /** + * 该季度的最后一天 + * + * @return {@link LocalDate} 对象 + */ public LocalDate lastDate() { return lastDate; } @@ -223,7 +283,7 @@ public final class YearQuarter implements Comparable, Serializable if (yearsToAdd == 0L) { return this; } - int newYear = YEAR.checkValidIntValue(this.year + yearsToAdd); // safe overflow + int newYear = YEAR.checkValidIntValue(this.year + yearsToAdd); // safe overflow return new YearQuarter(newYear, this.quarter); } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/util/ArrayTools.java b/src/main/java/xyz/zhouxy/plusone/commons/util/ArrayTools.java index ab05193..0363eec 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/util/ArrayTools.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/util/ArrayTools.java @@ -470,10 +470,24 @@ public class ArrayTools { // repeat - char + /** + * 重复数组中的元素 + * + * @param arr 重复内容 + * @param times 重复次数 + * @return 重复后的数组 + */ public static char[] repeat(char[] arr, int times) { return repeat(arr, times, Integer.MAX_VALUE); } + /** + * 重复数组中的元素 + * @param arr 重复内容 + * @param times 重复次数 + * @param maxLength 最大长度 + * @return 重复后的数组 + */ public static char[] repeat(char[] arr, int times, int maxLength) { AssertTools.checkArgument(Objects.nonNull(arr)); AssertTools.checkArgument(times >= 0, @@ -491,10 +505,24 @@ public class ArrayTools { // repeat - byte + /** + * 重复数组中的元素 + * + * @param arr 重复内容 + * @param times 重复次数 + * @return 重复后的数组 + */ public static byte[] repeat(byte[] arr, int times) { return repeat(arr, times, Integer.MAX_VALUE); } + /** + * 重复数组中的元素 + * @param arr 重复内容 + * @param times 重复次数 + * @param maxLength 最大长度 + * @return 重复后的数组 + */ public static byte[] repeat(byte[] arr, int times, int maxLength) { AssertTools.checkArgument(Objects.nonNull(arr)); AssertTools.checkArgument(times >= 0, @@ -512,10 +540,24 @@ public class ArrayTools { // repeat - short + /** + * 重复数组中的元素 + * + * @param arr 重复内容 + * @param times 重复次数 + * @return 重复后的数组 + */ public static short[] repeat(short[] arr, int times) { return repeat(arr, times, Integer.MAX_VALUE); } + /** + * 重复数组中的元素 + * @param arr 重复内容 + * @param times 重复次数 + * @param maxLength 最大长度 + * @return 重复后的数组 + */ public static short[] repeat(short[] arr, int times, int maxLength) { AssertTools.checkArgument(Objects.nonNull(arr)); AssertTools.checkArgument(times >= 0, @@ -533,10 +575,24 @@ public class ArrayTools { // repeat - int + /** + * 重复数组中的元素 + * + * @param arr 重复内容 + * @param times 重复次数 + * @return 重复后的数组 + */ public static int[] repeat(int[] arr, int times) { return repeat(arr, times, Integer.MAX_VALUE); } + /** + * 重复数组中的元素 + * @param arr 重复内容 + * @param times 重复次数 + * @param maxLength 最大长度 + * @return 重复后的数组 + */ public static int[] repeat(int[] arr, int times, int maxLength) { AssertTools.checkArgument(Objects.nonNull(arr)); AssertTools.checkArgument(times >= 0, @@ -554,10 +610,24 @@ public class ArrayTools { // repeat - long + /** + * 重复数组中的元素 + * + * @param arr 重复内容 + * @param times 重复次数 + * @return 重复后的数组 + */ public static long[] repeat(long[] arr, int times) { return repeat(arr, times, Integer.MAX_VALUE); } + /** + * 重复数组中的元素 + * @param arr 重复内容 + * @param times 重复次数 + * @param maxLength 最大长度 + * @return 重复后的数组 + */ public static long[] repeat(long[] arr, int times, int maxLength) { AssertTools.checkArgument(Objects.nonNull(arr)); AssertTools.checkArgument(times >= 0, @@ -575,10 +645,24 @@ public class ArrayTools { // repeat - float + /** + * 重复数组中的元素 + * + * @param arr 重复内容 + * @param times 重复次数 + * @return 重复后的数组 + */ public static float[] repeat(float[] arr, int times) { return repeat(arr, times, Integer.MAX_VALUE); } + /** + * 重复数组中的元素 + * @param arr 重复内容 + * @param times 重复次数 + * @param maxLength 最大长度 + * @return 重复后的数组 + */ public static float[] repeat(float[] arr, int times, int maxLength) { AssertTools.checkArgument(Objects.nonNull(arr)); AssertTools.checkArgument(times >= 0, @@ -596,10 +680,24 @@ public class ArrayTools { // repeat - double + /** + * 重复数组中的元素 + * + * @param arr 重复内容 + * @param times 重复次数 + * @return 重复后的数组 + */ public static double[] repeat(double[] arr, int times) { return repeat(arr, times, Integer.MAX_VALUE); } + /** + * 重复数组中的元素 + * @param arr 重复内容 + * @param times 重复次数 + * @param maxLength 最大长度 + * @return 重复后的数组 + */ public static double[] repeat(double[] arr, int times, int maxLength) { AssertTools.checkArgument(Objects.nonNull(arr)); AssertTools.checkArgument(times >= 0, @@ -621,14 +719,34 @@ public class ArrayTools { // fill - char + /** + * 填充数组 + * + * @param a 要填充的数组 + * @param values 填充内容 + */ public static void fill(char[] a, @Nullable char[] values) { fill(a, 0, a.length, values); } + /** + * 填充数组 + * + * @param a 要填充的数组 + * @param values 填充内容 + */ public static void fill(char[] a, @Nullable String values) { fill(a, 0, a.length, values != null ? values.toCharArray() : EMPTY_CHAR_ARRAY); } + /** + * 填充数组 + * + * @param a 要填充的数组 + * @param fromIndex 开始位置 + * @param toIndex 结束位置 + * @param values 填充内容 + */ public static void fill(char[] a, int fromIndex, int toIndex, @Nullable char[] values) { AssertTools.checkArgument(Objects.nonNull(a)); if (values == null || values.length == 0) { @@ -654,10 +772,24 @@ public class ArrayTools { // fill - byte + /** + * 填充数组 + * + * @param a 要填充的数组 + * @param values 填充内容 + */ public static void fill(byte[] a, @Nullable byte[] values) { fill(a, 0, a.length, values); } + /** + * 填充数组 + * + * @param a 要填充的数组 + * @param fromIndex 开始位置 + * @param toIndex 结束位置 + * @param values 填充内容 + */ public static void fill(byte[] a, int fromIndex, int toIndex, @Nullable byte[] values) { AssertTools.checkArgument(Objects.nonNull(a)); if (values == null || values.length == 0) { @@ -683,10 +815,24 @@ public class ArrayTools { // fill - short + /** + * 填充数组 + * + * @param a 要填充的数组 + * @param values 填充内容 + */ public static void fill(short[] a, @Nullable short[] values) { fill(a, 0, a.length, values); } + /** + * 填充数组 + * + * @param a 要填充的数组 + * @param fromIndex 开始位置 + * @param toIndex 结束位置 + * @param values 填充内容 + */ public static void fill(short[] a, int fromIndex, int toIndex, @Nullable short[] values) { AssertTools.checkArgument(Objects.nonNull(a)); if (values == null || values.length == 0) { @@ -712,10 +858,24 @@ public class ArrayTools { // fill - int + /** + * 填充数组 + * + * @param a 要填充的数组 + * @param values 填充内容 + */ public static void fill(int[] a, @Nullable int[] values) { fill(a, 0, a.length, values); } + /** + * 填充数组 + * + * @param a 要填充的数组 + * @param fromIndex 开始位置 + * @param toIndex 结束位置 + * @param values 填充内容 + */ public static void fill(int[] a, int fromIndex, int toIndex, @Nullable int[] values) { AssertTools.checkArgument(Objects.nonNull(a)); if (values == null || values.length == 0) { @@ -741,10 +901,24 @@ public class ArrayTools { // fill - long + /** + * 填充数组 + * + * @param a 要填充的数组 + * @param values 填充内容 + */ public static void fill(long[] a, @Nullable long[] values) { fill(a, 0, a.length, values); } + /** + * 填充数组 + * + * @param a 要填充的数组 + * @param fromIndex 开始位置 + * @param toIndex 结束位置 + * @param values 填充内容 + */ public static void fill(long[] a, int fromIndex, int toIndex, @Nullable long[] values) { AssertTools.checkArgument(Objects.nonNull(a)); if (values == null || values.length == 0) { @@ -770,10 +944,24 @@ public class ArrayTools { // fill - float + /** + * 填充数组 + * + * @param a 要填充的数组 + * @param values 填充内容 + */ public static void fill(float[] a, @Nullable float[] values) { fill(a, 0, a.length, values); } + /** + * 填充数组 + * + * @param a 要填充的数组 + * @param fromIndex 开始位置 + * @param toIndex 结束位置 + * @param values 填充内容 + */ public static void fill(float[] a, int fromIndex, int toIndex, @Nullable float[] values) { AssertTools.checkArgument(Objects.nonNull(a)); if (values == null || values.length == 0) { @@ -799,10 +987,24 @@ public class ArrayTools { // fill - double + /** + * 填充数组 + * + * @param a 要填充的数组 + * @param values 填充内容 + */ public static void fill(double[] a, @Nullable double[] values) { fill(a, 0, a.length, values); } + /** + * 填充数组 + * + * @param a 要填充的数组 + * @param fromIndex 开始位置 + * @param toIndex 结束位置 + * @param values 填充内容 + */ public static void fill(double[] a, int fromIndex, int toIndex, @Nullable double[] values) { AssertTools.checkArgument(Objects.nonNull(a)); if (values == null || values.length == 0) { @@ -828,14 +1030,36 @@ public class ArrayTools { // fill - T + /** + * 填充数组 + * + * @param a 要填充的数组 + * @param values 填充内容 + */ public static void fill(T[] a, @Nullable T[] values) { fillInternal(a, 0, a.length, values); } + /** + * 填充数组 + * + * @param a 要填充的数组 + * @param fromIndex 开始位置 + * @param toIndex 结束位置 + * @param values 填充内容 + */ public static void fill(T[] a, int fromIndex, int toIndex, @Nullable T[] values) { fillInternal(a, fromIndex, toIndex, values); } + /** + * 填充数组 + * + * @param a 要填充的数组 + * @param fromIndex 开始位置 + * @param toIndex 结束位置 + * @param values 填充内容 + */ private static void fillInternal(T[] a, int fromIndex, int toIndex, @Nullable T[] values) { AssertTools.checkArgument(Objects.nonNull(a)); if (values == null || values.length == 0) { diff --git a/src/main/java/xyz/zhouxy/plusone/commons/util/AssertTools.java b/src/main/java/xyz/zhouxy/plusone/commons/util/AssertTools.java index 77edf64..6ac89a6 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/util/AssertTools.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/util/AssertTools.java @@ -49,22 +49,46 @@ public class AssertTools { // #region - Argument // ================================ - /** Throw {@link IllegalArgumentException} if the {@code condition} is false. */ + /** + * 检查实参 + * + * @param condition 判断参数是否符合条件的结果 + * @throws IllegalArgumentException 当条件不满足时抛出 + */ public static void checkArgument(boolean condition) { checkCondition(condition, IllegalArgumentException::new); } - /** Throw {@link IllegalArgumentException} if the {@code condition} is false. */ + /** + * 检查实参 + * + * @param condition 判断参数是否符合条件的结果 + * @param errMsg 异常信息 + * @throws IllegalArgumentException 当条件不满足时抛出 + */ public static void checkArgument(boolean condition, @Nullable String errMsg) { checkCondition(condition, () -> new IllegalArgumentException(errMsg)); } - /** Throw {@link IllegalArgumentException} if the {@code condition} is false. */ + /** + * 检查实参 + * + * @param condition 判断参数是否符合条件的结果 + * @param messageSupplier 异常信息 + * @throws IllegalArgumentException 当条件不满足时抛出 + */ public static void checkArgument(boolean condition, Supplier messageSupplier) { checkCondition(condition, () -> new IllegalArgumentException(messageSupplier.get())); } - /** Throw {@link IllegalArgumentException} if the {@code condition} is false. */ + /** + * 检查实参 + * + * @param condition 判断参数是否符合条件的结果 + * @param format 异常信息模板 + * @param args 异常信息参数 + * @throws IllegalArgumentException 当条件不满足时抛出 + */ public static void checkArgument(boolean condition, String format, Object... args) { checkCondition(condition, () -> new IllegalArgumentException(String.format(format, args))); } @@ -77,22 +101,46 @@ public class AssertTools { // #region - State // ================================ - /** Throw {@link IllegalStateException} if the {@code condition} is false. */ + /** + * 检查状态 + * + * @param condition 判断状态是否符合条件的结果 + * @throws IllegalStateException 当条件不满足时抛出 + */ public static void checkState(boolean condition) { checkCondition(condition, IllegalStateException::new); } - /** Throw {@link IllegalStateException} if the {@code condition} is false. */ + /** + * 检查状态 + * + * @param condition 判断状态是否符合条件的结果 + * @param errMsg 异常信息 + * @throws IllegalStateException 当条件不满足时抛出 + */ public static void checkState(boolean condition, @Nullable String errMsg) { checkCondition(condition, () -> new IllegalStateException(errMsg)); } - /** Throw {@link IllegalStateException} if the {@code condition} is false. */ + /** + * 检查状态 + * + * @param condition 判断状态是否符合条件的结果 + * @param messageSupplier 异常信息 + * @throws IllegalStateException 当条件不满足时抛出 + */ public static void checkState(boolean condition, Supplier messageSupplier) { checkCondition(condition, () -> new IllegalStateException(messageSupplier.get())); } - /** Throw {@link IllegalStateException} if the {@code condition} is false. */ + /** + * 检查状态 + * + * @param condition 判断状态是否符合条件的结果 + * @param format 异常信息模板 + * @param args 异常信息参数 + * @throws IllegalStateException 当条件不满足时抛出 + */ public static void checkState(boolean condition, String format, Object... args) { checkCondition(condition, () -> new IllegalStateException(String.format(format, args))); } @@ -105,22 +153,50 @@ public class AssertTools { // #region - NotNull // ================================ - /** Throw {@link NullPointerException} if the {@code obj} is null. */ + /** + * 判空 + * + * @param 入参类型 + * @param obj 入参 * + * @throws NullPointerException 当 {@code obj} 为 {@code null} 时抛出 + */ public static void checkNotNull(@Nullable T obj) { checkCondition(obj != null, NullPointerException::new); } - /** Throw {@link NullPointerException} if the {@code obj} is null. */ + /** + * 判空 + * + * @param 入参类型 + * @param obj 入参 + * @param errMsg 异常信息 * + * @throws NullPointerException 当 {@code obj} 为 {@code null} 时抛出 + */ public static void checkNotNull(@Nullable T obj, String errMsg) { checkCondition(obj != null, () -> new NullPointerException(errMsg)); } - /** Throw {@link NullPointerException} if the {@code obj} is null. */ + /** + * 判空 + * + * @param 入参类型 + * @param obj 入参 + * @param messageSupplier 异常信息 * + * @throws NullPointerException 当 {@code obj} 为 {@code null} 时抛出 + */ public static void checkNotNull(@Nullable T obj, Supplier messageSupplier) { checkCondition(obj != null, () -> new NullPointerException(messageSupplier.get())); } - /** Throw {@link NullPointerException} if the {@code obj} is null. */ + /** + * 判空 + * + * @param 入参类型 + * @param obj 入参 + * @param format 异常信息模板 + * @param args 异常信息参数 + * @throws NullPointerException 当 {@code obj} 为 {@code null} 时抛出 + */ public static void checkNotNull(@Nullable T obj, String format, Object... args) { checkCondition(obj != null, () -> new NullPointerException(String.format(format, args))); } @@ -133,56 +209,120 @@ public class AssertTools { // #region - Exists // ================================ - /** Throw {@link DataNotExistsException} if the {@code obj} is null. */ + /** + * 检查数据是否存在 + * + * @param 入参类型 + * @param obj 入参 + * @return 如果 {@code obj} 存在，返回 {@code obj} 本身 + * @throws DataNotExistsException 当 {@code obj} 不存在时抛出 + */ public static T checkExists(@Nullable T obj) throws DataNotExistsException { checkCondition(Objects.nonNull(obj), DataNotExistsException::new); return obj; } - /** Throw {@link DataNotExistsException} if the {@code obj} is null. */ + /** + * 检查数据是否存在 + * + * @param 入参类型 + * @param obj 入参 + * @param message 异常信息 + * @return 如果 {@code obj} 存在，返回 {@code obj} 本身 + * @throws DataNotExistsException 当 {@code obj} 不存在时抛出 + */ public static T checkExists(@Nullable T obj, String message) throws DataNotExistsException { checkCondition(Objects.nonNull(obj), () -> new DataNotExistsException(message)); return obj; } - /** Throw {@link DataNotExistsException} if the {@code obj} is null. */ + /** + * 检查数据是否存在 + * + * @param 入参类型 + * @param obj 入参 + * @param messageSupplier 异常信息 + * @return 如果 {@code obj} 存在，返回 {@code obj} 本身 + * @throws DataNotExistsException 当 {@code obj} 不存在时抛出 + */ public static T checkExists(@Nullable T obj, Supplier messageSupplier) throws DataNotExistsException { checkCondition(Objects.nonNull(obj), () -> new DataNotExistsException(messageSupplier.get())); return obj; } - /** Throw {@link DataNotExistsException} if the {@code obj} is null. */ + /** + * 检查数据是否存在 + * + * @param 入参类型 + * @param obj 入参 + * @param format 异常信息模板 + * @param args 异常信息参数 + * @return 如果 {@code obj} 存在，返回 {@code obj} 本身 + * @throws DataNotExistsException 当 {@code obj} 不存在时抛出 + */ public static T checkExists(@Nullable T obj, String format, Object... args) throws DataNotExistsException { checkCondition(Objects.nonNull(obj), () -> new DataNotExistsException(String.format(format, args))); return obj; } - /** Throw {@link DataNotExistsException} if the {@code optional} is present. */ + /** + * 检查数据是否存在 + * + * @param 入参类型 + * @param optional 入参 + * @return 如果 {@code optional} 存在，返回 {@code optional} 包含的值 + * @throws DataNotExistsException 当 {@code optional} 的值不存在时抛出 + */ public static T checkExists(Optional optional) throws DataNotExistsException { checkCondition(optional.isPresent(), DataNotExistsException::new); return optional.get(); } - /** Throw {@link DataNotExistsException} if the {@code optional} is present. */ + /** + * 检查数据是否存在 + * + * @param 入参类型 + * @param optional 入参 + * @param message 异常信息 + * @return 如果 {@code optional} 存在，返回 {@code optional} 包含的值 + * @throws DataNotExistsException 当 {@code optional} 的值不存在时抛出 + */ public static T checkExists(Optional optional, String message) throws DataNotExistsException { checkCondition(optional.isPresent(), () -> new DataNotExistsException(message)); return optional.get(); } - /** Throw {@link DataNotExistsException} if the {@code optional} is present. */ + /** + * 检查数据是否存在 + * + * @param 入参类型 + * @param optional 入参 + * @param messageSupplier 异常信息 + * @return 如果 {@code optional} 存在，返回 {@code optional} 包含的值 + * @throws DataNotExistsException 当 {@code optional} 的值不存在时抛出 + */ public static T checkExists(Optional optional, Supplier messageSupplier) throws DataNotExistsException { checkCondition(optional.isPresent(), () -> new DataNotExistsException(messageSupplier.get())); return optional.get(); } - /** Throw {@link DataNotExistsException} if the {@code optional} is present. */ + /** + * 检查数据是否存在 + * + * @param 入参类型 + * @param optional 入参 + * @param format 异常信息模板 + * @param args 异常信息参数 + * @return 如果 {@code optional} 存在，返回 {@code optional} 包含的值 + * @throws DataNotExistsException 当 {@code optional} 的值不存在时抛出 + */ public static T checkExists(Optional optional, String format, Object... args) throws DataNotExistsException { checkCondition(optional.isPresent(), () -> new DataNotExistsException(String.format(format, args))); @@ -197,78 +337,182 @@ public class AssertTools { // #region - AffectedRows // ================================ + /** + * 当影响的数据量与预计不同时抛出 {@link DataOperationResultException}。 + * + * @param expectedValue 预计的数量 + * @param result 实际影响的数据量 + */ public static void checkAffectedRows(int expectedValue, int result) { checkAffectedRows(expectedValue, result, "The number of rows affected is expected to be %d, but is: %d", expectedValue, result); } + /** + * 当影响的数据量与预计不同时抛出 {@link DataOperationResultException}。 + * + * @param expectedValue 预计的数量 + * @param result 实际影响的数据量 + * @param message 异常信息 + */ public static void checkAffectedRows(int expectedValue, int result, @Nullable String message) { checkCondition(expectedValue == result, () -> new DataOperationResultException(message)); } + /** + * 当影响的数据量与预计不同时抛出 {@link DataOperationResultException}。 + * + * @param expectedValue 预计的数量 + * @param result 实际影响的数据量 + * @param messageSupplier 异常信息 + */ public static void checkAffectedRows(int expectedValue, int result, Supplier messageSupplier) { checkCondition(expectedValue == result, () -> new DataOperationResultException(messageSupplier.get())); } + /** + * 当影响的数据量与预计不同时抛出 {@link DataOperationResultException}。 + * + * @param expectedValue 预计的数量 + * @param result 实际影响的数据量 + * @param format 异常信息模板 + * @param args 异常信息参数 + */ public static void checkAffectedRows(int expectedValue, int result, String format, Object... args) { checkCondition(expectedValue == result, () -> new DataOperationResultException(String.format(format, args))); } + /** + * 当影响的数据量与预计不同时抛出 {@link DataOperationResultException}。 + * + * @param expectedValue 预计的数量 + * @param result 实际影响的数据量 + */ public static void checkAffectedRows(long expectedValue, long result) { checkAffectedRows(expectedValue, result, "The number of rows affected is expected to be %d, but is: %d", expectedValue, result); } + /** + * 当影响的数据量与预计不同时抛出 {@link DataOperationResultException}。 + * + * @param expectedValue 预计的数量 + * @param result 实际影响的数据量 + * @param message 异常信息 + */ public static void checkAffectedRows(long expectedValue, long result, @Nullable String message) { checkCondition(expectedValue == result, () -> new DataOperationResultException(message)); } + /** + * 当影响的数据量与预计不同时抛出 {@link DataOperationResultException}。 + * + * @param expectedValue 预计的数量 + * @param result 实际影响的数据量 + * @param messageSupplier 异常信息 + */ public static void checkAffectedRows(long expectedValue, long result, Supplier messageSupplier) { checkCondition(expectedValue == result, () -> new DataOperationResultException(messageSupplier.get())); } + /** + * 当影响的数据量与预计不同时抛出 {@link DataOperationResultException}。 + * + * @param expectedValue 预计的数量 + * @param result 实际影响的数据量 + * @param format 异常信息模板 + * @param args 异常信息参数 + */ public static void checkAffectedRows(long expectedValue, long result, String format, Object... args) { checkCondition(expectedValue == result, () -> new DataOperationResultException(String.format(format, args))); } + /** + * 当影响的数据量不为 1 时抛出 {@link DataOperationResultException}。 + * + * @param result 实际影响的数据量 + */ public static void checkAffectedOneRow(int result) { checkAffectedRows(1, result, () -> "The number of rows affected is expected to be 1, but is: " + result); } + /** + * 当影响的数据量不为 1 时抛出 {@link DataOperationResultException}。 + * + * @param result 实际影响的数据量 + * @param message 异常信息 + */ public static void checkAffectedOneRow(int result, String message) { checkAffectedRows(1, result, message); } + /** + * 当影响的数据量不为 1 时抛出 {@link DataOperationResultException}。 + * + * @param result 实际影响的数据量 + * @param messageSupplier 异常信息 + */ public static void checkAffectedOneRow(int result, Supplier messageSupplier) { checkAffectedRows(1, result, messageSupplier); } + /** + * 当影响的数据量不为 1 时抛出 {@link DataOperationResultException}。 + * + * @param result 实际影响的数据量 + * @param format 异常信息模板 + * @param args 异常信息参数 + */ public static void checkAffectedOneRow(int result, String format, Object... args) { checkAffectedRows(1, result, format, args); } + /** + * 当影响的数据量不为 1 时抛出 {@link DataOperationResultException}。 + * + * @param result 实际影响的数据量 + */ public static void checkAffectedOneRow(long result) { checkAffectedRows(1L, result, () -> "The number of rows affected is expected to be 1, but is: " + result); } + /** + * 当影响的数据量不为 1 时抛出 {@link DataOperationResultException}。 + * + * @param result 实际影响的数据量 + * @param message 异常信息 + */ public static void checkAffectedOneRow(long result, String message) { checkAffectedRows(1L, result, message); } + /** + * 当影响的数据量不为 1 时抛出 {@link DataOperationResultException}。 + * + * @param result 实际影响的数据量 + * @param messageSupplier 异常信息 + */ public static void checkAffectedOneRow(long result, Supplier messageSupplier) { checkAffectedRows(1L, result, messageSupplier); } + /** + * 当影响的数据量不为 1 时抛出 {@link DataOperationResultException}。 + * + * @param result 实际影响的数据量 + * @param format 异常信息模板 + * @param args 异常信息参数 + */ public static void checkAffectedOneRow(long result, String format, Object... args) { checkAffectedRows(1L, result, format, args); @@ -282,6 +526,14 @@ public class AssertTools { // #region - Condition // ================================ + /** + * 当条件不满足时抛出异常。 + * + * @param 异常类型 + * @param condition 条件 + * @param e 异常 + * @throws T 当条件不满足时抛出异常 + */ public static void checkCondition(boolean condition, Supplier e) throws T { if (!condition) { diff --git a/src/main/java/xyz/zhouxy/plusone/commons/util/BigDecimals.java b/src/main/java/xyz/zhouxy/plusone/commons/util/BigDecimals.java index bdf3c85..5f4b0fe 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/util/BigDecimals.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/util/BigDecimals.java @@ -35,34 +35,75 @@ import xyz.zhouxy.plusone.commons.annotation.StaticFactoryMethod; */ public class BigDecimals { + /** + * 判断两个 {@code BigDecimal} 的值是否相等 + * + * @param a 第一个 {@code BigDecimal} + * @param b 第二个 {@code BigDecimal} + * @return 当两个 {@code BigDecimal} 的值相等时返回 {@code true} + */ public static boolean equalsValue(@Nullable BigDecimal a, @Nullable BigDecimal b) { return (a == b) || (a != null && b != null && a.compareTo(b) == 0); } + /** + * 判断两个 {@code BigDecimal} 的值 - 大于 + * + * @param a 第一个 {@code BigDecimal} + * @param b 第二个 {@code BigDecimal} + * @return 当 {@code a} 大于 {@code b} 时返回 {@code true} + */ public static boolean gt(BigDecimal a, BigDecimal b) { AssertTools.checkNotNull(a, "Parameter could not be null."); AssertTools.checkNotNull(b, "Parameter could not be null."); return (a != b) && (a.compareTo(b) > 0); } + /** + * 判断两个 {@code BigDecimal} 的值 - 大于等于 + * + * @param a 第一个 {@code BigDecimal} + * @param b 第二个 {@code BigDecimal} + * @return 当 {@code a} 大于等于 {@code b} 时返回 {@code true} + */ public static boolean ge(BigDecimal a, BigDecimal b) { AssertTools.checkNotNull(a, "Parameter could not be null."); AssertTools.checkNotNull(b, "Parameter could not be null."); return (a == b) || (a.compareTo(b) >= 0); } + /** + * 判断两个 {@code BigDecimal} 的值 - 小于 + * + * @param a 第一个 {@code BigDecimal} + * @param b 第二个 {@code BigDecimal} + * @return 当 {@code a} 小于 {@code b} 时返回 {@code true} + */ public static boolean lt(BigDecimal a, BigDecimal b) { AssertTools.checkNotNull(a, "Parameter could not be null."); AssertTools.checkNotNull(b, "Parameter could not be null."); return (a != b) && (a.compareTo(b) < 0); } + /** + * 判断两个 {@code BigDecimal} 的值 - 小于等于 + * + * @param a 第一个 {@code BigDecimal} + * @param b 第二个 {@code BigDecimal} + * @return 当 {@code a} 小于等于 {@code b} 时返回 {@code true} + */ public static boolean le(BigDecimal a, BigDecimal b) { AssertTools.checkNotNull(a, "Parameter could not be null."); AssertTools.checkNotNull(b, "Parameter could not be null."); return (a == b) || (a.compareTo(b) <= 0); } + /** + * 求和 + * + * @param numbers {@code BigDecimal} 数组 + * @return 求和结果 + */ public static BigDecimal sum(final BigDecimal... numbers) { if (ArrayTools.isNullOrEmpty(numbers)) { return BigDecimal.ZERO; @@ -77,11 +118,23 @@ public class BigDecimals { return result; } + /** + * 将 {@code null} 转换为 {@link BigDecimal#ZERO} + * + * @param val BigDecimal 对象 + * @return 如果 {@code val} 为 {@code null}，则返回 {@link BigDecimal#ZERO}，否则返回 {@code val} + */ @Nonnull public static BigDecimal nullToZero(@Nullable final BigDecimal val) { return val != null ? val : BigDecimal.ZERO; } + /** + * 获取字符串所表示的数值转换为 {@code BigDecimal} + * + * @param val 表示数值的字符串 + * @return {@code BigDecimal} 对象 + */ @StaticFactoryMethod(BigDecimal.class) public static BigDecimal of(@Nullable final String val) { return (StringTools.isNotBlank(val)) ? new BigDecimal(val) : BigDecimal.ZERO; diff --git a/src/main/java/xyz/zhouxy/plusone/commons/util/DateTimeTools.java b/src/main/java/xyz/zhouxy/plusone/commons/util/DateTimeTools.java index 1ecfc0b..c89dcd1 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/util/DateTimeTools.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/util/DateTimeTools.java @@ -702,18 +702,43 @@ public class DateTimeTools { // #region - start & end // ================================ + /** + * 获取指定年份的开始日期 + * + * @param year 年份 + * @return 指定年份的开始日期 + */ public static LocalDate startDateOfYear(int year) { return LocalDate.ofYearDay(year, 1); } + /** + * 获取指定年份的结束日期 + * + * @param year 年份 + * @return 指定年份的结束日期 + */ public static LocalDate endDateOfYear(int year) { return LocalDate.of(year, 12, 31); } + /** + * 获取指定日期的第二天的开始时间 + * + * @param date 日期 + * @return 指定日期的第二天的开始时间 + */ public static LocalDateTime startOfNextDate(LocalDate date) { return date.plusDays(1L).atStartOfDay(); } + /** + * 获取指定日期的第二天的开始时间 + * + * @param date 日期 + * @param zone 时区 + * @return 指定日期的第二天的开始时间 + */ public static ZonedDateTime startOfNextDate(LocalDate date, ZoneId zone) { return date.plusDays(1L).atStartOfDay(zone); } @@ -726,30 +751,72 @@ public class DateTimeTools { // #region - isFuture // ================================ + /** + * 判断指定日期时间是否在将来 + * + * @param date 日期时间 + * @return 指定日期时间是否在将来 + */ public static boolean isFuture(Date date) { return date.after(new Date()); } - public static boolean isFuture(Calendar date) { - return date.after(Calendar.getInstance()); + /** + * 判断指定日期时间是否在将来 + * + * @param calendar 日期时间 + * @return 指定日期时间是否在将来 + */ + public static boolean isFuture(Calendar calendar) { + return calendar.after(Calendar.getInstance()); } + /** + * 判断指定时刻是否在将来 + * + * @param instant 时刻 + * @return 指定时刻是否在将来 + */ public static boolean isFuture(Instant instant) { return instant.isAfter(Instant.now()); } + /** + * 判断指定时间戳是否在将来 + * + * @param timeMillis 时间戳 + * @return 指定时间戳是否在将来 + */ public static boolean isFuture(long timeMillis) { return timeMillis > System.currentTimeMillis(); } + /** + * 判断指定日期是否在将来 + * + * @param date 日期 + * @return 指定日期是否在将来 + */ public static boolean isFuture(LocalDate date) { return date.isAfter(LocalDate.now()); } + /** + * 判断指定日期时间是否在将来 + * + * @param dateTime 日期时间 + * @return 指定日期时间是否在将来 + */ public static boolean isFuture(LocalDateTime dateTime) { return dateTime.isAfter(LocalDateTime.now()); } + /** + * 判断指定日期时间是否在将来 + * + * @param dateTime 日期时间 + * @return 指定日期时间是否在将来 + */ public static boolean isFuture(ZonedDateTime dateTime) { return dateTime.isAfter(ZonedDateTime.now()); } @@ -762,30 +829,72 @@ public class DateTimeTools { // #region - isPast // ================================ + /** + * 判断指定日期时间是否在过去 + * + * @param date 日期时间 + * @return 指定日期时间是否在过去 + */ public static boolean isPast(Date date) { return date.before(new Date()); } - public static boolean isPast(Calendar date) { - return date.before(Calendar.getInstance()); + /** + * 判断指定日期时间是否在过去 + * + * @param calendar 日期时间 + * @return 指定日期时间是否在过去 + */ + public static boolean isPast(Calendar calendar) { + return calendar.before(Calendar.getInstance()); } + /** + * 判断指定时刻是否在过去 + * + * @param instant 时刻 + * @return 指定时刻是否在过去 + */ public static boolean isPast(Instant instant) { return instant.isBefore(Instant.now()); } + /** + * 判断指定时间戳是否在过去 + * + * @param timeMillis 时间戳 + * @return 指定时间戳是否在过去 + */ public static boolean isPast(long timeMillis) { return timeMillis < System.currentTimeMillis(); } + /** + * 判断指定日期是否在过去 + * + * @param date 日期 + * @return 指定日期是否在过去 + */ public static boolean isPast(LocalDate date) { return date.isBefore(LocalDate.now()); } + /** + * 判断指定日期时间是否在过去 + * + * @param dateTime 日期时间 + * @return 指定日期时间是否在过去 + */ public static boolean isPast(LocalDateTime dateTime) { return dateTime.isBefore(LocalDateTime.now()); } + /** + * 判断指定日期时间是否在过去 + * + * @param dateTime 日期时间 + * @return 指定日期时间是否在过去 + */ public static boolean isPast(ZonedDateTime dateTime) { return dateTime.isBefore(ZonedDateTime.now()); } @@ -798,14 +907,33 @@ public class DateTimeTools { // #region - others // ================================ + /** + * 获取指定日期的时间范围 + * + * @param date 日期 + * @return 指定日期的时间范围 + */ public static Range toDateTimeRange(LocalDate date) { return Range.closedOpen(date.atStartOfDay(), startOfNextDate(date)); } + /** + * 获取指定日期的时间范围 + * + * @param date 日期 + * @param zone 时区 + * @return 指定日期的时间范围 + */ public static Range toDateTimeRange(LocalDate date, ZoneId zone) { return Range.closedOpen(date.atStartOfDay(zone), startOfNextDate(date, zone)); } + /** + * 判断指定年份是否为闰年 + * + * @param year 年份 + * @return 指定年份是否为闰年 + */ public static boolean isLeapYear(int year) { return IsoChronology.INSTANCE.isLeapYear(year); } @@ -815,7 +943,7 @@ public class DateTimeTools { // ================================ /** - * 私有构造方法，明确标识该常量类的作用。 + * 私有构造方法 */ private DateTimeTools() { throw new IllegalStateException("Utility class"); diff --git a/src/main/java/xyz/zhouxy/plusone/commons/util/Enumeration.java b/src/main/java/xyz/zhouxy/plusone/commons/util/Enumeration.java index 8787559..568a954 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/util/Enumeration.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/util/Enumeration.java @@ -48,10 +48,20 @@ public abstract class Enumeration> // NOSONAR 暂不移 this.name = name; } + /** + * 枚举整数码值 + * + * @return 整数码值 + */ public final int getId() { return id; } + /** + * 枚举名称 + * + * @return 枚举名称 + */ public final String getName() { return name; } @@ -84,6 +94,9 @@ public abstract class Enumeration> // NOSONAR 暂不移 return getClass().getSimpleName() + '(' + id + ":" + name + ')'; } + /** + * 枚举值集合 + */ protected static final class ValueSet> { private final Map valueMap; @@ -91,6 +104,13 @@ public abstract class Enumeration> // NOSONAR 暂不移 this.valueMap = valueMap; } + /** + * 创建枚举值集合 + * + * @param 枚举类型 + * @param values 枚举值 + * @return 枚举值集合 + */ @StaticFactoryMethod(ValueSet.class) public static > ValueSet of(T[] values) { Map temp = Arrays.stream(values) @@ -98,11 +118,22 @@ public abstract class Enumeration> // NOSONAR 暂不移 return new ValueSet<>(Collections.unmodifiableMap(temp)); } + /** + * 根据整数码值获取枚举对象 + * + * @param id 整数码 + * @return 枚举对象 + */ public T get(int id) { AssertTools.checkArgument(this.valueMap.containsKey(id), "[%s] 对应的值不存在", id); return this.valueMap.get(id); } + /** + * 获取所有枚举对象 + * + * @return 所有枚举对象 + */ public Collection getValues() { return this.valueMap.values(); } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/util/IdGenerator.java b/src/main/java/xyz/zhouxy/plusone/commons/util/IdGenerator.java index 9dc028b..0d846c2 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/util/IdGenerator.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/util/IdGenerator.java @@ -36,18 +36,39 @@ public class IdGenerator { // ===== UUID ===== + /** + * 生成 UUID + * + * @return UUID + */ public static UUID newUuid() { return UUID.randomUUID(); } + /** + * 生成 UUID 字符串 + * + * @return UUID 字符串 + */ public static String uuidString() { return UUID.randomUUID().toString(); } + /** + * 生成 UUID 字符串（无分隔符） + * + * @return UUID 字符串 + */ public static String simpleUuidString() { return toSimpleString(UUID.randomUUID()); } + /** + * 生成 UUID 字符串（无分隔符） + * + * @param uuid UUID + * @return UUID 字符串 + */ public static String toSimpleString(UUID uuid) { AssertTools.checkArgument(Objects.nonNull(uuid)); return (uuidDigits(uuid.getMostSignificantBits() >> 32, 8) + @@ -67,11 +88,23 @@ public class IdGenerator { private static final Map snowflakePool = new ConcurrentHashMap<>(); + /** + * 生成雪花ID + * + * @param workerId 工作机器ID + * @return 雪花ID + */ public static long nextSnowflakeId(long workerId) { IdWorker generator = getSnowflakeIdGenerator(workerId); return generator.nextId(); } + /** + * 获取雪花ID生成器 + * + * @param workerId 工作机器ID + * @return {@code IdWorker} 对象。来自 Seata 的修改版雪花ID生成器。 + */ public static IdWorker getSnowflakeIdGenerator(long workerId) { return snowflakePool.computeIfAbsent(workerId, wid -> new IdWorker(workerId)); } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/util/Numbers.java b/src/main/java/xyz/zhouxy/plusone/commons/util/Numbers.java index d8138f3..0086ea1 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/util/Numbers.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/util/Numbers.java @@ -23,7 +23,7 @@ import javax.annotation.Nonnull; import javax.annotation.Nullable; /** - * Numbers + * 数字工具类 * * @author ZhouXY */ @@ -31,6 +31,12 @@ public class Numbers { // #region - sum + /** + * 求和 + * + * @param numbers 数据数组 + * @return 求和结果 + */ public static int sum(final short... numbers) { int result = 0; for (short number : numbers) { @@ -39,6 +45,12 @@ public class Numbers { return result; } + /** + * 求和 + * + * @param numbers 数据数组 + * @return 求和结果 + */ public static long sum(final int... numbers) { long result = 0L; for (int number : numbers) { @@ -47,6 +59,12 @@ public class Numbers { return result; } + /** + * 求和 + * + * @param numbers 数据数组 + * @return 求和结果 + */ public static long sum(final long... numbers) { long result = 0L; for (long number : numbers) { @@ -55,6 +73,12 @@ public class Numbers { return result; } + /** + * 求和 + * + * @param numbers 数据数组 + * @return 求和结果 + */ public static double sum(final float... numbers) { double result = 0.00; for (float number : numbers) { @@ -63,6 +87,12 @@ public class Numbers { return result; } + /** + * 求和 + * + * @param numbers 数据数组 + * @return 求和结果 + */ public static double sum(final double... numbers) { double result = 0.00; for (double number : numbers) { @@ -71,6 +101,12 @@ public class Numbers { return result; } + /** + * 求和 + * + * @param numbers 数据数组 + * @return 求和结果 + */ public static BigInteger sum(final BigInteger... numbers) { if (ArrayTools.isNullOrEmpty(numbers)) { return BigInteger.ZERO; @@ -85,6 +121,12 @@ public class Numbers { return result; } + /** + * 求和 + * + * @param numbers 数据数组 + * @return 求和结果 + */ public static BigDecimal sum(final BigDecimal... numbers) { return BigDecimals.sum(numbers); } @@ -93,35 +135,83 @@ public class Numbers { // #region - nullToZero + /** + * 将 {@code null} 转换为 {@code 0} + * + * @param val 待转换的值 + * @return 如果 {@code val} 不为 {@code null}，则返回该值；如果值为 {@code null}，则返回 {@code 0} + */ public static byte nullToZero(@Nullable final Byte val) { return val != null ? val : 0; } + /** + * 将 {@code null} 转换为 {@code 0} + * + * @param val 待转换的值 + * @return 如果 {@code val} 不为 {@code null}，则返回该值；如果值为 {@code null}，则返回 {@code 0} + */ public static short nullToZero(@Nullable final Short val) { return val != null ? val : 0; } + /** + * 将 {@code null} 转换为 {@code 0} + * + * @param val 待转换的值 + * @return 如果 {@code val} 不为 {@code null}，则返回该值；如果值为 {@code null}，则返回 {@code 0} + */ public static int nullToZero(@Nullable final Integer val) { return val != null ? val : 0; } + /** + * 将 {@code null} 转换为 {@code 0} + * + * @param val 待转换的值 + * @return 如果 {@code val} 不为 {@code null}，则返回该值；如果值为 {@code null}，则返回 {@code 0} + */ public static long nullToZero(@Nullable final Long val) { return val != null ? val : 0L; } + /** + * 将 {@code null} 转换为 {@code 0} + * + * @param val 待转换的值 + * @return 如果 {@code val} 不为 {@code null}，则返回该值；如果值为 {@code null}，则返回 {@code 0} + */ public static float nullToZero(@Nullable final Float val) { return val != null ? val : 0.0F; } + /** + * 将 {@code null} 转换为 {@code 0} + * + * @param val 待转换的值 + * @return 如果 {@code val} 不为 {@code null}，则返回该值；如果值为 {@code null}，则返回 {@code 0} + */ public static double nullToZero(@Nullable final Double val) { return val != null ? val : 0.0; } + /** + * 将 {@code null} 转换为 {@code 0} + * + * @param val 待转换的值 + * @return 如果 {@code val} 不为 {@code null}，则返回该值；如果值为 {@code null}，则返回 {@code 0} + */ @Nonnull public static BigInteger nullToZero(@Nullable final BigInteger val) { return val != null ? val : BigInteger.ZERO; } + /** + * 将 {@code null} 转换为 {@code 0} + * + * @param val 待转换的值 + * @return 如果 {@code val} 不为 {@code null}，则返回该值；如果值为 {@code null}，则返回 {@code 0} + */ @Nonnull public static BigDecimal nullToZero(@Nullable final BigDecimal val) { return BigDecimals.nullToZero(val); diff --git a/src/main/java/xyz/zhouxy/plusone/commons/util/OptionalTools.java b/src/main/java/xyz/zhouxy/plusone/commons/util/OptionalTools.java index b36f41a..c8ba964 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/util/OptionalTools.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/util/OptionalTools.java @@ -134,16 +134,34 @@ public class OptionalTools { return optionalObj.orElse(null); } + /** + * 将 {@link OptionalInt} 转为 {@link Integer} + * + * @param optionalObj optional 对象 + * @return {@link Integer} 对象。如果 {@code OptionalInt} 的值缺失，返回 {@code null}。 + */ @Beta public static Integer toInteger(OptionalInt optionalObj) { return optionalObj.isPresent() ? optionalObj.getAsInt() : null; } + /** + * 将 {@link OptionalLong} 转为 {@link Long} + * + * @param optionalObj optional 对象 + * @return {@link Long} 对象。如果 {@code OptionalLong} 的值缺失，返回 {@code null}。 + */ @Beta public static Long toLong(OptionalLong optionalObj) { return optionalObj.isPresent() ? optionalObj.getAsLong() : null; } + /** + * 将 {@link OptionalDouble} 转为 {@link Double} + * + * @param optionalObj optional 对象 + * @return {@link Double} 对象。如果 {@code OptionalDouble} 的值缺失，返回 {@code null}。 + */ @Beta public static Double toDouble(OptionalDouble optionalObj) { return optionalObj.isPresent() ? optionalObj.getAsDouble() : null; diff --git a/src/main/java/xyz/zhouxy/plusone/commons/util/RegexTools.java b/src/main/java/xyz/zhouxy/plusone/commons/util/RegexTools.java index ddd502d..d01dd97 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/util/RegexTools.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/util/RegexTools.java @@ -326,12 +326,26 @@ public final class RegexTools { return input != null && pattern.matcher(input).matches(); } + /** + * 判断 {@code input} 是否匹配至少一个正则。 + * + * @param input 输入 + * @param patterns 正则表达式 + * @return 判断结果 + */ private static boolean matchesOneInternal(@Nullable final CharSequence input, final Pattern[] patterns) { return input != null && Arrays.stream(patterns) .anyMatch(pattern -> pattern.matcher(input).matches()); } + /** + * 判断 {@code input} 是否匹配全部正则。 + * + * @param input 输入 + * @param patterns 正则表达式 + * @return 判断结果 + */ private static boolean matchesAllInternal(@Nullable final CharSequence input, final Pattern[] patterns) { return input != null && Arrays.stream(patterns) diff --git a/src/main/java/xyz/zhouxy/plusone/commons/util/TreeBuilder.java b/src/main/java/xyz/zhouxy/plusone/commons/util/TreeBuilder.java index 211d2f3..d36bb1b 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/util/TreeBuilder.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/util/TreeBuilder.java @@ -39,11 +39,26 @@ public class TreeBuilder { private final BiConsumer addChildMethod; private final Comparator defaultComparator; + /** + * 构造一个 {@code TreeBuilder}。不指定用于排序的 {@code Comparator}。 + * + * @param identityGetter 从节点中获取其标识的逻辑 + * @param parentIdentityGetter 获取父节点标识的逻辑 + * @param addChild 添加子节点的逻辑 + */ public TreeBuilder(Function identityGetter, Function> parentIdentityGetter, BiConsumer addChild) { this(identityGetter, parentIdentityGetter, addChild, null); } + /** + * 构造一个 {@code TreeBuilder}。 + * + * @param identityGetter 从节点中获取其标识的逻辑 + * @param parentIdentityGetter 获取父节点标识的逻辑 + * @param addChild 添加子节点的逻辑 + * @param defaultComparator 默认的 {@code Comparator}，用于排序 + */ public TreeBuilder(Function identityGetter, Function> parentIdentityGetter, BiConsumer addChild, @Nullable Comparator defaultComparator) { this.identityGetter = identityGetter;