Java LocalDate spiegato: Guida completa alla gestione delle date in Java 8 e versioni successive

.## Cos’è LocalDate?

La gestione delle date in Java è evoluta notevolmente dalla versione 8. Al centro di questa evoluzione c’è LocalDate. LocalDate è un oggetto immutabile che rappresenta solo una data (anno, mese e giorno, ad es. 2025-06-26), senza alcun concetto di ora o fuso orario. Consente di gestire la data odierna o date di calendario specifiche in modo semplice e sicuro.

Differenze rispetto alle classi Date legacy

Prima di Java 8, classi come java.util.Date e java.util.Calendar erano comunemente usate. Tuttavia, queste classi presentavano diversi problemi, tra cui design soggetto a errori (come i mesi indicizzati da zero), mancanza di thread‑safety e API non intuitive. Di conseguenza, spesso portavano a bug o comportamenti inattesi.

LocalDate risolve questi problemi e offre le seguenti caratteristiche:

• Gestione esplicita di anno, mese e giorno soltanto (ad es. 26 giugno 2025)
• Oggetto immutabile (i valori non possono essere modificati, garantendo sicurezza)
• Nomi di metodo intuitivi e design dell’API (ad es. plusDays(1) per il giorno successivo, getMonthValue() per il numero del mese)
• Indipendente dal fuso orario (comportamento coerente indipendentemente dalle impostazioni di sistema o del server)

Quando dovresti usare LocalDate?

LocalDate è ideale quando vuoi gestire le date in modo chiaro, non hai bisogno di informazioni sull’ora e desideri implementare operazioni sulle date in modo sicuro e semplice. I casi d’uso tipici includono:

• Registrare date senza ora, come compleanni o anniversari
• Gestire programmi, scadenze e date di consegna
• Calcolare scadenze o giorni rimanenti

Per questi motivi, LocalDate può essere considerato il nuovo standard per la gestione delle date in Java. Nella sezione successiva spiegheremo in dettaglio l’uso di base e l’inizializzazione di LocalDate.

Operazioni di base con LocalDate

LocalDate fornisce un’API intuitiva e semplice per la manipolazione delle date. Questa sezione illustra le funzionalità più comuni con esempi concreti.

Ottenere la data corrente

Per ottenere la data di oggi, usa il metodo LocalDate.now(). Restituisce la data di sistema corrente (indipendente dal fuso orario) come istanza di LocalDate.

import java.time.LocalDate;

LocalDate today = LocalDate.now();
System.out.println(today); // Example: 2025-06-26

Creare una data specifica

Per creare una data arbitraria nel passato o nel futuro, usa LocalDate.of(int year, int month, int dayOfMonth). Questo ti permette di creare liberamente date come il 31 dicembre 2024.

LocalDate specialDay = LocalDate.of(2024, 12, 31);
System.out.println(specialDay); // 2024-12-31

Analizzare (parse) una data da una stringa

Per generare un LocalDate da una stringa come “2023-03-15”, usa il metodo LocalDate.parse(String text). Se la stringa segue il formato ISO standard (“YYYY-MM-DD”), non è necessaria alcuna configurazione aggiuntiva.

LocalDate parsedDate = LocalDate.parse("2023-03-15");
System.out.println(parsedDate); // 2023-03-15

Analisi con formato personalizzato (Supplemento)

Se devi gestire date in un formato personalizzato come “2023/03/15”, puoi combinare DateTimeFormatter con parse().

import java.time.format.DateTimeFormatter;

DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy/MM/dd");
LocalDate formattedDate = LocalDate.parse("2023/03/15", formatter);
System.out.println(formattedDate); // 2023-03-15

Come mostrato sopra, le operazioni di base di LocalDate sono intuitive e dirette. Nel codice Java moderno, l’inizializzazione e la conversione delle date è raramente fonte di confusione. Nel capitolo successivo spiegheremo come estrarre i valori di anno, mese, giorno e giorno della settimana da LocalDate.

Recuperare anno, mese, giorno e giorno della settimana

LocalDate consente di estrarre facilmente non solo la data stessa, ma anche i singoli componenti come anno, mese, giorno e giorno della settimana. Questa sezione spiega come ottenere questi elementi comunemente usati.

