- * This class defines the valid eras for the Japanese chronology. - * Japan introduced the Gregorian calendar starting with Meiji 6. - * Only Meiji and later eras are supported; - * dates before Meiji 6, January 1 are not supported. + * The Japanese government defines the official name and start date of + * each era. Eras are consecutive and their date ranges do not overlap, + * so the end date of one era is always the day before the start date + * of the next era. + *
+ * The Java SE Platform supports all eras defined by the Japanese government, + * beginning with the Meiji era. Each era is identified in the Platform by an + * integer value and a name. The of(int) and valueOf(String) methods may be + * used to obtain a singleton instance of JapaneseEra for each era. The + * values() method returns the singleton instances of all supported eras. + *
+ * For convenience, this class declares a number of public static final fields + * that refer to singleton instances returned by the values() method. + * + * @apiNote + * The fields declared in this class may evolve over time, in line with the + * results of the values() method. However, there is not necessarily a 1:1 + * correspondence between the fields and the singleton instances. + * + * @apiNote + * The Japanese government may announce a new era and define its start + * date but not its official name. In this scenario, the singleton instance + * that represents the new era may return a name that is not stable until + * the official name is defined. Developers should exercise caution when + * relying on the name returned by any singleton instance that does not + * correspond to a public static final field. * * @implSpec * This class is immutable and thread-safe. @@ -122,7 +144,7 @@ */ public static final JapaneseEra SHOWA = new JapaneseEra(1, LocalDate.of(1926, 12, 25)); /** - * The singleton instance for the 'Heisei' era (1989-01-08 - current) + * The singleton instance for the 'Heisei' era (1989-01-08 - 2019-04-30) * which has the value 2. */ public static final JapaneseEra HEISEI = new JapaneseEra(2, LocalDate.of(1989, 1, 8)); @@ -186,15 +208,23 @@ //----------------------------------------------------------------------- /** - * Obtains an instance of {@code JapaneseEra} from an {@code int} value. - *
- * The {@link #SHOWA} era that contains 1970-01-01 (ISO calendar system) has the value 1 - * Later era is numbered 2 ({@link #HEISEI}). Earlier eras are numbered 0 ({@link #TAISHO}), - * -1 ({@link #MEIJI}), only Meiji and later eras are supported. - * - * @param japaneseEra the era to represent - * @return the {@code JapaneseEra} singleton, not null - * @throws DateTimeException if the value is invalid + * Obtains an instance of {@code JapaneseEra} from an {@code int} value. + *
+ * Every instance of {@code JapaneseEra} that is returned from the {@link values()} + * method has an int value (available via {@link Era#getValue()} which is + * accepted by this method. + * + * @param japaneseEra the era to represent + * @return the {@code JapaneseEra} singleton, not null + * @throws DateTimeException if the value is invalid */ public static JapaneseEra of(int japaneseEra) { if (japaneseEra < MEIJI.eraValue || japaneseEra + ERA_OFFSET > KNOWN_ERAS.length) {