Master Core Java Programming From Scratch

Why Use the Modern Date and Time API?

Modern Java applications should generally use the java.time package for new date and time code.

The API provides immutable and thread-safe types for representing dates, times, date-time combinations, instants, durations, periods, and time zones.

java.time
    │
    ├── LocalDate
    ├── LocalTime
    ├── LocalDateTime
    ├── ZonedDateTime
    ├── Instant
    ├── Duration
    └── Period

LocalDate

LocalDate represents a date without a time and without a time zone.

import java.time.LocalDate;

LocalDate today =
    LocalDate.now();

System.out.println(today);

Creating a LocalDate

LocalDate date =
    LocalDate.of(
        2026,
        9,
        5
    );

System.out.println(date);

Output:

2026-09-05

LocalDate Methods

LocalDate date =
    LocalDate.of(
        2026,
        9,
        5
    );

System.out.println(
    date.getYear()
);

System.out.println(
    date.getMonth()
);

System.out.println(
    date.getDayOfMonth()
);

System.out.println(
    date.getDayOfWeek()
);

Output:

2026
SEPTEMBER
5
SATURDAY

Adding and Removing Date Values

Date-time objects are immutable. Methods such as plusDays() return a new value rather than modifying the existing object.

LocalDate date =
    LocalDate.of(
        2026,
        9,
        5
    );

LocalDate nextWeek =
    date.plusDays(7);

LocalDate previousMonth =
    date.minusMonths(1);

System.out.println(nextWeek);
System.out.println(previousMonth);

Output:

2026-09-12
2026-08-05

LocalTime

LocalTime represents a time without a date and without a time zone.

import java.time.LocalTime;

LocalTime currentTime =
    LocalTime.now();

System.out.println(
    currentTime
);

Creating a LocalTime

LocalTime time =
    LocalTime.of(
        14,
        30,
        15
    );

System.out.println(time);

Output:

14:30:15

LocalDateTime

LocalDateTime combines a date and time but does not contain time-zone information.

import java.time.LocalDateTime;

LocalDateTime now =
    LocalDateTime.now();

System.out.println(now);

Creating LocalDateTime

LocalDateTime meeting =
    LocalDateTime.of(
        2026,
        9,
        5,
        10,
        30
    );

System.out.println(meeting);

Output:

2026-09-05T10:30

ZonedDateTime

ZonedDateTime represents a date and time together with a time zone.

import java.time.ZoneId;
import java.time.ZonedDateTime;

ZonedDateTime indiaTime =
    ZonedDateTime.now(
        ZoneId.of(
            "Asia/Kolkata"
        )
    );

System.out.println(indiaTime);

ZoneId

ZoneId represents a time-zone identifier such as Asia/Kolkata or America/New_York.

ZoneId zone =
    ZoneId.of(
        "Asia/Kolkata"
    );

System.out.println(zone);

Output:

Asia/Kolkata

Instant

Instant represents a point on the UTC timeline. It is useful for timestamps and machine-oriented time values.

import java.time.Instant;

Instant timestamp =
    Instant.now();

System.out.println(
    timestamp
);

OffsetDateTime

OffsetDateTime represents a date and time with a UTC offset.

import java.time.OffsetDateTime;

OffsetDateTime value =
    OffsetDateTime.now();

System.out.println(value);

Period

Period represents a date-based amount of time in years, months, and days.

import java.time.Period;

Period period =
    Period.of(
        1,
        2,
        10
    );

System.out.println(period);

Output:

P1Y2M10D

Period.between()

LocalDate start =
    LocalDate.of(
        2025,
        1,
        1
    );

LocalDate end =
    LocalDate.of(
        2026,
        9,
        5
    );

Period difference =
    Period.between(
        start,
        end
    );

System.out.println(
    difference.getYears()
);

System.out.println(
    difference.getMonths()
);

System.out.println(
    difference.getDays()
);

Output:

1
8
4

Duration

Duration represents a time-based amount such as seconds and nanoseconds.

import java.time.Duration;

Duration duration =
    Duration.ofHours(5);

System.out.println(
    duration
);

Output:

PT5H

Duration.between()

LocalTime start =
    LocalTime.of(
        10,
        0
    );

