Lesson 10 – New Date & Time Library

Lesson 10 – New Date & Time Library

Ok, In this lesson we will cover the Java date & time library. We can use this to create, edit and manipulate dates in our programs. This is something which no data type we have learnt so far is particularly good at. We will also briefly cover the old Date and time classes and why these were upgraded in Java 8.


To get started you can use the basic starter project and follow the steps to compile the code examples for the lesson.

Please note that the Date and Time library covered in this lesson is new to java 8. Therefore you will need to be using a minimum version of the java 8 JDK or JRE. If you have an older version installed please upgrade here. For info on how to do this please revisit my setting up guide

The old date library

Up to and including Java 7 there was still the ability to create Date and time functionality mainly through the java.util.Date and the java.util.Calendar classes. These classes where poorly written and became even more difficult to use from version to version. The main issues with the old Date and Time classes are:

  • Poor naming – a Date was actually a timestamp and a Calendar was actually a mixture of date’s and times.
  • Limited ability to support different timezones
  • Concurrency issues – we will cover this subject in the advanced course
  • Months starting with zero instead of 1, Dates must have a year etc
  • Inoperability with other ‘Date’ type classes

All in all using the standard Date classes in java up until java 8 was extremely troublesome. For this reason many developers choose to use another library called Joda time instead of the default classes.

Thankfully Joda’s approach has now been taken onboard and a new Date and Time library has been created in java 8.

What is a library?

A library is a collection of prewritten classes which can be specified and used by a programmer when developing a program

Ok, lets start to learn the main classes of the new Date and Time Library.


The easiest way to get the time ‘right now’ is with the Clock class.

Notice that we don’t use the new keyword. This is because this class is known as abstract which means we cant create (or instantiate) it. Instead we use special methods which return copies of Clocks to us.

systemUTC() is a method which returns the date and time ‘right now’ using the UTC timezone.

UTC – the time standard used commonly across the world. The world’s timing centers have agreed to keep their time scales closely synchronized – or coordinated – therefore the name Coordinated Universal Time.

To use the default time zone on the machine the code is being run on we can also use systemDefaultZone().

It is important to realise that this has a dependency to the timezone the machine running your code is set to. Java recommends that instead you explicitly state which timezone you want to be in. This way the behaviour of your code will not change if you’re running the program in different locations of the world.


The LocalDateTime class is a time without a timezone. This class is simply a way to describe a date and does not represent an actual exact time anywhere. We use it to describe a date and time such as a birthday or anniversaries.

There are many ways to create these. Here are some examples:

You’ll notice that again we do not use the new keyword. Instead we use special helper methods to create the LocalDateTime for us. You’ll also notice in the last few examples that we have other helper classes/methods we can use to create Years, Months and DayOfWeeks for us.

For a full list of the parameters we pass to the of method above practice creating LocalDateTimes in your IDE with auto complete and/or use Oracle’s official documentation


LocalDate is similar to LocalDateTime but with out the time or timezone. To create this we have various methods we can use on the LocalDate class:

Again this can be used for things like birthdays and other dates that do not require times or timezones.


Conversely, LocalTime is similar to LocalDateTime but with out the Date or timezone added. To create this we have various methods we can use on the LocalTime class:

All of the above classes (LocalDateTime, LocalDate and LocalTime) cannot be used to find an exact point in time due to there lack of timezone functionality. So these are just used to represent date and times in a human readable way.


To represent an exact point in time we can use the Instant class:

You can also convert Strings into Instants:



As always play around with the examples and try to use them in your own basic program.

Next: Primitive types vs wrapper classes