Java 8 Date and Time API

Any experienced Java programmer would agree that the Date/Calendar API before Java 8 was confusing and inconsistent. It also has some design flaws. I have found myself in confusing situations like whether to use java.util.Date or java.util.Calendar API. Most of the cases, I used to google for code snippet and quickly get rid of the problem. And in some other cases which required lot of date/time manipulation, I used third-party libraries (like Joda-time API).

It's pleasing to see that, Java designers finally addressed this pain point and introduced a new set of API. I have tried to quickly cover major API and their usage with simple examples. This post will give you quick start to understand new classes added in package java.time.

java.time.LocalDate

An instance of this class is an immutable object which just stores date information, i.e. year, month and day. It doesn't store the time and time zone. LocalDate provides factory methods to fetch the system current date or refer a specific date.

LocalDate independenceDay = LocalDate.of(1947, 8, 15); //15th Aug 1947

LocalDate parsedDate  = LocalDate.parse("2015-01-31");

LocalDate today = LocalDate.now();       //2015-06-24

int day        = today.getDayOfMonth();  //24

int month      = today.getMonthValue();  //6

Month mon      = today.getMonth();       //JUNE

int year       = today.getYear();        //2015

DayOfWeek days = today.getDayOfWeek();   //WEDNESDAY

int len        = today.lengthOfMonth();  //30

java.time.LocalTime

Similar to LocalDate, LocalTime represents just the time without any date and time zone information. 

LocalTime specificTime = LocalTime.of(12, 45, 59);

LocalTime parseTime = LocalTime.parse("13:45:20");

LocalTime now =  LocalTime.now();

int hour      = now.getHour();

int minute    = now.getMinute();

int seconds   = now.getSecond();

int nanoSec = now.getNano();  //gets nano of second

java.time.LocalDateTime

As the name suggests, LocalDateTime represents both date and time, without any time zone information. It can also be created by combining LocalDate and LocalTime. 

LocalDateTime NowDateTime = LocalDateTime.of(LocalDate.now(), LocalTime.now());   //2015-06-24T17:58:29.557

LocalDateTime specificDateTime = LocalDateTime.of(2015, Month.JANUARY, 18, 13, 45, 20); //2015-01-18T13:45:20

LocalDateTime aTime = LocalDate.now().atTime(13, 45, 20);   //2015-06-24T13:45:20

Date and Time for machines

All approaches discussed above are more suitable for humans, but machines will prefer a unique number which abstracts date and time information (similar to the way it was done in java.util.Date API). 

java.time.Instant represents the number of seconds passed since the Unix epoch time (midnight Jan 1, 1970, UTC). The Instant class also provides a now factory method to capture current timestamp. This API also supports nanoseconds precision which was not there in previous date/time/calendar API.

Instant timeStamp = Instant.now();   //2015-01-18T13:45:20

long second = timeStamp.getEpochSecond();  //1435149943

long nano = timeStamp.getNano();  //341000000, total number of nano seconds since getEpochSecond