11.2 Timestamps, Intervals, and Durations: `Instant`, `Period`, and `Duration`

11.2 Timestamps, Intervals, and Durations: Instant, Period, and Duration

Working effectively with time requires distinguishing between two distinct perspectives: human calendar time (years, months, weeks, days) and machine timeline points and durations (exact seconds, milliseconds, and nanoseconds). The Java SE 17 Date-Time API models these dimensions using Instant, Period, and Duration.

---

Machine Timeline: Instant

An Instant represents an instantaneous point on the global timeline, defined as an offset from the standard Unix epoch: January 1, 1970, 00:00:00 UTC (Zulu time). It stores time as a 64-bit integer representing epoch seconds and a 32-bit integer representing nanoseconds of the second.

Factory Methods and Conversions

// Current instant from system clock in UTC
Instant now = Instant.now(); 

// Specific offsets from Unix epoch
Instant epoch = Instant.ofEpochMilli(0);                     // 1970-01-01T00:00:00Z
Instant specificSec = Instant.ofEpochSecond(1_000_000_000);  // 2001-09-09T01:46:40Z

// Parsing standard ISO-8601 UTC string (must include 'Z' or offset)
Instant parsed = Instant.parse("2026-10-11T12:00:00Z");

Characteristics and Limitations of Instant

Because Instant models the continuous physical timeline in UTC without human calendar semantics:

• It contains no time zone (it is inherently pinned to UTC).
• It has no concept of year, month, day, or day of week.
• Calling instant.get(ChronoField.YEAR) or instant.get(ChronoField.DAY_OF_MONTH) compiles (since Instant implements TemporalAccessor), but throws UnsupportedTemporalTypeException at runtime!

To bridge human calendar representations with machine timestamps, you must associate the Instant with a time zone (ZoneId) to produce a ZonedDateTime:

Instant stamp = Instant.now();
ZonedDateTime tokyoTime = stamp.atZone(ZoneId.of("Asia/Tokyo"));
LocalDate localDateInTokyo = tokyoTime.toLocalDate();

---

Human Calendar Amounts: Period

A Period represents an amount of time in terms of calendar-based units: years, months, and days.

Factory Creation and Parsing

Period instances are created using static factory methods:

Period oneYear = Period.ofYears(1);
Period twoMonths = Period.ofMonths(2);
Period threeWeeks = Period.ofWeeks(3); // Stored internally as 21 days!
Period fiveDays = Period.ofDays(5);

// Compound period: 1 year, 6 months, and 15 days
Period compound = Period.of(1, 6, 15);

// Parsing ISO-8601 period format (prefixed with 'P')
Period parsedPeriod = Period.parse("P1Y6M15D"); // 1 year, 6 months, 15 days
Period twoWeeks = Period.parse("P2W");          // 14 days

Modifying Temporals with Period

Period is designed to be added to or subtracted from date-bearing temporal objects (LocalDate, LocalDateTime, ZonedDateTime):

LocalDate wedding = LocalDate.of(2026, Month.JUNE, 20);
LocalDate anniversary = wedding.plus(Period.ofYears(1)); // 2027-06-20

The Period Incompatibility Trap

A Period contains days, months, or years. It contains no hours, minutes, or seconds. If you attempt to add or subtract a Period from a LocalTime, the code compiles (because plus(TemporalAmount) accepts any TemporalAmount), but throws UnsupportedTemporalTypeException at runtime:

LocalTime bedtime = LocalTime.of(22, 0);
Period dayPeriod = Period.ofDays(1);

// COMPILES! But throws UnsupportedTemporalTypeException at runtime:
// java.time.temporal.UnsupportedTemporalTypeException: Unsupported unit: Days
LocalTime failed = bedtime.plus(dayPeriod); 

---

Machine Time Amounts: Duration

A Duration represents an amount of time in terms of exact, machine-based units: seconds and nanoseconds. For convenience, the API provides helper methods to work with days, hours, and minutes, but internally these are always converted to exact seconds ($1 \text{ day} = 24 \text{ hours} = 86,400 \text{ seconds}$).

Factory Creation and Calculation

