Java Date & Time API (java.time)

// Old API horrors
Date date = new Date(2024, 5, 15);     // Actually: year 3924, June 15
Calendar cal = Calendar.getInstance();
cal.set(Calendar.MONTH, 5);             // June, not May!
SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd");
// sdf is NOT thread-safe -- shared across threads = silent data corruption

// Creation
LocalDate today = LocalDate.now();                      // 2024-05-15
LocalDate specific = LocalDate.of(2024, Month.MAY, 15); // 2024-05-15
LocalDate parsed = LocalDate.parse("2024-05-15");       // ISO format

// Querying
int year = today.getYear();              // 2024
Month month = today.getMonth();          // MAY
int day = today.getDayOfMonth();         // 15
DayOfWeek dow = today.getDayOfWeek();    // WEDNESDAY
boolean isLeap = today.isLeapYear();     // true

// Manipulation (returns NEW instance -- immutable!)
LocalDate tomorrow = today.plusDays(1);
LocalDate lastMonth = today.minusMonths(1);
LocalDate endOfMonth = today.withDayOfMonth(today.lengthOfMonth());

// Comparison
today.isBefore(tomorrow);   // true
today.isAfter(lastMonth);   // true
today.isEqual(today);       // true

LocalTime now = LocalTime.now();                    // 14:30:45.123456789
LocalTime specific = LocalTime.of(14, 30, 45);     // 14:30:45
LocalTime parsed = LocalTime.parse("14:30:45");     // ISO format

LocalTime noon = LocalTime.NOON;                    // 12:00
LocalTime midnight = LocalTime.MIDNIGHT;            // 00:00
LocalTime max = LocalTime.MAX;                      // 23:59:59.999999999

// Manipulation
LocalTime later = now.plusHours(2).plusMinutes(30);
int hour = now.getHour();         // 14
int minute = now.getMinute();     // 30

LocalDateTime now = LocalDateTime.now();
LocalDateTime specific = LocalDateTime.of(2024, Month.MAY, 15, 14, 30);
LocalDateTime combined = LocalDateTime.of(
    LocalDate.of(2024, 5, 15),
    LocalTime.of(14, 30)
);

// Extract parts
LocalDate datePart = now.toLocalDate();
LocalTime timePart = now.toLocalTime();

// Convert to zoned
ZonedDateTime zoned = now.atZone(ZoneId.of("America/New_York"));
OffsetDateTime offset = now.atOffset(ZoneOffset.ofHours(-5));

Instant now = Instant.now();                          // 2024-05-15T09:00:00Z
Instant epoch = Instant.EPOCH;                         // 1970-01-01T00:00:00Z
Instant fromEpoch = Instant.ofEpochSecond(1715763600); // specific moment

// Arithmetic
Instant later = now.plusSeconds(3600);    // 1 hour later
Duration between = Duration.between(epoch, now);
long days = between.toDays();            // ~19858

// Convert to zoned
ZonedDateTime inKolkata = now.atZone(ZoneId.of("Asia/Kolkata"));

ZonedDateTime nowInNY = ZonedDateTime.now(ZoneId.of("America/New_York"));
ZonedDateTime nowInTokyo = ZonedDateTime.now(ZoneId.of("Asia/Tokyo"));

// Zone conversion
ZonedDateTime converted = nowInNY.withZoneSameInstant(ZoneId.of("Asia/Kolkata"));
// Same moment, different wall clock time

// DST-safe! Handles spring-forward / fall-back automatically
ZonedDateTime beforeDST = ZonedDateTime.of(
    2024, 3, 10, 1, 30, 0, 0, ZoneId.of("America/New_York")
);
ZonedDateTime afterDST = beforeDST.plusHours(1);
// Correctly jumps from 1:30 AM to 3:30 AM (2 AM doesn't exist)

OffsetDateTime odt = OffsetDateTime.now(ZoneOffset.ofHours(5));
OffsetDateTime utc = OffsetDateTime.now(ZoneOffset.UTC);

// OffsetDateTime vs ZonedDateTime:
// OffsetDateTime: fixed offset (+05:30), no DST rules
// ZonedDateTime:  named zone (Asia/Kolkata), DST-aware

// Period -- human calendar amounts
Period period = Period.between(
    LocalDate.of(2020, 1, 1),
    LocalDate.of(2024, 5, 15)
);
System.out.println(period);  // P4Y4M14D (4 years, 4 months, 14 days)

Period twoYears = Period.ofYears(2);
Period custom = Period.of(1, 6, 15);  // 1 year, 6 months, 15 days
LocalDate future = LocalDate.now().plus(twoYears);

// Duration -- machine-precise time
Duration duration = Duration.between(
    LocalTime.of(9, 0),
    LocalTime.of(17, 30)
);
System.out.println(duration);          // PT8H30M (8 hours 30 minutes)

Duration fiveMinutes = Duration.ofMinutes(5);
Duration halfDay = Duration.ofHours(12);
long totalSeconds = duration.getSeconds();  // 30600

// ChronoUnit for quick calculations
long daysBetween = ChronoUnit.DAYS.between(
    LocalDate.of(2020, 1, 1),
    LocalDate.of(2024, 5, 15)
);  // 1596

// Built-in formatters
LocalDate date = LocalDate.now();
String iso = date.format(DateTimeFormatter.ISO_LOCAL_DATE);  // 2024-05-15

