1 /* 2 * Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 /* 27 * This file is available under and governed by the GNU General Public 28 * License version 2 only, as published by the Free Software Foundation. 29 * However, the following notice accompanied the original version of this 30 * file: 31 * 32 * Copyright (c) 2012, Stephen Colebourne & Michael Nascimento Santos 33 * 34 * All rights reserved. 35 * 36 * Redistribution and use in source and binary forms, with or without 37 * modification, are permitted provided that the following conditions are met: 38 * 39 * * Redistributions of source code must retain the above copyright notice, 40 * this list of conditions and the following disclaimer. 41 * 42 * * Redistributions in binary form must reproduce the above copyright notice, 43 * this list of conditions and the following disclaimer in the documentation 44 * and/or other materials provided with the distribution. 45 * 46 * * Neither the name of JSR-310 nor the names of its contributors 47 * may be used to endorse or promote products derived from this software 48 * without specific prior written permission. 49 * 50 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 51 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 52 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 53 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 54 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 55 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 56 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 57 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 58 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 59 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 60 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 61 */ 62 package java.time.chrono; 63 64 import static java.time.chrono.JapaneseDate.MEIJI_6_ISODATE; 65 import static java.time.temporal.ChronoField.ERA; 66 67 import java.io.DataInput; 68 import java.io.DataOutput; 69 import java.io.IOException; 70 import java.io.InvalidObjectException; 71 import java.io.ObjectInputStream; 72 import java.io.ObjectStreamException; 73 import java.io.Serializable; 74 import java.time.DateTimeException; 75 import java.time.LocalDate; 76 import java.time.format.DateTimeFormatterBuilder; 77 import java.time.format.TextStyle; 78 import java.time.temporal.ChronoField; 79 import java.time.temporal.TemporalField; 80 import java.time.temporal.UnsupportedTemporalTypeException; 81 import java.time.temporal.ValueRange; 82 import java.util.Arrays; 83 import java.util.Locale; 84 import java.util.Objects; 85 86 import sun.util.calendar.CalendarDate; 87 88 /** 89 * An era in the Japanese Imperial calendar system. 90 * <p> 91 * The Japanese government defines the official name and start date of 92 * each era. Eras are consecutive and their date ranges do not overlap, 93 * so the end date of one era is always the day before the start date 94 * of the next era. 95 * <p> 96 * The Java SE Platform supports all eras defined by the Japanese government, 97 * beginning with the Meiji era. Each era is identified in the Platform by an 98 * integer value and a name. The {@link #of(int)} and {@link #valueOf(String)} 99 * methods may be used to obtain a singleton instance of JapaneseEra for each 100 * era. The {@link #values()} method returns the singleton instances of all 101 * supported eras. 102 * <p> 103 * For convenience, this class declares a number of public static final fields 104 * that refer to singleton instances returned by the values() method. 105 * 106 * @apiNote 107 * The fields declared in this class may evolve over time, in line with the 108 * results of the {@link #values()} method. However, there is not necessarily 109 * a 1:1 correspondence between the fields and the singleton instances. 110 * 111 * @apiNote 112 * The Japanese government may announce a new era and define its start 113 * date but not its official name. In this scenario, the singleton instance 114 * that represents the new era may return a name that is not stable until 115 * the official name is defined. Developers should exercise caution when 116 * relying on the name returned by any singleton instance that does not 117 * correspond to a public static final field. 118 * 119 * @implSpec 120 * This class is immutable and thread-safe. 121 * 122 * @since 1.8 123 */ 124 public final class JapaneseEra 125 implements Era, Serializable { 126 127 // The offset value to 0-based index from the era value. 128 // i.e., getValue() + ERA_OFFSET == 0-based index 129 static final int ERA_OFFSET = 2; 130 131 static final sun.util.calendar.Era[] ERA_CONFIG; 132 133 /** 134 * The singleton instance for the 'Meiji' era (1868-01-01 - 1912-07-29) 135 * which has the value -1. 136 */ 137 public static final JapaneseEra MEIJI = new JapaneseEra(-1, LocalDate.of(1868, 1, 1)); 138 /** 139 * The singleton instance for the 'Taisho' era (1912-07-30 - 1926-12-24) 140 * which has the value 0. 141 */ 142 public static final JapaneseEra TAISHO = new JapaneseEra(0, LocalDate.of(1912, 7, 30)); 143 /** 144 * The singleton instance for the 'Showa' era (1926-12-25 - 1989-01-07) 145 * which has the value 1. 146 */ 147 public static final JapaneseEra SHOWA = new JapaneseEra(1, LocalDate.of(1926, 12, 25)); 148 /** 149 * The singleton instance for the 'Heisei' era (1989-01-08 - 2019-04-30) 150 * which has the value 2. 151 */ 152 public static final JapaneseEra HEISEI = new JapaneseEra(2, LocalDate.of(1989, 1, 8)); 153 /** 154 * The singleton instance for the 'NewEra' era (2019-05-01 - current) 155 * which has the value 3. 156 */ 157 private static final JapaneseEra NEWERA = new JapaneseEra(3, LocalDate.of(2019, 5, 1)); 158 159 // The number of predefined JapaneseEra constants. 160 // There may be a supplemental era defined by the property. 161 private static final int N_ERA_CONSTANTS = NEWERA.getValue() + ERA_OFFSET; 162 163 /** 164 * Serialization version. 165 */ 166 private static final long serialVersionUID = 1466499369062886794L; 167 168 // array for the singleton JapaneseEra instances 169 private static final JapaneseEra[] KNOWN_ERAS; 170 171 static { 172 ERA_CONFIG = JapaneseChronology.JCAL.getEras(); 173 174 KNOWN_ERAS = new JapaneseEra[ERA_CONFIG.length]; 175 KNOWN_ERAS[0] = MEIJI; 176 KNOWN_ERAS[1] = TAISHO; 177 KNOWN_ERAS[2] = SHOWA; 178 KNOWN_ERAS[3] = HEISEI; 179 KNOWN_ERAS[4] = NEWERA; 180 for (int i = N_ERA_CONSTANTS; i < ERA_CONFIG.length; i++) { 181 CalendarDate date = ERA_CONFIG[i].getSinceDate(); 182 LocalDate isoDate = LocalDate.of(date.getYear(), date.getMonth(), date.getDayOfMonth()); 183 KNOWN_ERAS[i] = new JapaneseEra(i - ERA_OFFSET + 1, isoDate); 184 } 185 }; 186 187 /** 188 * The era value. 189 * @serial 190 */ 191 private final transient int eraValue; 192 193 // the first day of the era 194 private final transient LocalDate since; 195 196 /** 197 * Creates an instance. 198 * 199 * @param eraValue the era value, validated 200 * @param since the date representing the first date of the era, validated not null 201 */ 202 private JapaneseEra(int eraValue, LocalDate since) { 203 this.eraValue = eraValue; 204 this.since = since; 205 } 206 207 //----------------------------------------------------------------------- 208 /** 209 * Returns the Sun private Era instance corresponding to this {@code JapaneseEra}. 210 * 211 * @return the Sun private Era instance for this {@code JapaneseEra}. 212 */ 213 sun.util.calendar.Era getPrivateEra() { 214 return ERA_CONFIG[ordinal(eraValue)]; 215 } 216 217 //----------------------------------------------------------------------- 218 /** 219 * Obtains an instance of {@code JapaneseEra} from an {@code int} value. 220 * <ul> 221 * <li>The value {@code 1} is associated with the 'Showa' era, because 222 * it contains 1970-01-01 (ISO calendar system).</li> 223 * <li>The values {@code -1} and {@code 0} are associated with two earlier 224 * eras, Meiji and Taisho, respectively.</li> 225 * <li>A value greater than {@code 1} is associated with a later era, 226 * beginning with Heisei ({@code 2}).</li> 227 * </ul> 228 * <p> 229 * Every instance of {@code JapaneseEra} that is returned from the {@link values()} 230 * method has an int value (available via {@link Era#getValue()} which is 231 * accepted by this method. 232 * 233 * @param japaneseEra the era to represent 234 * @return the {@code JapaneseEra} singleton, not null 235 * @throws DateTimeException if the value is invalid 236 */ 237 public static JapaneseEra of(int japaneseEra) { 238 if (japaneseEra < MEIJI.eraValue || japaneseEra + ERA_OFFSET > KNOWN_ERAS.length) { 239 throw new DateTimeException("Invalid era: " + japaneseEra); 240 } 241 return KNOWN_ERAS[ordinal(japaneseEra)]; 242 } 243 244 /** 245 * Returns the {@code JapaneseEra} with the name. 246 * <p> 247 * The string must match exactly the name of the era. 248 * (Extraneous whitespace characters are not permitted.) 249 * 250 * @param japaneseEra the japaneseEra name; non-null 251 * @return the {@code JapaneseEra} singleton, never null 252 * @throws IllegalArgumentException if there is not JapaneseEra with the specified name 253 */ 254 public static JapaneseEra valueOf(String japaneseEra) { 255 Objects.requireNonNull(japaneseEra, "japaneseEra"); 256 for (JapaneseEra era : KNOWN_ERAS) { 257 if (era.getName().equals(japaneseEra)) { 258 return era; 259 } 260 } 261 throw new IllegalArgumentException("japaneseEra is invalid"); 262 } 263 264 /** 265 * Returns an array of JapaneseEras. 266 * <p> 267 * This method may be used to iterate over the JapaneseEras as follows: 268 * <pre> 269 * for (JapaneseEra c : JapaneseEra.values()) 270 * System.out.println(c); 271 * </pre> 272 * 273 * @return an array of JapaneseEras 274 */ 275 public static JapaneseEra[] values() { 276 return Arrays.copyOf(KNOWN_ERAS, KNOWN_ERAS.length); 277 } 278 279 /** 280 * {@inheritDoc} 281 * 282 * @param style {@inheritDoc} 283 * @param locale {@inheritDoc} 284 */ 285 @Override 286 public String getDisplayName(TextStyle style, Locale locale) { 287 // If this JapaneseEra is a supplemental one, obtain the name from 288 // the era definition. 289 if (getValue() > N_ERA_CONSTANTS - ERA_OFFSET) { 290 Objects.requireNonNull(locale, "locale"); 291 return style.asNormal() == TextStyle.NARROW ? getAbbreviation() : getName(); 292 } 293 294 return new DateTimeFormatterBuilder() 295 .appendText(ERA, style) 296 .toFormatter(locale) 297 .withChronology(JapaneseChronology.INSTANCE) 298 .format(this == MEIJI ? MEIJI_6_ISODATE : since); 299 } 300 301 //----------------------------------------------------------------------- 302 /** 303 * Obtains an instance of {@code JapaneseEra} from a date. 304 * 305 * @param date the date, not null 306 * @return the Era singleton, never null 307 */ 308 static JapaneseEra from(LocalDate date) { 309 if (date.isBefore(MEIJI_6_ISODATE)) { 310 throw new DateTimeException("JapaneseDate before Meiji 6 are not supported"); 311 } 312 for (int i = KNOWN_ERAS.length - 1; i > 0; i--) { 313 JapaneseEra era = KNOWN_ERAS[i]; 314 if (date.compareTo(era.since) >= 0) { 315 return era; 316 } 317 } 318 return null; 319 } 320 321 static JapaneseEra toJapaneseEra(sun.util.calendar.Era privateEra) { 322 for (int i = ERA_CONFIG.length - 1; i >= 0; i--) { 323 if (ERA_CONFIG[i].equals(privateEra)) { 324 return KNOWN_ERAS[i]; 325 } 326 } 327 return null; 328 } 329 330 static sun.util.calendar.Era privateEraFrom(LocalDate isoDate) { 331 for (int i = KNOWN_ERAS.length - 1; i > 0; i--) { 332 JapaneseEra era = KNOWN_ERAS[i]; 333 if (isoDate.compareTo(era.since) >= 0) { 334 return ERA_CONFIG[i]; 335 } 336 } 337 return null; 338 } 339 340 /** 341 * Returns the index into the arrays from the Era value. 342 * the eraValue is a valid Era number, -1..2. 343 * 344 * @param eraValue the era value to convert to the index 345 * @return the index of the current Era 346 */ 347 private static int ordinal(int eraValue) { 348 return eraValue + ERA_OFFSET - 1; 349 } 350 351 //----------------------------------------------------------------------- 352 /** 353 * Gets the numeric era {@code int} value. 354 * <p> 355 * The {@link #SHOWA} era that contains 1970-01-01 (ISO calendar system) has the value 1. 356 * Later eras are numbered from 2 ({@link #HEISEI}). 357 * Earlier eras are numbered 0 ({@link #TAISHO}), -1 ({@link #MEIJI})). 358 * 359 * @return the era value 360 */ 361 @Override 362 public int getValue() { 363 return eraValue; 364 } 365 366 //----------------------------------------------------------------------- 367 /** 368 * Gets the range of valid values for the specified field. 369 * <p> 370 * The range object expresses the minimum and maximum valid values for a field. 371 * This era is used to enhance the accuracy of the returned range. 372 * If it is not possible to return the range, because the field is not supported 373 * or for some other reason, an exception is thrown. 374 * <p> 375 * If the field is a {@link ChronoField} then the query is implemented here. 376 * The {@code ERA} field returns the range. 377 * All other {@code ChronoField} instances will throw an {@code UnsupportedTemporalTypeException}. 378 * <p> 379 * If the field is not a {@code ChronoField}, then the result of this method 380 * is obtained by invoking {@code TemporalField.rangeRefinedBy(TemporalAccessor)} 381 * passing {@code this} as the argument. 382 * Whether the range can be obtained is determined by the field. 383 * <p> 384 * The range of valid Japanese eras can change over time due to the nature 385 * of the Japanese calendar system. 386 * 387 * @param field the field to query the range for, not null 388 * @return the range of valid values for the field, not null 389 * @throws DateTimeException if the range for the field cannot be obtained 390 * @throws UnsupportedTemporalTypeException if the unit is not supported 391 */ 392 @Override // override as super would return range from 0 to 1 393 public ValueRange range(TemporalField field) { 394 if (field == ERA) { 395 return JapaneseChronology.INSTANCE.range(ERA); 396 } 397 return Era.super.range(field); 398 } 399 400 //----------------------------------------------------------------------- 401 String getAbbreviation() { 402 return ERA_CONFIG[ordinal(getValue())].getAbbreviation(); 403 } 404 405 String getName() { 406 return ERA_CONFIG[ordinal(getValue())].getName(); 407 } 408 409 @Override 410 public String toString() { 411 return getName(); 412 } 413 414 //----------------------------------------------------------------------- 415 /** 416 * Defend against malicious streams. 417 * 418 * @param s the stream to read 419 * @throws InvalidObjectException always 420 */ 421 private void readObject(ObjectInputStream s) throws InvalidObjectException { 422 throw new InvalidObjectException("Deserialization via serialization delegate"); 423 } 424 425 //----------------------------------------------------------------------- 426 /** 427 * Writes the object using a 428 * <a href="../../../serialized-form.html#java.time.chrono.Ser">dedicated serialized form</a>. 429 * @serialData 430 * <pre> 431 * out.writeByte(5); // identifies a JapaneseEra 432 * out.writeInt(getValue()); 433 * </pre> 434 * 435 * @return the instance of {@code Ser}, not null 436 */ 437 private Object writeReplace() { 438 return new Ser(Ser.JAPANESE_ERA_TYPE, this); 439 } 440 441 void writeExternal(DataOutput out) throws IOException { 442 out.writeByte(this.getValue()); 443 } 444 445 static JapaneseEra readExternal(DataInput in) throws IOException { 446 byte eraValue = in.readByte(); 447 return JapaneseEra.of(eraValue); 448 } 449 450 }