src/share/classes/java/time/chrono/Chronology.java
Print this page
@@ -57,11 +57,11 @@
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
-package java.time.temporal;
+package java.time.chrono;
import java.io.DataInput;
import java.io.DataOutput;
import java.io.IOException;
import java.io.InvalidObjectException;
@@ -70,16 +70,23 @@
import java.time.DateTimeException;
import java.time.Instant;
import java.time.LocalDate;
import java.time.LocalTime;
import java.time.ZoneId;
-import java.time.calendar.HijrahChrono;
-import java.time.calendar.JapaneseChrono;
-import java.time.calendar.MinguoChrono;
-import java.time.calendar.ThaiBuddhistChrono;
+import java.time.chrono.HijrahChronology;
+import java.time.chrono.JapaneseChronology;
+import java.time.chrono.MinguoChronology;
+import java.time.chrono.ThaiBuddhistChronology;
import java.time.format.DateTimeFormatterBuilder;
import java.time.format.TextStyle;
+import java.time.temporal.ChronoField;
+import java.time.temporal.Queries;
+import java.time.temporal.Temporal;
+import java.time.temporal.TemporalAccessor;
+import java.time.temporal.TemporalField;
+import java.time.temporal.TemporalQuery;
+import java.time.temporal.ValueRange;
import java.util.HashSet;
import java.util.List;
import java.util.Locale;
import java.util.Objects;
import java.util.ServiceLoader;
@@ -93,34 +100,34 @@
* This class operates behind the scenes to represent the general concept of a calendar system.
* For example, the Japanese, Minguo, Thai Buddhist and others.
* <p>
* 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:
+ * These shared concepts are defined by {@link ChronoField} and are available
+ * for use by any {@code Chronology} implementation:
* <pre>
* LocalDate isoDate = ...
- * ChronoLocalDate<ThaiBuddhistChrono> thaiDate = ...
+ * ChronoLocalDate<ThaiBuddhistChronology> thaiDate = ...
* int isoYear = isoDate.get(ChronoField.YEAR);
* int thaiYear = thaiDate.get(ChronoField.YEAR);
* </pre>
* 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}.
+ * {@code Chronology} 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}.
* <p>
- * While a {@code Chrono} object typically uses {@code ChronoField} and is based on
+ * While a {@code Chronology} 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,
+ * A {@code Chronology} instance may represent a totally different kind of calendar system,
* such as the Mayan.
* <p>
- * In practical terms, the {@code Chrono} instance also acts as a factory.
+ * In practical terms, the {@code Chronology} 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.
* <p>
- * The {@code Chrono} instance provides a set of methods to create {@code ChronoLocalDate} instances.
+ * The {@code Chronology} instance provides a set of methods to create {@code ChronoLocalDate} instances.
* The date classes are used to manipulate specific dates.
* <p><ul>
* <li> {@link #dateNow() dateNow()}
* <li> {@link #dateNow(Clock) dateNow(clock)}
* <li> {@link #dateNow(ZoneId) dateNow(zone)}
@@ -129,20 +136,20 @@
* <li> {@link #dateYearDay(int, int) dateYearDay(yearProleptic, dayOfYear)}
* <li> {@link #dateYearDay(Era, int, int) dateYearDay(era, yearOfEra, dayOfYear)}
* <li> {@link #date(TemporalAccessor) date(TemporalAccessor)}
* </ul><p>
*
- * <p id="addcalendars">Adding New Calendars</p>
+ * <h3 id="addcalendars">Adding New Calendars</h3>
* 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}.
+ * {@code Chronology}, {@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.
+ * {@code ChronoLocalDate}. The {@code Chronology} subclass acts as a factory.
* <p>
* 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.
+ * name 'java.time.chrono.Chronology' 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.
* <p>
* Each chronology must define a chronology ID that is unique within the system.
@@ -153,134 +160,161 @@
* <h3>Specification for implementors</h3>
* This class must be implemented with care to ensure other classes operate correctly.
* All implementations that can be instantiated must be final, immutable and thread-safe.
* Subclasses should be Serializable wherever possible.
*
- * @param <C> the type of the implementing subclass
* @since 1.8
*/
-public abstract class Chrono<C extends Chrono<C>> implements Comparable<Chrono<?>> {
+public abstract class Chronology implements Comparable<Chronology> {
/**
* Map of available calendars by ID.
*/
- private static final ConcurrentHashMap<String, Chrono<?>> CHRONOS_BY_ID = new ConcurrentHashMap<>();
+ private static final ConcurrentHashMap<String, Chronology> CHRONOS_BY_ID = new ConcurrentHashMap<>();
/**
* Map of available calendars by calendar type.
*/
- private static final ConcurrentHashMap<String, Chrono<?>> CHRONOS_BY_TYPE = new ConcurrentHashMap<>();
+ private static final ConcurrentHashMap<String, Chronology> CHRONOS_BY_TYPE = new ConcurrentHashMap<>();
/**
- * Register a Chrono by ID and type for lookup by {@link #of(java.lang.String)}.
+ * Register a Chronology by ID and type for lookup by {@link #of(java.lang.String)}.
* Chronos must not be registered until they are completely constructed.
- * Specifically, not in the constructor of Chrono.
+ * Specifically, not in the constructor of Chronology.
* @param chrono the chronology to register; not null
*/
- private static void registerChrono(Chrono chrono) {
- Chrono<?> prev = CHRONOS_BY_ID.putIfAbsent(chrono.getId(), chrono);
+ private static void registerChrono(Chronology chrono) {
+ Chronology prev = CHRONOS_BY_ID.putIfAbsent(chrono.getId(), chrono);
if (prev == null) {
String type = chrono.getCalendarType();
if (type != null) {
CHRONOS_BY_TYPE.putIfAbsent(type, chrono);
}
}
}
/**
- * Initialization of the maps from id and type to Chrono.
+ * Initialization of the maps from id and type to Chronology.
* The ServiceLoader is used to find and register any implementations
- * of {@link javax.time.temporal.Chrono} found in the bootclass loader.
+ * of {@link java.time.chrono.Chronology} found in the bootclass loader.
* The built-in chronologies are registered explicitly.
* Calendars configured via the Thread's context classloader are local
* to that thread and are ignored.
* <p>
* The initialization is done only once using the registration
- * of the ISOChrono as the test and the final step.
+ * of the IsoChronology 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
+ * Only the first registration of each Chronology 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<Chrono> loader = ServiceLoader.load(Chrono.class, null);
- for (Chrono<?> chrono : loader) {
+ ServiceLoader<Chronology> loader = ServiceLoader.load(Chronology.class, null);
+ for (Chronology chrono : loader) {
registerChrono(chrono);
}
// Register these calendars; the ServiceLoader configuration is not used
- registerChrono(HijrahChrono.INSTANCE);
- registerChrono(JapaneseChrono.INSTANCE);
- registerChrono(MinguoChrono.INSTANCE);
- registerChrono(ThaiBuddhistChrono.INSTANCE);
+ registerChrono(HijrahChronology.INSTANCE);
+ registerChrono(JapaneseChronology.INSTANCE);
+ registerChrono(MinguoChronology.INSTANCE);
+ registerChrono(ThaiBuddhistChronology.INSTANCE);
- // finally, register ISOChrono to mark initialization is complete
- registerChrono(ISOChrono.INSTANCE);
+ // finally, register IsoChronology to mark initialization is complete
+ registerChrono(IsoChronology.INSTANCE);
return true;
}
return false;
}
//-----------------------------------------------------------------------
/**
- * Obtains an instance of {@code Chrono} from a temporal object.
+ * Obtains an instance of {@code Chronology} from a temporal object.
* <p>
- * 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.
+ * This obtains a chronology based on the specified temporal.
+ * A {@code TemporalAccessor} represents an arbitrary set of date and time information,
+ * which this factory converts to an instance of {@code Chronology}.
* <p>
- * The conversion will obtain the chronology using {@link Queries#chrono()}.
+ * The conversion will obtain the chronology using {@link Queries#chronology()}.
+ * If the specified temporal object does not have a chronology, {@link IsoChronology} is returned.
* <p>
* This method matches the signature of the functional interface {@link TemporalQuery}
- * allowing it to be used in queries via method reference, {@code Chrono::from}.
+ * allowing it to be used in queries via method reference, {@code Chronology::from}.
*
* @param temporal the temporal to convert, not null
* @return the chronology, not null
- * @throws DateTimeException if unable to convert to an {@code Chrono}
+ * @throws DateTimeException if unable to convert to an {@code Chronology}
*/
- public static Chrono<?> from(TemporalAccessor temporal) {
+ public static Chronology from(TemporalAccessor temporal) {
Objects.requireNonNull(temporal, "temporal");
- Chrono<?> obj = temporal.query(Queries.chrono());
- return (obj != null ? obj : ISOChrono.INSTANCE);
+ Chronology obj = temporal.query(Queries.chronology());
+ return (obj != null ? obj : IsoChronology.INSTANCE);
}
//-----------------------------------------------------------------------
/**
- * Obtains an instance of {@code Chrono} from a locale.
+ * Obtains an instance of {@code Chronology} from a locale.
* <p>
- * 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.
- * <p>
- * If the locale does not contain calendar system information, the standard
- * ISO calendar system is used.
+ * This returns a {@code Chronology} based on the specified locale,
+ * typically returning {@code IsoChronology}. Other calendar systems
+ * are only returned if they are explicitly selected within the locale.
+ * <p>
+ * The {@link Locale} class provide access to a range of information useful
+ * for localizing an application. This includes the language and region,
+ * such as "en-GB" for English as used in Great Britain.
+ * <p>
+ * The {@code Locale} class also supports an extension mechanism that
+ * can be used to identify a calendar system. The mechanism is a form
+ * of key-value pairs, where the calendar system has the key "ca".
+ * For example, the locale "en-JP-u-ca-japanese" represents the English
+ * language as used in Japan with the Japanese calendar system.
+ * <p>
+ * This method finds the desired calendar system by in a manner equivalent
+ * to passing "ca" to {@link Locale#getUnicodeLocaleType(String)}.
+ * If the "ca" key is not present, then {@code IsoChronology} is returned.
+ * <p>
+ * Note that the behavior of this method differs from the older
+ * {@link java.util.Calendar#getInstance(Locale)} method.
+ * If that method receives a locale of "th_TH" it will return {@code BuddhistCalendar}.
+ * By contrast, this method will return {@code IsoChronology}.
+ * Passing the locale "th-TH-u-ca-buddhist" into either method will
+ * result in the Thai Buddhist calendar system and is therefore the
+ * recommended approach going forward for Thai calendar system localization.
+ * <p>
+ * A similar, but simpler, situation occurs for the Japanese calendar system.
+ * The locale "jp_JP_JP" has previously been used to access the calendar.
+ * However, unlike the Thai locale, "ja_JP_JP" is automatically converted by
+ * {@code Locale} to the modern and recommended form of "ja-JP-u-ca-japanese".
+ * Thus, there is no difference in behavior between this method and
+ * {@code Calendar#getInstance(Locale)}.
*
* @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) {
+ public static Chronology 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);
+ if (type == null || "iso".equals(type) || "iso8601".equals(type)) {
+ return IsoChronology.INSTANCE;
}
+ // Not pre-defined; lookup by the type
+ do {
+ Chronology chrono = CHRONOS_BY_TYPE.get(type);
+ if (chrono != null) {
return chrono;
}
+ // If not found, do the initialization (once) and repeat the lookup
+ } while (initCache());
+ throw new DateTimeException("Unknown calendar system: " + type);
}
//-----------------------------------------------------------------------
/**
- * Obtains an instance of {@code Chrono} from a chronology ID or
+ * Obtains an instance of {@code Chronology} from a chronology ID or
* calendar system type.
* <p>
* 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.
@@ -294,156 +328,137 @@
*
* @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) {
+ public static Chronology of(String id) {
Objects.requireNonNull(id, "id");
do {
- Chrono chrono = of0(id);
+ Chronology 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
+ // Look for a Chronology using ServiceLoader of the Thread's ContextClassLoader
// Application provided Chronologies must not be cached
@SuppressWarnings("rawtypes")
- ServiceLoader<Chrono> loader = ServiceLoader.load(Chrono.class);
- for (Chrono<?> chrono : loader) {
+ ServiceLoader<Chronology> loader = ServiceLoader.load(Chronology.class);
+ for (Chronology chrono : loader) {
if (id.equals(chrono.getId()) || id.equals(chrono.getCalendarType())) {
return chrono;
}
}
throw new DateTimeException("Unknown chronology: " + id);
}
/**
- * Obtains an instance of {@code Chrono} from a chronology ID or
+ * Obtains an instance of {@code Chronology} from a chronology ID or
* calendar system type.
*
* @param id the chronology ID or calendar system type, not null
* @return the chronology with the identifier requested, or {@code null} if not found
*/
- private static Chrono<?> of0(String id) {
- Chrono<?> chrono = CHRONOS_BY_ID.get(id);
+ private static Chronology of0(String id) {
+ Chronology chrono = CHRONOS_BY_ID.get(id);
if (chrono == null) {
chrono = CHRONOS_BY_TYPE.get(id);
}
return chrono;
}
/**
* Returns the available chronologies.
* <p>
- * Each returned {@code Chrono} is available for use in the system.
+ * Each returned {@code Chronology} 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<Chrono<?>> getAvailableChronologies() {
+ public static Set<Chronology> getAvailableChronologies() {
initCache(); // force initialization
- HashSet<Chrono<?>> chronos = new HashSet<>(CHRONOS_BY_ID.values());
+ HashSet<Chronology> chronos = new HashSet(CHRONOS_BY_ID.values());
/// Add in Chronologies from the ServiceLoader configuration
@SuppressWarnings("rawtypes")
- ServiceLoader<Chrono> loader = ServiceLoader.load(Chrono.class);
- for (Chrono<?> chrono : loader) {
+ ServiceLoader<Chronology> loader = ServiceLoader.load(Chronology.class);
+ for (Chronology chrono : loader) {
chronos.add(chrono);
}
return chronos;
}
//-----------------------------------------------------------------------
/**
- * Obtains a local date-time from the a date and time.
- * <p>
- * This combines a {@link ChronoLocalDate}, which provides the {@code Chrono},
- * with a {@link LocalTime} to produce a {@link ChronoLocalDateTime}.
- * <p>
- * This method is intended for chronology implementations.
- * It uses a standard implementation that is shared for all chronologies.
- *
- * @param <R> the chronology of the date
- * @param date the date, not null
- * @param time the time, not null
- * @return the local date-time combining the input date and time, not null
- */
- public static <R extends Chrono<R>> ChronoLocalDateTime<R> dateTime(ChronoLocalDate<R> date, LocalTime time) {
- return ChronoLocalDateTimeImpl.of(date, time);
- }
-
- //-----------------------------------------------------------------------
- /**
* Creates an instance.
*/
- protected Chrono() {
+ protected Chronology() {
}
//-----------------------------------------------------------------------
/**
* Casts the {@code Temporal} to {@code ChronoLocalDate} with the same chronology.
*
* @param temporal a date-time to cast, not null
* @return the date-time checked and cast to {@code ChronoLocalDate}, not null
* @throws ClassCastException if the date-time cannot be cast to ChronoLocalDate
- * or the chronology is not equal this Chrono
+ * or the chronology is not equal this Chronology
*/
- ChronoLocalDate<C> ensureChronoLocalDate(Temporal temporal) {
+ ChronoLocalDate ensureChronoLocalDate(Temporal temporal) {
@SuppressWarnings("unchecked")
- ChronoLocalDate<C> other = (ChronoLocalDate<C>) temporal;
- if (this.equals(other.getChrono()) == false) {
- throw new ClassCastException("Chrono mismatch, expected: " + getId() + ", actual: " + other.getChrono().getId());
+ ChronoLocalDate other = (ChronoLocalDate) temporal;
+ if (this.equals(other.getChronology()) == false) {
+ throw new ClassCastException("Chronology mismatch, expected: " + getId() + ", actual: " + other.getChronology().getId());
}
return other;
}
/**
* Casts the {@code Temporal} to {@code ChronoLocalDateTime} with the same chronology.
*
* @param temporal a date-time to cast, not null
* @return the date-time checked and cast to {@code ChronoLocalDateTime}, not null
* @throws ClassCastException if the date-time cannot be cast to ChronoLocalDateTimeImpl
- * or the chronology is not equal this Chrono
+ * or the chronology is not equal this Chronology
*/
- ChronoLocalDateTimeImpl<C> ensureChronoLocalDateTime(Temporal temporal) {
+ ChronoLocalDateTimeImpl<?> ensureChronoLocalDateTime(Temporal temporal) {
@SuppressWarnings("unchecked")
- ChronoLocalDateTimeImpl<C> other = (ChronoLocalDateTimeImpl<C>) temporal;
- if (this.equals(other.getDate().getChrono()) == false) {
- throw new ClassCastException("Chrono mismatch, required: " + getId()
- + ", supplied: " + other.getDate().getChrono().getId());
+ ChronoLocalDateTimeImpl<?> other = (ChronoLocalDateTimeImpl<?>) temporal;
+ if (this.equals(other.toLocalDate().getChronology()) == false) {
+ throw new ClassCastException("Chronology mismatch, required: " + getId()
+ + ", supplied: " + other.toLocalDate().getChronology().getId());
}
return other;
}
/**
* Casts the {@code Temporal} to {@code ChronoZonedDateTimeImpl} with the same chronology.
*
* @param temporal a date-time to cast, not null
* @return the date-time checked and cast to {@code ChronoZonedDateTimeImpl}, not null
* @throws ClassCastException if the date-time cannot be cast to ChronoZonedDateTimeImpl
- * or the chronology is not equal this Chrono
+ * or the chronology is not equal this Chronology
*/
- ChronoZonedDateTimeImpl<C> ensureChronoZonedDateTime(Temporal temporal) {
+ ChronoZonedDateTimeImpl<?> ensureChronoZonedDateTime(Temporal temporal) {
@SuppressWarnings("unchecked")
- ChronoZonedDateTimeImpl<C> other = (ChronoZonedDateTimeImpl<C>) temporal;
- if (this.equals(other.getDate().getChrono()) == false) {
- throw new ClassCastException("Chrono mismatch, required: " + getId()
- + ", supplied: " + other.getDate().getChrono().getId());
+ ChronoZonedDateTimeImpl<?> other = (ChronoZonedDateTimeImpl<?>) temporal;
+ if (this.equals(other.toLocalDate().getChronology()) == false) {
+ throw new ClassCastException("Chronology mismatch, required: " + getId()
+ + ", supplied: " + other.toLocalDate().getChronology().getId());
}
return other;
}
//-----------------------------------------------------------------------
/**
* Gets the ID of the chronology.
* <p>
- * The ID uniquely identifies the {@code Chrono}.
- * It can be used to lookup the {@code Chrono} using {@link #of(String)}.
+ * The ID uniquely identifies the {@code Chronology}.
+ * It can be used to lookup the {@code Chronology} using {@link #of(String)}.
*
* @return the chronology ID, not null
* @see #getCalendarType()
*/
public abstract String getId();
@@ -451,11 +466,11 @@
/**
* Gets the calendar type of the underlying calendar system.
* <p>
* The calendar type is an identifier defined by the
* <em>Unicode Locale Data Markup Language (LDML)</em> specification.
- * It can be used to lookup the {@code Chrono} using {@link #of(String)}.
+ * It can be used to lookup the {@code Chronology} 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()
@@ -472,11 +487,11 @@
* @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<C> date(Era<C> era, int yearOfEra, int month, int dayOfMonth) {
+ public ChronoLocalDate date(Era era, int yearOfEra, int month, int dayOfMonth) {
return date(prolepticYear(era, yearOfEra), month, dayOfMonth);
}
/**
* Obtains a local date in this chronology from the proleptic-year,
@@ -486,11 +501,11 @@
* @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 abstract ChronoLocalDate<C> date(int prolepticYear, int month, int dayOfMonth);
+ public abstract ChronoLocalDate date(int prolepticYear, int month, int dayOfMonth);
/**
* Obtains a local date in this chronology from the era, year-of-era and
* day-of-year fields.
*
@@ -498,11 +513,11 @@
* @param yearOfEra the chronology year-of-era
* @param dayOfYear the chronology day-of-year
* @return the local date in this chronology, not null
* @throws DateTimeException if unable to create the date
*/
- public ChronoLocalDate<C> dateYearDay(Era<C> era, int yearOfEra, int dayOfYear) {
+ public ChronoLocalDate dateYearDay(Era era, int yearOfEra, int dayOfYear) {
return dateYearDay(prolepticYear(era, yearOfEra), dayOfYear);
}
/**
* Obtains a local date in this chronology from the proleptic-year and
@@ -511,25 +526,11 @@
* @param prolepticYear the chronology proleptic-year
* @param dayOfYear the chronology day-of-year
* @return the local date in this chronology, not null
* @throws DateTimeException if unable to create the date
*/
- public abstract ChronoLocalDate<C> dateYearDay(int prolepticYear, int dayOfYear);
-
- /**
- * Obtains a local date in this chronology from another temporal object.
- * <p>
- * This creates a date in this chronology based on the specified {@code TemporalAccessor}.
- * <p>
- * 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<C> date(TemporalAccessor temporal);
+ public abstract ChronoLocalDate dateYearDay(int prolepticYear, int dayOfYear);
//-----------------------------------------------------------------------
/**
* Obtains the current local date in this chronology from the system clock in the default time-zone.
* <p>
@@ -542,11 +543,11 @@
* 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<C> dateNow() {
+ public ChronoLocalDate dateNow() {
return dateNow(Clock.systemDefaultZone());
}
/**
* Obtains the current local date in this chronology from the system clock in the specified time-zone.
@@ -559,11 +560,11 @@
*
* @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<C> dateNow(ZoneId zone) {
+ public ChronoLocalDate dateNow(ZoneId zone) {
return dateNow(Clock.system(zone));
}
/**
* Obtains the current local date in this chronology from the specified clock.
@@ -574,78 +575,113 @@
*
* @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<C> dateNow(Clock clock) {
+ public ChronoLocalDate dateNow(Clock clock) {
Objects.requireNonNull(clock, "clock");
return date(LocalDate.now(clock));
}
//-----------------------------------------------------------------------
/**
+ * Obtains a local date in this chronology from another temporal object.
+ * <p>
+ * This creates a date in this chronology based on the specified temporal.
+ * A {@code TemporalAccessor} represents an arbitrary set of date and time information,
+ * which this factory converts to an instance of {@code ChronoLocalDate}.
+ * <p>
+ * The conversion typically uses the {@link ChronoField#EPOCH_DAY EPOCH_DAY}
+ * field, which is standardized across calendar systems.
+ * <p>
+ * This method matches the signature of the functional interface {@link TemporalQuery}
+ * allowing it to be used as a query via method reference, {@code aChronology::date}.
+ *
+ * @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 date(TemporalAccessor temporal);
+
+ /**
* Obtains a local date-time in this chronology from another temporal object.
* <p>
- * This creates a date-time in this chronology based on the specified {@code TemporalAccessor}.
+ * This creates a date-time in this chronology based on the specified temporal.
+ * A {@code TemporalAccessor} represents an arbitrary set of date and time information,
+ * which this factory converts to an instance of {@code ChronoLocalDateTime}.
+ * <p>
+ * The conversion extracts and combines the {@code ChronoLocalDate} and the
+ * {@code LocalTime} from the temporal object.
+ * Implementations are permitted to perform optimizations such as accessing
+ * those fields that are equivalent to the relevant objects.
+ * The result uses this chronology.
* <p>
- * 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.
+ * This method matches the signature of the functional interface {@link TemporalQuery}
+ * allowing it to be used as a query via method reference, {@code aChronology::localDateTime}.
*
* @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<C> localDateTime(TemporalAccessor temporal) {
+ public ChronoLocalDateTime<?> localDateTime(TemporalAccessor temporal) {
try {
return date(temporal).atTime(LocalTime.from(temporal));
} catch (DateTimeException ex) {
throw new DateTimeException("Unable to obtain ChronoLocalDateTime from TemporalAccessor: " + temporal.getClass(), ex);
}
}
/**
- * Obtains a zoned date-time in this chronology from another temporal object.
+ * Obtains a {@code ChronoZonedDateTime} in this chronology from another temporal object.
* <p>
- * This creates a date-time in this chronology based on the specified {@code TemporalAccessor}.
+ * This creates a zoned date-time in this chronology based on the specified temporal.
+ * A {@code TemporalAccessor} represents an arbitrary set of date and time information,
+ * which this factory converts to an instance of {@code ChronoZonedDateTime}.
+ * <p>
+ * The conversion will first obtain a {@code ZoneId} from the temporal object,
+ * falling back to a {@code ZoneOffset} if necessary. It will then try to obtain
+ * an {@code Instant}, falling back to a {@code ChronoLocalDateTime} if necessary.
+ * The result will be either the combination of {@code ZoneId} or {@code ZoneOffset}
+ * with {@code Instant} or {@code ChronoLocalDateTime}.
+ * Implementations are permitted to perform optimizations such as accessing
+ * those fields that are equivalent to the relevant objects.
+ * The result uses this chronology.
* <p>
- * 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.
+ * This method matches the signature of the functional interface {@link TemporalQuery}
+ * allowing it to be used as a query via method reference, {@code aChronology::zonedDateTime}.
*
* @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<C> zonedDateTime(TemporalAccessor temporal) {
+ public ChronoZonedDateTime<?> zonedDateTime(TemporalAccessor temporal) {
try {
ZoneId zone = ZoneId.from(temporal);
try {
Instant instant = Instant.from(temporal);
return zonedDateTime(instant, zone);
} catch (DateTimeException ex1) {
- ChronoLocalDateTimeImpl<C> cldt = ensureChronoLocalDateTime(localDateTime(temporal));
+ ChronoLocalDateTimeImpl cldt = ensureChronoLocalDateTime(localDateTime(temporal));
return ChronoZonedDateTimeImpl.ofBest(cldt, zone, null);
}
} catch (DateTimeException ex) {
throw new DateTimeException("Unable to obtain ChronoZonedDateTime from TemporalAccessor: " + temporal.getClass(), ex);
}
}
/**
- * Obtains a zoned date-time in this chronology from an {@code Instant}.
+ * Obtains a {@code ChronoZonedDateTime} in this chronology from an {@code Instant}.
* <p>
* 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<C> zonedDateTime(Instant instant, ZoneId zone) {
+ public ChronoZonedDateTime<?> zonedDateTime(Instant instant, ZoneId zone) {
return ChronoZonedDateTimeImpl.ofInstant(this, instant, zone);
}
//-----------------------------------------------------------------------
/**
@@ -671,11 +707,11 @@
* @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<C> era, int yearOfEra);
+ public abstract int prolepticYear(Era era, int yearOfEra);
/**
* Creates the chronology era object from the numeric value.
* <p>
* The era is, conceptually, the largest division of the time-line.
@@ -692,22 +728,22 @@
*
* @param eraValue the era value
* @return the calendar system era, not null
* @throws DateTimeException if unable to create the era
*/
- public abstract Era<C> eraOf(int eraValue);
+ public abstract Era eraOf(int eraValue);
/**
* Gets the list of eras for the chronology.
* <p>
* 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<Era<C>> eras();
+ public abstract List<Era> eras();
//-----------------------------------------------------------------------
/**
* Gets the range of valid values for the specified field.
* <p>
@@ -728,19 +764,20 @@
//-----------------------------------------------------------------------
/**
* Gets the textual representation of this chronology.
* <p>
- * This returns the textual name used to identify the chronology.
+ * This returns the textual name used to identify the chronology,
+ * suitable for presentation to the user.
* 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() {
+ public String getDisplayName(TextStyle style, Locale locale) {
+ return new DateTimeFormatterBuilder().appendChronologyText(style).toFormatter(locale).format(new TemporalAccessor() {
@Override
public boolean isSupported(TemporalField field) {
return false;
}
@Override
@@ -748,12 +785,12 @@
throw new DateTimeException("Unsupported field: " + field);
}
@SuppressWarnings("unchecked")
@Override
public <R> R query(TemporalQuery<R> query) {
- if (query == Queries.chrono()) {
- return (R) Chrono.this;
+ if (query == Queries.chronology()) {
+ return (R) Chronology.this;
}
return TemporalAccessor.super.query(query);
}
});
}
@@ -771,31 +808,31 @@
*
* @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) {
+ public int compareTo(Chronology other) {
return getId().compareTo(other.getId());
}
/**
* Checks if this chronology is equal to another chronology.
* <p>
* The comparison is based on the entire state of the object.
* <p>
- * The default implementation checks the type and calls {@link #compareTo(Chrono)}.
+ * The default implementation checks the type and calls {@link #compareTo(Chronology)}.
*
* @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;
+ if (obj instanceof Chronology) {
+ return compareTo((Chronology) obj) == 0;
}
return false;
}
/**
@@ -825,11 +862,11 @@
//-----------------------------------------------------------------------
/**
* Writes the object using a
* <a href="../../../serialized-form.html#java.time.temporal.Ser">dedicated serialized form</a>.
* <pre>
- * out.writeByte(7); // identifies this as a Chrono
+ * out.writeByte(7); // identifies this as a Chronology
* out.writeUTF(chronoId);
* </pre>
*
* @return the instance of {@code Ser}, not null
*/
@@ -848,11 +885,11 @@
void writeExternal(DataOutput out) throws IOException {
out.writeUTF(getId());
}
- static Chrono<?> readExternal(DataInput in) throws IOException {
+ static Chronology readExternal(DataInput in) throws IOException {
String id = in.readUTF();
- return Chrono.of(id);
+ return Chronology.of(id);
}
}