Java Date & Time API (java.time)

// Legacy, error-prone approach
Date oldDate = new Date(2024 - 1900, 0, 15);  // confusing offset year AND zero-based month for January 15, 2024!

// Modern, clear approach
LocalDate newDate = LocalDate.of(2024, 1, 15);  // January 15, 2024 -- reads exactly as intended, no offsets

Common follow-ups: Why is immutability specifically such a valuable property for a date/time class, beyond just general good practice?;What specific library inspired java.time's design, and did that library's author actually work on java.time itself?

LocalDate birthday = LocalDate.of(1990, 5, 15);              // just a date, no time or zone
LocalTime lunchTime = LocalTime.of(12, 30);                    // just a time, no date or zone
LocalDateTime meeting = LocalDateTime.of(2024, 6, 1, 14, 0);    // date+time, but no zone -- ambiguous globally
ZonedDateTime flight = ZonedDateTime.of(meeting, ZoneId.of("America/New_York"));  // fully unambiguous

Common follow-ups: Why is LocalDateTime specifically dangerous to use for representing a genuine, globally-unambiguous instant in time?;How does Instant differ from all four of these types, and when would you use it instead?

Instant now = Instant.now();  // pure timestamp, e.g. 2024-06-01T18:30:00Z, no calendar/timezone concept
System.out.println(now);

// Convert to a human-readable local representation for a SPECIFIC timezone when needed for display
ZonedDateTime nyTime = now.atZone(ZoneId.of("America/New_York"));
ZonedDateTime tokyoTime = now.atZone(ZoneId.of("Asia/Tokyo"));
// Both represent the EXACT SAME underlying instant, just displayed differently for each timezone

Common follow-ups: Why is it generally considered bad practice to store Instant values converted to a specific ZonedDateTime in a database, rather than storing the Instant/UTC value directly?;How does Instant's nanosecond precision compare to the precision typically available from java.util.Date's millisecond-based design?

LocalDate start = LocalDate.of(2024, 1, 15);
LocalDate end = LocalDate.of(2024, 6, 20);
Period period = Period.between(start, end);
System.out.println(period.getMonths() + " months, " + period.getDays() + " days");  // calendar-aware difference

Instant startTime = Instant.now();
Instant endTime = startTime.plusSeconds(3661);
Duration duration = Duration.between(startTime, endTime);
System.out.println(duration.toHours() + "h " + duration.toMinutesPart() + "m");  // exact elapsed time

Common follow-ups: What happens if you try to compute a Period between two Instant values, or a Duration between two LocalDate values -- does it compile?;How does Period.between() handle the calculation when the day-of-month values don't align evenly (like from January 31 to March 1)?

ZoneId nyZone = ZoneId.of("America/New_York");
// Suppose DST 'springs forward' from 2:00 AM to 3:00 AM on this specific date
ZonedDateTime beforeTransition = ZonedDateTime.of(2024, 3, 10, 1, 30, 0, 0, nyZone);
ZonedDateTime afterAddingHour = beforeTransition.plusHours(1);
// Result correctly accounts for the DST gap -- the LOCAL time jumps by more than a naive 1-hour addition would suggest
System.out.println(afterAddingHour);  // reflects the actual wall-clock time after the DST transition

Common follow-ups: What's the practical difference between using plusDays() on a ZonedDateTime versus adding an equivalent Duration to an Instant, specifically regarding DST?;How would you specifically detect and handle the ambiguous 'fall back' scenario where a local time occurs twice?

// Modern, thread-safe DateTimeFormatter -- safe to share as a static final constant across threads
private static final DateTimeFormatter FORMATTER = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");

LocalDateTime dateTime = LocalDateTime.parse("2024-06-01 14:30:00", FORMATTER);
String formatted = dateTime.format(FORMATTER);

// vs. the OLD, unsafe-to-share SimpleDateFormat, which required per-use or per-thread instances
// SimpleDateFormat oldFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");  // NOT safe as a shared static field!

Common follow-ups: What specific internal mutable state made SimpleDateFormat unsafe for concurrent use in the first place?;How do DateTimeFormatter's predefined ISO formatters differ from a custom ofPattern()-based formatter in terms of strictness and flexibility?

// Modern code internally uses Instant
Instant modernInstant = Instant.now();

// Convert to legacy Date only at the boundary where a legacy API requires it
Date legacyDate = Date.from(modernInstant);
legacyLibraryMethod(legacyDate);  // some older API that still requires java.util.Date

// Convert a legacy Date received FROM an old API back to modern Instant
Instant convertedBack = legacyDate.toInstant();

Common follow-ups: Why do these specific bridge methods exist only on Date/Calendar and their java.time counterparts, but not for the even older java.sql.Date/Timestamp classes as directly?;What's the recommended approach if a legacy library's API can't be avoided long-term and is used extensively throughout a codebase?

LocalDate today = LocalDate.of(2024, 6, 15);  // a Saturday

LocalDate nextMonday = today.with(TemporalAdjusters.next(DayOfWeek.MONDAY));
LocalDate lastDayOfMonth = today.with(TemporalAdjusters.lastDayOfMonth());
LocalDate firstDayOfNextMonth = today.with(TemporalAdjusters.firstDayOfNextMonth());

System.out.println(nextMonday);        // 2024-06-17
System.out.println(lastDayOfMonth);    // 2024-06-30

Common follow-ups: How would you write a completely custom TemporalAdjuster for a business-specific date rule not covered by the built-in ones (like 'next business day, skipping weekends')?;What's the difference between TemporalAdjusters.next() and nextOrSame() for a date that already falls on the target day of week?

public class NextBusinessDayAdjuster implements TemporalAdjuster {
    private final Set<LocalDate> holidays;
    public NextBusinessDayAdjuster(Set<LocalDate> holidays) { this.holidays = holidays; }

    @Override
    public Temporal adjustInto(Temporal temporal) {
        LocalDate date = LocalDate.from(temporal);
        do {
            date = date.plusDays(1);
        } while (date.getDayOfWeek() == DayOfWeek.SATURDAY
              || date.getDayOfWeek() == DayOfWeek.SUNDAY
              || holidays.contains(date));
        return temporal.with(date);
    }
}

LocalDate next = today.with(new NextBusinessDayAdjuster(companyHolidays));

Common follow-ups: How would you make this custom adjuster's holiday lookup efficient for a very large date range or high-frequency usage pattern?;What's the benefit of implementing this as a proper TemporalAdjuster versus just writing a standalone utility method with the same logic?

LocalDate birthDate = LocalDate.of(2000, 2, 29);  // a leap-day birthday
LocalDate nonLeapYear = LocalDate.of(2023, 1, 1);  // 2023 is NOT a leap year

long age = ChronoUnit.YEARS.between(birthDate, LocalDate.now());

// Handling the Feb 29 edge case explicitly for a non-leap year
LocalDate thisYearsBirthday = birthDate.withYear(2023).isLeapYear()
    ? birthDate.withYear(2023)
    : LocalDate.of(2023, 2, 28);  // or March 1, depending on the business's chosen convention

Common follow-ups: What determines whether a given year is a leap year, and how does LocalDate.isLeapYear() implement this check?;How would ChronoUnit.DAYS.between() behave differently from Period.between().getDays() for computing a difference spanning multiple months?