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][1], but it was not clear how the class identifies the supported eras. Unfortunately, that CSR  [JDK-8212942][1] 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][2] 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
```


  [1]: https://bugs.openjdk.java.net/browse/JDK-8212942
  [2]: https://bugs.openjdk.java.net/browse/JDK-8215946