1 /*
   2  * Copyright (c) 2012, 2016, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 /*
  27  * This file is available under and governed by the GNU General Public
  28  * License version 2 only, as published by the Free Software Foundation.
  29  * However, the following notice accompanied the original version of this
  30  * file:
  31  *
  32  * Copyright (c) 2012, Stephen Colebourne & Michael Nascimento Santos
  33  *
  34  * All rights reserved.
  35  *
  36  * Redistribution and use in source and binary forms, with or without
  37  * modification, are permitted provided that the following conditions are met:
  38  *
  39  *  * Redistributions of source code must retain the above copyright notice,
  40  *    this list of conditions and the following disclaimer.
  41  *
  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 java.time.Clock;
  65 import java.time.DateTimeException;
  66 import java.time.Instant;
  67 import java.time.LocalDate;
  68 import java.time.LocalTime;
  69 import java.time.ZoneId;
  70 import java.time.ZoneOffset;
  71 import java.time.format.DateTimeFormatterBuilder;
  72 import java.time.format.ResolverStyle;
  73 import java.time.format.TextStyle;
  74 import java.time.temporal.ChronoField;
  75 import java.time.temporal.TemporalAccessor;
  76 import java.time.temporal.TemporalField;
  77 import java.time.temporal.TemporalQueries;
  78 import java.time.temporal.TemporalQuery;
  79 import java.time.temporal.UnsupportedTemporalTypeException;
  80 import java.time.temporal.ValueRange;
  81 import java.util.List;
  82 import java.util.Locale;
  83 import java.util.Map;
  84 import java.util.Objects;
  85 import java.util.Set;
  86 
  87 /**
  88  * A calendar system, used to organize and identify dates.
  89  * <p>
  90  * The main date and time API is built on the ISO calendar system.
  91  * The chronology operates behind the scenes to represent the general concept of a calendar system.
  92  * For example, the Japanese, Minguo, Thai Buddhist and others.
  93  * <p>
  94  * Most other calendar systems also operate on the shared concepts of year, month and day,
  95  * linked to the cycles of the Earth around the Sun, and the Moon around the Earth.
  96  * These shared concepts are defined by {@link ChronoField} and are available
  97  * for use by any {@code Chronology} implementation:
  98  * <pre>
  99  *   LocalDate isoDate = ...
 100  *   ThaiBuddhistDate thaiDate = ...
 101  *   int isoYear = isoDate.get(ChronoField.YEAR);
 102  *   int thaiYear = thaiDate.get(ChronoField.YEAR);
 103  * </pre>
 104  * As shown, although the date objects are in different calendar systems, represented by different
 105  * {@code Chronology} instances, both can be queried using the same constant on {@code ChronoField}.
 106  * For a full discussion of the implications of this, see {@link ChronoLocalDate}.
 107  * In general, the advice is to use the known ISO-based {@code LocalDate}, rather than
 108  * {@code ChronoLocalDate}.
 109  * <p>
 110  * While a {@code Chronology} object typically uses {@code ChronoField} and is based on
 111  * an era, year-of-era, month-of-year, day-of-month model of a date, this is not required.
 112  * A {@code Chronology} instance may represent a totally different kind of calendar system,
 113  * such as the Mayan.
 114  * <p>
 115  * In practical terms, the {@code Chronology} instance also acts as a factory.
 116  * The {@link #of(String)} method allows an instance to be looked up by identifier,
 117  * while the {@link #ofLocale(Locale)} method allows lookup by locale.
 118  * <p>
 119  * The {@code Chronology} instance provides a set of methods to create {@code ChronoLocalDate} instances.
 120  * The date classes are used to manipulate specific dates.
 121  * <ul>
 122  * <li> {@link #dateNow() dateNow()}
 123  * <li> {@link #dateNow(Clock) dateNow(clock)}
 124  * <li> {@link #dateNow(ZoneId) dateNow(zone)}
 125  * <li> {@link #date(int, int, int) date(yearProleptic, month, day)}
 126  * <li> {@link #date(Era, int, int, int) date(era, yearOfEra, month, day)}
 127  * <li> {@link #dateYearDay(int, int) dateYearDay(yearProleptic, dayOfYear)}
 128  * <li> {@link #dateYearDay(Era, int, int) dateYearDay(era, yearOfEra, dayOfYear)}
 129  * <li> {@link #date(TemporalAccessor) date(TemporalAccessor)}
 130  * </ul>
 131  *
 132  * <h3 id="addcalendars">Adding New Calendars</h3>
 133  * The set of available chronologies can be extended by applications.
 134  * Adding a new calendar system requires the writing of an implementation of
 135  * {@code Chronology}, {@code ChronoLocalDate} and {@code Era}.
 136  * The majority of the logic specific to the calendar system will be in the
 137  * {@code ChronoLocalDate} implementation.
 138  * The {@code Chronology} implementation acts as a factory.
 139  * <p>
 140  * To permit the discovery of additional chronologies, the {@link java.util.ServiceLoader ServiceLoader}
 141  * is used. A file must be added to the {@code META-INF/services} directory with the
 142  * name 'java.time.chrono.Chronology' listing the implementation classes.
 143  * See the ServiceLoader for more details on service loading.
 144  * For lookup by id or calendarType, the system provided calendars are found
 145  * first followed by application provided calendars.
 146  * <p>
 147  * Each chronology must define a chronology ID that is unique within the system.
 148  * If the chronology represents a calendar system defined by the
 149  * CLDR specification then the calendar type is the concatenation of the
 150  * CLDR type and, if applicable, the CLDR variant,
 151  *
 152  * @implSpec
 153  * This interface must be implemented with care to ensure other classes operate correctly.
 154  * All implementations that can be instantiated must be final, immutable and thread-safe.
 155  * Subclasses should be Serializable wherever possible.
 156  *
 157  * @since 1.8
 158  */
 159 public interface Chronology extends Comparable<Chronology> {
 160 
 161     /**
 162      * Obtains an instance of {@code Chronology} from a temporal object.
 163      * <p>
 164      * This obtains a chronology based on the specified temporal.
 165      * A {@code TemporalAccessor} represents an arbitrary set of date and time information,
 166      * which this factory converts to an instance of {@code Chronology}.
 167      * <p>
 168      * The conversion will obtain the chronology using {@link TemporalQueries#chronology()}.
 169      * If the specified temporal object does not have a chronology, {@link IsoChronology} is returned.
 170      * <p>
 171      * This method matches the signature of the functional interface {@link TemporalQuery}
 172      * allowing it to be used as a query via method reference, {@code Chronology::from}.
 173      *
 174      * @param temporal  the temporal to convert, not null
 175      * @return the chronology, not null
 176      * @throws DateTimeException if unable to convert to an {@code Chronology}
 177      */
 178     static Chronology from(TemporalAccessor temporal) {
 179         Objects.requireNonNull(temporal, "temporal");
 180         Chronology obj = temporal.query(TemporalQueries.chronology());
 181         return Objects.requireNonNullElse(obj, IsoChronology.INSTANCE);
 182     }
 183 
 184     //-----------------------------------------------------------------------
 185     /**
 186      * Obtains an instance of {@code Chronology} from a locale.
 187      * <p>
 188      * This returns a {@code Chronology} based on the specified locale,
 189      * typically returning {@code IsoChronology}. Other calendar systems
 190      * are only returned if they are explicitly selected within the locale.
 191      * <p>
 192      * The {@link Locale} class provide access to a range of information useful
 193      * for localizing an application. This includes the language and region,
 194      * such as "en-GB" for English as used in Great Britain.
 195      * <p>
 196      * The {@code Locale} class also supports an extension mechanism that
 197      * can be used to identify a calendar system. The mechanism is a form
 198      * of key-value pairs, where the calendar system has the key "ca".
 199      * For example, the locale "en-JP-u-ca-japanese" represents the English
 200      * language as used in Japan with the Japanese calendar system.
 201      * <p>
 202      * This method finds the desired calendar system by in a manner equivalent
 203      * to passing "ca" to {@link Locale#getUnicodeLocaleType(String)}.
 204      * If the "ca" key is not present, then {@code IsoChronology} is returned.
 205      * <p>
 206      * Note that the behavior of this method differs from the older
 207      * {@link java.util.Calendar#getInstance(Locale)} method.
 208      * If that method receives a locale of "th_TH" it will return {@code BuddhistCalendar}.
 209      * By contrast, this method will return {@code IsoChronology}.
 210      * Passing the locale "th-TH-u-ca-buddhist" into either method will
 211      * result in the Thai Buddhist calendar system and is therefore the
 212      * recommended approach going forward for Thai calendar system localization.
 213      * <p>
 214      * A similar, but simpler, situation occurs for the Japanese calendar system.
 215      * The locale "jp_JP_JP" has previously been used to access the calendar.
 216      * However, unlike the Thai locale, "ja_JP_JP" is automatically converted by
 217      * {@code Locale} to the modern and recommended form of "ja-JP-u-ca-japanese".
 218      * Thus, there is no difference in behavior between this method and
 219      * {@code Calendar#getInstance(Locale)}.
 220      *
 221      * @param locale  the locale to use to obtain the calendar system, not null
 222      * @return the calendar system associated with the locale, not null
 223      * @throws DateTimeException if the locale-specified calendar cannot be found
 224      */
 225     static Chronology ofLocale(Locale locale) {
 226         return AbstractChronology.ofLocale(locale);
 227     }
 228 
 229     //-----------------------------------------------------------------------
 230     /**
 231      * Obtains an instance of {@code Chronology} from a chronology ID or
 232      * calendar system type.
 233      * <p>
 234      * This returns a chronology based on either the ID or the type.
 235      * The {@link #getId() chronology ID} uniquely identifies the chronology.
 236      * The {@link #getCalendarType() calendar system type} is defined by the
 237      * CLDR specification.
 238      * <p>
 239      * The chronology may be a system chronology or a chronology
 240      * provided by the application via ServiceLoader configuration.
 241      * <p>
 242      * Since some calendars can be customized, the ID or type typically refers
 243      * to the default customization. For example, the Gregorian calendar can have multiple
 244      * cutover dates from the Julian, but the lookup only provides the default cutover date.
 245      *
 246      * @param id  the chronology ID or calendar system type, not null
 247      * @return the chronology with the identifier requested, not null
 248      * @throws DateTimeException if the chronology cannot be found
 249      */
 250     static Chronology of(String id) {
 251         return AbstractChronology.of(id);
 252     }
 253 
 254     /**
 255      * Returns the available chronologies.
 256      * <p>
 257      * Each returned {@code Chronology} is available for use in the system.
 258      * The set of chronologies includes the system chronologies and
 259      * any chronologies provided by the application via ServiceLoader
 260      * configuration.
 261      *
 262      * @return the independent, modifiable set of the available chronology IDs, not null
 263      */
 264     static Set<Chronology> getAvailableChronologies() {
 265         return AbstractChronology.getAvailableChronologies();
 266     }
 267 
 268     //-----------------------------------------------------------------------
 269     /**
 270      * Gets the ID of the chronology.
 271      * <p>
 272      * The ID uniquely identifies the {@code Chronology}.
 273      * It can be used to lookup the {@code Chronology} using {@link #of(String)}.
 274      *
 275      * @return the chronology ID, not null
 276      * @see #getCalendarType()
 277      */
 278     String getId();
 279 
 280     /**
 281      * Gets the calendar type of the calendar system.
 282      * <p>
 283      * The calendar type is an identifier defined by the CLDR and
 284      * <em>Unicode Locale Data Markup Language (LDML)</em> specifications
 285      * to uniquely identification a calendar.
 286      * The {@code getCalendarType} is the concatenation of the CLDR calendar type
 287      * and the variant, if applicable, is appended separated by "-".
 288      * The calendar type is used to lookup the {@code Chronology} using {@link #of(String)}.
 289      *
 290      * @return the calendar system type, null if the calendar is not defined by CLDR/LDML
 291      * @see #getId()
 292      */
 293     String getCalendarType();
 294 
 295     //-----------------------------------------------------------------------
 296     /**
 297      * Obtains a local date in this chronology from the era, year-of-era,
 298      * month-of-year and day-of-month fields.
 299      *
 300      * @implSpec
 301      * The default implementation combines the era and year-of-era into a proleptic
 302      * year before calling {@link #date(int, int, int)}.
 303      *
 304      * @param era  the era of the correct type for the chronology, not null
 305      * @param yearOfEra  the chronology year-of-era
 306      * @param month  the chronology month-of-year
 307      * @param dayOfMonth  the chronology day-of-month
 308      * @return the local date in this chronology, not null
 309      * @throws DateTimeException if unable to create the date
 310      * @throws ClassCastException if the {@code era} is not of the correct type for the chronology
 311      */
 312     default ChronoLocalDate date(Era era, int yearOfEra, int month, int dayOfMonth) {
 313         return date(prolepticYear(era, yearOfEra), month, dayOfMonth);
 314     }
 315 
 316     /**
 317      * Obtains a local date in this chronology from the proleptic-year,
 318      * month-of-year and day-of-month fields.
 319      *
 320      * @param prolepticYear  the chronology proleptic-year
 321      * @param month  the chronology month-of-year
 322      * @param dayOfMonth  the chronology day-of-month
 323      * @return the local date in this chronology, not null
 324      * @throws DateTimeException if unable to create the date
 325      */
 326     ChronoLocalDate date(int prolepticYear, int month, int dayOfMonth);
 327 
 328     /**
 329      * Obtains a local date in this chronology from the era, year-of-era and
 330      * day-of-year fields.
 331      *
 332      * @implSpec
 333      * The default implementation combines the era and year-of-era into a proleptic
 334      * year before calling {@link #dateYearDay(int, int)}.
 335      *
 336      * @param era  the era of the correct type for the chronology, not null
 337      * @param yearOfEra  the chronology year-of-era
 338      * @param dayOfYear  the chronology day-of-year
 339      * @return the local date in this chronology, not null
 340      * @throws DateTimeException if unable to create the date
 341      * @throws ClassCastException if the {@code era} is not of the correct type for the chronology
 342      */
 343     default ChronoLocalDate dateYearDay(Era era, int yearOfEra, int dayOfYear) {
 344         return dateYearDay(prolepticYear(era, yearOfEra), dayOfYear);
 345     }
 346 
 347     /**
 348      * Obtains a local date in this chronology from the proleptic-year and
 349      * day-of-year fields.
 350      *
 351      * @param prolepticYear  the chronology proleptic-year
 352      * @param dayOfYear  the chronology day-of-year
 353      * @return the local date in this chronology, not null
 354      * @throws DateTimeException if unable to create the date
 355      */
 356     ChronoLocalDate dateYearDay(int prolepticYear, int dayOfYear);
 357 
 358     /**
 359      * Obtains a local date in this chronology from the epoch-day.
 360      * <p>
 361      * The definition of {@link ChronoField#EPOCH_DAY EPOCH_DAY} is the same
 362      * for all calendar systems, thus it can be used for conversion.
 363      *
 364      * @param epochDay  the epoch day
 365      * @return the local date in this chronology, not null
 366      * @throws DateTimeException if unable to create the date
 367      */
 368     ChronoLocalDate dateEpochDay(long epochDay);
 369 
 370     //-----------------------------------------------------------------------
 371     /**
 372      * Obtains the current local date in this chronology from the system clock in the default time-zone.
 373      * <p>
 374      * This will query the {@link Clock#systemDefaultZone() system clock} in the default
 375      * time-zone to obtain the current date.
 376      * <p>
 377      * Using this method will prevent the ability to use an alternate clock for testing
 378      * because the clock is hard-coded.
 379      *
 380      * @implSpec
 381      * The default implementation invokes {@link #dateNow(Clock)}.
 382      *
 383      * @return the current local date using the system clock and default time-zone, not null
 384      * @throws DateTimeException if unable to create the date
 385      */
 386     default ChronoLocalDate dateNow() {
 387         return dateNow(Clock.systemDefaultZone());
 388     }
 389 
 390     /**
 391      * Obtains the current local date in this chronology from the system clock in the specified time-zone.
 392      * <p>
 393      * This will query the {@link Clock#system(ZoneId) system clock} to obtain the current date.
 394      * Specifying the time-zone avoids dependence on the default time-zone.
 395      * <p>
 396      * Using this method will prevent the ability to use an alternate clock for testing
 397      * because the clock is hard-coded.
 398      *
 399      * @implSpec
 400      * The default implementation invokes {@link #dateNow(Clock)}.
 401      *
 402      * @param zone  the zone ID to use, not null
 403      * @return the current local date using the system clock, not null
 404      * @throws DateTimeException if unable to create the date
 405      */
 406     default ChronoLocalDate dateNow(ZoneId zone) {
 407         return dateNow(Clock.system(zone));
 408     }
 409 
 410     /**
 411      * Obtains the current local date in this chronology from the specified clock.
 412      * <p>
 413      * This will query the specified clock to obtain the current date - today.
 414      * Using this method allows the use of an alternate clock for testing.
 415      * The alternate clock may be introduced using {@link Clock dependency injection}.
 416      *
 417      * @implSpec
 418      * The default implementation invokes {@link #date(TemporalAccessor)}.
 419      *
 420      * @param clock  the clock to use, not null
 421      * @return the current local date, not null
 422      * @throws DateTimeException if unable to create the date
 423      */
 424     default ChronoLocalDate dateNow(Clock clock) {
 425         Objects.requireNonNull(clock, "clock");
 426         return date(LocalDate.now(clock));
 427     }
 428 
 429     //-----------------------------------------------------------------------
 430     /**
 431      * Obtains a local date in this chronology from another temporal object.
 432      * <p>
 433      * This obtains a date in this chronology based on the specified temporal.
 434      * A {@code TemporalAccessor} represents an arbitrary set of date and time information,
 435      * which this factory converts to an instance of {@code ChronoLocalDate}.
 436      * <p>
 437      * The conversion typically uses the {@link ChronoField#EPOCH_DAY EPOCH_DAY}
 438      * field, which is standardized across calendar systems.
 439      * <p>
 440      * This method matches the signature of the functional interface {@link TemporalQuery}
 441      * allowing it to be used as a query via method reference, {@code aChronology::date}.
 442      *
 443      * @param temporal  the temporal object to convert, not null
 444      * @return the local date in this chronology, not null
 445      * @throws DateTimeException if unable to create the date
 446      * @see ChronoLocalDate#from(TemporalAccessor)
 447      */
 448     ChronoLocalDate date(TemporalAccessor temporal);
 449 
 450     /**
 451      * Obtains a local date-time in this chronology from another temporal object.
 452      * <p>
 453      * This obtains a date-time in this chronology based on the specified temporal.
 454      * A {@code TemporalAccessor} represents an arbitrary set of date and time information,
 455      * which this factory converts to an instance of {@code ChronoLocalDateTime}.
 456      * <p>
 457      * The conversion extracts and combines the {@code ChronoLocalDate} and the
 458      * {@code LocalTime} from the temporal object.
 459      * Implementations are permitted to perform optimizations such as accessing
 460      * those fields that are equivalent to the relevant objects.
 461      * The result uses this chronology.
 462      * <p>
 463      * This method matches the signature of the functional interface {@link TemporalQuery}
 464      * allowing it to be used as a query via method reference, {@code aChronology::localDateTime}.
 465      *
 466      * @param temporal  the temporal object to convert, not null
 467      * @return the local date-time in this chronology, not null
 468      * @throws DateTimeException if unable to create the date-time
 469      * @see ChronoLocalDateTime#from(TemporalAccessor)
 470      */
 471     default ChronoLocalDateTime<? extends ChronoLocalDate> localDateTime(TemporalAccessor temporal) {
 472         try {
 473             return date(temporal).atTime(LocalTime.from(temporal));
 474         } catch (DateTimeException ex) {
 475             throw new DateTimeException("Unable to obtain ChronoLocalDateTime from TemporalAccessor: " + temporal.getClass(), ex);
 476         }
 477     }
 478 
 479     /**
 480      * Obtains a {@code ChronoZonedDateTime} in this chronology from another temporal object.
 481      * <p>
 482      * This obtains a zoned date-time in this chronology based on the specified temporal.
 483      * A {@code TemporalAccessor} represents an arbitrary set of date and time information,
 484      * which this factory converts to an instance of {@code ChronoZonedDateTime}.
 485      * <p>
 486      * The conversion will first obtain a {@code ZoneId} from the temporal object,
 487      * falling back to a {@code ZoneOffset} if necessary. It will then try to obtain
 488      * an {@code Instant}, falling back to a {@code ChronoLocalDateTime} if necessary.
 489      * The result will be either the combination of {@code ZoneId} or {@code ZoneOffset}
 490      * with {@code Instant} or {@code ChronoLocalDateTime}.
 491      * Implementations are permitted to perform optimizations such as accessing
 492      * those fields that are equivalent to the relevant objects.
 493      * The result uses this chronology.
 494      * <p>
 495      * This method matches the signature of the functional interface {@link TemporalQuery}
 496      * allowing it to be used as a query via method reference, {@code aChronology::zonedDateTime}.
 497      *
 498      * @param temporal  the temporal object to convert, not null
 499      * @return the zoned date-time in this chronology, not null
 500      * @throws DateTimeException if unable to create the date-time
 501      * @see ChronoZonedDateTime#from(TemporalAccessor)
 502      */
 503     default ChronoZonedDateTime<? extends ChronoLocalDate> zonedDateTime(TemporalAccessor temporal) {
 504         try {
 505             ZoneId zone = ZoneId.from(temporal);
 506             try {
 507                 Instant instant = Instant.from(temporal);
 508                 return zonedDateTime(instant, zone);
 509 
 510             } catch (DateTimeException ex1) {
 511                 ChronoLocalDateTimeImpl<?> cldt = ChronoLocalDateTimeImpl.ensureValid(this, localDateTime(temporal));
 512                 return ChronoZonedDateTimeImpl.ofBest(cldt, zone, null);
 513             }
 514         } catch (DateTimeException ex) {
 515             throw new DateTimeException("Unable to obtain ChronoZonedDateTime from TemporalAccessor: " + temporal.getClass(), ex);
 516         }
 517     }
 518 
 519     /**
 520      * Obtains a {@code ChronoZonedDateTime} in this chronology from an {@code Instant}.
 521      * <p>
 522      * This obtains a zoned date-time with the same instant as that specified.
 523      *
 524      * @param instant  the instant to create the date-time from, not null
 525      * @param zone  the time-zone, not null
 526      * @return the zoned date-time, not null
 527      * @throws DateTimeException if the result exceeds the supported range
 528      */
 529     default ChronoZonedDateTime<? extends ChronoLocalDate> zonedDateTime(Instant instant, ZoneId zone) {
 530         return ChronoZonedDateTimeImpl.ofInstant(this, instant, zone);
 531     }
 532 
 533     //-----------------------------------------------------------------------
 534     /**
 535      * Checks if the specified year is a leap year.
 536      * <p>
 537      * A leap-year is a year of a longer length than normal.
 538      * The exact meaning is determined by the chronology according to the following constraints.
 539      * <ul>
 540      * <li>a leap-year must imply a year-length longer than a non leap-year.
 541      * <li>a chronology that does not support the concept of a year must return false.
 542      * <li>the correct result must be returned for all years within the
 543      *     valid range of years for the chronology.
 544      * </ul>
 545      * <p>
 546      * Outside the range of valid years an implementation is free to return
 547      * either a best guess or false.
 548      * An implementation must not throw an exception, even if the year is
 549      * outside the range of valid years.
 550      *
 551      * @param prolepticYear  the proleptic-year to check, not validated for range
 552      * @return true if the year is a leap year
 553      */
 554     boolean isLeapYear(long prolepticYear);
 555 
 556     /**
 557      * Calculates the proleptic-year given the era and year-of-era.
 558      * <p>
 559      * This combines the era and year-of-era into the single proleptic-year field.
 560      * <p>
 561      * If the chronology makes active use of eras, such as {@code JapaneseChronology}
 562      * then the year-of-era will be validated against the era.
 563      * For other chronologies, validation is optional.
 564      *
 565      * @param era  the era of the correct type for the chronology, not null
 566      * @param yearOfEra  the chronology year-of-era
 567      * @return the proleptic-year
 568      * @throws DateTimeException if unable to convert to a proleptic-year,
 569      *  such as if the year is invalid for the era
 570      * @throws ClassCastException if the {@code era} is not of the correct type for the chronology
 571      */
 572     int prolepticYear(Era era, int yearOfEra);
 573 
 574     /**
 575      * Creates the chronology era object from the numeric value.
 576      * <p>
 577      * The era is, conceptually, the largest division of the time-line.
 578      * Most calendar systems have a single epoch dividing the time-line into two eras.
 579      * However, some have multiple eras, such as one for the reign of each leader.
 580      * The exact meaning is determined by the chronology according to the following constraints.
 581      * <p>
 582      * The era in use at 1970-01-01 must have the value 1.
 583      * Later eras must have sequentially higher values.
 584      * Earlier eras must have sequentially lower values.
 585      * Each chronology must refer to an enum or similar singleton to provide the era values.
 586      * <p>
 587      * This method returns the singleton era of the correct type for the specified era value.
 588      *
 589      * @param eraValue  the era value
 590      * @return the calendar system era, not null
 591      * @throws DateTimeException if unable to create the era
 592      */
 593     Era eraOf(int eraValue);
 594 
 595     /**
 596      * Gets the list of eras for the chronology.
 597      * <p>
 598      * Most calendar systems have an era, within which the year has meaning.
 599      * If the calendar system does not support the concept of eras, an empty
 600      * list must be returned.
 601      *
 602      * @return the list of eras for the chronology, may be immutable, not null
 603      */
 604     List<Era> eras();
 605 
 606     //-----------------------------------------------------------------------
 607     /**
 608      * Gets the range of valid values for the specified field.
 609      * <p>
 610      * All fields can be expressed as a {@code long} integer.
 611      * This method returns an object that describes the valid range for that value.
 612      * <p>
 613      * Note that the result only describes the minimum and maximum valid values
 614      * and it is important not to read too much into them. For example, there
 615      * could be values within the range that are invalid for the field.
 616      * <p>
 617      * This method will return a result whether or not the chronology supports the field.
 618      *
 619      * @param field  the field to get the range for, not null
 620      * @return the range of valid values for the field, not null
 621      * @throws DateTimeException if the range for the field cannot be obtained
 622      */
 623     ValueRange range(ChronoField field);
 624 
 625     //-----------------------------------------------------------------------
 626     /**
 627      * Gets the textual representation of this chronology.
 628      * <p>
 629      * This returns the textual name used to identify the chronology,
 630      * suitable for presentation to the user.
 631      * The parameters control the style of the returned text and the locale.
 632      *
 633      * @implSpec
 634      * The default implementation behaves as though the formatter was used to
 635      * format the chronology textual name.
 636      *
 637      * @param style  the style of the text required, not null
 638      * @param locale  the locale to use, not null
 639      * @return the text value of the chronology, not null
 640      */
 641     default String getDisplayName(TextStyle style, Locale locale) {
 642         TemporalAccessor temporal = new TemporalAccessor() {
 643             @Override
 644             public boolean isSupported(TemporalField field) {
 645                 return false;
 646             }
 647             @Override
 648             public long getLong(TemporalField field) {
 649                 throw new UnsupportedTemporalTypeException("Unsupported field: " + field);
 650             }
 651             @SuppressWarnings("unchecked")
 652             @Override
 653             public <R> R query(TemporalQuery<R> query) {
 654                 if (query == TemporalQueries.chronology()) {
 655                     return (R) Chronology.this;
 656                 }
 657                 return TemporalAccessor.super.query(query);
 658             }
 659         };
 660         return new DateTimeFormatterBuilder().appendChronologyText(style).toFormatter(locale).format(temporal);
 661     }
 662 
 663     //-----------------------------------------------------------------------
 664     /**
 665      * Resolves parsed {@code ChronoField} values into a date during parsing.
 666      * <p>
 667      * Most {@code TemporalField} implementations are resolved using the
 668      * resolve method on the field. By contrast, the {@code ChronoField} class
 669      * defines fields that only have meaning relative to the chronology.
 670      * As such, {@code ChronoField} date fields are resolved here in the
 671      * context of a specific chronology.
 672      * <p>
 673      * The default implementation, which explains typical resolve behaviour,
 674      * is provided in {@link AbstractChronology}.
 675      *
 676      * @param fieldValues  the map of fields to values, which can be updated, not null
 677      * @param resolverStyle  the requested type of resolve, not null
 678      * @return the resolved date, null if insufficient information to create a date
 679      * @throws DateTimeException if the date cannot be resolved, typically
 680      *  because of a conflict in the input data
 681      */
 682     ChronoLocalDate resolveDate(Map<TemporalField, Long> fieldValues, ResolverStyle resolverStyle);
 683 
 684     //-----------------------------------------------------------------------
 685     /**
 686      * Obtains a period for this chronology based on years, months and days.
 687      * <p>
 688      * This returns a period tied to this chronology using the specified
 689      * years, months and days.  All supplied chronologies use periods
 690      * based on years, months and days, however the {@code ChronoPeriod} API
 691      * allows the period to be represented using other units.
 692      *
 693      * @implSpec
 694      * The default implementation returns an implementation class suitable
 695      * for most calendar systems. It is based solely on the three units.
 696      * Normalization, addition and subtraction derive the number of months
 697      * in a year from the {@link #range(ChronoField)}. If the number of
 698      * months within a year is fixed, then the calculation approach for
 699      * addition, subtraction and normalization is slightly different.
 700      * <p>
 701      * If implementing an unusual calendar system that is not based on
 702      * years, months and days, or where you want direct control, then
 703      * the {@code ChronoPeriod} interface must be directly implemented.
 704      * <p>
 705      * The returned period is immutable and thread-safe.
 706      *
 707      * @param years  the number of years, may be negative
 708      * @param months  the number of years, may be negative
 709      * @param days  the number of years, may be negative
 710      * @return the period in terms of this chronology, not null
 711      */
 712     default ChronoPeriod period(int years, int months, int days) {
 713         return new ChronoPeriodImpl(this, years, months, days);
 714     }
 715 
 716     //---------------------------------------------------------------------
 717 
 718     /**
 719      * Gets the number of seconds from the epoch of 1970-01-01T00:00:00Z.
 720      * <p>
 721      * The number of seconds is calculated using the proleptic-year,
 722      * month, day-of-month, hour, minute, second, and zoneOffset.
 723      *
 724      * @param prolepticYear the chronology proleptic-year
 725      * @param month the chronology month-of-year
 726      * @param dayOfMonth the chronology day-of-month
 727      * @param hour the hour-of-day, from 0 to 23
 728      * @param minute the minute-of-hour, from 0 to 59
 729      * @param second the second-of-minute, from 0 to 59
 730      * @param zoneOffset the zone offset, not null
 731      * @return the number of seconds relative to 1970-01-01T00:00:00Z, may be negative
 732      * @since 9
 733      */
 734      public default long epochSecond(int prolepticYear, int month, int dayOfMonth,
 735                                      int hour, int minute, int second, ZoneOffset zoneOffset) {
 736         Objects.requireNonNull(zoneOffset, "zoneOffset");
 737         long daysInSec = Math.multiplyExact(date(prolepticYear, month, dayOfMonth).toEpochDay(), 86400);
 738         long timeinSec = (hour * 60 + minute) * 60 + second;
 739         return Math.addExact(daysInSec, timeinSec - zoneOffset.getTotalSeconds());
 740     }
 741 
 742     /**
 743      * Gets the number of seconds from the epoch of 1970-01-01T00:00:00Z.
 744      * <p>
 745      * The number of seconds is calculated using the era, year-of-era,
 746      * month, day-of-month, hour, minute, second, and zoneOffset.
 747      *
 748      * @param era  the era of the correct type for the chronology, not null
 749      * @param yearOfEra the chronology year-of-era
 750      * @param month the chronology month-of-year
 751      * @param dayOfMonth the chronology day-of-month
 752      * @param hour the hour-of-day, from 0 to 23
 753      * @param minute the minute-of-hour, from 0 to 59
 754      * @param second the second-of-minute, from 0 to 59
 755      * @param zoneOffset the zone offset, not null
 756      * @return the number of seconds relative to 1970-01-01T00:00:00Z, may be negative
 757      * @since 9
 758      */
 759      public default long epochSecond(Era era, int yearOfEra, int month, int dayOfMonth,
 760                                      int hour, int minute, int second, ZoneOffset zoneOffset) {
 761         Objects.requireNonNull(era, "era");
 762         return epochSecond(prolepticYear(era, yearOfEra), month, dayOfMonth, hour, minute, second, zoneOffset);
 763     }
 764     //-----------------------------------------------------------------------
 765     /**
 766      * Compares this chronology to another chronology.
 767      * <p>
 768      * The comparison order first by the chronology ID string, then by any
 769      * additional information specific to the subclass.
 770      * It is "consistent with equals", as defined by {@link Comparable}.
 771      *
 772      * @param other  the other chronology to compare to, not null
 773      * @return the comparator value, negative if less, positive if greater
 774      */
 775     @Override
 776     int compareTo(Chronology other);
 777 
 778     /**
 779      * Checks if this chronology is equal to another chronology.
 780      * <p>
 781      * The comparison is based on the entire state of the object.
 782      *
 783      * @param obj  the object to check, null returns false
 784      * @return true if this is equal to the other chronology
 785      */
 786     @Override
 787     boolean equals(Object obj);
 788 
 789     /**
 790      * A hash code for this chronology.
 791      * <p>
 792      * The hash code should be based on the entire state of the object.
 793      *
 794      * @return a suitable hash code
 795      */
 796     @Override
 797     int hashCode();
 798 
 799     //-----------------------------------------------------------------------
 800     /**
 801      * Outputs this chronology as a {@code String}.
 802      * <p>
 803      * The format should include the entire state of the object.
 804      *
 805      * @return a string representation of this chronology, not null
 806      */
 807     @Override
 808     String toString();
 809 
 810 }