Java ChronoLocalDate Interface

Last modified: April 16, 2025

The java.time.chrono.ChronoLocalDate interface represents a date without time or time-zone in an arbitrary chronology. It is part of Java's modern date-time API introduced in Java 8. The interface is calendar system agnostic.

ChronoLocalDate extends Temporal and Comparable. It provides methods for date manipulation and querying across different calendar systems. Implementations include LocalDate for ISO calendar and dates in other calendar systems like Japanese or Thai.

ChronoLocalDate Interface Overview

The interface defines operations common to all calendar systems. Key methods include date arithmetic, field access, and comparisons. It supports both proleptic and non-proleptic calendar systems through implementations.

public interface ChronoLocalDate extends Temporal, TemporalAdjuster, 
    Comparable<ChronoLocalDate> {
    Chronology getChronology();
    int getEraValue();
    boolean isLeapYear();
    int lengthOfMonth();
    int lengthOfYear();
    ChronoLocalDate plus(long amountToAdd, TemporalUnit unit);
    ChronoLocalDate minus(long amountToSubtract, TemporalUnit unit);
    long until(Temporal endExclusive, TemporalUnit unit);
    boolean isAfter(ChronoLocalDate other);
    boolean isBefore(ChronoLocalDate other);
    boolean isEqual(ChronoLocalDate other);
}

The code shows key methods of ChronoLocalDate. These methods allow date manipulation across different calendar systems. The interface provides consistent operations regardless of the underlying chronology.

Creating ChronoLocalDate Objects

ChronoLocalDate instances are created through chronology-specific implementations. The ISO calendar uses LocalDate, while other calendars use their specific date classes. Factory methods are commonly used.

package com.zetcode;

import java.time.LocalDate;
import java.time.chrono.HijrahDate;
import java.time.chrono.JapaneseDate;
import java.time.chrono.MinguoDate;
import java.time.chrono.ThaiBuddhistDate;

public class Main {

    public static void main(String[] args) {
        
        // ISO calendar date
        LocalDate isoDate = LocalDate.of(2025, 4, 15);
        System.out.println("ISO date: " + isoDate);
        
        // Japanese calendar date
        JapaneseDate japaneseDate = JapaneseDate.of(2025, 4, 15);
        System.out.println("Japanese date: " + japaneseDate);
        
        // Hijrah (Islamic) calendar date
        HijrahDate hijrahDate = HijrahDate.of(1446, 10, 17);
        System.out.println("Hijrah date: " + hijrahDate);
        
        // Thai Buddhist calendar date
        ThaiBuddhistDate thaiDate = ThaiBuddhistDate.of(2568, 4, 15);
        System.out.println("Thai date: " + thaiDate);
        
        // Minguo (Taiwan) calendar date
        MinguoDate minguoDate = MinguoDate.of(114, 4, 15);
        System.out.println("Minguo date: " + minguoDate);
    }
}

This example creates dates in different calendar systems. Each date class implements ChronoLocalDate. The output shows dates formatted according to their respective calendar systems.

Accessing Date Fields

ChronoLocalDate provides methods to access date fields like year, month, and day. These values are calendar-system specific. The interface also provides methods to get era and check for leap years.

package com.zetcode;

import java.time.chrono.JapaneseDate;
import java.time.chrono.JapaneseEra;

public class Main {

    public static void main(String[] args) {
        
        JapaneseDate jdate = JapaneseDate.of(JapaneseEra.REIWA, 7, 4, 15);
        
        System.out.println("Chronology: " + jdate.getChronology());
        System.out.println("Era: " + jdate.getEra());
        System.out.println("Year: " + jdate.getYear());
        System.out.println("Month: " + jdate.getMonthValue());
        System.out.println("Day: " + jdate.getDayOfMonth());
        System.out.println("Day of year: " + jdate.getDayOfYear());
        System.out.println("Leap year: " + jdate.isLeapYear());
        System.out.println("Month length: " + jdate.lengthOfMonth());
        System.out.println("Year length: " + jdate.lengthOfYear());
    }
}

This example demonstrates accessing various fields of a Japanese calendar date. The values are specific to the Japanese calendar system. Note how era is a significant part of the date representation in some calendar systems.

Date Comparisons

ChronoLocalDate provides methods to compare dates across different calendar systems. The comparisons are based on the temporal position of dates rather than their calendar-specific representations.

package com.zetcode;

import java.time.LocalDate;
import java.time.chrono.HijrahDate;
import java.time.chrono.JapaneseDate;

public class Main {

    public static void main(String[] args) {
        
        LocalDate isoDate = LocalDate.of(2025, 4, 15);
        JapaneseDate jdate = JapaneseDate.of(2025, 4, 15);
        HijrahDate hdate = HijrahDate.of(1446, 10, 17);
        
        System.out.println("ISO equals Japanese: " + isoDate.isEqual(jdate));
        System.out.println("ISO equals Hijrah: " + isoDate.isEqual(hdate));
        System.out.println("ISO before Hijrah: " + isoDate.isBefore(hdate));
        System.out.println("ISO after Japanese: " + isoDate.isAfter(jdate));
        
        // Compare across chronologies
        System.out.println("Comparison result: " + isoDate.compareTo(hdate));
    }
}

