Class CronBuilder

java.lang.Object
cloud.opencode.base.cron.CronBuilder
public final class CronBuilder extends Object
Cron Builder - Fluent API for Building Cron Expressions Cron构建器 - 构建Cron表达式的流式API

Type-safe builder for constructing valid cron expressions with input validation and support for special characters (L, W, #).

用于构建有效Cron表达式的类型安全构建器， 支持输入校验和特殊字符（L、W、#）。

Features | 主要功能:

  • Fluent API for 5-field and 6-field cron expressions - 流式API支持5字段和6字段cron表达式
  • Type-safe day-of-week via DayOfWeek enum - 通过 DayOfWeek 枚举实现类型安全的星期设置
  • Special characters: L (last), W (weekday), # (nth occurrence) - 特殊字符：L（最后）、W（工作日）、#（第N个）
  • Input validation on all setters - 所有设置器都有输入校验
  • Convenience factories: everySeconds, everyMinutes, everyHours - 便捷工厂方法

Usage Examples | 使用示例:

// Every day at 10:30 | 每天10:30
CronBuilder.every().day().at(10, 30).buildExpression()    // "30 10 * * *"

// Weekdays at 9:00 | 工作日9:00
CronBuilder.every().weekdays().at(9, 0).buildExpression() // "0 9 * * 1-5"

// Every 5 seconds | 每5秒
CronBuilder.everySeconds(5).buildExpression()             // "0/5 * * * * *"

// Last day of month at 18:00 | 每月最后一天18:00
CronBuilder.create().lastDayOfMonth().at(18, 0).buildExpression() // "0 18 L * *"

// 3rd Friday of every month at 10:00 | 每月第三个周五10:00
CronBuilder.create().nthDayOfWeek(DayOfWeek.FRIDAY, 3).at(10, 0).buildExpression()
    // "0 10 * * 5#3"

Security | 安全性:

  • Thread-safe: No (not shared across threads) - 线程安全: 否（不跨线程共享）
  • Null-safe: Yes (rejects null DayOfWeek) - 空值安全: 是

Performance | 性能特性:

  • Time complexity: O(1) - each setter and buildExpression are constant time - 时间复杂度: O(1)，每个 setter 和 buildExpression 均为常量时间
  • Space complexity: O(1) - stores at most 6 field strings - 空间复杂度: O(1) 最多存储 6 个字段字符串
Since:
JDK 25, opencode-base-cron V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • create

      public static CronBuilder create()
      Creates a new builder 创建新构建器
      Returns:
      the builder | 构建器

    • every

      public static CronBuilder every()
      Creates a new builder with fluent "every" semantics 创建具有"每"语义的新构建器
      Returns:
      the builder | 构建器

    • everySeconds

      public static CronBuilder everySeconds(int n)
      Creates schedule that fires every N seconds (6-field cron) 创建每N秒触发的调度（6字段cron）
      Parameters:
      n - the interval in seconds (1-59) | 秒间隔（1-59）
      Returns:
      the builder | 构建器
      Throws:
      IllegalArgumentException - if n is out of range | 如果n超出范围

    • everyMinutes

      public static CronBuilder everyMinutes(int n)
      Creates schedule that fires every N minutes 创建每N分钟触发的调度
      Parameters:
      n - the interval in minutes (1-59) | 分钟间隔（1-59）
      Returns:
      the builder | 构建器
      Throws:
      IllegalArgumentException - if n is out of range | 如果n超出范围

    • everyHours

      public static CronBuilder everyHours(int n)
      Creates schedule that fires every N hours 创建每N小时触发的调度
      Parameters:
      n - the interval in hours (1-23) | 小时间隔（1-23）
      Returns:
      the builder | 构建器
      Throws:
      IllegalArgumentException - if n is out of range | 如果n超出范围

    • everyDays

      public static CronBuilder everyDays(int n)
      Creates schedule that fires every N days at midnight 创建每N天午夜触发的调度
      Parameters:
      n - the interval in days (1-31) | 天间隔（1-31）
      Returns:
      the builder | 构建器
      Throws:
      IllegalArgumentException - if n is out of range | 如果n超出范围

    • at

      public CronBuilder at(int hour, int minute)
      Sets hour and minute for execution 设置执行的小时和分钟
      Parameters:
      hour - the hour (0-23) | 小时（0-23）
      minute - the minute (0-59) | 分钟（0-59）
      Returns:
      this builder | 此构建器
      Throws:
      IllegalArgumentException - if out of range | 如果超出范围

    • second

      public CronBuilder second(int s)
      Sets the second field (enables 6-field cron format) 设置秒字段（启用6字段cron格式）
      Parameters:
      s - the second (0-59) | 秒（0-59）
      Returns:
      this builder | 此构建器
      Throws:
      IllegalArgumentException - if out of range | 如果超出范围

    • minute

      public CronBuilder minute(int m)
      Sets the minute field 设置分钟字段
      Parameters:
      m - the minute (0-59) | 分钟（0-59）
      Returns:
      this builder | 此构建器
      Throws:
      IllegalArgumentException - if out of range | 如果超出范围

    • hour

      public CronBuilder hour(int h)
      Sets the hour field 设置小时字段
      Parameters:
      h - the hour (0-23) | 小时（0-23）
      Returns:
      this builder | 此构建器
      Throws:
      IllegalArgumentException - if out of range | 如果超出范围

    • day

      public CronBuilder day()
      Sets to every day (default, no-op) 设置为每天（默认，无操作）
      Returns:
      this builder | 此构建器

    • dayOfMonth

      public CronBuilder dayOfMonth(int d)
      Sets the day-of-month field 设置月中日字段
      Parameters:
      d - the day of month (1-31) | 月中日（1-31）
      Returns:
      this builder | 此构建器
      Throws:
      IllegalArgumentException - if out of range | 如果超出范围

    • month

      public CronBuilder month(int m)
      Sets the month field 设置月份字段
      Parameters:
      m - the month (1-12) | 月份（1-12）
      Returns:
      this builder | 此构建器
      Throws:
      IllegalArgumentException - if out of range | 如果超出范围

    • lastDayOfMonth

      public CronBuilder lastDayOfMonth()
      Sets to the last day of the month (L) 设置为月最后一天（L）
      Returns:
      this builder | 此构建器

    • lastDayOfMonth

      public CronBuilder lastDayOfMonth(int offset)
      Sets to N days before the last day of month (L-N) 设置为月最后一天前N天（L-N）
      Parameters:
      offset - the offset from last day (0-30) | 距最后一天的偏移（0-30）
      Returns:
      this builder | 此构建器
      Throws:
      IllegalArgumentException - if offset is out of range | 如果偏移超出范围

    • nearestWeekday

      public CronBuilder nearestWeekday(int day)
      Sets to the nearest weekday to a specific day (nW) 设置为最接近指定日的工作日（nW）
      Parameters:
      day - the target day of month (1-31) | 目标月中日（1-31）
      Returns:
      this builder | 此构建器
      Throws:
      IllegalArgumentException - if day is out of range | 如果日期超出范围

    • lastWeekdayOfMonth

      public CronBuilder lastWeekdayOfMonth()
      Sets to the last weekday of the month (LW) 设置为月最后一个工作日（LW）
      Returns:
      this builder | 此构建器

    • monday

      public CronBuilder monday()
      Sets to Monday 设置为星期一
      Returns:
      this builder | 此构建器

    • tuesday

      public CronBuilder tuesday()
      Sets to Tuesday 设置为星期二
      Returns:
      this builder | 此构建器

    • wednesday

      public CronBuilder wednesday()
      Sets to Wednesday 设置为星期三
      Returns:
      this builder | 此构建器

    • thursday

      public CronBuilder thursday()
      Sets to Thursday 设置为星期四
      Returns:
      this builder | 此构建器

    • friday

      public CronBuilder friday()
      Sets to Friday 设置为星期五
      Returns:
      this builder | 此构建器

    • saturday

      public CronBuilder saturday()
      Sets to Saturday 设置为星期六
      Returns:
      this builder | 此构建器

    • sunday

      public CronBuilder sunday()
      Sets to Sunday 设置为星期日
      Returns:
      this builder | 此构建器

    • weekdays

      public CronBuilder weekdays()
      Sets to weekdays (Monday-Friday) 设置为工作日（周一到周五）
      Returns:
      this builder | 此构建器

    • weekends

      public CronBuilder weekends()
      Sets to weekends (Saturday-Sunday) 设置为周末（周六和周日）
      Returns:
      this builder | 此构建器

    • dayOfWeek

      public CronBuilder dayOfWeek(DayOfWeek dow)
      Sets the day of week from DayOfWeek 从 DayOfWeek 设置星期几
      Parameters:
      dow - the day of week | 星期几
      Returns:
      this builder | 此构建器

    • nthDayOfWeek

      public CronBuilder nthDayOfWeek(DayOfWeek dow, int nth)
      Sets to the Nth occurrence of a day of week in the month (n#m) 设置为月中第N个某星期几（n#m）
      Parameters:
      dow - the day of week | 星期几
      nth - the ordinal (1-5) | 序号（1-5）
      Returns:
      this builder | 此构建器
      Throws:
      IllegalArgumentException - if nth is out of range | 如果序号超出范围

    • lastDayOfWeek

      public CronBuilder lastDayOfWeek(DayOfWeek dow)
      Sets to the last occurrence of a day of week in the month (nL) 设置为月中最后一个某星期几（nL）
      Parameters:
      dow - the day of week | 星期几
      Returns:
      this builder | 此构建器

    • dayOfMonthRange

      public CronBuilder dayOfMonthRange(int from, int to)
      Sets the day-of-month field to a range (e.g., 10-20) 设置月中日字段为范围（如10-20）
      Parameters:
      from - the start day (1-31) | 起始日（1-31）
      to - the end day (1-31) | 结束日（1-31）
      Returns:
      this builder | 此构建器
      Throws:
      IllegalArgumentException - if out of range | 如果超出范围

    • monthRange

      public CronBuilder monthRange(int from, int to)
      Sets the month field to a range (e.g., 3-9) 设置月份字段为范围（如3-9）
      Parameters:
      from - the start month (1-12) | 起始月份（1-12）
      to - the end month (1-12) | 结束月份（1-12）
      Returns:
      this builder | 此构建器
      Throws:
      IllegalArgumentException - if out of range | 如果超出范围

    • secondRange

      public CronBuilder secondRange(int from, int to)
      Sets the second field to a range (enables 6-field cron) 设置秒字段为范围（启用6字段cron）
      Parameters:
      from - the start (0-59) | 起始（0-59）
      to - the end (0-59) | 结束（0-59）
      Returns:
      this builder | 此构建器
      Throws:
      IllegalArgumentException - if out of range | 如果超出范围

    • minuteRange

      public CronBuilder minuteRange(int from, int to)
      Sets the minute field to a range 设置分钟字段为范围
      Parameters:
      from - the start (0-59) | 起始（0-59）
      to - the end (0-59) | 结束（0-59）
      Returns:
      this builder | 此构建器
      Throws:
      IllegalArgumentException - if out of range | 如果超出范围

    • hourRange

      public CronBuilder hourRange(int from, int to)
      Sets the hour field to a range 设置小时字段为范围
      Parameters:
      from - the start (0-23) | 起始（0-23）
      to - the end (0-23) | 结束（0-23）
      Returns:
      this builder | 此构建器
      Throws:
      IllegalArgumentException - if out of range | 如果超出范围

    • buildExpression

      public String buildExpression()
      Builds the cron expression string 构建Cron表达式字符串
      Returns:
      the cron expression | Cron表达式

    • build

      public CronExpression build()
      Builds and parses the cron expression into a CronExpression 构建并解析Cron表达式为 CronExpression
      Returns:
      the parsed expression | 解析后的表达式