JSTEP 7

(Back to JSTEP page)

New DataTypeFeature configuration options (Jackson 2.x)

Related change issues: JSTEP-3 contains/-ed aspects of JsonNodeFeature

Author

Tatu Saloranta (@cowtowncoder)

Version history

• 2022-01-16: The first draft version

Background

Over time, various XxxFeature on/off options have proven useful and popular with developers: they are easy to set, change and (for the most part), understand.

Original set of "Features" were configurable at Streaming API and Databind level, including:

• JsonParser.Feature / JsonGenerator.Feature / JsonFactory.Feature for Streaming API
• MapperFeature / SerializationFeature / DeserializationFeature for databind

and for Streaming API, further split of format-specific (often JSON-specific) vs. generic (across all or most formats) features, resulted in:

• JsonParser.Feature split into generic StreamReadFeature and XxxReadFeature (like JsonReadFeature)
• JsonGenerator.Feature split into generic StreamWriteFeature and XxxWriteFeature (like JsonWriteFeature).

But while this split allowed better support for Format-specific features (via Streaming API), there is no similar mechanism for more granular configuration for datatype-specific features. This has lead to inclusion of some "too [datatype] specific" features at databind level; for example:

• DeserializationFeature.READ_ENUMS_USING_TO_STRING
• DeserializationFeature.READ_DATE_TIMESTAMPS_AS_NANOSECONDS
• SerializationFeature.WRITE_DATES_AS_TIMESTAMPS

Such configuration is against the idea that these Features should be cross-cutting across dataformats AND datatypes. But it is worth noting that there is need for such configuration, at some other granularity. This lead to the idea of "datatype-specific" features, to cover up to 3 initial datatypes:

1. JsonNode (Tree Model) configuration -- since it differs a lot from POJO configuration, and is difficult to configure
2. Enum configuration -- a few entries already leaked into generic features, and a few configuration aspects missing
3. Date/Time configuration -- similar to Enums, some configurability exists in general features, as well as via @JsonFormat, but there's need for more.

Approach

There are a few things to consider with respect to the general idea. For example:

• Would a single DataTypeFeature enum suffice? Based on having multiple general "datatypes", settings, not really.
  • So, need multiple concrete Feature Enums
  • But would like to avoid need to add all relevant plumbing -- would prefer general-purpose extension mechanism
• How similar should configuration interface (API) be compared to, say, DeserializationFeature?
  • Seems like usage should be very similar, perhaps almost identical
  • Possible to implement if we make DataTypeFeature an interface that actual Feature enum implements
• Do these features need to be per-call, or per-mapper?
  • Since some of the settings should be per-call, it seems necessary to make them ALL per-call
  • Needs to be considered when adding new feature entries: should adding Features that do not work on per-call scope
• Should we support pluggable, per-datatype-module way of adding DataTypeFeatures?
  • Ideally that would be great, but coordination of new types seems difficult (depending on mechanism)
  • Would likely lead to worse issues wrt. cross-version (different minor version between Datatype and Core modules)
  • At least initially the plan is NOT to support anything other than DataTypeFeatures defined by Databind module itself

So, to summarize:

1. We would have DataTypeFeature general interface for each actual feature (say, JsonNodeFeature) to implement: this interface mostly exists to keep Databind API simple and does not affect users directly (no functionality to access through it)
2. There will be multiple Enum subtypes of DataTypeFeature, and more can (and likely will) be added over future Jackson versions
3. Datatype Modules cannot define additional subtypes: these features will relate to either somewhat abstract/general types (Date/Time), or JDK- (Enum) and Jackson-specific (JsonNode) types