ZhouXY108/plusone-commons
1
0
Fork 0
forked from plusone/plusone-commons
Code Issues Pull Requests Activity

docs: 完善 javadoc

Browse Source
This commit is contained in:
zhouxy108 2025-04-03 10:09:18 +08:00
parent 7923046423
commit aa5e0b1798
43 changed files with 1963 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
src/main/java/xyz/zhouxy/plusone/commons/base/IWithCode.java
View File

@ -29,21 +29,50 @@ import javax.annotation.Nullable;
* @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
*/
public interface IWithCode<T> {
/**
* 获取码值
* @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());
}

29
src/main/java/xyz/zhouxy/plusone/commons/base/IWithIntCode.java
View File

@ -28,20 +28,49 @@ import javax.annotation.Nullable;
* @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
*/
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();
}

29
src/main/java/xyz/zhouxy/plusone/commons/base/IWithLongCode.java
View File

@ -28,20 +28,49 @@ import javax.annotation.Nullable;
* @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
*/
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();
}

57
src/main/java/xyz/zhouxy/plusone/commons/base/Ref.java
View File

@ -79,43 +79,100 @@ public final class Ref<T> {
this.value = value;
}
/**
* 创建对象引用
*
* @param <T> 引用的类型
* @param value 引用的对象
* @return {@code Ref} 对象
*/
public static <T> Ref<T> of(@Nullable T value) {
return new Ref<>(value);
}
/**
* 创建空引用
*
* @param <T> 引用的类型
* @return 空引用
*/
public static <T> Ref<T> 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<T> operator) {
this.value = operator.apply(this.value);
}
/**
* 使用 {@link Function} 修改所引用的对象，返回新的 {@code Ref}
*
* @param <R> 结果的引用类型
* @param function 修改逻辑
* @return 修改后的对象的引用
*/
public <R> Ref<R> transform(Function<? super T, R> function) {
return Ref.of(function.apply(this.value));
}
/**
* 使用 {@link Predicate} 检查引用的对象
*
* @param predicate 判断逻辑
* @return 判断结果
*/
public boolean checkValue(Predicate<? super T> predicate) {
return predicate.test(this.value);
}
/**
* 将引用的对象作为入参，执行 {@link Consumer} 的逻辑
*
* @param consumer 要执行的逻辑
*/
public void execute(Consumer<? super T> 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;
}

97
src/main/java/xyz/zhouxy/plusone/commons/collection/CollectionTools.java
View File

@ -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 <T> List 元素的类型
* @param list list
* @return 如果 {@code list} 为 {@code null}，返回空列表；
* 如果 {@code list} 不为 {@code null}，返回 {@code list} 本身
*/
@Nonnull
public static <T> List<T> nullToEmptyList(@Nullable List<T> list) {
return list == null ? Collections.emptyList() : list;
}
/**
* 将 {@code null} 转为空 {@code Set}
*
* @param <T> Set 元素的类型
* @param set set
* @return 如果 {@code set} 为 {@code null}，返回空集合；
* 如果 {@code set} 不为 {@code null}，返回 {@code set} 本身
*/
@Nonnull
public static <T> Set<T> nullToEmptySet(@Nullable Set<T> set) {
return set == null ? Collections.emptySet() : set;
}
/**
* 将 {@code null} 转为空 {@code Map}
*
* @param <K> Map 的键的类型
* @param <V> Map 的值的类型
* @param map map
* @return 如果 {@code map} 为 {@code null}，返回空集合；
* 如果 {@code map} 不为 {@code null}，返回 {@code map} 本身
*/
@Nonnull
public static <K, V> Map<K, V> nullToEmptyMap(@Nullable Map<K, V> map) {
return map == null ? Collections.emptyMap() : map;

22
src/main/java/xyz/zhouxy/plusone/commons/exception/DataNotExistsException.java
View File

@ -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);
}

40
src/main/java/xyz/zhouxy/plusone/commons/exception/MultiTypesException.java
View File

