From 8813923c861fb76d87670cc83701bda7c505e2f4 Mon Sep 17 00:00:00 2001 From: ZhouXY108 Date: Tue, 7 Jan 2025 16:21:24 +0800 Subject: [PATCH 1/2] =?UTF-8?q?=E6=96=B0=E5=A2=9E=20base=20=E5=8C=85?= =?UTF-8?q?=E7=9A=84=20Javadoc=EF=BC=9B=E4=BC=98=E5=8C=96=20base=20?= =?UTF-8?q?=E5=8C=85=E4=B8=AD=20JSR-305=20=E6=B3=A8=E8=A7=A3=E7=9A=84?= =?UTF-8?q?=E4=BD=BF=E7=94=A8=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../plusone/commons/base/IWithCode.java | 9 ++- .../plusone/commons/base/IWithIntCode.java | 8 +- .../plusone/commons/base/IWithLongCode.java | 8 +- .../plusone/commons/base/package-info.java | 75 +++++++++++++++++++ 4 files changed, 90 insertions(+), 10 deletions(-) create mode 100644 src/main/java/xyz/zhouxy/plusone/commons/base/package-info.java 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 42212ff..5633567 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/base/IWithCode.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/base/IWithCode.java @@ -19,6 +19,7 @@ package xyz.zhouxy.plusone.commons.base; import java.util.Objects; import javax.annotation.Nonnull; +import javax.annotation.Nullable; /** * 规定实现类带有 {@code getCode} 方法。 @@ -31,19 +32,19 @@ public interface IWithCode { @Nonnull T getCode(); - default boolean isCodeEquals(T code) { + default boolean isCodeEquals(@Nullable T code) { return Objects.equals(getCode(), code); } - default boolean isSameCodeAs(IWithCode other) { + default boolean isSameCodeAs(@Nullable IWithCode other) { return other != null && Objects.equals(getCode(), other.getCode()); } - default boolean isSameCodeAs(IWithIntCode other) { + default boolean isSameCodeAs(@Nullable IWithIntCode other) { return other != null && Objects.equals(getCode(), other.getCode()); } - default boolean isSameCodeAs(IWithLongCode other) { + 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 4a42578..3e881cc 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/base/IWithIntCode.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/base/IWithIntCode.java @@ -18,6 +18,8 @@ package xyz.zhouxy.plusone.commons.base; import java.util.Objects; +import javax.annotation.Nullable; + /** * 规定实现类带有 {@code getCode} 方法。 * 用于像自定义异常等需要带有 {@code code} 字段的类， @@ -32,15 +34,15 @@ public interface IWithIntCode { return getCode() == code; } - default boolean isSameCodeAs(IWithCode other) { + default boolean isSameCodeAs(@Nullable IWithCode other) { return other != null && Objects.equals(getCode(), other.getCode()); } - default boolean isSameCodeAs(IWithIntCode other) { + default boolean isSameCodeAs(@Nullable IWithIntCode other) { return other != null && getCode() == other.getCode(); } - default boolean isSameCodeAs(IWithLongCode other) { + 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 70192d7..b10d8a2 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/base/IWithLongCode.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/base/IWithLongCode.java @@ -18,6 +18,8 @@ package xyz.zhouxy.plusone.commons.base; import java.util.Objects; +import javax.annotation.Nullable; + /** * 规定实现类带有 {@code getCode} 方法。 * 用于像自定义异常等需要带有 {@code code} 字段的类， @@ -32,15 +34,15 @@ public interface IWithLongCode { return getCode() == code; } - default boolean isSameCodeAs(IWithCode other) { + default boolean isSameCodeAs(@Nullable IWithCode other) { return other != null && Objects.equals(getCode(), other.getCode()); } - default boolean isSameCodeAs(IWithIntCode other) { + default boolean isSameCodeAs(@Nullable IWithIntCode other) { return other != null && getCode() == other.getCode(); } - default boolean isSameCodeAs(IWithLongCode other) { + default boolean isSameCodeAs(@Nullable IWithLongCode other) { return other != null && getCode() == other.getCode(); } } diff --git a/src/main/java/xyz/zhouxy/plusone/commons/base/package-info.java b/src/main/java/xyz/zhouxy/plusone/commons/base/package-info.java new file mode 100644 index 0000000..523b74d --- /dev/null +++ b/src/main/java/xyz/zhouxy/plusone/commons/base/package-info.java @@ -0,0 +1,75 @@ +/* + * Copyright 2025 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * 基础组件 + * + *

Ref

+ *

+ * {@link Ref} 包装了一个值，表示对该值的应用。 + *

+ *

灵感来自于 C# 的 {@value ref} 参数修饰符。C# 允许通过以下方式，将值返回给调用端：

+ * 
+ * void Method(ref int refArgument)
+ * {
+ *     refArgument = refArgument + 44;
+ * }
+ *
+ * int number = 1;
+ * Method(ref number);
+ * Console.WriteLine(number); // Output: 45
+ *
+ * {@link Ref} 使 Java 可以达到类似的效果，如： + * 
+ * void method(Ref<Integer> refArgument) {
+ *     refArgument.transformValue(i -> i + 44);
+ * }
+ *
+ * Ref<Integer> number = Ref.of(1);
+ * method(number);
+ * System.out.println(number.getValue()); // Output: 45
+ *
+ *

+ * 当一个方法需要产生多个结果时，无法有多个返回值，可以使用 {@link Ref} 作为参数传入，方法内部修改 {@link Ref} 的值。 + * 调用方在调用方法之后，使用 {@code getValue()} 获取结果。 + *

+ * 
+ * String method(Ref<Integer> intRefArgument, Ref<String> strRefArgument) {
+ *     intRefArgument.transformValue(i -> i + 44);
+ *     strRefArgument.setValue("Hello " + strRefArgument.getValue());
+ *     return "Return string";
+ * }
+ *
+ * Ref<Integer> number = Ref.of(1);
+ * Ref<String> str = Ref.of("Java");
+ * String result = method(number, str);
+ * System.out.println(number.getValue()); // Output: 45
+ * System.out.println(str.getValue()); // Output: Hello Java
+ * System.out.println(result); // Output: Return string
+ *
+ * + *

IWithCode

+ *

+ * 类似于枚举之类的类，通常需要设置固定的码值表示对应的含义。 + * 可实现 {@link IWithCode}、{@link IWithIntCode}、{@link IWithLongCode}，便于在需要的地方对这些接口的实现进行处理。 + *

+ */ +@CheckReturnValue +@ParametersAreNonnullByDefault +package xyz.zhouxy.plusone.commons.base; + +import javax.annotation.ParametersAreNonnullByDefault; +import javax.annotation.CheckReturnValue; From 0d1935bc8ccb4e13f0381a56e78b57e3d5c77504 Mon Sep 17 00:00:00 2001 From: ZhouXY108 Date: Tue, 7 Jan 2025 16:33:29 +0800 Subject: [PATCH 2/2] =?UTF-8?q?=E6=96=B0=E5=A2=9E=20function=20=E5=8C=85?= =?UTF-8?q?=E7=9A=84=20package-info?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../commons/function/package-info.java | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 src/main/java/xyz/zhouxy/plusone/commons/function/package-info.java diff --git a/src/main/java/xyz/zhouxy/plusone/commons/function/package-info.java b/src/main/java/xyz/zhouxy/plusone/commons/function/package-info.java new file mode 100644 index 0000000..757c37a --- /dev/null +++ b/src/main/java/xyz/zhouxy/plusone/commons/function/package-info.java @@ -0,0 +1,43 @@ +/* + * Copyright 2025 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * 函数式编程 + * + *

PredicateTools

+ *

+ * {@link PredicateTools} 用于 {@link java.util.function.Predicate} 的相关操作。 + *

+ * + *

Functional interfaces

+ *

+ * 补充一些 JDK 没有，而项目中可能用得上的函数式接口： + * 

+ * | Group         | FunctionalInterface  | method                           |
+ * | ------------- | -------------------- | -------------------------------- |
+ * | UnaryOperator | BoolUnaryOperator    | boolean applyAsBool (boolean)    |
+ * | UnaryOperator | CharUnaryOperator    | char applyAsChar(char)           |
+ * | Throwing      | Executable           | void execute() throws E          |
+ * | Throwing      | ThrowingConsumer     | void accept(T) throws E          |
+ * | Throwing      | ThrowingPredicate    | boolean test(T) throws E         |
+ * | Throwing      | ThrowingSupplier     | T get() throws E                 |
+ * | Optional      | OptionalSupplier     | Optional<T> get() throws E       |
+ * | Optional      | ToOptionalBiFunction | Optional<R> apply(T,U)           |
+ * | Optional      | ToOptionalFunction   | Optional<R> apply(T)             |
+ *
+ *

+ */ +package xyz.zhouxy.plusone.commons.function;