109 * <p> |
109 * <p> |
110 * It is intended that {@code ZonedDateTime} or {@code Instant} is used to model data |
110 * It is intended that {@code ZonedDateTime} or {@code Instant} is used to model data |
111 * in simpler applications. This class may be used when modeling date-time concepts in |
111 * in simpler applications. This class may be used when modeling date-time concepts in |
112 * more detail, or when communicating to a database or in a network protocol. |
112 * more detail, or when communicating to a database or in a network protocol. |
113 * |
113 * |
114 * <h3>Specification for implementors</h3> |
114 * @implSpec |
115 * This class is immutable and thread-safe. |
115 * This class is immutable and thread-safe. |
116 * |
116 * |
117 * @since 1.8 |
117 * @since 1.8 |
118 */ |
118 */ |
119 public final class OffsetDateTime |
119 public final class OffsetDateTime |
1519 .with(NANO_OF_DAY, toLocalTime().toNanoOfDay()) |
1519 .with(NANO_OF_DAY, toLocalTime().toNanoOfDay()) |
1520 .with(OFFSET_SECONDS, getOffset().getTotalSeconds()); |
1520 .with(OFFSET_SECONDS, getOffset().getTotalSeconds()); |
1521 } |
1521 } |
1522 |
1522 |
1523 /** |
1523 /** |
1524 * Calculates the period between this date-time and another date-time in |
1524 * Calculates the amount of time until another date-time in terms of the specified unit. |
1525 * terms of the specified unit. |
1525 * <p> |
1526 * <p> |
1526 * This calculates the amount of time between two {@code OffsetDateTime} |
1527 * This calculates the period between two date-times in terms of a single unit. |
1527 * objects in terms of a single {@code TemporalUnit}. |
1528 * The start and end points are {@code this} and the specified date-time. |
1528 * The start and end points are {@code this} and the specified date-time. |
1529 * The result will be negative if the end is before the start. |
1529 * The result will be negative if the end is before the start. |
1530 * For example, the period in days between two date-times can be calculated |
1530 * For example, the period in days between two date-times can be calculated |
1531 * using {@code startDateTime.periodUntil(endDateTime, DAYS)}. |
1531 * using {@code startDateTime.periodUntil(endDateTime, DAYS)}. |
1532 * <p> |
1532 * <p> |
1562 * the second argument. |
1562 * the second argument. |
1563 * <p> |
1563 * <p> |
1564 * This instance is immutable and unaffected by this method call. |
1564 * This instance is immutable and unaffected by this method call. |
1565 * |
1565 * |
1566 * @param endDateTime the end date-time, which must be an {@code OffsetDateTime}, not null |
1566 * @param endDateTime the end date-time, which must be an {@code OffsetDateTime}, not null |
1567 * @param unit the unit to measure the period in, not null |
1567 * @param unit the unit to measure the amount in, not null |
1568 * @return the amount of the period between this date-time and the end date-time |
1568 * @return the amount of time between this date-time and the end date-time |
1569 * @throws DateTimeException if the period cannot be calculated |
1569 * @throws DateTimeException if the amount cannot be calculated |
1570 * @throws UnsupportedTemporalTypeException if the unit is not supported |
1570 * @throws UnsupportedTemporalTypeException if the unit is not supported |
1571 * @throws ArithmeticException if numeric overflow occurs |
1571 * @throws ArithmeticException if numeric overflow occurs |
1572 */ |
1572 */ |
1573 @Override |
1573 @Override |
1574 public long periodUntil(Temporal endDateTime, TemporalUnit unit) { |
1574 public long periodUntil(Temporal endDateTime, TemporalUnit unit) { |
1575 if (endDateTime instanceof OffsetDateTime == false) { |
1575 if (endDateTime instanceof OffsetDateTime == false) { |
1576 Objects.requireNonNull(endDateTime, "endDateTime"); |
1576 Objects.requireNonNull(endDateTime, "endDateTime"); |
1577 throw new DateTimeException("Unable to calculate period between objects of two different types"); |
1577 throw new DateTimeException("Unable to calculate amount as objects are of two different types"); |
1578 } |
1578 } |
1579 if (unit instanceof ChronoUnit) { |
1579 if (unit instanceof ChronoUnit) { |
1580 OffsetDateTime end = (OffsetDateTime) endDateTime; |
1580 OffsetDateTime end = (OffsetDateTime) endDateTime; |
1581 end = end.withOffsetSameInstant(offset); |
1581 end = end.withOffsetSameInstant(offset); |
1582 return dateTime.periodUntil(end.dateTime, unit); |
1582 return dateTime.periodUntil(end.dateTime, unit); |