Class OpenCron

java.lang.Object
cloud.opencode.base.cron.OpenCron
public final class OpenCron extends Object
OpenCron - Cron Expression Facade OpenCron - Cron表达式门面类

Unified entry point for cron expression parsing, validation, scheduling, and human-readable description. All cron functionality is accessible through this single facade class.

Cron表达式解析、验证、调度和人类可读描述的统一入口。 所有Cron功能都可通过此单一门面类访问。

Features | 主要功能:

  • Parse cron expressions (5/6-field, macros, aliases) - 解析Cron表达式
  • Validate expressions with optional minimum interval check - 验证表达式
  • Calculate next/previous execution times - 计算下次/上次执行时间
  • Generate human-readable descriptions - 生成人类可读描述
  • Fluent builder API for constructing expressions - 流式构建器API

Usage Examples | 使用示例:

// Parse and query next execution | 解析并查询下次执行
ZonedDateTime next = OpenCron.nextExecution("0 9 * * MON-FRI", ZonedDateTime.now());

// Get next 5 executions | 获取下5次执行时间
List<ZonedDateTime> times = OpenCron.nextExecutions("30 10 * * *", ZonedDateTime.now(), 5);

// Validate expression | 验证表达式
boolean valid = OpenCron.isValid("0 0 L * *");

// Human-readable description | 人类可读描述
String desc = OpenCron.describe("0 9 * * MON-FRI"); // "At 09:00, Monday through Friday"

// Builder API | 构建器API
CronExpression expr = OpenCron.builder().weekdays().at(9, 0).build();

// Macro support | 宏支持
CronExpression daily = OpenCron.parse("@daily");

Security | 安全性:

  • Thread-safe: Yes (stateless static methods) - 线程安全: 是（无状态静态方法）
  • Null-safe: Yes (rejects null inputs) - 空值安全: 是
