Summary

Clarify support for the new Japanese era in the Java SE 12 Platform.

Problem

Support for the new era was added with the CSR JDK-8212942, but it was not clear how the class identifies the supported eras. Unfortunately, that CSR JDK-8212942 is closed, and the CSR Process does not allow it to be withdrawn or reopened for clarification.

Solution

Clarify the following points in the specification of java.time.chrono.JapaneseEra, by applying the modifications from JDK-8215946 which applied to Java SE 11:

• Which eras are supported by the class, in the form of singleton instances of JapaneseEra.
• How to identify a specific era.
• Correspondence of the public static final fields to the singleton instances.
• Developer guidance on dealing with the new era, especially explaining the unstable placeholder name exposed by the appropriate singleton instance.

Clarify the integer values accepted by the of(int) method.

Specification

Change the specification of the java.time.chrono.JapaneseEra class from:

  * An era in the Japanese Imperial calendar system.
  * <p>
  * 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 number of the valid eras may increase, as new eras may be
  * defined by the Japanese government. Once an era is defined,
  * future versions of the platform may add a singleton instance
  * for it. The defined era is expected to have a consecutive integer
  * associated with it.
  *
  * @implSpec
  * This class is immutable and thread-safe.
  *
  * @since 1.8

to:

 * An era in the Japanese Imperial calendar system.
 * <p>
 * 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.
 * <p>
 * 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 {@link #of(int)} and {@link #valueOf(String)}
 * methods may be used to obtain a singleton instance of {@code JapaneseEra}
 * for each era. The {@link #values()} method returns the singleton instances
 * of all supported eras.
 * <p>
 * For convenience, this class declares a number of public static final fields
 * that refer to singleton instances returned by the {@link #values()} method.
 *
 * @apiNote
 * The fields declared in this class may evolve over time, in line with the
 * results of the {@link #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.
 *
 * @since 1.8

Change the specification of the of(int) method from:

      * Obtains an instance of {@code JapaneseEra} from an {@code int} value.
      * <p>
      * 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.
      * <p>
      * In addition to the known era singletons, values for additional
      * eras may be defined. Those values are the {@link Era#getValue()}
      * of corresponding eras from the {@link #values()} method.
      *
      * @param japaneseEra  the era to represent
      * @return the {@code JapaneseEra} singleton, not null
      * @throws DateTimeException if the value is invalid

to:

     * Obtains an instance of {@code JapaneseEra} from an {@code int} value.
     * <ul>
     * <li>The value {@code 1} is associated with the 'Showa' era, because
     * it contains 1970-01-01 (ISO calendar system).</li>
     * <li>The values {@code -1} and {@code 0} are associated with two earlier
     * eras, Meiji and Taisho, respectively.</li>
     * <li>A value greater than {@code 1} is associated with a later era,
     * beginning with Heisei ({@code 2}).</li>
     * </ul>
     * <p>
     * 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