Every article in this series so far has covered one piece of java.time on its own. This one puts the legacy java.util.Date, Calendar, and SimpleDateFormat classes directly next to their java.time replacements and answers the question that actually comes up in real codebases — not "which is better," since java.time always is, but "how do I make code using both sides talk to each other." Almost every Java codebase old enough to have shipped before 2014 still has at least one legacy Date sitting somewhere in a database layer, a third-party library, or an old API contract nobody has migrated yet.

What Are the Legacy Date API and the Modern Date and Time API?

The legacy API — java.util.Date, java.util.Calendar, java.text.SimpleDateFormat — has been part of Java since its earliest versions. Date tries to represent a single instant while remaining mutable and not thread-safe. Calendar is an abstract, verbose, field-based class for calendar calculations, also mutable. SimpleDateFormat formats and parses dates but is explicitly documented as unsafe to share across threads.

The modern API, java.time, introduced in Java 8, replaces all three with a set of immutable, thread-safe, purpose-built classes — LocalDate, LocalTime, LocalDateTime, ZonedDateTime, Instant, Period, Duration, and DateTimeFormatter, each covered in its own article in this series. Neither side has been removed from the JDK — java.util.Date still exists and still shows up constantly, which is exactly why converting cleanly between the two matters in practice.

One sentence before the diagram: mutability is the one root cause behind nearly every legacy-API bug this series has covered, and it disappears entirely on the modern side.

Legacy (mutable)                    Modern (immutable)
-----------------                   -------------------
Date d = new Date();                LocalDate d = LocalDate.now();
d.setTime(...)   <-- same object    d.plusDays(1)  <-- returns a NEW
   mutated in place, shared             object, original d is
   references silently affected         completely untouched

Calendar c = Calendar.getInstance();
c.add(Calendar.DAY_OF_MONTH, 1);    (no equivalent risk exists -
   same danger, same object             every java.time class is
   mutated under any holder              structurally incapable
   of a reference                        of being mutated at all)

Why the New API Replaced the Legacy One

Some of the legacy API's design decisions are confusing enough that seeing one concretely is worth more than a description of the general problem. Date's deprecated getYear() method is a good example — it does not return the actual year at all.

Java

Try it out

// File: LegacyGetYearTrap.java
import java.util.*;

public class LegacyGetYearTrap {
    public static void main(String[] args) {
        Date date = new Date(126, 7, 25); // deprecated constructor - year is "since 1900"

        // The deprecated getYear() method returns the year minus 1900,
        // not the actual year - this single method has confused Java
        // developers for decades
        System.out.println("date.getYear(): " + date.getYear());
        System.out.println("Actual year: " + (date.getYear() + 1900));
    }
}

Output:
date.getYear(): 126
Actual year: 2026

Every recurring problem covered across this series' earlier articles traces back to one of a small set of legacy classes, each with a specific, well-documented java.time replacement.

Legacy Class	Modern Replacement	Core Problem With the Legacy Class
`java.util.Date`	`Instant` / `LocalDateTime`	Mutable, not thread-safe, and stores a full timestamp even when only a date was intended
`java.util.Calendar`	`LocalDate` / `LocalDateTime` / `ZonedDateTime`	Mutable, verbose field-based API, zero-indexed months
`java.text.SimpleDateFormat`	`java.time.format.DateTimeFormatter`	Not thread-safe — a shared instance corrupts output under concurrent access
`java.util.TimeZone`	`java.time.ZoneId`	No clean way to reason about daylight saving rules or convert between zones safely
`Date.getYear()` / `getMonth()` (deprecated since Java 1.1)	`LocalDate.getYear()` / `getMonthValue()`	Non-standard offsets baked directly into the accessor methods themselves

Bridging Between the Two APIs

Never introduce a new java.util.Date, Calendar, or SimpleDateFormat field in code written today, even for "just this one legacy integration" — accept or return java.time types at the boundary and convert with a one-line adapter instead.

Instant is the pivot point most conversions pass through — Date.toInstant() and Date.from(Instant) connect the legacy and modern worlds in both directions.

