Best Practices: When to Use ZonedDateTime
What You'll Learn
You'll learn when to choose ZonedDateTime over other date-time types based on your application's needs.
Understanding Your Options
Think of date-time types like addresses: LocalDateTime is like "123 Main Street" (no city), Instant is like GPS coordinates (universal), and ZonedDateTime is the complete address with city and state (context-aware).
When to Use ZonedDateTime
Use ZonedDateTime when:
-
User-facing timestamps matter: When displaying times to users in different locations. If someone in Tokyo and someone in New York both schedule a meeting, you need to show each person the correct local time.
-
You need time zone awareness: When business rules depend on local time zones (e.g., "send this email at 9 AM local time to each customer").
-
Handling recurring events: When events repeat based on local time ("every Monday at 10 AM"), regardless of DST changes.
-
Storing future events: When you need to preserve the intended local time across potential time zone rule changes.
When NOT to Use ZonedDateTime
Prefer other types when:
- Just need a timestamp: Use
Instantfor logging, database timestamps, or measuring duration between events. - Working with dates only: Use
LocalDatefor birthdays, holidays, or date ranges. - Time without context: Use
LocalDateTimefor internal calculations where time zones don't matter. - Fixed offset suffices: Use
OffsetDateTimewhen you only need the UTC offset, not full zone rules (DST transitions don't matter).
The Decision Rule
If your application crosses time zones or serves users in different regions, ZonedDateTime is your friend. If you're just recording "when did this happen?" use Instant.
Key Takeaway: Choose ZonedDateTime when time zone context and local time interpretation matter to your business logic; prefer simpler types like Instant or LocalDateTime for straightforward timestamps or zone-independent calculations.