How to Replace Joda Time and java.util.Date With java.time
Migrate from java.util.Date, Calendar and Joda Time to java.time with a type table, boundary adapters, JPA and Jackson settings and time zone tests.

Dates are where small bugs hide for years. A SimpleDateFormat shared between threads produces corrupt dates once a week. A Calendar month is zero based, so December is 11. A java.util.Date that is called a date is a timestamp and prints in whatever zone the server uses. Joda Time fixed most of this in 2005 and its author then co-designed java.time, which has been in the JDK since Java 8; the Joda project's own page says to migrate. This post gives you the type mapping, the conversion code for the boundaries you cannot change yet and the settings for JPA and JSON, then shows how to test time zone behaviour. For the Hibernate side in more depth, mapping Java time types in Hibernate is the companion.
Choose by meaning, not by habit
The reason java.time has several types is that "a date" means different things. Pick the type that states what your value is.
| You mean | Use | Replaces |
|---|---|---|
| A point on the timeline, the same everywhere | Instant | Date, Calendar for timestamps, Joda Instant |
| A calendar day with no time or zone | LocalDate | Date used for a birthday, Joda LocalDate |
| A wall clock time with no zone | LocalTime, LocalDateTime | Joda LocalTime, LocalDateTime |
| A local date time in a specific zone | ZonedDateTime | Calendar, Joda DateTime |
| A date time with a fixed UTC offset | OffsetDateTime | Joda DateTime in a fixed zone |
| An amount of time | Duration (exact), Period (calendar) | Joda Duration, Period |
| A zone | ZoneId | TimeZone, Joda DateTimeZone |
Most business fields are one of two things: when something happened (an event time, store as Instant) or which day something applies to (a due date, store as LocalDate). LocalDateTime is the type most often misused, because it looks like a timestamp and is not one: it cannot be ordered across zones or turned into an instant without being told the zone.
The conversions at the boundary
You will not convert a large codebase in one change, and libraries you call still return Date. The conversions are one liners, and writing them once in a utility keeps the rest of the code clean:
package dev.javahacks.time;
import java.time.*;
import java.util.Calendar;
import java.util.Date;
import java.util.GregorianCalendar;
public final class LegacyDates {
private LegacyDates() {}
public static Instant toInstant(Date date) {
return date == null ? null : date.toInstant();
}
public static Date toDate(Instant instant) {
return instant == null ? null : Date.from(instant);
}
public static ZonedDateTime toZoned(Calendar cal) {
return cal instanceof GregorianCalendar g ? g.toZonedDateTime() : cal.toInstant().atZone(cal.getTimeZone().toZoneId());
}
public static LocalDate toLocalDate(Date date, ZoneId zone) {
return date == null ? null : date.toInstant().atZone(zone).toLocalDate();
}
public static Date toDate(LocalDate day, ZoneId zone) {
return day == null ? null : Date.from(day.atStartOfDay(zone).toInstant());
}
}Two details deserve a comment. java.sql.Date overrides toInstant() to throw UnsupportedOperationException, because it has no time part. Use sqlDate.toLocalDate() for those. And converting a Date to a LocalDate needs a zone, because a Date is an instant and the same instant is different calendar days in Tokyo and in Los Angeles. Passing the zone explicitly is the point: it forces the decision that the old code made silently with the server's default.
Joda has the same bridge in its own API, so you can convert in either direction during the transition: new DateTime(instant.toEpochMilli(), DateTimeZone.forID(zone.getId())) to go from java.time to Joda, and Instant.ofEpochMilli(jodaDateTime.getMillis()) to go back.
Rewriting the code
The typical formatting and arithmetic code becomes shorter. Old style:
SimpleDateFormat fmt = new SimpleDateFormat("yyyy-MM-dd");
Calendar cal = Calendar.getInstance();
cal.setTime(order.getPlacedAt());
cal.add(Calendar.DAY_OF_MONTH, 30);
String due = fmt.format(cal.getTime());Modern equivalent, where placedAt is an Instant:
private static final DateTimeFormatter ISO_DAY = DateTimeFormatter.ISO_LOCAL_DATE;
String due = ISO_DAY.format(order.placedAt().atZone(ZoneId.of("Asia/Ho_Chi_Minh")).toLocalDate().plusDays(30));The formatter is a static final constant because DateTimeFormatter is immutable and thread safe, unlike SimpleDateFormat. The zone is explicit. plusDays(30) does calendar arithmetic and returns a new value, where Calendar.add mutated one. Joda users will find the shape familiar: new DateTime().plusDays(30) becomes ZonedDateTime.now(zone).plusDays(30), and LocalDate maps one to one. A few Joda idioms change name: DateTimeFormat.forPattern becomes DateTimeFormatter.ofPattern, Interval has no direct equivalent (use two Instants or the ThreeTen-Extra library's Interval) and Period still means a calendar based amount.
Persistence
Hibernate 6 and later map java.time types natively, with no extra module and no @Type annotation. Hibernate 5 needed hibernate-java8, which is why old codebases carry @Convert converters you can now delete.
@Entity
public class PurchaseOrder {
@Id @GeneratedValue private Long id;
private Instant placedAt; // timestamp with time zone / timestamp
private LocalDate dueOn; // date
private Duration slaWindow; // stored as a number of nanoseconds by default
}Two storage traps. First, Hibernate stores an Instant using the JVM's default time zone unless you configure it, and the result is data that changes meaning if the server's zone changes. Set the JDBC time zone explicitly to UTC:
spring.jpa.properties.hibernate.jdbc.time_zone=UTCSecond, a column of type timestamp without time zone cannot represent an instant by itself. For events, prefer timestamp with time zone (on PostgreSQL, which still stores UTC internally) so that the database knows what the value means. When migrating existing columns, find out what zone the legacy code was writing in, because java.util.Date values were written in the application server's default zone and that is part of your data.
Plain JDBC with a JDBC 4.2 driver reads and writes java.time directly: ps.setObject(1, instant) for an Instant on drivers that support it (PostgreSQL uses OffsetDateTime) and rs.getObject("due_on", LocalDate.class). Avoid setTimestamp with conversions in new code.
JSON
Jackson needs the jackson-datatype-jsr310 module, which Spring Boot registers automatically, and a setting that stops it writing dates as numeric arrays:
spring.jackson.serialization.write-dates-as-timestamps=falseThen Instant serializes as an ISO 8601 string like 2026-11-03T08:15:30Z, and LocalDate as 2026-11-03. If you used Jackson's Joda module, remove jackson-datatype-joda once the last Joda type is gone. When the format of existing API clients depends on a different pattern, annotate the field with @JsonFormat(pattern = "...") to keep the wire format while changing the Java type; the wire format is a contract, and a type migration should not change it silently.
Test with a Clock
The biggest design improvement is to stop calling now() directly. Inject a Clock, the java.time abstraction of "what time is it", and tests can fix it:
@Service
public class InvoiceService {
private final Clock clock;
public InvoiceService(Clock clock) {
this.clock = clock;
}
public Invoice issue(Order order) {
LocalDate today = LocalDate.now(clock);
return new Invoice(order.id(), today, today.plusDays(30));
}
}@Bean
Clock clock() {
return Clock.systemUTC();
}class InvoiceServiceTest {
@Test
void dueDateIsThirtyDaysAfterIssueInTheBusinessZone() {
Clock fixed = Clock.fixed(Instant.parse("2026-12-31T23:30:00Z"), ZoneId.of("Asia/Ho_Chi_Minh"));
var service = new InvoiceService(fixed);
Invoice invoice = service.issue(new Order(7L));
assertThat(invoice.issuedOn()).isEqualTo(LocalDate.of(2027, 1, 1)); // 23:30 UTC is already 1 January in Vietnam
assertThat(invoice.dueOn()).isEqualTo(LocalDate.of(2027, 1, 31));
}
}That test pins a bug class. At 23:30 UTC on New Year's Eve it is already 6:30 in the morning of 1 January in Ho Chi Minh City. Code using LocalDate.now() with the server's zone would date the invoice differently depending on where it runs. The Clock carries both the instant and the zone, so the test is the same on every machine and in every CI zone. Also test daylight saving boundaries when your business zone has them: ZonedDateTime.of(2026, 3, 8, 2, 30, ...) in America/New_York does not exist, and java.time resolves it forward by an hour by default; a test documents what your code does.
A migration order that works
- Add the conversion utility above and a
Clockbean. - Convert the leaf code first: formatters and parsers, utility classes, anything with no callers outside the package.
- Change entity fields and column mappings, one entity at a time, with a Flyway migration if column types change.
- Change API types, with the wire format pinned by a contract test.
- Remove Joda from the dependency list, and ban
java.util.Dateoutside the boundary package with an ArchUnit rule or a CheckstyleIllegalImport. Both are described in enforcing module boundaries with ArchUnit.
OpenRewrite includes recipes for the mechanical part, org.openrewrite.java.migrate.joda.JodaTimeScanner and the related Joda migration recipes among them, as covered in automating upgrades with OpenRewrite. Review what they generate: the choice between Instant, ZonedDateTime and LocalDate is semantic, and a tool cannot know what your field means.
When this does not apply
Code that must stay on Java 6 or 7 cannot use java.time; the ThreeTen backport library provides the same API under the org.threeten.bp package for that case. Libraries that publish a Date based API, such as an old SDK, keep their Date and are wrapped by the boundary utility. Joda itself is not insecure, and a stable codebase that rarely touches dates can leave it, but its documentation recommends migration and new code should not add to it. References: the Joda Time home page note on migration and the java.time package documentation.