Java

Try it out

// File: BridgingSyntaxForms.java
import java.util.*;
import java.time.*;

public class BridgingSyntaxForms {
    public static void main(String[] args) {
        Instant knownInstant = Instant.parse("2026-08-25T09:00:00Z");

        // java.time to legacy Date
        Date legacyDate = Date.from(knownInstant);

        // Legacy Date back to java.time
        Instant recoveredInstant = legacyDate.toInstant();
        LocalDateTime asLocalDateTime = LocalDateTime.ofInstant(recoveredInstant, ZoneId.of("UTC"));

        System.out.println("Original instant: " + knownInstant);
        System.out.println("Recovered instant matches: " + knownInstant.equals(recoveredInstant));
        System.out.println("As LocalDateTime (UTC): " + asLocalDateTime);
    }
}

Output:
Original instant: 2026-08-25T09:00:00Z
Recovered instant matches: true
As LocalDateTime (UTC): 2026-08-25T09:00

Common Use Cases

Converting a Legacy Date Into a LocalDate

Going through Instant and attaching an explicit zone is the standard route from java.util.Date down to a plain calendar date.

Java

Try it out

// File: LegacyDateToLocalDateExample.java
import java.util.*;
import java.time.*;

public class LegacyDateToLocalDateExample {
    public static void main(String[] args) {
        Instant fixedInstant = Instant.parse("2026-08-25T00:00:00Z");
        Date legacyDate = Date.from(fixedInstant);

        LocalDate localDate = legacyDate.toInstant().atZone(ZoneId.of("UTC")).toLocalDate();

        System.out.println("Converted LocalDate: " + localDate);
    }
}

Output:
Converted LocalDate: 2026-08-25

Converting a LocalDate Into a Legacy Date

The same route runs in reverse whenever an older API still insists on a java.util.Date parameter.

Java

Try it out

// File: LocalDateToLegacyDateExample.java
import java.util.*;
import java.time.*;

public class LocalDateToLegacyDateExample {
    public static void main(String[] args) {
        LocalDate localDate = LocalDate.of(2026, 8, 25);

        Date legacyDate = Date.from(localDate.atStartOfDay(ZoneId.of("UTC")).toInstant());

        System.out.println("Legacy Date instant: " + legacyDate.toInstant());
    }
}

Output:
Legacy Date instant: 2026-08-25T00:00:00Z

Bridging a Calendar to a ZonedDateTime

GregorianCalendar, the one concrete Calendar subclass most legacy code actually uses, provides a direct toZonedDateTime() method.

Java

Try it out

// File: CalendarToZonedDateTimeExample.java
import java.util.*;
import java.time.*;

public class CalendarToZonedDateTimeExample {
    public static void main(String[] args) {
        GregorianCalendar calendar = new GregorianCalendar(TimeZone.getTimeZone("Asia/Kolkata"));
        calendar.clear();
        calendar.set(2026, Calendar.AUGUST, 25, 20, 0, 0);

        ZonedDateTime zonedDateTime = calendar.toZonedDateTime();

        System.out.println("Converted ZonedDateTime: " + zonedDateTime);
    }
}

Output:
Converted ZonedDateTime: 2026-08-25T20:00+05:30[Asia/Kolkata]

Bridging java.sql.Timestamp for JDBC Code

Timestamp.valueOf() and toLocalDateTime() were added in Java 8 specifically for JDBC interop, and they avoid the need to route through Instant at all.

Java

Try it out

// File: SqlTimestampConversionExample.java
import java.sql.*;
import java.time.*;

public class SqlTimestampConversionExample {
    public static void main(String[] args) {
        LocalDateTime orderPlacedAt = LocalDateTime.of(2026, 8, 25, 14, 30, 0);

        // Converting to java.sql.Timestamp for a JDBC PreparedStatement parameter
        Timestamp sqlTimestamp = Timestamp.valueOf(orderPlacedAt);

        // Converting a Timestamp read back from a ResultSet into LocalDateTime
        LocalDateTime recovered = sqlTimestamp.toLocalDateTime();

        System.out.println("As java.sql.Timestamp: " + sqlTimestamp);
        System.out.println("Recovered LocalDateTime: " + recovered);
    }
}

