Migration Checklist and Common Pitfalls
You'll learn a systematic approach to migrating from legacy date/time APIs to java.time, plus traps to avoid.
The Core Strategy
Migrating an entire codebase from java.util.Date and Calendar to the modern java.time API isn't just a search-and-replace operation—it requires careful planning to avoid breaking existing behavior, especially around time zones, formatting, and boundary conditions.
Migration Checklist
1. Audit Your Codebase
Identify all uses of Date, Calendar, SimpleDateFormat, and TimeZone. Note whether they handle dates-only, times-only, or both.
2. Replace Types Systematically
Date→Instant(for timestamps) orLocalDateTime(no zone context)Calendar→ZonedDateTime(preserves zone information)SimpleDateFormat→DateTimeFormatter(thread-safe!)TimeZone→ZoneId
3. Address Thread Safety
Replace all shared SimpleDateFormat instances with DateTimeFormatter (which is immutable and thread-safe).
4. Test Time Zone Conversions
Pay special attention to Calendar.getInstance() conversions—these use the system default zone, which may differ from expectations.
5. Update Serialization Logic
If persisting dates, ensure your storage format (epoch millis, ISO-8601 strings) remains compatible.
Common Pitfalls
Pitfall #1: Forgetting that Date.toInstant() always represents UTC. If the original Date was implicitly treated as local time, you'll lose hours.
Pitfall #2: Using LocalDateTime when you actually need ZonedDateTime. Without zone information, daylight saving transitions can produce incorrect results.
Pitfall #3: Replacing SimpleDateFormat patterns without checking symbol differences (some symbols changed meaning).
Key Takeaway: Migrate incrementally, prioritize thread-safety fixes first, and always verify time zone handling—especially for Calendar conversions where implicit zones may have masked bugs.