19.1 Date and Time Fundamentals

The java.time API, introduced in Java 8, provides a comprehensive set of immutable, thread-safe classes for date and time handling. This section covers the core concepts, fundamental types, and the Clock abstraction that forms the foundation of modern temporal programming in Java.

Historical Context and Design Philosophy

The java.time API (JSR-310) replaced the problematic java.util.Date and java.util.Calendar classes with a cleaner design based on the Joda-Time library.

Problems with Legacy Date/Time APIs:

• Mutability: Date and Calendar are mutable, leading to concurrency issues
• Month indexing: January = 0, December = 11 (counterintuitive)
• Poor timezone handling: Confusing timezone behavior in Calendar
• No type safety: Single Date class for both date and time
• Limited functionality: Missing duration and period concepts

java.time Design Principles:

• Immutability: All core classes are immutable and thread-safe
• Clarity: Separate types for different temporal concepts
• Fluent API: Method chaining for readable date/time operations
• Extensibility: Support for custom calendar systems
• ISO-8601: Standard calendar system as default

Core Temporal Types

The java.time package provides distinct types for different temporal concepts.

Type Hierarchy:

public class TemporalTypesOverview {
    public static void demonstrateTypes() {
        // Instant: Machine timeline (UTC epoch nanoseconds)
        Instant instant = Instant.now();
        System.out.println("Instant: " + instant);

        // LocalDate: Date without time or timezone
        LocalDate date = LocalDate.now();
        System.out.println("LocalDate: " + date);

        // LocalTime: Time without date or timezone
        LocalTime time = LocalTime.now();
        System.out.println("LocalTime: " + time);

        // LocalDateTime: Date and time without timezone
        LocalDateTime dateTime = LocalDateTime.now();
        System.out.println("LocalDateTime: " + dateTime);

        // ZonedDateTime: Date-time with timezone
        ZonedDateTime zonedDateTime = ZonedDateTime.now();
        System.out.println("ZonedDateTime: " + zonedDateTime);

        // OffsetDateTime: Date-time with UTC offset
        OffsetDateTime offsetDateTime = OffsetDateTime.now();
        System.out.println("OffsetDateTime: " + offsetDateTime);

        // Duration: Time-based amount (hours, minutes, seconds)
        Duration duration = Duration.ofHours(2);
        System.out.println("Duration: " + duration);

        // Period: Date-based amount (years, months, days)
        Period period = Period.ofMonths(3);
        System.out.println("Period: " + period);
    }
}

Instant: Machine Timeline

Instant represents a point on the UTC timeline as nanoseconds since the Unix epoch (1970-01-01T00:00:00Z).

Creating Instants:

public class InstantExamples {
    public void instantCreation() {
        // Current instant
        Instant now = Instant.now();

        // From epoch seconds
        Instant epoch = Instant.ofEpochSecond(0);
        System.out.println("Unix epoch: " + epoch);

        // From epoch milliseconds
        long millis = System.currentTimeMillis();
        Instant fromMillis = Instant.ofEpochMilli(millis);

        // From epoch seconds with nanosecond adjustment
        Instant precise = Instant.ofEpochSecond(1609459200L, 123456789);

        // Parsing from ISO-8601 string
        Instant parsed = Instant.parse("2025-01-06T10:15:30.123Z");
        System.out.println("Parsed instant: " + parsed);
    }

    public void instantOperations() {
        Instant now = Instant.now();

        // Get epoch seconds and nanoseconds
        long epochSeconds = now.getEpochSecond();
        int nanos = now.getNano();
        System.out.println("Epoch seconds: " + epochSeconds);
        System.out.println("Nanoseconds: " + nanos);

        // Arithmetic operations
        Instant later = now.plusSeconds(3600); // Add 1 hour
        Instant earlier = now.minusSeconds(1800); // Subtract 30 minutes
        Instant muchLater = now.plus(Duration.ofDays(7));

        // Comparisons
        boolean isBefore = earlier.isBefore(now);
        boolean isAfter = later.isAfter(now);

        // Duration between instants
        Duration elapsed = Duration.between(earlier, now);
        System.out.println("Elapsed: " + elapsed.toMinutes() + " minutes");
    }
}

Instant Precision:

public class InstantPrecision {
    public void demonstratePrecision() {
        Instant instant = Instant.now();

        // Instant stores nanosecond precision
        System.out.println("Full precision: " + instant);

        // Truncate to different units
        Instant truncSeconds = instant.truncatedTo(ChronoUnit.SECONDS);
        Instant truncMillis = instant.truncatedTo(ChronoUnit.MILLIS);
        Instant truncMicros = instant.truncatedTo(ChronoUnit.MICROS);

        System.out.println("Truncated to seconds: " + truncSeconds);
        System.out.println("Truncated to millis: " + truncMillis);
        System.out.println("Truncated to micros: " + truncMicros);
    }