Output:
As java.sql.Timestamp: 2026-08-25 14:30:00.0
Recovered LocalDateTime: 2026-08-25T14:30

Real-World Example

A company's older data access layer still returns java.sql.Timestamp values straight from raw JDBC queries, since that part of the codebase predates the team's adoption of java.time, while the newer service layer works entirely in LocalDateTime. A clean mapper at the boundary keeps the legacy type fully contained inside the data access layer, so nothing above it ever needs to know the legacy type exists.

Java

Try it out

// File: LegacyOrderRow.java
import java.sql.*;

public record LegacyOrderRow(String orderId, Timestamp placedAtTimestamp) {}

Java

Try it out

// File: OrderRecord.java
import java.time.*;

public record OrderRecord(String orderId, LocalDateTime placedAt) {}

Java

Try it out

// File: OrderMapper.java

public class OrderMapper {
    public OrderRecord toModern(LegacyOrderRow legacyRow) {
        return new OrderRecord(legacyRow.orderId(), legacyRow.placedAtTimestamp().toLocalDateTime());
    }
}

Java

Try it out

// File: LegacyBridgeDemo.java
import java.sql.*;
import java.time.*;

public class LegacyBridgeDemo {
    public static void main(String[] args) {
        LocalDateTime originalTimestamp = LocalDateTime.of(2026, 8, 25, 14, 30, 0);
        LegacyOrderRow legacyRow = new LegacyOrderRow("ORD-1042", Timestamp.valueOf(originalTimestamp));

        OrderMapper mapper = new OrderMapper();
        OrderRecord modernRecord = mapper.toModern(legacyRow);

        System.out.println("Legacy row timestamp: " + legacyRow.placedAtTimestamp());
        System.out.println("Modern record: " + modernRecord.orderId() + " placed at " + modernRecord.placedAt());
    }
}

Output:
Legacy row timestamp: 2026-08-25 14:30:00.0
Modern record: ORD-1042 placed at 2026-08-25T14:30

A mistake that appears often in fresher pull requests is letting java.sql.Timestamp leak past the data access layer into service and business logic code, just because the conversion felt like extra work at the call site. Keeping the legacy type fully contained inside OrderMapper, and converting exactly once at the boundary, is what stops the rest of the codebase from ever needing to know the legacy type existed at all.

Combining Legacy and Modern APIs

Date.toInstant() and Instant-based bridging tie directly back to the Instant-and-ZonedDateTime relationship covered in the ZonedDateTime article. java.sql.Date, java.sql.Time, and java.sql.Timestamp each have their own direct toLocalDate(), toLocalTime(), toLocalDateTime(), and valueOf() bridge methods added in Java 8 specifically for JDBC interop, distinct from the general java.util.Date bridge. GregorianCalendar is the one concrete Calendar subclass with toZonedDateTime() and from(ZonedDateTime) methods, since the abstract Calendar class itself has no direct java.time equivalent to convert to.

Best Practices

Contain every legacy Date, Calendar, or Timestamp reference inside the thinnest possible boundary layer — a DAO, a legacy API adapter — and convert to java.time immediately at that boundary, so the rest of the codebase never has to reason about the legacy type at all.

Prefer the type-specific java.sql bridge methods, like Timestamp.toLocalDateTime() and Timestamp.valueOf(), over manually converting through Instant when working specifically with JDBC types, since they exist precisely to avoid unnecessary intermediate conversions.

Never introduce a new java.util.Date or Calendar field in code written today, even for "just this one legacy integration." Accept or return java.time types at the boundary and do a one-line conversion inside the adapter instead.

When migrating an existing method from Calendar to java.time, migrate its full call chain in one pass where practical, rather than leaving a method that internally converts back and forth between the two APIs repeatedly.

Common Mistakes

Calling toInstant() on a java.sql.Date throws UnsupportedOperationException, a genuinely surprising and well-documented restriction — java.sql.Date deliberately does not support it, since a date-only value has no well-defined instant without a time and zone.

