Date & Time in Java

Work with the modern java.time API — LocalDate, LocalTime, LocalDateTime, ZonedDateTime, Duration, Period, and DateTimeFormatter.

Introduction to Date & Time

Java 8 introduced the `java.time` package (JSR-310) as a complete replacement for the old `java.util.Date` and `Calendar` classes. It is immutable, thread-safe, and much easier to work with.

1. What is Date & Time in Java?

The `java.time` package provides separate classes for date, time, and combined date-time — all immutable.

Creating Date Objects

Use `.now()` for the current moment, `.of()` for specific values, `Instant.ofEpochMilli()` for timestamps, and `parse()` for strings.

1. Current Date & Time

`.now()` returns the current date/time from the system clock.

2. Date from Specific Values

`.of()` creates a date/time from specific year, month, day, hour, minute, second values.

3. Date from Timestamp

Convert a Unix timestamp (milliseconds since epoch) to a readable date using `Instant`.

4. Date from String

`.parse()` parses an ISO-8601 string into a date object. Use `DateTimeFormatter` for custom formats.

Timestamps

Java uses `Instant` to represent a point in time as Unix epoch. Use `System.currentTimeMillis()` for a quick millisecond timestamp.

1. Getting Current Timestamp

Use `Instant.now()` for a UTC timestamp or `System.currentTimeMillis()` for milliseconds.

2. Date to Timestamp

Convert a `LocalDateTime` or `ZonedDateTime` to a Unix timestamp using `.toEpochSecond()`.

Getting Date Components

All `java.time` classes provide getter methods for individual components like `getYear()`, `getMonthValue()`, `getDayOfMonth()`, etc.

1. Date & Time Components

Extract individual fields from `LocalDate`, `LocalTime`, and `LocalDateTime`.

Formatting Dates

`DateTimeFormatter.ofPattern()` converts a date/time object to a custom string format. Use predefined formatters like `ISO_LOCAL_DATE` for standard formats.

1. toString & ISO Format

Calling `.toString()` on any `java.time` object returns ISO-8601 format by default.

2. Custom & Locale Formatting

Use `DateTimeFormatter.ofPattern()` for custom formats and `ofLocalizedDate()` for locale-aware output.

Comparing Dates

All `java.time` classes provide `isBefore()`, `isAfter()`, and `isEqual()` for readable comparisons. Use `compareTo()` when you need a numeric result.

1. Comparing Two Dates

Use `isBefore()`, `isAfter()`, `isEqual()` for clear, readable date comparisons.

Date Arithmetic

Java `java.time` classes are immutable — `plus` and `minus` methods return new instances. Use `Period` for date differences and `Duration` for time differences.

1. Adding & Subtracting

Use `plusDays()`, `plusMonths()`, `plusYears()`, `minusDays()`, etc. to shift a date.

2. Difference Between Two Dates

Use `Period.between()` for date differences and `Duration.between()` for time differences.

Timezones & UTC

`ZonedDateTime` attaches a timezone to a `LocalDateTime`. Use `ZoneId` to specify the timezone and `withZoneSameInstant()` to convert between zones.

1. Local Time vs UTC & Zone Conversion

Create a `ZonedDateTime` in one timezone and convert it to another using `withZoneSameInstant()`.

Best Practices

Following these practices prevents common bugs like timezone confusion, mutable state issues, and incorrect date comparisons.

1. Recommended Practices

A quick reference for the most important rules when working with `java.time`.