Introduction

This article demonstrates the usage of LocalDateTime with examples.

Starting from Java 8, the java.time package provides a new date and time API. The main types include:

• Local date and time: LocalDateTime, LocalDate, LocalTime;
• Date and time with time zone: ZonedDateTime;
• Instant: Instant;
• Time zones: ZoneId, ZoneOffset;
• Time intervals: Period, Duration – representing the difference between two dates or times;
• DateTimeFormatter replaces SimpleDateFormat.

Compared to the old API, the new API strictly distinguishes between instants, local dates, local times, and zoned date times, making date and time calculations more convenient. Additionally, the new API fixes unreasonable constant designs from the old API:

• Month ranges from 1 to 12 for January to December;
• Week ranges from 1 to 7 for Monday to Sunday.

All new API types are immutable (similar to String), so they can be safely used with out concern for modification.

Corresponding SQL Types

SQL Type	Java Type
date	LocalDate
time	LocalTime
timestamp	LocalDateTime

Common Operations

Note: All the following usages are similar for LocalDate and LocalTime.

Creation

Create a LocalDateTime from year, month, day, hour, minute, second, nanosecond, etc.

// Examples:
LocalTime zero = LocalTime.of(0, 0, 0); // 00:00:00
LocalTime mid = LocalTime.parse("12:00:00"); // 12:00:00
LocalTime now = LocalTime.now(); // 23:11:08.006

// All creation methods:
LocalDateTime of(LocalDate date, LocalTime time)
LocalDateTime of(int year, Month month, int dayOfMonth, int hour, int minute)
LocalDateTime of(int year, Month month, int dayOfMonth, int hour, int minute, int second)
LocalDateTime of(int year, Month month, int dayOfMonth, int hour, int minute, int second, int nanoOfSecond)
LocalDateTime of(int year, int month, int dayOfMonth, int hour, int minute)
LocalDateTime of(int year, int month, int dayOfMonth, int hour, int minute, int second)
LocalDateTime of(int year, int month, int dayOfMonth, int hour, int minute, int second, int nanoOfSecond)

Conversion with Date

Convert Date to LocalDateTime

Date date = new Date();
LocalDateTime dateTime = date.toInstant()
    .atZone(ZoneId.systemDefault())
    .toLocalDateTime();
// Alternative with specific time zone:
// LocalDateTime dateTime = date.toInstant().atZone(ZoneId.of("Asia/Shanghai")).toLocalDateTime();
// LocalDateTime dateTime = date.toInstant().atOffset(ZoneOffset.ofHours(8)).toLocalDateTime();

Note: Date is from the java.util package.

Convert LocalDateTime to Date

LocalDateTime now = LocalDateTime.now(ZoneId.systemDefault());
Date date = Date.from(now.atZone(ZoneId.systemDefault()).toInstant());

Conversion with LocalDate/LocalTime

The conversion methods are straightforward:

• toLocalDate(): extracts the date part.
• toLocalTime(): extracts the time part.

LocalDateTime dateTime = LocalDateTime.now();
LocalDate date = dateTime.toLocalDate();
LocalTime time = dateTime.toLocalTime();

This concludes the usage guide for LocalDateTime.