cn.hutool.cron.pattern.CronPattern Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of hutool-all Show documentation
Hutool是一个小而全的Java工具类库，通过静态方法封装，降低相关API的学习成本，提高工作效率，使Java拥有函数式语言般的优雅，让Java语言也可以“甜甜的”。
There is a newer version: 5.8.34
package cn.hutool.cron.pattern;

import cn.hutool.core.collection.CollUtil;
import cn.hutool.core.date.CalendarUtil;
import cn.hutool.cron.pattern.matcher.PatternMatcher;
import cn.hutool.cron.pattern.parser.PatternParser;

import java.time.LocalDateTime;
import java.util.ArrayList;
import java.util.Calendar;
import java.util.GregorianCalendar;
import java.util.List;
import java.util.TimeZone;

/**
 * 定时任务表达式

 * 表达式类似于Linux的crontab表达式，表达式使用空格分成5个部分，按顺序依次为：
 * 
 * 分 ：范围：0~59
 * 时 ：范围：0~23
 * 日 ：范围：1~31，"L" 表示月的最后一天
 * 月 ：范围：1~12，同时支持不区分大小写的别名："jan","feb", "mar", "apr", "may","jun", "jul", "aug", "sep","oct", "nov", "dec"
 * 周 ：范围：0 (Sunday)~6(Saturday)，7也可以表示周日，同时支持不区分大小写的别名："sun","mon", "tue", "wed", "thu","fri", "sat"，"L" 表示周六
 * 
 * 
 * 为了兼容Quartz表达式，同时支持6位和7位表达式，其中：

 *
 * 
 * 当为6位时，第一位表示秒 ，范围0~59，但是第一位不做匹配
 * 当为7位时，最后一位表示年 ，范围1970~2099，但是第7位不做解析，也不做匹配
 * 
 * 
 * 当定时任务运行到的时间匹配这些表达式后，任务被启动。

 * 注意：
 *
 * 
 * 当isMatchSecond为{@code true}时才会匹配秒部分
 * 默认都是关闭的
 * 
 * 
 * 对于每一个子表达式，同样支持以下形式：
 * 

 * * ：表示匹配这个位置所有的时间
 * ? ：表示匹配这个位置任意的时间（与"*"作用一致）
 * */2 ：表示间隔时间，例如在分上，表示每两分钟，同样*可以使用数字列表代替，逗号分隔
 * 2-8 ：表示连续区间，例如在分上，表示2,3,4,5,6,7,8分
 * 2,3,5,8 ：表示列表
 * cronA | cronB ：表示多个定时表达式
 * 
 * 注意：在每一个子表达式中优先级：
 *
 *  * 间隔（/） > 区间（-） > 列表（,）
 * 
 * 
 * 例如 2,3,6/3中，由于“/”优先级高，因此相当于2,3,(6/3)，结果与 2,3,6等价

 * 

 * 

 * 一些例子：
 * 

 * 5 * * * * ：每个点钟的5分执行，00:05,01:05……
 * * * * * * ：每分钟执行
 * */2 * * * * ：每两分钟执行
 * * 12 * * * ：12点的每分钟执行
 * 59 11 * * 1,2 ：每周一和周二的11:59执行
 * 3-18/5 * * * * ：3~18分，每5分钟执行一次，即0:03, 0:08, 0:13, 0:18, 1:03, 1:08……
 * 
 *
 * @author Looly
 */
public class CronPattern {

	private final String pattern;
	private final List matchers;

	/**
	 * 解析表达式为 CronPattern
	 *
	 * @param pattern 表达式
	 * @return CronPattern
	 * @since 5.8.0
	 */
	public static CronPattern of(String pattern) {
		return new CronPattern(pattern);
	}

	/**
	 * 构造
	 *
	 * @param pattern 表达式
	 */
	public CronPattern(String pattern) {
		this.pattern = pattern;
		this.matchers = PatternParser.parse(pattern);
	}

