Calendar

// ── Calendar.getInstance() — factory method, not a public constructor ─
Calendar cal = Calendar.getInstance();   // returns a GregorianCalendar in virtually all real cases

// ── Field-based access — raw integer constants, not self-documenting methods
cal.set(Calendar.YEAR, 2024);
cal.set(Calendar.DAY_OF_MONTH, 15);
int year = cal.get(Calendar.YEAR);          // raw int, retrieved via a raw int CONSTANT
int dayOfMonth = cal.get(Calendar.DAY_OF_MONTH);

// ── Mutability — the SAME hazard as Date, carried forward into Calendar
Calendar shared = Calendar.getInstance();
someMethodThatTakesACalendar(shared);
shared.set(Calendar.YEAR, 1999);   // if someMethodThatTakesACalendar() kept a reference,
// its view of "shared" just silently changed too — same underlying object

// ── The infamous zero-indexed MONTH field — DAY_OF_MONTH is NOT zero-indexed
Calendar cal = Calendar.getInstance();
cal.set(Calendar.YEAR, 2024);
cal.set(Calendar.MONTH, 6);             // ← developer THINKS this means July...
cal.set(Calendar.DAY_OF_MONTH, 15);     // ← ...and correctly uses 15 for the 15th (1-indexed here!)

System.out.println(cal.get(Calendar.MONTH));   // 6 — but Calendar.JULY is actually 6... wait:
System.out.println(Calendar.JULY);              // 6 — OK this one happens to be right
System.out.println(Calendar.AUGUST);             // 7 — but set(MONTH, 7) would be AUGUST, not July!
// The constants exist PRECISELY because raw integers here are so easy to get wrong

// ── java.time's fix — Month is one-indexed, matching DAY_OF_MONTH's convention
LocalDate clearDate = LocalDate.of(2024, Month.JULY, 15);   // unambiguous, self-documenting

// ── getInstance() depends on AMBIENT, implicit JVM-wide Locale/TimeZone
Calendar implicitDefaults = Calendar.getInstance();              // uses default Locale + TimeZone
Calendar explicitZone = Calendar.getInstance(TimeZone.getTimeZone("Asia/Tokyo"));   // explicit instead

// ── add() — overflow CORRECTLY carries into the next larger field ─────
Calendar addCal = Calendar.getInstance();
addCal.set(2024, Calendar.DECEMBER, 15);
addCal.add(Calendar.MONTH, 1);
System.out.println(addCal.get(Calendar.YEAR) + "-" + (addCal.get(Calendar.MONTH) + 1));
// 2025-1 — correctly rolled over into January of the FOLLOWING year

// ── roll() — wraps WITHIN the field only, larger fields stay UNCHANGED ─
Calendar rollCal = Calendar.getInstance();
rollCal.set(2024, Calendar.DECEMBER, 15);
rollCal.roll(Calendar.MONTH, 1);
System.out.println(rollCal.get(Calendar.YEAR) + "-" + (rollCal.get(Calendar.MONTH) + 1));
// 2024-1 — STILL 2024! Month wrapped back to January, but the year did NOT advance

// ── Calendar's java.time equivalent — and the boundary-conversion bridge
LocalDate javaTimeEquivalent = LocalDate.of(2024, 12, 15).plusMonths(1);
System.out.println(javaTimeEquivalent);   // 2025-01-15 — unambiguous, matches add()'s behavior

Calendar legacyCal = Calendar.getInstance();
Instant fromCalendar = legacyCal.toInstant();   // same bridging pattern as Date.toInstant()