DEV Community


Introduction to JAVA8 Date/Time API

housniabdellatife profile image HousniAbdellatife ・4 min read

Java 8 was released in March 2014 and brought a lot of language improvements. One of those is new Date and Time API for Java, also known as JSR-310. It represents a very rich API for working with dates and time.

Issues with java.util.Date and java.util.Calendar:

  • A Date instance represents an instant in time, not a date.
  • It rates years as two digits since 1900.
  • Months are zero indexed (0 – January, 11 – December).
  • All classes in this old API are mutable, and not thread safe.

New Java8 Date/Time API:

  • Thread Safety: the new Date and Time APIs introduced in Java 8 are immutable and thread safe,
  • Domain-driven design: The new API models its domain very precisely with classes that represent different use cases for Date and Time closely
  • ZonedDate and Time: handling of timezone can be done with Local and ZonedDate/Time APIs.

java.time.LocalDate :

we can create LocalDate objects using one of the following its static methods:

 LocalDate nowDate =; //Obtains the current date from the system clock in the default time-zone.       
 LocalDate date  = LocalDate.of(int year, int month, int day); //January is equivalent to 1 

we can also create LocalDate from a String:

 LocalDate date = LocalDate.parse("2012-01-26"); // default format is yyyy-MM-dd

the most common useful methods :

 LocalDate date  = LocalDate.of(2020, 01, 01);




 date.getDayOfMonth(); // day of month is 1-index
 date.getDayOfWeek();  // returns DayOfWeek enum
 date.getDayOfYear();  // day of year is 1-index

java.time.LocalTime :

  • LocalTime is an immutable date-time object that represents a time.
  • This class is immutable and thread-safe.
  • time without a time-zone.
  • it follows ISO-8601 calendar system

we can create LocalTime objects using one of the following its static methods:;
 LocalTime.of(int hour, int minute);
 LocalTime.of(int hour, int minute, int second);
 LocalTime.of(int hour, int minute, int second, int nanoOfSecond);

the most common useful methods :

 LocalTime time =;





java.time.LocalDateTime :

  • represents a combinaison of date and time.
  • immutable object and thread safe.
  • It follow ISO-8601.

we can create LocalTime objects using one of the following its static methods:

  LocalDateTime dateTime =;
  LocalDateTime.of(int year, int month, int dayOfMonth, int hour, int minute);
  LocalDateTime.of(int year, int month, int dayOfMonth, int hour, int minute, int second);
  LocalDateTime.of(int year, int month, int dayOfMonth, int hour, int minute, int second, int nanoOfSecond) ;
  LocalDateTime.of(LocalDate date, LocalTime time); 

Method chaining :
chaining method is an very useful technic that used with immutable objects to write clear and clean code and more concise, and avoid multi statements code.

int dayOfYear = LocalDate.of(2,2, 2022)

java.time.Period :

A date-based amount of time in the ISO-8601 calendar system, such as '2 years, 3 months and 4 days'.

The total period of time is represented by all three units together: months, days, and years.

The Date can be manipulated using Period as shown in the following code snippet:

  LocalDate  initialDate = LocalDate.parse("2020-02-25");
  LocalDate endDate =;
  Period difference = Period.between(initialDate, endDate);

if we are going to use the same multiple times, we can create an object Period and reused:

  // Period of 5 years, 4 months, and 2 days
   Period period = Period.of(5, 4 , 2);

java.util.Duration :
Similar to Period, the Duration class is use to deal with Time.
A time-based amount of time, such as '34.5 seconds'.

in this example we create an LocalTime object 4:5:45am and add 30 seconds to it.

  LocalTime initialTime = LocalTime.of(4, 5, 45);
  LocalTime endTime =;

The Duration between two instants can be obtained as a Duration:

   Duration difference = Duration.between(initialTime, endTime);
   long seconds = difference.getSeconds();

the class stores a long representing epoch-seconds and an int representing nanosecond-of-second, which will always be between 0 and 999,999,999.

The instant is defined as an offset since the origin (called an epoch). The origin is Jan. 1st 1970 - 00:00 - Greenwhich mean time (GMT).

Instant instant = Instant;

we can create an LocalDateTime from an instant as following, but we need a timeZone also:

Instant instant =;
LocalDateTime.ofInstant(instant, ZoneId.systemDefault());

From java.util.Date to a LocalDateTime:
Java8 added the method toInstant() to Date object which help us to convert a Date or Calendar to the new java date/time api, let's see how:

Date date = new Date();
LocalDateTime localDateTime = LocalDateTime.ofInstant(date.toInstant(), ZoneId.systemDefault());       
LocalDate localDate = localDateTime.toLocalDate();
LocalTime localTime = localDateTime.toLocalTime();

Date and Time Formatting :
Java 8 provides APIs for the easy formatting of Date and Time.

the code below shows default date format:

LocalDateTime localDateTime = LocalDateTime.of(2019, 06, 19, 12, 05, 23);

its output is:


also we can use predefined ISO format:

LocalDateTime localDateTime = LocalDateTime.of(2019, 06, 19, 12, 05, 23);
String  localDateTimeString = localDateTime.format(DateTimeFormatter.ISO_DATE);

the output is :


we can create our format as following :

LocalDateTime localDateTime = LocalDateTime.of(2019, 06, 19, 12, 05, 23);   
DateTimeFormatter dateTimeFormatter = DateTimeFormatter.ofPattern("dd/yyyy/MM");
String  localDateTimeString = localDateTime.format(dateTimeFormatter);

output is :



Editor guide