The New Date-Time API: LocalDate, LocalTime, LocalDateTime

Published: May 17, 2016

---

Introduction

Java 8 introduced a completely new Date-Time API that revolutionized how dates and times are handled in Java. The new API is built around immutable objects, which helps avoid the many issues with the old Date and Calendar classes.

In this tutorial, we will focus on:

• The basics of the new Date-Time API.
• Working with LocalDate, LocalTime, and LocalDateTime.
• How these new classes are more intuitive and less error-prone than the old classes.

---

Why a New Date-Time API?

The old Date and Calendar classes were not designed to be thread-safe, and they often required a lot of boilerplate code to manipulate dates and times. Additionally, these classes used 1-based indexing, which could be confusing.

Java 8 introduced the java.time package, which provides a new set of classes designed to handle dates and times in a more reliable, predictable, and readable way.

---

The Core Classes of the New Date-Time API

There are several key classes introduced in the java.time package. The most commonly used classes are:

1. LocalDate – Represents a date without time (e.g., 2023-03-14).
2. LocalTime – Represents a time without a date (e.g., 12:30:45).
3. LocalDateTime – Combines both date and time without a time-zone (e.g., 2023-03-14T12:30:45).

Let’s now look at examples of how to use these classes.

---

Working with LocalDate

LocalDate represents a date in the ISO-8601 calendar system (e.g., 2023-03-14). It does not include any time information.

Creating a LocalDate

You can create a LocalDate object using one of the following methods:

import java.time.LocalDate;

public class DateExample {
    public static void main(String[] args) {
        // Current date
        LocalDate today = LocalDate.now();
        System.out.println("Today's date: " + today);

        // Specific date
        LocalDate specificDate = LocalDate.of(2016, 2, 17);
        System.out.println("Specific date: " + specificDate);
    }
}

Output:

Today's date: 2023-03-14
Specific date: 2016-02-17

---

Manipulating Dates

You can perform various operations on LocalDate, such as adding or subtracting days, months, or years.

LocalDate today = LocalDate.now();
LocalDate tomorrow = today.plusDays(1);
LocalDate nextMonth = today.plusMonths(1);
LocalDate lastYear = today.minusYears(1);

System.out.println("Tomorrow: " + tomorrow);
System.out.println("Next month: " + nextMonth);
System.out.println("Last year: " + lastYear);

Output:

Tomorrow: 2023-03-15
Next month: 2023-04-14
Last year: 2022-03-14

---

Working with LocalTime

LocalTime represents a time without a date. It can store hours, minutes, seconds, and nanoseconds.

Creating a LocalTime

import java.time.LocalTime;

public class TimeExample {
    public static void main(String[] args) {
        // Current time
        LocalTime currentTime = LocalTime.now();
        System.out.println("Current time: " + currentTime);

        // Specific time
        LocalTime specificTime = LocalTime.of(14, 30, 0);
        System.out.println("Specific time: " + specificTime);
    }
}

Output:

Current time: 12:30:45.123
Specific time: 14:30

---

Manipulating Time

Just like LocalDate, you can also perform operations on LocalTime, such as adding or subtracting hours, minutes, or seconds.

LocalTime time = LocalTime.of(14, 30);
LocalTime later = time.plusHours(2);
LocalTime earlier = time.minusMinutes(15);

System.out.println("Later time: " + later);
System.out.println("Earlier time: " + earlier);

Output:

Later time: 16:30
Earlier time: 14:15

---

Working with LocalDateTime

LocalDateTime combines both date and time in one object. This is useful when you need to work with both date and time but do not require time-zone information.

Creating a LocalDateTime

import java.time.LocalDateTime;

public class DateTimeExample {
    public static void main(String[] args) {
        // Current date and time
        LocalDateTime now = LocalDateTime.now();
        System.out.println("Current date and time: " + now);

        // Specific date and time
        LocalDateTime specificDateTime = LocalDateTime.of(2023, 3, 14, 12, 30);
        System.out.println("Specific date and time: " + specificDateTime);
    }
}

Output:

Current date and time: 2023-03-14T12:30:45.123
Specific date and time: 2023-03-14T12:30

---

Manipulating DateTime

You can also perform date-time arithmetic with LocalDateTime, adding or subtracting time units.

LocalDateTime dateTime = LocalDateTime.now();
LocalDateTime futureDateTime = dateTime.plusWeeks(1);
LocalDateTime pastDateTime = dateTime.minusDays(5);

System.out.println("Future date and time: " + futureDateTime);
System.out.println("Past date and time: " + pastDateTime);

Output:

Future date and time: 2023-03-21T12:30:45.123
Past date and time: 2023-03-09T12:30:45.123

---

Conclusion

The new Date-Time API in Java 8 provides a much more flexible and reliable way to handle dates and times. By using classes like LocalDate, LocalTime, and LocalDateTime, you can avoid the pitfalls of the old Date and Calendar classes. These new classes offer an easy-to-understand and thread-safe approach to working with dates and times in Java.

In the next tutorial, we will explore Understanding the Comparator Interface in Java 8 and how it can be used to sort and compare objects.