DateTime API is introduced in Java 8 to solve the issues with current java.util package Date and Timestamp API problems.

DateTime API in Java 8

Why do we need it?

  • Existing DateTime api doesn’t provide much support in case of manipulation and conversion of DateTime. With current api, its very difficult to handle time zone issues like converting the time from one time zone to other keeping day light savings in mind.
  • Existing java.util.Date is not thread-safe and doesn’t support concurrency, this makes developers to keep extra effort of understanding concurrency issues and handling them explicitly in their project. So we need something that is immutable for thread-safe environment
  • Existing api doesn’t follow standard api design like:
    • Year starts from 1900
    • Month starts from 1
    • Days start from 0
  • So following JSR 310 standards, Oracle with collaboration of Joda-Time developed standard API for DateTime under java.time package.

DateTime API

  • A separate set of classes were added to support the behavior of local time as well as other set  for Zoned time, to support particular zone related use cases.
    • java.time.LocalDate and java.time.LocalTime are for defining local times. There is also java.time.LocalDateTime which is combination of LocalDate and Localtime.
    • Java.time.ZonedDateTime for having time specific to TimeZone

DateTime api Usage:

  • Creation of objects for any of above set of classes follows Factory Design pattern such that when we pass the parameters as per syntax, appropriate object will be returned with the values embedded in it. Object is created by calling the static method of of those respective classes as shown below:
LocalDate date = LocalDate.of(2016, 01, 01); 
LocalDate date2 = LocalDate.of(2016, Month.FEBRUARY, 21); 
LocalTime time = LocalTime.of(10,11,7,10);

Local Specific Date/Time:

java.time.LocalDate and java.time.LocalTime are for defining local times. There is also java.time.LocalDateTime which is combination of LocalDate and Localtime.

LocalDate date = LocalDate.of(2016, Month.FEBRUARY, 21); 
System.out.println("Date:" +date.toString()); 
LocalTime time = LocalTime.of(10,11,7,10); 
time = LocalTime.parse("10:15:30+03:00", DateTimeFormatter.ISO_OFFSET_TIME); 
System.out.println("Time" +time.toString()); 
LocalDateTime dt =; 
System.out.println("Current Date/Time: "+dt.toString()); 
System.out.println("Accessing the data from the Local Time Object"); 
LocalDate theDate = dt.toLocalDate(); 
System.out.println("Retrieved Dat2: "+ theDate); 
Month month = dt.getMonth(); 
System.out.println("Retrieved Month: " + month); 
LocalDateTime dt1 = dt.withDayOfMonth(10).withYear(2010); 
System.out.println("dt1: " + dt1); 
LocalDateTime dt2 = dt.plusWeeks(3).plus(3, ChronoUnit.WEEKS); 
System.out.println("dt2: " + dt2);


Current Date/Time: 2016-09-06T20:52:45.914
Accessing the data from the Local Time Object
Retrieved Dat2: 2016-09-06
Retrieved Month: SEPTEMBER
dt1: 2010-09-10T20:52:45.914
dt2: 2016-10-18T20:52:45.914

Zone Specific Date/Time:

ZonedDateTime provides api to create date time instances based on time zone without depending on local time(where the jvm is running).

ZonedDateTime date1 =; 
System.out.println("Current Time in Asia/Calcutta: " + date1); 
ZoneId id = ZoneId.of("Europe/Paris"); 
ZonedDateTime date2 = date1.withZoneSameInstant(id); 
System.out.println("Current Time in Europe/Paris: " + date2);


Current Time in Asia/Calcutta: 2016-09-06T20:46:26.708+05:30[Asia/Calcutta]

Current Time in Europe/Paris: 2016-09-06T17:16:26.708+02:00[Europe/Paris]

Duration and Period:

Duration is used to represent a scale of time using hours, seconds and minutes as below:

Duration duration = Duration.ofHours(1); 
long seconds = duration.getSeconds(); 
//Below statement will print 3600 
System.out.println("In Seconds:" +seconds);

Period is also analogous to Duration, but we can represent in years, days and months in Period as below:

LocalDate today =; 
LocalDate examinationDate = LocalDate.of(2017, Month.JANUARY, 1); 
Period p = Period.between(today, examinationDate); 
long p2 = ChronoUnit.DAYS.between(today, examinationDate); 
System.out.println("You have " + p.getYears() + " years, " + p.getMonths() +" months, and " + p.getDays() +" days for exams to start. (" + p2 + " days total)");


You have 0 years, 3 months, and 26 days for exams to start. (117 days total)

Chrono package:

There are some zones that fall under non-ISO calendaring systems. For that kind of system, Java introduced the concept of chronology. All supporting classes are places under java.time.chrono package.

We can create our own calendar system by extending AbstractChronology class.

Happy Learning 🙂