This example compares dates from different calendar systems. The isEqual method returns true for dates representing the same day, regardless of calendar system. Comparisons are based on temporal position.

Date Arithmetic

ChronoLocalDate supports date arithmetic operations like adding or subtracting days, months, or years. These operations respect the rules of the specific calendar system.

package com.zetcode;

import java.time.LocalDate;
import java.time.chrono.HijrahDate;
import java.time.temporal.ChronoUnit;

public class Main {

    public static void main(String[] args) {
        
        HijrahDate hdate = HijrahDate.of(1446, 10, 17);
        System.out.println("Original Hijrah date: " + hdate);
        
        // Add days
        HijrahDate plusDays = hdate.plus(10, ChronoUnit.DAYS);
        System.out.println("Plus 10 days: " + plusDays);
        
        // Subtract months
        HijrahDate minusMonths = hdate.minus(2, ChronoUnit.MONTHS);
        System.out.println("Minus 2 months: " + minusMonths);
        
        // Add years
        HijrahDate plusYears = hdate.plus(1, ChronoUnit.YEARS);
        System.out.println("Plus 1 year: " + plusYears);
        
        // Using Period with ISO date
        LocalDate isoDate = LocalDate.of(2025, 4, 15);
        System.out.println("Original ISO date: " + isoDate);
        System.out.println("Plus 1 month: " + isoDate.plusMonths(1));
    }
}

This example shows date arithmetic operations on Hijrah and ISO dates. The operations respect each calendar's rules. Note how month lengths and leap years are handled differently in each calendar system.

Converting Between Calendars

ChronoLocalDate implementations can convert between different calendar systems. The conversion preserves the temporal position while changing the calendar representation.

package com.zetcode;

import java.time.LocalDate;
import java.time.chrono.HijrahDate;
import java.time.chrono.JapaneseDate;
import java.time.chrono.MinguoDate;

public class Main {

    public static void main(String[] args) {
        
        LocalDate isoDate = LocalDate.of(2025, 4, 15);
        System.out.println("ISO date: " + isoDate);
        
        // Convert to Japanese date
        JapaneseDate jdate = JapaneseDate.from(isoDate);
        System.out.println("Japanese date: " + jdate);
        
        // Convert to Hijrah date
        HijrahDate hdate = HijrahDate.from(isoDate);
        System.out.println("Hijrah date: " + hdate);
        
        // Convert to Minguo date
        MinguoDate mdate = MinguoDate.from(isoDate);
        System.out.println("Minguo date: " + mdate);
        
        // Convert back to ISO
        LocalDate backToIso = LocalDate.from(hdate);
        System.out.println("Back to ISO: " + backToIso);
    }
}

This example demonstrates conversions between ISO and other calendar systems. The from method performs the conversion while maintaining the same temporal position. Conversions are symmetric and lossless.

Calculating Periods Between Dates

The until method calculates the period between two dates in specified units. This works across different calendar systems, returning the temporal distance between dates.

package com.zetcode;

import java.time.LocalDate;
import java.time.chrono.HijrahDate;
import java.time.chrono.JapaneseDate;
import java.time.temporal.ChronoUnit;

public class Main {

    public static void main(String[] args) {
        
        LocalDate date1 = LocalDate.of(2025, 1, 1);
        LocalDate date2 = LocalDate.of(2025, 4, 15);
        
        // Days between ISO dates
        long daysBetween = date1.until(date2, ChronoUnit.DAYS);
        System.out.println("Days between: " + daysBetween);
        
        // Months between ISO dates
        long monthsBetween = date1.until(date2, ChronoUnit.MONTHS);
        System.out.println("Months between: " + monthsBetween);
        
        // Days between different calendar systems
        HijrahDate hdate1 = HijrahDate.from(date1);
        JapaneseDate jdate2 = JapaneseDate.from(date2);
        long crossDays = hdate1.until(jdate2, ChronoUnit.DAYS);
        System.out.println("Cross-calendar days: " + crossDays);
    }
}

This example shows period calculations between dates. The until method works with both same-calendar and cross-calendar comparisons. The results represent the actual temporal distance between dates.

Source

Java ChronoLocalDate Interface Documentation

In this article, we've covered the essential methods and features of the Java ChronoLocalDate interface. Understanding these concepts is crucial for working with dates in different calendar systems in Java applications.

Author

My name is Jan Bodnar, and I am a dedicated programmer with many years of experience in the field. I began writing programming articles in 2007 and have since authored over 1,400 articles and eight e-books. With more than eight years of teaching experience, I am committed to sharing my knowledge and helping others master programming concepts.

List all Java tutorials.