1 /*
   2  * Copyright (c) 2012, 2013, 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  * Copyright (c) 2012, Stephen Colebourne & Michael Nascimento Santos
  28  *
  29  * All rights reserved.
  30  *
  31  * Redistribution and use in source and binary forms, with or without
  32  * modification, are permitted provided that the following conditions are met:
  33  *
  34  *  * Redistributions of source code must retain the above copyright notice,
  35  *    this list of conditions and the following disclaimer.
  36  *
  37  *  * Redistributions in binary form must reproduce the above copyright notice,
  38  *    this list of conditions and the following disclaimer in the documentation
  39  *    and/or other materials provided with the distribution.
  40  *
  41  *  * Neither the name of JSR-310 nor the names of its contributors
  42  *    may be used to endorse or promote products derived from this software
  43  *    without specific prior written permission.
  44  *
  45  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  46  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  47  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  48  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  49  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  50  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  51  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  52  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  53  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  54  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  55  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  56  */
  57 package java.time.temporal;
  58 
  59 import static java.time.temporal.ChronoUnit.DAYS;
  60 import static java.time.temporal.ChronoUnit.ERAS;
  61 import static java.time.temporal.ChronoUnit.FOREVER;
  62 import static java.time.temporal.ChronoUnit.HALF_DAYS;
  63 import static java.time.temporal.ChronoUnit.HOURS;
  64 import static java.time.temporal.ChronoUnit.MICROS;
  65 import static java.time.temporal.ChronoUnit.MILLIS;
  66 import static java.time.temporal.ChronoUnit.MINUTES;
  67 import static java.time.temporal.ChronoUnit.MONTHS;
  68 import static java.time.temporal.ChronoUnit.NANOS;
  69 import static java.time.temporal.ChronoUnit.SECONDS;
  70 import static java.time.temporal.ChronoUnit.WEEKS;
  71 import static java.time.temporal.ChronoUnit.YEARS;
  72 
  73 import java.time.DayOfWeek;
  74 import java.time.Instant;
  75 import java.time.Year;
  76 import java.time.ZoneOffset;
  77 import java.time.chrono.ChronoLocalDate;
  78 import java.time.chrono.Chronology;
  79 import java.util.Locale;
  80 import java.util.Objects;
  81 import java.util.ResourceBundle;
  82 import sun.util.locale.provider.LocaleProviderAdapter;
  83 import sun.util.locale.provider.LocaleResources;
  84 
  85 /**
  86  * A standard set of fields.
  87  * <p>
  88  * This set of fields provide field-based access to manipulate a date, time or date-time.
  89  * The standard set of fields can be extended by implementing {@link TemporalField}.
  90  * <p>
  91  * These fields are intended to be applicable in multiple calendar systems.
  92  * For example, most non-ISO calendar systems define dates as a year, month and day,
  93  * just with slightly different rules.
  94  * The documentation of each field explains how it operates.
  95  *
  96  * <h3>Specification for implementors</h3>
  97  * This is a final, immutable and thread-safe enum.
  98  *
  99  * @since 1.8
 100  */
 101 public enum ChronoField implements TemporalField {
 102 
 103     /**
 104      * The nano-of-second.
 105      * <p>
 106      * This counts the nanosecond within the second, from 0 to 999,999,999.
 107      * This field has the same meaning for all calendar systems.
 108      * <p>
 109      * This field is used to represent the nano-of-second handling any fraction of the second.
 110      * Implementations of {@code TemporalAccessor} should provide a value for this field if
 111      * they can return a value for {@link #SECOND_OF_MINUTE}, {@link #SECOND_OF_DAY} or
 112      * {@link #INSTANT_SECONDS} filling unknown precision with zero.
 113      * <p>
 114      * When this field is used for setting a value, it should set as much precision as the
 115      * object stores, using integer division to remove excess precision.
 116      * For example, if the {@code TemporalAccessor} stores time to millisecond precision,
 117      * then the nano-of-second must be divided by 1,000,000 before replacing the milli-of-second.
 118      */
 119     NANO_OF_SECOND("NanoOfSecond", NANOS, SECONDS, ValueRange.of(0, 999_999_999)),
 120     /**
 121      * The nano-of-day.
 122      * <p>
 123      * This counts the nanosecond within the day, from 0 to (24 * 60 * 60 * 1,000,000,000) - 1.
 124      * This field has the same meaning for all calendar systems.
 125      * <p>
 126      * This field is used to represent the nano-of-day handling any fraction of the second.
 127      * Implementations of {@code TemporalAccessor} should provide a value for this field if
 128      * they can return a value for {@link #SECOND_OF_DAY} filling unknown precision with zero.
 129      */
 130     NANO_OF_DAY("NanoOfDay", NANOS, DAYS, ValueRange.of(0, 86400L * 1000_000_000L - 1)),
 131     /**
 132      * The micro-of-second.
 133      * <p>
 134      * This counts the microsecond within the second, from 0 to 999,999.
 135      * This field has the same meaning for all calendar systems.
 136      * <p>
 137      * This field is used to represent the micro-of-second handling any fraction of the second.
 138      * Implementations of {@code TemporalAccessor} should provide a value for this field if
 139      * they can return a value for {@link #SECOND_OF_MINUTE}, {@link #SECOND_OF_DAY} or
 140      * {@link #INSTANT_SECONDS} filling unknown precision with zero.
 141      * <p>
 142      * When this field is used for setting a value, it should behave in the same way as
 143      * setting {@link #NANO_OF_SECOND} with the value multiplied by 1,000.
 144      */
 145     MICRO_OF_SECOND("MicroOfSecond", MICROS, SECONDS, ValueRange.of(0, 999_999)),
 146     /**
 147      * The micro-of-day.
 148      * <p>
 149      * This counts the microsecond within the day, from 0 to (24 * 60 * 60 * 1,000,000) - 1.
 150      * This field has the same meaning for all calendar systems.
 151      * <p>
 152      * This field is used to represent the micro-of-day handling any fraction of the second.
 153      * Implementations of {@code TemporalAccessor} should provide a value for this field if
 154      * they can return a value for {@link #SECOND_OF_DAY} filling unknown precision with zero.
 155      * <p>
 156      * When this field is used for setting a value, it should behave in the same way as
 157      * setting {@link #NANO_OF_DAY} with the value multiplied by 1,000.
 158      */
 159     MICRO_OF_DAY("MicroOfDay", MICROS, DAYS, ValueRange.of(0, 86400L * 1000_000L - 1)),
 160     /**
 161      * The milli-of-second.
 162      * <p>
 163      * This counts the millisecond within the second, from 0 to 999.
 164      * This field has the same meaning for all calendar systems.
 165      * <p>
 166      * This field is used to represent the milli-of-second handling any fraction of the second.
 167      * Implementations of {@code TemporalAccessor} should provide a value for this field if
 168      * they can return a value for {@link #SECOND_OF_MINUTE}, {@link #SECOND_OF_DAY} or
 169      * {@link #INSTANT_SECONDS} filling unknown precision with zero.
 170      * <p>
 171      * When this field is used for setting a value, it should behave in the same way as
 172      * setting {@link #NANO_OF_SECOND} with the value multiplied by 1,000,000.
 173      */
 174     MILLI_OF_SECOND("MilliOfSecond", MILLIS, SECONDS, ValueRange.of(0, 999)),
 175     /**
 176      * The milli-of-day.
 177      * <p>
 178      * This counts the millisecond within the day, from 0 to (24 * 60 * 60 * 1,000) - 1.
 179      * This field has the same meaning for all calendar systems.
 180      * <p>
 181      * This field is used to represent the milli-of-day handling any fraction of the second.
 182      * Implementations of {@code TemporalAccessor} should provide a value for this field if
 183      * they can return a value for {@link #SECOND_OF_DAY} filling unknown precision with zero.
 184      * <p>
 185      * When this field is used for setting a value, it should behave in the same way as
 186      * setting {@link #NANO_OF_DAY} with the value multiplied by 1,000,000.
 187      */
 188     MILLI_OF_DAY("MilliOfDay", MILLIS, DAYS, ValueRange.of(0, 86400L * 1000L - 1)),
 189     /**
 190      * The second-of-minute.
 191      * <p>
 192      * This counts the second within the minute, from 0 to 59.
 193      * This field has the same meaning for all calendar systems.
 194      */
 195     SECOND_OF_MINUTE("SecondOfMinute", SECONDS, MINUTES, ValueRange.of(0, 59), "second"),
 196     /**
 197      * The second-of-day.
 198      * <p>
 199      * This counts the second within the day, from 0 to (24 * 60 * 60) - 1.
 200      * This field has the same meaning for all calendar systems.
 201      */
 202     SECOND_OF_DAY("SecondOfDay", SECONDS, DAYS, ValueRange.of(0, 86400L - 1)),
 203     /**
 204      * The minute-of-hour.
 205      * <p>
 206      * This counts the minute within the hour, from 0 to 59.
 207      * This field has the same meaning for all calendar systems.
 208      */
 209     MINUTE_OF_HOUR("MinuteOfHour", MINUTES, HOURS, ValueRange.of(0, 59), "minute"),
 210     /**
 211      * The minute-of-day.
 212      * <p>
 213      * This counts the minute within the day, from 0 to (24 * 60) - 1.
 214      * This field has the same meaning for all calendar systems.
 215      */
 216     MINUTE_OF_DAY("MinuteOfDay", MINUTES, DAYS, ValueRange.of(0, (24 * 60) - 1)),
 217     /**
 218      * The hour-of-am-pm.
 219      * <p>
 220      * This counts the hour within the AM/PM, from 0 to 11.
 221      * This is the hour that would be observed on a standard 12-hour digital clock.
 222      * This field has the same meaning for all calendar systems.
 223      */
 224     HOUR_OF_AMPM("HourOfAmPm", HOURS, HALF_DAYS, ValueRange.of(0, 11)),
 225     /**
 226      * The clock-hour-of-am-pm.
 227      * <p>
 228      * This counts the hour within the AM/PM, from 1 to 12.
 229      * This is the hour that would be observed on a standard 12-hour analog wall clock.
 230      * This field has the same meaning for all calendar systems.
 231      */
 232     CLOCK_HOUR_OF_AMPM("ClockHourOfAmPm", HOURS, HALF_DAYS, ValueRange.of(1, 12)),
 233     /**
 234      * The hour-of-day.
 235      * <p>
 236      * This counts the hour within the day, from 0 to 23.
 237      * This is the hour that would be observed on a standard 24-hour digital clock.
 238      * This field has the same meaning for all calendar systems.
 239      */
 240     HOUR_OF_DAY("HourOfDay", HOURS, DAYS, ValueRange.of(0, 23), "hour"),
 241     /**
 242      * The clock-hour-of-day.
 243      * <p>
 244      * This counts the hour within the AM/PM, from 1 to 24.
 245      * This is the hour that would be observed on a 24-hour analog wall clock.
 246      * This field has the same meaning for all calendar systems.
 247      */
 248     CLOCK_HOUR_OF_DAY("ClockHourOfDay", HOURS, DAYS, ValueRange.of(1, 24)),
 249     /**
 250      * The am-pm-of-day.
 251      * <p>
 252      * This counts the AM/PM within the day, from 0 (AM) to 1 (PM).
 253      * This field has the same meaning for all calendar systems.
 254      */
 255     AMPM_OF_DAY("AmPmOfDay", HALF_DAYS, DAYS, ValueRange.of(0, 1), "dayperiod"),
 256     /**
 257      * The day-of-week, such as Tuesday.
 258      * <p>
 259      * This represents the standard concept of the day of the week.
 260      * In the default ISO calendar system, this has values from Monday (1) to Sunday (7).
 261      * The {@link DayOfWeek} class can be used to interpret the result.
 262      * <p>
 263      * Most non-ISO calendar systems also define a seven day week that aligns with ISO.
 264      * Those calendar systems must also use the same numbering system, from Monday (1) to
 265      * Sunday (7), which allows {@code DayOfWeek} to be used.
 266      * <p>
 267      * Calendar systems that do not have a standard seven day week should implement this field
 268      * if they have a similar concept of named or numbered days within a period similar
 269      * to a week. It is recommended that the numbering starts from 1.
 270      */
 271     DAY_OF_WEEK("DayOfWeek", DAYS, WEEKS, ValueRange.of(1, 7), "weekday"),
 272     /**
 273      * The aligned day-of-week within a month.
 274      * <p>
 275      * This represents concept of the count of days within the period of a week
 276      * where the weeks are aligned to the start of the month.
 277      * This field is typically used with {@link #ALIGNED_WEEK_OF_MONTH}.
 278      * <p>
 279      * For example, in a calendar systems with a seven day week, the first aligned-week-of-month
 280      * starts on day-of-month 1, the second aligned-week starts on day-of-month 8, and so on.
 281      * Within each of these aligned-weeks, the days are numbered from 1 to 7 and returned
 282      * as the value of this field.
 283      * As such, day-of-month 1 to 7 will have aligned-day-of-week values from 1 to 7.
 284      * And day-of-month 8 to 14 will repeat this with aligned-day-of-week values from 1 to 7.
 285      * <p>
 286      * Calendar systems that do not have a seven day week should typically implement this
 287      * field in the same way, but using the alternate week length.
 288      */
 289     ALIGNED_DAY_OF_WEEK_IN_MONTH("AlignedDayOfWeekInMonth", DAYS, WEEKS, ValueRange.of(1, 7)),
 290     /**
 291      * The aligned day-of-week within a year.
 292      * <p>
 293      * This represents concept of the count of days within the period of a week
 294      * where the weeks are aligned to the start of the year.
 295      * This field is typically used with {@link #ALIGNED_WEEK_OF_YEAR}.
 296      * <p>
 297      * For example, in a calendar systems with a seven day week, the first aligned-week-of-year
 298      * starts on day-of-year 1, the second aligned-week starts on day-of-year 8, and so on.
 299      * Within each of these aligned-weeks, the days are numbered from 1 to 7 and returned
 300      * as the value of this field.
 301      * As such, day-of-year 1 to 7 will have aligned-day-of-week values from 1 to 7.
 302      * And day-of-year 8 to 14 will repeat this with aligned-day-of-week values from 1 to 7.
 303      * <p>
 304      * Calendar systems that do not have a seven day week should typically implement this
 305      * field in the same way, but using the alternate week length.
 306      */
 307     ALIGNED_DAY_OF_WEEK_IN_YEAR("AlignedDayOfWeekInYear", DAYS, WEEKS, ValueRange.of(1, 7)),
 308     /**
 309      * The day-of-month.
 310      * <p>
 311      * This represents the concept of the day within the month.
 312      * In the default ISO calendar system, this has values from 1 to 31 in most months.
 313      * April, June, September, November have days from 1 to 30, while February has days
 314      * from 1 to 28, or 29 in a leap year.
 315      * <p>
 316      * Non-ISO calendar systems should implement this field using the most recognized
 317      * day-of-month values for users of the calendar system.
 318      * Normally, this is a count of days from 1 to the length of the month.
 319      */
 320     DAY_OF_MONTH("DayOfMonth", DAYS, MONTHS, ValueRange.of(1, 28, 31), "day"),
 321     /**
 322      * The day-of-year.
 323      * <p>
 324      * This represents the concept of the day within the year.
 325      * In the default ISO calendar system, this has values from 1 to 365 in standard
 326      * years and 1 to 366 in leap years.
 327      * <p>
 328      * Non-ISO calendar systems should implement this field using the most recognized
 329      * day-of-year values for users of the calendar system.
 330      * Normally, this is a count of days from 1 to the length of the year.
 331      */
 332     DAY_OF_YEAR("DayOfYear", DAYS, YEARS, ValueRange.of(1, 365, 366)),
 333     /**
 334      * The epoch-day, based on the Java epoch of 1970-01-01 (ISO).
 335      * <p>
 336      * This field is the sequential count of days where 1970-01-01 (ISO) is zero.
 337      * Note that this uses the <i>local</i> time-line, ignoring offset and time-zone.
 338      * <p>
 339      * This field is strictly defined to have the same meaning in all calendar systems.
 340      * This is necessary to ensure interoperation between calendars.
 341      */
 342     EPOCH_DAY("EpochDay", DAYS, FOREVER, ValueRange.of((long) (Year.MIN_VALUE * 365.25), (long) (Year.MAX_VALUE * 365.25))),
 343     /**
 344      * The aligned week within a month.
 345      * <p>
 346      * This represents concept of the count of weeks within the period of a month
 347      * where the weeks are aligned to the start of the month.
 348      * This field is typically used with {@link #ALIGNED_DAY_OF_WEEK_IN_MONTH}.
 349      * <p>
 350      * For example, in a calendar systems with a seven day week, the first aligned-week-of-month
 351      * starts on day-of-month 1, the second aligned-week starts on day-of-month 8, and so on.
 352      * Thus, day-of-month values 1 to 7 are in aligned-week 1, while day-of-month values
 353      * 8 to 14 are in aligned-week 2, and so on.
 354      * <p>
 355      * Calendar systems that do not have a seven day week should typically implement this
 356      * field in the same way, but using the alternate week length.
 357      */
 358     ALIGNED_WEEK_OF_MONTH("AlignedWeekOfMonth", WEEKS, MONTHS, ValueRange.of(1, 4, 5)),
 359     /**
 360      * The aligned week within a year.
 361      * <p>
 362      * This represents concept of the count of weeks within the period of a year
 363      * where the weeks are aligned to the start of the year.
 364      * This field is typically used with {@link #ALIGNED_DAY_OF_WEEK_IN_YEAR}.
 365      * <p>
 366      * For example, in a calendar systems with a seven day week, the first aligned-week-of-year
 367      * starts on day-of-year 1, the second aligned-week starts on day-of-year 8, and so on.
 368      * Thus, day-of-year values 1 to 7 are in aligned-week 1, while day-of-year values
 369      * 8 to 14 are in aligned-week 2, and so on.
 370      * <p>
 371      * Calendar systems that do not have a seven day week should typically implement this
 372      * field in the same way, but using the alternate week length.
 373      */
 374     ALIGNED_WEEK_OF_YEAR("AlignedWeekOfYear", WEEKS, YEARS, ValueRange.of(1, 53)),
 375     /**
 376      * The month-of-year, such as March.
 377      * <p>
 378      * This represents the concept of the month within the year.
 379      * In the default ISO calendar system, this has values from January (1) to December (12).
 380      * <p>
 381      * Non-ISO calendar systems should implement this field using the most recognized
 382      * month-of-year values for users of the calendar system.
 383      * Normally, this is a count of months starting from 1.
 384      */
 385     MONTH_OF_YEAR("MonthOfYear", MONTHS, YEARS, ValueRange.of(1, 12), "month"),
 386     /**
 387      * The proleptic-month based, counting months sequentially from year 0.
 388      * <p>
 389      * This field is the sequential count of months where the first month
 390      * in proleptic-year zero has the value zero.
 391      * Later months have increasingly larger values.
 392      * Earlier months have increasingly small values.
 393      * There are no gaps or breaks in the sequence of months.
 394      * Note that this uses the <i>local</i> time-line, ignoring offset and time-zone.
 395      * <p>
 396      * In the default ISO calendar system, June 2012 would have the value
 397      * {@code (2012 * 12 + 6 - 1)}. This field is primarily for internal use.
 398      * <p>
 399      * Non-ISO calendar systems must implement this field as per the definition above.
 400      * It is just a simple zero-based count of elapsed months from the start of proleptic-year 0.
 401      * All calendar systems with a full proleptic-year definition will have a year zero.
 402      * If the calendar system has a minimum year that excludes year zero, then one must
 403      * be extrapolated in order for this method to be defined.
 404      */
 405     PROLEPTIC_MONTH("ProlepticMonth", MONTHS, FOREVER, ValueRange.of(Year.MIN_VALUE * 12L, Year.MAX_VALUE * 12L + 11)),
 406     /**
 407      * The year within the era.
 408      * <p>
 409      * This represents the concept of the year within the era.
 410      * This field is typically used with {@link #ERA}.
 411      * <p>
 412      * The standard mental model for a date is based on three concepts - year, month and day.
 413      * These map onto the {@code YEAR}, {@code MONTH_OF_YEAR} and {@code DAY_OF_MONTH} fields.
 414      * Note that there is no reference to eras.
 415      * The full model for a date requires four concepts - era, year, month and day. These map onto
 416      * the {@code ERA}, {@code YEAR_OF_ERA}, {@code MONTH_OF_YEAR} and {@code DAY_OF_MONTH} fields.
 417      * Whether this field or {@code YEAR} is used depends on which mental model is being used.
 418      * See {@link ChronoLocalDate} for more discussion on this topic.
 419      * <p>
 420      * In the default ISO calendar system, there are two eras defined, 'BCE' and 'CE'.
 421      * The era 'CE' is the one currently in use and year-of-era runs from 1 to the maximum value.
 422      * The era 'BCE' is the previous era, and the year-of-era runs backwards.
 423      * <p>
 424      * For example, subtracting a year each time yield the following:<br>
 425      * - year-proleptic 2  = 'CE' year-of-era 2<br>
 426      * - year-proleptic 1  = 'CE' year-of-era 1<br>
 427      * - year-proleptic 0  = 'BCE' year-of-era 1<br>
 428      * - year-proleptic -1 = 'BCE' year-of-era 2<br>
 429      * <p>
 430      * Note that the ISO-8601 standard does not actually define eras.
 431      * Note also that the ISO eras do not align with the well-known AD/BC eras due to the
 432      * change between the Julian and Gregorian calendar systems.
 433      * <p>
 434      * Non-ISO calendar systems should implement this field using the most recognized
 435      * year-of-era value for users of the calendar system.
 436      * Since most calendar systems have only two eras, the year-of-era numbering approach
 437      * will typically be the same as that used by the ISO calendar system.
 438      * The year-of-era value should typically always be positive, however this is not required.
 439      */
 440     YEAR_OF_ERA("YearOfEra", YEARS, FOREVER, ValueRange.of(1, Year.MAX_VALUE, Year.MAX_VALUE + 1)),
 441     /**
 442      * The proleptic year, such as 2012.
 443      * <p>
 444      * This represents the concept of the year, counting sequentially and using negative numbers.
 445      * The proleptic year is not interpreted in terms of the era.
 446      * See {@link #YEAR_OF_ERA} for an example showing the mapping from proleptic year to year-of-era.
 447      * <p>
 448      * The standard mental model for a date is based on three concepts - year, month and day.
 449      * These map onto the {@code YEAR}, {@code MONTH_OF_YEAR} and {@code DAY_OF_MONTH} fields.
 450      * Note that there is no reference to eras.
 451      * The full model for a date requires four concepts - era, year, month and day. These map onto
 452      * the {@code ERA}, {@code YEAR_OF_ERA}, {@code MONTH_OF_YEAR} and {@code DAY_OF_MONTH} fields.
 453      * Whether this field or {@code YEAR_OF_ERA} is used depends on which mental model is being used.
 454      * See {@link ChronoLocalDate} for more discussion on this topic.
 455      * <p>
 456      * Non-ISO calendar systems should implement this field as follows.
 457      * If the calendar system has only two eras, before and after a fixed date, then the
 458      * proleptic-year value must be the same as the year-of-era value for the later era,
 459      * and increasingly negative for the earlier era.
 460      * If the calendar system has more than two eras, then the proleptic-year value may be
 461      * defined with any appropriate value, although defining it to be the same as ISO may be
 462      * the best option.
 463      */
 464     YEAR("Year", YEARS, FOREVER, ValueRange.of(Year.MIN_VALUE, Year.MAX_VALUE), "year"),
 465     /**
 466      * The era.
 467      * <p>
 468      * This represents the concept of the era, which is the largest division of the time-line.
 469      * This field is typically used with {@link #YEAR_OF_ERA}.
 470      * <p>
 471      * In the default ISO calendar system, there are two eras defined, 'BCE' and 'CE'.
 472      * The era 'CE' is the one currently in use and year-of-era runs from 1 to the maximum value.
 473      * The era 'BCE' is the previous era, and the year-of-era runs backwards.
 474      * See {@link #YEAR_OF_ERA} for a full example.
 475      * <p>
 476      * Non-ISO calendar systems should implement this field to define eras.
 477      * The value of the era that was active on 1970-01-01 (ISO) must be assigned the value 1.
 478      * Earlier eras must have sequentially smaller values.
 479      * Later eras must have sequentially larger values,
 480      */
 481     ERA("Era", ERAS, FOREVER, ValueRange.of(0, 1), "era"),
 482     /**
 483      * The instant epoch-seconds.
 484      * <p>
 485      * This represents the concept of the sequential count of seconds where
 486      * 1970-01-01T00:00Z (ISO) is zero.
 487      * This field may be used with {@link #NANO_OF_DAY} to represent the fraction of the day.
 488      * <p>
 489      * An {@link Instant} represents an instantaneous point on the time-line.
 490      * On their own they have no elements which allow a local date-time to be obtained.
 491      * Only when paired with an offset or time-zone can the local date or time be found.
 492      * This field allows the seconds part of the instant to be queried.
 493      * <p>
 494      * This field is strictly defined to have the same meaning in all calendar systems.
 495      * This is necessary to ensure interoperation between calendars.
 496      */
 497     INSTANT_SECONDS("InstantSeconds", SECONDS, FOREVER, ValueRange.of(Long.MIN_VALUE, Long.MAX_VALUE)),
 498     /**
 499      * The offset from UTC/Greenwich.
 500      * <p>
 501      * This represents the concept of the offset in seconds of local time from UTC/Greenwich.
 502      * <p>
 503      * A {@link ZoneOffset} represents the period of time that local time differs from UTC/Greenwich.
 504      * This is usually a fixed number of hours and minutes.
 505      * It is equivalent to the {@link ZoneOffset#getTotalSeconds() total amount} of the offset in seconds.
 506      * For example, during the winter Paris has an offset of {@code +01:00}, which is 3600 seconds.
 507      * <p>
 508      * This field is strictly defined to have the same meaning in all calendar systems.
 509      * This is necessary to ensure interoperation between calendars.
 510      */
 511     OFFSET_SECONDS("OffsetSeconds", SECONDS, FOREVER, ValueRange.of(-18 * 3600, 18 * 3600));
 512 
 513     private final String name;
 514     private final TemporalUnit baseUnit;
 515     private final TemporalUnit rangeUnit;
 516     private final ValueRange range;
 517     private final String displayNameKey;
 518 
 519     private ChronoField(String name, TemporalUnit baseUnit, TemporalUnit rangeUnit, ValueRange range) {
 520         this.name = name;
 521         this.baseUnit = baseUnit;
 522         this.rangeUnit = rangeUnit;
 523         this.range = range;
 524         this.displayNameKey = null;
 525     }
 526 
 527     private ChronoField(String name, TemporalUnit baseUnit, TemporalUnit rangeUnit,
 528             ValueRange range, String displayNameKey) {
 529         this.name = name;
 530         this.baseUnit = baseUnit;
 531         this.rangeUnit = rangeUnit;
 532         this.range = range;
 533         this.displayNameKey = displayNameKey;
 534     }
 535 
 536     //-----------------------------------------------------------------------
 537     @Override
 538     public String getName() {
 539         return name;
 540     }
 541 
 542     @Override
 543     public String getDisplayName(Locale locale) {
 544         Objects.requireNonNull(locale, "locale");
 545         if (displayNameKey == null) {
 546             return getName();
 547         }
 548 
 549         LocaleResources lr = LocaleProviderAdapter.getResourceBundleBased()
 550                                     .getLocaleResources(locale);
 551         ResourceBundle rb = lr.getJavaTimeFormatData();
 552         String key = "field." + displayNameKey;
 553         return rb.containsKey(key) ? rb.getString(key) : getName();
 554     }
 555 
 556     @Override
 557     public TemporalUnit getBaseUnit() {
 558         return baseUnit;
 559     }
 560 
 561     @Override
 562     public TemporalUnit getRangeUnit() {
 563         return rangeUnit;
 564     }
 565 
 566     /**
 567      * Gets the range of valid values for the field.
 568      * <p>
 569      * All fields can be expressed as a {@code long} integer.
 570      * This method returns an object that describes the valid range for that value.
 571      * <p>
 572      * This method returns the range of the field in the ISO-8601 calendar system.
 573      * This range may be incorrect for other calendar systems.
 574      * Use {@link Chronology#range(ChronoField)} to access the correct range
 575      * for a different calendar system.
 576      * <p>
 577      * Note that the result only describes the minimum and maximum valid values
 578      * and it is important not to read too much into them. For example, there
 579      * could be values within the range that are invalid for the field.
 580      *
 581      * @return the range of valid values for the field, not null
 582      */
 583     @Override
 584     public ValueRange range() {
 585         return range;
 586     }
 587 
 588     //-----------------------------------------------------------------------
 589     /**
 590      * Checks if this field represents a component of a date.
 591      * <p>
 592      * Fields from day-of-week to era are date-based.
 593      *
 594      * @return true if it is a component of a date
 595      */
 596     @Override
 597     public boolean isDateBased() {
 598         return ordinal() >= DAY_OF_WEEK.ordinal() && ordinal() <= ERA.ordinal();
 599     }
 600 
 601     /**
 602      * Checks if this field represents a component of a time.
 603      * <p>
 604      * Fields from nano-of-second to am-pm-of-day are time-based.
 605      *
 606      * @return true if it is a component of a time
 607      */
 608     @Override
 609     public boolean isTimeBased() {
 610         return ordinal() < DAY_OF_WEEK.ordinal();
 611     }
 612 
 613     //-----------------------------------------------------------------------
 614     /**
 615      * Checks that the specified value is valid for this field.
 616      * <p>
 617      * This validates that the value is within the outer range of valid values
 618      * returned by {@link #range()}.
 619      * <p>
 620      * This method checks against the range of the field in the ISO-8601 calendar system.
 621      * This range may be incorrect for other calendar systems.
 622      * Use {@link Chronology#range(ChronoField)} to access the correct range
 623      * for a different calendar system.
 624      *
 625      * @param value  the value to check
 626      * @return the value that was passed in
 627      */
 628     public long checkValidValue(long value) {
 629         return range().checkValidValue(value, this);
 630     }
 631 
 632     /**
 633      * Checks that the specified value is valid and fits in an {@code int}.
 634      * <p>
 635      * This validates that the value is within the outer range of valid values
 636      * returned by {@link #range()}.
 637      * It also checks that all valid values are within the bounds of an {@code int}.
 638      * <p>
 639      * This method checks against the range of the field in the ISO-8601 calendar system.
 640      * This range may be incorrect for other calendar systems.
 641      * Use {@link Chronology#range(ChronoField)} to access the correct range
 642      * for a different calendar system.
 643      *
 644      * @param value  the value to check
 645      * @return the value that was passed in
 646      */
 647     public int checkValidIntValue(long value) {
 648         return range().checkValidIntValue(value, this);
 649     }
 650 
 651     //-----------------------------------------------------------------------
 652     @Override
 653     public boolean isSupportedBy(TemporalAccessor temporal) {
 654         return temporal.isSupported(this);
 655     }
 656 
 657     @Override
 658     public ValueRange rangeRefinedBy(TemporalAccessor temporal) {
 659         return temporal.range(this);
 660     }
 661 
 662     @Override
 663     public long getFrom(TemporalAccessor temporal) {
 664         return temporal.getLong(this);
 665     }
 666 
 667     @SuppressWarnings("unchecked")
 668     @Override
 669     public <R extends Temporal> R adjustInto(R temporal, long newValue) {
 670         return (R) temporal.with(this, newValue);
 671     }
 672 
 673     //-----------------------------------------------------------------------
 674     @Override
 675     public String toString() {
 676         return getName();
 677     }
 678 
 679 }