Java 8 (JSR-310) provided a comprehensive set of date and time classes which addressed many inconsistencies in the old API.
Following table shows the new classes along with their features:
| Class |
Date |
Time |
Zone Offset |
Time Zone |
Example API |
| LocalDate |
✅ |
❌ |
❌ |
❌ |
LocalDate.of(int year, int month, int dayOfMonth) |
| LocalTime |
❌ |
✅ |
❌ |
❌ |
LocalTime.of(int hour, int minute, int second, int nanoOfSecond)
|
| LocalDateTime |
✅ |
✅ |
❌ |
❌ |
LocalDateTime.of(int year, Month month, int dayOfMonth,
int hour, int minute, int second, int nanoOfSecond)
|
| OffsetTime |
❌ |
✅ |
✅ |
❌ |
OffsetTime.of(int hour, int minute, int second,
int nanoOfSecond, ZoneOffset offset)
|
| OffsetDateTime |
✅ |
✅ |
✅ |
❌ |
OffsetDateTime.of(int year, int month, int dayOfMonth,
int hour, int minute, int second,
int nanoOfSecond, ZoneOffset offset)
|
| ZonedDateTime |
✅ |
✅ |
✅ |
✅ |
ZonedDateTime.of(int year, int month, int dayOfMonth,
int hour, int minute, int second,
int nanoOfSecond, ZoneId zone)
|
| ZoneOffset |
❌ |
❌ |
✅ |
❌ |
ZoneOffset.ofHoursMinutesSeconds(int hours, int minutes, int seconds)
|
| ZoneId |
❌ |
❌ |
❌ |
✅ |
ZoneId.of(String zoneId)
|
All above classes are defined in java.time package.
All above classes are immutable.
Zone offset vs Time Zone
A time-zone offset is the amount of time that a time-zone differs from Greenwich/UTC. Different parts of the world have different time-zone offsets. In Java ZoneOffset represents the time-zone offset.
The rules for how offsets vary by place and time of year are captured in the ZoneId class.
ZoneId class is a representation of time-zone, it simply represents an ID for time-zone, e.g. Europe/Paris.
Let's consider an ZoneOffset example: Paris is one hour ahead of Greenwich/UTC in winter and two hours ahead in summer. The ZoneId instance for Paris will reference two ZoneOffset instances:
(1) a +01:00 instance for winter,
(2) a +02:00 instance for summer.
Machine time
There are two basic ways to represent time. One way represents time as human time, such as year, month, day, hour, minute and second. The other way, machine time, measures time continuously along a timeline from an origin, called the epoch.
Instant
java.time.Instant models a single instantaneous point on the timeline.
The starting point of a timeline (known as epoch) is used to represent an Instant.
The epoch used is 1970-01-01T00:00:00Z (midnight at the start of 1 January 1970 UTC), as per the current Java SE date and time classes.
This class has nanosecond precision. It stores a long representing epoch-seconds and an int representing nanosecond-of-second
Example API
Instant.ofEpochSecond(long epochSecond, long nanoAdjustment)
Instant.from(TemporalAccessor temporal)
Example
Instant instant = Instant.from(OffsetDateTime.now());
System.out.println(instant.getEpochSecond());
1592552961
Duration
A java.time.Duration measures an amount of time using time-based values (seconds, nanoseconds).
The Duration can be between two temporal objects (any date time class showing in above table) which support the SECONDS unit.
Example API
Duration.between(Temporal startInclusive, Temporal endExclusive)
Example
Duration duration = Duration.between(LocalDateTime.now().minusDays(100), LocalDateTime.now());
System.out.println(duration.getSeconds());
8640000
Period
A java.time.Period uses date-based values (years, months, days).
Example API
Period between(LocalDate startDateInclusive, LocalDate endDateExclusive)
Example
Period period = Period.between(LocalDate.of(1995, 1, 1), LocalDate.now());
System.out.println(period.getYears());
25
|
|