Java

Try it out

// File: SqlDateToInstantMistake.java
import java.sql.*;
import java.time.*;

public class SqlDateToInstantMistake {
    public static void main(String[] args) {
        Date sqlDate = Date.valueOf("2026-08-25");

        try {
            sqlDate.toInstant();
            System.out.println("Never printed");
        } catch (UnsupportedOperationException e) {
            System.out.println("UnsupportedOperationException - java.sql.Date deliberately does not support toInstant()");
        }

        // The correct bridge for java.sql.Date is toLocalDate()
        LocalDate localDate = sqlDate.toLocalDate();
        System.out.println("Correct conversion: " + localDate);
    }
}

Output:
UnsupportedOperationException - java.sql.Date deliberately does not support toInstant()
Correct conversion: 2026-08-25

Letting a legacy type leak into a public method signature forces every caller throughout the codebase to also deal with it, instead of converting once at the boundary where the legacy data actually enters the system.

Java

Try it out

// File: LeakingLegacyTypeMistake.java
import java.util.*;
import java.time.*;

public class LeakingLegacyTypeMistake {

    // WRONG - the legacy Date type leaks into a public method signature,
    // forcing every caller throughout the codebase to also deal with it
    static Date findLastLoginBroken(String userId) {
        return new Date();
    }

    // CORRECT - convert at the boundary, so java.time is the only type
    // the rest of the codebase ever has to work with
    static LocalDateTime findLastLogin(String userId) {
        Date legacyResult = findLastLoginBroken(userId);
        return legacyResult.toInstant().atZone(ZoneId.systemDefault()).toLocalDateTime();
    }

    public static void main(String[] args) {
        LocalDateTime lastLogin = findLastLogin("user-42");
        System.out.println("Converted at the boundary: " + (lastLogin != null));
    }
}

Output:
Converted at the boundary: true

Assuming Calendar and GregorianCalendar are interchangeable for bridging purposes is another subtle trap. toZonedDateTime() is declared on GregorianCalendar specifically, not on the abstract Calendar class, so code holding a plain Calendar reference — even one that is actually a GregorianCalendar at runtime — cannot call it without an explicit cast first.

Interview Questions

Q1. What are the main problems with java.util.Date and java.util.Calendar that java.time was designed to fix?

Both are mutable, which makes them unsafe to share across threads and easy to modify accidentally through a reference held elsewhere. Calendar's field-based API is verbose and includes design mistakes like zero-indexed months. Date conflates the idea of an instant with a display format and carries deprecated methods, like getYear(), that return values offset from what a reasonable person would expect. java.time fixes all of this with immutable, purpose-specific classes and standard, unambiguous numbering.

Q2. How would you convert a java.util.Date into a LocalDateTime?

Call date.toInstant() to get an Instant, then LocalDateTime.ofInstant(instant, zoneId) with an explicit ZoneId to interpret that instant in a specific time zone's local terms. An explicit zone is required because Instant itself has no zone — the conversion has to be told which zone's wall-clock time to produce.

Q3. Why does calling toInstant() on a java.sql.Date throw UnsupportedOperationException?

java.sql.Date extends java.util.Date but is meant to represent a date-only value with no time-of-day component, which is exactly why it overrides toInstant() to throw rather than silently returning a misleading instant at midnight in some arbitrary zone. The correct bridge method for java.sql.Date is toLocalDate(), which was added specifically for this purpose and does not have the same restriction.

Q4. What does Date.getYear() actually return, and why is that considered a design flaw?

It returns the year minus 1900, a convention baked into Date from a very early version of Java and never changed, since fixing it would have broken every existing caller. The method was deprecated in Java 1.1 specifically because of how confusing and error-prone this offset turned out to be in practice — code that naively used the raw return value as "the year" was silently off by nineteen centuries.

Q5. How would you convert between java.sql.Timestamp and LocalDateTime for JDBC code?

