src/share/classes/java/time/overview.html

Print this page




  71     <p>
  72         The Java Time API is composed of several packages, each with a primary function:
  73     </p>
  74     <p>
  75         {@link java.time} contains the main API based on the ISO-8601 standard.
  76         The classes defined here represent the principal date-time concepts,
  77         including instants, durations, dates, times, time-zones and periods.
  78         They are based on the ISO calendar system, which is the <i>de facto</i> world
  79         calendar following the proleptic Gregorian rules.
  80         All the classes are immutable and thread-safe.
  81     </p>
  82     <p>
  83         {@link java.time.temporal} contains the API for accessing the fields and units
  84         of date-time. Units are measurable, such as years, months and hours.
  85         For example, the expression "2 hours later" uses the hours unit.
  86         By contrast, fields are mini-calculations, defining a value.
  87         For example, month-of-year, day-of-week and hour-of-day are all fields.
  88         The set of supported units and fields can be extended by applications if desired.
  89     </p>
  90     <p>
  91         It also contains the basic part of the calendar neutral API.
  92         This is intended for use by applications that need to use localized calendars.
  93         Ensure that you read the class documentation of {@link java.time.temporal.ChronoLocalDate}
  94         before using non-ISO calendar systems.
  95     </p>
  96     <p>
  97         {@link java.time.format} contains the API to print and parse fields into date-time
  98         objects and to customize parsing and printing.
  99         Formatters can be created in a variety of ways, including constants, patterns,
 100         localized styles and a builder.
 101         Formatters are immutable and thread-safe.
 102     </p>
 103     <p>
 104         {@link java.time.zone} contains the API to handle time-zones.
 105         Detailed information is made available about the rules of each time-zone.
 106     </p>
 107     <p>
 108         The {@link java.time.calendar} package contains alternate calendar systems.

 109         This is intended for use by applications that need to use localized calendars.
 110         Support is provided for the Hijrah, Japanese, Minguo, and Thai Buddhist Calendars.
 111     </p>
 112     <h3>Design notes</h3>
 113     <p>
 114         Where possible, the API avoids the use of null.
 115         All methods define whether they accept or return null in the Javadoc.
 116         As a general rule, methods do not accept or return null.
 117         A key exception is any method that takes an object and returns a boolean, for the purpose
 118         of checking or validating, will generally return false for null.
 119     </p>
 120     <p>
 121         The API is designed to be type-safe where reasonable in the main high-level API.
 122         Thus, there are separate classes for the distinct concepts of date, time and date-time, plus variants
 123         for offset and time-zones. The core 7 date-time classes, plus Instant, handle the needs of most applications.
 124         Further classes handle other combinations - year, year-month and month-day in a type-safe manner.
 125     </p>
 126     <p>
 127         In a language like Java, the use of many different types tends to cause API bloat.
 128         This is handled here through the use of common method naming patterns throughout the API.
 129         The common prefixes are 'of', 'get', 'is', 'with', 'plus', 'minus', 'to' and 'at'.
 130         See {@link java.time.LocalDate} for an example of each of these methods.
 131     </p>
 132     <p>
 133         Following type-safety to its logical conclusion would result in more classes, especially for time -
 134         hour-minute, hour-minute-second and hour-minute-second-nanosecond.
 135         While logically pure, this was not possible in practice, as the additional classes would have
 136         excessively complicated the API. Notably, there would be additional combinations at the offset
 137         and date-time levels, such as offset-date-hour-minute.
 138         To avoid this explosion of types, {@link java.time.LocalTime} is used for all precisions of time.
 139         By contrast, some additional classes were used for dates, such as {@link java.time.temporal.YearMonth}.
 140         This proved necessary, as the API for year-month is significantly different to that for a date, whereas
 141         an absence of nanoseconds in a time can be approximated by returning zero.
 142     </p>
 143     <p>
 144         Similarly, full type-safety might argue for a separate class for each field in date-time,
 145         such as a class for HourOfDay and another for DayOfMonth.
 146         This approach was tried, but was excessively complicated in the Java language, lacking usability.
 147         A similar problem occurs with periods.
 148         There is a case for a separate class for each period unit, such as a type for Years and a type for Minutes.
 149         However, this yields a lot of classes and a problem of type conversion.
 150         As such, general access to fields and units is not wrapped in a class.
 151     </p>
 152     <p>
 153         Multiple calendar systems is an awkward addition to the design challenges.
 154         The first principal is that most users want the standard ISO calendar system.
 155         As such, the main classes are ISO-only. The second principal is that most of those that want a
 156         non-ISO calendar system want it for user interaction, thus it is a UI localization issue.
 157         As such, date and time objects should be held as ISO objects in the data model and persistent
 158         storage, only being converted to and from a local calendar for display.
 159         The calendar system would be stored separately in the user preferences.
 160     </p>
 161     <p>
 162         There are, however, some limited use cases where users believe they need to store and use
 163         dates in arbitrary calendar systems throughout the application.
 164         This is supported by {@link java.time.temporal.ChronoLocalDate}, however it is vital to read
 165         all the associated warnings in the Javadoc of that interface before using it.
 166         In summary, applications that require general interoperation between multiple calendar systems
 167         typically need to be written in a very different way to those only using the ISO calendar,
 168         thus most applications should just use ISO and avoid {@code ChronoLocalDate}.
 169     </p>
 170     <p>
 171         Throughout all of this, a key goal was to allow date-time fields and units to be defined by applications.
 172         This has been achieved having tried many different designs.
 173     </p>
 174 </body>


  71     <p>
  72         The Java Time API is composed of several packages, each with a primary function:
  73     </p>
  74     <p>
  75         {@link java.time} contains the main API based on the ISO-8601 standard.
  76         The classes defined here represent the principal date-time concepts,
  77         including instants, durations, dates, times, time-zones and periods.
  78         They are based on the ISO calendar system, which is the <i>de facto</i> world
  79         calendar following the proleptic Gregorian rules.
  80         All the classes are immutable and thread-safe.
  81     </p>
  82     <p>
  83         {@link java.time.temporal} contains the API for accessing the fields and units
  84         of date-time. Units are measurable, such as years, months and hours.
  85         For example, the expression "2 hours later" uses the hours unit.
  86         By contrast, fields are mini-calculations, defining a value.
  87         For example, month-of-year, day-of-week and hour-of-day are all fields.
  88         The set of supported units and fields can be extended by applications if desired.
  89     </p>
  90     <p>






  91         {@link java.time.format} contains the API to print and parse fields into date-time
  92         objects and to customize parsing and printing.
  93         Formatters can be created in a variety of ways, including constants, patterns,
  94         localized styles and a builder.
  95         Formatters are immutable and thread-safe.
  96     </p>
  97     <p>
  98         {@link java.time.zone} contains the API to handle time-zones.
  99         Detailed information is made available about the rules of each time-zone.
 100     </p>
 101     <p>
 102         {@link java.time.chrono} contains the basic part of the calendar neutral API
 103         and alternate calendar systems.
 104         This is intended for use by applications that need to use localized calendars.
 105         Support is provided for the Hijrah, Japanese, Minguo, and Thai Buddhist Calendars.
 106     </p>
 107     <h3>Design notes</h3>
 108     <p>
 109         Where possible, the API avoids the use of null.
 110         All methods define whether they accept or return null in the Javadoc.
 111         As a general rule, methods do not accept or return null.
 112         A key exception is any method that takes an object and returns a boolean, for the purpose
 113         of checking or validating, will generally return false for null.
 114     </p>
 115     <p>
 116         The API is designed to be type-safe where reasonable in the main high-level API.
 117         Thus, there are separate classes for the distinct concepts of date, time and date-time, plus variants
 118         for offset and time-zones. The core 7 date-time classes, plus Instant, handle the needs of most applications.
 119         Further classes handle other combinations - year, year-month and month-day in a type-safe manner.
 120     </p>
 121     <p>
 122         In a language like Java, the use of many different types tends to cause API bloat.
 123         This is handled here through the use of common method naming patterns throughout the API.
 124         The common prefixes are 'of', 'get', 'is', 'with', 'plus', 'minus', 'to' and 'at'.
 125         See {@link java.time.LocalDate} for an example of each of these methods.
 126     </p>
 127     <p>
 128         Following type-safety to its logical conclusion would result in more classes, especially for time -
 129         hour-minute, hour-minute-second and hour-minute-second-nanosecond.
 130         While logically pure, this was not possible in practice, as the additional classes would have
 131         excessively complicated the API. Notably, there would be additional combinations at the offset
 132         and date-time levels, such as offset-date-hour-minute.
 133         To avoid this explosion of types, {@link java.time.LocalTime} is used for all precisions of time.
 134         By contrast, some additional classes were used for dates, such as {@link java.time.YearMonth}.
 135         This proved necessary, as the API for year-month is significantly different to that for a date, whereas
 136         an absence of nanoseconds in a time can be approximated by returning zero.
 137     </p>
 138     <p>
 139         Similarly, full type-safety might argue for a separate class for each field in date-time,
 140         such as a class for HourOfDay and another for DayOfMonth.
 141         This approach was tried, but was excessively complicated in the Java language, lacking usability.
 142         A similar problem occurs with periods.
 143         There is a case for a separate class for each period unit, such as a type for Years and a type for Minutes.
 144         However, this yields a lot of classes and a problem of type conversion.
 145         As such, general access to fields and units is not wrapped in a class.
 146     </p>
 147     <p>
 148         Multiple calendar systems is an awkward addition to the design challenges.
 149         The first principal is that most users want the standard ISO calendar system.
 150         As such, the main classes are ISO-only. The second principal is that most of those that want a
 151         non-ISO calendar system want it for user interaction, thus it is a UI localization issue.
 152         As such, date and time objects should be held as ISO objects in the data model and persistent
 153         storage, only being converted to and from a local calendar for display.
 154         The calendar system would be stored separately in the user preferences.
 155     </p>
 156     <p>
 157         There are, however, some limited use cases where users believe they need to store and use
 158         dates in arbitrary calendar systems throughout the application.
 159         This is supported by {@link java.time.chrono.ChronoLocalDate}, however it is vital to read
 160         all the associated warnings in the Javadoc of that interface before using it.
 161         In summary, applications that require general interoperation between multiple calendar systems
 162         typically need to be written in a very different way to those only using the ISO calendar,
 163         thus most applications should just use ISO and avoid {@code ChronoLocalDate}.
 164     </p>
 165     <p>
 166         Throughout all of this, a key goal was to allow date-time fields and units to be defined by applications.
 167         This has been achieved having tried many different designs.
 168     </p>
 169 </body>