Ottenere anno, mese e giorno

Per recuperare ciascun componente da un’istanza di LocalDate, usa i metodi getter dedicati.

LocalDate date = LocalDate.of(2025, 6, 26);

int year = date.getYear();           // Year (e.g. 2025)
int month = date.getMonthValue();    // Month as a number (1–12, e.g. 6)
int day = date.getDayOfMonth();      // Day of month (1–31, e.g. 26)

System.out.println("Year: " + year);
System.out.println("Month: " + month);
System.out.println("Day: " + day);

Ottenere i nomi di mesi e giorni della settimana

LocalDate supporta anche il recupero dei nomi di mesi e giorni della settimana, utile quando è necessario avere rappresentazioni testuali.

• Nome del mese (rappresentazione in inglese) Usando getMonth() restituisce un valore enum Month (ad es. JUNE).

  import java.time.Month;
  
  Month monthName = date.getMonth(); // JUNE (uppercase English)
  System.out.println(monthName);
  

• Nome del giorno della settimana getDayOfWeek() restituisce un enum DayOfWeek (ad es. THURSDAY).

  import java.time.DayOfWeek;
  
  DayOfWeek dayOfWeek = date.getDayOfWeek(); // THURSDAY (uppercase English)
  System.out.println(dayOfWeek);
  

Visualizzare i nomi di mesi e giorni della settimana in giapponese

Se desideri visualizzare i nomi di mesi o giorni della settimana in giapponese anziché in inglese, puoi personalizzare l’output usando DateTimeFormatter.

import java.time.format.DateTimeFormatter;
import java.util.Locale;

DateTimeFormatter formatter =
    DateTimeFormatter.ofPattern("yyyy年MM月dd日(E)", Locale.JAPANESE);
String formatted = date.format(formatter); // 2025年06月26日(木)
System.out.println(formatted);

Riepilogo dei componenti recuperati

Una delle principali caratteristiche di LocalDate è che consente di recuperare anno, mese, giorno e giorno della settimana usando metodi intuitivi. Questa flessibilità rende la gestione delle date in applicazioni aziendali e web molto più semplice.

Calcoli di data (Aggiunta e Sottrazione)

I calcoli di data, come aggiungere o sottrarre giorni, sono spesso necessari per la gestione dei programmi e il calcolo delle scadenze. Con LocalDate, è possibile eseguire in modo sicuro e intuitivo operazioni come “tre giorni dopo”, “una settimana prima” o “la differenza tra due date”.

Aggiungere date

• Aggiungere giorni

  LocalDate today = LocalDate.of(2025, 6, 26);
  LocalDate threeDaysLater = today.plusDays(3); // Three days later
  System.out.println(threeDaysLater); // 2025-06-29
  

• Aggiungere mesi o anni

  LocalDate nextMonth = today.plusMonths(1); // One month later
  LocalDate nextYear = today.plusYears(1);   // One year later
  System.out.println(nextMonth); // 2025-07-26
  System.out.println(nextYear);  // 2026-06-26
  

Sottrarre date

• Sottrarre giorni, mesi o anni

  LocalDate lastWeek = today.minusWeeks(1);   // One week earlier
  LocalDate previousDay = today.minusDays(1); // Previous day
  System.out.println(lastWeek);    // 2025-06-19
  System.out.println(previousDay); // 2025-06-25
  

Calcolare le differenze tra date

• Calcolare la differenza in giorni

  import java.time.temporal.ChronoUnit;
  
  LocalDate start = LocalDate.of(2025, 6, 1);
  LocalDate end = LocalDate.of(2025, 6, 26);
  
  long daysBetween = ChronoUnit.DAYS.between(start, end); // 25
  System.out.println(daysBetween); // 25
  

• Calcolare le differenze usando altre unità (mesi, anni)

  long monthsBetween = ChronoUnit.MONTHS.between(start, end); // 0
  long yearsBetween = ChronoUnit.YEARS.between(start, end);   // 0
  

Riepilogo

Utilizzando i metodi di aggiunta e sottrazione di LocalDate, è possibile implementare facilmente i calcoli di data comuni, come “scadenza del prossimo mese” o “giorni trascorsi dall’ultimo evento”.

