DateTime adapters

The standard defines different types for representing date and time elements. For some of them multiple options are compliant for their string representation in the XML. To accommodate the flexibility and variability in representing date and time elements as per ISO standards and specific usage guidelines, the library employs type adapters.

The Java model is annotated with generic type adapters, allowing multiple implementation options for marshalling and unmarshalling the different date and time values.

Default Adapters

The default implementations of these type adapters are designed to handle the most common cases. These default adapters ensure that date and time elements are serialized and deserialized in a manner that aligns with ISO conventions.

For example, the default implementation for IsoDateTimeAdapter ensures that date-time values are represented as local time with a UTC offset in the format YYYY-MM-DDThh:mm:ss[.sss]+/-hh:mm. Similarly, the IsoDateAdapter handles date values in the format YYY-MM-DD, and the IsoTimeAdapter manages time values in the format hh:mm:ss[.sss]+/-hh:mm.

This implementation by default will replace the Zulu indicator Z with the +00:00 offset, and will also trim meaningless zeros in the fractional seconds. However, you can customize this behavior by providing your own adapter.

Customization for Specific Use Cases

While the default adapters cover a wide range of scenarios, there may be cases where you need to tailor the serialization and/or deserialization of date and time elements to meet specific requirements. In such situations, the library allows you to override or replace the default adapters with your custom implementations.

By creating custom adapters, you can precisely control how date and time values are represented in XML. This customization is particularly valuable when your XML documents need to adhere to specific standards or conventions that deviate from the default representations.

The TypeAdaptersConfiguration holder DTO is used to set up a collection of adapters. This configuration is then used by the MxWriteConfiguration and MxReadConfiguration to set up the adapters in the JaxbContext.

There are many ways to create custom adapters by just implementing the XmlAdapter interface.

The following example leverage the default adapters to create custom adapters that preserve the default behavior but add additional customization with a simple string replace to preserve the Zulu indicator Z for offset date times in UTC.

    public class CustomDateTimeAdapter extends OffsetDateTimeAdapter {
        @Override
        public String marshal(OffsetDateTime offsetDateTime) throws Exception {
            return StringUtils.replace(super.marshal(offsetDateTime), "+00:00", "Z");
        }
    }

The custom implementation can then be passed to the MxWriteConfiguration to override the default adapter.

    MxWriteConfiguration config = new MxWriteConfiguration();
    config.adapters.dateTimeAdapter = new IsoDateTimeAdapter(new CustomDateTimeAdapter());
    xml = mx.message(config);