New Date & Time API in Java 8

Question

On this page i read the following:

To do calculations with dates, it is also very easy. Probably the best improvement compared to the current situation with Java < 1.8:

Period p = Period.of(2, HOURS);
LocalTime time = LocalTime.now();
LocalTime newTime = time.plus(p); // or time.plus(5, HOURS); or time.plusHours(5); 

I don't clearly see the advantage prior to Versions < 1.8.

Maybe someone can give me an example? Atm i am asking myself, where the improvement of the new date & time API comes from.

Answer 1

With Java < 8, you would need to write something like:

Calendar cal = Calendar.getInstance();
cal.set(Calendar.HOUR, cal.get(Calendar.HOUR) + 2);

vs. with Java 8:

LocalTime now = LocalTime.now();
LocalTime later = now.plus(2, HOURS);

The improvements are essentially on

• readability:
  • Calendar.getInstance() is not very well named: it is hard to tell which instance you are getting without reading the Javadoc. LocalTime.now() is quite self-describing: you get a time and it is now.
  • To offset a date, you call an offsetting method (plus) whereas with the Calendar API, you have to manually change the fields of the object (in this example, the hour) which is error prone.
• ease of use (see for example the table towards the bottom of this page for a comparison):
  • the Calendar API is complicated to use because it mixes concepts, such as a simple date (June 26th 2015) and an instant in time (June 26th 2015 at 10am UTC) - there isn't a class for the former concept
  • The new Time API has a clear separation between the various date/time concepts
• safety:
  • The Calendar API is not safe: nothing prevents you from writing cal.set(123, 2) which would throw a not-so-helpful ArrayOutOfBoundsException. The new API uses enums which solves that problem.
  • The new API uses immutable objects, which makes it thread safe.

Overall, the new API is significantly inspired from jodatime which has been the preferred Java Date API for quite some time now. You can also read this detailed comparison of Java (<1.8) date vs. JodaTime (most of it should apply to the Java 8 Date API).

Answer 2

Advantages of the new date/time API

• The notions of date (LocalDate), time (LocalTime), date&time (LocalDateTime), instant (Instant) are much clearer and correspond to their meaning in common language.
• Intializing date/time to a specific value got easier (method 'of', e.g. LocalDate.of(2016,1,1))
• Dealing with leap years (method isLeapYear) got trivial
• Adding/subtracting dates got very easy. E.g. to reference today in 10 years: LocalDate.now().plusYears(10)
• Month numbering offset adapted to intuition. 'January' is '1' now and not '0' as before

Disadvantages

• Not yet supported by JPA2
• Not yet supported by JSF2