* 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);
}
}