Add support for multiple nth-day-of-month values

[serac]

We have a use case to run a single job on a single trigger semi-monthly using a cron expression like the following:

0 1 0 ? * 7#1,7#3

In plain English, on the first and third Saturdays of the month at 1201.

We are aware that this can be accomplished at present with multiple triggers, but we are using quartz indirectly in a bundled product where a single trigger is used to drive a job schedule.

[serac]

I am willing to provide a patch for this feature and spent a full day on a tactical solution that would introduce as few changes as possible, but I was unsuccessful. In short the CronExpression#getTimeAfter() method is impenetrable.

I am interesting in exploring an alternative solution. I believe I understand the core functions of the component enough to re-implement the workhorse methods:

1. getTimeBefore(Date)
2. getTimeAfter(Date)
3. isSatisfiedBy(Date)

My inclination is to make isSatisfiedBy the key method that simply checks whether a date is in range of the parsed cron expression. Maybe I'm being naïve, but this seems straightforward. Then getTimeBefore and getTimeAfter will simply iterate over the least-significant time decrement/increment in the cron expression and invoke isSatisfiedBy until it returns true (possibly limited by some upper-bound check, which is a feature that exists already afaict). This seems clear and straightforward, in contrast to the existing implementation that is painfully complex.

I want to gauge willingness for such a big change before I spend any time completing the contributor agreement and developing the solution. Assuming that it would be accompanied by a sufficiently comprehensive set of test vectors, would you be willing to accept a patch of this scope for this feature?

[t-beckmann]

The code is rather complex, asked AI for an explanation. Turned out it is doing what you are suggesting in a clever way:

How Quartz getTimeAfter Works

Quartz calculates the next execution time using a cascading "guess, test, and roll forward" strategy:

1. Smallest to Largest: It evaluates date components sequentially starting from Seconds up to Years.
2. The Ripple Effect: If a component fails to match the CRON rule, Quartz increments it to the next valid value.
3. Downward Reset: Whenever a larger component is incremented, all smaller components are reset to zero (their minimum allowed values).
4. Termination: The loop exits as soon as it passes a full cycle where every component satisfies the expression simultaneously.

To find the next valid minimum, thus is where the code is using the tailSet, for example.

Given that explanation adding your additional validity checks should be doable.

[hiSandog]

If this is added, the important part will be keeping the cron parser and next-fire calculation semantics explicit. Multiple # entries in the same day-of-week field could be represented as a set of nth-weekday candidates and then choose the earliest valid next time among them, rather than trying to fold it into the current single-value path. Tests should include months where the first and third target weekdays both exist, months where a fifth occurrence does not, and interaction with day-of-month being ?.