Class CronExpression

java.lang.Object
cloud.opencode.base.cron.CronExpression
All Implemented Interfaces:
Serializable
public final class CronExpression extends Object implements Serializable
Cron Expression - Full-Featured Cron Expression Parser and Evaluator Cron表达式 - 功能完整的Cron表达式解析器和评估器

Parses and evaluates cron expressions with full standard Unix cron semantics, including OR logic for day-of-month/day-of-week, special characters (L, W, #), name aliases (MON-FRI, JAN-DEC), and macro support (@daily, @yearly, etc.).

解析和评估具有完整标准Unix Cron语义的Cron表达式， 包括月中日/星期几的OR逻辑、特殊字符（L、W、#）、 名称别名（MON-FRI、JAN-DEC）和宏支持（@daily、@yearly等）。

Features | 主要功能:

  • 5-field and 6-field (with seconds) cron formats - 5字段和6字段（含秒）cron格式
  • Standard OR semantics for day-of-month/day-of-week - 标准OR语义
  • Special characters: L, L-N, LW, nW, n#m, nL - 特殊字符支持
  • Name aliases: MON-FRI, JAN-DEC (case-insensitive) - 名称别名（不区分大小写）
  • Macros: @yearly, @monthly, @weekly, @daily, @hourly - 预定义宏
  • Range wrap-around: 22-2 for hours means 22,23,0,1,2 - 范围回绕
  • Forward scheduling: nextExecution(ZonedDateTime), nextExecutions(ZonedDateTime, int) - 正向调度
  • Reverse scheduling: previousExecution(ZonedDateTime) - 反向调度
  • Human-readable description: describe() - 人类可读描述
  • Serializable with equals/hashCode - 可序列化，支持equals/hashCode

Usage Examples | 使用示例:

// Every day at 10:30 | 每天10:30
CronExpression.parse("30 10 * * *")

// Every weekday at 9:00 | 工作日9:00
CronExpression.parse("0 9 * * MON-FRI")

// 15th of month OR every Monday at noon | 15号或周一中午
CronExpression.parse("0 12 15 * MON")

// Last day of every month at 18:00 | 每月最后一天18:00
CronExpression.parse("0 18 L * *")

// 3rd Friday of every month at 10:00 | 每月第三个周五10:00
CronExpression.parse("0 10 * * FRI#3")

// Next 5 executions | 下5次执行时间
expr.nextExecutions(ZonedDateTime.now(), 5)

// Human-readable | 人类可读描述
expr.describe()  // "At 09:00, Monday through Friday"

Performance | 性能特性:

  • Parse: O(fields) - one-time cost - 解析: O(字段数) - 一次性开销
  • nextExecution: O(1) amortized via field-jumping - 下次执行: 均摊O(1)，字段跳跃优化

Security | 安全性:

  • Thread-safe: Yes (immutable after construction) - 线程安全: 是（构造后不可变）
  • Null-safe: Yes (rejects null inputs) - 空值安全: 是
Since:
JDK 25, opencode-base-cron V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • parse

      public static CronExpression parse(String expression)
      Parse a cron expression 解析Cron表达式

      Supports 5-field, 6-field formats and macros (@yearly, @daily, etc.).

      支持5字段、6字段格式和宏（@yearly、@daily 等）。

      Parameters:
      expression - the cron expression | Cron表达式
      Returns:
      the parsed expression | 解析后的表达式
      Throws:
      OpenCronException - if the expression is invalid | 如果表达式无效

    • matches

      public boolean matches(ZonedDateTime time)
      Check if a time matches this cron expression 检查时间是否匹配此Cron表达式
      Parameters:
      time - the time to check | 要检查的时间
      Returns:
      true if the time matches | 如果匹配返回true

    • nextExecution

      public ZonedDateTime nextExecution(ZonedDateTime from)
      Gets the next execution time after the given time 获取给定时间之后的下次执行时间
      Parameters:
      from - the start time | 开始时间
      Returns:
      the next execution time, or null if none within 4 years | 下次执行时间，如果4年内没有则返回null

    • nextExecutions

      public List<ZonedDateTime> nextExecutions(ZonedDateTime from, int count)
      Gets the next N execution times after the given time 获取给定时间之后的下N次执行时间
      Parameters:
      from - the start time | 开始时间
      count - the number of executions | 执行次数
      Returns:
      the list of execution times | 执行时间列表
      Throws:
      IllegalArgumentException - if count is not positive | 如果count不是正数

    • previousExecution

      public ZonedDateTime previousExecution(ZonedDateTime from)
      Gets the previous execution time before the given time 获取给定时间之前的上次执行时间
      Parameters:
      from - the reference time | 参考时间
      Returns:
      the previous execution time, or null if none within 4 years | 上次执行时间，如果4年内没有则返回null

    • previousExecutions

      public List<ZonedDateTime> previousExecutions(ZonedDateTime from, int count)
      Gets the previous N execution times before the given time 获取给定时间之前的前N次执行时间
      Parameters:
      from - the reference time | 参考时间
      count - the number of executions | 执行次数
      Returns:
      the list of execution times (newest first) | 执行时间列表（最新在前）
      Throws:
      IllegalArgumentException - if count is not positive | 如果count不是正数

    • describe

      public String describe()
      Gets a human-readable description of this expression 获取此表达式的人类可读描述
      Returns:
      the description in English | 英文描述

    • getExpression

      public String getExpression()
      Gets the original expression string 获取原始表达式字符串
      Returns:
      the expression | 表达式

    • hasSeconds

      public boolean hasSeconds()
      Checks if this expression uses 6-field format (with seconds) 检查此表达式是否使用6字段格式（含秒）
      Returns:
      true if 6-field format | 如果是6字段格式返回true

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object