...
Note: a ZonedDateTimeAttributeConverter has already been implemented in the Reference Data Service for use. This converts between ZonedDateTime and java.sql.Timestamp. However, the instant date fields that are of type ZonedDateTime will also need a JPA annotation to explicitly define the column as "timestamp with time zone". See https://github.com/OpenLMIS/openlmis-referencedata/blob/master/src/main/java/org/openlmis/referencedata/domain/SupportedProgram.java's startDate field for an example.
API Interface
When exposing During serialization (returning dates through the API), they dates should be serialized into a String first. This is because when Jackson serializes date classes, it turns it them into an array of values, which is not as useful or readable. The serialized String should be in an ISO-8601 format.
During deserialization (when dates are provided by a client to an API call), instant dates should have timezone information added. Because we cannot depend on clients (browsers) to understand complex timezone scenarios (sending a date in UTC that’s for a facility in UTC+1 for a browser that’s in Seattle running UTC-8), we should assume that instant dates are passed in without timezones and the backend code will do a timezone "translation". Rough steps for this translation:
- Get the timestamp from the client
- Ignore/strip any timezone information
- Make a "best guess" about the timezone to use
- If the API call is respective to a user, use the timezone in the user's profile
- If respective to a facility, use the facility's timezone
- If neither, may have an implementation default timezone (although this may not work with an implementation that spans multiple timezones)
- Append the "best guess" timezone to the timestamp and use that in the backend and database
General dates should be in ISO-8601 format, deserialize into a LocalDate object properly and should be left alone.
Survey of Usage
Places where dates and times are being used currently (as of 2016-12-19 / 2016-12-20):
...