Duration oneDay = Duration.ofDays(1);          // 86,400 seconds
Duration twoHours = Duration.ofHours(2);       // 7,200 seconds
Duration tenMinutes = Duration.ofMinutes(10);   // 600 seconds
Duration thirtySeconds = Duration.ofSeconds(30);
Duration hundredMillis = Duration.ofMillis(100);

// Calculating elapsed duration between two temporal points
LocalTime start = LocalTime.of(9, 0);
LocalTime end = LocalTime.of(10, 30);
Duration elapsed = Duration.between(start, end); // PT1H30M (1 hour, 30 minutes)

// Parsing ISO-8601 duration format (prefixed with 'PT' for time)
Duration parsedDuration = Duration.parse("PT2H15M"); // 2 hours, 15 minutes

The Duration Incompatibility Trap

A Duration tracks time in seconds and nanoseconds. A LocalDate contains only calendar dates and has no time components. If you attempt to add or subtract a Duration to or from a LocalDate, Java throws UnsupportedTemporalTypeException at runtime:

LocalDate date = LocalDate.of(2026, Month.MAY, 1);
Duration twoHoursDuration = Duration.ofHours(2);

// COMPILES! But throws UnsupportedTemporalTypeException at runtime:
// java.time.temporal.UnsupportedTemporalTypeException: Unsupported unit: Seconds
LocalDate invalidDate = date.plus(twoHoursDuration);

---

Comparison: Period vs. Duration

---

The Static Factory Chaining Trap

A well-known trick pattern is the static method chaining illusion on Period and Duration.

In Java, static methods can be syntactically called on an instance reference or chained together, but static calls are resolved entirely by the compiler against the declaring class. They never operate on an accumulated instance:

// What does this produce?
Period period = Period.ofYears(1).ofMonths(2).ofDays(3);
System.out.println(period); // PRINTS: P3D (3 days only!)

Why Does This Occur?

1. Period.ofYears(1) executes statically, returning a new Period representing 1 year (P1Y).
2. .ofMonths(2) is invoked. Because ofMonths is static, the compiler ignores the P1Y instance completely and evaluates Period.ofMonths(2), returning a new Period of 2 months (P2M).
3. .ofDays(3) is invoked. Similarly, it is static, discarding the P2M instance and returning a new Period of 3 days (P3D).
4. The variable period receives only the 3-day period!

// WRONG: Yields only 30 minutes!
Duration d = Duration.ofHours(5).ofMinutes(30); 

// CORRECT way to create compound periods and durations:
Period correctPeriod = Period.of(1, 2, 3); // 1 year, 2 months, 3 days
Duration correctDuration = Duration.ofHours(5).plusMinutes(30); // 5 hours, 30 minutes

---

Calculating Differences with ChronoUnit.between()

The java.time.temporal.ChronoUnit enum represents standard date-time units (from NANOS through FOREVER) and provides the between(Temporal, Temporal) utility method:

LocalDate d1 = LocalDate.of(2026, Month.JANUARY, 1);
LocalDate d2 = LocalDate.of(2026, Month.JANUARY, 15);

long daysBetween = ChronoUnit.DAYS.between(d1, d2); // 14 (d1 inclusive, d2 exclusive)

Key Rules for ChronoUnit.between()

1. Truncation to Whole Units: between() calculates the number of complete whole units. Any fractional remainder is truncated. For example, between 10:00 and 11:45, ChronoUnit.HOURS.between() yields 1.
2. Direction and Sign: The calculation is temporal2Exclusive - temporal1Inclusive. If the second argument is chronologically earlier than the first, the result is negative:

   LocalTime t1 = LocalTime.of(15, 0);
   LocalTime t2 = LocalTime.of(12, 0);
   long hours = ChronoUnit.HOURS.between(t1, t2); // -3
   

3. Unit Compatibility: Attempting to calculate an unsupported unit (such as hours between two LocalDate instances) throws UnsupportedTemporalTypeException:

   // COMPILES! But throws UnsupportedTemporalTypeException at runtime:
   long hours = ChronoUnit.HOURS.between(d1, d2);