    public void precisionLimits() {
        // Instant range: approximately +/- 1 billion years from epoch
        Instant min = Instant.MIN;
        Instant max = Instant.MAX;

        System.out.println("MIN: " + min);
        System.out.println("MAX: " + max);

        // Practical limits for most applications
        Instant year1970 = Instant.EPOCH;
        Instant year2100 = Instant.parse("2100-01-01T00:00:00Z");

        Duration range = Duration.between(year1970, year2100);
        System.out.println("Days between 1970-2100: " + range.toDays());
    }
}

Duration: Time-Based Amounts

Duration represents a time-based amount measured in seconds and nanoseconds.

Creating Durations:

public class DurationExamples {
    public void durationCreation() {
        // Factory methods for common durations
        Duration oneSecond = Duration.ofSeconds(1);
        Duration oneMinute = Duration.ofMinutes(1);
        Duration oneHour = Duration.ofHours(1);
        Duration oneDay = Duration.ofDays(1);

        // With nanosecond precision
        Duration precise = Duration.ofSeconds(5, 123456789);

        // From milliseconds
        Duration millis = Duration.ofMillis(500);

        // From nanoseconds
        Duration nanos = Duration.ofNanos(123456);

        // Parsing ISO-8601 duration format
        Duration parsed = Duration.parse("PT2H30M15S"); // 2h 30m 15s
        System.out.println("Parsed duration: " + parsed);

        // Between two temporal objects
        Instant start = Instant.now();
        Instant end = start.plusSeconds(3600);
        Duration between = Duration.between(start, end);
        System.out.println("Duration: " + between.toMinutes() + " minutes");
    }

    public void durationOperations() {
        Duration duration = Duration.ofHours(2).plusMinutes(30);

        // Get components
        long seconds = duration.getSeconds();
        int nanos = duration.getNano();

        // Convert to different units
        long totalSeconds = duration.toSeconds();
        long totalMillis = duration.toMillis();
        long totalMinutes = duration.toMinutes();
        long totalHours = duration.toHours();
        long totalDays = duration.toDays();

        System.out.println("Duration: " + totalHours + "h " + 
                         (totalMinutes % 60) + "m");

        // Arithmetic
        Duration doubled = duration.multipliedBy(2);
        Duration halved = duration.dividedBy(2);
        Duration negated = duration.negated();
        Duration absolute = duration.abs();

        // Comparisons
        Duration longer = Duration.ofHours(3);
        boolean isLonger = longer.compareTo(duration) > 0;

        // Check if negative or zero
        boolean isNegative = duration.isNegative();
        boolean isZero = duration.isZero();
    }

    public void durationFormatting() {
        Duration duration = Duration.ofHours(2).plusMinutes(45).plusSeconds(30);

        // ISO-8601 format
        String iso = duration.toString(); // PT2H45M30S

        // Custom formatting
        long hours = duration.toHours();
        long minutes = duration.toMinutesPart();
        long seconds = duration.toSecondsPart();

        String formatted = String.format("%d:%02d:%02d", hours, minutes, seconds);
        System.out.println("Formatted: " + formatted); // 2:45:30
    }
}

Period: Date-Based Amounts

Period represents a date-based amount in years, months, and days.

Creating Periods:

public class PeriodExamples {
    public void periodCreation() {
        // Factory methods
        Period oneDay = Period.ofDays(1);
        Period oneWeek = Period.ofWeeks(1);
        Period oneMonth = Period.ofMonths(1);
        Period oneYear = Period.ofYears(1);

        // Combined amounts
        Period combined = Period.of(1, 6, 15); // 1 year, 6 months, 15 days

        // Parsing ISO-8601 period format
        Period parsed = Period.parse("P1Y2M3D"); // 1 year, 2 months, 3 days
        System.out.println("Parsed period: " + parsed);

        // Between two dates
        LocalDate start = LocalDate.of(2025, 1, 1);
        LocalDate end = LocalDate.of(2026, 7, 15);
        Period between = Period.between(start, end);
        System.out.println("Period: " + between.getYears() + "y " + 
                         between.getMonths() + "m " + 
                         between.getDays() + "d");
    }

    public void periodOperations() {
        Period period = Period.ofMonths(6).plusDays(15);

        // Get components
        int years = period.getYears();
        int months = period.getMonths();
        int days = period.getDays();

        // Arithmetic (date-based, not exact)
        Period doubled = period.multipliedBy(2);
        Period negated = period.negated();

        // Normalize: Converts to standard representation
        Period unnormalized = Period.of(0, 14, 0); // 14 months
        Period normalized = unnormalized.normalized(); // 1 year, 2 months
        System.out.println("Normalized: " + normalized);

        // Check properties
        boolean isZero = period.isZero();
        boolean isNegative = period.isNegative();
    }

