Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8215926

Support new Japanese era in java.time.chrono.JapaneseEra

    Details

    • Subcomponent:
    • Resolved In Build:
      master

      Description

      The java.time.chrono.JapaneseEra class introduced in Java SE 8 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 8, 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 8 Platform. See the announcement [0] to the OpenJDK community.
       
      [0] http://mail.openjdk.java.net/pipermail/jdk8u-dev/2018-December/008324.html

      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 public static singleton instance "HEISEI" field is changed from:
       
      /**
          * The singleton instance for the 'Heisei' era (1989-01-08 - current)
          * which has the value 2.
      */
       
      to
       
      /**
          * The singleton instance for the 'Heisei' era (1989-01-08 - 2019-04-30)
          * which has the value 2.
      */
       
       
       
      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
       */

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                dkejriwal Deepak Kejriwal
                Reporter:
                naoto Naoto Sato
              • Votes:
                0 Vote for this issue
                Watchers:
                2 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: