Legacy Date API

// ── Date's name is misleading — it's really just an instant in milliseconds
Date now = new Date();
System.out.println(now.getTime());   // a single long: milliseconds since the epoch
// There is NO separate field for "just the date part" — Date IS the millisecond count,
// full stop, with a time-of-day and implicit zone baked in whether wanted or not

// ── Deprecated since Java 1.1 — yet still technically callable ────────
Date deprecatedConstructed = new Date(2024 - 1900, 5, 15);   // year is OFFSET from 1900!!
System.out.println(deprecatedConstructed.getYear());          // 124 — ALSO offset from 1900
// Both the constructor AND getYear() use this bizarre, easy-to-get-wrong 1900 offset —
// a frequent, very real source of off-by-1900 bugs in old codebases

// ── The "correct" pre-java.time way to extract fields required Calendar
Calendar cal = Calendar.getInstance();
cal.setTime(now);
int year = cal.get(Calendar.YEAR);   // the actual, non-offset year — but via a SEPARATE class

// ── Date is MUTABLE — a shared reference can be changed out from under you
public class Appointment {
    private Date when;
    public Date getWhen() { return when; }   // returns the LIVE, mutable object directly!
}

Appointment appt = new Appointment();
Date exposedRef = appt.getWhen();
exposedRef.setTime(0L);   // ← THIS SILENTLY CORRUPTS appt's internal state too —
// both references point at the exact same mutable Date object

// ── SimpleDateFormat — NOT thread-safe, sharing across threads is a real bug
private static final SimpleDateFormat SHARED_FORMAT =
    new SimpleDateFormat("yyyy-MM-dd");   // DANGEROUS if multiple threads call it concurrently

// Two threads calling SHARED_FORMAT.format(...) or .parse(...) at the same time
// can corrupt each other's internal Calendar state, producing wrong dates silently

// ── The defensive (but easy to forget) old workaround ──────────────────
private static final ThreadLocal<SimpleDateFormat> THREAD_SAFE_FORMAT =
    ThreadLocal.withInitial(() -> new SimpleDateFormat("yyyy-MM-dd"));

// ── Legacy Date → java.time, via Instant as the bridge ────────────────
Date legacyDate = new Date();
Instant instant = legacyDate.toInstant();             // capture the SAME instant, java.time-side
ZonedDateTime zoned = instant.atZone(ZoneId.of("Asia/Tokyo"));   // full java.time API from here

System.out.println(zoned);   // human-readable, zone-aware — do all real logic from this point on

// ── java.time → legacy Date, at the boundary, right before a legacy API call
Instant resultInstant = Instant.now();
Date forLegacyApi = Date.from(resultInstant);   // convert back ONLY when a legacy API demands it

legacyApiThatStillTakesDate(forLegacyApi);   // some old method signature requiring java.util.Date

// ── Recommended pattern: convert at the boundary, do all logic in java.time
void processIncoming(Date incoming) {
    LocalDateTime working = incoming.toInstant()
        .atZone(ZoneId.systemDefault())
        .toLocalDateTime();   // ← all subsequent logic uses THIS, never the raw Date again
}