Java - Introduction to Java 8 Date and Time API

[Last Updated: Jun 19, 2020]

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.of(int year, int month, int dayOfMonth)
LocalTime.of(int hour, int minute, int second, int nanoOfSecond)
LocalDateTime.of(int year, Month month, int dayOfMonth, 
                 int hour, int minute, int second, int nanoOfSecond) 
OffsetTime.of(int hour, int minute, int second, 
              int nanoOfSecond, ZoneOffset offset)
OffsetDateTime.of(int year, int month, int dayOfMonth,
                  int hour, int minute, int second, 
                  int nanoOfSecond, ZoneOffset offset)
ZonedDateTime.of(int year, int month, int dayOfMonth,
                 int hour, int minute, int second, 
                 int nanoOfSecond, ZoneId zone)
ZoneOffset.ofHoursMinutesSeconds(int hours, int minutes, int seconds)
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.


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)


 Instant instant = Instant.from(;


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)


 Duration duration = Duration.between(,;


A java.time.Period uses date-based values (years, months, days).

Example API

Period between(LocalDate startDateInclusive, LocalDate endDateExclusive)


 Period period = Period.between(LocalDate.of(1995, 1, 1),;

See Also