This improves the ability of the Java
compiler to infer generic types and reduce explicit type-arguments in generic
method calls. In Java 7, the code looks something like this:
foo(Utility.<Type>bar());
Utility.<Type>foo().bar();
In Java 8, improved inference in arguments
and in chained calls allows you to write something like this:
foo(Utility.bar());
Utility.foo().bar();
The main API for dates, times, instants, and durations.
The classes defined here represent the principal
date-time concepts, including instants, durations, dates, times, time-zones and
periods. They are based on the ISO calendar system, which is the de facto world calendar following the
proleptic Gregorian rules. All the classes are immutable and thread-safe.
Each date time instance is composed of fields that
are conveniently made available by the APIs. For lower level access to the
fields refer to the java.time.temporal package. Each class includes support for printing and parsing all manner
of dates and times. Refer to the java.time.format package for customization options.
The java.time.chrono package contains the calendar neutral API ChronoLocalDate, ChronoLocalDateTime, ChronoZonedDateTime and Era. This is intended for use by applications that
need to use localized calendars. It is recommended that applications use the
ISO-8601 date and time classes from this package across system boundaries, such
as to the database or across the network. The calendar neutral API should be
reserved for interactions with users.
Dates and Times
Instant is essentially a
numeric timestamp. The current Instant can be retrieved from a Clock. This is useful for logging and
persistence of a point in time and has in the past been associated with storing
the result fromSystem.currentTimeMillis().
LocalDate stores a date without a time. This stores a date like '2010-12-03' and
could be used to store a birthday.
LocalTime stores a time without a date. This stores a time like '11:30' and could
be used to store an opening or closing time.
LocalDateTime stores a date and time. This stores a date-time like '2010-12-03T11:30'.
ZonedDateTime stores a date and time with a time-zone. This is useful if you want to
perform accurate calculations of dates and times taking into account the ZoneId, such as 'Europe/Paris'. Where
possible, it is recommended to use a simpler class without a time-zone. The
widespread use of time-zones tends to add considerable complexity to an
application.
Duration and Period
Beyond dates and times, the API also allows the
storage of period and durations of time. A Duration is a simple measure of time along the
time-line in nanoseconds. A Period expresses an amount of time in units meaningful to humans, such as years
or hours.
Additional value
types
Month stores a month on
its own. This stores a single month-of-year in isolation, such as 'DECEMBER'.
DayOfWeek stores a day-of-week on its own. This stores a single day-of-week in
isolation, such as 'TUESDAY'.
Year stores a year on
its own. This stores a single year in isolation, such as '2010'.
YearMonth stores a year and month without a day or time. This stores a year and
month, such as '2010-12' and could be used for a credit card expiry.
MonthDay stores a month and day without a year or time. This stores a month and
day-of-month, such as '--12-03' and could be used to store an annual event like
a birthday without storing the year.
OffsetTime stores a time and offset from UTC without a date. This stores a date
like '11:30+01:00'. The ZoneOffset is of the form '+01:00'.
OffsetDateTime stores a date and time and offset from UTC. This stores a date-time like
'2010-12-03T11:30+01:00'. This is sometimes found in XML messages and other
forms of persistence, but contains less information than a full time-zone.
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 NullPointerException" is not
explicitly documented in each method.
All calculations should check for numeric overflow
and throw either an ArithmeticException or a DateTimeException.
Design notes (non
normative)
The API has been designed to reject null early and
to be clear about this behavior. A key exception is any method that takes an
object and returns a boolean, for the purpose of checking or validating, will
generally return false for null.
The API is designed to be type-safe where
reasonable in the main high-level API. Thus, there are separate classes for the
distinct concepts of date, time and date-time, plus variants for offset and
time-zone. This can seem like a lot of classes, but most applications can begin
with just five date/time types.
- Instant - a timestamp
- LocalDate - a date without a time, or
any reference to an offset or time-zone
- LocalTime - a time without a date, or
any reference to an offset or time-zone
- LocalDateTime - combines date and time,
but still without any offset or time-zone
- ZonedDateTime - a "full"
date-time with time-zone and resolved offset from UTC/Greenwich
Instant is the closest
equivalent class to java.util.Date. ZonedDateTime is the closest
equivalent class to java.util.GregorianCalendar.
Where possible, applications should use LocalDate, LocalTime and LocalDateTime to better model the domain. For
example, a birthday should be stored in a code LocalDate. Bear in mind that any use of a time-zone, such as 'Europe/Paris', adds considerable complexity to a calculation.
Many applications can be written only using LocalDate, LocalTime and Instant, with the
time-zone added at the user interface (UI) layer.
The offset-based date-time types OffsetTime and OffsetDateTime, are intended primarily for use with
network protocols and database access. For example, most databases cannot
automatically store a time-zone like 'Europe/Paris', but they can store an
offset like '+02:00'.
Classes are also provided for the most important
sub-parts of a date, including Month, DayOfWeek, Year, YearMonth and MonthDay. These can be used
to model more complex date-time concepts. For example, YearMonth is useful for
representing a credit card expiry.
Note that while there are a large number of classes
representing different aspects of dates, there are relatively few dealing with
different aspects of time. Following type-safety to its logical conclusion
would have resulted in classes for hour-minute, hour-minute-second and
hour-minute-second-nanosecond. While logically pure, this was not a practical
option as it would have almost tripled the number of classes due to the
combinations of date and time. Thus, LocalTime is used for all precisions of time,
with zeroes used to imply lower precision.
Following full type-safety to its ultimate
conclusion might also argue for a separate class for each field in date-time,
such as a class for HourOfDay and another for DayOfMonth. This approach was
tried, but was excessively complicated in the Java language, lacking usability.
A similar problem occurs with periods. There is a case for a separate class for
each period unit, such as a type for Years and a type for Minutes. However,
this yields a lot of classes and a problem of type conversion. Thus, the set of
date-time types provided is a compromise between purity and practicality.
The API has a relatively large surface area in
terms of number of methods. This is made manageable through the use of
consistent method prefixes.
- of - static factory method
- parse - static factory method
focussed on parsing
- get - gets the value of
something
- is - checks if something is
true
- with - the immutable equivalent
of a setter
- plus - adds an amount to an
object
- minus - subtracts an amount from
an object
- to - converts this object to
another type
- at - combines this object with
another, such as date.atTime(time)
Multiple calendar systems is an awkward addition to
the design challenges. The first principal is that most users want the standard
ISO calendar system. As such, the main classes are ISO-only. The second
principal is that most of those that want a non-ISO calendar system want it for
user interaction, thus it is a UI localization issue. As such, date and time
objects should be held as ISO objects in the data model and persistent storage,
only being converted to and from a local calendar for display. The calendar
system would be stored separately in the user preferences.
There are, however, some limited use cases where
users believe they need to store and use dates in arbitrary calendar systems
throughout the application. This is supported by ChronoLocalDate, however it is vital to read all the associated warnings in the Javadoc
of that interface before using it. In summary, applications that require
general interoperation between multiple calendar systems typically need to be
written in a very different way to those only using the ISO calendar, thus most
applications should just use ISO and avoid ChronoLocalDate.
The API is also designed for user extensibility, as
there are many ways of calculating time. The field and unit API, accessed via TemporalAccessor and Temporal provide
considerable flexibility to applications. In addition, theTemporalQuery and TemporalAdjuster interfaces provide day-to-day power,
allowing code to read close to business requirements:
LocalDate customerBirthday =
customer.loadBirthdayFromDatabase();
LocalDate today = LocalDate.now();
if (customerBirthday.equals(today)) {
LocalDate specialOfferExpiryDate =
today.plusWeeks(2).with(next(FRIDAY));
customer.sendBirthdaySpecialOffer(specialOfferExpiryDate);
}
No comments:
Post a Comment