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.chrono;
63
64 import static java.time.temporal.ChronoField.INSTANT_SECONDS;
65 import static java.time.temporal.ChronoField.OFFSET_SECONDS;
66 import static java.time.temporal.ChronoUnit.NANOS;
67
68 import java.time.DateTimeException;
69 import java.time.Instant;
70 import java.time.LocalTime;
71 import java.time.ZoneId;
72 import java.time.ZoneOffset;
73 import java.time.ZonedDateTime;
74 import java.time.format.DateTimeFormatter;
75 import java.time.temporal.ChronoField;
76 import java.time.temporal.Temporal;
77 import java.time.temporal.TemporalAccessor;
78 import java.time.temporal.TemporalAdjuster;
79 import java.time.temporal.TemporalAmount;
80 import java.time.temporal.TemporalField;
81 import java.time.temporal.TemporalQuery;
82 import java.time.temporal.TemporalUnit;
83 import java.time.temporal.UnsupportedTemporalTypeException;
84 import java.time.temporal.ValueRange;
85 import java.util.Comparator;
86 import java.util.Objects;
87
88 /**
89 * A date-time with a time-zone in an arbitrary chronology,
90 * intended for advanced globalization use cases.
91 * <p>
92 * <b>Most applications should declare method signatures, fields and variables
93 * as {@link ZonedDateTime}, not this interface.</b>
94 * <p>
95 * A {@code ChronoZonedDateTime} is the abstract representation of an offset date-time
98 * where most common implementations are defined in {@link ChronoField}.
99 * The chronology defines how the calendar system operates and the meaning of
100 * the standard fields.
101 *
102 * <h3>When to use this interface</h3>
103 * The design of the API encourages the use of {@code ZonedDateTime} rather than this
104 * interface, even in the case where the application needs to deal with multiple
105 * calendar systems. The rationale for this is explored in detail in {@link ChronoLocalDate}.
106 * <p>
107 * Ensure that the discussion in {@code ChronoLocalDate} has been read and understood
108 * before using this interface.
109 *
110 * @implSpec
111 * This interface must be implemented with care to ensure other classes operate correctly.
112 * All implementations that can be instantiated must be final, immutable and thread-safe.
113 * Subclasses should be Serializable wherever possible.
114 *
115 * @param <D> the concrete type for the date of this date-time
116 * @since 1.8
117 */
118 public interface ChronoZonedDateTime<D extends ChronoLocalDate<D>>
119 extends Temporal, Comparable<ChronoZonedDateTime<?>> {
120
121 /**
122 * Gets a comparator that compares {@code ChronoZonedDateTime} in
123 * time-line order ignoring the chronology.
124 * <p>
125 * This comparator differs from the comparison in {@link #compareTo} in that it
126 * only compares the underlying instant and not the chronology.
127 * This allows dates in different calendar systems to be compared based
128 * on the position of the date-time on the instant time-line.
129 * The underlying comparison is equivalent to comparing the epoch-second and nano-of-second.
130 *
131 * @return a comparator that compares in time-line order ignoring the chronology
132 *
133 * @see #isAfter
134 * @see #isBefore
135 * @see #isEqual
136 */
137 static Comparator<ChronoZonedDateTime<?>> timeLineOrder() {
138 return Chronology.INSTANT_ORDER;
321
322 /**
323 * Returns a copy of this date-time with a different time-zone,
324 * retaining the instant.
325 * <p>
326 * This method changes the time-zone and retains the instant.
327 * This normally results in a change to the local date-time.
328 * <p>
329 * This method is based on retaining the same instant, thus gaps and overlaps
330 * in the local time-line have no effect on the result.
331 * <p>
332 * To change the offset while keeping the local time,
333 * use {@link #withZoneSameLocal(ZoneId)}.
334 *
335 * @param zone the time-zone to change to, not null
336 * @return a {@code ChronoZonedDateTime} based on this date-time with the requested zone, not null
337 * @throws DateTimeException if the result exceeds the supported date range
338 */
339 ChronoZonedDateTime<D> withZoneSameInstant(ZoneId zone);
340
341 @Override // Override to provide javadoc
342 boolean isSupported(TemporalField field);
343
344 //-----------------------------------------------------------------------
345 // override for covariant return type
346 /**
347 * {@inheritDoc}
348 * @throws DateTimeException {@inheritDoc}
349 * @throws ArithmeticException {@inheritDoc}
350 */
351 @Override
352 default ChronoZonedDateTime<D> with(TemporalAdjuster adjuster) {
353 return (ChronoZonedDateTime<D>)(toLocalDate().getChronology().ensureChronoZonedDateTime(Temporal.super.with(adjuster)));
354 }
355
356 /**
357 * {@inheritDoc}
358 * @throws DateTimeException {@inheritDoc}
359 * @throws ArithmeticException {@inheritDoc}
360 */
361 @Override
362 ChronoZonedDateTime<D> with(TemporalField field, long newValue);
363
364 /**
365 * {@inheritDoc}
366 * @throws DateTimeException {@inheritDoc}
367 * @throws ArithmeticException {@inheritDoc}
368 */
369 @Override
370 default ChronoZonedDateTime<D> plus(TemporalAmount amount) {
371 return (ChronoZonedDateTime<D>)(toLocalDate().getChronology().ensureChronoZonedDateTime(Temporal.super.plus(amount)));
372 }
373
374 /**
375 * {@inheritDoc}
376 * @throws DateTimeException {@inheritDoc}
377 * @throws ArithmeticException {@inheritDoc}
378 */
379 @Override
380 ChronoZonedDateTime<D> plus(long amountToAdd, TemporalUnit unit);
381
382 /**
383 * {@inheritDoc}
384 * @throws DateTimeException {@inheritDoc}
385 * @throws ArithmeticException {@inheritDoc}
386 */
387 @Override
388 default ChronoZonedDateTime<D> minus(TemporalAmount amount) {
389 return (ChronoZonedDateTime<D>)(toLocalDate().getChronology().ensureChronoZonedDateTime(Temporal.super.minus(amount)));
390 }
391
392 /**
393 * {@inheritDoc}
394 * @throws DateTimeException {@inheritDoc}
395 * @throws ArithmeticException {@inheritDoc}
396 */
397 @Override
398 default ChronoZonedDateTime<D> minus(long amountToSubtract, TemporalUnit unit) {
399 return (ChronoZonedDateTime<D>)(toLocalDate().getChronology().ensureChronoZonedDateTime(Temporal.super.minus(amountToSubtract, unit)));
400 }
401
402 //-----------------------------------------------------------------------
403 /**
404 * Queries this date-time using the specified query.
405 * <p>
406 * This queries this date-time using the specified query strategy object.
407 * The {@code TemporalQuery} object defines the logic to be used to
408 * obtain the result. Read the documentation of the query to understand
409 * what the result of this method will be.
410 * <p>
411 * The result of this method is obtained by invoking the
412 * {@link java.time.temporal.TemporalQuery#queryFrom(TemporalAccessor)} method on the
413 * specified query passing {@code this} as the argument.
414 *
415 * @param <R> the type of the result
416 * @param query the query to invoke, not null
417 * @return the query result, null may be returned (defined by the query)
418 * @throws DateTimeException if unable to query (defined by the query)
419 * @throws ArithmeticException if numeric overflow occurs (defined by the query)
|
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.chrono;
63
64 import static java.time.temporal.ChronoField.INSTANT_SECONDS;
65 import static java.time.temporal.ChronoField.OFFSET_SECONDS;
66 import static java.time.temporal.ChronoUnit.FOREVER;
67 import static java.time.temporal.ChronoUnit.NANOS;
68
69 import java.time.DateTimeException;
70 import java.time.Instant;
71 import java.time.LocalTime;
72 import java.time.ZoneId;
73 import java.time.ZoneOffset;
74 import java.time.ZonedDateTime;
75 import java.time.format.DateTimeFormatter;
76 import java.time.temporal.ChronoField;
77 import java.time.temporal.ChronoUnit;
78 import java.time.temporal.Temporal;
79 import java.time.temporal.TemporalAccessor;
80 import java.time.temporal.TemporalAdjuster;
81 import java.time.temporal.TemporalAmount;
82 import java.time.temporal.TemporalField;
83 import java.time.temporal.TemporalQuery;
84 import java.time.temporal.TemporalUnit;
85 import java.time.temporal.UnsupportedTemporalTypeException;
86 import java.time.temporal.ValueRange;
87 import java.util.Comparator;
88 import java.util.Objects;
89
90 /**
91 * A date-time with a time-zone in an arbitrary chronology,
92 * intended for advanced globalization use cases.
93 * <p>
94 * <b>Most applications should declare method signatures, fields and variables
95 * as {@link ZonedDateTime}, not this interface.</b>
96 * <p>
97 * A {@code ChronoZonedDateTime} is the abstract representation of an offset date-time
100 * where most common implementations are defined in {@link ChronoField}.
101 * The chronology defines how the calendar system operates and the meaning of
102 * the standard fields.
103 *
104 * <h3>When to use this interface</h3>
105 * The design of the API encourages the use of {@code ZonedDateTime} rather than this
106 * interface, even in the case where the application needs to deal with multiple
107 * calendar systems. The rationale for this is explored in detail in {@link ChronoLocalDate}.
108 * <p>
109 * Ensure that the discussion in {@code ChronoLocalDate} has been read and understood
110 * before using this interface.
111 *
112 * @implSpec
113 * This interface must be implemented with care to ensure other classes operate correctly.
114 * All implementations that can be instantiated must be final, immutable and thread-safe.
115 * Subclasses should be Serializable wherever possible.
116 *
117 * @param <D> the concrete type for the date of this date-time
118 * @since 1.8
119 */
120 public interface ChronoZonedDateTime<D extends ChronoLocalDate>
121 extends Temporal, Comparable<ChronoZonedDateTime<?>> {
122
123 /**
124 * Gets a comparator that compares {@code ChronoZonedDateTime} in
125 * time-line order ignoring the chronology.
126 * <p>
127 * This comparator differs from the comparison in {@link #compareTo} in that it
128 * only compares the underlying instant and not the chronology.
129 * This allows dates in different calendar systems to be compared based
130 * on the position of the date-time on the instant time-line.
131 * The underlying comparison is equivalent to comparing the epoch-second and nano-of-second.
132 *
133 * @return a comparator that compares in time-line order ignoring the chronology
134 *
135 * @see #isAfter
136 * @see #isBefore
137 * @see #isEqual
138 */
139 static Comparator<ChronoZonedDateTime<?>> timeLineOrder() {
140 return Chronology.INSTANT_ORDER;
323
324 /**
325 * Returns a copy of this date-time with a different time-zone,
326 * retaining the instant.
327 * <p>
328 * This method changes the time-zone and retains the instant.
329 * This normally results in a change to the local date-time.
330 * <p>
331 * This method is based on retaining the same instant, thus gaps and overlaps
332 * in the local time-line have no effect on the result.
333 * <p>
334 * To change the offset while keeping the local time,
335 * use {@link #withZoneSameLocal(ZoneId)}.
336 *
337 * @param zone the time-zone to change to, not null
338 * @return a {@code ChronoZonedDateTime} based on this date-time with the requested zone, not null
339 * @throws DateTimeException if the result exceeds the supported date range
340 */
341 ChronoZonedDateTime<D> withZoneSameInstant(ZoneId zone);
342
343 /**
344 * Checks if the specified field is supported.
345 * <p>
346 * This checks if the specified field can be queried on this date-time.
347 * If false, then calling the {@link #range(TemporalField) range},
348 * {@link #get(TemporalField) get} and {@link #with(TemporalField, long)}
349 * methods will throw an exception.
350 * <p>
351 * The set of supported fields is defined by the chronology and normally includes
352 * all {@code ChronoField} fields.
353 * <p>
354 * If the field is not a {@code ChronoField}, then the result of this method
355 * is obtained by invoking {@code TemporalField.isSupportedBy(TemporalAccessor)}
356 * passing {@code this} as the argument.
357 * Whether the field is supported is determined by the field.
358 *
359 * @param field the field to check, null returns false
360 * @return true if the field can be queried, false if not
361 */
362 @Override
363 boolean isSupported(TemporalField field);
364
365 /**
366 * Checks if the specified unit is supported.
367 * <p>
368 * This checks if the specified unit can be added to or subtracted from this date-time.
369 * If false, then calling the {@link #plus(long, TemporalUnit)} and
370 * {@link #minus(long, TemporalUnit) minus} methods will throw an exception.
371 * <p>
372 * The set of supported units is defined by the chronology and normally includes
373 * all {@code ChronoUnit} units except {@code FOREVER}.
374 * <p>
375 * If the unit is not a {@code ChronoUnit}, then the result of this method
376 * is obtained by invoking {@code TemporalUnit.isSupportedBy(Temporal)}
377 * passing {@code this} as the argument.
378 * Whether the unit is supported is determined by the unit.
379 *
380 * @param unit the unit to check, null returns false
381 * @return true if the unit can be added/subtracted, false if not
382 */
383 @Override
384 default boolean isSupported(TemporalUnit unit) {
385 if (unit instanceof ChronoUnit) {
386 return unit != FOREVER;
387 }
388 return unit != null && unit.isSupportedBy(this);
389 }
390
391 //-----------------------------------------------------------------------
392 // override for covariant return type
393 /**
394 * {@inheritDoc}
395 * @throws DateTimeException {@inheritDoc}
396 * @throws ArithmeticException {@inheritDoc}
397 */
398 @Override
399 default ChronoZonedDateTime<D> with(TemporalAdjuster adjuster) {
400 return ChronoZonedDateTimeImpl.ensureValid(toLocalDate().getChronology(), Temporal.super.with(adjuster));
401 }
402
403 /**
404 * {@inheritDoc}
405 * @throws DateTimeException {@inheritDoc}
406 * @throws ArithmeticException {@inheritDoc}
407 */
408 @Override
409 ChronoZonedDateTime<D> with(TemporalField field, long newValue);
410
411 /**
412 * {@inheritDoc}
413 * @throws DateTimeException {@inheritDoc}
414 * @throws ArithmeticException {@inheritDoc}
415 */
416 @Override
417 default ChronoZonedDateTime<D> plus(TemporalAmount amount) {
418 return ChronoZonedDateTimeImpl.ensureValid(toLocalDate().getChronology(), Temporal.super.plus(amount));
419 }
420
421 /**
422 * {@inheritDoc}
423 * @throws DateTimeException {@inheritDoc}
424 * @throws ArithmeticException {@inheritDoc}
425 */
426 @Override
427 ChronoZonedDateTime<D> plus(long amountToAdd, TemporalUnit unit);
428
429 /**
430 * {@inheritDoc}
431 * @throws DateTimeException {@inheritDoc}
432 * @throws ArithmeticException {@inheritDoc}
433 */
434 @Override
435 default ChronoZonedDateTime<D> minus(TemporalAmount amount) {
436 return ChronoZonedDateTimeImpl.ensureValid(toLocalDate().getChronology(), Temporal.super.minus(amount));
437 }
438
439 /**
440 * {@inheritDoc}
441 * @throws DateTimeException {@inheritDoc}
442 * @throws ArithmeticException {@inheritDoc}
443 */
444 @Override
445 default ChronoZonedDateTime<D> minus(long amountToSubtract, TemporalUnit unit) {
446 return ChronoZonedDateTimeImpl.ensureValid(toLocalDate().getChronology(), Temporal.super.minus(amountToSubtract, unit));
447 }
448
449 //-----------------------------------------------------------------------
450 /**
451 * Queries this date-time using the specified query.
452 * <p>
453 * This queries this date-time using the specified query strategy object.
454 * The {@code TemporalQuery} object defines the logic to be used to
455 * obtain the result. Read the documentation of the query to understand
456 * what the result of this method will be.
457 * <p>
458 * The result of this method is obtained by invoking the
459 * {@link java.time.temporal.TemporalQuery#queryFrom(TemporalAccessor)} method on the
460 * specified query passing {@code this} as the argument.
461 *
462 * @param <R> the type of the result
463 * @param query the query to invoke, not null
464 * @return the query result, null may be returned (defined by the query)
465 * @throws DateTimeException if unable to query (defined by the query)
466 * @throws ArithmeticException if numeric overflow occurs (defined by the query)
|