Java 8’s Date Time API Quickstart

Java 8's Data Time API Quickstart

Java has introduced a new date and time API in Java 8. The interface is much more intuitive than the old java.util.Date and java.util.Calendar based APIs. The new library was developed and integrated via JSR-310 and is heavily inspired from the popular Joda-Time library. It has a comprehensive set of classes for various use cases (as you’ll see later on in the article). Another important benefit of the new library is that the objects created are immutable and therefore cause less problems in multithreaded programming.

The new APIs are designed to be fluent, e.g.:

The main classes in the new library are


A LocalDate stores the year-month-day information with no time and no time zone. For example, you will use this class to represent a date like Jun 15, 2014. The use case for this class is to represent birthday, start/end day of a project, holiday etc.

To get a LocalDate object for today, use

To create a LocalDate object for a particular date

LocalDates are very easy to compare

To convert a LocalDate to a string representation (ISO-8601)

There are many utility methods in this class to make life easier for the programmer

Date Manipulation

It’s very easy to manipulate dates to get new dates. There are lots of methods to add/subtract/set day/month/year for a given date. Since the objects in the new library are immutable, all these methods return a new LocalDate object. The methods can be easily chained together without sacrificing code readability.

To push a date ahead by a month and fifteen days

To get a date with first day of current month

To get a date with month changed to October

Adjusters for more complex manipulations

The new library has support for complex manipulations like

Get the date on the last day of this month

Get the date on next Sunday


LocalTime is similar to LocalDate but stores time information. It stores time (hours, minutes, seconds, and nanoseconds) with no date or time zone. E.g. “20:00” or “8:00 PM”. This class is useful for representing alarms, office opening hours, etc.

The methods for this class are on the same pattern as that for LocalDate

Just like LocalDate, LocalTime also has lots of utility methods to manipulate time values.


LocalDateTime combines LocalDate and LocalTime and stores year-month-day-hours-minutes-seconds-nanoseconds. E.g. 15 Jun 2014 at 20:00. This class can be useful for representing restaurant reservations, music concert timings etc. The API is very similar to the previous 2 classes.


ZonedDateTime is the main date/time class that has time zone support. The other classes that are used by the library to represent time zone related information are

  • ZoneId – e.g. “Europe/London”
  • ZoneOffset – “+05:30”, i.e. offset from UTC
  • ZoneRules – behind the scenes class that represents the rules that govern a particular time zone. Not used directly by your code

A ZonedDateTime object stores LocalDateTime, ZoneId and ZoneOffset. e.g. 15th June 2014 at 20:00, 05:30 hours ahead of UTC. This class is the closest equivalent of java.util.GregorianCalendar class.

As with other library classes, the API is quite intuitive


The Instant class is a timestamp. It is useful for representing machine time. A value returned from the Instant class counts time (nanoseconds) beginning from the first second of January 1, 1970 (1970-01-01T00:00:00Z) also called the EPOCH. An instant that occurs before the epoch has a negative value, and an instant that occurs after the epoch has a positive value. Instant objects are useful, for example, while logging. This class is the closest equivalent of java.util.Date.


All the classes that we’ve seen till now, represent instances on the timeline. The amount classes, however, are not tied to the timeline. They are used to represent amount of time, e.g. 3 years, 40 minutes, etc. There are two amount classes in the new library:

  • Duration
  • Period


Duration is useful for representing time based amount – hours, minutes, seconds and nanoseconds. Useful for representing stop watch, timeouts, etc.

Duration objects can also be added to datetime objects


Period objects can be used to represent date based amounts (years, months, days). They can be used to refer to duration of projects for example.


Happy coding!


3 Responses to “Java 8’s Date Time API Quickstart”

  1. Good overview – thanks for this. It seems like a very clean and useful interface to dates.

  2. Nice overview, but I really missed date formatting part. Java 8 solves that problem as well, no more reliance on non thread-safe SimpleDateFormat class.