Poiché LocalDate è immutabile, l’istanza originale non viene mai modificata. Ogni operazione restituisce una nuova istanza di LocalDate, garantendo una gestione sicura delle date.

Operazioni avanzate: Regolare date specifiche

Nella gestione delle date nel mondo reale, una semplice aggiunta o sottrazione spesso non è sufficiente. Le esigenze comuni includono determinare l’“ultimo giorno del mese” o il “primo giorno del mese successivo”. LocalDate fornisce API pratiche per questi tipi di aggiustamenti.

.### Utilizzo di TemporalAdjuster

Con LocalDate, puoi combinare il metodo with() e TemporalAdjuster per eseguire operazioni intuitive come “fine del mese”, “inizio del mese” o “prossimo giorno della settimana specifico”. Gli adjuster integrati sono forniti nella classe TemporalAdjusters.

Ottenere il Primo e l’Ultimo Giorno di un Mese

• Ottenere l’ultimo giorno del mese

  import java.time.LocalDate;
  import java.time.temporal.TemporalAdjusters;
  
  LocalDate date = LocalDate.of(2025, 6, 26);
  LocalDate endOfMonth = date.with(TemporalAdjusters.lastDayOfMonth());
  System.out.println(endOfMonth); // 2025-06-30
  

• Ottenere il primo giorno del mese

  LocalDate startOfMonth = date.with(TemporalAdjusters.firstDayOfMonth());
  System.out.println(startOfMonth); // 2025-06-01
  

Regolare in Base ai Giorni della Settimana

Le regolazioni basate sui giorni della settimana — come “il secondo lunedì del mese” o “il prossimo venerdì” — sono anch’esse facili da implementare.

• Ottenere il prossimo venerdì

  import java.time.DayOfWeek;
  
  LocalDate nextFriday =
      date.with(TemporalAdjusters.next(DayOfWeek.FRIDAY));
  System.out.println(nextFriday); // 2025-06-27
  

• Ottenere il secondo lunedì del mese corrente

  LocalDate secondMonday =
      date.with(TemporalAdjusters.dayOfWeekInMonth(2, DayOfWeek.MONDAY));
  System.out.println(secondMonday); // 2025-06-09
  

Regolare all’Inizio o alla Fine di un Anno

Puoi applicare lo stesso approccio per recuperare il primo o l’ultimo giorno di un anno.

LocalDate startOfYear =
    date.with(TemporalAdjusters.firstDayOfYear());
LocalDate endOfYear =
    date.with(TemporalAdjusters.lastDayOfYear());

System.out.println(startOfYear); // 2025-01-01
System.out.println(endOfYear);   // 2025-12-31

Creare Adjuster Personalizzati

Se hai bisogno di una logica di aggiustamento della data personalizzata basata su regole di business specifiche, puoi implementare tu stesso l’interfaccia TemporalAdjuster.

Combinando LocalDate con TemporalAdjusters, anche i calcoli di data più complessi diventano intuitivi e flessibili. Questo è particolarmente utile quando si gestiscono scadenze o calendari specifici per l’azienda.

Lavorare con LocalDate e LocalDateTime

All’interno dell’API Java Date and Time (java.time package), LocalDate rappresenta solo una data, mentre LocalDateTime rappresenta sia data che ora. Nella pratica, gli sviluppatori spesso devono convertire tra questi due tipi. Questa sezione spiega come eseguire tali conversioni.

Convertire LocalDate in LocalDateTime

Per aggiungere informazioni sull’ora a un LocalDate e convertirlo in LocalDateTime, usa atTime() o atStartOfDay().

• Aggiungere un orario specifico

  import java.time.LocalDate;
  import java.time.LocalDateTime;
  
  LocalDate date = LocalDate.of(2025, 6, 26);
  LocalDateTime dateTime =
      date.atTime(14, 30, 0); // 2025-06-26 14:30:00
  System.out.println(dateTime);
  

• Creare un LocalDateTime all’inizio della giornata

  LocalDateTime startOfDay =
      date.atStartOfDay(); // 2025-06-26T00:00
  System.out.println(startOfDay);
  

Convertire LocalDateTime in LocalDate

Per estrarre solo la parte di data da un LocalDateTime, usa il metodo toLocalDate().