@ -124,26 +124,66 @@ import xyz.zhouxy.plusone.commons.base.IWithCode;
*/
public interface MultiTypesException<E extends Exception, T extends MultiTypesException.ExceptionType<E>> {
/**
* 异常类型
*
* @return 异常类型。通常是实现了 {@link ExceptionType} 的枚举。
*/
@Nonnull
T getType();
/**
* 获取异常类型编码
*
* @return 异常类型编码
*/
default @Nonnull String getTypeCode() {
return getType().getCode();
}
/**
* 异常类型
*/
public static interface ExceptionType<E extends Exception> extends IWithCode<String> {
/**
* 默认异常信息
*/
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);

62
src/main/java/xyz/zhouxy/plusone/commons/exception/ParsingFailureException.java
View File

@ -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<ParsingFailureException> {

22
src/main/java/xyz/zhouxy/plusone/commons/exception/business/BizException.java
View File

@ -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);
}

27
src/main/java/xyz/zhouxy/plusone/commons/exception/business/InvalidInputException.java
View File

@ -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);
}

22
src/main/java/xyz/zhouxy/plusone/commons/exception/business/RequestParamsException.java
View File

@ -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);
}

22
src/main/java/xyz/zhouxy/plusone/commons/exception/system/DataOperationResultException.java
View File

@ -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);
}

22
src/main/java/xyz/zhouxy/plusone/commons/exception/system/NoAvailableMacFoundException.java
View File

@ -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);
}

22
src/main/java/xyz/zhouxy/plusone/commons/exception/system/SysException.java
View File

@ -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);
}

24
src/main/java/xyz/zhouxy/plusone/commons/function/BoolUnaryOperator.java
View File

@ -18,11 +18,35 @@ package xyz.zhouxy.plusone.commons.function;
import com.google.common.annotations.Beta;
/**
* BoolUnaryOperator
*
* <p>
* 一个特殊的 {@link java.util.function.UnaryOperator}。
* 表示对 {@code boolean} 值的一元操作。
* </p>
*
* @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
* @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;
}

19
src/main/java/xyz/zhouxy/plusone/commons/function/CharUnaryOperator.java
View File

@ -18,8 +18,27 @@ package xyz.zhouxy.plusone.commons.function;
import com.google.common.annotations.Beta;
/**
* CharUnaryOperator
*
* <p>
* 一个特殊的 {@link java.util.function.UnaryOperator}。
* 表示对 {@code char} 的一元操作。
* </p>
*
* @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
* @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);
}

17
src/main/java/xyz/zhouxy/plusone/commons/function/Executable.java
View File

@ -16,9 +16,26 @@
package xyz.zhouxy.plusone.commons.function;
/**
* Executable
*
* <p>
* 表示一个无入参无返回值的操作，可抛出异常。
* </p>
*
* @param <E> 可抛出的异常类型
*
* @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
* @since 1.0.0
*/
@FunctionalInterface
public interface Executable<E extends Throwable> {
/**
* 执行
*
* @throws E 可抛出的异常
*/
void execute() throws E;
}

1
src/main/java/xyz/zhouxy/plusone/commons/function/OptionalSupplier.java
View File

@ -24,6 +24,7 @@ import java.util.function.Supplier;
*
* <p>
* 返回 {@code Optional&lt;T&gt;} 对象。
* </p>
*
* @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
* @since 1.0.0

15
src/main/java/xyz/zhouxy/plusone/commons/function/ThrowingConsumer.java
View File