Use Timestamp.valueOf(localDateTime) to go from LocalDateTime to Timestamp when setting a JDBC parameter, and timestamp.toLocalDateTime() to go the other way when reading a value back from a ResultSet. Both methods were added directly to java.sql.Timestamp in Java 8 specifically for this conversion, avoiding the need to route through Instant manually.

Q6. If you inherit a legacy codebase full of Calendar and Date usage, what migration strategy would you recommend?

Start at the boundaries — DAOs, third-party API adapters, serialization layers — and convert to java.time immediately as data enters the system, rather than attempting a single sweeping rewrite. Migrate a method's entire call chain together where practical, since a method that repeatedly converts back and forth between the legacy and modern APIs internally is worse than either extreme, and prioritize the areas most affected by the legacy API's known problems — anything touching daylight saving time, multi-threaded formatting, or date arithmetic — first.

FAQs

Is java.util.Date deprecated?

The class itself is not deprecated, but most of its individual methods are, including the constructors that take year, month, and day as separate integers, and accessor methods like getYear() and getMonth(). The class remains fully present in the JDK because too much existing code and too many external APIs still depend on it.

Can I mix java.util.Date and java.time classes in the same codebase?

Yes, and in practice most real codebases have to, at least during a migration period or wherever a third-party library still requires the legacy type. The key is converting deliberately at well-defined boundaries rather than letting both types spread freely throughout the codebase.

What is the difference between java.util.Date and java.sql.Date?

java.sql.Date extends java.util.Date but is meant to represent a date-only value with no time-of-day component, which is why its toInstant() method is overridden to throw an exception rather than return a misleading result.

Does converting a Date to an Instant lose any precision?

No, in the sense that both java.util.Date and Instant are ultimately backed by a count of milliseconds since the epoch for Date's part of the conversion — Date only has millisecond precision to begin with, so converting to Instant and back preserves everything Date was capable of representing, with Instant's additional nanosecond capacity simply staying at zero.

Why does GregorianCalendar have a toZonedDateTime() method but Calendar doesn't?

Calendar is an abstract class meant to support multiple calendar systems, not just the Gregorian one, so a direct conversion to ZonedDateTime — which assumes the ISO/Gregorian calendar system — only makes sense on a concrete subclass that actually uses that system. GregorianCalendar is that subclass, and it is also the one almost all real-world legacy code actually uses.

Is SimpleDateFormat completely unusable, or just risky?

It works correctly as long as each instance is confined to a single thread, or properly synchronized when shared — the risk is specifically about concurrent access from multiple threads without synchronization, which is easy to introduce accidentally with a shared static field. DateTimeFormatter removes the risk entirely by being immutable, which is why it is the recommended choice for any new code.

What should I do if a third-party library still requires a java.util.Date parameter?

Keep the rest of the application working entirely in java.time, and convert to Date only at the exact call site where the library requires it, using Date.from(instant). Treat that conversion as a narrow, isolated adapter rather than letting Date spread into the surrounding code just because one dependency still needs it.

Summary

The legacy API and java.time are not really in competition anymore — java.time won that argument the moment it shipped, and this article's real value is the bridge, not the verdict. Date.toInstant() and Date.from() connect the general case, java.sql.Date, Time, and Timestamp each have their own direct, JDBC-specific bridge methods, and GregorianCalendar.toZonedDateTime() covers the one concrete Calendar subclass that actually matters in practice.

The habit worth carrying forward is converting exactly once, at the boundary where legacy data enters a system, and never letting Date, Calendar, or Timestamp spread past that point into the rest of the codebase — exactly the discipline the JDBC mapper example in this article is built around. Every other article in this series assumes that discipline is already in place, working entirely in java.time from the moment a value crosses that one line.

What to Read Next

Continue Learning Date & Time API

Next Step

Java 8 Key Features

Learn the features that changed Java forever in version 8.

→

Function

Learn how to write a function that transforms one value into another.

→

Period

Learn how to measure a gap between two dates.

→

DateTimeFormatter

Learn how to format dates and times for display.

→

←

PreviousDateTimeFormatter

NextJava 8 Key Features

→