// Custom patterns
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("dd-MMM-yyyy HH:mm:ss");
LocalDateTime now = LocalDateTime.now();
String formatted = now.format(formatter);  // 15-May-2024 14:30:45

// Parsing
LocalDate parsed = LocalDate.parse("15-May-2024",
    DateTimeFormatter.ofPattern("dd-MMM-yyyy"));

// With locale
DateTimeFormatter german = DateTimeFormatter
    .ofPattern("dd. MMMM yyyy")
    .withLocale(Locale.GERMAN);
String germanDate = date.format(german);  // 15. Mai 2024

// DateTimeFormatter is thread-safe -- define once, reuse everywhere
public static final DateTimeFormatter API_FORMAT =
    DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss.SSSXXX");

import java.time.temporal.TemporalAdjusters;

LocalDate date = LocalDate.of(2024, 5, 15);

// Built-in adjusters
LocalDate firstDay = date.with(TemporalAdjusters.firstDayOfMonth());      // 2024-05-01
LocalDate lastDay = date.with(TemporalAdjusters.lastDayOfMonth());        // 2024-05-31
LocalDate firstMonday = date.with(TemporalAdjusters.firstInMonth(DayOfWeek.MONDAY));  // 2024-05-06
LocalDate nextFriday = date.with(TemporalAdjusters.next(DayOfWeek.FRIDAY));           // 2024-05-17
LocalDate lastDayOfYear = date.with(TemporalAdjusters.lastDayOfYear());               // 2024-12-31

// Custom adjuster -- next working day
TemporalAdjuster nextWorkingDay = temporal -> {
    LocalDate d = LocalDate.from(temporal);
    do {
        d = d.plusDays(1);
    } while (d.getDayOfWeek() == DayOfWeek.SATURDAY
          || d.getDayOfWeek() == DayOfWeek.SUNDAY);
    return d;
};

LocalDate nextWork = date.with(nextWorkingDay);  // 2024-05-16 (Thursday)

// Production code -- inject Clock
public class OrderService {
    private final Clock clock;

    public OrderService(Clock clock) {
        this.clock = clock;
    }

    public Order createOrder(String item) {
        Order order = new Order();
        order.setCreatedAt(Instant.now(clock));  // uses injected clock
        order.setItem(item);
        return order;
    }

    public boolean isExpired(Order order, Duration ttl) {
        Instant now = Instant.now(clock);
        return order.getCreatedAt().plus(ttl).isBefore(now);
    }
}

// Production usage
OrderService service = new OrderService(Clock.systemUTC());

// Test usage -- time is fixed, deterministic
Clock fixedClock = Clock.fixed(
    Instant.parse("2024-05-15T10:00:00Z"),
    ZoneId.of("UTC")
);
OrderService testService = new OrderService(fixedClock);
Order order = testService.createOrder("Widget");
// order.getCreatedAt() is always 2024-05-15T10:00:00Z

// Offset clock -- simulate "2 hours from now"
Clock offsetClock = Clock.offset(Clock.systemUTC(), Duration.ofHours(2));

// ZoneId -- named zone with DST rules
ZoneId kolkata = ZoneId.of("Asia/Kolkata");      // UTC+05:30
ZoneId newYork = ZoneId.of("America/New_York");  // UTC-05:00 / UTC-04:00 (DST)
ZoneId utc = ZoneId.of("UTC");

// ZoneOffset -- fixed offset, no DST
ZoneOffset plus530 = ZoneOffset.of("+05:30");
ZoneOffset minusFive = ZoneOffset.ofHours(-5);

// List all available zone IDs
Set<String> allZones = ZoneId.getAvailableZoneIds();  // ~600 zones

// Get current rules
ZoneRules rules = newYork.getRules();
boolean isDST = rules.isDaylightSavings(Instant.now());

// Convert between zones
ZonedDateTime meeting = ZonedDateTime.of(
    2024, 5, 15, 9, 0, 0, 0, ZoneId.of("America/New_York")
);
ZonedDateTime inKolkata = meeting.withZoneSameInstant(kolkata);
System.out.println(inKolkata);  // 2024-05-15T18:30+05:30[Asia/Kolkata]

// Date <-> Instant
Date oldDate = new Date();
Instant instant = oldDate.toInstant();                // Date -> Instant
Date backToDate = Date.from(instant);                  // Instant -> Date

// Date <-> LocalDate
LocalDate localDate = oldDate.toInstant()
    .atZone(ZoneId.systemDefault())
    .toLocalDate();

// Calendar <-> ZonedDateTime
Calendar calendar = Calendar.getInstance();
ZonedDateTime zdt = calendar.toInstant()
    .atZone(calendar.getTimeZone().toZoneId());

// Instant -> Calendar
Calendar fromInstant = GregorianCalendar.from(
    instant.atZone(ZoneId.systemDefault())
);

// java.sql.Date <-> LocalDate (direct support)
java.sql.Date sqlDate = java.sql.Date.valueOf(localDate);   // LocalDate -> sql.Date
LocalDate fromSql = sqlDate.toLocalDate();                    // sql.Date -> LocalDate

// java.sql.Timestamp <-> LocalDateTime
java.sql.Timestamp ts = java.sql.Timestamp.valueOf(LocalDateTime.now());
LocalDateTime ldt = ts.toLocalDateTime();

// TimeZone <-> ZoneId
TimeZone oldTz = TimeZone.getTimeZone("America/New_York");
ZoneId newZone = oldTz.toZoneId();
TimeZone backToOld = TimeZone.getTimeZone(newZone);