LocalTime end =
    LocalTime.of(
        12,
        30
    );

Duration duration =
    Duration.between(
        start,
        end
    );

System.out.println(
    duration.toMinutes()
);

Output:

150

Period vs Duration

DateTimeFormatter

DateTimeFormatter formats date and time objects into strings and parses strings into date-time objects.

import java.time.LocalDate;
import java.time.format.DateTimeFormatter;

LocalDate date =
    LocalDate.of(
        2026,
        9,
        5
    );

DateTimeFormatter formatter =
    DateTimeFormatter.ofPattern(
        "dd-MM-yyyy"
    );

String formatted =
    date.format(
        formatter
    );

System.out.println(formatted);

Output:

05-09-2026

Parsing a Date

String text =
    "05-09-2026";

DateTimeFormatter formatter =
    DateTimeFormatter.ofPattern(
        "dd-MM-yyyy"
    );

LocalDate date =
    LocalDate.parse(
        text,
        formatter
    );

System.out.println(date);

Output:

2026-09-05

ISO Date Formats

The Java time API provides standard ISO-based formatters such as DateTimeFormatter.ISO_LOCAL_DATE.

LocalDate date =
    LocalDate.of(
        2026,
        9,
        5
    );

String value =
    date.format(
        DateTimeFormatter.ISO_LOCAL_DATE
    );

System.out.println(value);

Output:

2026-09-05

Comparing Dates

LocalDate first =
    LocalDate.of(
        2026,
        1,
        1
    );

LocalDate second =
    LocalDate.of(
        2026,
        9,
        5
    );

System.out.println(
    first.isBefore(second)
);

System.out.println(
    second.isAfter(first)
);

System.out.println(
    first.isEqual(second)
);

Output:

true
true
false

with() Methods

Date-time objects provide methods such as withYear(), withMonth(), and withDayOfMonth() to create modified values.

LocalDate date =
    LocalDate.of(
        2026,
        9,
        5
    );

LocalDate modified =
    date.withYear(2030);

System.out.println(modified);

Output:

2030-09-05

Month and DayOfWeek

The modern API provides enums such as Month and DayOfWeek.

LocalDate date =
    LocalDate.now();

Month month =
    date.getMonth();

DayOfWeek day =
    date.getDayOfWeek();

System.out.println(month);
System.out.println(day);

Converting Between Time Zones

ZonedDateTime india =
    ZonedDateTime.now(
        ZoneId.of(
            "Asia/Kolkata"
        )
    );

ZonedDateTime newYork =
    india.withZoneSameInstant(
        ZoneId.of(
            "America/New_York"
        )
    );

System.out.println(india);
System.out.println(newYork);

Clock

Clock provides an abstraction for obtaining the current instant and time. It can also make time-dependent application code easier to test.

import java.time.Clock;
import java.time.Instant;

Clock clock =
    Clock.systemUTC();

Instant now =
    clock.instant();

System.out.println(now);

Immutability

Classes in the modern Java date and time API are immutable. Operations return new objects rather than changing existing instances.

LocalDate original =
    LocalDate.of(
        2026,
        9,
        5
    );

LocalDate changed =
    original.plusDays(10);

System.out.println(original);
System.out.println(changed);

Output:

2026-09-05
2026-09-15

Legacy Date API

Older Java applications may contain classes such as java.util.Date and java.util.Calendar. New code should generally prefer the java.time API.

Example 👨‍🏫👀

A booking application may store an instant and display the booking time in the user's local time zone.

Instant bookingTime =
    Instant.now();

ZonedDateTime userTime =
    bookingTime.atZone(
        ZoneId.of(
            "Asia/Kolkata"
        )
    );

DateTimeFormatter formatter =
    DateTimeFormatter.ofPattern(
        "dd MMM yyyy HH:mm z"
    );

System.out.println(
    userTime.format(formatter)
);

Date and Time Best Practices

• Prefer the java.time API for new code.
• Use LocalDate when only a calendar date is required.
• Use LocalTime when only a local time is required.
• Use Instant for machine-oriented timestamps.
• Use ZonedDateTime when time-zone information matters.
• Use Duration for time-based amounts and Period for date-based amounts.
• Avoid using the legacy date API for new application code unless compatibility requires it.

Interview Questions