Java 8 introduced new APIs for Date and Time to address the shortcomings of the older java.util.Date and java.util.Calendar.

1. Java 8 Date Time API Packages

Java 8 Date Time API consists of following packages.

1. java.time This is the base package of new Java Date Time API. All the major base classes are part of this package, such as LocalDate, LocalTime, LocalDateTime, Instant, Period, Duration etc. All of these classes are immutable and thread safe. Most of the times, these classes will be sufficient for handling common requirements.
2. java.time.chrono This package defines generic APIs for non ISO calendar systems. We can extend AbstractChronology class to create our own calendar system.
3. java.time.format This package contains classes used for formatting and parsing date time objects. Most of the times, we would not be directly using them because principle classes in java.time package provide formatting and parsing methods.
4. java.time.temporal This package contains temporal objects and we can use it for find out specific date or time related to date/time object. For example, we can use these to find out the first or last day of the month. You can identify these methods easily because they always have format “withXXX”.
5. java.time.zone This package contains classes for supporting different time zones and their rules.

Please note that this post is mainly driven by code examples that show the new API functionality. We think the examples are self-explanatory.

2. Using LocalDate, LocalTime and LocalDateTime API

1. Exploring LocalDate

   LocalDate represents a date in ISO format (yyyy-MM-dd) without time.

   LocalDate API Snippets

   Java

   // the current date in format yyyy-MM-dd LocalDate currentDate = LocalDate.now(); // 2016-02-29 LocalDate formattedDate = LocalDate.of(2016, Month.FEBRUARY, 29); // the 75th day of 2016 (2016-03-15) LocalDate dayFromNumber = LocalDate.ofYearDay(2016, 75); // parse date from string LocalDate parseDateFromString = LocalDate.parse("2016-08-08"); // today + 1 day = tomorrow LocalDate tomorrow = LocalDate.now().plusDays(1); // same day of previous month LocalDate previousMonthSameDay = LocalDate.now().minus(1, ChronoUnit.MONTHS); // day of specific date DayOfWeek friday = LocalDate.parse("2016-08-12").getDayOfWeek(); // day of month for specific date int twelve = LocalDate.parse("2016-08-12").getDayOfMonth(); // Is leap year? boolean leapYear = LocalDate.now().isLeapYear(); // date on left side is before date on right side? boolean isBefore = LocalDate.parse("2016-08-15").isBefore(LocalDate.parse("2016-08-20")); // first day of the month for specific date LocalDate firstDayOfMonth = LocalDate.parse("2016-08-28").with(TemporalAdjusters.firstDayOfMonth());

   0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33

   // the current date in format yyyy-MM-dd LocalDate currentDate = LocalDate.now(); // 2016-02-29 LocalDate formattedDate = LocalDate.of(2016, Month.FEBRUARY, 29);   // the 75th day of 2016 (2016-03-15) LocalDate dayFromNumber = LocalDate.ofYearDay(2016, 75);   // parse date from string LocalDate parseDateFromString = LocalDate.parse("2016-08-08");   // today + 1 day = tomorrow LocalDate tomorrow = LocalDate.now().plusDays(1);   // same day of previous month LocalDate previousMonthSameDay = LocalDate.now().minus(1, ChronoUnit.MONTHS);   // day of specific date DayOfWeek friday = LocalDate.parse("2016-08-12").getDayOfWeek();   // day of month for specific date int twelve = LocalDate.parse("2016-08-12").getDayOfMonth();   // Is leap year? boolean leapYear = LocalDate.now().isLeapYear();   // date on left side is before date on right side? boolean isBefore = LocalDate.parse("2016-08-15").isBefore(LocalDate.parse("2016-08-20"));   // first day of the month for specific date LocalDate firstDayOfMonth = LocalDate.parse("2016-08-28").with(TemporalAdjusters.firstDayOfMonth());

2. Exploring LocalTime

   LocalTime represents time without a date.

   LocalTime API Snippets

   Java

   // current time in format HH:mm:ss.SSS LocalTime currentTime = LocalTime.now(); // 10:10 in 24hr format LocalTime timeFromNumber = LocalTime.of(10, 10); // 20000th second of day (03:25:45) LocalTime fromSecondsOfDay = LocalTime.ofSecondOfDay(20000); // parse time from string LocalTime parseTime = LocalTime.parse("10:10"); // add 1hr to current time LocalTime nextHour = LocalTime.now().plusHours(1); // minus 2hrs from current time LocalTime backToTwoHours = LocalTime.now().minus(2, ChronoUnit.HOURS); // minutes from time int minutesFromTime = LocalTime.parse("10:10").getMinute(); // time on left side is before time on right side? boolean isbefore = LocalTime.parse("10:10").isBefore(LocalTime.parse("11:05")); // current (local) time in India LocalTime currentTimeInIndia = LocalTime.now(ZoneId.of("Asia/Kolkata")); // Current time in UTC time zone LocalTime nowInUtc = LocalTime.now(Clock.systemUTC());

   0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30

   // current time in format HH:mm:ss.SSS LocalTime currentTime = LocalTime.now();   // 10:10 in 24hr format LocalTime timeFromNumber = LocalTime.of(10, 10);   // 20000th second of day (03:25:45) LocalTime fromSecondsOfDay = LocalTime.ofSecondOfDay(20000);   // parse time from string LocalTime parseTime = LocalTime.parse("10:10");   // add 1hr to current time LocalTime nextHour = LocalTime.now().plusHours(1);   // minus 2hrs from current time LocalTime backToTwoHours =  LocalTime.now().minus(2, ChronoUnit.HOURS);   // minutes from time int minutesFromTime = LocalTime.parse("10:10").getMinute();   // time on left side is before time on right side? boolean isbefore = LocalTime.parse("10:10").isBefore(LocalTime.parse("11:05"));   // current (local) time in India LocalTime currentTimeInIndia = LocalTime.now(ZoneId.of("Asia/Kolkata")); // Current time in UTC time zone LocalTime nowInUtc = LocalTime.now(Clock.systemUTC());

