+ * The main date and time API is built on the ISO calendar system. + * This class operates behind the scenes to represent the general concept of a calendar system. + * For example, the Japanese, Minguo, Thai Buddhist and others. + *
+ * Most other calendar systems also operate on the shared concepts of year, month and day, + * linked to the cycles of the Earth around the Sun, and the Moon around the Earth. + * These shared concepts are defined by {@link ChronoField} and are availalbe + * for use by any {@code Chrono} implementation: + *
+ * LocalDate isoDate = ... + * ChronoLocalDate<ThaiBuddhistChrono> thaiDate = ... + * int isoYear = isoDate.get(ChronoField.YEAR); + * int thaiYear = thaiDate.get(ChronoField.YEAR); + *+ * As shown, although the date objects are in different calendar systems, represented by different + * {@code Chrono} instances, both can be queried using the same constant on {@code ChronoField}. + * For a full discussion of the implications of this, see {@link ChronoLocalDate}. + * In general, the advice is to use the known ISO-based {@code LocalDate}, rather than + * {@code ChronoLocalDate}. + *
+ * While a {@code Chrono} object typically uses {@code ChronoField} and is based on + * an era, year-of-era, month-of-year, day-of-month model of a date, this is not required. + * A {@code Chrono} instance may represent a totally different kind of calendar system, + * such as the Mayan. + *
+ * In practical terms, the {@code Chrono} instance also acts as a factory. + * The {@link #of(String)} method allows an instance to be looked up by identifier, + * while the {@link #ofLocale(Locale)} method allows lookup by locale. + *
+ * The {@code Chrono} instance provides a set of methods to create {@code ChronoLocalDate} instances. + * The date classes are used to manipulate specific dates. + *
+ * + *
Adding New Calendars
+ * The set of available chronologies can be extended by applications. + * Adding a new calendar system requires the writing of an implementation of + * {@code Chrono}, {@code ChronoLocalDate} and {@code Era}. + * The majority of the logic specific to the calendar system will be in + * {@code ChronoLocalDate}. The {@code Chrono} subclass acts as a factory. + *+ * To permit the discovery of additional chronologies, the {@link java.util.ServiceLoader ServiceLoader} + * is used. A file must be added to the {@code META-INF/services} directory with the + * name 'java.time.temporal.Chrono' listing the implementation classes. + * See the ServiceLoader for more details on service loading. + * For lookup by id or calendarType, the system provided calendars are found + * first followed by application provided calendars. + *
+ * Each chronology must define a chronology ID that is unique within the system. + * If the chronology represents a calendar system defined by the + * Unicode Locale Data Markup Language (LDML) specification then that + * calendar type should also be specified. + * + *
+ * The initialization is done only once using the registration
+ * of the ISOChrono as the test and the final step.
+ * Multiple threads may perform the initialization concurrently.
+ * Only the first registration of each Chrono is retained by the
+ * ConcurrentHashMap.
+ * @return true if the cache was initialized
+ */
+ private static boolean initCache() {
+ if (CHRONOS_BY_ID.get("ISO") == null) {
+ // Initialization is incomplete
+ @SuppressWarnings("rawtypes")
+ ServiceLoader
+ * A {@code TemporalAccessor} represents some form of date and time information.
+ * This factory converts the arbitrary temporal object to an instance of {@code Chrono}.
+ * If the specified temporal object does not have a chronology, {@link ISOChrono} is returned.
+ *
+ * The conversion will obtain the chronology using {@link Queries#chrono()}.
+ *
+ * This method matches the signature of the functional interface {@link TemporalQuery}
+ * allowing it to be used in queries via method reference, {@code Chrono::from}.
+ *
+ * @param temporal the temporal to convert, not null
+ * @return the chronology, not null
+ * @throws DateTimeException if unable to convert to an {@code Chrono}
+ */
+ public static Chrono from(TemporalAccessor temporal) {
+ Objects.requireNonNull(temporal, "temporal");
+ Chrono obj = temporal.query(Queries.chrono());
+ return (obj != null ? obj : ISOChrono.INSTANCE);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Obtains an instance of {@code Chrono} from a locale.
+ *
+ * The locale can be used to identify a calendar.
+ * This uses {@link Locale#getUnicodeLocaleType(String)} to obtain the "ca" key
+ * to identify the calendar system.
+ *
+ * If the locale does not contain calendar system information, the standard
+ * ISO calendar system is used.
+ *
+ * @param locale the locale to use to obtain the calendar system, not null
+ * @return the calendar system associated with the locale, not null
+ * @throws DateTimeException if the locale-specified calendar cannot be found
+ */
+ public static Chrono ofLocale(Locale locale) {
+ Objects.requireNonNull(locale, "locale");
+ String type = locale.getUnicodeLocaleType("ca");
+ if (type == null) {
+ return ISOChrono.INSTANCE;
+ } else if ("iso".equals(type) || "iso8601".equals(type)) {
+ return ISOChrono.INSTANCE;
+ } else {
+ Chrono chrono = CHRONOS_BY_TYPE.get(type);
+ if (chrono == null) {
+ throw new DateTimeException("Unknown calendar system: " + type);
+ }
+ return chrono;
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Obtains an instance of {@code Chrono} from a chronology ID or
+ * calendar system type.
+ *
+ * This returns a chronology based on either the ID or the type.
+ * The {@link #getId() chronology ID} uniquely identifies the chronology.
+ * The {@link #getCalendarType() calendar system type} is defined by the LDML specification.
+ *
+ * The chronology may be a system chronology or a chronology
+ * provided by the application via ServiceLoader configuration.
+ *
+ * Since some calendars can be customized, the ID or type typically refers
+ * to the default customization. For example, the Gregorian calendar can have multiple
+ * cutover dates from the Julian, but the lookup only provides the default cutover date.
+ *
+ * @param id the chronology ID or calendar system type, not null
+ * @return the chronology with the identifier requested, not null
+ * @throws DateTimeException if the chronology cannot be found
+ */
+ public static Chrono of(String id) {
+ Objects.requireNonNull(id, "id");
+ do {
+ Chrono chrono = of0(id);
+ if (chrono != null) {
+ return chrono;
+ }
+ // If not found, do the initialization (once) and repeat the lookup
+ } while (initCache());
+
+ // Look for a Chrono using ServiceLoader of the Thread's ContextClassLoader
+ // Application provided Chronologies must not be cached
+ @SuppressWarnings("rawtypes")
+ ServiceLoader
+ * Each returned {@code Chrono} is available for use in the system.
+ * The set of chronologies includes the system chronologies and
+ * any chronologies provided by the application via ServiceLoader
+ * configuration.
+ *
+ * @return the independent, modifiable set of the available chronology IDs, not null
+ */
+ public static Set
+ * This combines a {@link ChronoLocalDate}, which provides the {@code Chrono},
+ * with a {@link LocalTime} to produce a {@link ChronoLocalDateTime}.
+ *
+ * This method is intended for chronology implementations.
+ * It uses a standard implementation that is shared for all chronologies.
+ *
+ * @param
+ * The ID uniquely identifies the {@code Chrono}.
+ * It can be used to lookup the {@code Chrono} using {@link #of(String)}.
+ *
+ * @return the chronology ID, not null
+ * @see #getCalendarType()
+ */
+ public abstract String getId();
+
+ /**
+ * Gets the calendar type of the underlying calendar system.
+ *
+ * The calendar type is an identifier defined by the
+ * Unicode Locale Data Markup Language (LDML) specification.
+ * It can be used to lookup the {@code Chrono} using {@link #of(String)}.
+ * It can also be used as part of a locale, accessible via
+ * {@link Locale#getUnicodeLocaleType(String)} with the key 'ca'.
+ *
+ * @return the calendar system type, null if the calendar is not defined by LDML
+ * @see #getId()
+ */
+ public abstract String getCalendarType();
+
+ //-----------------------------------------------------------------------
+ /**
+ * Obtains a local date in this chronology from the era, year-of-era,
+ * month-of-year and day-of-month fields.
+ *
+ * @param era the era of the correct type for the chronology, not null
+ * @param yearOfEra the chronology year-of-era
+ * @param month the chronology month-of-year
+ * @param dayOfMonth the chronology day-of-month
+ * @return the local date in this chronology, not null
+ * @throws DateTimeException if unable to create the date
+ */
+ public ChronoLocalDate
+ * This creates a date in this chronology based on the specified {@code TemporalAccessor}.
+ *
+ * The standard mechanism for conversion between date types is the
+ * {@link ChronoField#EPOCH_DAY local epoch-day} field.
+ *
+ * @param temporal the temporal object to convert, not null
+ * @return the local date in this chronology, not null
+ * @throws DateTimeException if unable to create the date
+ */
+ public abstract ChronoLocalDate
+ * This will query the {@link Clock#systemDefaultZone() system clock} in the default
+ * time-zone to obtain the current date.
+ *
+ * Using this method will prevent the ability to use an alternate clock for testing
+ * because the clock is hard-coded.
+ *
+ * This implementation uses {@link #dateNow(Clock)}.
+ *
+ * @return the current local date using the system clock and default time-zone, not null
+ * @throws DateTimeException if unable to create the date
+ */
+ public ChronoLocalDate
+ * This will query the {@link Clock#system(ZoneId) system clock} to obtain the current date.
+ * Specifying the time-zone avoids dependence on the default time-zone.
+ *
+ * Using this method will prevent the ability to use an alternate clock for testing
+ * because the clock is hard-coded.
+ *
+ * @param zone the zone ID to use, not null
+ * @return the current local date using the system clock, not null
+ * @throws DateTimeException if unable to create the date
+ */
+ public ChronoLocalDate
+ * This will query the specified clock to obtain the current date - today.
+ * Using this method allows the use of an alternate clock for testing.
+ * The alternate clock may be introduced using {@link Clock dependency injection}.
+ *
+ * @param clock the clock to use, not null
+ * @return the current local date, not null
+ * @throws DateTimeException if unable to create the date
+ */
+ public ChronoLocalDate
+ * This creates a date-time in this chronology based on the specified {@code TemporalAccessor}.
+ *
+ * The date of the date-time should be equivalent to that obtained by calling
+ * {@link #date(TemporalAccessor)}.
+ * The standard mechanism for conversion between time types is the
+ * {@link ChronoField#NANO_OF_DAY nano-of-day} field.
+ *
+ * @param temporal the temporal object to convert, not null
+ * @return the local date-time in this chronology, not null
+ * @throws DateTimeException if unable to create the date-time
+ */
+ public ChronoLocalDateTime
+ * This creates a date-time in this chronology based on the specified {@code TemporalAccessor}.
+ *
+ * This should obtain a {@code ZoneId} using {@link ZoneId#from(TemporalAccessor)}.
+ * The date-time should be obtained by obtaining an {@code Instant}.
+ * If that fails, the local date-time should be used.
+ *
+ * @param temporal the temporal object to convert, not null
+ * @return the zoned date-time in this chronology, not null
+ * @throws DateTimeException if unable to create the date-time
+ */
+ public ChronoZonedDateTime
+ * This creates a zoned date-time with the same instant as that specified.
+ *
+ * @param instant the instant to create the date-time from, not null
+ * @param zone the time-zone, not null
+ * @return the zoned date-time, not null
+ * @throws DateTimeException if the result exceeds the supported range
+ */
+ public ChronoZonedDateTime
+ * A leap-year is a year of a longer length than normal.
+ * The exact meaning is determined by the chronology according to the following constraints.
+ *
+ *
+ * @param prolepticYear the proleptic-year to check, not validated for range
+ * @return true if the year is a leap year
+ */
+ public abstract boolean isLeapYear(long prolepticYear);
+
+ /**
+ * Calculates the proleptic-year given the era and year-of-era.
+ *
+ * This combines the era and year-of-era into the single proleptic-year field.
+ *
+ * @param era the era of the correct type for the chronology, not null
+ * @param yearOfEra the chronology year-of-era
+ * @return the proleptic-year
+ * @throws DateTimeException if unable to convert
+ */
+ public abstract int prolepticYear(Era
+ * The era is, conceptually, the largest division of the time-line.
+ * Most calendar systems have a single epoch dividing the time-line into two eras.
+ * However, some have multiple eras, such as one for the reign of each leader.
+ * The exact meaning is determined by the chronology according to the following constraints.
+ *
+ * The era in use at 1970-01-01 must have the value 1.
+ * Later eras must have sequentially higher values.
+ * Earlier eras must have sequentially lower values.
+ * Each chronology must refer to an enum or similar singleton to provide the era values.
+ *
+ * This method returns the singleton era of the correct type for the specified era value.
+ *
+ * @param eraValue the era value
+ * @return the calendar system era, not null
+ * @throws DateTimeException if unable to create the era
+ */
+ public abstract Era
+ * Most calendar systems have an era, within which the year has meaning.
+ * If the calendar system does not support the concept of eras, an empty
+ * list must be returned.
+ *
+ * @return the list of eras for the chronology, may be immutable, not null
+ */
+ public abstract List
+ * All fields can be expressed as a {@code long} integer.
+ * This method returns an object that describes the valid range for that value.
+ *
+ * Note that the result only describes the minimum and maximum valid values
+ * and it is important not to read too much into them. For example, there
+ * could be values within the range that are invalid for the field.
+ *
+ * This method will return a result whether or not the chronology supports the field.
+ *
+ * @param field the field to get 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
+ */
+ public abstract ValueRange range(ChronoField field);
+
+ //-----------------------------------------------------------------------
+ /**
+ * Gets the textual representation of this chronology.
+ *
+ * This returns the textual name used to identify the chronology.
+ * The parameters control the style of the returned text and the locale.
+ *
+ * @param style the style of the text required, not null
+ * @param locale the locale to use, not null
+ * @return the text value of the chronology, not null
+ */
+ public String getText(TextStyle style, Locale locale) {
+ return new DateTimeFormatterBuilder().appendChronoText(style).toFormatter(locale).print(new TemporalAccessor() {
+ @Override
+ public boolean isSupported(TemporalField field) {
+ return false;
+ }
+ @Override
+ public long getLong(TemporalField field) {
+ throw new DateTimeException("Unsupported field: " + field);
+ }
+ @SuppressWarnings("unchecked")
+ @Override
+ public
+ * The comparison order first by the chronology ID string, then by any
+ * additional information specific to the subclass.
+ * It is "consistent with equals", as defined by {@link Comparable}.
+ *
+ * The default implementation compares the chronology ID.
+ * Subclasses must compare any additional state that they store.
+ *
+ * @param other the other chronology to compare to, not null
+ * @return the comparator value, negative if less, positive if greater
+ */
+ @Override
+ public int compareTo(Chrono other) {
+ return getId().compareTo(other.getId());
+ }
+
+ /**
+ * Checks if this chronology is equal to another chronology.
+ *
+ * The comparison is based on the entire state of the object.
+ *
+ * The default implementation checks the type and calls {@link #compareTo(Chrono)}.
+ *
+ * @param obj the object to check, null returns false
+ * @return true if this is equal to the other chronology
+ */
+ @Override
+ public boolean equals(Object obj) {
+ if (this == obj) {
+ return true;
+ }
+ if (obj instanceof Chrono) {
+ return compareTo((Chrono) obj) == 0;
+ }
+ return false;
+ }
+
+ /**
+ * A hash code for this chronology.
+ *
+ * The default implementation is based on the ID and class.
+ * Subclasses should add any additional state that they store.
+ *
+ * @return a suitable hash code
+ */
+ @Override
+ public int hashCode() {
+ return getClass().hashCode() ^ getId().hashCode();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Outputs this chronology as a {@code String}, using the ID.
+ *
+ * @return a string representation of this chronology, not null
+ */
+ @Override
+ public String toString() {
+ return getId();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Writes the object using a
+ * dedicated serialized form.
+ *
+ *
+ * out.writeByte(7); // identifies this as a Chrono
+ * out.writeUTF(chronoId);
+ *
+ *
+ * @return the instance of {@code Ser}, not null
+ */
+ private Object writeReplace() {
+ return new Ser(Ser.CHRONO_TYPE, this);
+ }
+
+ /**
+ * Defend against malicious streams.
+ * @return never
+ * @throws InvalidObjectException always
+ */
+ private Object readResolve() throws ObjectStreamException {
+ throw new InvalidObjectException("Deserialization via serialization delegate");
+ }
+
+ void writeExternal(DataOutput out) throws IOException {
+ out.writeUTF(getId());
+ }
+
+ static Chrono readExternal(DataInput in) throws IOException {
+ String id = in.readUTF();
+ return Chrono.of(id);
+ }
+
+}