1 /* 2 * Copyright (c) 2007-present, Stephen Colebourne & Michael Nascimento Santos 3 * 4 * All rights reserved. 5 * 6 * Redistribution and use in source and binary forms, with or without 7 * modification, are permitted provided that the following conditions are met: 8 * 9 * * Redistributions of source code must retain the above copyright notice, 10 * this list of conditions and the following disclaimer. 11 * 12 * * Redistributions in binary form must reproduce the above copyright notice, 13 * this list of conditions and the following disclaimer in the documentation 14 * and/or other materials provided with the distribution. 15 * 16 * * Neither the name of JSR-310 nor the names of its contributors 17 * may be used to endorse or promote products derived from this software 18 * without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 23 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 27 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 28 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 29 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 30 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 package org.threeten.bp.chrono; 33 34 import java.util.Locale; 35 36 import org.threeten.bp.format.TextStyle; 37 import org.threeten.bp.temporal.TemporalAccessor; 38 import org.threeten.bp.temporal.TemporalAdjuster; 39 40 /** 41 * An era of the time-line. 42 * <p> 43 * Most calendar systems have a single epoch dividing the time-line into two eras. 44 * However, some calendar systems, have multiple eras, such as one for the reign 45 * of each leader. 46 * In all cases, the era is conceptually the largest division of the time-line. 47 * Each chronology defines the Era's that are known Eras and a 48 * {@link Chronology#eras Chrono.eras} to get the valid eras. 49 * <p> 50 * For example, the Thai Buddhist calendar system divides time into two eras, 51 * before and after a single date. By contrast, the Japanese calendar system 52 * has one era for the reign of each Emperor. 53 * <p> 54 * Instances of {@code Era} may be compared using the {@code ==} operator. 55 * 56 * <h3>Specification for implementors</h3> 57 * This interface must be implemented with care to ensure other classes operate correctly. 58 * All implementations must be singletons - final, immutable and thread-safe. 59 * It is recommended to use an enum whenever possible. 60 */ 61 public interface Era extends TemporalAccessor, TemporalAdjuster { 62 63 /** 64 * Gets the numeric value associated with the era as defined by the chronology. 65 * Each chronology defines the predefined Eras and methods to list the Eras 66 * of the chronology. 67 * <p> 68 * All fields, including eras, have an associated numeric value. 69 * The meaning of the numeric value for era is determined by the chronology 70 * according to these principles: 71 * <p><ul> 72 * <li>The era in use at the epoch 1970-01-01 (ISO) has the value 1. 73 * <li>Later eras have sequentially higher values. 74 * <li>Earlier eras have sequentially lower values, which may be negative. 75 * </ul><p> 76 * 77 * @return the numeric era value 78 */ getValue()79 int getValue(); 80 81 /** 82 * Gets the textual representation of this era. 83 * <p> 84 * This returns the textual name used to identify the era. 85 * The parameters control the style of the returned text and the locale. 86 * <p> 87 * If no textual mapping is found then the {@link #getValue() numeric value} is returned. 88 * 89 * @param style the style of the text required, not null 90 * @param locale the locale to use, not null 91 * @return the text value of the era, not null 92 */ getDisplayName(TextStyle style, Locale locale)93 String getDisplayName(TextStyle style, Locale locale); 94 95 } 96