import java.time.LocalDateTime;

LocalDateTime dateTime =
    LocalDateTime.of(2025, 6, 26, 14, 30);
LocalDate dateOnly = dateTime.toLocalDate();
System.out.println(dateOnly); // 2025-06-26

Combinare LocalDate con LocalTime

Puoi anche combinare un LocalDate e un LocalTime per creare un LocalDateTime.

import java.time.LocalTime;

LocalTime time = LocalTime.of(9, 0);
LocalDateTime combined =
    date.atTime(time); // 2025-06-26T09:00
System.out.println(combined);

Riepilogo

• Converti LocalDate in LocalDateTime usando atTime() o atStartOfDay()
• Converti LocalDateTime in LocalDate usando toLocalDate()
• Separare e combinare data e ora è comune nei sistemi reali

Gestione delle Eccezioni e Buone Pratiche

La gestione delle date può facilmente portare a eccezioni inaspettate se vengono utilizzati valori o formati non validi. Anche quando si lavora con LocalDate, possono verificarsi eccezioni a causa di date inesistenti o errori di parsing. Questa sezione spiega le eccezioni comuni e le migliori pratiche per gestirle in modo sicuro.

Specificare una Data Inesistente

Se si tenta di creare una data che non esiste—come il 30 febbraio 2023—verrà lanciata una DateTimeException.

import java.time.LocalDate;

// Example that throws an exception
LocalDate invalidDate = LocalDate.of(2023, 2, 30);

In tali casi, è importante catturare l’eccezione e gestirla in modo appropriato.

try {
    LocalDate invalidDate = LocalDate.of(2023, 2, 30);
} catch (DateTimeException e) {
    System.out.println("An invalid date was specified: " + e.getMessage());
}

Eccezioni Durante il Parsing di Stringhe

Quando si utilizza LocalDate.parse(), viene lanciata una DateTimeParseException se il formato della stringa è non valido o la data stessa non esiste.

import java.time.format.DateTimeParseException;

try {
    LocalDate date = LocalDate.parse("2023/02/30");
} catch (DateTimeParseException e) {
    System.out.println("Failed to parse date: " + e.getMessage());
}

Migliori Pratiche

• Validare i valori di input in anticipo Quando si accetta l’input dell’utente, validare sia il formato che il valore prima del parsing per prevenire eccezioni.
• Catturare le eccezioni e fornire messaggi user-friendly Invece di permettere all’applicazione di crashare, restituire messaggi di errore chiari e comprensibili all’utente.
• Sfruttare l’immutabilità Poiché LocalDate è immutabile, trattare sempre i risultati dei calcoli come nuove istanze piuttosto che sovrascrivere quelle esistenti.

Trappole Comuni

• Gestione del 29 febbraio negli anni bisestili
• Specificare valori al di fuori degli intervalli validi (ad es. mese = 13, giorno = 0)
• Formati non corrispondenti durante il parsing di stringhe

Questi problemi sono particolarmente comuni tra i principianti, quindi è richiesta un’attenzione extra.

Casi d’Uso Pratici per LocalDate

LocalDate non si limita allo storage semplice delle date—è ampiamente utilizzato in sistemi aziendali e applicazioni del mondo reale. Di seguito sono riportati diversi esempi pratici.

Calcolo del Compleanno e dell’Età

Calcolare l’età di una persona in base alla data di nascita è un caso d’uso classico. Utilizzare LocalDate insieme a Period rende questo facile.

import java.time.LocalDate;
import java.time.Period;

LocalDate birthDay = LocalDate.of(1990, 8, 15);
LocalDate today = LocalDate.now();

Period period = Period.between(birthDay, today);
int age = period.getYears();
System.out.println("Age: " + age);

Gestione delle Scadenze e delle Date di Scadenza

LocalDate è anche utile per i sistemi di gestione delle attività, come il calcolo di quanti giorni rimangono fino a una scadenza.

LocalDate deadline = LocalDate.of(2025, 7, 10);
long daysLeft =
    java.time.temporal.ChronoUnit.DAYS.between(today, deadline);

System.out.println("Days remaining until deadline: " + daysLeft);

Programmazione e Generazione del Calendario