3. Exploring LocalDateTime

   LocalDateTime is used to represent a combination of date and time.

   An instance of LocalDateTime can be obtained from the system clock similar to LocalDate and LocalTime

   LocalDateTime API Snippets

   Java

   // the current date in format yyyy-MM-dd LocalDateTime currentDate = LocalDateTime.now(); // 2016-08-08T10:10 LocalDateTime dateFromNumbers = LocalDateTime.of(2016, 8, 8, 10, 10); // 2016-08-08T10:10 LocalDateTime dateFromNumbers1 = LocalDateTime.of(2016, Month.AUGUST, 8, 10, 10); // parse date-time from string LocalDateTime parseDateTime = LocalDateTime.parse("2016-08-08T10:10"); // add one day in specific time LocalDateTime addDays = LocalDateTime.now().plusDays(1); // minus five hours in specific time LocalDateTime minusHours = LocalDateTime.now().minusHours(5); // get month of specific date Month currentMonth = LocalDateTime.now().getMonth();

   0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

   // the current date in format yyyy-MM-dd LocalDateTime currentDate = LocalDateTime.now();   // 2016-08-08T10:10 LocalDateTime dateFromNumbers  = LocalDateTime.of(2016, 8, 8, 10, 10);   // 2016-08-08T10:10 LocalDateTime dateFromNumbers1 = LocalDateTime.of(2016, Month.AUGUST, 8, 10, 10);   // parse date-time from string LocalDateTime parseDateTime = LocalDateTime.parse("2016-08-08T10:10");   // add one day in specific time LocalDateTime addDays = LocalDateTime.now().plusDays(1);   // minus five hours in specific time LocalDateTime minusHours = LocalDateTime.now().minusHours(5);   // get month of specific date Month currentMonth = LocalDateTime.now().getMonth();

3. Using ZonedDateTime API

We can use ZonedDateTime to deal with Date and Time with specific Zone.

There are about 40 different time zones provided by ZoneId.

4. Using Instant API a.k.a Timestamps

An Instant counts the time beginning from the first second of January 1, 1970 (1970-01-01 00:00:00) also called the EPOCH.

5. Using Period and Duration

The Period class represents a quantity of time in terms of years, months and days and the Duration class represents a quantity of time in terms of seconds and nano seconds.

1. Exploring Period

   Period API Snippets

   Java

   LocalDate firstDate = LocalDate.of(2012, 8, 8); // 2012-08-08 LocalDate secondDate = LocalDate.of(2016, 2, 21); // 2016-02-21 // get difference between two dates Period period = Period.between(firstDate, secondDate); int days = period.getDays(); // 13 int months = period.getMonths(); // 6 int years = period.getYears(); // 3 boolean isNegative = period.isNegative(); // false // selects 2 months and 15 days Period specificPeriods = Period.ofMonths(2).plusDays(15);

   0 1 2 3 4 5 6 7 8 9 10 11 12 13 14

   LocalDate firstDate = LocalDate.of(2012, 8, 8); // 2012-08-08 LocalDate secondDate = LocalDate.of(2016, 2, 21); // 2016-02-21   // get difference between two dates Period period = Period.between(firstDate, secondDate);   int days = period.getDays(); // 13 int months = period.getMonths(); // 6 int years = period.getYears(); // 3 boolean isNegative = period.isNegative(); // false   // selects 2 months and 15 days Period specificPeriods = Period.ofMonths(2).plusDays(15);

2. Exploring Duration

   Duration API Snippets

   Java

   Instant firstInstant= Instant.ofEpochSecond( 1470654323 ); // 2016-08-08 11:05 Instant secondInstant = Instant.ofEpochSecond(1470687623); // 2011-01-11 20:20 // get difference between two time Duration between = Duration.between(firstInstant, secondInstant); // negative because firstInstant is after secondInstant (33300) long seconds = between.getSeconds(); // get absolute result in minutes (555) long absoluteResult = between.abs().toMinutes(); // four hours in seconds (14400) long fourHoursInSeconds = Duration.ofHours(4).getSeconds();

   0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

   Instant firstInstant= Instant.ofEpochSecond( 1470654323 ); // 2016-08-08 11:05 Instant secondInstant = Instant.ofEpochSecond(1470687623); // 2011-01-11 20:20 // get difference between two time Duration between = Duration.between(firstInstant, secondInstant); // negative because firstInstant is after secondInstant (33300) long seconds = between.getSeconds(); // get absolute result in minutes (555) long absoluteResult = between.abs().toMinutes(); // four hours in seconds (14400) long fourHoursInSeconds = Duration.ofHours(4).getSeconds();

6. Date and Time Formatting

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

7. Conclusion

Java 8 provides a rich set of APIs with a consistent API design for easier development. The API can completely replace old classes like java.util.Date or java.util.Calendar with newer, more flexible classes.