Course contentsShow
← Java
Lesson 1903 of 2,87038. Date and Time API (java.time)Free lesson

Migration Checklist and Common Pitfalls

Step-by-step guide and frequent mistakes when migrating codebases from legacy to java.time API.

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) or LocalDateTime (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.