	/**
	 * 给定时间是否匹配定时任务表达式
	 *
	 * @param millis        时间毫秒数
	 * @param isMatchSecond 是否匹配秒
	 * @return 如果匹配返回 {@code true}, 否则返回 {@code false}
	 */
	public boolean match(long millis, boolean isMatchSecond) {
		return match(TimeZone.getDefault(), millis, isMatchSecond);
	}

	/**
	 * 给定时间是否匹配定时任务表达式
	 *
	 * @param timezone      时区 {@link TimeZone}
	 * @param millis        时间毫秒数
	 * @param isMatchSecond 是否匹配秒
	 * @return 如果匹配返回 {@code true}, 否则返回 {@code false}
	 */
	public boolean match(TimeZone timezone, long millis, boolean isMatchSecond) {
		final GregorianCalendar calendar = new GregorianCalendar(timezone);
		calendar.setTimeInMillis(millis);
		return match(calendar, isMatchSecond);
	}

	/**
	 * 给定时间是否匹配定时任务表达式
	 *
	 * @param calendar      时间
	 * @param isMatchSecond 是否匹配秒
	 * @return 如果匹配返回 {@code true}, 否则返回 {@code false}
	 */
	public boolean match(Calendar calendar, boolean isMatchSecond) {
		return match(PatternUtil.getFields(calendar, isMatchSecond));
	}

	/**
	 * 给定时间是否匹配定时任务表达式
	 *
	 * @param dateTime      时间
	 * @param isMatchSecond 是否匹配秒
	 * @return 如果匹配返回 {@code true}, 否则返回 {@code false}
	 * @since 5.8.0
	 */
	public boolean match(LocalDateTime dateTime, boolean isMatchSecond) {
		return match(PatternUtil.getFields(dateTime, isMatchSecond));
	}

	/**
	 * 返回匹配到的下一个时间
	 *
	 * @param calendar 时间
	 * @return 匹配到的下一个时间
	 */
	public Calendar nextMatchAfter(Calendar calendar) {
		// issue#I9FQUA，当提供的时间已经匹配表达式时，增加1秒以匹配下一个时间
		if(match(calendar, true)){
			final Calendar newCalendar = Calendar.getInstance(calendar.getTimeZone());
			newCalendar.setTimeInMillis(calendar.getTimeInMillis() + 1000);
			calendar = newCalendar;
		}

		Calendar next = nextMatchAfter(PatternUtil.getFields(calendar, true), calendar.getTimeZone());
		if (false == match(next, true)) {
			next.set(Calendar.DAY_OF_MONTH, next.get(Calendar.DAY_OF_MONTH) + 1);
			next = CalendarUtil.beginOfDay(next);
			return nextMatchAfter(next);
		}
		return next;
	}

	@Override
	public String toString() {
		return this.pattern;
	}

	/**
	 * 给定时间是否匹配定时任务表达式
	 *
	 * @param fields 时间字段值，{second, minute, hour, dayOfMonth, month, dayOfWeek, year}
	 * @return 如果匹配返回 {@code true}, 否则返回 {@code false}
	 */
	private boolean match(int[] fields) {
		for (PatternMatcher matcher : matchers) {
			if (matcher.match(fields)) {
				return true;
			}
		}
		return false;
	}

	/**
	 * 获取下一个最近的匹配日期时间
	 *
	 * @param values 时间字段值，{second, minute, hour, dayOfMonth, month, dayOfWeek, year}
	 * @param zone   时区
	 * @return {@link Calendar}，毫秒数为0
	 */
	private Calendar nextMatchAfter(int[] values, TimeZone zone) {
		final List nextMatches = new ArrayList<>(matchers.size());
		for (PatternMatcher matcher : matchers) {
			nextMatches.add(matcher.nextMatchAfter(values, zone));
		}
		// 返回匹配到的最早日期
		return CollUtil.min(nextMatches);
	}
}