equal
deleted
inserted
replaced
90 * <p> |
90 * <p> |
91 * This class defines the valid eras for the Japanese chronology. |
91 * This class defines the valid eras for the Japanese chronology. |
92 * Japan introduced the Gregorian calendar starting with Meiji 6. |
92 * Japan introduced the Gregorian calendar starting with Meiji 6. |
93 * Only Meiji and later eras are supported; |
93 * Only Meiji and later eras are supported; |
94 * dates before Meiji 6, January 1 are not supported. |
94 * dates before Meiji 6, January 1 are not supported. |
|
95 * The number of the valid eras may increase, as new eras may be |
|
96 * defined by the Japanese government. Once an era is defined, |
|
97 * subsequent versions of this class will add a singleton instance |
|
98 * for it. The defined era is expected to have a consecutive integer |
|
99 * associated with it. |
95 * |
100 * |
96 * @implSpec |
101 * @implSpec |
97 * This class is immutable and thread-safe. |
102 * This class is immutable and thread-safe. |
98 * |
103 * |
99 * @since 1.8 |
104 * @since 1.8 |
193 |
198 |
194 //----------------------------------------------------------------------- |
199 //----------------------------------------------------------------------- |
195 /** |
200 /** |
196 * Obtains an instance of {@code JapaneseEra} from an {@code int} value. |
201 * Obtains an instance of {@code JapaneseEra} from an {@code int} value. |
197 * <p> |
202 * <p> |
198 * The {@link #SHOWA} era that contains 1970-01-01 (ISO calendar system) has the value 1 |
203 * The {@link #SHOWA} era that contains 1970-01-01 (ISO calendar system) has the value 1. |
199 * Later era is numbered 2 ({@link #HEISEI}). Earlier eras are numbered 0 ({@link #TAISHO}), |
204 * Later era is numbered 2 ({@link #HEISEI}). Earlier eras are numbered 0 ({@link #TAISHO}), |
200 * -1 ({@link #MEIJI}), only Meiji and later eras are supported. |
205 * -1 ({@link #MEIJI}), only Meiji and later eras are supported. |
|
206 * <p> |
|
207 * In addition to the known era singletons, values for additional |
|
208 * eras may be defined. Those values are the {@link Era#getValue()} |
|
209 * of corresponding eras from the {@link #values()} method. |
201 * |
210 * |
202 * @param japaneseEra the era to represent |
211 * @param japaneseEra the era to represent |
203 * @return the {@code JapaneseEra} singleton, not null |
212 * @return the {@code JapaneseEra} singleton, not null |
204 * @throws DateTimeException if the value is invalid |
213 * @throws DateTimeException if the value is invalid |
205 */ |
214 */ |
214 /** |
223 /** |
215 * Returns the {@code JapaneseEra} with the name. |
224 * Returns the {@code JapaneseEra} with the name. |
216 * <p> |
225 * <p> |
217 * The string must match exactly the name of the era. |
226 * The string must match exactly the name of the era. |
218 * (Extraneous whitespace characters are not permitted.) |
227 * (Extraneous whitespace characters are not permitted.) |
|
228 * <p> |
|
229 * Valid era names are the names of eras returned from {@link #values()}. |
219 * |
230 * |
220 * @param japaneseEra the japaneseEra name; non-null |
231 * @param japaneseEra the japaneseEra name; non-null |
221 * @return the {@code JapaneseEra} singleton, never null |
232 * @return the {@code JapaneseEra} singleton, never null |
222 * @throws IllegalArgumentException if there is not JapaneseEra with the specified name |
233 * @throws IllegalArgumentException if there is not JapaneseEra with the specified name |
223 */ |
234 */ |
230 } |
241 } |
231 throw new IllegalArgumentException("japaneseEra is invalid"); |
242 throw new IllegalArgumentException("japaneseEra is invalid"); |
232 } |
243 } |
233 |
244 |
234 /** |
245 /** |
235 * Returns an array of JapaneseEras. |
246 * Returns an array of JapaneseEras. The array may contain eras defined |
|
247 * by the Japanese government beyond the known era singletons. |
|
248 * |
236 * <p> |
249 * <p> |
237 * This method may be used to iterate over the JapaneseEras as follows: |
250 * This method may be used to iterate over the JapaneseEras as follows: |
238 * <pre> |
251 * <pre> |
239 * for (JapaneseEra c : JapaneseEra.values()) |
252 * for (JapaneseEra c : JapaneseEra.values()) |
240 * System.out.println(c); |
253 * System.out.println(c); |