Explicit documentation note on cron-vs-quartz parsing convention

Closes gh-32128

Author: jhoeller

spring-context/src/main/java/org/springframework/scheduling/support/BitsCronField.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -247,24 +247,25 @@ private void setBit(int index) {
 	}
 
 	private void clearBit(int index) {
-		this.bits &=  ~(1L << index);
+		this.bits &= ~(1L << index);
 	}
 
-	@Override
-	public int hashCode() {
-		return Long.hashCode(this.bits);
-	}
 
 	@Override
-	public boolean equals(Object o) {
-		if (this == o) {
+	public boolean equals(Object other) {
+		if (this == other) {
 			return true;
 		}
-		if (!(o instanceof BitsCronField)) {
+		if (!(other instanceof BitsCronField)) {
 			return false;
 		}
-		BitsCronField other = (BitsCronField) o;
-		return type() == other.type() && this.bits == other.bits;
+		BitsCronField otherField = (BitsCronField) other;
+		return (type() == otherField.type() && this.bits == otherField.bits);
+	}
+
+	@Override
+	public int hashCode() {
+		return Long.hashCode(this.bits);
 	}
 
 	@Override

spring-context/src/main/java/org/springframework/scheduling/support/CronExpression.java

@@ -29,9 +29,14 @@
  * <a href="https://www.manpagez.com/man/5/crontab/">crontab expression</a>
  * that can calculate the next time it matches.
  *
- * <p>{@code CronExpression} instances are created through
- * {@link #parse(String)}; the next match is determined with
- * {@link #next(Temporal)}.
+ * <p>{@code CronExpression} instances are created through {@link #parse(String)};
+ * the next match is determined with {@link #next(Temporal)}.
+ *
+ * <p>Supports a Quartz day-of-month/week field with an L/# expression. Follows
+ * common cron conventions in every other respect, including 0-6 for SUN-SAT
+ * (plus 7 for SUN as well). Note that Quartz deviates from the day-of-week
+ * convention in cron through 1-7 for SUN-SAT whereas Spring strictly follows
+ * cron even in combination with the optional Quartz-specific L/# expressions.
  *
  * @author Arjen Poutsma
  * @since 5.3

spring-context/src/main/java/org/springframework/scheduling/support/CronField.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -31,15 +31,22 @@
  * Single field in a cron pattern. Created using the {@code parse*} methods,
  * main and only entry point is {@link #nextOrSame(Temporal)}.
  *
+ * <p>Supports a Quartz day-of-month/week field with an L/# expression. Follows
+ * common cron conventions in every other respect, including 0-6 for SUN-SAT
+ * (plus 7 for SUN as well). Note that Quartz deviates from the day-of-week
+ * convention in cron through 1-7 for SUN-SAT whereas Spring strictly follows
+ * cron even in combination with the optional Quartz-specific L/# expressions.
+ *
  * @author Arjen Poutsma
  * @since 5.3
  */
 abstract class CronField {
 
-	private static final String[] MONTHS = new String[]{"JAN", "FEB", "MAR", "APR", "MAY", "JUN", "JUL", "AUG", "SEP",
-			"OCT", "NOV", "DEC"};
+	private static final String[] MONTHS = new String[]
+			{"JAN", "FEB", "MAR", "APR", "MAY", "JUN", "JUL", "AUG", "SEP", "OCT", "NOV", "DEC"};
 
-	private static final String[] DAYS = new String[]{"MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN"};
+	private static final String[] DAYS = new String[]
+			{"MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN"};
 
 	private final Type type;
 
@@ -48,6 +55,7 @@ protected CronField(Type type) {
 		this.type = type;
 	}
 
+
 	/**
 	 * Return a {@code CronField} enabled for 0 nanoseconds.
 	 */
@@ -169,6 +177,7 @@ protected static <T extends Temporal & Comparable<? super T>> T cast(Temporal te
 	 * day-of-month, month, day-of-week.
 	 */
 	protected enum Type {
+
 		NANO(ChronoField.NANO_OF_SECOND, ChronoUnit.SECONDS),
 		SECOND(ChronoField.SECOND_OF_MINUTE, ChronoUnit.MINUTES, ChronoField.NANO_OF_SECOND),
 		MINUTE(ChronoField.MINUTE_OF_HOUR, ChronoUnit.HOURS, ChronoField.SECOND_OF_MINUTE, ChronoField.NANO_OF_SECOND),
@@ -184,14 +193,12 @@ protected enum Type {
 
 		private final ChronoField[] lowerOrders;
 
-
 		Type(ChronoField field, ChronoUnit higherOrder, ChronoField... lowerOrders) {
 			this.field = field;
 			this.higherOrder = higherOrder;
 			this.lowerOrders = lowerOrders;
 		}
 
-
 		/**
 		 * Return the value of this type for the given temporal.
 		 * @return the value of this type

spring-context/src/main/java/org/springframework/scheduling/support/CronTrigger.java

@@ -27,8 +27,14 @@
 import org.springframework.util.Assert;
 
 /**
- * {@link Trigger} implementation for cron expressions.
- * Wraps a {@link CronExpression}.
+ * {@link Trigger} implementation for cron expressions. Wraps a
+ * {@link CronExpression} which parses according to common crontab conventions.
+ *
+ * <p>Supports a Quartz day-of-month/week field with an L/# expression. Follows
+ * common cron conventions in every other respect, including 0-6 for SUN-SAT
+ * (plus 7 for SUN as well). Note that Quartz deviates from the day-of-week
+ * convention in cron through 1-7 for SUN-SAT whereas Spring strictly follows
+ * cron even in combination with the optional Quartz-specific L/# expressions.
  *
  * @author Juergen Hoeller
  * @author Arjen Poutsma

spring-context/src/main/java/org/springframework/scheduling/support/QuartzCronField.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -29,10 +29,16 @@
 
 /**
  * Extension of {@link CronField} for
- * <a href="https://www.quartz-scheduler.org>Quartz</a> -specific fields.
+ * <a href="https://www.quartz-scheduler.org">Quartz</a>-specific fields.
  * Created using the {@code parse*} methods, uses a {@link TemporalAdjuster}
  * internally.
  *
+ * <p>Supports a Quartz day-of-month/week field with an L/# expression. Follows
+ * common cron conventions in every other respect, including 0-6 for SUN-SAT
+ * (plus 7 for SUN as well). Note that Quartz deviates from the day-of-week
+ * convention in cron through 1-7 for SUN-SAT whereas Spring strictly follows
+ * cron even in combination with the optional Quartz-specific L/# expressions.
+ *
  * @author Arjen Poutsma
  * @since 5.3
  */
@@ -60,8 +66,9 @@ private QuartzCronField(Type type, Type rollForwardType, TemporalAdjuster adjust
 		this.rollForwardType = rollForwardType;
 	}
 
+
 	/**
-	 * Returns whether the given value is a Quartz day-of-month field.
+	 * Determine whether the given value is a Quartz day-of-month field.
 	 */
 	public static boolean isQuartzDaysOfMonthField(String value) {
 		return value.contains("L") || value.contains("W");
@@ -78,14 +85,14 @@ public static QuartzCronField parseDaysOfMonth(String value) {
 			if (idx != 0) {
 				throw new IllegalArgumentException("Unrecognized characters before 'L' in '" + value + "'");
 			}
-			else if (value.length() == 2 && value.charAt(1) == 'W') { // "LW"
+			else if (value.length() == 2 && value.charAt(1) == 'W') {  // "LW"
 				adjuster = lastWeekdayOfMonth();
 			}
 			else {
-				if (value.length() == 1) { // "L"
+				if (value.length() == 1) {  // "L"
 					adjuster = lastDayOfMonth();
 				}
-				else { // "L-[0-9]+"
+				else {  // "L-[0-9]+"
 					int offset = Integer.parseInt(value.substring(idx + 1));
 					if (offset >= 0) {
 						throw new IllegalArgumentException("Offset '" + offset + " should be < 0 '" + value + "'");
@@ -103,7 +110,7 @@ else if (value.length() == 2 && value.charAt(1) == 'W') { // "LW"
 			else if (idx != value.length() - 1) {
 				throw new IllegalArgumentException("Unrecognized characters after 'W' in '" + value + "'");
 			}
-			else { // "[0-9]+W"
+			else {  // "[0-9]+W"
 				int dayOfMonth = Integer.parseInt(value.substring(0, idx));
 				dayOfMonth = Type.DAY_OF_MONTH.checkValidValue(dayOfMonth);
 				TemporalAdjuster adjuster = weekdayNearestTo(dayOfMonth);
@@ -114,15 +121,16 @@ else if (idx != value.length() - 1) {
 	}
 
 	/**
-	 * Returns whether the given value is a Quartz day-of-week field.
+	 * Determine whether the given value is a Quartz day-of-week field.
 	 */
 	public static boolean isQuartzDaysOfWeekField(String value) {
 		return value.contains("L") || value.contains("#");
 	}
 
 	/**
-	 * Parse the given value into a days of week {@code QuartzCronField}, the sixth entry of a cron expression.
-	 * Expects a "L" or "#" in the given value.
+	 * Parse the given value into a days of week {@code QuartzCronField},
+	 * the sixth entry of a cron expression.
+	 * <p>Expects a "L" or "#" in the given value.
 	 */
 	public static QuartzCronField parseDaysOfWeek(String value) {
 		int idx = value.lastIndexOf('L');
@@ -135,7 +143,7 @@ public static QuartzCronField parseDaysOfWeek(String value) {
 				if (idx == 0) {
 					throw new IllegalArgumentException("No day-of-week before 'L' in '" + value + "'");
 				}
-				else { // "[0-7]L"
+				else {  // "[0-7]L"
 					DayOfWeek dayOfWeek = parseDayOfWeek(value.substring(0, idx));
 					adjuster = lastInMonth(dayOfWeek);
 				}
@@ -157,7 +165,6 @@ else if (idx == value.length() - 1) {
 				throw new IllegalArgumentException("Ordinal '" + ordinal + "' in '" + value +
 						"' must be positive number ");
 			}
-
 			TemporalAdjuster adjuster = dayOfWeekInMonth(ordinal, dayOfWeek);
 			return new QuartzCronField(Type.DAY_OF_WEEK, Type.DAY_OF_MONTH, adjuster, value);
 		}
@@ -167,14 +174,13 @@ else if (idx == value.length() - 1) {
 	private static DayOfWeek parseDayOfWeek(String value) {
 		int dayOfWeek = Integer.parseInt(value);
 		if (dayOfWeek == 0) {
-			dayOfWeek = 7; // cron is 0 based; java.time 1 based
+			dayOfWeek = 7;  // cron is 0 based; java.time 1 based
 		}
 		try {
 			return DayOfWeek.of(dayOfWeek);
 		}
 		catch (DateTimeException ex) {
-			String msg = ex.getMessage() + " '" + value + "'";
-			throw new IllegalArgumentException(msg, ex);
+			throw new IllegalArgumentException(ex.getMessage() + " '" + value + "'", ex);
 		}
 	}
 
@@ -213,10 +219,10 @@ private static TemporalAdjuster lastWeekdayOfMonth() {
 			Temporal lastDom = adjuster.adjustInto(temporal);
 			Temporal result;
 			int dow = lastDom.get(ChronoField.DAY_OF_WEEK);
-			if (dow == 6) { // Saturday
+			if (dow == 6) {  // Saturday
 				result = lastDom.minus(1, ChronoUnit.DAYS);
 			}
-			else if (dow == 7) { // Sunday
+			else if (dow == 7) {  // Sunday
 				result = lastDom.minus(2, ChronoUnit.DAYS);
 			}
 			else {
@@ -227,7 +233,7 @@ else if (dow == 7) { // Sunday
 	}
 
 	/**
-	 * Return a temporal adjuster that finds the nth-to-last day of the month.
+	 * Returns a temporal adjuster that finds the nth-to-last day of the month.
 	 * @param offset the negative offset, i.e. -3 means third-to-last
 	 * @return a nth-to-last day-of-month adjuster
 	 */
@@ -241,7 +247,7 @@ private static TemporalAdjuster lastDayWithOffset(int offset) {
 	}
 
 	/**
-	 * Return a temporal adjuster that finds the weekday nearest to the given
+	 * Returns a temporal adjuster that finds the weekday nearest to the given
 	 * day-of-month. If {@code dayOfMonth} falls on a Saturday, the date is
 	 * moved back to Friday; if it falls on a Sunday (or if {@code dayOfMonth}
 	 * is 1 and it falls on a Saturday), it is moved forward to Monday.
@@ -253,10 +259,10 @@ private static TemporalAdjuster weekdayNearestTo(int dayOfMonth) {
 			int current = Type.DAY_OF_MONTH.get(temporal);
 			DayOfWeek dayOfWeek = DayOfWeek.from(temporal);
 
-			if ((current == dayOfMonth && isWeekday(dayOfWeek)) || // dayOfMonth is a weekday
-					(dayOfWeek == DayOfWeek.FRIDAY && current == dayOfMonth - 1) || // dayOfMonth is a Saturday, so Friday before
-					(dayOfWeek == DayOfWeek.MONDAY && current == dayOfMonth + 1) || // dayOfMonth is a Sunday, so Monday after
-					(dayOfWeek == DayOfWeek.MONDAY && dayOfMonth == 1 && current == 3)) { // dayOfMonth is Saturday 1st, so Monday 3rd
+			if ((current == dayOfMonth && isWeekday(dayOfWeek)) ||  // dayOfMonth is a weekday
+					(dayOfWeek == DayOfWeek.FRIDAY && current == dayOfMonth - 1) ||  // dayOfMonth is a Saturday, so Friday before
+					(dayOfWeek == DayOfWeek.MONDAY && current == dayOfMonth + 1) ||  // dayOfMonth is a Sunday, so Monday after
+					(dayOfWeek == DayOfWeek.MONDAY && dayOfMonth == 1 && current == 3)) {  // dayOfMonth is Saturday 1st, so Monday 3rd
 				return temporal;
 			}
 			int count = 0;
@@ -292,7 +298,7 @@ private static boolean isWeekday(DayOfWeek dayOfWeek) {
 	}
 
 	/**
-	 * Return a temporal adjuster that finds the last of the given doy-of-week
+	 * Returns a temporal adjuster that finds the last of the given day-of-week
 	 * in a month.
 	 */
 	private static TemporalAdjuster lastInMonth(DayOfWeek dayOfWeek) {
@@ -329,6 +335,7 @@ private static Temporal rollbackToMidnight(Temporal current, Temporal result) {
 		}
 	}
 
+
 	@Override
 	public <T extends Temporal & Comparable<? super T>> T nextOrSame(T temporal) {
 		T result = adjust(temporal);
@@ -345,7 +352,6 @@ public <T extends Temporal & Comparable<? super T>> T nextOrSame(T temporal) {
 		return result;
 	}
 
-
 	@Nullable
 	@SuppressWarnings("unchecked")
 	private <T extends Temporal & Comparable<? super T>> T adjust(T temporal) {
@@ -354,27 +360,25 @@ private <T extends Temporal & Comparable<? super T>> T adjust(T temporal) {
 
 
 	@Override
-	public int hashCode() {
-		return this.value.hashCode();
-	}
-
-	@Override
-	public boolean equals(Object o) {
-		if (this == o) {
+	public boolean equals(@Nullable Object other) {
+		if (this == other) {
 			return true;
 		}
-		if (!(o instanceof QuartzCronField)) {
+		if (!(other instanceof QuartzCronField)) {
 			return false;
 		}
-		QuartzCronField other = (QuartzCronField) o;
-		return type() == other.type() &&
-				this.value.equals(other.value);
+		QuartzCronField otherField = (QuartzCronField) other;
+		return (type() == otherField.type() && this.value.equals(otherField.value));
+	}
+
+	@Override
+	public int hashCode() {
+		return this.value.hashCode();
 	}
 
 	@Override
 	public String toString() {
 		return type() + " '" + this.value + "'";
-
 	}
 
 }