Deserializer Discovery 2.x

Discovering POJO Deserializers in Jackson 2.x

This page describes the process of discovering JsonDeserializers for POJO (aka Bean) types in Jackson 2.x

General

JsonDeserializers are needed for reading JSON (and other supported formats) from JsonParser and constructing desired Java Objects. Discovery process is initiated by 3 entities:

1. ObjectMapper to locate deserializer to use for target type indicated for readValue() method (and readValues(), convertValue())
2. ObjectReader (similar to ObjectMapper)
3. Deserializers themselves, to locate "child deserializers": for example when deserializing Lists, deserializer for elements contained is separate from deserializer for List itself (and similarly for other structured types like java.util.Maps, Arrays, POJOs)

Discovery process for these cases is almost identical (and in fact, (1) and (2) are identical), differing only in that for (3), contextualization (via method DeserializationContext._handleSecondaryContextualization(...)) passes referring property definition (BeanProperty) whereas one does not exist for "root" values.

Deserializer Contextualization vs Resolution

Two terms for deserializers (as defined by ResolvableDeserializer and ContextualDeserializer) are:

1. Resolution is needed to handle cyclic dependencies between deserialializers: this is mostly relevant for BeanDeserializer.
2. Contextualization is needed to give initially context-free (only based on Type) deserializers access to annotations added to property (that is, on Field and/or Method and/or Constructor parameter).

Understanding this processing is not strictly necessary to understand call flow, but is useful to know since these are referenced in couple of places.

High-level call sequence

ObjectMapper to DeserializationContext

The first step to trigger discovery is ObjectMapper (and other entities mentioned earlier) calling one of:

1. Explicit findXxxDeserializer() method such as findRootValueDeserializer()
2. One of readXxxValue() convenience methods like readValue() which will need to call one of findXxxDeserializer() methods

Either way method like findRootValueDeserializer() is called; and this is the call path we will focus on.

DeserializationContext to DeserializerCache

Big part of actual discovery is handled by DeserializerCache: the main entry point is method findValueDeserializer(). It will not only handle caching of constructed and resolved (but not contextualized) deserializers but also:

1. Mapping of abstract Java types (as well as Map and Collection types) into concrete (for abstract) and default (Map, Collection) implementation types
2. Introspecting BeanDescription (of type BasicBeanDescription) for type indicated
3. Handling annotations on Java types (Classes) that directly indicate JsonDeserializer to use (@JsonDeserialize(using = IMPL_CLASS))
4. Refinement of actual type to use (@JsonDeserialize(as = CONCRETE_TYPE)); and re-introspecting BeanDescription for refined type
5. Use of "converting" deserializers indicated by annotation (and directly constructing StdDelegatingDeserializer as needed)
6. Calling appropriate method of configured DeserializerFactory to actually construct JsonDeserializer to use
7. Resolution of ResolveDeserializers, to avoid StackOverflowError for cyclic types (put another way: allowing use of cyclic type definitions)

and last but not least:

• Calling type-specific method in DeserializerFactory as necessary to actually construct deserializer.

DeserializerCache to DeserializerFactory

With given target JavaType and introspected BeanDescription, cache will call one of following methods of DeserializerFactory (selected in following order)

1. createEnumDeserializer() (if JavaType.isEnumType() returns true)
2. createArrayDeserializer() (JavaType.isArrayType())
3. createMapDeserializer()/createMapLikeDeserializer() ("Map-like" types refer to Scala (f.ex) types that act like java.util.Map but do not implement that interface)
4. createCollectionDeserializer()/createCollectionLikeDeserializer() ("Collection-like" types similarly refer to Scala's collection types that work similar to java.util.Collection but do not implement it)
5. createReferenceDeserializer() for types like AtomicReference<> (JDK), Optional (JDK 8+, Guava), Option (Scala)
6. createTreeDeserializer() for JsonNode (and subtypes)
7. createBeanDeserializer() if none of above matches

We will focus on the last case, in which general POJO (aka "Bean") deserializers are constructed.

DeserializerFactory

Actual DeserializerFactory used is BeanDeserializerFactory, which extends BasicDeserializerFactory (which implements DeserializerFactory except for createBeanDeserializer()).

Here we will focus on BeanDeserializerFactory.createBeanDeserializer() implementation.