* 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}), @@ -210,22 +222,49 @@ * {@link #SEIREKI} is used. * * @param japaneseEra the era to represent - * @return the {@code JapaneseEra} singleton, never null - * @throws DateTimeException if {@code japaneseEra} is invalid + * @return the {@code JapaneseEra} singleton, not null + * @throws DateTimeException if the value is invalid */ public static JapaneseEra of(int japaneseEra) { if (japaneseEra != SEIREKI.eraValue && (japaneseEra < MEIJI.eraValue || japaneseEra > HEISEI.eraValue)) { - throw new DateTimeException("japaneseEra is invalid"); + throw new DateTimeException("Invalid era: " + japaneseEra); } return KNOWN_ERAS[ordinal(japaneseEra)]; } /** + * Returns the {@code JapaneseEra} with the name. + *
+ * The string must match exactly the name of the era. + * (Extraneous whitespace characters are not permitted.) + * + * @param japaneseEra the japaneseEra name; non-null + * @return the {@code JapaneseEra} singleton, never null + * @throws IllegalArgumentException if there is not JapaneseEra with the specified name + */ + public static JapaneseEra valueOf(String japaneseEra) { + Objects.requireNonNull(japaneseEra, "japaneseEra"); + for (JapaneseEra era : KNOWN_ERAS) { + if (era.getName().equals(japaneseEra)) { + return era; + } + } + throw new IllegalArgumentException("japaneseEra is invalid"); + } + + /** * Returns an array of JapaneseEras. + *
+ * This method may be used to iterate over the JapaneseEras as follows: + *
+ * for (JapaneseEra c : JapaneseEra.values()) + * System.out.println(c); + *+ * * @return an array of JapaneseEras */ - static JapaneseEra[] values() { + public static JapaneseEra[] values() { return Arrays.copyOf(KNOWN_ERAS, KNOWN_ERAS.length); } @@ -268,16 +307,17 @@ /** * Returns the index into the arrays from the Era value. * the eraValue is a valid Era number, -999, -1..2. - * @param eravalue the era value to convert to the index + * + * @param eraValue the era value to convert to the index * @return the index of the current Era */ - private static int ordinal(int eravalue) { - return (eravalue == SEIREKI.eraValue) ? 0 : eravalue + ERA_OFFSET; + private static int ordinal(int eraValue) { + return (eraValue == SEIREKI.eraValue) ? 0 : eraValue + ERA_OFFSET; } //----------------------------------------------------------------------- /** - * Returns the numeric value of this {@code JapaneseEra}. + * Gets the numeric era {@code int} value. *
* The {@link #SHOWA} era that contains 1970-01-01 (ISO calendar system) has the value 1. * Later eras are numbered from 2 ({@link #HEISEI}). @@ -290,9 +330,38 @@ return eraValue; } - @Override - public JapaneseChronology getChronology() { - return JapaneseChronology.INSTANCE; + //----------------------------------------------------------------------- + /** + * Gets the range of valid values for the specified field. + *
+ * The range object expresses the minimum and maximum valid values for a field. + * This era is used to enhance the accuracy of the returned range. + * If it is not possible to return the range, because the field is not supported + * or for some other reason, an exception is thrown. + *
+ * If the field is a {@link ChronoField} then the query is implemented here. + * The {@code ERA} field returns the range. + * All other {@code ChronoField} instances will throw an {@code UnsupportedTemporalTypeException}. + *
+ * If the field is not a {@code ChronoField}, then the result of this method + * is obtained by invoking {@code TemporalField.rangeRefinedBy(TemporalAccessor)} + * passing {@code this} as the argument. + * Whether the range can be obtained is determined by the field. + *
+ * The range of valid Japanese eras can change over time due to the nature + * of the Japanese calendar system. + * + * @param field the field to query the range for, not null + * @return the range of valid values for the field, not null + * @throws DateTimeException if the range for the field cannot be obtained + * @throws UnsupportedTemporalTypeException if the unit is not supported + */ + @Override // override as super would return range from 0 to 1 + public ValueRange range(TemporalField field) { + if (field == ERA) { + return JapaneseChronology.INSTANCE.range(ERA); + } + return Era.super.range(field); } //-----------------------------------------------------------------------