45 *
46 * * Neither the name of JSR-310 nor the names of its contributors
47 * may be used to endorse or promote products derived from this software
48 * without specific prior written permission.
49 *
50 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
51 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
52 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
53 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
54 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
55 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
56 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
57 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
58 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
59 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
60 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
61 */
62 package java.time.temporal;
63
64 import java.time.DateTimeException;
65
66 /**
67 * Strategy for adjusting a temporal object.
68 * <p>
69 * Adjusters are a key tool for modifying temporal objects.
70 * They exist to externalize the process of adjustment, permitting different
71 * approaches, as per the strategy design pattern.
72 * Examples might be an adjuster that sets the date avoiding weekends, or one that
73 * sets the date to the last day of the month.
74 * <p>
75 * There are two equivalent ways of using a {@code TemporalAdjuster}.
76 * The first is to invoke the method on this interface directly.
77 * The second is to use {@link Temporal#with(TemporalAdjuster)}:
78 * <pre>
79 * // these two lines are equivalent, but the second approach is recommended
80 * temporal = thisAdjuster.adjustInto(temporal);
81 * temporal = temporal.with(thisAdjuster);
82 * </pre>
83 * It is recommended to use the second approach, {@code with(TemporalAdjuster)},
84 * as it is a lot clearer to read in code.
85 * <p>
86 * See {@link Adjusters} for a standard set of adjusters, including finding the
87 * last day of the month.
88 * Adjusters may also be defined by applications.
89 *
90 * <h3>Specification for implementors</h3>
91 * This interface places no restrictions on the mutability of implementations,
92 * however immutability is strongly recommended.
93 *
94 * @since 1.8
95 */
96 @FunctionalInterface
97 public interface TemporalAdjuster {
98
99 /**
100 * Adjusts the specified temporal object.
101 * <p>
102 * This adjusts the specified temporal object using the logic
103 * encapsulated in the implementing class.
104 * Examples might be an adjuster that sets the date avoiding weekends, or one that
105 * sets the date to the last day of the month.
106 * <p>
107 * There are two equivalent ways of using this method.
108 * The first is to invoke this method directly.
109 * The second is to use {@link Temporal#with(TemporalAdjuster)}:
110 * <pre>
111 * // these two lines are equivalent, but the second approach is recommended
112 * temporal = thisAdjuster.adjustInto(temporal);
113 * temporal = temporal.with(thisAdjuster);
114 * </pre>
115 * It is recommended to use the second approach, {@code with(TemporalAdjuster)},
116 * as it is a lot clearer to read in code.
117 *
118 * <h3>Specification for implementors</h3>
119 * The implementation must take the input object and adjust it.
120 * The implementation defines the logic of the adjustment and is responsible for
121 * documenting that logic. It may use any method on {@code Temporal} to
122 * query the temporal object and perform the adjustment.
123 * The returned object must have the same observable type as the input object
124 * <p>
125 * The input object must not be altered.
126 * Instead, an adjusted copy of the original must be returned.
127 * This provides equivalent, safe behavior for immutable and mutable temporal objects.
128 * <p>
129 * The input temporal object may be in a calendar system other than ISO.
130 * Implementations may choose to document compatibility with other calendar systems,
131 * or reject non-ISO temporal objects by {@link Queries#chronology() querying the chronology}.
132 * <p>
133 * This method may be called from multiple threads in parallel.
134 * It must be thread-safe when invoked.
135 *
136 * @param temporal the temporal object to adjust, not null
137 * @return an object of the same observable type with the adjustment made, not null
138 * @throws DateTimeException if unable to make the adjustment
139 * @throws ArithmeticException if numeric overflow occurs
140 */
141 Temporal adjustInto(Temporal temporal);
142
143 }
|
45 *
46 * * Neither the name of JSR-310 nor the names of its contributors
47 * may be used to endorse or promote products derived from this software
48 * without specific prior written permission.
49 *
50 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
51 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
52 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
53 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
54 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
55 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
56 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
57 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
58 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
59 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
60 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
61 */
62 package java.time.temporal;
63
64 import java.time.DateTimeException;
65 import java.time.DayOfWeek;
66 import java.time.LocalDate;
67 import java.util.function.UnaryOperator;
68
69 /**
70 * Strategy for adjusting a temporal object.
71 * <p>
72 * Adjusters are a key tool for modifying temporal objects.
73 * They exist to externalize the process of adjustment, permitting different
74 * approaches, as per the strategy design pattern.
75 * Examples might be an adjuster that sets the date avoiding weekends, or one that
76 * sets the date to the last day of the month.
77 * <p>
78 * There are two equivalent ways of using a {@code TemporalAdjuster}.
79 * The first is to invoke the method on this interface directly.
80 * The second is to use {@link Temporal#with(TemporalAdjuster)}:
81 * <pre>
82 * // these two lines are equivalent, but the second approach is recommended
83 * temporal = thisAdjuster.adjustInto(temporal);
84 * temporal = temporal.with(thisAdjuster);
85 * </pre>
86 * It is recommended to use the second approach, {@code with(TemporalAdjuster)},
87 * as it is a lot clearer to read in code.
88 * <p>
89 * This class also contains a standard set of adjusters, available as static methods.
90 * These include:
91 * <ul>
92 * <li>finding the first or last day of the month
93 * <li>finding the first day of next month
94 * <li>finding the first or last day of the year
95 * <li>finding the first day of next year
96 * <li>finding the first or last day-of-week within a month, such as "first Wednesday in June"
97 * <li>finding the next or previous day-of-week, such as "next Thursday"
98 * </ul>
99 *
100 * <h3>Specification for implementors</h3>
101 * This interface places no restrictions on the mutability of implementations,
102 * however immutability is strongly recommended.
103 * <p>
104 * All the implementations supplied by the static methods on this interface are immutable.
105 *
106 * @since 1.8
107 */
108 @FunctionalInterface
109 public interface TemporalAdjuster {
110
111 /**
112 * Adjusts the specified temporal object.
113 * <p>
114 * This adjusts the specified temporal object using the logic
115 * encapsulated in the implementing class.
116 * Examples might be an adjuster that sets the date avoiding weekends, or one that
117 * sets the date to the last day of the month.
118 * <p>
119 * There are two equivalent ways of using this method.
120 * The first is to invoke this method directly.
121 * The second is to use {@link Temporal#with(TemporalAdjuster)}:
122 * <pre>
123 * // these two lines are equivalent, but the second approach is recommended
124 * temporal = thisAdjuster.adjustInto(temporal);
125 * temporal = temporal.with(thisAdjuster);
126 * </pre>
127 * It is recommended to use the second approach, {@code with(TemporalAdjuster)},
128 * as it is a lot clearer to read in code.
129 *
130 * <h3>Specification for implementors</h3>
131 * The implementation must take the input object and adjust it.
132 * The implementation defines the logic of the adjustment and is responsible for
133 * documenting that logic. It may use any method on {@code Temporal} to
134 * query the temporal object and perform the adjustment.
135 * The returned object must have the same observable type as the input object
136 * <p>
137 * The input object must not be altered.
138 * Instead, an adjusted copy of the original must be returned.
139 * This provides equivalent, safe behavior for immutable and mutable temporal objects.
140 * <p>
141 * The input temporal object may be in a calendar system other than ISO.
142 * Implementations may choose to document compatibility with other calendar systems,
143 * or reject non-ISO temporal objects by {@link TemporalQuery#chronology() querying the chronology}.
144 * <p>
145 * This method may be called from multiple threads in parallel.
146 * It must be thread-safe when invoked.
147 *
148 * @param temporal the temporal object to adjust, not null
149 * @return an object of the same observable type with the adjustment made, not null
150 * @throws DateTimeException if unable to make the adjustment
151 * @throws ArithmeticException if numeric overflow occurs
152 */
153 Temporal adjustInto(Temporal temporal);
154
155 //-----------------------------------------------------------------------
156 /**
157 * Obtains a {@code TemporalAdjuster} that wraps a date adjuster.
158 * <p>
159 * The {@code TemporalAdjuster} is based on the low level {@code Temporal} interface.
160 * This method allows an adjustment from {@code LocalDate} to {@code LocalDate}
161 * to be wrapped to match the temporal-based interface.
162 * This is provided for convenience to make user-written adjusters simpler.
163 * <p>
164 * In general, user-written adjusters should be static constants:
165 * <pre>
166 * static TemporalAdjuster TWO_DAYS_LATER = TemporalAdjuster.ofDateAdjuster(
167 * date -> date.plusDays(2));
168 * </pre>
169 *
170 * @param dateBasedAdjuster the date-based adjuster, not null
171 * @return the temporal adjuster wrapping on the date adjuster, not null
172 */
173 static TemporalAdjuster ofDateAdjuster(UnaryOperator<LocalDate> dateBasedAdjuster) {
174 return TemporalAdjusters.ofDateAdjuster(dateBasedAdjuster);
175 }
176
177 //-----------------------------------------------------------------------
178 /**
179 * Returns the "first day of month" adjuster, which returns a new date set to
180 * the first day of the current month.
181 * <p>
182 * The ISO calendar system behaves as follows:<br>
183 * The input 2011-01-15 will return 2011-01-01.<br>
184 * The input 2011-02-15 will return 2011-02-01.
185 * <p>
186 * The behavior is suitable for use with most calendar systems.
187 * It is equivalent to:
188 * <pre>
189 * temporal.with(DAY_OF_MONTH, 1);
190 * </pre>
191 *
192 * @return the first day-of-month adjuster, not null
193 */
194 static TemporalAdjuster firstDayOfMonth() {
195 return TemporalAdjusters.firstDayOfMonth();
196 }
197
198 /**
199 * Returns the "last day of month" adjuster, which returns a new date set to
200 * the last day of the current month.
201 * <p>
202 * The ISO calendar system behaves as follows:<br>
203 * The input 2011-01-15 will return 2011-01-31.<br>
204 * The input 2011-02-15 will return 2011-02-28.<br>
205 * The input 2012-02-15 will return 2012-02-29 (leap year).<br>
206 * The input 2011-04-15 will return 2011-04-30.
207 * <p>
208 * The behavior is suitable for use with most calendar systems.
209 * It is equivalent to:
210 * <pre>
211 * long lastDay = temporal.range(DAY_OF_MONTH).getMaximum();
212 * temporal.with(DAY_OF_MONTH, lastDay);
213 * </pre>
214 *
215 * @return the last day-of-month adjuster, not null
216 */
217 static TemporalAdjuster lastDayOfMonth() {
218 return TemporalAdjusters.lastDayOfMonth();
219 }
220
221 /**
222 * Returns the "first day of next month" adjuster, which returns a new date set to
223 * the first day of the next month.
224 * <p>
225 * The ISO calendar system behaves as follows:<br>
226 * The input 2011-01-15 will return 2011-02-01.<br>
227 * The input 2011-02-15 will return 2011-03-01.
228 * <p>
229 * The behavior is suitable for use with most calendar systems.
230 * It is equivalent to:
231 * <pre>
232 * temporal.with(DAY_OF_MONTH, 1).plus(1, MONTHS);
233 * </pre>
234 *
235 * @return the first day of next month adjuster, not null
236 */
237 static TemporalAdjuster firstDayOfNextMonth() {
238 return TemporalAdjusters.firstDayOfNextMonth();
239 }
240
241 //-----------------------------------------------------------------------
242 /**
243 * Returns the "first day of year" adjuster, which returns a new date set to
244 * the first day of the current year.
245 * <p>
246 * The ISO calendar system behaves as follows:<br>
247 * The input 2011-01-15 will return 2011-01-01.<br>
248 * The input 2011-02-15 will return 2011-01-01.<br>
249 * <p>
250 * The behavior is suitable for use with most calendar systems.
251 * It is equivalent to:
252 * <pre>
253 * temporal.with(DAY_OF_YEAR, 1);
254 * </pre>
255 *
256 * @return the first day-of-year adjuster, not null
257 */
258 static TemporalAdjuster firstDayOfYear() {
259 return TemporalAdjusters.firstDayOfYear();
260 }
261
262 /**
263 * Returns the "last day of year" adjuster, which returns a new date set to
264 * the last day of the current year.
265 * <p>
266 * The ISO calendar system behaves as follows:<br>
267 * The input 2011-01-15 will return 2011-12-31.<br>
268 * The input 2011-02-15 will return 2011-12-31.<br>
269 * <p>
270 * The behavior is suitable for use with most calendar systems.
271 * It is equivalent to:
272 * <pre>
273 * long lastDay = temporal.range(DAY_OF_YEAR).getMaximum();
274 * temporal.with(DAY_OF_YEAR, lastDay);
275 * </pre>
276 *
277 * @return the last day-of-year adjuster, not null
278 */
279 static TemporalAdjuster lastDayOfYear() {
280 return TemporalAdjusters.lastDayOfYear();
281 }
282
283 /**
284 * Returns the "first day of next year" adjuster, which returns a new date set to
285 * the first day of the next year.
286 * <p>
287 * The ISO calendar system behaves as follows:<br>
288 * The input 2011-01-15 will return 2012-01-01.
289 * <p>
290 * The behavior is suitable for use with most calendar systems.
291 * It is equivalent to:
292 * <pre>
293 * temporal.with(DAY_OF_YEAR, 1).plus(1, YEARS);
294 * </pre>
295 *
296 * @return the first day of next month adjuster, not null
297 */
298 static TemporalAdjuster firstDayOfNextYear() {
299 return TemporalAdjusters.firstDayOfNextYear();
300 }
301
302 //-----------------------------------------------------------------------
303 /**
304 * Returns the first in month adjuster, which returns a new date
305 * in the same month with the first matching day-of-week.
306 * This is used for expressions like 'first Tuesday in March'.
307 * <p>
308 * The ISO calendar system behaves as follows:<br>
309 * The input 2011-12-15 for (MONDAY) will return 2011-12-05.<br>
310 * The input 2011-12-15 for (FRIDAY) will return 2011-12-02.<br>
311 * <p>
312 * The behavior is suitable for use with most calendar systems.
313 * It uses the {@code DAY_OF_WEEK} and {@code DAY_OF_MONTH} fields
314 * and the {@code DAYS} unit, and assumes a seven day week.
315 *
316 * @param dayOfWeek the day-of-week, not null
317 * @return the first in month adjuster, not null
318 */
319 static TemporalAdjuster firstInMonth(DayOfWeek dayOfWeek) {
320 return TemporalAdjuster.dayOfWeekInMonth(1, dayOfWeek);
321 }
322
323 /**
324 * Returns the last in month adjuster, which returns a new date
325 * in the same month with the last matching day-of-week.
326 * This is used for expressions like 'last Tuesday in March'.
327 * <p>
328 * The ISO calendar system behaves as follows:<br>
329 * The input 2011-12-15 for (MONDAY) will return 2011-12-26.<br>
330 * The input 2011-12-15 for (FRIDAY) will return 2011-12-30.<br>
331 * <p>
332 * The behavior is suitable for use with most calendar systems.
333 * It uses the {@code DAY_OF_WEEK} and {@code DAY_OF_MONTH} fields
334 * and the {@code DAYS} unit, and assumes a seven day week.
335 *
336 * @param dayOfWeek the day-of-week, not null
337 * @return the first in month adjuster, not null
338 */
339 static TemporalAdjuster lastInMonth(DayOfWeek dayOfWeek) {
340 return TemporalAdjuster.dayOfWeekInMonth(-1, dayOfWeek);
341 }
342
343 /**
344 * Returns the day-of-week in month adjuster, which returns a new date
345 * in the same month with the ordinal day-of-week.
346 * This is used for expressions like the 'second Tuesday in March'.
347 * <p>
348 * The ISO calendar system behaves as follows:<br>
349 * The input 2011-12-15 for (1,TUESDAY) will return 2011-12-06.<br>
350 * The input 2011-12-15 for (2,TUESDAY) will return 2011-12-13.<br>
351 * The input 2011-12-15 for (3,TUESDAY) will return 2011-12-20.<br>
352 * The input 2011-12-15 for (4,TUESDAY) will return 2011-12-27.<br>
353 * The input 2011-12-15 for (5,TUESDAY) will return 2012-01-03.<br>
354 * The input 2011-12-15 for (-1,TUESDAY) will return 2011-12-27 (last in month).<br>
355 * The input 2011-12-15 for (-4,TUESDAY) will return 2011-12-06 (3 weeks before last in month).<br>
356 * The input 2011-12-15 for (-5,TUESDAY) will return 2011-11-29 (4 weeks before last in month).<br>
357 * The input 2011-12-15 for (0,TUESDAY) will return 2011-11-29 (last in previous month).<br>
358 * <p>
359 * For a positive or zero ordinal, the algorithm is equivalent to finding the first
360 * day-of-week that matches within the month and then adding a number of weeks to it.
361 * For a negative ordinal, the algorithm is equivalent to finding the last
362 * day-of-week that matches within the month and then subtracting a number of weeks to it.
363 * The ordinal number of weeks is not validated and is interpreted leniently
364 * according to this algorithm. This definition means that an ordinal of zero finds
365 * the last matching day-of-week in the previous month.
366 * <p>
367 * The behavior is suitable for use with most calendar systems.
368 * It uses the {@code DAY_OF_WEEK} and {@code DAY_OF_MONTH} fields
369 * and the {@code DAYS} unit, and assumes a seven day week.
370 *
371 * @param ordinal the week within the month, unbounded but typically from -5 to 5
372 * @param dayOfWeek the day-of-week, not null
373 * @return the day-of-week in month adjuster, not null
374 */
375 static TemporalAdjuster dayOfWeekInMonth(final int ordinal, DayOfWeek dayOfWeek) {
376 return TemporalAdjusters.dayOfWeekInMonth(ordinal, dayOfWeek);
377 }
378
379 //-----------------------------------------------------------------------
380 /**
381 * Returns the next day-of-week adjuster, which adjusts the date to the
382 * first occurrence of the specified day-of-week after the date being adjusted.
383 * <p>
384 * The ISO calendar system behaves as follows:<br>
385 * The input 2011-01-15 (a Saturday) for parameter (MONDAY) will return 2011-01-17 (two days later).<br>
386 * The input 2011-01-15 (a Saturday) for parameter (WEDNESDAY) will return 2011-01-19 (four days later).<br>
387 * The input 2011-01-15 (a Saturday) for parameter (SATURDAY) will return 2011-01-22 (seven days later).
388 * <p>
389 * The behavior is suitable for use with most calendar systems.
390 * It uses the {@code DAY_OF_WEEK} field and the {@code DAYS} unit,
391 * and assumes a seven day week.
392 *
393 * @param dayOfWeek the day-of-week to move the date to, not null
394 * @return the next day-of-week adjuster, not null
395 */
396 static TemporalAdjuster next(DayOfWeek dayOfWeek) {
397 return TemporalAdjusters.next(dayOfWeek);
398 }
399
400 /**
401 * Returns the next-or-same day-of-week adjuster, which adjusts the date to the
402 * first occurrence of the specified day-of-week after the date being adjusted
403 * unless it is already on that day in which case the same object is returned.
404 * <p>
405 * The ISO calendar system behaves as follows:<br>
406 * The input 2011-01-15 (a Saturday) for parameter (MONDAY) will return 2011-01-17 (two days later).<br>
407 * The input 2011-01-15 (a Saturday) for parameter (WEDNESDAY) will return 2011-01-19 (four days later).<br>
408 * The input 2011-01-15 (a Saturday) for parameter (SATURDAY) will return 2011-01-15 (same as input).
409 * <p>
410 * The behavior is suitable for use with most calendar systems.
411 * It uses the {@code DAY_OF_WEEK} field and the {@code DAYS} unit,
412 * and assumes a seven day week.
413 *
414 * @param dayOfWeek the day-of-week to check for or move the date to, not null
415 * @return the next-or-same day-of-week adjuster, not null
416 */
417 static TemporalAdjuster nextOrSame(DayOfWeek dayOfWeek) {
418 return TemporalAdjusters.nextOrSame(dayOfWeek);
419 }
420
421 /**
422 * Returns the previous day-of-week adjuster, which adjusts the date to the
423 * first occurrence of the specified day-of-week before the date being adjusted.
424 * <p>
425 * The ISO calendar system behaves as follows:<br>
426 * The input 2011-01-15 (a Saturday) for parameter (MONDAY) will return 2011-01-10 (five days earlier).<br>
427 * The input 2011-01-15 (a Saturday) for parameter (WEDNESDAY) will return 2011-01-12 (three days earlier).<br>
428 * The input 2011-01-15 (a Saturday) for parameter (SATURDAY) will return 2011-01-08 (seven days earlier).
429 * <p>
430 * The behavior is suitable for use with most calendar systems.
431 * It uses the {@code DAY_OF_WEEK} field and the {@code DAYS} unit,
432 * and assumes a seven day week.
433 *
434 * @param dayOfWeek the day-of-week to move the date to, not null
435 * @return the previous day-of-week adjuster, not null
436 */
437 static TemporalAdjuster previous(DayOfWeek dayOfWeek) {
438 return TemporalAdjusters.previous(dayOfWeek);
439 }
440
441 /**
442 * Returns the previous-or-same day-of-week adjuster, which adjusts the date to the
443 * first occurrence of the specified day-of-week before the date being adjusted
444 * unless it is already on that day in which case the same object is returned.
445 * <p>
446 * The ISO calendar system behaves as follows:<br>
447 * The input 2011-01-15 (a Saturday) for parameter (MONDAY) will return 2011-01-10 (five days earlier).<br>
448 * The input 2011-01-15 (a Saturday) for parameter (WEDNESDAY) will return 2011-01-12 (three days earlier).<br>
449 * The input 2011-01-15 (a Saturday) for parameter (SATURDAY) will return 2011-01-15 (same as input).
450 * <p>
451 * The behavior is suitable for use with most calendar systems.
452 * It uses the {@code DAY_OF_WEEK} field and the {@code DAYS} unit,
453 * and assumes a seven day week.
454 *
455 * @param dayOfWeek the day-of-week to check for or move the date to, not null
456 * @return the previous-or-same day-of-week adjuster, not null
457 */
458 static TemporalAdjuster previousOrSame(DayOfWeek dayOfWeek) {
459 return TemporalAdjusters.previousOrSame(dayOfWeek);
460 }
461
462 }
|