    public void periodVsDuration() {
        // Period: Date-based (months can vary in length)
        LocalDate date1 = LocalDate.of(2025, 1, 31);
        LocalDate plusOneMonth = date1.plus(Period.ofMonths(1));
        System.out.println("Jan 31 + 1 month = " + plusOneMonth); // Feb 28

        // Duration: Time-based (always exact)
        Instant instant1 = Instant.now();
        Instant plus24Hours = instant1.plus(Duration.ofHours(24));
        Instant plus1Day = instant1.plus(Duration.ofDays(1)); // Same as 24 hours

        // Period doesn't work with time-based types
        // instant1.plus(Period.ofDays(1)); // Throws UnsupportedTemporalTypeException
    }
}

Clock Abstraction

The Clock class provides access to the current instant and zone, enabling testable time-dependent code.

Clock Types:

public class ClockExamples {
    public void systemClocks() {
        // System clock with UTC timezone
        Clock utcClock = Clock.systemUTC();
        Instant utcNow = Instant.now(utcClock);

        // System clock with default timezone
        Clock defaultClock = Clock.systemDefaultZone();
        ZonedDateTime now = ZonedDateTime.now(defaultClock);

        // System clock with specific timezone
        Clock nyClock = Clock.system(ZoneId.of("America/New_York"));
        ZonedDateTime nyNow = ZonedDateTime.now(nyClock);

        System.out.println("UTC: " + utcNow);
        System.out.println("Default: " + now);
        System.out.println("NY: " + nyNow);
    }

    public void fixedClocks() {
        // Fixed clock for testing
        Instant fixedInstant = Instant.parse("2025-01-01T12:00:00Z");
        Clock fixedClock = Clock.fixed(fixedInstant, ZoneOffset.UTC);

        // All calls return the same instant
        Instant t1 = Instant.now(fixedClock);
        Thread.sleep(1000);
        Instant t2 = Instant.now(fixedClock);

        System.out.println("t1 equals t2: " + t1.equals(t2)); // true
    }

    public void offsetClocks() {
        // Offset from system clock
        Clock systemClock = Clock.systemUTC();
        Clock offsetClock = Clock.offset(systemClock, Duration.ofHours(2));

        Instant systemTime = Instant.now(systemClock);
        Instant offsetTime = Instant.now(offsetClock);

        System.out.println("System: " + systemTime);
        System.out.println("Offset: " + offsetTime);
        System.out.println("Difference: " + 
                         Duration.between(systemTime, offsetTime).toHours() + " hours");
    }

    public void tickClocks() {
        // Clock that ticks every second (truncates to seconds)
        Clock secondClock = Clock.tickSeconds(ZoneOffset.UTC);

        // Clock that ticks every minute
        Clock minuteClock = Clock.tickMinutes(ZoneOffset.UTC);

        // Custom tick interval
        Clock tick5Seconds = Clock.tick(Clock.systemUTC(), Duration.ofSeconds(5));

        Instant precise = Instant.now();
        Instant rounded = Instant.now(tick5Seconds);

        System.out.println("Precise: " + precise);
        System.out.println("5-second tick: " + rounded);
    }
}

Testable Code with Clock:

public class TimeBasedService {
    private final Clock clock;

    public TimeBasedService(Clock clock) {
        this.clock = clock;
    }

    // Default constructor uses system clock
    public TimeBasedService() {
        this(Clock.systemDefaultZone());
    }

    public boolean isBusinessHours() {
        LocalTime now = LocalTime.now(clock);
        return now.isAfter(LocalTime.of(9, 0)) && 
               now.isBefore(LocalTime.of(17, 0));
    }

    public String createTimestamp() {
        return Instant.now(clock).toString();
    }

    public boolean isExpired(Instant expiryTime) {
        return Instant.now(clock).isAfter(expiryTime);
    }
}

// Testing with fixed clock
class TimeBasedServiceTest {
    @Test
    public void testBusinessHours() {
        // Fix time to 10:00 AM
        Clock fixedClock = Clock.fixed(
            LocalDateTime.of(2025, 1, 6, 10, 0)
                .toInstant(ZoneOffset.UTC),
            ZoneOffset.UTC
        );

        TimeBasedService service = new TimeBasedService(fixedClock);
        assertTrue(service.isBusinessHours());
    }

    @Test
    public void testExpiry() {
        Instant fixedNow = Instant.parse("2025-01-06T12:00:00Z");
        Clock fixedClock = Clock.fixed(fixedNow, ZoneOffset.UTC);

        TimeBasedService service = new TimeBasedService(fixedClock);

        Instant futureExpiry = fixedNow.plus(Duration.ofHours(1));
        assertFalse(service.isExpired(futureExpiry));

        Instant pastExpiry = fixedNow.minus(Duration.ofHours(1));
        assertTrue(service.isExpired(pastExpiry));
    }
}

