Date-Time API Naming Conventions

The Java date-time module offers a comprehensive suite of classes and methods designed for consistency and immutability. To support these immutable objects, the API adopts specific method prefixes. For instance, rather than using set methods which modify state in-place, the API utilizes a with prefix to generate new instances with modified values.

Static Factory Methods

• of: Constructs a new instance primarily validating inputs.
• from: Conevrts an object from another type, potentially discarding data.
• parse: Transforms string representations into object instances.

Instance Methods

• get: Retrieves specific state enformation.
• is: Checks conditional status flags.
• with: Returns a copy with a specific element changed.
• plus / minus: Produces copies adjusted forward or backward by time amounts.
• to: Converts the current object into a different class type.
• at: Combines the current object with another entity.
• format: Outputs a string representation using a specified formattter.

The ISO Calendar System

The foundation of the java.time package is the ISO-8601 calendar system. This standard aligns dates chronologically starting from the introduction of the Gregorian calendar in 1582, projected continuously backwards (Proleptic Gregorian). This approach simplifies calculations by establishing a single, continuous timeline.

Core Components

This documentation explores the primary categories within the package:

• Overview: Distinguishes between human-readable time (year/month/day) and machine time (epochs).
• Enumerations: Types for days of the week (DayOfWeek) and months (Month).
• Date-Only Classes: LocalDate, YearMonth, MonthDay, and Year.
• Date-Time Classes: LocalTime and LocalDateTime (excluding time zone data).
• Time Zone & Offset: ZonedDateTime, OffsetDateTime, OffsetTime, plus supporting classes like ZoneId.
• Instant: Represents a point on the timeline in UTC.
• Formatting: Mechanisms to parse strings and format objects.
• Temporal Package: Advanced manipulation via TemporalAdjuster and fields.
• Intervals: Calculating durations between dates using Period and Duration.
• Clock: Simulating time sources for testing.
• Non-ISO Calendars: Converting to and from local calendar systems.
• Legacy Support: Interoperability with deprecated java.util classes.

Data Representation Overview

Selecting the right class depends on whether you require absolute machine time or human-centric data. Below is a summary of available types:

Enumerations: Days and Months

Strongly typed enumerations exist for recurring calendar concepts.

DayOfWeek

The DayOfWeek enum defines seven constants representing Monday through Sunday. You can perform arithmetic on these directly.

var dow = DayOfWeek.MONDAY;
var result = dow.plus(3);
System.out.println(result); // Prints: THURSDAY

To display localized names, use getDisplayName:

var locale = Locale.getDefault();
System.out.println(dow.getDisplayName(TextStyle.FULL, locale));     // Full name
System.out.println(dow.getDisplayName(TextStyle.SHORT, locale));    // Abbreviated

Month

The Month enum follows similar logic, ranging from January (1) to December (12).

var febDays = Month.FEBRUARY.maxLength();
// Feb usually has 29 days in leap years, otherwise 28/29

Working with Dates

For scenarios requiring granular date control without time components, several classes are available.

LocalDate

Represents a date independent of time or timezone (Year-Month-Day). Useful for birthdays or anniversaries.

var eventDate = LocalDate.of(2023, Month.OCTOBER, 15);
// Find the next Wednesday
var nextWed = eventDate.with(TemporalAdjusters.next(DayOfWeek.WEDNESDAY));

YearMonth & Year

YearMonth captures the month of a specific year, useful for billing cycles. Year represents just the year value.

var february2024 = YearMonth.of(2024, Month.FEBRUARY);
if (february2024.lengthOfMonth() == 29) {
    System.out.println("Leap Year Detected");
}

Local Time and DateTime

These classes handle time components but exclude timezone awareness.

LocalTime

Ideal for schedules, opening hours, or clock displays.

var currentTime = LocalTime.now();
System.out.printf("%02d:%02d%n", currentTime.getHour(), currentTime.getMinute());

LocalDateTime

Combines LocalDate and LocalTime. Essential for recording when events occur locally.

var dt = LocalDateTime.now().plusMonths(6);
System.out.println(dt.format(DateTimeFormatter.ISO_LOCAL_DATE_TIME));

Time Zones and Offsets

Global applications require handling geographical time differences.

ZoneId and ZoneOffset