Requisiti come “una riunione il secondo lunedì di ogni mese” possono essere implementati facilmente utilizzando TemporalAdjusters.

import java.time.DayOfWeek;
import java.time.temporal.TemporalAdjusters;

LocalDate secondMonday =
    LocalDate.of(2025, 7, 1)
        .with(TemporalAdjusters.dayOfWeekInMonth(2, DayOfWeek.MONDAY));

System.out.println("Second Monday of July: " + secondMonday);

Validazione delle Date nei Sistemi Web e API

LocalDate è frequentemente utilizzato nei sistemi backend per validare l’input delle date. Ad esempio, potresti voler rifiutare date future o date più vecchie di un certo intervallo.

LocalDate inputDate = LocalDate.parse("2024-12-31");
LocalDate tenYearsAgo = today.minusYears(10);

if (inputDate.isAfter(today)) {
    System.out.println("Le date future non sono consentite");
} else if (inputDate.isBefore(tenYearsAgo)) {
    System.out.println("Specifica una data entro gli ultimi 10 anni");
} else {
    System.out.println("La data è valida");
}

Adoption in Training and Production Systems

As seen in many competing articles, LocalDate is now a standard topic in Java training programs and onboarding curricula. It is also widely used in production systems such as banking business-day calculations and inventory management.

FAQ (Frequently Asked Questions)

Q1. What is the difference between LocalDate and Date?

A.
LocalDate is part of the modern Java Date and Time API introduced in Java 8 and represents only a date (year, month, day). java.util.Date, on the other hand, is a legacy class that includes time and internally manages values in milliseconds.

LocalDate is immutable, intuitive, and thread-safe, and is recommended for modern Java development.

Q2. Can LocalDate handle time zones?

A.
LocalDate itself does not contain time zone information. If time zone support is required, use ZonedDateTime or OffsetDateTime. A common approach is to manage dates with LocalDate first, then convert when time zones become necessary.

Q3. What is the difference between LocalDate and LocalDateTime?

A.
LocalDate represents only a date. LocalDateTime represents both date and time (e.g. 2025-06-26 14:00). Use LocalDate for deadlines or anniversaries, and LocalDateTime for events with precise timestamps.

Q4. Can I parse custom date formats?

A.
Yes. By using DateTimeFormatter, you can parse dates in custom formats.

import java.time.format.DateTimeFormatter;

DateTimeFormatter formatter =
    DateTimeFormatter.ofPattern("yyyy/MM/dd");
LocalDate date =
    LocalDate.parse("2025/06/26", formatter);

Q5. How should I handle invalid dates or formats?

A.
Invalid dates or formats cause exceptions such as DateTimeException or DateTimeParseException. Use try-catch blocks, validate input in advance, and provide clear error messages to users.

Q6. Can I compare two LocalDate instances?

A.
Yes. Use isAfter(), isBefore(), or isEqual().

LocalDate date1 = LocalDate.of(2025, 6, 26);
LocalDate date2 = LocalDate.of(2025, 7, 1);

if (date1.isBefore(date2)) {
    System.out.println("date1 è precedente a date2");
}

Conclusion

This article provided a comprehensive explanation of Java LocalDate, from basic concepts to advanced use cases. Key points include:

• What LocalDate is An immutable date-only object introduced in Java 8 that fixes the flaws of legacy Date and Calendar classes.
• Basic usage Retrieving the current date, creating specific dates, and parsing strings using simple APIs.
• Extracting components Easily retrieving year, month, day, and weekday values.
• Date calculations Intuitive addition, subtraction, and difference calculations.
• Date adjustments Using TemporalAdjusters to handle end-of-month, weekdays, and more.
• Integration with time APIs Flexible conversion between LocalDate, LocalDateTime, and LocalTime.
• Safe handling and best practices Proper exception handling and validation for robust systems.
• Real-world applications and FAQs Practical examples such as age calculation, deadlines, scheduling, and validation.

Next Steps

Once you master LocalDate, date handling becomes straightforward and reliable. For more advanced scenarios—such as time zones, period calculations, and formatting—consider learning ZonedDateTime, Period, and DateTimeFormatter.

Use LocalDate as a powerful foundation to build clean, robust, and maintainable Java applications.