src/share/classes/java/time/package-info.java

Print this page




  62 
  63 /**
  64  * <p>
  65  * The main API for dates, times, instants, and durations.
  66  * </p>
  67  * <p>
  68  * The classes defined here represent the principal date-time concepts,
  69  * including instants, durations, dates, times, time-zones and periods.
  70  * They are based on the ISO calendar system, which is the <i>de facto</i> world
  71  * calendar following the proleptic Gregorian rules.
  72  * All the classes are immutable and thread-safe.
  73  * </p>
  74  * <p>
  75  * Each date time instance is composed of fields that are conveniently
  76  * made available by the APIs.  For lower level access to the fields refer
  77  * to the {@code java.time.temporal} package.
  78  * Each class includes support for printing and parsing all manner of dates and times.
  79  * Refer to the {@code java.time.format} package for customization options.
  80  * </p>
  81  * <p>
  82  * The {@code java.time.temporal} package also contains the calendar neutral API
  83  * {@link java.time.temporal.ChronoLocalDate ChronoLocalDate},
  84  * {@link java.time.temporal.ChronoLocalDateTime ChronoLocalDateTime},
  85  * {@link java.time.temporal.ChronoZonedDateTime ChronoZonedDateTime} and
  86  * {@link java.time.temporal.Era Era}.
  87  * This is intended for use by applications that need to use localized calendars.
  88  * It is recommended that applications use the ISO-8601 dates and time classes from
  89  * this package across system boundaries, such as to the database or across the network.
  90  * The calendar neutral API should be reserved for interactions with users.
  91  * </p>
  92  *
  93  * <h3>Dates and Times</h3>
  94  * <p>
  95  * {@link java.time.Instant} is essentially a numeric timestamp.
  96  * The current Instant can be retrieved from a {@link java.time.Clock}.
  97  * This is useful for logging and persistence of a point in time
  98  * and has in the past been associated with storing the result
  99  * from {@link java.lang.System#currentTimeMillis()}.
 100  * </p>
 101  * <p>
 102  * {@link java.time.LocalDate} stores a date without a time.
 103  * This stores a date like '2010-12-03' and could be used to store a birthday.
 104  * </p>
 105  * <p>
 106  * {@link java.time.LocalTime} stores a time without a date.
 107  * This stores a time like '11:30' and could be used to store an opening or closing time.
 108  * </p>


 118  * The widespread use of time-zones tends to add considerable complexity to an application.
 119  * </p>
 120  *
 121  * <h3>Duration and Period</h3>
 122  * <p>
 123  * Beyond dates and times, the API also allows the storage of period and durations of time.
 124  * A {@link java.time.Duration} is a simple measure of time along the time-line in nanoseconds.
 125  * A {@link java.time.Period} expresses an amount of time in units meaningful to humans, such as years or hours.
 126  * </p>
 127  *
 128  * <h3>Additional value types</h3>
 129  * <p>
 130  * {@link java.time.Month} stores a month on its own.
 131  * This stores a single month-of-year in isolation, such as 'DECEMBER'.
 132  * </p>
 133  * <p>
 134  * {@link java.time.DayOfWeek} stores a day-of-week on its own.
 135  * This stores a single day-of-week in isolation, such as 'TUESDAY'.
 136  * </p>
 137  * <p>
 138  * {@link java.time.temporal.Year} stores a year on its own.
 139  * This stores a single year in isolation, such as '2010'.
 140  * </p>
 141  * <p>
 142  * {@link java.time.temporal.YearMonth} stores a year and month without a day or time.
 143  * This stores a year and month, such as '2010-12' and could be used for a credit card expiry.
 144  * </p>
 145  * <p>
 146  * {@link java.time.temporal.MonthDay} stores a month and day without a year or time.
 147  * This stores a month and day-of-month, such as '--12-03' and
 148  * could be used to store an annual event like a birthday without storing the year.
 149  * </p>
 150  * <p>
 151  * {@link java.time.temporal.OffsetTime} stores a time and offset from UTC without a date.
 152  * This stores a date like '11:30+01:00'.
 153  * The {@link java.time.ZoneOffset ZoneOffset} is of the form '+01:00'.
 154  * </p>
 155  * <p>
 156  * {@link java.time.temporal.OffsetDate} stores a date and offset from UTC without a time.
 157  * This stores a time like '2010-12-03+01:00'.
 158  * </p>
 159  * <p>
 160  * {@link java.time.temporal.OffsetDateTime} stores a date and time and offset from UTC.
 161  * This stores a date-time like '2010-12-03T11:30+01:00'.
 162  * This is sometimes found in XML messages and other forms of persistence,
 163  * but contains less information than a full time-zone.
 164  * </p>
 165  *
 166  * <h3>Package specification</h3>
 167  * <p>
 168  * Unless otherwise noted, passing a null argument to a constructor or method in any class or interface
 169  * in this package will cause a {@link java.lang.NullPointerException NullPointerException} to be thrown.
 170  * The Javadoc "@param" definition is used to summarise the null-behavior.
 171  * The "@throws {@link java.lang.NullPointerException}" is not explicitly documented in each method.
 172  * </p>
 173  * <p>
 174  * All calculations should check for numeric overflow and throw either an {@link java.lang.ArithmeticException}
 175  * or a {@link java.time.DateTimeException}.
 176  * </p>
 177  *
 178  * <h3>Design notes (non normative)</h3>
 179  * <p>
 180  * The API has been designed to reject null early and to be clear about this behavior.


 189  * <ul>
 190  * <li>{@link java.time.Instant} - a timestamp</li>
 191  * <li>{@link java.time.LocalDate} - a date without a time, or any reference to an offset or time-zone</li>
 192  * <li>{@link java.time.LocalTime} - a time without a date, or any reference to an offset or time-zone</li>
 193  * <li>{@link java.time.LocalDateTime} - combines date and time, but still without any offset or time-zone</li>
 194  * <li>{@link java.time.ZonedDateTime} - a "full" date-time with time-zone and resolved offset from UTC/Greenwich</li>
 195  * </ul>
 196  * <p>
 197  * {@code Instant} is the closest equivalent class to {@code java.util.Date}.
 198  * {@code ZonedDateTime} is the closest equivalent class to {@code java.util.GregorianCalendar}.
 199  * </p>
 200  * <p>
 201  * Where possible, applications should use {@code LocalDate}, {@code LocalTime} and {@code LocalDateTime}
 202  * to better model the domain. For example, a birthday should be stored in a code {@code LocalDate}.
 203  * Bear in mind that any use of a {@linkplain java.time.ZoneId time-zone}, such as 'Europe/Paris', adds
 204  * considerable complexity to a calculation.
 205  * Many applications can be written only using {@code LocalDate}, {@code LocalTime} and {@code Instant},
 206  * with the time-zone added at the user interface (UI) layer.
 207  * </p>
 208  * <p>
 209  * The offset-based date-time types, {@code OffsetDate}, {@code OffsetTime} and {@code OffsetDateTime},
 210  * are intended primarily for use with network protocols and database access.
 211  * For example, most databases cannot automatically store a time-zone like 'Europe/Paris', but
 212  * they can store an offset like '+02:00'.
 213  * </p>
 214  * <p>
 215  * Classes are also provided for the most important sub-parts of a date, including {@code Month},
 216  * {@code DayOfWeek}, {@code Year}, {@code YearMonth} and {@code MonthDay}.
 217  * These can be used to model more complex date-time concepts.
 218  * For example, {@code YearMonth} is useful for representing a credit card expiry.
 219  * </p>
 220  * <p>
 221  * Note that while there are a large number of classes representing different aspects of dates,
 222  * there are relatively few dealing with different aspects of time.
 223  * Following type-safety to its logical conclusion would have resulted in classes for
 224  * hour-minute, hour-minute-second and hour-minute-second-nanosecond.
 225  * While logically pure, this was not a practical option as it would have almost tripled the
 226  * number of classes due to the combinations of date and time.
 227  * Thus, {@code LocalTime} is used for all precisions of time, with zeroes used to imply lower precision.
 228  * </p>
 229  * <p>


 244  * <li>{@code get} - gets the value of something</li>
 245  * <li>{@code is} - checks if something is true</li>
 246  * <li>{@code with} - the immutable equivalent of a setter</li>
 247  * <li>{@code plus} - adds an amount to an object</li>
 248  * <li>{@code minus} - subtracts an amount from an object</li>
 249  * <li>{@code to} - converts this object to another type</li>
 250  * <li>{@code at} - combines this object with another, such as {@code date.atTime(time)}</li>
 251  * </ul>
 252  * <p>
 253  * Multiple calendar systems is an awkward addition to the design challenges.
 254  * The first principal is that most users want the standard ISO calendar system.
 255  * As such, the main classes are ISO-only. The second principal is that most of those that want a
 256  * non-ISO calendar system want it for user interaction, thus it is a UI localization issue.
 257  * As such, date and time objects should be held as ISO objects in the data model and persistent
 258  * storage, only being converted to and from a local calendar for display.
 259  * The calendar system would be stored separately in the user preferences.
 260  * </p>
 261  * <p>
 262  * There are, however, some limited use cases where users believe they need to store and use
 263  * dates in arbitrary calendar systems throughout the application.
 264  * This is supported by {@link java.time.temporal.ChronoLocalDate}, however it is vital to read
 265  * all the associated warnings in the Javadoc of that interface before using it.
 266  * In summary, applications that require general interoperation between multiple calendar systems
 267  * typically need to be written in a very different way to those only using the ISO calendar,
 268  * thus most applications should just use ISO and avoid {@code ChronoLocalDate}.
 269  * </p>
 270  * <p>
 271  * The API is also designed for user extensibility, as there are many ways of calculating time.
 272  * The {@linkplain java.time.temporal.TemporalField field} and {@linkplain java.time.temporal.TemporalUnit unit}
 273  * API, accessed via {@link java.time.temporal.TemporalAccessor TemporalAccessor} and
 274  * {@link java.time.temporal.Temporal Temporal} provide considerable flexibility to applications.
 275  * In addition, the {@link java.time.temporal.TemporalQuery TemporalQuery} and
 276  * {@link java.time.temporal.TemporalAdjuster TemporalAdjuster} interfaces provide day-to-day
 277  * power, allowing code to read close to business requirements:
 278  * </p>
 279  * <pre>
 280  *   LocalDate customerBirthday = customer.loadBirthdayFromDatabase();
 281  *   LocalDate today = LocalDate.now();
 282  *   if (customerBirthday.equals(today)) {
 283  *     LocalDate specialOfferExpiryDate = today.plusWeeks(2).with(next(FRIDAY));
 284  *     customer.sendBirthdaySpecialOffer(specialOfferExpiryDate);


  62 
  63 /**
  64  * <p>
  65  * The main API for dates, times, instants, and durations.
  66  * </p>
  67  * <p>
  68  * The classes defined here represent the principal date-time concepts,
  69  * including instants, durations, dates, times, time-zones and periods.
  70  * They are based on the ISO calendar system, which is the <i>de facto</i> world
  71  * calendar following the proleptic Gregorian rules.
  72  * All the classes are immutable and thread-safe.
  73  * </p>
  74  * <p>
  75  * Each date time instance is composed of fields that are conveniently
  76  * made available by the APIs.  For lower level access to the fields refer
  77  * to the {@code java.time.temporal} package.
  78  * Each class includes support for printing and parsing all manner of dates and times.
  79  * Refer to the {@code java.time.format} package for customization options.
  80  * </p>
  81  * <p>
  82  * The {@code java.time.chrono} package contains the calendar neutral API
  83  * {@link java.time.chrono.ChronoLocalDate ChronoLocalDate},
  84  * {@link java.time.chrono.ChronoLocalDateTime ChronoLocalDateTime},
  85  * {@link java.time.chrono.ChronoZonedDateTime ChronoZonedDateTime} and
  86  * {@link java.time.chrono.Era Era}.
  87  * This is intended for use by applications that need to use localized calendars.
  88  * It is recommended that applications use the ISO-8601 date and time classes from
  89  * this package across system boundaries, such as to the database or across the network.
  90  * The calendar neutral API should be reserved for interactions with users.
  91  * </p>
  92  *
  93  * <h3>Dates and Times</h3>
  94  * <p>
  95  * {@link java.time.Instant} is essentially a numeric timestamp.
  96  * The current Instant can be retrieved from a {@link java.time.Clock}.
  97  * This is useful for logging and persistence of a point in time
  98  * and has in the past been associated with storing the result
  99  * from {@link java.lang.System#currentTimeMillis()}.
 100  * </p>
 101  * <p>
 102  * {@link java.time.LocalDate} stores a date without a time.
 103  * This stores a date like '2010-12-03' and could be used to store a birthday.
 104  * </p>
 105  * <p>
 106  * {@link java.time.LocalTime} stores a time without a date.
 107  * This stores a time like '11:30' and could be used to store an opening or closing time.
 108  * </p>


 118  * The widespread use of time-zones tends to add considerable complexity to an application.
 119  * </p>
 120  *
 121  * <h3>Duration and Period</h3>
 122  * <p>
 123  * Beyond dates and times, the API also allows the storage of period and durations of time.
 124  * A {@link java.time.Duration} is a simple measure of time along the time-line in nanoseconds.
 125  * A {@link java.time.Period} expresses an amount of time in units meaningful to humans, such as years or hours.
 126  * </p>
 127  *
 128  * <h3>Additional value types</h3>
 129  * <p>
 130  * {@link java.time.Month} stores a month on its own.
 131  * This stores a single month-of-year in isolation, such as 'DECEMBER'.
 132  * </p>
 133  * <p>
 134  * {@link java.time.DayOfWeek} stores a day-of-week on its own.
 135  * This stores a single day-of-week in isolation, such as 'TUESDAY'.
 136  * </p>
 137  * <p>
 138  * {@link java.time.Year} stores a year on its own.
 139  * This stores a single year in isolation, such as '2010'.
 140  * </p>
 141  * <p>
 142  * {@link java.time.YearMonth} stores a year and month without a day or time.
 143  * This stores a year and month, such as '2010-12' and could be used for a credit card expiry.
 144  * </p>
 145  * <p>
 146  * {@link java.time.MonthDay} stores a month and day without a year or time.
 147  * This stores a month and day-of-month, such as '--12-03' and
 148  * could be used to store an annual event like a birthday without storing the year.
 149  * </p>
 150  * <p>
 151  * {@link java.time.OffsetTime} stores a time and offset from UTC without a date.
 152  * This stores a date like '11:30+01:00'.
 153  * The {@link java.time.ZoneOffset ZoneOffset} is of the form '+01:00'.
 154  * </p>
 155  * <p>
 156  * {@link java.time.OffsetDateTime} stores a date and time and offset from UTC.




 157  * This stores a date-time like '2010-12-03T11:30+01:00'.
 158  * This is sometimes found in XML messages and other forms of persistence,
 159  * but contains less information than a full time-zone.
 160  * </p>
 161  *
 162  * <h3>Package specification</h3>
 163  * <p>
 164  * Unless otherwise noted, passing a null argument to a constructor or method in any class or interface
 165  * in this package will cause a {@link java.lang.NullPointerException NullPointerException} to be thrown.
 166  * The Javadoc "@param" definition is used to summarise the null-behavior.
 167  * The "@throws {@link java.lang.NullPointerException}" is not explicitly documented in each method.
 168  * </p>
 169  * <p>
 170  * All calculations should check for numeric overflow and throw either an {@link java.lang.ArithmeticException}
 171  * or a {@link java.time.DateTimeException}.
 172  * </p>
 173  *
 174  * <h3>Design notes (non normative)</h3>
 175  * <p>
 176  * The API has been designed to reject null early and to be clear about this behavior.


 185  * <ul>
 186  * <li>{@link java.time.Instant} - a timestamp</li>
 187  * <li>{@link java.time.LocalDate} - a date without a time, or any reference to an offset or time-zone</li>
 188  * <li>{@link java.time.LocalTime} - a time without a date, or any reference to an offset or time-zone</li>
 189  * <li>{@link java.time.LocalDateTime} - combines date and time, but still without any offset or time-zone</li>
 190  * <li>{@link java.time.ZonedDateTime} - a "full" date-time with time-zone and resolved offset from UTC/Greenwich</li>
 191  * </ul>
 192  * <p>
 193  * {@code Instant} is the closest equivalent class to {@code java.util.Date}.
 194  * {@code ZonedDateTime} is the closest equivalent class to {@code java.util.GregorianCalendar}.
 195  * </p>
 196  * <p>
 197  * Where possible, applications should use {@code LocalDate}, {@code LocalTime} and {@code LocalDateTime}
 198  * to better model the domain. For example, a birthday should be stored in a code {@code LocalDate}.
 199  * Bear in mind that any use of a {@linkplain java.time.ZoneId time-zone}, such as 'Europe/Paris', adds
 200  * considerable complexity to a calculation.
 201  * Many applications can be written only using {@code LocalDate}, {@code LocalTime} and {@code Instant},
 202  * with the time-zone added at the user interface (UI) layer.
 203  * </p>
 204  * <p>
 205  * The offset-based date-time types {@code OffsetTime} and {@code OffsetDateTime},
 206  * are intended primarily for use with network protocols and database access.
 207  * For example, most databases cannot automatically store a time-zone like 'Europe/Paris', but
 208  * they can store an offset like '+02:00'.
 209  * </p>
 210  * <p>
 211  * Classes are also provided for the most important sub-parts of a date, including {@code Month},
 212  * {@code DayOfWeek}, {@code Year}, {@code YearMonth} and {@code MonthDay}.
 213  * These can be used to model more complex date-time concepts.
 214  * For example, {@code YearMonth} is useful for representing a credit card expiry.
 215  * </p>
 216  * <p>
 217  * Note that while there are a large number of classes representing different aspects of dates,
 218  * there are relatively few dealing with different aspects of time.
 219  * Following type-safety to its logical conclusion would have resulted in classes for
 220  * hour-minute, hour-minute-second and hour-minute-second-nanosecond.
 221  * While logically pure, this was not a practical option as it would have almost tripled the
 222  * number of classes due to the combinations of date and time.
 223  * Thus, {@code LocalTime} is used for all precisions of time, with zeroes used to imply lower precision.
 224  * </p>
 225  * <p>


 240  * <li>{@code get} - gets the value of something</li>
 241  * <li>{@code is} - checks if something is true</li>
 242  * <li>{@code with} - the immutable equivalent of a setter</li>
 243  * <li>{@code plus} - adds an amount to an object</li>
 244  * <li>{@code minus} - subtracts an amount from an object</li>
 245  * <li>{@code to} - converts this object to another type</li>
 246  * <li>{@code at} - combines this object with another, such as {@code date.atTime(time)}</li>
 247  * </ul>
 248  * <p>
 249  * Multiple calendar systems is an awkward addition to the design challenges.
 250  * The first principal is that most users want the standard ISO calendar system.
 251  * As such, the main classes are ISO-only. The second principal is that most of those that want a
 252  * non-ISO calendar system want it for user interaction, thus it is a UI localization issue.
 253  * As such, date and time objects should be held as ISO objects in the data model and persistent
 254  * storage, only being converted to and from a local calendar for display.
 255  * The calendar system would be stored separately in the user preferences.
 256  * </p>
 257  * <p>
 258  * There are, however, some limited use cases where users believe they need to store and use
 259  * dates in arbitrary calendar systems throughout the application.
 260  * This is supported by {@link java.time.chrono.ChronoLocalDate}, however it is vital to read
 261  * all the associated warnings in the Javadoc of that interface before using it.
 262  * In summary, applications that require general interoperation between multiple calendar systems
 263  * typically need to be written in a very different way to those only using the ISO calendar,
 264  * thus most applications should just use ISO and avoid {@code ChronoLocalDate}.
 265  * </p>
 266  * <p>
 267  * The API is also designed for user extensibility, as there are many ways of calculating time.
 268  * The {@linkplain java.time.temporal.TemporalField field} and {@linkplain java.time.temporal.TemporalUnit unit}
 269  * API, accessed via {@link java.time.temporal.TemporalAccessor TemporalAccessor} and
 270  * {@link java.time.temporal.Temporal Temporal} provide considerable flexibility to applications.
 271  * In addition, the {@link java.time.temporal.TemporalQuery TemporalQuery} and
 272  * {@link java.time.temporal.TemporalAdjuster TemporalAdjuster} interfaces provide day-to-day
 273  * power, allowing code to read close to business requirements:
 274  * </p>
 275  * <pre>
 276  *   LocalDate customerBirthday = customer.loadBirthdayFromDatabase();
 277  *   LocalDate today = LocalDate.now();
 278  *   if (customerBirthday.equals(today)) {
 279  *     LocalDate specialOfferExpiryDate = today.plusWeeks(2).with(next(FRIDAY));
 280  *     customer.sendBirthdaySpecialOffer(specialOfferExpiryDate);