ZoneId identifies a region (e.g., America/New_York), accounting for daylight saving rules. ZoneOffset represents a fixed offset from UTC (e.g., +05:30).

Timezone Aware Classes

1. ZonedDateTime: Includes full timezone information and DST transitions.
2. OffsetDateTime: Includes a fixed UTC offset, used often in logs or APIs.

Example of flight calculation across zones:

var departure = ZonedDateTime.of(
    LocalDateTime.of(2023, 7, 20, 19, 30), 
    ZoneId.of("America/Los_Angeles")
);

var arrival = departure.plusHours(11).withZoneSameInstant(ZoneId.of("Asia/Tokyo"));

The Instant Class

Instant represents a precise moment on the timeline (nanosecond precision), typically stored as seconds/nanos since the Epoch (Jan 1, 1970 UTC). It does not handle human readable units like years directly.

var timestamp = Instant.now();
long nanos = timestamp.until(Instant.EPOCH, ChronoUnit.NANOS);

Parsing and Formatting

The DateTimeFormatter class handles string conversions safely and is thread-safe.

// Custom Pattern
var formatter = DateTimeFormatter.ofPattern("dd/MM/yyyy hh:mm a");
String str = localDate.format(formatter);

// Parsing
try {
    var parsed = LocalDate.parse("2023-01-01", DateTimeFormatter.ISO_LOCAL_DATE);
} catch (DateTimeParseException e) {
    e.printStackTrace();
}

Advanced Temporal Operations

The java.time.temporal package enables deep customization of time logic.

Units and Fields

ChronoUnit lists standard intervals (Seconds, Days, Months). ChronoField specifies properties like HOUR_OF_DAY. Check support via isSupported.

boolean supported = instant.isSupported(ChronoUnit.DAYS);

Adjusters

Predefined adjusters simplify common tasks like finding the "last day of the month" or "next Monday".

var lastMonday = today.with(TemporalAdjusters.lastInMonth(DayOfWeek.MONDAY));

Queries

TemporalQuery allows extracting specific values from time objects dynamically.

Long ageInYears = today.query(TemporalkQueries.age());

Duration vs Period

Distinguish between measuring elapsed machine time versus calendar time.

• Duration: Measures exact time passed (seconds/nanoseconds). Independent of calendars.
• Period: Measures calendar-based time (years/months/days). Sensitive to DST.

// Exact duration
var dur = Duration.between(start, end);

// Calendar period
var p = Period.between(birthday, now);
int years = p.getYears();

Clocks

While LocalDateTime.now() uses the system clock, injecting a Clock allows mocking time for testing purposes.

var fakeClock = Clock.fixed(Instant.parse("2023-01-01T00:00Z"), ZoneId.of("UTC"));
var frozenTime = LocalDateTime.now(fakeClock);

Non-ISO Calendars

The java.time.chrono package supports alternative calendar systems like Japanese or Buddhist eras.

var jpDate = JapaneseDate.from(LocalDate.now());
// Format using specific rules
System.out.println(jpDate.toString());

Migrating Legacy Code

If dealing with pre-Java 8 code, use utility methods for conversion.

// Date to Instant
Instant inst = date.toInstant();

// Calendar to Zoned
ZonedDateTime zdt = cal.toZonedDateTime();

Introduction to Internationalization (i18n)

Internationalization prepares software for global audiences by separating language-specific resources from code. Localization (l10n) adapts the application for specific regions.

Using Locales

A Locale identifies a specific language and geographic region.

var deDE = new Locale("de", "DE");
var frFR = Locale.FRENCH; // Shortcut

You can construct locales using builders or language tags compatible with BCP 47 standards.

Resource Bundles

Externalize strings into property files named according to their locale (e.g., Messages_en_US.properties). Retrieve messages dynamically.

var bundle = ResourceBundle.getBundle("Messages", locale);
System.out.println(bundle.getString("welcome_msg"));

Formatting Data

Numerical and date formatting must respect regional standards.

NumberFormat nf = NumberFormat.getCurrencyInstance(Locale.FRANCE);
System.out.println(nf.format(1234.56)); // € 1 234,56

Standardized classes ensure correct sorting (Collation), character validation (Unicode), and currency symbols regardless of the user's environment.