Aprender Java API java.time

API java.time

La gestión del tiempo en aplicaciones Java ha experimentado una transformación significativa con la introducción de la API java.time en Java 8. Esta API moderna reemplaza las problemáticas clases Date y Calendar, ofreciendo un enfoque más intuitivo, seguro y funcional para trabajar con fechas, horas y períodos temporales.

Fundamentos de la nueva API temporal

La API java.time se basa en principios de inmutabilidad y claridad semántica. Todas las clases principales son inmutables, lo que significa que cualquier operación que modifique un objeto temporal devuelve una nueva instancia en lugar de alterar la original.

LocalDate fecha = LocalDate.of(2024, 3, 15);
LocalDate nuevaFecha = fecha.plusDays(10); // fecha original no cambia
System.out.println(fecha);      // 2024-03-15
System.out.println(nuevaFecha); // 2024-03-25

Esta característica elimina muchos errores comunes relacionados con la mutabilidad accidental y hace que el código sea más predecible y seguro en entornos concurrentes.

Clases principales para representación temporal

La API se organiza en torno a varias clases especializadas, cada una diseñada para casos de uso específicos:

LocalDate representa fechas sin información de hora ni zona horaria:

LocalDate hoy = LocalDate.now();
LocalDate cumpleanos = LocalDate.of(1990, Month.DECEMBER, 25);
LocalDate proximoLunes = LocalDate.now().with(TemporalAdjusters.next(DayOfWeek.MONDAY));

LocalTime maneja únicamente información horaria:

LocalTime ahora = LocalTime.now();
LocalTime reunion = LocalTime.of(14, 30, 0);
LocalTime mediaHoraAntes = reunion.minusMinutes(30);

LocalDateTime combina fecha y hora sin considerar zonas horarias:

LocalDateTime momento = LocalDateTime.now();
LocalDateTime evento = LocalDateTime.of(2024, 6, 15, 19, 30);
LocalDateTime inicioSemana = momento.with(TemporalAdjusters.previousOrSame(DayOfWeek.MONDAY))
                                   .withHour(0).withMinute(0).withSecond(0);

Trabajando con zonas horarias

Para aplicaciones que requieren conciencia de zona horaria, la API proporciona ZonedDateTime y OffsetDateTime:

ZonedDateTime madridTime = ZonedDateTime.now(ZoneId.of("Europe/Madrid"));
ZonedDateTime tokyoTime = madridTime.withZoneSameInstant(ZoneId.of("Asia/Tokyo"));

// Crear una fecha específica en una zona horaria
ZonedDateTime conferencia = ZonedDateTime.of(
    LocalDateTime.of(2024, 9, 20, 10, 0),
    ZoneId.of("America/New_York")
);

La diferencia entre ZonedDateTime y OffsetDateTime radica en que el primero mantiene información completa sobre la zona horaria (incluyendo reglas de horario de verano), mientras que el segundo solo almacena el desplazamiento fijo respecto a UTC.

Medición y cálculo de períodos temporales

La API distingue entre dos conceptos fundamentales para medir tiempo:

Period representa cantidades de tiempo en términos de años, meses y días:

Period edad = Period.between(LocalDate.of(1990, 5, 15), LocalDate.now());
System.out.println("Edad: " + edad.getYears() + " años, " + 
                   edad.getMonths() + " meses, " + 
                   edad.getDays() + " días");

LocalDate vencimiento = LocalDate.now().plus(Period.ofMonths(6));

Duration mide tiempo en términos de segundos y nanosegundos, ideal para intervalos precisos:

LocalTime inicio = LocalTime.of(9, 0);
LocalTime fin = LocalTime.of(17, 30);
Duration jornada = Duration.between(inicio, fin);

System.out.println("Horas trabajadas: " + jornada.toHours());
System.out.println("Minutos totales: " + jornada.toMinutes());

Formateo y parsing de fechas

La clase DateTimeFormatter proporciona capacidades avanzadas de formateo y análisis:

LocalDateTime momento = LocalDateTime.now();

// Formateo con patrones predefinidos
String iso = momento.format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);
String basico = momento.format(DateTimeFormatter.BASIC_ISO_DATE);

// Formateo personalizado
DateTimeFormatter formato = DateTimeFormatter.ofPattern("dd/MM/yyyy HH:mm");
String personalizado = momento.format(formato);

// Parsing desde string
LocalDate fechaParseada = LocalDate.parse("2024-12-25", DateTimeFormatter.ISO_LOCAL_DATE);
LocalDateTime momentoParseado = LocalDateTime.parse("15/03/2024 14:30", formato);

Operaciones avanzadas con TemporalAdjusters

Los TemporalAdjusters permiten realizar cálculos temporales complejos de manera elegante:

LocalDate hoy = LocalDate.now();

// Ajustadores predefinidos
LocalDate primerDiaMes = hoy.with(TemporalAdjusters.firstDayOfMonth());
LocalDate ultimoViernes = hoy.with(TemporalAdjusters.lastInMonth(DayOfWeek.FRIDAY));
LocalDate proximoAnio = hoy.with(TemporalAdjusters.firstDayOfNextYear());

// Ajustador personalizado para el próximo día laborable
TemporalAdjuster proximoDiaLaborable = temporal -> {
    LocalDate fecha = LocalDate.from(temporal);
    DayOfWeek dia = fecha.getDayOfWeek();
    
    if (dia == DayOfWeek.FRIDAY) {
        return fecha.plusDays(3); // Lunes
    } else if (dia == DayOfWeek.SATURDAY) {
        return fecha.plusDays(2); // Lunes
    } else {
        return fecha.plusDays(1); // Día siguiente
    }
};

LocalDate siguienteLaborable = hoy.with(proximoDiaLaborable);

La API java.time representa un salto cualitativo en el manejo temporal en Java, proporcionando herramientas robustas y expresivas que simplifican tareas complejas mientras mantienen la precisión y seguridad necesarias para aplicaciones profesionales.