Why Java Needed a New Date‑Time API and How JSR‑310 Solves It

1. Background: Why a New API

Introducing the need for a new date‑time API.

1.1 Issues with java.util.Date

Non‑deterministic – Date instances are mutable.

Concurrency problems – Date is not thread‑safe.

Misleading name – Date actually represents a timestamp.

Lack of conventions – Days start at 1, months at 0, years at 1900.

Missing fluent operations – Cannot create durations or combine components easily.

1.2 Pre‑Java 8 Date‑Time APIs

System.currentTimeInMillis()

can return the same value on rapid calls. java.util.Date vs java.sql.Date: the latter lacks time information. java.sql.Timestamp extends java.util.Date with nanosecond precision.

1.3 Issues with java.util.Calendar

Lacks clarity – mixes date and time.

Confusing timezone support – hard to switch zones or offsets.

Interoperability problems – SimpleDateFormat and Calendar do not work well together.

Difficult to extend – hard to build new calendar systems on top of Calendar.

2. Solution: JSR‑310 Date and Time API

JSR‑310 was created to address the lessons learned from the old Date and Calendar APIs and to provide a richer, more comprehensive model for date‑time manipulation.

The new API replaces Date and Calendar, supporting date‑only, time‑only, durations, and intervals.

It handles formatting and parsing according to ISO‑8601, including XML support.

Designed for ease of use while offering powerful features without obscuring common use cases.

2.2 Origin of JSR‑310

Inspired by Stephen Colebourne’s popular Joda‑Time library.

JSR‑310 refines and re‑architects concepts from Joda‑Time.

References for migration from Joda‑Time to java.time are available on the Joda‑Time blog and StackOverflow.

3. Java 8 Date‑Time Classes

Instant

– stores a timestamp from the Java epoch with nanoseconds. LocalDate – date without time. LocalTime – time without date. LocalDateTime – combination of date and time. ZonedDateTime – date‑time with timezone. OffsetTime – time with UTC offset. OffsetDateTime – date‑time with UTC offset.

4. Ranges and Partials

Duration

– time‑based amount measured in nanoseconds (e.g., 5 minutes). Period – date‑based amount in years, months, days (e.g., 2 days). Month – month of the year (e.g., MARCH). MonthDay – month and day without year (e.g., birthday). Year – year value (e.g., 2015). YearMonth – year and month without day (e.g., credit‑card expiry). DayOfWeek – day of the week (e.g., WEDNESDAY).

5. Chronology

Chronology

– factory for calendar systems, default is IsoChronology (others include ThaiBuddhistChronology). ChronoLocalDate – date without time in any chronology. ChronoLocalDateTime – date‑time in any chronology. ChronoZonedDateTime – date‑time with zone in any chronology. ChronoPeriod – period of days/time for any chronology. Era – represents a timeline era.

6. Fluent and Semantic API Methods

of {ClassFactory} – creates an instance without conversion (e.g., LocalDate.of(...)).

from {ClassFactory} – creates an instance with validation and conversion (e.g., LocalDateTime.from(...)).

parse {ClassFactory} – parses a CharSequence into an instance (e.g., LocalDate.parse(...)).

format {ObjectMethod} – formats an object using a formatter (e.g., localDate.format(formatter)).

get {ObjectMethod} – retrieves a part of the temporal object (e.g., localDate.getDayOfWeek()).

is {ObjectMethod} – queries a state (e.g., localTime.isAfter(...)).

with {ObjectMethod} – returns a copy with modified part (e.g., offsetTime.withHour(...)).

plus {ObjectMethod} – returns a copy with added time (e.g., localDate.plusWeeks(...)).

minus {ObjectMethod} – returns a copy with subtracted time (e.g., localTime.minusSeconds(...)).

to {ObjectMethod} – converts to another type (e.g., localDateTime.toLocalDate()).

at {ObjectMethod} – combines objects into a new one (e.g., localDate.atTime(...)).