Background & Introduction: Until Java 7 java.util.Date
was all that the JDK provided for handling dates, time, and dates with time. Java 8’s new Date-Time APIRead Overview of what has changed in Java 8’s new Date-Time API has acknowledged the difference in these three types of date and time usages and accordingly defined different classes for each of them in the new java.time
package. LocalDate
, LocalTime
and LocalDateTime
are thus separate classes, although they are related and interchangeable, thus facilitating date and time handling for a myriad set of scenarios.
Java 8 designers have defined similar method naming and usage patterns for LocalDate
, LocalTime
and LocalDateTime
classes and this would allow us to look at these classes together. The sections in this tutorial are also divided as per the method names, i.e. each section covers a method and its usage for all three classes.
Note – I will refer the three classes, LocalDate
, LocalTime
and LocalDateTime
, together as LocalXXX
going forward.
What this tutorial covers
- To begin with, we will first see a quick introduction and understand the purpose of
LocalXXX
classes. - Next we will understand the inherent immutability of the date-time classes.
- We will then look at the static methods used to create instances of these classes viz.
now()
andof()
methods. - Next we will go through the methods meant for modifying individual date-time attributes stored in
LocalXXX
objects, i.e. the methods with ‘plus
’/‘minus
’ and ‘with
’ prefixes. - Lastly, we will take a look at the methods provided for ‘getting’ specific date-time values from the
LocalXXX
instances.
Purpose of LocalXXX
Date-Time classes
java.time.LocalDate: A LocalDate instance holds a date without a time zone, in ISO-86011 calendar system. LocalDate has the default format ‘YYYY-MM-DD’ as in ‘2016-12-12’.
java.time.LocalTime: A LocalTime holds time in the ISO-8601 calendar system, without any date or time zone information associated with it. The format is typically – ‘HH:mm:ss’ as in ‘12:10:35’. LocalTime can be upto nanosecond precision(after the last second) with the format ‘HH:mm:ss.nnnnnnnnn’ as in ‘12:10:35.123456789’.
java.time.LocalDateTime: Represents a Date and Time without a time zone in the ISO-8601 format. Its typical format is ‘YYYY-MM-DDTHH:mm:ss’. (Notice the ‘T’ separating days from hours) as in ‘2016-12-12T12:10:35’. LocalDateTime can also have a nanosecond-of-the-second component like in LocalTime.
Immutability of LocalXXX
Classes
The instances of all three classes – LocalDate
, LocalTime
and LocalDateTime
are immutable. I.e. the LocalXXX
objects with a specific date and/or time information, once created, cannot be modified.
You might come across many methods, including the ones explained further in this tutorial, which modify LocalXXX
objects and returned objects with modified values. It is important to note that what you are getting back from these modification methods are in fact new immutable objects and not the modified versions of previous objects. So, in order to not allow errors to creep in your logic, always assign the returned objects from methods such as plus()
/minus()
/with()
etc to a new LocalXXX
object of the same type, and then use this new object further in your code.
Having understood what values LocalDate
, LocalTime
or LocalDateTime
hold, let us now take a look at the methods which the new Date-Time API provides to us in order to instantiate, modify, and fetch values from the LocalXXX
objects.
Creation of LocalXXX
instances
The 2 most important ways in which you will be instantiating LocalXXX
objects are via the static methods now()
and of()
–
- Using static method
LocalXXX.now()
method: All three date-time classes provide the static methodnow()
which fetches the date(forLocalDate
), time(forLocalTime
) and date-time(forLocalDateTime
) from the system clock of the machine on which the JVM is running. Given next are the three methods in action, followed by output showing the values returned by these methods.
OUTPUT of the above codeJava 8 code showing LocalXXX.now() usageLocalDate localDate = LocalDate.now(); System.out.println("localDate: "+localDate); LocalTime localTime =LocalTime.now(); System.out.println("localTime: "+localTime); LocalDateTime localDateTime =LocalDateTime.now(); System.out.println("localDateTime: "+localDateTime);
localDate: 2016-12-16
localTime: 12:15:26.343
localDateTime: 2016-12-16T12:15:26.344 - Using static method
LocalXXX.of()
method:LocalXXX.of()
method takes as input the individual values constituting date-time asint
parameters. These are values corresponding to date, month, year, hours, minutes, seconds and seconds inint
format. Usage ofof()
method is as follows –
OUTPUT of the above codeJava 8 code showing LocalXXX.of() usageLocalDate localDate = LocalDate.of(2016,12,01); System.out.println("localDate: "+localDate); LocalTime localTime =LocalTime.of(23,12,56,234); System.out.println("localTime: "+localTime); LocalDateTime localDateTime =LocalDateTime.of(2016,12,01,23,12,56,234); System.out.println("localDateTime: "+localDateTime); LocalDate localDateNov = LocalDate.of(2016, Month.NOVEMBER,01); System.out.println("localDateNov: "+localDateNov);
localDate: 2016-12-01
localTime: 23:12:56.000000234
localDateTime: 2016-12-01T23:12:56.000000234
localDateNov: 2016-11-01- First an instance of
LocalDate
, namedlocalDate
, is created foryear=2016
,month=12
, anddate=01
. - Next an instance of
LocalTime
, namedlocalTime
, is created forhour=23
,minute=12
,second=56
, andnanosecond=234
. - Next a
LocalDateTim
e instance is created wherein the sameint
values used forlocalDate
andlocalTime
are passed as input to theof()
method. - Lastly, an overridden usage of
LocalDate.of()
method is shown where for the month an enum value –Month.November
is passed to createlocalDateNov
instance.
- First an instance of
(Note – There is another method for creating the LocalXXX
instances which is parse(). I will cover this method in a separate detailed tutorial on Java8 Date-Time parsing and formatting.)
Modifying LocalXXX
instances
Modification of LocalDate, LocalTime and LocalDateTime objects can be done via two varieties of methods – the methods with prefix as ‘plus’/’minus’ and those with prefix ‘with’.
LocalXXX.plus()
/minus()
methods: The plus/minus methods work by adding or subtracting the required number of days, months, years, hours, minutes, seconds and nanoseconds toLocalXXX
objects. Each of theLocalXXX
classes provide methods for plus/minus for each field of date and time they store. So,LocalDate
hasplusDays()
andminusDays()
methods, whileLocalTime
has aplusMinutes()
andminusMinutes()
methods, and so on.Let us see a few of the variants of these methods in action. For further examples on these methods you can refer the tutorial on Java 8 date-time calculationsRead tutorial on Java 8 Date-Time calculations.
OUTPUT of the above codeJava 8 code showing LocalXXX.plus()minus() methods usageSystem.out.println("Today: "+LocalDate.now()); LocalDate todayPlus10Days=LocalDate.now().plusDays(10); System.out.println("localDatePlus10: "+todayPlus10Days); System.out.println("Time Now: "+LocalTime.now()); LocalTime nowMinus20Minutes=LocalTime.now().minusMinutes(20); System.out.println("nowMinus20Minutes: "+nowMinus20Minutes); System.out.println("Date-Time Now: "+LocalDateTime.now()); LocalDateTime nowPlus2Years =LocalDateTime.now().plusYears(2); System.out.println("todayPlus2Years: "+nowPlus2Years);
Today: 2016-12-16
localDatePlus10: 2016-12-26Time Now: 20:36:26
nowMinus20Minutes: 20:16:26Date-Time Now: 2016-12-16T20:36:26
todayPlus2Years: 2018-12-16T20:36:26- First example for
LocalDate
– creates an instance ofLocalDate
usingLocalDate.now()
, and then adds 10 days to it usingplusDays(10)
. - Second example for
LocalTime
– creates an instance ofLocalTime
usingLocalTime.now()
, and then subtracts 20 minutes from it usingminusMinutes(20)
. - Third example for
LocalDateTime
– creates aLocalDateTime
instance using thenow()
method, and then adds 2 years to it usingplusYears(2)
. - Note – there couple of variants of
plus()
andminus()
operations which are defined inTemporal
3– the parent interface ofLocalXXX
classes. I will be covering theTemporal
/TemporalUnit
/TemporalAmount
handling in a separate tutorial on temporals.
- First example for
LocalXXX.with()
methods:The with methods work by setting the required number of days, months, years, hours, minutes, seconds and nanoseconds in theLocalXXX
objects. Each of theLocalXXX
classes provide specific with() methods for setting each each field of date and time they store. So,LocalDate
has awithDaysOfMonth()
method, whileLocalTime
has awithMinute()
method, and so on. Let us see a few of the variants of these methods in action –
OUTPUT of the above codeJava 8 code showing LocalXXX.with() methods usageSystem.out.println("Today: "+LocalDate.now()); LocalDate dayOfMonth20=LocalDate.now().withDayOfMonth(20); System.out.println("Day of month set as 20: "+dayOfMonth20); System.out.println("Time Now: "+LocalTime.now()); LocalTime minute0=LocalTime.now().withMinute(0); System.out.println("Minutes set to 0: "+minute0); System.out.println("Date-Time Now: "+LocalDateTime.now()); LocalDateTime month10 =LocalDateTime.now().withMonth(10); System.out.println("Month set to 10: "+month10);
Today: 2016-12-19
Day of month set as 20: 2016-12-20Time Now: 15:13:27.175
Minutes set to 0: 15:00:27.175Date-Time Now: 2016-12-19T15:13:27.176
Month set to 10: 2016-10-19T15:13:27.176- First example for
LocalDate
– creates an instance ofLocalDate
usingLocalDate.now()
, and then sets the day value to20
. - Second example for
LocalTime
– creates an instance ofLocalTime
usingLocalTime.now()
, and then sets the minutes value to00
. - Third example for
LocalDateTime
– creates aLocalDateTime
instance using thenow()
method, and then sets the month value to10
. - Note – there couple of variants of
with()
operations which are defined inTemporal
which useTemporalAdjuster
andTemporalField
values. I will be covering these in separate tutorials onTemporalAdjuster
andTemporal
respectively.
- First example for
Fetching individual fields of LocalXXX
All three LocalXXX
classes define methods to fetch individual values of their fields. The naming of these methods matches the naming for with()
methods in the classes. So, LocalDate has getDayofMonth()
, getMonth()
, getDays()
methods, while LocalTime
has getHour()
, getMinute()
, getSecond()
, getNano()
methods. Similarly there are get()
methods for LocalDateTime
. Let us see a few of these methods used in code to better understand their usage –
System.out.println("Today: "+LocalDate.now()); int dayOfMonth=LocalDate.now().getDayOfMonth(); System.out.println("Day of month is: "+dayOfMonth); System.out.println("Time Now: "+LocalTime.now()); int minute=LocalTime.now().getMinute(); System.out.println("Minutes value is: "+minute); System.out.println("Date-Time Now: "+LocalDateTime.now()); Month month = LocalDateTime.now().getMonth(); System.out.println("Month value is: "+month.getValue());
Day of month is: 19
Time Now: 15:42:08.775
Minutes value is: 42
Date-Time Now: 2016-12-19T15:42:08.775
Month value is: 12
- First example for
LocalDate
– creates an instance ofLocalDate
using LocalDate.now(), and then fetches the value ofday
usinggetDayOfMonth()
as19
. - Second example for
LocalTime
– creates an instance ofLocalTime
usingLocalTime.now()
, and then fetches the value ofminute
usinggetMinute()
as42
. - Third example for
LocalDateTime
– creates aLocalDateTime
instance using thenow()
method, and then fetches the value ofmonth
by usinggetMonth()
to get an instance ofjava.time.Month
and then usingMonth.getValue()
to get the value as12
. - Note – there are couple of variants of
get()
operations which are defined inTemporalAccessor
4– which allLocalXXX
classes implement – which useTemporalField
values. I will be covering these in separate tutorials onTemporal
s.
Summary
In the above tutorial we understood how to work with LocalDate
, LocalTime
and LocalDateTime
classes. We understood the purpose of each of the date-time classes, learnt the implications of their immutable instances, saw how to create, modify and fetch the values of each of the classes using their similarly-named methods.
3. Official LocalTime API reference
4. Official LocalDateTime API reference
5. Official Temporal API reference
6. Official TemporalAccessor API reference
Overview of Java 8’s new Date and Time APIClick to Read Overview of Java 8’s new Date-Time API Working with time zones in Java 8| ZonedDateTime, ZoneId tutorial with examplesClick to Read tutorial on time zone handling in Java 8 How to convert LocalDate to String and String to LocalDateClick to Read tutorial on String to LocalDate conversions How to convert java.util.Date to java.time.LocalDateClick to Read tutorial on java.util.Date to LocalDate conversion Formatting localized dates in Spanish and FrenchClick to Read date formatting in Spanish & French How to get day-of-week for a given dateHow to get day-of-week using java.time.DayOfWeek enumDate Modification using TemporalAdjuster Click to Read Tutorial on TemporalAdjusters
