src/java.base/share/classes/java/time/chrono/JapaneseEra.java

rev 53194 : [mq]: 8217892

*** 86,104 ****
  import sun.util.calendar.CalendarDate;
  
  /**
   * 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
--- 86,122 ----
  import sun.util.calendar.CalendarDate;
  
  /**
   * 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
*** 197,214 ****
      }
  
      //-----------------------------------------------------------------------
      /**
       * 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
       */
--- 215,236 ----
      }
  
      //-----------------------------------------------------------------------
      /**
       * 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
       */