src/share/classes/java/time/chrono/ChronoLocalDate.java

Print this page




  42  *  * Redistributions in binary form must reproduce the above copyright notice,
  43  *    this list of conditions and the following disclaimer in the documentation
  44  *    and/or other materials provided with the distribution.
  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 static java.time.temporal.ChronoField.EPOCH_DAY;
  65 import static java.time.temporal.ChronoField.ERA;
  66 import static java.time.temporal.ChronoField.YEAR;
  67 import static java.time.temporal.ChronoUnit.DAYS;
  68 
  69 import java.time.DateTimeException;
  70 import java.time.LocalDate;
  71 import java.time.LocalTime;

  72 import java.time.format.DateTimeFormatter;










  73 import java.util.Comparator;
  74 import java.util.Objects;
  75 
  76 /**
  77  * A date without time-of-day or time-zone in an arbitrary chronology, intended
  78  * for advanced globalization use cases.
  79  * <p>
  80  * <b>Most applications should declare method signatures, fields and variables
  81  * as {@link LocalDate}, not this interface.</b>
  82  * <p>
  83  * A {@code ChronoLocalDate} is the abstract representation of a date where the
  84  * {@code Chrono chronology}, or calendar system, is pluggable.
  85  * The date is defined in terms of fields expressed by {@link TemporalField},
  86  * where most common implementations are defined in {@link ChronoField}.
  87  * The chronology defines how the calendar system operates and the meaning of
  88  * the standard fields.
  89  *
  90  * <h3>When to use this interface</h3>
  91  * The design of the API encourages the use of {@code LocalDate} rather than this
  92  * interface, even in the case where the application needs to deal with multiple
  93  * calendar systems. The rationale for this is explored in the following documentation.
  94  * <p>
  95  * The primary use case where this interface should be used is where the generic
  96  * type parameter {@code <C>} is fully defined as a specific chronology.
  97  * In that case, the assumptions of that chronology are known at development
  98  * time and specified in the code.
  99  * <p>
 100  * When the chronology is defined in the generic type parameter as ? or otherwise
 101  * unknown at development time, the rest of the discussion below applies.
 102  * <p>
 103  * To emphasize the point, declaring a method signature, field or variable as this
 104  * interface type can initially seem like the sensible way to globalize an application,
 105  * however it is usually the wrong approach.
 106  * As such, it should be considered an application-wide architectural decision to choose
 107  * to use this interface as opposed to {@code LocalDate}.
 108  *
 109  * <h3>Architectural issues to consider</h3>
 110  * These are some of the points that must be considered before using this interface
 111  * throughout an application.
 112  * <p>
 113  * 1) Applications using this interface, as opposed to using just {@code LocalDate},
 114  * face a significantly higher probability of bugs. This is because the calendar system
 115  * in use is not known at development time. A key cause of bugs is where the developer
 116  * applies assumptions from their day-to-day knowledge of the ISO calendar system


 212  * which may require manipulating the date.
 213  * This kind of use case can be handled as follows:
 214  * <p><ul>
 215  * <li>start from the ISO {@code LocalDate} being passed to the method
 216  * <li>convert the date to the alternate calendar system, which for this use case is known
 217  *  rather than arbitrary
 218  * <li>perform the calculation
 219  * <li>convert back to {@code LocalDate}
 220  * </ul><p>
 221  * Developers writing low-level frameworks or libraries should also avoid this interface.
 222  * Instead, one of the two general purpose access interfaces should be used.
 223  * Use {@link TemporalAccessor} if read-only access is required, or use {@link Temporal}
 224  * if read-write access is required.
 225  *
 226  * <h3>Specification for implementors</h3>
 227  * This interface must be implemented with care to ensure other classes operate correctly.
 228  * All implementations that can be instantiated must be final, immutable and thread-safe.
 229  * Subclasses should be Serializable wherever possible.
 230  * <p>
 231  * Additional calendar systems may be added to the system.
 232  * See {@link Chrono} for more details.
 233  *
 234  * @param <C> the chronology of this date
 235  * @since 1.8
 236  */
 237 public interface ChronoLocalDate<C extends Chrono<C>>
 238         extends Temporal, TemporalAdjuster, Comparable<ChronoLocalDate<?>> {
 239 
 240     /**
 241      * Comparator for two {@code ChronoLocalDate}s ignoring the chronology.
 242      * <p>
 243      * This comparator differs from the comparison in {@link #compareTo} in that it
 244      * only compares the underlying date and not the chronology.
 245      * This allows dates in different calendar systems to be compared based
 246      * on the time-line position.
 247      * This is equivalent to using {@code Long.compare(date1.toEpochDay(),  date2.toEpochDay())}.
 248      *
 249      * @see #isAfter
 250      * @see #isBefore
 251      * @see #isEqual
 252      */
 253     public static final Comparator<ChronoLocalDate<?>> DATE_COMPARATOR =
 254             new Comparator<ChronoLocalDate<?>>() {
 255         @Override
 256         public int compare(ChronoLocalDate<?> date1, ChronoLocalDate<?> date2) {
 257             return Long.compare(date1.toEpochDay(), date2.toEpochDay());
 258         }
 259     };
 260 
 261     //-----------------------------------------------------------------------
 262     /**
 263      * Gets the chronology of this date.
 264      * <p>
 265      * The {@code Chrono} represents the calendar system in use.
 266      * The era and other fields in {@link ChronoField} are defined by the chronology.
 267      *
 268      * @return the chronology, not null
 269      */
 270     C getChrono();
 271 
 272     /**
 273      * Gets the era, as defined by the chronology.
 274      * <p>
 275      * The era is, conceptually, the largest division of the time-line.
 276      * Most calendar systems have a single epoch dividing the time-line into two eras.
 277      * However, some have multiple eras, such as one for the reign of each leader.
 278      * The exact meaning is determined by the {@code Chrono}.
 279      * <p>
 280      * All correctly implemented {@code Era} classes are singletons, thus it
 281      * is valid code to write {@code date.getEra() == SomeChrono.ERA_NAME)}.
 282      * <p>
 283      * This default implementation uses {@link Chrono#eraOf(int)}.
 284      *
 285      * @return the chronology specific era constant applicable at this date, not null
 286      */
 287     public default Era<C> getEra() {
 288         return getChrono().eraOf(get(ERA));
 289     }
 290 
 291     /**
 292      * Checks if the year is a leap year, as defined by the calendar system.
 293      * <p>
 294      * A leap-year is a year of a longer length than normal.
 295      * The exact meaning is determined by the chronology with the constraint that
 296      * a leap-year must imply a year-length longer than a non leap-year.
 297      * <p>
 298      * This default implementation uses {@link Chrono#isLeapYear(long)}.
 299      *
 300      * @return true if this date is in a leap year, false otherwise
 301      */
 302     public default boolean isLeapYear() {
 303         return getChrono().isLeapYear(getLong(YEAR));
 304     }
 305 
 306     /**
 307      * Returns the length of the month represented by this date, as defined by the calendar system.
 308      * <p>
 309      * This returns the length of the month in days.
 310      *
 311      * @return the length of the month in days
 312      */
 313     int lengthOfMonth();
 314 
 315     /**
 316      * Returns the length of the year represented by this date, as defined by the calendar system.
 317      * <p>
 318      * This returns the length of the year in days.
 319      * <p>
 320      * The default implementation uses {@link #isLeapYear()} and returns 365 or 366.
 321      *
 322      * @return the length of the year in days
 323      */
 324     public default int lengthOfYear() {
 325         return (isLeapYear() ? 366 : 365);
 326     }
 327 
 328     @Override
 329     public default boolean isSupported(TemporalField field) {
 330         if (field instanceof ChronoField) {
 331             return ((ChronoField) field).isDateField();
 332         }
 333         return field != null && field.doIsSupported(this);
 334     }
 335 
 336     //-----------------------------------------------------------------------
 337     // override for covariant return type
 338     /**
 339      * {@inheritDoc}
 340      * @throws DateTimeException {@inheritDoc}
 341      * @throws ArithmeticException {@inheritDoc}
 342      */
 343     @Override
 344     public default ChronoLocalDate<C> with(TemporalAdjuster adjuster) {
 345         return getChrono().ensureChronoLocalDate(Temporal.super.with(adjuster));
 346     }
 347 
 348     /**
 349      * {@inheritDoc}
 350      * @throws DateTimeException {@inheritDoc}
 351      * @throws ArithmeticException {@inheritDoc}
 352      */
 353     @Override
 354     public default ChronoLocalDate<C> with(TemporalField field, long newValue) {
 355         if (field instanceof ChronoField) {
 356             throw new DateTimeException("Unsupported field: " + field.getName());
 357         }
 358         return getChrono().ensureChronoLocalDate(field.doWith(this, newValue));
 359     }
 360 
 361     /**
 362      * {@inheritDoc}
 363      * @throws DateTimeException {@inheritDoc}
 364      * @throws ArithmeticException {@inheritDoc}
 365      */
 366     @Override
 367     public default ChronoLocalDate<C> plus(TemporalAdder adder) {
 368         return getChrono().ensureChronoLocalDate(Temporal.super.plus(adder));
 369     }
 370 
 371     /**
 372      * {@inheritDoc}
 373      * @throws DateTimeException {@inheritDoc}
 374      * @throws ArithmeticException {@inheritDoc}
 375      */
 376     @Override
 377     public default ChronoLocalDate<C> plus(long amountToAdd, TemporalUnit unit) {
 378         if (unit instanceof ChronoUnit) {
 379             throw new DateTimeException("Unsupported unit: " + unit.getName());
 380         }
 381         return getChrono().ensureChronoLocalDate(unit.doPlus(this, amountToAdd));
 382     }
 383 
 384     /**
 385      * {@inheritDoc}
 386      * @throws DateTimeException {@inheritDoc}
 387      * @throws ArithmeticException {@inheritDoc}
 388      */
 389     @Override
 390     public default ChronoLocalDate<C> minus(TemporalSubtractor subtractor) {
 391         return getChrono().ensureChronoLocalDate(Temporal.super.minus(subtractor));
 392     }
 393 
 394     /**
 395      * {@inheritDoc}
 396      * @throws DateTimeException {@inheritDoc}
 397      * @throws ArithmeticException {@inheritDoc}
 398      */
 399     @Override
 400     public default ChronoLocalDate<C> minus(long amountToSubtract, TemporalUnit unit) {
 401         return getChrono().ensureChronoLocalDate(Temporal.super.minus(amountToSubtract, unit));
 402     }
 403 
 404     //-----------------------------------------------------------------------
 405     /**
 406      * Queries this date using the specified query.
 407      * <p>
 408      * This queries this date using the specified query strategy object.
 409      * The {@code TemporalQuery} object defines the logic to be used to
 410      * obtain the result. Read the documentation of the query to understand
 411      * what the result of this method will be.
 412      * <p>
 413      * The result of this method is obtained by invoking the
 414      * {@link TemporalQuery#queryFrom(TemporalAccessor)} method on the
 415      * specified query passing {@code this} as the argument.
 416      *
 417      * @param <R> the type of the result
 418      * @param query  the query to invoke, not null
 419      * @return the query result, null may be returned (defined by the query)
 420      * @throws DateTimeException if unable to query (defined by the query)
 421      * @throws ArithmeticException if numeric overflow occurs (defined by the query)
 422      */
 423     @SuppressWarnings("unchecked")
 424     @Override
 425     public default <R> R query(TemporalQuery<R> query) {
 426         if (query == Queries.chrono()) {
 427             return (R) getChrono();
 428         }
 429         if (query == Queries.precision()) {
 430             return (R) DAYS;
 431         }
 432         // inline TemporalAccessor.super.query(query) as an optimization
 433         if (query == Queries.zoneId() || query == Queries.zone() || query == Queries.offset()) {
 434             return null;






 435         }


 436         return query.queryFrom(this);
 437     }
 438 
 439     /**
 440      * Adjusts the specified temporal object to have the same date as this object.
 441      * <p>
 442      * This returns a temporal object of the same observable type as the input
 443      * with the date changed to be the same as this.
 444      * <p>
 445      * The adjustment is equivalent to using {@link Temporal#with(TemporalField, long)}
 446      * passing {@link ChronoField#EPOCH_DAY} as the field.
 447      * <p>
 448      * In most cases, it is clearer to reverse the calling pattern by using
 449      * {@link Temporal#with(TemporalAdjuster)}:
 450      * <pre>
 451      *   // these two lines are equivalent, but the second approach is recommended
 452      *   temporal = thisLocalDate.adjustInto(temporal);
 453      *   temporal = temporal.with(thisLocalDate);
 454      * </pre>
 455      * <p>


 462      */
 463     @Override
 464     public default Temporal adjustInto(Temporal temporal) {
 465         return temporal.with(EPOCH_DAY, toEpochDay());
 466     }
 467 
 468     /**
 469      * Calculates the period between this date and another date in
 470      * terms of the specified unit.
 471      * <p>
 472      * This calculates the period between two dates in terms of a single unit.
 473      * The start and end points are {@code this} and the specified date.
 474      * The result will be negative if the end is before the start.
 475      * The {@code Temporal} passed to this method must be a
 476      * {@code ChronoLocalDate} in the same chronology.
 477      * The calculation returns a whole number, representing the number of
 478      * complete units between the two dates.
 479      * For example, the period in days between two dates can be calculated
 480      * using {@code startDate.periodUntil(endDate, DAYS)}.
 481      * <p>
 482      * This method operates in association with {@link TemporalUnit#between}.
 483      * The result of this method is a {@code long} representing the amount of
 484      * the specified unit. By contrast, the result of {@code between} is an
 485      * object that can be used directly in addition/subtraction:
 486      * <pre>
 487      *   long period = start.periodUntil(end, MONTHS);   // this method
 488      *   dateTime.plus(MONTHS.between(start, end));      // use in plus/minus

 489      * </pre>

 490      * <p>
 491      * The calculation is implemented in this method for {@link ChronoUnit}.
 492      * The units {@code DAYS}, {@code WEEKS}, {@code MONTHS}, {@code YEARS},
 493      * {@code DECADES}, {@code CENTURIES}, {@code MILLENNIA} and {@code ERAS}
 494      * should be supported by all implementations.
 495      * Other {@code ChronoUnit} values will throw an exception.
 496      * <p>
 497      * If the unit is not a {@code ChronoUnit}, then the result of this method
 498      * is obtained by invoking {@code TemporalUnit.between(Temporal, Temporal)}
 499      * passing {@code this} as the first argument and the input temporal as
 500      * the second argument.
 501      * <p>
 502      * This instance is immutable and unaffected by this method call.
 503      *
 504      * @param endDate  the end date, which must be a {@code ChronoLocalDate}
 505      *  in the same chronology, not null
 506      * @param unit  the unit to measure the period in, not null
 507      * @return the amount of the period between this date and the end date
 508      * @throws DateTimeException if the period cannot be calculated
 509      * @throws ArithmeticException if numeric overflow occurs
 510      */
 511     @Override  // override for Javadoc
 512     public abstract long periodUntil(Temporal endDate, TemporalUnit unit);
 513 
 514     //-----------------------------------------------------------------------
 515     /**
 516      * Returns a date-time formed from this date at the specified time.
 517      * <p>
 518      * This merges the two objects - {@code this} and the specified time -
 519      * to form an instance of {@code ChronoLocalDateTime}.







 520      * <p>
 521      * This instance is immutable and unaffected by this method call.











 522      * <p>
 523      * This default implementation creates the date-time.

 524      *
 525      * @param localTime  the local time to use, not null
 526      * @return the local date-time formed from this date and the specified time, not null
 527      */
 528     public default ChronoLocalDateTime<C> atTime(LocalTime localTime) {
 529         return Chrono.dateTime(this, localTime);
 530     }
 531 
 532     //-----------------------------------------------------------------------
 533     /**
 534      * Converts this date to the Epoch Day.
 535      * <p>
 536      * The {@link ChronoField#EPOCH_DAY Epoch Day count} is a simple
 537      * incrementing count of days where day 0 is 1970-01-01 (ISO).
 538      * This definition is the same for all chronologies, enabling conversion.
 539      * <p>
 540      * This default implementation queries the {@code EPOCH_DAY} field.
 541      *
 542      * @return the Epoch Day equivalent to this date
 543      */
 544     public default long toEpochDay() {
 545         return getLong(EPOCH_DAY);
 546     }
 547 
 548     //-----------------------------------------------------------------------
 549     /**


 561      * <li>{@code 2012-12-05 (ISO)}</li>
 562      * </ol>
 563      * Values #2 and #3 represent the same date on the time-line.
 564      * When two values represent the same date, the chronology ID is compared to distinguish them.
 565      * This step is needed to make the ordering "consistent with equals".
 566      * <p>
 567      * If all the date objects being compared are in the same chronology, then the
 568      * additional chronology stage is not required and only the local date is used.
 569      * To compare the dates of two {@code TemporalAccessor} instances, including dates
 570      * in two different chronologies, use {@link ChronoField#EPOCH_DAY} as a comparator.
 571      * <p>
 572      * This default implementation performs the comparison defined above.
 573      *
 574      * @param other  the other date to compare to, not null
 575      * @return the comparator value, negative if less, positive if greater
 576      */
 577     @Override
 578     public default int compareTo(ChronoLocalDate<?> other) {
 579         int cmp = Long.compare(toEpochDay(), other.toEpochDay());
 580         if (cmp == 0) {
 581             cmp = getChrono().compareTo(other.getChrono());
 582         }
 583         return cmp;
 584     }
 585 
 586     /**
 587      * Checks if this date is after the specified date ignoring the chronology.
 588      * <p>
 589      * This method differs from the comparison in {@link #compareTo} in that it
 590      * only compares the underlying date and not the chronology.
 591      * This allows dates in different calendar systems to be compared based
 592      * on the time-line position.
 593      * This is equivalent to using {@code date1.toEpochDay() &gt; date2.toEpochDay()}.
 594      * <p>
 595      * This default implementation performs the comparison based on the epoch-day.
 596      *
 597      * @param other  the other date to compare to, not null
 598      * @return true if this is after the specified date
 599      */
 600     public default boolean isAfter(ChronoLocalDate<?> other) {
 601         return this.toEpochDay() > other.toEpochDay();


 659      */
 660     @Override
 661     int hashCode();
 662 
 663     //-----------------------------------------------------------------------
 664     /**
 665      * Outputs this date as a {@code String}.
 666      * <p>
 667      * The output will include the full local date and the chronology ID.
 668      *
 669      * @return the formatted date, not null
 670      */
 671     @Override
 672     String toString();
 673 
 674     /**
 675      * Outputs this date as a {@code String} using the formatter.
 676      * <p>
 677      * The default implementation must behave as follows:
 678      * <pre>
 679      *  return formatter.print(this);
 680      * </pre>
 681      *
 682      * @param formatter  the formatter to use, not null
 683      * @return the formatted date string, not null
 684      * @throws DateTimeException if an error occurs during printing
 685      */
 686     public default String toString(DateTimeFormatter formatter) {
 687         Objects.requireNonNull(formatter, "formatter");
 688         return formatter.print(this);
 689     }
 690 
 691 }


  42  *  * Redistributions in binary form must reproduce the above copyright notice,
  43  *    this list of conditions and the following disclaimer in the documentation
  44  *    and/or other materials provided with the distribution.
  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.chrono;
  63 
  64 import static java.time.temporal.ChronoField.EPOCH_DAY;
  65 import static java.time.temporal.ChronoField.ERA;
  66 import static java.time.temporal.ChronoField.YEAR;
  67 import static java.time.temporal.ChronoUnit.DAYS;
  68 
  69 import java.time.DateTimeException;
  70 import java.time.LocalDate;
  71 import java.time.LocalTime;
  72 import java.time.Period;
  73 import java.time.format.DateTimeFormatter;
  74 import java.time.temporal.ChronoField;
  75 import java.time.temporal.ChronoUnit;
  76 import java.time.temporal.Queries;
  77 import java.time.temporal.Temporal;
  78 import java.time.temporal.TemporalAccessor;
  79 import java.time.temporal.TemporalAdjuster;
  80 import java.time.temporal.TemporalAmount;
  81 import java.time.temporal.TemporalField;
  82 import java.time.temporal.TemporalQuery;
  83 import java.time.temporal.TemporalUnit;
  84 import java.util.Comparator;
  85 import java.util.Objects;
  86 
  87 /**
  88  * A date without time-of-day or time-zone in an arbitrary chronology, intended
  89  * for advanced globalization use cases.
  90  * <p>
  91  * <b>Most applications should declare method signatures, fields and variables
  92  * as {@link LocalDate}, not this interface.</b>
  93  * <p>
  94  * A {@code ChronoLocalDate} is the abstract representation of a date where the
  95  * {@code Chronology chronology}, or calendar system, is pluggable.
  96  * The date is defined in terms of fields expressed by {@link TemporalField},
  97  * where most common implementations are defined in {@link ChronoField}.
  98  * The chronology defines how the calendar system operates and the meaning of
  99  * the standard fields.
 100  *
 101  * <h3>When to use this interface</h3>
 102  * The design of the API encourages the use of {@code LocalDate} rather than this
 103  * interface, even in the case where the application needs to deal with multiple
 104  * calendar systems. The rationale for this is explored in the following documentation.
 105  * <p>
 106  * The primary use case where this interface should be used is where the generic
 107  * type parameter {@code <D>} is fully defined as a specific chronology.
 108  * In that case, the assumptions of that chronology are known at development
 109  * time and specified in the code.
 110  * <p>
 111  * When the chronology is defined in the generic type parameter as ? or otherwise
 112  * unknown at development time, the rest of the discussion below applies.
 113  * <p>
 114  * To emphasize the point, declaring a method signature, field or variable as this
 115  * interface type can initially seem like the sensible way to globalize an application,
 116  * however it is usually the wrong approach.
 117  * As such, it should be considered an application-wide architectural decision to choose
 118  * to use this interface as opposed to {@code LocalDate}.
 119  *
 120  * <h3>Architectural issues to consider</h3>
 121  * These are some of the points that must be considered before using this interface
 122  * throughout an application.
 123  * <p>
 124  * 1) Applications using this interface, as opposed to using just {@code LocalDate},
 125  * face a significantly higher probability of bugs. This is because the calendar system
 126  * in use is not known at development time. A key cause of bugs is where the developer
 127  * applies assumptions from their day-to-day knowledge of the ISO calendar system


 223  * which may require manipulating the date.
 224  * This kind of use case can be handled as follows:
 225  * <p><ul>
 226  * <li>start from the ISO {@code LocalDate} being passed to the method
 227  * <li>convert the date to the alternate calendar system, which for this use case is known
 228  *  rather than arbitrary
 229  * <li>perform the calculation
 230  * <li>convert back to {@code LocalDate}
 231  * </ul><p>
 232  * Developers writing low-level frameworks or libraries should also avoid this interface.
 233  * Instead, one of the two general purpose access interfaces should be used.
 234  * Use {@link TemporalAccessor} if read-only access is required, or use {@link Temporal}
 235  * if read-write access is required.
 236  *
 237  * <h3>Specification for implementors</h3>
 238  * This interface must be implemented with care to ensure other classes operate correctly.
 239  * All implementations that can be instantiated must be final, immutable and thread-safe.
 240  * Subclasses should be Serializable wherever possible.
 241  * <p>
 242  * Additional calendar systems may be added to the system.
 243  * See {@link Chronology} for more details.
 244  *
 245  * @param <D> the concrete type for the date
 246  * @since 1.8
 247  */
 248 public interface ChronoLocalDate<D extends ChronoLocalDate<D>>
 249         extends Temporal, TemporalAdjuster, Comparable<ChronoLocalDate<?>> {
 250 
 251     /**
 252      * Comparator for two {@code ChronoLocalDate}s ignoring the chronology.
 253      * <p>
 254      * This comparator differs from the comparison in {@link #compareTo} in that it
 255      * only compares the underlying date and not the chronology.
 256      * This allows dates in different calendar systems to be compared based
 257      * on the time-line position.
 258      * This is equivalent to using {@code Long.compare(date1.toEpochDay(),  date2.toEpochDay())}.
 259      *
 260      * @see #isAfter
 261      * @see #isBefore
 262      * @see #isEqual
 263      */
 264     public static final Comparator<ChronoLocalDate<?>> DATE_COMPARATOR =
 265             new Comparator<ChronoLocalDate<?>>() {
 266         @Override
 267         public int compare(ChronoLocalDate<?> date1, ChronoLocalDate<?> date2) {
 268             return Long.compare(date1.toEpochDay(), date2.toEpochDay());
 269         }
 270     };
 271 
 272     //-----------------------------------------------------------------------
 273     /**
 274      * Gets the chronology of this date.
 275      * <p>
 276      * The {@code Chronology} represents the calendar system in use.
 277      * The era and other fields in {@link ChronoField} are defined by the chronology.
 278      *
 279      * @return the chronology, not null
 280      */
 281     Chronology getChronology();
 282 
 283     /**
 284      * Gets the era, as defined by the chronology.
 285      * <p>
 286      * The era is, conceptually, the largest division of the time-line.
 287      * Most calendar systems have a single epoch dividing the time-line into two eras.
 288      * However, some have multiple eras, such as one for the reign of each leader.
 289      * The exact meaning is determined by the {@code Chronology}.
 290      * <p>
 291      * All correctly implemented {@code Era} classes are singletons, thus it
 292      * is valid code to write {@code date.getEra() == SomeChrono.ERA_NAME)}.
 293      * <p>
 294      * This default implementation uses {@link Chronology#eraOf(int)}.
 295      *
 296      * @return the chronology specific era constant applicable at this date, not null
 297      */
 298     public default Era getEra() {
 299         return getChronology().eraOf(get(ERA));
 300     }
 301 
 302     /**
 303      * Checks if the year is a leap year, as defined by the calendar system.
 304      * <p>
 305      * A leap-year is a year of a longer length than normal.
 306      * The exact meaning is determined by the chronology with the constraint that
 307      * a leap-year must imply a year-length longer than a non leap-year.
 308      * <p>
 309      * This default implementation uses {@link Chronology#isLeapYear(long)}.
 310      *
 311      * @return true if this date is in a leap year, false otherwise
 312      */
 313     public default boolean isLeapYear() {
 314         return getChronology().isLeapYear(getLong(YEAR));
 315     }
 316 
 317     /**
 318      * Returns the length of the month represented by this date, as defined by the calendar system.
 319      * <p>
 320      * This returns the length of the month in days.
 321      *
 322      * @return the length of the month in days
 323      */
 324     int lengthOfMonth();
 325 
 326     /**
 327      * Returns the length of the year represented by this date, as defined by the calendar system.
 328      * <p>
 329      * This returns the length of the year in days.
 330      * <p>
 331      * The default implementation uses {@link #isLeapYear()} and returns 365 or 366.
 332      *
 333      * @return the length of the year in days
 334      */
 335     public default int lengthOfYear() {
 336         return (isLeapYear() ? 366 : 365);
 337     }
 338 
 339     @Override
 340     public default boolean isSupported(TemporalField field) {
 341         if (field instanceof ChronoField) {
 342             return ((ChronoField) field).isDateField();
 343         }
 344         return field != null && field.isSupportedBy(this);
 345     }
 346 
 347     //-----------------------------------------------------------------------
 348     // override for covariant return type
 349     /**
 350      * {@inheritDoc}
 351      * @throws DateTimeException {@inheritDoc}
 352      * @throws ArithmeticException {@inheritDoc}
 353      */
 354     @Override
 355     public default D with(TemporalAdjuster adjuster) {
 356         return (D) getChronology().ensureChronoLocalDate(Temporal.super.with(adjuster));
 357     }
 358 
 359     /**
 360      * {@inheritDoc}
 361      * @throws DateTimeException {@inheritDoc}
 362      * @throws ArithmeticException {@inheritDoc}
 363      */
 364     @Override
 365     public default D with(TemporalField field, long newValue) {
 366         if (field instanceof ChronoField) {
 367             throw new DateTimeException("Unsupported field: " + field.getName());
 368         }
 369         return (D) getChronology().ensureChronoLocalDate(field.adjustInto(this, newValue));
 370     }
 371 
 372     /**
 373      * {@inheritDoc}
 374      * @throws DateTimeException {@inheritDoc}
 375      * @throws ArithmeticException {@inheritDoc}
 376      */
 377     @Override
 378     public default D plus(TemporalAmount amount) {
 379         return (D) getChronology().ensureChronoLocalDate(Temporal.super.plus(amount));
 380     }
 381 
 382     /**
 383      * {@inheritDoc}
 384      * @throws DateTimeException {@inheritDoc}
 385      * @throws ArithmeticException {@inheritDoc}
 386      */
 387     @Override
 388     public default D plus(long amountToAdd, TemporalUnit unit) {
 389         if (unit instanceof ChronoUnit) {
 390             throw new DateTimeException("Unsupported unit: " + unit.getName());
 391         }
 392         return (D) getChronology().ensureChronoLocalDate(unit.addTo(this, amountToAdd));
 393     }
 394 
 395     /**
 396      * {@inheritDoc}
 397      * @throws DateTimeException {@inheritDoc}
 398      * @throws ArithmeticException {@inheritDoc}
 399      */
 400     @Override
 401     public default D minus(TemporalAmount amount) {
 402         return (D) getChronology().ensureChronoLocalDate(Temporal.super.minus(amount));
 403     }
 404 
 405     /**
 406      * {@inheritDoc}
 407      * @throws DateTimeException {@inheritDoc}
 408      * @throws ArithmeticException {@inheritDoc}
 409      */
 410     @Override
 411     public default D minus(long amountToSubtract, TemporalUnit unit) {
 412         return (D) getChronology().ensureChronoLocalDate(Temporal.super.minus(amountToSubtract, unit));
 413     }
 414 
 415     //-----------------------------------------------------------------------
 416     /**
 417      * Queries this date using the specified query.
 418      * <p>
 419      * This queries this date using the specified query strategy object.
 420      * The {@code TemporalQuery} object defines the logic to be used to
 421      * obtain the result. Read the documentation of the query to understand
 422      * what the result of this method will be.
 423      * <p>
 424      * The result of this method is obtained by invoking the
 425      * {@link TemporalQuery#queryFrom(TemporalAccessor)} method on the
 426      * specified query passing {@code this} as the argument.
 427      *
 428      * @param <R> the type of the result
 429      * @param query  the query to invoke, not null
 430      * @return the query result, null may be returned (defined by the query)
 431      * @throws DateTimeException if unable to query (defined by the query)
 432      * @throws ArithmeticException if numeric overflow occurs (defined by the query)
 433      */
 434     @SuppressWarnings("unchecked")
 435     @Override
 436     public default <R> R query(TemporalQuery<R> query) {







 437         if (query == Queries.zoneId() || query == Queries.zone() || query == Queries.offset()) {
 438             return null;
 439         } else if (query == Queries.localTime()) {
 440             return null;
 441         } else if (query == Queries.chronology()) {
 442             return (R) getChronology();
 443         } else if (query == Queries.precision()) {
 444             return (R) DAYS;
 445         }
 446         // inline TemporalAccessor.super.query(query) as an optimization
 447         // non-JDK classes are not permitted to make this optimization
 448         return query.queryFrom(this);
 449     }
 450 
 451     /**
 452      * Adjusts the specified temporal object to have the same date as this object.
 453      * <p>
 454      * This returns a temporal object of the same observable type as the input
 455      * with the date changed to be the same as this.
 456      * <p>
 457      * The adjustment is equivalent to using {@link Temporal#with(TemporalField, long)}
 458      * passing {@link ChronoField#EPOCH_DAY} as the field.
 459      * <p>
 460      * In most cases, it is clearer to reverse the calling pattern by using
 461      * {@link Temporal#with(TemporalAdjuster)}:
 462      * <pre>
 463      *   // these two lines are equivalent, but the second approach is recommended
 464      *   temporal = thisLocalDate.adjustInto(temporal);
 465      *   temporal = temporal.with(thisLocalDate);
 466      * </pre>
 467      * <p>


 474      */
 475     @Override
 476     public default Temporal adjustInto(Temporal temporal) {
 477         return temporal.with(EPOCH_DAY, toEpochDay());
 478     }
 479 
 480     /**
 481      * Calculates the period between this date and another date in
 482      * terms of the specified unit.
 483      * <p>
 484      * This calculates the period between two dates in terms of a single unit.
 485      * The start and end points are {@code this} and the specified date.
 486      * The result will be negative if the end is before the start.
 487      * The {@code Temporal} passed to this method must be a
 488      * {@code ChronoLocalDate} in the same chronology.
 489      * The calculation returns a whole number, representing the number of
 490      * complete units between the two dates.
 491      * For example, the period in days between two dates can be calculated
 492      * using {@code startDate.periodUntil(endDate, DAYS)}.
 493      * <p>
 494      * There are two equivalent ways of using this method.
 495      * The first is to invoke this method.
 496      * The second is to use {@link TemporalUnit#between(Temporal, Temporal)}:

 497      * <pre>
 498      *   // these two lines are equivalent
 499      *   amount = start.periodUntil(end, MONTHS);
 500      *   amount = MONTHS.between(start, end);
 501      * </pre>
 502      * The choice should be made based on which makes the code more readable.
 503      * <p>
 504      * The calculation is implemented in this method for {@link ChronoUnit}.
 505      * The units {@code DAYS}, {@code WEEKS}, {@code MONTHS}, {@code YEARS},
 506      * {@code DECADES}, {@code CENTURIES}, {@code MILLENNIA} and {@code ERAS}
 507      * should be supported by all implementations.
 508      * Other {@code ChronoUnit} values will throw an exception.
 509      * <p>
 510      * If the unit is not a {@code ChronoUnit}, then the result of this method
 511      * is obtained by invoking {@code TemporalUnit.between(Temporal, Temporal)}
 512      * passing {@code this} as the first argument and the input temporal as
 513      * the second argument.
 514      * <p>
 515      * This instance is immutable and unaffected by this method call.
 516      *
 517      * @param endDate  the end date, which must be a {@code ChronoLocalDate}
 518      *  in the same chronology, not null
 519      * @param unit  the unit to measure the period in, not null
 520      * @return the amount of the period between this date and the end date
 521      * @throws DateTimeException if the period cannot be calculated
 522      * @throws ArithmeticException if numeric overflow occurs
 523      */
 524     @Override  // override for Javadoc
 525     public abstract long periodUntil(Temporal endDate, TemporalUnit unit);
 526 

 527     /**
 528      * Calculates the period between this date and another date as a {@code Period}.
 529      * <p>
 530      * This calculates the period between two dates in terms of years, months and days.
 531      * The start and end points are {@code this} and the specified date.
 532      * The result will be negative if the end is before the start.
 533      * <p>
 534      * The calculation is performed using the the chronology of this date.
 535      * If necessary, the input date will be converted to match.
 536      * <p>
 537      * The result of this method can be a negative period if the end is before the start.
 538      * The negative sign will be the same in each of year, month and day.
 539      * <p>
 540      * This instance is immutable and unaffected by this method call.
 541      *
 542      * @param endDate  the end date, exclusive, which may be in any chronology, not null
 543      * @return the period between this date and the end date, not null
 544      * @throws DateTimeException if the period cannot be calculated
 545      * @throws ArithmeticException if numeric overflow occurs
 546      */
 547     public abstract Period periodUntil(ChronoLocalDate<?> endDate);
 548 
 549     //-----------------------------------------------------------------------
 550     /**
 551      * Combines this date with a time to create a {@code ChronoLocalDateTime}.
 552      * <p>
 553      * This returns a {@code ChronoLocalDateTime} formed from this date at the specified time.
 554      * All possible combinations of date and time are valid.
 555      *
 556      * @param localTime  the local time to use, not null
 557      * @return the local date-time formed from this date and the specified time, not null
 558      */
 559     public default ChronoLocalDateTime<D> atTime(LocalTime localTime) {
 560         return (ChronoLocalDateTime<D>)ChronoLocalDateTimeImpl.of(this, localTime);
 561     }
 562 
 563     //-----------------------------------------------------------------------
 564     /**
 565      * Converts this date to the Epoch Day.
 566      * <p>
 567      * The {@link ChronoField#EPOCH_DAY Epoch Day count} is a simple
 568      * incrementing count of days where day 0 is 1970-01-01 (ISO).
 569      * This definition is the same for all chronologies, enabling conversion.
 570      * <p>
 571      * This default implementation queries the {@code EPOCH_DAY} field.
 572      *
 573      * @return the Epoch Day equivalent to this date
 574      */
 575     public default long toEpochDay() {
 576         return getLong(EPOCH_DAY);
 577     }
 578 
 579     //-----------------------------------------------------------------------
 580     /**


 592      * <li>{@code 2012-12-05 (ISO)}</li>
 593      * </ol>
 594      * Values #2 and #3 represent the same date on the time-line.
 595      * When two values represent the same date, the chronology ID is compared to distinguish them.
 596      * This step is needed to make the ordering "consistent with equals".
 597      * <p>
 598      * If all the date objects being compared are in the same chronology, then the
 599      * additional chronology stage is not required and only the local date is used.
 600      * To compare the dates of two {@code TemporalAccessor} instances, including dates
 601      * in two different chronologies, use {@link ChronoField#EPOCH_DAY} as a comparator.
 602      * <p>
 603      * This default implementation performs the comparison defined above.
 604      *
 605      * @param other  the other date to compare to, not null
 606      * @return the comparator value, negative if less, positive if greater
 607      */
 608     @Override
 609     public default int compareTo(ChronoLocalDate<?> other) {
 610         int cmp = Long.compare(toEpochDay(), other.toEpochDay());
 611         if (cmp == 0) {
 612             cmp = getChronology().compareTo(other.getChronology());
 613         }
 614         return cmp;
 615     }
 616 
 617     /**
 618      * Checks if this date is after the specified date ignoring the chronology.
 619      * <p>
 620      * This method differs from the comparison in {@link #compareTo} in that it
 621      * only compares the underlying date and not the chronology.
 622      * This allows dates in different calendar systems to be compared based
 623      * on the time-line position.
 624      * This is equivalent to using {@code date1.toEpochDay() &gt; date2.toEpochDay()}.
 625      * <p>
 626      * This default implementation performs the comparison based on the epoch-day.
 627      *
 628      * @param other  the other date to compare to, not null
 629      * @return true if this is after the specified date
 630      */
 631     public default boolean isAfter(ChronoLocalDate<?> other) {
 632         return this.toEpochDay() > other.toEpochDay();


 690      */
 691     @Override
 692     int hashCode();
 693 
 694     //-----------------------------------------------------------------------
 695     /**
 696      * Outputs this date as a {@code String}.
 697      * <p>
 698      * The output will include the full local date and the chronology ID.
 699      *
 700      * @return the formatted date, not null
 701      */
 702     @Override
 703     String toString();
 704 
 705     /**
 706      * Outputs this date as a {@code String} using the formatter.
 707      * <p>
 708      * The default implementation must behave as follows:
 709      * <pre>
 710      *  return formatter.format(this);
 711      * </pre>
 712      *
 713      * @param formatter  the formatter to use, not null
 714      * @return the formatted date string, not null
 715      * @throws DateTimeException if an error occurs during printing
 716      */
 717     public default String toString(DateTimeFormatter formatter) {
 718         Objects.requireNonNull(formatter, "formatter");
 719         return formatter.format(this);
 720     }
 721 
 722 }