From f733e1ff5aaf6bbe8da0eb9bc5133053c643ef38 Mon Sep 17 00:00:00 2001 From: SerLiunx-ctrl <17689543@qq.com> Date: Fri, 16 May 2025 17:16:50 +0800 Subject: [PATCH] =?UTF-8?q?doc:=20=E6=96=87=E6=A1=A3=E6=A0=87=E5=87=86?= =?UTF-8?q?=E5=8C=96.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../machine/ConcurrentStateMachine.java | 8 +-- .../DefaultConcurrentStateMachine.java | 14 ++++-- .../machine/HandlerInvocationDelegate.java | 12 ++++- .../machine/StateEventRegistry.java | 49 +++++++++++++++---- .../statemanagement/machine/StateMachine.java | 16 ++++-- .../machine/StateMachineBuilder.java | 34 ++++++++++--- .../machine/handler/StateHandlerWrapper.java | 3 +- .../manager/AbstractStateManager.java | 20 ++++++-- .../BreakageUnidirectionalStateManager.java | 6 ++- .../manager/CircleStateManager.java | 4 +- .../DefaultUnidirectionalStateManager.java | 3 ++ .../statemanagement/manager/StateManager.java | 6 ++- .../manager/UnidirectionalStateManager.java | 16 +++--- .../support/ExecutorUtils.java | 5 +- 14 files changed, 146 insertions(+), 50 deletions(-) diff --git a/src/main/java/com/serliunx/statemanagement/machine/ConcurrentStateMachine.java b/src/main/java/com/serliunx/statemanagement/machine/ConcurrentStateMachine.java index 02fa16b..bd0aea3 100644 --- a/src/main/java/com/serliunx/statemanagement/machine/ConcurrentStateMachine.java +++ b/src/main/java/com/serliunx/statemanagement/machine/ConcurrentStateMachine.java @@ -1,8 +1,9 @@ package com.serliunx.statemanagement.machine; /** - * 基本行为与{@link StateMachine} 一致, 最大不同是切换状态不再使用直接的锁机制, 具体由实现类决定 - *
  • 默认实现{@link DefaultConcurrentStateMachine}, 状态切换序列由CAS实现. + * 基本行为与{@link StateMachine} 一致, 最大不同是切换状态不再使用直接的锁机制, 具体由实现类决定; + *

    + * 默认实现{@link DefaultConcurrentStateMachine}, 状态切换序列由CAS实现. * * @author SerLiunx * @version 1.0.0 @@ -12,8 +13,7 @@ package com.serliunx.statemanagement.machine; public interface ConcurrentStateMachine extends StateMachine { /** - * 尝试使用CAS更新状态 - *

  • 成功更新时触发状态处理器 + * 尝试使用CAS更新状态, 成功更新时触发状态处理器 * * @param expectedValue 前置状态 * @param newValue 更新的状态值 diff --git a/src/main/java/com/serliunx/statemanagement/machine/DefaultConcurrentStateMachine.java b/src/main/java/com/serliunx/statemanagement/machine/DefaultConcurrentStateMachine.java index ae7d505..9206cf2 100644 --- a/src/main/java/com/serliunx/statemanagement/machine/DefaultConcurrentStateMachine.java +++ b/src/main/java/com/serliunx/statemanagement/machine/DefaultConcurrentStateMachine.java @@ -161,6 +161,8 @@ public class DefaultConcurrentStateMachine extends AbstractStateMachine im /** * 是否为默认状态 + * + * @return 默认状态时返回真, 否则返回假. */ protected boolean isDefault() { return index.get() == 0; @@ -168,7 +170,9 @@ public class DefaultConcurrentStateMachine extends AbstractStateMachine im /** * 移动下标至上一个状态 - *
  • 使用CAS一直尝试, 直到成功 + *

    + * 使用CAS一直尝试, 直到成功 + *

    */ protected void exchangeToPrev() { final int size = size(); @@ -180,7 +184,9 @@ public class DefaultConcurrentStateMachine extends AbstractStateMachine im /** * 移动下标至下一个状态 - *
  • 使用CAS一直尝试, 直到成功 + *

    + * 使用CAS一直尝试, 直到成功 + *

    */ protected void exchangeToNext() { final int size = size(); @@ -192,7 +198,9 @@ public class DefaultConcurrentStateMachine extends AbstractStateMachine im /** * 切换到指定状态值 - *
  • 使用CAS一直尝试, 直到成功 + *

    + * 使用CAS一直尝试, 直到成功 + *

    * * @param target 目标值 */ diff --git a/src/main/java/com/serliunx/statemanagement/machine/HandlerInvocationDelegate.java b/src/main/java/com/serliunx/statemanagement/machine/HandlerInvocationDelegate.java index 03abe4a..9b31a12 100644 --- a/src/main/java/com/serliunx/statemanagement/machine/HandlerInvocationDelegate.java +++ b/src/main/java/com/serliunx/statemanagement/machine/HandlerInvocationDelegate.java @@ -18,8 +18,10 @@ public final class HandlerInvocationDelegate { /** * 触发处理器 * - * @param from 源状态 - * @param to 目的状态 + * @param context 状态机上下文 + * @param from 源状态 + * @param to 目的状态 + * @param 状态类型 */ public static void invokeHandlers(StateMachineContext context, S from, S to) { // 触发离开处理器 @@ -35,6 +37,12 @@ public final class HandlerInvocationDelegate { /** * 触发逻辑 + * + * @param context 状态机上下文 + * @param handlerWrappers 封装后处理器集合 + * @param from 源状态 + * @param to 目的状态 + * @param 状态类型 */ public static void doInvokeHandlers(StateMachineContext context, List> handlerWrappers, S from, S to) { diff --git a/src/main/java/com/serliunx/statemanagement/machine/StateEventRegistry.java b/src/main/java/com/serliunx/statemanagement/machine/StateEventRegistry.java index 84affeb..b5b069a 100644 --- a/src/main/java/com/serliunx/statemanagement/machine/StateEventRegistry.java +++ b/src/main/java/com/serliunx/statemanagement/machine/StateEventRegistry.java @@ -7,8 +7,10 @@ import java.util.concurrent.Executor; /** * 状态机之状态事件注册 - *
  • 注册状态切换时的事件, 一般用于状态机构建和支持动态调整的状态机{@link FlexibleStateMachine}; + *

    + * 注册状态切换时的事件, 一般用于状态机构建和支持动态调整的状态机{@link FlexibleStateMachine}; * 当然实际不仅于此, 任何相关的都可以使用. + *

    * * @author SerLiunx * @since 2025/3/28 @@ -18,94 +20,121 @@ public interface StateEventRegistry { /** * 添加进入事件 - *
  • 切换到了指定状态时执行的逻辑 + *

    + * 切换到了指定状态时执行的逻辑 + *

    * * @param state 状态 * @param handler 处理逻辑 * @param async 是否异步执行 * @param executor 异步执行器, 异步执行时将使用, 不指定时将使用状态机内置的执行器 + * @return 当前对象, 链式调用 */ StateEventRegistry whenEntry(S state, StateHandler handler, Boolean async, Executor executor); /** * 添加进入事件 - *
  • 切换到了指定状态时执行的逻辑 + *

    + * 切换到了指定状态时执行的逻辑 + *

    * * @param state 状态 * @param handler 处理逻辑 * @param async 是否异步执行 + * @return 当前对象, 链式调用 */ StateEventRegistry whenEntry(S state, StateHandler handler, Boolean async); /** * 添加进入事件 - *
  • 切换到了指定状态时执行的逻辑 + *

    + * 切换到了指定状态时执行的逻辑 + *

    * * @param state 状态 * @param handler 处理逻辑 + * @return 当前对象, 链式调用 */ StateEventRegistry whenEntry(S state, StateHandler handler); /** * 添加离开事件 - *
  • 从指定状态切换到别的状态时执行的逻辑 + *

    + * 从指定状态切换到别的状态时执行的逻辑 + *

    * * @param state 状态 * @param handler 处理逻辑 * @param async 是否异步执行 * @param executor 异步执行器, 异步执行时将使用, 不指定时将使用状态机内置的执行器 + * @return 当前对象, 链式调用 */ StateEventRegistry whenLeave(S state, StateHandler handler, Boolean async, Executor executor); /** * 添加离开事件 - *
  • 从指定状态切换到别的状态时执行的逻辑 + *

    + * 从指定状态切换到别的状态时执行的逻辑 + *

    * * @param state 状态 * @param handler 处理逻辑 * @param async 是否异步执行 + * @return 当前对象, 链式调用 */ StateEventRegistry whenLeave(S state, StateHandler handler, Boolean async); /** * 添加离开事件 - *
  • 从指定状态切换到别的状态时执行的逻辑 + *

    + * 从指定状态切换到别的状态时执行的逻辑 + *

    * * @param state 状态 * @param handler 处理逻辑 + * @return 当前对象, 链式调用 */ StateEventRegistry whenLeave(S state, StateHandler handler); /** * 添加交换事件 - *
  • 从A状态切换至B状态时触发 + *

    + * 从A状态切换至B状态时触发 + *

    * * @param from 源状态 * @param to 目的状态 * @param handler 处理器 * @param async 是否异步执行 * @param executor 异步执行器, 异步执行时将使用, 不指定时将使用状态机内置的执行器 + * @return 当前对象, 链式调用 */ StateEventRegistry exchange(S from, S to, StateHandler handler, Boolean async, Executor executor); /** * 添加交换事件 - *
  • 从A状态切换至B状态时触发 + *

    + * 从A状态切换至B状态时触发 + *

    * * @param from 源状态 * @param to 目的状态 * @param handler 处理器 * @param async 是否异步执行 + * @return 当前对象, 链式调用 */ StateEventRegistry exchange(S from, S to, StateHandler handler, Boolean async); /** * 添加交换事件 - *
  • 从A状态切换至B状态时触发 + *

    + * 从A状态切换至B状态时触发 + *

    * * @param from 源状态 * @param to 目的状态 * @param handler 处理器 + * @return 当前对象, 链式调用 */ StateEventRegistry exchange(S from, S to, StateHandler handler); } diff --git a/src/main/java/com/serliunx/statemanagement/machine/StateMachine.java b/src/main/java/com/serliunx/statemanagement/machine/StateMachine.java index b2ef0e4..b7ba952 100644 --- a/src/main/java/com/serliunx/statemanagement/machine/StateMachine.java +++ b/src/main/java/com/serliunx/statemanagement/machine/StateMachine.java @@ -7,9 +7,11 @@ import com.serliunx.statemanagement.manager.BidirectionalStateManager; *

    * 基于双向的状态管理器扩展 {@link BidirectionalStateManager}; * 同时可以监听多种事件和发布事件, 包括: - *

  • 切换至指定状态时触发 (进入事件) - *
  • 切出指定状态时触发 (离开事件) - *
  • 从A切换到B状态时触发 (交换事件) + *
      + *
    • 切换至指定状态时触发 (进入事件) + *
    • 切出指定状态时触发 (离开事件) + *
    • 从A切换到B状态时触发 (交换事件) + *
    *

    * 请使用 {@link StateMachineBuilder} 来构建状态机. * @@ -77,7 +79,9 @@ public interface StateMachine extends BidirectionalStateManager, AutoClose /** * 切换至指定状态 - *

  • 在使用状态机的情况, 仅切换成功才会触发注册的各种事件. + *

    + * 在使用状态机的情况, 仅切换成功才会触发注册的各种事件. + *

    * * @param invokeHandlers 是否唤醒状态处理器 * @param state 新的状态 @@ -94,7 +98,9 @@ public interface StateMachine extends BidirectionalStateManager, AutoClose /** * 切换至指定状态 - *
  • 在使用状态机的情况, 仅切换成功才会触发注册的各种事件. + *

    + * 在使用状态机的情况, 仅切换成功才会触发注册的各种事件. + *

    * * @param state 新的状态 * @return 切换成功返回真, 否则返回假 diff --git a/src/main/java/com/serliunx/statemanagement/machine/StateMachineBuilder.java b/src/main/java/com/serliunx/statemanagement/machine/StateMachineBuilder.java index 97f8227..a4ebeea 100644 --- a/src/main/java/com/serliunx/statemanagement/machine/StateMachineBuilder.java +++ b/src/main/java/com/serliunx/statemanagement/machine/StateMachineBuilder.java @@ -57,6 +57,7 @@ public final class StateMachineBuilder implements StateEventRegistry { * 定义初始状态 * * @param initialState 初始状态 + * @return 状态机构建 */ public StateMachineBuilder withInitial(S initialState) { this.initialState = initialState; @@ -123,6 +124,7 @@ public final class StateMachineBuilder implements StateEventRegistry { * * @param event 事件 * @param logic 切换逻辑 + * @return 当前对象, 链式调用 */ public StateMachineBuilder whenHappened(Object event, Consumer> logic) { List>> consumers = eventRegistries.computeIfAbsent(event, k -> new ArrayList<>()); @@ -136,6 +138,7 @@ public final class StateMachineBuilder implements StateEventRegistry { * 优先级低于添加事件时指定的执行器 * * @param executor 执行器 + * @return 当前对象, 链式调用 */ public StateMachineBuilder executor(Executor executor) { this.executor = executor; @@ -146,6 +149,7 @@ public final class StateMachineBuilder implements StateEventRegistry { * 定义状态机是否异步执行 * * @param async 是否异步执行 + * @return 当前对象, 链式调用 */ public StateMachineBuilder async(Boolean async) { this.async = async; @@ -154,6 +158,8 @@ public final class StateMachineBuilder implements StateEventRegistry { /** * 定义状态机为异步执行 + * + * @return 当前对象, 链式调用 */ public StateMachineBuilder async() { return async(true); @@ -161,9 +167,12 @@ public final class StateMachineBuilder implements StateEventRegistry { /** * 指定状态机的类型 - *
  • 状态机并发与否并不影响事件的执行逻辑 + *

    + * 状态机并发与否并不影响事件的执行逻辑 + *

    * * @param type 类型 + * @return 当前对象, 链式调用 */ public StateMachineBuilder type(StateMachineType type) { if (type == null) { @@ -175,7 +184,11 @@ public final class StateMachineBuilder implements StateEventRegistry { /** * 指定状态机的类型为标准型 - *
  • 状态机并发与否并不影响事件的执行逻辑 + *

    + * 状态机并发与否并不影响事件的执行逻辑 + *

    + * + * @return 当前对象, 链式调用 */ public StateMachineBuilder standard() { return type(StateMachineType.STANDARD); @@ -183,14 +196,21 @@ public final class StateMachineBuilder implements StateEventRegistry { /** * 指定状态机的类型为并发型 - *
  • 状态机并发与否并不影响事件的执行逻辑 + *

    + * 状态机并发与否并不影响事件的执行逻辑 + *

    + * + * @return 当前对象, 链式调用 */ public StateMachineBuilder concurrent() { return type(StateMachineType.CONCURRENT); } /** - * 构建 + * 执行构建 + * + * @param 状态机类型 + * @return 状态机 */ @SuppressWarnings("unchecked") public > M build() { @@ -210,7 +230,8 @@ public final class StateMachineBuilder implements StateEventRegistry { /** * 状态机构建器 * - * @param states 状态集合 + * @param 状态类型 + * @param states 状态集合 * @return 状态机构建器实例 */ public static StateMachineBuilder from(S[] states) { @@ -220,7 +241,8 @@ public final class StateMachineBuilder implements StateEventRegistry { /** * 状态机构建器 * - * @param states 状态集合 + * @param 状态类型 + * @param states 状态集合 * @return 状态机构建器实例 */ public static StateMachineBuilder from(List states) { diff --git a/src/main/java/com/serliunx/statemanagement/machine/handler/StateHandlerWrapper.java b/src/main/java/com/serliunx/statemanagement/machine/handler/StateHandlerWrapper.java index c8cacc6..dba5361 100644 --- a/src/main/java/com/serliunx/statemanagement/machine/handler/StateHandlerWrapper.java +++ b/src/main/java/com/serliunx/statemanagement/machine/handler/StateHandlerWrapper.java @@ -19,7 +19,8 @@ public final class StateHandlerWrapper { private final StateHandler stateHandler; /** * 执行器 - *
  • 用于异步执行处理逻辑 + *

    + * 用于异步执行处理逻辑 */ private final Executor executor; /** diff --git a/src/main/java/com/serliunx/statemanagement/manager/AbstractStateManager.java b/src/main/java/com/serliunx/statemanagement/manager/AbstractStateManager.java index a901062..a398a9c 100644 --- a/src/main/java/com/serliunx/statemanagement/manager/AbstractStateManager.java +++ b/src/main/java/com/serliunx/statemanagement/manager/AbstractStateManager.java @@ -112,8 +112,10 @@ public abstract class AbstractStateManager implements StateManager { /** * 将序号移动至下一个 - *

  • 自动归零 - *
  • 仅在持有写锁的情况下访问 + *
      + *
    • 自动归零 + *
    • 仅在持有写锁的情况下访问 + *
    */ @SuppressWarnings("all") protected void next() { @@ -123,8 +125,10 @@ public abstract class AbstractStateManager implements StateManager { /** * 将序号移动至上一个 - *
  • 自动归零 - *
  • 仅在持有写锁的情况下访问 + *
      + *
    • 自动归零 + *
    • 仅在持有写锁的情况下访问 + *
    */ @SuppressWarnings("all") protected void prev() { @@ -137,7 +141,9 @@ public abstract class AbstractStateManager implements StateManager { *

    * 类及子类访问当前状态时不允许使用{@link #current()}，因为会造成死锁 * - *

  • 仅在持有锁的情况下访问 + *

    + * 仅在持有锁的情况下访问 + *

    * * @return 当前状态 */ @@ -197,6 +203,8 @@ public abstract class AbstractStateManager implements StateManager { /** * 更新当前状态的序号 + * + * @param newIndex 新的序号 */ protected void updateCurrentIndex(int newIndex) { index = newIndex; @@ -204,6 +212,8 @@ public abstract class AbstractStateManager implements StateManager { /** * 状态序号默认值(等同于默认状态) + * + * @return 默认的状态值 */ protected int getDefault() { return defaultIndex; diff --git a/src/main/java/com/serliunx/statemanagement/manager/BreakageUnidirectionalStateManager.java b/src/main/java/com/serliunx/statemanagement/manager/BreakageUnidirectionalStateManager.java index 0073e98..5cccd18 100644 --- a/src/main/java/com/serliunx/statemanagement/manager/BreakageUnidirectionalStateManager.java +++ b/src/main/java/com/serliunx/statemanagement/manager/BreakageUnidirectionalStateManager.java @@ -6,8 +6,10 @@ import java.util.List; /** * 断路的单向状态管理器 - *

    逻辑与{@link UnidirectionalStateManager}大体相同, 不同的点在于: - *

  • 最后一个状态无法转向第一个状态, 即为一次性的状态管理器. + *

    + * 逻辑与{@link UnidirectionalStateManager}大体相同, 不同的点在于: + * 最后一个状态无法转向第一个状态, 即为一次性的状态管理器. + *

    * * @author SerLiunx * @version 1.0.0 diff --git a/src/main/java/com/serliunx/statemanagement/manager/CircleStateManager.java b/src/main/java/com/serliunx/statemanagement/manager/CircleStateManager.java index c6e86f1..7dc7738 100644 --- a/src/main/java/com/serliunx/statemanagement/manager/CircleStateManager.java +++ b/src/main/java/com/serliunx/statemanagement/manager/CircleStateManager.java @@ -2,7 +2,9 @@ package com.serliunx.statemanagement.manager; /** * 将指定状态管理器标记为循环的状态管理器 - *
  • 允许单向、双向循环 + *

    + * 允许单向、双向循环 + *

    * * @author SerLiunx * @version 1.0.0 diff --git a/src/main/java/com/serliunx/statemanagement/manager/DefaultUnidirectionalStateManager.java b/src/main/java/com/serliunx/statemanagement/manager/DefaultUnidirectionalStateManager.java index 1e13604..344e06e 100644 --- a/src/main/java/com/serliunx/statemanagement/manager/DefaultUnidirectionalStateManager.java +++ b/src/main/java/com/serliunx/statemanagement/manager/DefaultUnidirectionalStateManager.java @@ -83,6 +83,9 @@ public class DefaultUnidirectionalStateManager extends AbstractStateManager { /** * 如果是指定的状态则切换到另一个状态 - *
  • 例: 检测当前状态是否为 1 且可切换, 如何为 1 则将状态切换到 2 - *
  • 结合了 {@link #current()}、 {@link #switchTo(Object)} 及 {@link #isSwitchable()} + *

    + * 例: 检测当前状态是否为 1 且可切换, 如何为 1 则将状态切换到 2; + * 结合了 {@link #current()}、 {@link #switchTo(Object)} 及 {@link #isSwitchable()} + *

    * * @param now 当前状态 * @param newState 新的状态 diff --git a/src/main/java/com/serliunx/statemanagement/manager/UnidirectionalStateManager.java b/src/main/java/com/serliunx/statemanagement/manager/UnidirectionalStateManager.java index d2d9f62..81e142e 100644 --- a/src/main/java/com/serliunx/statemanagement/manager/UnidirectionalStateManager.java +++ b/src/main/java/com/serliunx/statemanagement/manager/UnidirectionalStateManager.java @@ -3,14 +3,14 @@ package com.serliunx.statemanagement.manager; /** * 单向流转的状态管理器 *

    - * 其基本逻辑等同于 {@link StateManager}, 但存在以下不同: - *

  • 状态只能单方向流动(最后一个状态允许切换至第一个状态), 如果有A, B, C, D 四种状态则存在以下几种情况: - *

    - *

    - *

  • A -> B 允许直接切换, A -> C 允许直接切换, C -> D 允许直接切换 等等.. - *
  • B -> A 不允许切换, C -> A 不允许切换, D -> C 不允许切换 等等.. - *
  • 特例: D -> A 是允许的, 因为D是最后一个状态, 故可以切换至第一个状态. - *

    + * 其基本逻辑等同于 {@link StateManager}, 但存在以下不同: + * 状态只能单方向流动(最后一个状态允许切换至第一个状态), 如果有A, B, C, D 四种状态则存在以下几种情况: + *

    + *
      + *
    • A 至 B 允许直接切换, A 至 C 允许直接切换, C 至 D 允许直接切换 等等.. + *
    • B 至 A 不允许切换, C 至 A 不允许切换, D 至 C 不允许切换 等等.. + *
    • 特例: D 至 A 是允许的, 因为 D 是最后一个状态, 故可以切换至第一个状态. + *
    * 即状态的切换只允许一个方向，不允许向前流动，除非到达最后一个状态! * * @author SerLiunx diff --git a/src/main/java/com/serliunx/statemanagement/support/ExecutorUtils.java b/src/main/java/com/serliunx/statemanagement/support/ExecutorUtils.java index e3ff2df..9aaa303 100644 --- a/src/main/java/com/serliunx/statemanagement/support/ExecutorUtils.java +++ b/src/main/java/com/serliunx/statemanagement/support/ExecutorUtils.java @@ -15,8 +15,11 @@ public final class ExecutorUtils { /** * 快速获取自适应参数的线程池 - *
  • 核心线程数量为当前处理器数量的两倍; 最大线程数量为当前处理器数量的四倍. + *

    + * 核心线程数量为当前处理器数量的两倍; 最大线程数量为当前处理器数量的四倍. + *

    * + * @param rejectedExecutionHandler 拒绝策略 * @return 执行器(线程池) */ public static Executor adaptiveThreadPool(RejectedExecutionHandler rejectedExecutionHandler) {