Since:
JDK 25, opencode-base-cron V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Field Details

  • Method Details

    • parse

      public static CronExpression parse(String expression)
      Parses a cron expression 解析Cron表达式
      Parameters:
      expression - the cron expression (5/6-field or macro) | Cron表达式（5/6字段或宏）
      Returns:
      the parsed expression | 解析后的表达式
      Throws:
      OpenCronException - if invalid | 如果无效

    • isValid

      public static boolean isValid(String expression)
      Checks if a cron expression is valid 检查Cron表达式是否有效
      Parameters:
      expression - the cron expression | Cron表达式
      Returns:
      true if valid | 如果有效返回true

    • validate

      public static void validate(String expression)
      Validates a cron expression, throwing on failure 验证Cron表达式，失败时抛出异常
      Parameters:
      expression - the cron expression | Cron表达式
      Throws:
      OpenCronException - if invalid | 如果无效

    • validate

      public static void validate(String expression, Duration minInterval)
      Validates a cron expression with minimum interval check 验证Cron表达式并检查最小间隔
      Parameters:
      expression - the cron expression | Cron表达式
      minInterval - the minimum interval | 最小间隔
      Throws:
      OpenCronException - if invalid or interval too short | 如果无效或间隔太短

    • nextExecution

      public static ZonedDateTime nextExecution(String expression, ZonedDateTime from)
      Gets the next execution time 获取下次执行时间
      Parameters:
      expression - the cron expression | Cron表达式
      from - the start time | 开始时间
      Returns:
      the next execution time, or null | 下次执行时间，或null

    • nextExecutions

      public static List<ZonedDateTime> nextExecutions(String expression, ZonedDateTime from, int count)
      Gets the next N execution times 获取下N次执行时间
      Parameters:
      expression - the cron expression | Cron表达式
      from - the start time | 开始时间
      count - the number of executions | 执行次数
      Returns:
      the list of execution times | 执行时间列表

    • previousExecution

      public static ZonedDateTime previousExecution(String expression, ZonedDateTime from)
      Gets the previous execution time 获取上次执行时间
      Parameters:
      expression - the cron expression | Cron表达式
      from - the reference time | 参考时间
      Returns:
      the previous execution time, or null | 上次执行时间，或null

    • previousExecutions

      public static List<ZonedDateTime> previousExecutions(String expression, ZonedDateTime from, int count)
      Gets the previous N execution times 获取前N次执行时间
      Parameters:
      expression - the cron expression | Cron表达式
      from - the reference time | 参考时间
      count - the number of executions | 执行次数
      Returns:
      the list of execution times (newest first) | 执行时间列表（最新在前）

    • getEstimatedInterval

      public static Duration getEstimatedInterval(String expression)
      Gets the estimated interval between executions 获取执行之间的预估间隔
      Parameters:
      expression - the cron expression | Cron表达式
      Returns:
      the estimated interval | 预估间隔

    • timeToNextExecution

      public static Duration timeToNextExecution(String expression, ZonedDateTime from)
      Gets the duration until the next execution 获取距下次执行的时间间隔
      Parameters:
      expression - the cron expression | Cron表达式
      from - the reference time | 参考时间
      Returns:
      the duration to next execution, or null | 距下次执行的Duration，或null

    • timeFromLastExecution

      public static Duration timeFromLastExecution(String expression, ZonedDateTime from)
      Gets the duration since the last execution 获取距上次执行的时间间隔
      Parameters:
      expression - the cron expression | Cron表达式
      from - the reference time | 参考时间
      Returns:
      the duration from last execution, or null | 距上次执行的Duration，或null

    • countExecutionsBetween

      public static long countExecutionsBetween(String expression, ZonedDateTime from, ZonedDateTime to)
      Counts executions between two times 计算两个时间点之间的执行次数
      Parameters:
      expression - the cron expression | Cron表达式
      from - the start time (exclusive) | 开始时间（不包含）
      to - the end time (inclusive) | 结束时间（包含）
      Returns:
      the count of executions | 执行次数

    • executionsBetween

      public static List<ZonedDateTime> executionsBetween(String expression, ZonedDateTime from, ZonedDateTime to)
      Lists all executions between two times 列出两个时间点之间的所有执行时间
      Parameters:
      expression - the cron expression | Cron表达式
      from - the start time (exclusive) | 开始时间（不包含）
      to - the end time (inclusive) | 结束时间（包含）
      Returns:
      unmodifiable list of execution times | 不可修改的执行时间列表

    • isEquivalent

      public static boolean isEquivalent(String expr1, String expr2)
      Checks if two cron expressions produce the same schedule 检查两个Cron表达式是否产生相同的调度
      Parameters:
      expr1 - the first cron expression | 第一个Cron表达式
      expr2 - the second cron expression | 第二个Cron表达式
      Returns:
      true if equivalent schedules | 如果调度等价返回true

    • explain

      public static CronExplanation explain(String expression, ZonedDateTime from)
      Gets a comprehensive explanation for debugging 获取用于调试的综合解释信息
      Parameters:
      expression - the cron expression | Cron表达式
      from - the reference time | 参考时间
      Returns:
      the explanation | 解释信息

    • stream

      public static Stream<ZonedDateTime> stream(String expression, ZonedDateTime from)
      Returns a lazy stream of future execution times 返回未来执行时间的惰性流
      Parameters:
      expression - the cron expression | Cron表达式
      from - the start time (exclusive) | 开始时间（不包含）
      Returns:
      an ordered stream of execution times | 有序的执行时间流

    • reverseStream

      public static Stream<ZonedDateTime> reverseStream(String expression, ZonedDateTime from)
      Returns a lazy stream of past execution times (newest first) 返回过去执行时间的惰性流（最新在前）
      Parameters:
      expression - the cron expression | Cron表达式
      from - the reference time (exclusive) | 参考时间（不包含）
      Returns:
      an ordered stream of past execution times | 有序的过去执行时间流

    • nextExecution

      public static ZonedDateTime nextExecution(String expression, ZonedDateTime from, Predicate<ZonedDateTime> filter)
      Gets the next execution time that satisfies a filter 获取满足过滤条件的下次执行时间
      Parameters:
      expression - the cron expression | Cron表达式
      from - the start time (exclusive) | 开始时间（不包含）
      filter - the filter predicate | 过滤谓词
      Returns:
      the next matching execution time, or null | 下次匹配的执行时间

    • previousExecution

      public static ZonedDateTime previousExecution(String expression, ZonedDateTime from, Predicate<ZonedDateTime> filter)
      Gets the previous execution time that satisfies a filter 获取满足过滤条件的上次执行时间
      Parameters:
      expression - the cron expression | Cron表达式
      from - the reference time (exclusive) | 参考时间（不包含）
      filter - the filter predicate | 过滤谓词
      Returns:
      the previous matching execution time, or null | 上次匹配的执行时间

    • nextOverlap

      public static ZonedDateTime nextOverlap(String expr1, String expr2, ZonedDateTime from)
      Finds the next time both expressions fire simultaneously 查找两个表达式同时触发的下一个时间
      Parameters:
      expr1 - the first cron expression | 第一个Cron表达式
      expr2 - the second cron expression | 第二个Cron表达式
      from - the start time (exclusive) | 开始时间（不包含）
      Returns:
      the next overlapping time, or null | 下一个重叠时间

    • hasOverlap

      public static boolean hasOverlap(String expr1, String expr2, ZonedDateTime from, ZonedDateTime to)
      Checks if two expressions overlap in a time range 检查两个表达式在时间范围内是否有重叠
      Parameters:
      expr1 - the first cron expression | 第一个Cron表达式
      expr2 - the second cron expression | 第二个Cron表达式
      from - the start time (exclusive) | 开始时间（不包含）
      to - the end time (inclusive) | 结束时间（包含）
      Returns:
      true if overlapping | 如果重叠返回true

    • describe

      public static String describe(String expression)
      Gets a human-readable description of a cron expression 获取Cron表达式的人类可读描述
      Parameters:
      expression - the cron expression | Cron表达式
      Returns:
      the description | 描述

    • describe

      public static String describe(String expression, Locale locale)
      Gets a human-readable description in the specified locale 获取指定语言的人类可读描述
      Parameters:
      expression - the cron expression | Cron表达式
      locale - the locale | 语言
      Returns:
      the localized description | 本地化描述

    • builder

      public static CronBuilder builder()
      Creates a new cron expression builder 创建新的Cron表达式构建器
      Returns:
      the builder | 构建器