Accueil › Java › L'API java.time
L'API java.time
Dates, texte et formatsintermediaire
java.util.Date et java.util.Calendar sont mutables, indexent les mois à partir de 0 (janvier = 0) et exposent une API confuse (Date mélange date et heure sans fuseau clair, Calendar demande des constantes peu lisibles). Elles ne sont pas dépréciées ni promises à la suppression, mais sont supplantées depuis Java 8 par java.time (JSR-310) : tout nouveau code doit utiliser java.time.
Les types principaux, tous immuables (une opération comme plusDays renvoie une nouvelle instance, sans jamais modifier l'original) :
LocalDate dateCommande = LocalDate.of(2026, 3, 10);
LocalDate dateLivraison = dateCommande.plusDays(5); // nouvelle instance, dateCommande inchangée
LocalDateTime horodatage = LocalDateTime.of(dateCommande, LocalTime.of(14, 30));
ZonedDateTime rdv = ZonedDateTime.of(horodatage, ZoneId.of("Europe/Paris"));
Instant maintenant = Instant.now(); // instant UTC, pour horodater un événement
Duration attente = Duration.ofMinutes(30);
Period delaiLivraison = Period.ofDays(5);
LocalDate/LocalTime/LocalDateTime n'ont pas de fuseau : pratiques pour une date calendaire, insuffisantes dès qu'on compare des événements produits dans des fuseaux différents — utiliser alors ZonedDateTime (fuseau complet, avec ses règles d'heure d'été) ou OffsetDateTime (simple décalage fixe).
Les termes à connaître
- LocalDate
Date calendaire sans heure ni fuseau horaire (une année, un mois, un jour). Convient pour une date de naissance, une date de commande sans notion d'instant précis, une échéance.
- LocalDateTime
Date et heure, toujours sans fuseau horaire. Utile pour un affichage local ou un calcul purement calendaire, mais ambiguë dès qu'on doit comparer des événements produits dans des fuseaux différents.
- ZonedDateTime
Date, heure et fuseau horaire complet (
ZoneId, ex.Europe/Paris), avec les règles de passage à l'heure d'été. Le bon type pour représenter « le rendez-vous du 14 mars à 10h à Paris ».- Instant
Point précis sur la ligne du temps, exprimé en secondes (et nanosecondes) depuis l'epoch UTC (1er janvier 1970). Ne connaît ni fuseau ni calendrier : c'est le bon type pour horodater un événement et le stocker en base.
- Duration
Quantité de temps basée sur des secondes/nanosecondes (heures, minutes, secondes) :
Duration.ofMinutes(30). S'utilise avec les types qui portent une heure (Instant,LocalDateTime,ZonedDateTime).- Period
Quantité de temps basée sur le calendrier (années, mois, jours) :
Period.ofDays(5). S'utilise avec les types purement calendaires (LocalDate) ; mélangerDurationetLocalDatelève une exception à l'exécution.- ZoneId
Identifiant d'un fuseau horaire avec ses règles historiques et ses transitions d'heure d'été, par exemple
ZoneId.of("Europe/Paris"). À distinguer d'un simple décalage fixe (ZoneOffset, ex.+01:00), qui ne suit pas les changements d'heure.- Clock
Source du temps courant, injectable à la place d'un appel direct à
now(). Permet de fixer une horloge de test (Clock.fixed(...)) pour rendre le code qui dépend de la date/heure testable de façon déterministe.
Cette page présente la partie essentielle de la leçon. Les exemples commentés, les pièges courants et les trois questions de quiz sont dans l'application.