1. Introduction to java.time Package
The java.time package was introduced in Java 8 (JSR-310) as a modern replacement for the old java.util.Date and java.util.Calendar classes. This comprehensive API provides a much cleaner, more intuitive, and thread-safe way to work with dates, times, and durations.
The package is inspired by the popular Joda-Time library and addresses many of the shortcomings of the legacy date/time APIs. All classes in java.time are immutable and thread-safe, making them ideal for modern concurrent applications.
2. Instant class
2.1 Introducing the Instant Class
The Instant class represents a specific moment on the timeline in UTC (Coordinated Universal Time). It’s essentially a timestamp that captures a point in time with nanosecond precision. Think of it as a snapshot of the universal clock at a particular moment.
Instant is timezone-agnostic and represents the same moment everywhere in the world. It’s perfect for recording event timestamps, measuring elapsed time, or working with machine-oriented time.
// Create an Instant representing the current moment
Instant now = Instant.now();
// Parse an Instant from a string (ISO-8601 format)
Instant parsed = Instant.parse("2024-12-07T10:15:30.123Z");
// Create an Instant from epoch seconds
Instant epochInstant = Instant.ofEpochSecond(1701950130);2.2 How Instant Class Stores Time Value
The Instant class stores time using two internal fields that together provide nanosecond precision:
Internal Storage Structure:
- seconds: A long value representing the number of seconds from the Java epoch (1970-01-01T00:00:00Z)
- nanos: An int value representing the nanosecond adjustment within that second (0 to 999,999,999)
This two-field design efficiently represents any instant in time with nanosecond precision while avoiding the need for BigInteger arithmetic. The seconds field can represent approximately 292 years before and after the epoch, which is sufficient for virtually all practical applications.
Instant instant = Instant.now();
// Access the components
long seconds = instant.getEpochSecond(); // Seconds from epoch
int nanos = instant.getNano(); // Nanosecond portion
System.out.println("Seconds: " + seconds);
System.out.println("Nanos: " + nanos);3.Non-Timezone Classes vs Timezone Classes
The Java Time API clearly distinguishes between classes that work without timezone information and those that include timezone context. Understanding this distinction is crucial for choosing the right class for your use case.
| Non-Timezone Classes | Timezone Classes |
LocalDate – Date without time or timezone | ZonedDateTime – Date and time with timezone |
LocalTime – Time without date or timezone | OffsetDateTime – Date and time with UTC offset |
LocalDateTime – Date and time without timezone | OffsetTime – Time with UTC offset |
Instant – Point in time (implicitly UTC) | ZoneId / ZoneOffset – Timezone identifiers |
// Non-timezone: A birthday (same date everywhere conceptually)
LocalDate birthday = LocalDate.of(1990, 5, 15);
// Non-timezone: A meeting time (assumes local context)
LocalDateTime meeting = LocalDateTime.of(2024, 12, 7, 14, 30);
// Timezone: An international flight departure
ZonedDateTime departure = ZonedDateTime.of(
2024, 12, 7, 14, 30, 0, 0,
ZoneId.of("America/New_York")
);4. Conversions Between Classes in the Java Time API
One of the powerful features of the Java Time API is the ability to convert between different temporal classes. Understanding these conversions is essential for working effectively with the API.
// LocalDateTime to ZonedDateTime
LocalDateTime localDT = LocalDateTime.now();
ZonedDateTime zonedDT = localDT.atZone(ZoneId.of("Asia/Ho_Chi_Minh"));
// ZonedDateTime to Instant
Instant instant = zonedDT.toInstant();
// Instant to ZonedDateTime
ZonedDateTime backToZoned = instant.atZone(ZoneId.of("Europe/Paris"));
// LocalDate + LocalTime = LocalDateTime
LocalDate date = LocalDate.of(2024, 12, 7);
LocalTime time = LocalTime.of(14, 30);
LocalDateTime combined = LocalDateTime.of(date, time);
// ZonedDateTime to LocalDateTime (loses timezone info)
LocalDateTime localFromZoned = zonedDT.toLocalDateTime();
// LocalDateTime to OffsetDateTime
OffsetDateTime offsetDT = localDT.atOffset(ZoneOffset.of("+07:00"));
// Instant to OffsetDateTime
OffsetDateTime instantToOffset = instant.atOffset(ZoneOffset.UTC);5. Differences Between OffsetDateTime and ZonedDateTime
Both OffsetDateTime and ZonedDateTime represent a date-time with timezone information, but they differ in how they handle that information and when you should use each.
| Aspect | OffsetDateTime | ZonedDateTime |
| Timezone Representation | Fixed UTC offset (e.g., +07:00) | Full timezone with rules (e.g., Asia/Ho_Chi_Minh) |
| DST Handling | Does not handle DST transitions | Automatically handles DST transitions |
| Storage | date, time, offset | date, time, zone ID, offset |
| Example | 2024-12-07T14:30:00+07:00 | 2024-12-07T14:30:00+07:00[Asia/Ho_Chi_Minh] |