OpenJDK 1.23 · java.time.chrono · APIdia, the JavaDoc alternative

Generic API for calendar systems other than the default ISO.

The main API is based around the calendar system defined in ISO-8601. However, there are other calendar systems, and this package provides basic support for them. The alternate calendars are provided in the java.time.chrono package.

A calendar system is defined by the java.time.chrono.Chronology interface, while a date in a calendar system is defined by the java.time.chrono.ChronoLocalDate interface.

It is intended that applications use the main API whenever possible, including code to read and write from a persistent data store, such as a database, and to send dates and times across a network. The "chrono" classes are then used at the user interface level to deal with localized input/output. See ChronoLocalDate for a full discussion of the issues.

Using non-ISO calendar systems in an application introduces significant extra complexity. Ensure that the warnings and recommendations in ChronoLocalDate have been read before working with the "chrono" interfaces.

The supported calendar systems includes:

Example

This example lists today's date for all of the available calendars.

  // Enumerate the list of available calendars and print today's date for each.
      Set<Chronology> chronos = Chronology.getAvailableChronologies();
      for (Chronology chrono : chronos) {
          ChronoLocalDate date = chrono.dateNow();
          System.out.printf("   %20s: %s%n", chrono.getId(), date.toString());
      }

This example creates and uses a date in a named non-ISO calendar system.

  // Print the Thai Buddhist date
      ChronoLocalDate now1 = Chronology.of("ThaiBuddhist").dateNow();
      int day = now1.get(ChronoField.DAY_OF_MONTH);
      int dow = now1.get(ChronoField.DAY_OF_WEEK);
      int month = now1.get(ChronoField.MONTH_OF_YEAR);
      int year = now1.get(ChronoField.YEAR);
      System.out.printf("  Today is %s %s %d-%s-%d%n", now1.getChronology().getId(),
                dow, day, month, year);
  // Print today's date and the last day of the year for the Thai Buddhist Calendar.
      ChronoLocalDate first = now1
                .with(ChronoField.DAY_OF_MONTH, 1)
                .with(ChronoField.MONTH_OF_YEAR, 1);
      ChronoLocalDate last = first
                .plus(1, ChronoUnit.YEARS)
                .minus(1, ChronoUnit.DAYS);
      System.out.printf("  %s: 1st of year: %s; end of year: %s%n", last.getChronology().getId(),
                first, last);

This example creates and uses a date in a specific ThaiBuddhist calendar system.

  // Print the Thai Buddhist date
      ThaiBuddhistDate now1 = ThaiBuddhistDate.now();
      int day = now1.get(ChronoField.DAY_OF_MONTH);
      int dow = now1.get(ChronoField.DAY_OF_WEEK);
      int month = now1.get(ChronoField.MONTH_OF_YEAR);
      int year = now1.get(ChronoField.YEAR);
      System.out.printf("  Today is %s %s %d-%s-%d%n", now1.getChronology().getId(),
                dow, day, month, year);

  // Print today's date and the last day of the year for the Thai Buddhist Calendar.
      ThaiBuddhistDate first = now1
                .with(ChronoField.DAY_OF_MONTH, 1)
                .with(ChronoField.MONTH_OF_YEAR, 1);
      ThaiBuddhistDate last = first
                .plus(1, ChronoUnit.YEARS)
                .minus(1, ChronoUnit.DAYS);
      System.out.printf("  %s: 1st of year: %s; end of year: %s%n", last.getChronology().getId(),
                first, last);

Package specification

Unless otherwise noted, passing a null argument to a constructor or method in any class or interface in this package will cause a NullPointerException to be thrown. The Javadoc "@param" definition is used to summarise the null-behavior. The "@throws java.lang.NullPointerException" is not explicitly documented in each method.

All calculations should check for numeric overflow and throw either an java.lang.ArithmeticException or a java.time.DateTimeException.

Interface Summary

Modifier and Type	Interface and Description
public interface	ChronoLocalDate A date without time-of-day or time-zone in an arbitrary chronology, intended for advanced globalization use cases.
public interface	ChronoLocalDateTime< the concrete type for the date of this date-time D extends ChronoLocalDate> A date-time without a time-zone in an arbitrary chronology, intended for advanced globalization use cases.
public interface	Chronology A calendar system, used to organize and identify dates.
public interface	ChronoPeriod A date-based amount of time, such as '3 years, 4 months and 5 days' in an arbitrary chronology, intended for advanced globalization use cases.
public interface	ChronoZonedDateTime< the concrete type for the date of this date-time D extends ChronoLocalDate> A date-time with a time-zone in an arbitrary chronology, intended for advanced globalization use cases.
public interface	Era An era of the time-line.

Class Summary

Modifier and Type	Class and Description
public abstract class	AbstractChronology An abstract implementation of a calendar system, used to organize and identify dates.
pack-priv abstract class	ChronoLocalDateImpl< the ChronoLocalDate of this date-time D extends ChronoLocalDate> A date expressed in terms of a standard year-month-day calendar system.
pack-priv class	ChronoLocalDateTimeImpl< the concrete type for the date of this date-time D extends ChronoLocalDate> A date-time without a time-zone for the calendar neutral API.
pack-priv class	ChronoPeriodImpl A period expressed in terms of a standard year-month-day calendar system.
pack-priv class	ChronoZonedDateTimeImpl< the concrete type for the date of this date-time D extends ChronoLocalDate> A date-time with a time-zone in the calendar neutral API.
public class	HijrahChronology The Hijrah calendar is a lunar calendar supporting Islamic calendars.
public class	HijrahDate A date in the Hijrah calendar system.
public class	IsoChronology The ISO calendar system.
public class	JapaneseChronology The Japanese Imperial calendar system.
public class	JapaneseDate A date in the Japanese Imperial calendar system.
public class	JapaneseEra An era in the Japanese Imperial calendar system.
public class	MinguoChronology The Minguo calendar system.
public class	MinguoDate A date in the Minguo calendar system.
pack-priv class	Ser The shared serialization delegate for this package.
public class	ThaiBuddhistChronology The Thai Buddhist calendar system.
public class	ThaiBuddhistDate A date in the Thai Buddhist calendar system.

Modifier and Type	Enum and Description
public enum	HijrahEra An era in the Hijrah calendar system.
public enum	IsoEra An era in the ISO calendar system.
public enum	MinguoEra An era in the Minguo calendar system.
public enum	ThaiBuddhistEra An era in the Thai Buddhist calendar system.

Package java.time.chrono

Example

Package specification

Interface Summary

Class Summary

Enum Summary