HOWTO · Java

Fecha de Java frente a LocalDate

Este tutorial demuestra la diferencia entre fecha y fecha local en Java.

En esta página

Date y LocalDate representan conceptos distintos en Java. Date representa un instante en la línea de tiempo con precisión de milisegundos. LocalDate representa una fecha de calendario, como un cumpleaños, sin hora ni zona horaria. Elige según si el valor representa un momento o un día del calendario.

Date frente a LocalDate en Java

java.util.Date es un tipo heredado. El valor almacenado identifica un instante; no almacena una zona horaria de calendario. Al formatearlo o convertirlo en campos de calendario, ese instante se interpreta con una zona horaria elegida, a menudo la predeterminada del sistema. Por eso, el día mostrado puede variar según la zona.

java.time.LocalDate pertenece al paquete java.time. Es inmutable y contiene los campos de año, mes y día, pero no incluye hora, desplazamiento ni zona. Por sí solo, no puede identificar un momento único. Sumar o restar días devuelve un nuevo LocalDate en lugar de modificar el valor original.

Aspecto java.util.Date java.time.LocalDate
Significado Un instante en la línea de tiempo Una fecha de calendario
Zona horaria No se almacena; elige una zona al convertir o mostrar el valor Ninguna; no identifica un instante
Precisión Milisegundos Días completos
Mutabilidad Mutable Inmutable
Uso habitual Interoperabilidad con API que requieren Date Cumpleaños, fechas límite y otros valores que solo representan una fecha

A pesar de su nombre, Date no es un tipo que represente solo una fecha. Para un evento programado en un momento concreto, usa un tipo que represente un instante y aplica una zona al mostrarlo. Para una fecha empresarial que deba mantenerse igual sin importar dónde se encuentre quien la consulta, usa LocalDate.

Uso de Date con API heredadas

Es posible que algunas bibliotecas e interfaces existentes todavía acepten o devuelvan java.util.Date. Conserva ese tipo en el límite de compatibilidad y usa Instant para expresar explícitamente su significado en la línea de tiempo. Date.toInstant() y Date.from(Instant) permiten convertir entre el tipo heredado y la API moderna de fecha y hora.

Ejecuta este ejemplo:

El código y las etiquetas o salidas visibles de esta sección se mantienen en inglés.

import java.time.Instant;
import java.time.LocalDate;
import java.time.ZoneId;
import java.util.Date;

public class Main {
  public static void main(String[] args) {
    Date legacyDate = Date.from(Instant.parse("2024-03-10T00:30:00Z"));
    Instant instant = legacyDate.toInstant();
    LocalDate dateInNewYork = instant.atZone(ZoneId.of("America/New_York")).toLocalDate();
    System.out.println("Instant: " + instant);
    System.out.println("New York date: " + dateInNewYork);
  }
}
Instant: 2024-03-10T00:30:00Z
New York date: 2024-03-09

Este programa parte de un instante fijo, lo convierte a Date para usarlo con una API heredada y luego vuelve a convertirlo a Instant. Al aplicar la zona de Nueva York se determina la fecha de calendario correspondiente a esa ubicación. Estos son los resultados de la ejecución proporcionada.

No supongas que Date conserva la zona usada para mostrarlo: el mismo instante puede corresponder a fechas locales distintas en zonas diferentes. Al adaptar una API existente, especifica la zona de conversión siempre que necesites una fecha de calendario.

Creación y uso de LocalDate

Usa LocalDate.now() para obtener la fecha actual en la zona predeterminada del sistema, o pasa un ZoneId si la aplicación necesita la fecha de una ubicación concreta. La zona determina qué fecha de calendario se devuelve; el LocalDate resultante no conserva esa zona. Usa LocalDate.of(year, month, day) para una fecha conocida. También puedes usar ofEpochDay y ofYearDay cuando la entrada se expresa como el número de días desde la época o como el día del año.

Ejecuta este ejemplo:

El código y las etiquetas o salidas visibles de esta sección se mantienen en inglés.

import java.time.LocalDate;
import java.time.Month;
import java.time.ZoneId;

public class Main {
  public static void main(String[] args) {
    LocalDate todayInTokyo = LocalDate.now(ZoneId.of("Asia/Tokyo"));
    LocalDate dueDate = LocalDate.of(2025, Month.JANUARY, 15);
    LocalDate epochDay = LocalDate.ofEpochDay(300);
    LocalDate hundredthDay = LocalDate.ofYearDay(2024, 100);
    System.out.println("Tokyo date: " + todayInTokyo);
    System.out.println("Due date: " + dueDate);
    System.out.println("Epoch day 300: " + epochDay);
    System.out.println("Day 100 of 2024: " + hundredthDay);
  }
}
Tokyo date: 2026-11-04
Due date: 2025-01-15
Epoch day 300: 1970-10-28
Day 100 of 2024: 2024-04-09

LocalDate.now(ZoneId) es una forma válida de obtener la fecha en la zona proporcionada. Resulta útil cuando un servicio funciona con una zona empresarial que puede diferir de la zona predeterminada de la máquina. Una fecha creada con of es explícita y estable, mientras que now depende del reloj y de la zona en tiempo de ejecución. La fecha de Tokio que se muestra arriba corresponde a la línea de fecha actual de la ejecución proporcionada.

Cómo elegir entre Date y LocalDate

Usa LocalDate cuando el valor sea una fecha de calendario sin una hora significativa, como un cumpleaños, una fecha de facturación o una fecha límite. Usa un tipo que represente un instante cuando el valor indique cuándo ocurrió algo. Convierte ese instante mediante un ZoneId explícito cuando necesites la fecha o la hora local de un lugar concreto.

Conserva Date cuando una API heredada lo requiera y realiza la conversión en el límite, en lugar de usarlo como representación principal para la nueva lógica que maneja fechas sin hora. En resumen: LocalDate para un día del calendario, un tipo que represente un instante para un momento y Date para la compatibilidad con interfaces antiguas.