Package com.fasterxml.jackson.datatype.jsr310

Class JavaTimeModule

  • All Implemented Interfaces:
    Versioned, java.io.Serializable
    public final class JavaTimeModule
extends SimpleModule
    Class that registers capability of serializing java.time objects with the Jackson core. 
     ObjectMapper mapper = new ObjectMapper();
 mapper.registerModule(new JavaTimeModule());

    Note that as of 2.x, if auto-registering modules, this package will register legacy version, JSR310Module, and NOT this module. 3.x will change the default. Legacy version has the same functionality, but slightly different default configuration: see JSR310Module for details.

    Most java.time types are serialized as numbers (integers or decimals as appropriate) if the SerializationFeature.WRITE_DATES_AS_TIMESTAMPS feature is enabled (or, for Duration, SerializationFeature.WRITE_DURATIONS_AS_TIMESTAMPS), and otherwise are serialized in standard ISO-8601 string representation. ISO-8601 specifies formats for representing offset dates and times, zoned dates and times, local dates and times, periods, durations, zones, and more. All java.time types have built-in translation to and from ISO-8601 formats.

    Granularity of timestamps is controlled through the companion features SerializationFeature.WRITE_DATE_TIMESTAMPS_AS_NANOSECONDS and DeserializationFeature.READ_DATE_TIMESTAMPS_AS_NANOSECONDS. For serialization, timestamps are written as fractional numbers (decimals), where the number is seconds and the decimal is fractional seconds, if WRITE_DATE_TIMESTAMPS_AS_NANOSECONDS is enabled (it is by default), with resolution as fine as nanoseconds depending on the underlying JDK implementation. If WRITE_DATE_TIMESTAMPS_AS_NANOSECONDS is disabled, timestamps are written as a whole number of milliseconds. At deserialization time, decimal numbers are always read as fractional second timestamps with up-to-nanosecond resolution, since the meaning of the decimal is unambiguous. The more ambiguous integer types are read as fractional seconds without a decimal point if READ_DATE_TIMESTAMPS_AS_NANOSECONDS is enabled (it is by default), and otherwise they are read as milliseconds.

    Some exceptions to this standard serialization/deserialization rule:

    • Period, which always results in an ISO-8601 format because Periods must be represented in years, months, and/or days.
    • Year, which only contains a year and cannot be represented with a timestamp.
    • YearMonth, which only contains a year and a month and cannot be represented with a timestamp.
    • MonthDay, which only contains a month and a day and cannot be represented with a timestamp.
    • ZoneId and ZoneOffset, which do not actually store dates and times but are supported with this module nonetheless.
    • LocalDate, LocalTime, LocalDateTime, and OffsetTime, which cannot portably be converted to timestamps and are instead represented as arrays when WRITE_DATES_AS_TIMESTAMPS is enabled.
    Since:
    2.6
    See Also:
    Jsr310NullKeySerializer, Serialized Form

    • Constructor Detail

      • JavaTimeModule

        public JavaTimeModule()

    • Method Detail

      • setupModule

        public void setupModule​(Module.SetupContext context)
        Description copied from class: SimpleModule
        Standard implementation handles registration of all configured customizations: it is important that sub-classes call this implementation (usually before additional custom logic) if they choose to override it; otherwise customizations will not be registered.
        Overrides:
        setupModule in class SimpleModule