4 min read

Blog Java date api The fourth post in the series, the top most interesting features of Java 8 that make its adoption worthwhile for the enterprises, divulges the features of the new Date and Time APIs which are thread-safe and have better API design.

Background

The existing classes, such as java.util. Date and SimpleDateFormatter, aren’t thread-safe. Moreover, some of the date and the time classes have poor API design. For instance, years in java.util. Date start at 1900, months start at 1, and days start at 0.

In order to resolve these issues and provide a better API design in the JDK core, a new date and time API has been designed for Java 8.

Java 8 – Date and Time APIs

New Classes

Many classes have been introduced to represent time, date, time period, and timezone specific data. Furthermore, there are transformers for dates and times.

For dates and times without a timezone, we can use the following classes:

  • LocalDate – Day, month, year
  • LocalTime – Time of day only
  • LocalDateTime – Both date and time
  • ZonedDateTime - timezone specific

java8-snippet1

There are some useful methods such as plusDays, plusMonths, minusDays, and minusMonths. For example,

java8 snippet2

Each method returns a different instance of LocalDate. The original LocalDate, today, remains unchanged. This is because the new Date-Time types are immutable and it allows them to be thread-safe and cacheable.

Creation

Creating new date and time objects is easy in Java 8. Every type is immutable and has static factory methods.

The LocalDate can use following methods:

  • atTime(int hour, int minute)
  • atTime(int hour, int minute, int second)
  • atTime(int hour, int minute, int second, int nanosecond)

The now () method corresponds to the current date, or time, or date and time.

java8 snippet3

Enums

The new API has enums, such as java.time.temporal. ChronoUnit for expressing the things like “weeks” and “months” instead of the integer constants used in the Calendar API. For example,

java8 snippet4

The enums, java.time. DayOfWeek and java.time. Month are also available. The month enum can be used to create LocalDate and is returned by LocalDate.getMonth().

java8 snippet5

Clock

The Clock can be used in conjunction with dates and times. For example,

java8 snippet6

Period and Duration

The Duration is a time-based amount of time, such as ‘24.6 seconds’ and the Period is a date-based amount of time, such as ‘3 years, 2 months and 6 days’.

The Period and the Duration can be determined using the between method. They can also be created using static methods. The Duration can be created for any amount of seconds, minutes, hours, or days. For example,

java8 snippet7

Temporal Adjusters

A TemporalAdjuster can be used to find the “first Monday of the month” or “next Tuesday”.

The java.time.temporal.TemporalAdjusters class contains a lot of useful methods for creating TemporalAdjusters. A few of them are:

  • firstDayOfMonth(), firstDayOfNextMonth(), firstInMonth(DayOfWeek)
  • lastDayOfMont(), next(DayOfWeek), nextOrSame(DayOfWeek)
  • previous(DayOfWeek), previousOrSame(DayOfWeek)

java8 snippet8

Instant

The Instant class represents a point in time measured to the nanosecond. It forms the basis of the time measurements in Java 8 date-time API. The Instant measures the time starting from the “epoch” (Jan. 1, 1920) and is time-zone ignorant.

java8 snippet9

Time Zones

The java.time.ZoneId class represents Time-Zones. There are two kinds of ZoneIds: fixed offsets and geographical regions. For example

java8 snippet10

Backwards Compatibility

The original Date and the Calendar objects have the toInstant() method to convert them to the new Date-Time API. We can use an ofInstant (Instant, ZoneId) method to get a LocalDateTime or a ZonedDateTime object. For example,

java8 snippet11

Summary

The new Date and Time APIs are thread-safe, immutable, cacheable, and represent a point in time measured to the nanosecond and have the option for backward compatibility. It borrows the ideas from Joda-Time and allows the programmers to capitalize on the features which were not available in java.util.Date and Calendar.