@ -16,13 +16,24 @@
package xyz.zhouxy.plusone.commons.function;
/**
* ThrowingConsumer
*
* <p>
* 允许抛出异常的消费操作。是一个特殊的 {@link java.util.function.Consumer}。
* </p>
*
* @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
* @since 1.0.0
* @see java.util.function.Consumer
*/
@FunctionalInterface
public interface ThrowingConsumer<T, E extends Throwable> {
/**
* Consume the supplied argument, potentially throwing an exception.
* 消费给定的参数，允许抛出异常
*
* @param t the argument to consume
* @param t 要消费的参数
*/
void accept(T t) throws E;

21
src/main/java/xyz/zhouxy/plusone/commons/function/ThrowingFunction.java
View File

@ -15,14 +15,29 @@
*/
package xyz.zhouxy.plusone.commons.function;
/**
* ThrowingFunction
*
* <p>
* 接收一个参数，并返回一个结果，可以抛出异常。
* </p>
*
* @param <T> 入参类型
* @param <R> 返回结果类型
* @param <E> 异常类型
*
* @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
* @since 1.0
* @see java.util.function.Function
*/
@FunctionalInterface
public interface ThrowingFunction<T, R, E extends Throwable> {
/**
* 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;

18
src/main/java/xyz/zhouxy/plusone/commons/function/ThrowingPredicate.java
View File

@ -16,15 +16,25 @@
package xyz.zhouxy.plusone.commons.function;
/**
* ThrowingPredicate
*
* <p>
* 接收一个参数，返回一个布尔值，可抛出异常。
* </p>
*
* @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
* @since 1.0.0
* @see java.util.function.Predicate
*/
@FunctionalInterface
public interface ThrowingPredicate<T, E extends Throwable> {
/**
* 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;
}

18
src/main/java/xyz/zhouxy/plusone/commons/function/ThrowingSupplier.java
View File

@ -16,13 +16,27 @@
package xyz.zhouxy.plusone.commons.function;
/**
* ThrowingSupplier
*
* <p>
* 允许抛出异常的 Supplier 接口。
* </p>
*
* @param <T> 结果类型
* @param <E> 异常类型
*
* @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
* @since 1.0.0
* @see java.util.function.Supplier
*/
@FunctionalInterface
public interface ThrowingSupplier<T, E extends Throwable> {
/**
* Get a result, potentially throwing an exception.
* 获取一个结果，允许抛出异常。
*
* @return a result
* @return 结果
*/
T get() throws E;

41
src/main/java/xyz/zhouxy/plusone/commons/model/Chinese2ndGenIDCardNumber.java
View File

@ -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');

21
src/main/java/xyz/zhouxy/plusone/commons/model/Gender.java
View File

@ -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;
}

31
src/main/java/xyz/zhouxy/plusone/commons/model/IDCardNumber.java
View File

@ -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);
}

27
src/main/java/xyz/zhouxy/plusone/commons/model/ValidatableStringRecord.java
View File

@ -36,7 +36,7 @@ import xyz.zhouxy.plusone.commons.util.AssertTools;
* @deprecated 弃用。使用工厂方法创建对象，并在其中进行校验即可。
*/
@Deprecated
public abstract class ValidatableStringRecord<T extends ValidatableStringRecord<T>>
public abstract class ValidatableStringRecord<T extends ValidatableStringRecord<T>> // NOSONAR 暂不删除
implements Comparable<T> {
@Nonnull
@ -44,15 +44,35 @@ public abstract class ValidatableStringRecord<T extends ValidatableStringRecord<
private final Matcher matcher;
/**
* 构造字符串值对象
*
* @param value 字符串值
* @param pattern 正则
*/
protected ValidatableStringRecord(String value, Pattern pattern) {
this(value, pattern, "Invalid value");
}
/**
* 构造字符串值对象
*
* @param value 字符串值
* @param pattern 正则
* @param errorMessageSupplier 正则不匹配时的错误信息
*/
protected ValidatableStringRecord(String value, Pattern pattern,
Supplier<String> 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<T extends ValidatableStringRecord<
return this.value();
}
/**
* 获取正则匹配结果
*
* @return {@code Matcher} 对象
*/
protected final Matcher getMatcher() {
return matcher;
}

24
src/main/java/xyz/zhouxy/plusone/commons/model/dto/PageResult.java
View File

@ -43,20 +43,44 @@ public class PageResult<T> {
this.total = total;
}
/**
* 创建一个分页查询的结果
*
* @param <T> 内容类型
* @param content 一页数据
* @param total 总数据量
* @return 分页查询的结果
*/
@StaticFactoryMethod(PageResult.class)
public static <T> PageResult<T> of(@Nullable final List<T> content, final long total) {
return new PageResult<>(content, total);
}
/**
* 创建一个空的分页查询的结果
*
* @param <T> 内容类型
* @return 空结果
*/
@StaticFactoryMethod(PageResult.class)
public static <T> PageResult<T> empty() {
return new PageResult<>(Collections.emptyList(), 0L);
}
/**
* 总数据量
*
* @return 总数据量
*/
public long getTotal() {
return total;
}
/**
* 一页数据
*
* @return 一页数据
*/
public List<T> getContent() {
return content;
}

50
src/main/java/xyz/zhouxy/plusone/commons/model/dto/PagingAndSortingQueryParams.java
View File

@ -54,6 +54,11 @@ public class PagingAndSortingQueryParams {
private final Map<String, String> sortableProperties;
/**
* 构造分页排序查询参数
*
* @param sortableProperties 可排序的属性。不可为空。
*/
public PagingAndSortingQueryParams(Map<String, String> 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);
}
/**
* 默认每页大小
*
* <p>NOTE: 可覆写此方法</p>
*
* @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;
}

24
src/main/java/xyz/zhouxy/plusone/commons/model/dto/PagingParams.java
View File

@ -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<SortableProperty> orderBy;
PagingParams(int size, long pageNum, List<SortableProperty> orderBy) {
@ -37,18 +41,38 @@ public class PagingParams {
// Getters
/**
* 排序规则
*
* @return 排序规则
*/
public final List<SortableProperty> 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;
}

28
src/main/java/xyz/zhouxy/plusone/commons/model/dto/UnifiedResponse.java
View File

@ -35,10 +35,23 @@ public class UnifiedResponse<T> {
// #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<T> {
// #region - Getters
// ================================
/**
* 状态码
*
* @return 状态码
*/
public String getCode() {
return code;
}
/**
* 响应信息
*
* @return 响应信息
*/
public String getMessage() {
return message;
}
/**
* 响应数据
*
* @return 响应数据
*/
@Nullable
public T getData() {
return data;

63
src/main/java/xyz/zhouxy/plusone/commons/model/dto/UnifiedResponses.java
View File

@ -34,14 +34,36 @@ public class UnifiedResponses {
// #region - success
// ================================
/**
* 默认成功响应结果
*
* @return {@code UnifiedResponse} 对象。
* {@code code} = "2000000", {@code message} = "SUCCESS", {@code data} = null
*/
public static UnifiedResponse<Void> 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<Void> success(@Nullable String message) {
return new UnifiedResponse<>(SUCCESS_CODE, message);
}
/**
* 使用指定 {@code message} 和 {@code data} 创建成功响应结果
*
* @param <T> data 类型
* @param message 成功信息
* @param data 携带数据
* @return {@code UnifiedResponse} 对象。
* {@code code} = "2000000"
*/
public static <T> UnifiedResponse<T> 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<Void> error(String code, @Nullable String message) {
return new UnifiedResponse<>(code, message);
}
/**
* 创建错误响应结果
*
* @param <T> data 类型
* @param code 错误码
* @param message 错误信息
* @param data 携带数据
* @return {@code UnifiedResponse} 对象
*/
public static <T> UnifiedResponse<T> 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<Void> 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<Void> of(String code, @Nullable String message) {
return new UnifiedResponse<>(code, message);
}
/**
* 创建响应结果
*
* @param <T> data 类型
* @param code 状态码
* @param message 响应信息
* @param data 携带数据
* @return {@code UnifiedResponse} 对象
*/
public static <T> UnifiedResponse<T> of(String code, @Nullable String message, @Nullable T data) {
return new UnifiedResponse<>(code, message, data);
}

93
src/main/java/xyz/zhouxy/plusone/commons/time/Quarter.java
View File

@ -46,6 +46,7 @@ public enum Quarter implements IWithIntCode {
/** 季度值 (1/2/3/4) */
private final int value;
/** 月份范围 */
private final Range<Integer> 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
// ================================
}

62
src/main/java/xyz/zhouxy/plusone/commons/time/YearQuarter.java
View File

@ -139,6 +139,11 @@ public final class YearQuarter implements Comparable<YearQuarter>, 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<YearQuarter>, 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<YearQuarter>, 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);
}

224
src/main/java/xyz/zhouxy/plusone/commons/util/ArrayTools.java
View File

@ -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 <T> void fill(T[] a, @Nullable T[] values) {
fillInternal(a, 0, a.length, values);
}
/**
* 填充数组
*
* @param a 要填充的数组
* @param fromIndex 开始位置
* @param toIndex 结束位置
* @param values 填充内容
*/
public static <T> 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 <T> void fillInternal(T[] a, int fromIndex, int toIndex, @Nullable T[] values) {
AssertTools.checkArgument(Objects.nonNull(a));
if (values == null || values.length == 0) {

292
src/main/java/xyz/zhouxy/plusone/commons/util/AssertTools.java
View File

@ -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<String> 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<String> 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 <T> 入参类型
* @param obj 入参 *
* @throws NullPointerException 当 {@code obj} 为 {@code null} 时抛出
*/
public static <T> void checkNotNull(@Nullable T obj) {
checkCondition(obj != null, NullPointerException::new);
}
/** Throw {@link NullPointerException} if the {@code obj} is null. */
/**
* 判空
*
* @param <T> 入参类型
* @param obj 入参
* @param errMsg 异常信息 *
* @throws NullPointerException 当 {@code obj} 为 {@code null} 时抛出
*/
public static <T> void checkNotNull(@Nullable T obj, String errMsg) {
checkCondition(obj != null, () -> new NullPointerException(errMsg));
}
/** Throw {@link NullPointerException} if the {@code obj} is null. */
/**
* 判空
*
* @param <T> 入参类型
* @param obj 入参
* @param messageSupplier 异常信息 *
* @throws NullPointerException 当 {@code obj} 为 {@code null} 时抛出
*/
public static <T> void checkNotNull(@Nullable T obj, Supplier<String> messageSupplier) {
checkCondition(obj != null, () -> new NullPointerException(messageSupplier.get()));
}
/** Throw {@link NullPointerException} if the {@code obj} is null. */
/**
* 判空
*
* @param <T> 入参类型
* @param obj 入参
* @param format 异常信息模板
* @param args 异常信息参数
* @throws NullPointerException 当 {@code obj} 为 {@code null} 时抛出
*/
public static <T> 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 <T> 入参类型
* @param obj 入参
* @return 如果 {@code obj} 存在，返回 {@code obj} 本身
* @throws DataNotExistsException 当 {@code obj} 不存在时抛出
*/
public static <T> 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 <T> 入参类型
* @param obj 入参
* @param message 异常信息
* @return 如果 {@code obj} 存在，返回 {@code obj} 本身
* @throws DataNotExistsException 当 {@code obj} 不存在时抛出
*/
public static <T> 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 <T> 入参类型
* @param obj 入参
* @param messageSupplier 异常信息
* @return 如果 {@code obj} 存在，返回 {@code obj} 本身
* @throws DataNotExistsException 当 {@code obj} 不存在时抛出
*/
public static <T> T checkExists(@Nullable T obj, Supplier<String> messageSupplier)
throws DataNotExistsException {
checkCondition(Objects.nonNull(obj), () -> new DataNotExistsException(messageSupplier.get()));
return obj;
}
/** Throw {@link DataNotExistsException} if the {@code obj} is null. */
/**
* 检查数据是否存在
*
* @param <T> 入参类型
* @param obj 入参
* @param format 异常信息模板
* @param args 异常信息参数
* @return 如果 {@code obj} 存在，返回 {@code obj} 本身
* @throws DataNotExistsException 当 {@code obj} 不存在时抛出
*/
public static <T> 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 <T> 入参类型
* @param optional 入参
* @return 如果 {@code optional} 存在，返回 {@code optional} 包含的值
* @throws DataNotExistsException 当 {@code optional} 的值不存在时抛出
*/
public static <T> T checkExists(Optional<T> optional)
throws DataNotExistsException {
checkCondition(optional.isPresent(), DataNotExistsException::new);
return optional.get();
}
/** Throw {@link DataNotExistsException} if the {@code optional} is present. */
/**
* 检查数据是否存在
*
* @param <T> 入参类型
* @param optional 入参
* @param message 异常信息
* @return 如果 {@code optional} 存在，返回 {@code optional} 包含的值
* @throws DataNotExistsException 当 {@code optional} 的值不存在时抛出
*/
public static <T> T checkExists(Optional<T> optional, String message)
throws DataNotExistsException {
checkCondition(optional.isPresent(), () -> new DataNotExistsException(message));
return optional.get();
}
/** Throw {@link DataNotExistsException} if the {@code optional} is present. */
/**
* 检查数据是否存在
*
* @param <T> 入参类型
* @param optional 入参
* @param messageSupplier 异常信息
* @return 如果 {@code optional} 存在，返回 {@code optional} 包含的值
* @throws DataNotExistsException 当 {@code optional} 的值不存在时抛出
*/
public static <T> T checkExists(Optional<T> optional, Supplier<String> messageSupplier)
throws DataNotExistsException {
checkCondition(optional.isPresent(), () -> new DataNotExistsException(messageSupplier.get()));
return optional.get();
}
/** Throw {@link DataNotExistsException} if the {@code optional} is present. */
/**
* 检查数据是否存在
*
* @param <T> 入参类型
* @param optional 入参
* @param format 异常信息模板
* @param args 异常信息参数
* @return 如果 {@code optional} 存在，返回 {@code optional} 包含的值
* @throws DataNotExistsException 当 {@code optional} 的值不存在时抛出
*/
public static <T> T checkExists(Optional<T> 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<String> 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<String> 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<String> 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<String> 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 <T> 异常类型
* @param condition 条件
* @param e 异常
* @throws T 当条件不满足时抛出异常
*/
public static <T extends Exception> void checkCondition(boolean condition, Supplier<T> e)
throws T {
if (!condition) {

53
src/main/java/xyz/zhouxy/plusone/commons/util/BigDecimals.java
View File

@ -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;

138
src/main/java/xyz/zhouxy/plusone/commons/util/DateTimeTools.java
View File

@ -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<LocalDateTime> toDateTimeRange(LocalDate date) {
return Range.closedOpen(date.atStartOfDay(), startOfNextDate(date));
}
/**
* 获取指定日期的时间范围
*
* @param date 日期
* @param zone 时区
* @return 指定日期的时间范围
*/
public static Range<ZonedDateTime> 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");

31
src/main/java/xyz/zhouxy/plusone/commons/util/Enumeration.java
View File

@ -48,10 +48,20 @@ public abstract class Enumeration<T extends Enumeration<T>> // 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<T extends Enumeration<T>> // NOSONAR 暂不移
return getClass().getSimpleName() + '(' + id + ":" + name + ')';
}
/**
* 枚举值集合
*/
protected static final class ValueSet<T extends Enumeration<T>> {
private final Map<Integer, T> valueMap;
@ -91,6 +104,13 @@ public abstract class Enumeration<T extends Enumeration<T>> // NOSONAR 暂不移
this.valueMap = valueMap;
}
/**
* 创建枚举值集合
*
* @param <T> 枚举类型
* @param values 枚举值
* @return 枚举值集合
*/
@StaticFactoryMethod(ValueSet.class)
public static <T extends Enumeration<T>> ValueSet<T> of(T[] values) {
Map<Integer, T> temp = Arrays.stream(values)
@ -98,11 +118,22 @@ public abstract class Enumeration<T extends Enumeration<T>> // 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<T> getValues() {
return this.valueMap.values();
}

33
src/main/java/xyz/zhouxy/plusone/commons/util/IdGenerator.java
View File

@ -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<Long, IdWorker> 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));
}

92
src/main/java/xyz/zhouxy/plusone/commons/util/Numbers.java
View File

@ -23,7 +23,7 @@ import javax.annotation.Nonnull;
import javax.annotation.Nullable;
/**
* Numbers
* 数字工具类
*
* @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
*/
@ -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);

18
src/main/java/xyz/zhouxy/plusone/commons/util/OptionalTools.java
View File

@ -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;

14
src/main/java/xyz/zhouxy/plusone/commons/util/RegexTools.java
View File

@ -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)

15
src/main/java/xyz/zhouxy/plusone/commons/util/TreeBuilder.java
View File

@ -39,11 +39,26 @@ public class TreeBuilder<T, TSubTree extends T, TIdentity> {
private final BiConsumer<TSubTree, T> addChildMethod;
private final Comparator<? super T> defaultComparator;
/**
* 构造一个 {@code TreeBuilder}。不指定用于排序的 {@code Comparator}。
*
* @param identityGetter 从节点中获取其标识的逻辑
* @param parentIdentityGetter 获取父节点标识的逻辑
* @param addChild 添加子节点的逻辑
*/
public TreeBuilder(Function<T, TIdentity> identityGetter, Function<T, Optional<TIdentity>> parentIdentityGetter,
BiConsumer<TSubTree, T> addChild) {
this(identityGetter, parentIdentityGetter, addChild, null);
}
/**
* 构造一个 {@code TreeBuilder}。
*
* @param identityGetter 从节点中获取其标识的逻辑
* @param parentIdentityGetter 获取父节点标识的逻辑
* @param addChild 添加子节点的逻辑
* @param defaultComparator 默认的 {@code Comparator}，用于排序
*/
public TreeBuilder(Function<T, TIdentity> identityGetter, Function<T, Optional<TIdentity>> parentIdentityGetter,
BiConsumer<TSubTree, T> addChild, @Nullable Comparator<? super T> defaultComparator) {
this.identityGetter = identityGetter;