Summary
-------
Allow Java SE 11 to accommodate the new Japanese era in the java.time API.

Problem
-------
The `java.time.chrono.JapaneseEra` class introduced in Java SE 11 declares four `public static final` fields that represent eras in the Japanese calendar system. New eras can be defined by the relevant Japanese authorities. The `JapaneseEra` class should accommodate such new eras.

Solution
--------
The `values()` method of `JapaneseEra` is intended to return singleton instances representing all the eras supported by the Java SE Platform. In Java SE 11 and earlier, that meant four instances, corresponding precisely to the four `public static final` fields provided for convenience. Going forward, the Japanese government may define a new era, in which case the `values()` method will return an additional singleton instance in existing implementations of the Platform, but a corresponding field will be provided only in new versions of the Platform. The class-level specification of `JapaneseEra` should document this relaxed correspondence between singleton instances and the convenience fields. It should also make clear that access to any supported era (not just the eras corresponding to fields) is possible via accessor methods in the class, such as `of(int)`.

These changes necessitate a Maintenance Review of the Java SE 11 Platform. See the [announcement](http://mail.openjdk.java.net/pipermail/jdk-updates-dev/2018-December/000308.html) to the OpenJDK community.

Specification
-------

The specification of the `java.time.chrono.JapaneseEra` class is changed 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.
     *
     * @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 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.
     * <p>
     * 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.
     *
     * @since 1.8
     */

The specification of the `of(int)` method is changed 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.
     *
     * @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
     */