Time Zones and Zone Offsets

Understanding the difference between time zones and zone offsets is crucial for correct temporal handling.

ZoneId vs ZoneOffset:

public class TimeZoneBasics {
    public void zoneIdExamples() {
        // Region-based timezone with DST rules
        ZoneId newYork = ZoneId.of("America/New_York");
        ZoneId tokyo = ZoneId.of("Asia/Tokyo");
        ZoneId utc = ZoneId.of("UTC");

        // System default timezone
        ZoneId defaultZone = ZoneId.systemDefault();

        // Get all available zone IDs
        Set<String> availableZones = ZoneId.getAvailableZoneIds();
        System.out.println("Available zones: " + availableZones.size());

        // Zone rules include DST transitions
        ZoneRules nyRules = newYork.getRules();
        boolean isDst = nyRules.isDaylightSavings(Instant.now());
        System.out.println("NY currently in DST: " + isDst);
    }

    public void zoneOffsetExamples() {
        // Fixed UTC offsets (no DST)
        ZoneOffset utc = ZoneOffset.UTC;
        ZoneOffset plus5 = ZoneOffset.of("+05:00");
        ZoneOffset minus8 = ZoneOffset.ofHours(-8);
        ZoneOffset plusHalfHour = ZoneOffset.of("+05:30"); // India

        // Get total seconds from UTC
        int totalSeconds = plus5.getTotalSeconds();
        System.out.println("Total seconds offset: " + totalSeconds);

        // ZoneOffset is a ZoneId
        ZoneId offsetAsZone = plus5;
    }

    public void conversionExamples() {
        Instant instant = Instant.now();

        // Convert instant to zoned date-time
        ZoneId london = ZoneId.of("Europe/London");
        ZonedDateTime londonTime = instant.atZone(london);

        ZoneId sydney = ZoneId.of("Australia/Sydney");
        ZonedDateTime sydneyTime = instant.atZone(sydney);

        System.out.println("Same instant, different zones:");
        System.out.println("London: " + londonTime);
        System.out.println("Sydney: " + sydneyTime);

        // Both represent the same instant
        boolean sameInstant = londonTime.toInstant().equals(sydneyTime.toInstant());
        System.out.println("Same instant: " + sameInstant); // true
    }
}

Temporal Interface and ChronoUnit

The Temporal interface and ChronoUnit enum provide the foundation for temporal calculations.

Temporal Interface:

public class TemporalInterfaceExamples {
    public void temporalOperations() {
        // All date-time types implement Temporal
        Temporal instant = Instant.now();
        Temporal localDate = LocalDate.now();
        Temporal localDateTime = LocalDateTime.now();

        // Generic temporal operations
        Temporal later = instant.plus(1, ChronoUnit.HOURS);
        Temporal earlier = localDate.minus(7, ChronoUnit.DAYS);

        // Query temporal fields
        long epochDay = localDate.getLong(ChronoField.EPOCH_DAY);
        long hourOfDay = localDateTime.getLong(ChronoField.HOUR_OF_DAY);

        System.out.println("Epoch day: " + epochDay);
        System.out.println("Hour: " + hourOfDay);
    }

    public void chronoUnitOperations() {
        Instant start = Instant.now();

        // Add different units
        Instant plusNanos = start.plus(1000000, ChronoUnit.NANOS);
        Instant plusMicros = start.plus(1000, ChronoUnit.MICROS);
        Instant plusMillis = start.plus(100, ChronoUnit.MILLIS);
        Instant plusSeconds = start.plus(60, ChronoUnit.SECONDS);
        Instant plusMinutes = start.plus(30, ChronoUnit.MINUTES);
        Instant plusHours = start.plus(2, ChronoUnit.HOURS);
        Instant plusDays = start.plus(1, ChronoUnit.DAYS);

        // Calculate between units
        LocalDate date1 = LocalDate.of(2025, 1, 1);
        LocalDate date2 = LocalDate.of(2025, 12, 31);

        long daysBetween = ChronoUnit.DAYS.between(date1, date2);
        long weeksBetween = ChronoUnit.WEEKS.between(date1, date2);
        long monthsBetween = ChronoUnit.MONTHS.between(date1, date2);

        System.out.println("Days: " + daysBetween);
        System.out.println("Weeks: " + weeksBetween);
        System.out.println("Months: " + monthsBetween);
    }
}

Summary

The java.time fundamentals provide:

• Instant: Machine timeline representation with nanosecond precision
• Duration: Time-based amounts for hours, minutes, seconds
• Period: Date-based amounts for years, months, days
• Clock: Abstraction enabling testable time-dependent code
• ZoneId/ZoneOffset: Time zone and UTC offset representations
• Temporal Interface: Common abstraction for all temporal types

These building blocks form the foundation for all date and time operations in modern Java applications.