- Status: accepted
- Deciders: CAN, FAR, PIO, VHA, VME
- Date: 2026-03-10
The Scala and Java backend of the webapp have been using Joda-Time and its DateTime class for handling of dates and as common data type for representation of date and time.
But since Java SE 8 (JSR-310), the Joda-Time library is a no longer viable project, and it is explicitly stated that users are asked to migrate away from it, in favor of the API in the standard Java library : java.time.
The Java date and time API is quite rich, there are several classes that could be used instead of the DateTime one from Joda-Time : Instant, LocalDateTime, OffsetDateTime, ZonedDateTime.
Since ADR #28227, we should represent date and times in UTC in most parts of the webapp, which is possible with all of those classes, but is always enforced with Instant (which is a timestamp that is naturally expressed in the UTC timezone). We also most often do not have the need to keep timezone or offset information, but need an exact moment for computation, which is satisfied by the Instant class. But the Instant is not suited for computations of days or months because it has no concepts of DST and calendar, so in this case LocalDateTime is more suited.
Some storage components of the webapp are low-level and have are some constraint on time representation :
- in PostgreSQL, we always use the timestamp with timezone column type ; since we use the doobie library which has some support for the Java API, for instance the
Instantclass can be used for that, - in LDAP, the "generalized time" type defined in RFC 4517 is the low-level representation ; we use the unboundid-ldapsdk library which also has support for some of the Java API, we already have a dedicated class for
GeneralizedTime.
Since the aforementionned ADR, we should format dates into a RFC 3339-comptatible format and with Z offset. The DateTimeFormatter#ISO_INSTANT and DateTimeFormatter#ISO_OFFSET_DATE_TIME from the Java API satisfy that need, especially when used with the Instant class for the UTC offset.
- Mainly use the
Instantclass to represent date and time, but :- in case where computation in units of days and above is needed, use
LocalDateTimelocally - in case where the timezone is needed, keep the timezone in the context (e.g. in another class field), in preference to using the
ZonedDateTime
- in case where computation in units of days and above is needed, use
- In storage components :
- for LDAP, use the dedicated
GeneralizedTime - for PostgreSQL, use the existing bindings :
import doobie.postgres.implicits.*
- for LDAP, use the dedicated
- For serialisation, use
ISO_INSTANTorISO_OFFSET_DATE_TIMEto comply with ADR #28227, by using the dedicatedDateFormaterService
- We will need to migrate usage of joda-time to be replaced with equivalent usage with Java API to follow this ADR, namely replacing most
org.joda.time.DateTimewithjava.time.Instant