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 It serves as the background/context for low-level POJO Property Introspection work.

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 findRootValueDeserializer() (or one of alternatives). 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, DeserializerCache 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") deserializer is constructed.

DeserializerFactory

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

Here we will focus on BeanDeserializerFactory.createBeanDeserializer() implementation: it will be covered later on in this document.

Detailed call path for constructing BeanDeserializer

High-level description has many branches off for different cases other than producing a standard POJO Deserializer (named BeanDeserializer for historic reasons). But let's focus on specific call path/sequence that results in a new BeanDeserializer

Entry: DeserializationContext.findRootValueDeserializer()

So when call is made like:

ObjectMapper mapper = new ObjectMapper();
MyValue value = mapper.readValue(jsonInput, MyValue.class);

we will get a call to DeserializationContext method findRootValueDeserializer(). This will call DeserializerCache.findValueDeserializer() which will try to locate a deserializer already created, and if failing to do so (which is the case the first time it gets called like above), proceed with discovery and construction of needed deserializer. After deserializer has been returned, it will be contextualized as necessary (by a call to ContextualDeserializer.createContextual() -- we will not be going through contextualization process here).

DeserializerCache.findValueDeserializer()

1. First thing done in this method is to look for already cached deserializers (see _findCachedDeserializer(); nothing special here).
2. Assuming no cached deserializer is found, method _createAndCacheValueDeserializer() is called
   • _createAndCacheValueDeserializer() handles synchronization aspects (by keeping track of in-process deserializers in its _incompleteDeserializers Map), but it calls _createAndCache2() for further processing.
3. _createAndCache2() will:
   • delegate actual construction further to _createDeserializer() (which is covered in next section)
   • trigger deserializer (dependency) resolution if deserializer implements ResolvableDeserializer (in which case its resolve() method is called)
   • add deserializer into _cachedDeserializers if (but only if!) it is eligible for caching

DeserializerCache._createDeserializer()

This is where most of the magic is found:

1. First, abstract and Collection and Map types are mapped (to "concrete" and "default" types, respectively)
2. Once we have likely type to use, BeanDescription is obtained via Property Introspection through DeserializationConfig.introspect(JavaType) method (which in turn calls ClassIntrospector.forDeserialization() method)
   • !!! This is where Property Introspection occurs !!!
   • Actual implementation type will be BasicBeanDescription
   • See the next section, "Detailed call path for [Basic]BeanDescription introspection" for details
3. Once we have BeanDescription, we check if a Class-Annotated deserializer is found (by call to findDeserializerFromAnnotation()) and if so, create instance and return it. Check is made by a call to
   • Annotation checked is @JsonDeserialize(using = DESER_IMPL.class), but lookup is via configured AnnotationIntrospector
4. Otherwise annotations are checked to see if type mapping is needed (from more generic to more specialized type), via call to modifyTypeByAnnotation()
   • Annotation check is @JsonDeserialize(as = SUBTYPE.class), via AnnotationIntrospector.refineDeserializationType() (which can refine main type itself as well as Content/Element types for Collection and Map types; as well as Key type for Maps)
   • If type refinement (to more specific type) occurs, Property Introspection needs to be re-done for the new type -- that is, a new BeanDescription is introspected.
5. Check is made to see if we have Builder-style deserializer (@JsonDeserialize(builder = BUILDER_IMPL.class))
   • Check is via BeanDescription.findPOJOBuilder()
   • If builder-style construction found, DeserializerFactory.createBuilderBasedDeserializer() is called to construct deserializer
6. If none found so far, check is made (via BeanDescription.findDeserializationConverter()) to see if @JsonDeserialize(converter = CONVERTER_IMPL.class) is found; if so, a StdConvertingDeserializer is constructed and returned
7. Otherwise, if none of above results in a JsonDeserializer being constructed, _createDeserializer2() is called.

DeserializerCache._createDeserializer2()

This method will create "regular" deserializers of 3 main types:

1. Module-provided deserializers (both shared 3rd party modules and application-provided "custom" modules)
2. Standard JDK type deserializers like StringDeserializer and ObjectArrayDeserializer
3. POJO (aka Bean) deserializers (BeanDeserializer)

Construction is delegated to DeserializerFactory (API), implementation of which is BeanDeserializerFactory (which extends BasicDeserializerFactory, which implements most of DeserializerFactory).

Factory methods in DeserializerFactory and callback methods in Deserializers (API provided by Modules to provide custom deserializers) are divided into in about 10 different types. Specifically, DeserializerFactory exposes following methods to call, checked in specified order:

• createEnumDeserializer() (if target type's JavaType.isEnumType() returns true)
• createArrayDeserializer() (JavaType.isArrayType())
• createMapDeserializer() / createMapLikeDeserializer() (for true java.util.Map types / "Map-like" type such as Scala Maps that work like Maps but do not implement java.util.Map)
• createCollectionDeserializer() / createCollectionLikeDeserializer() (for true java.util.Collection / "Collection-like", for Scala Collections etc)
• createReferenceDeserializer() (JavaType.isReferenceType(): true for JDK AtomicReference, JDK8+/Guava Optional, Scala Option)
• createTreeDeserializer() (for JsonNode and its subtypes)
• createBeanDeserializer() for everything else

Of these, all but last method are implemented by BasicDeserializerFactory: the last method is implemented by BeanDeserializerFactory.

DeserializerFactory.createXxxDeserializer()

DeserializerFactory is configured with access to callbacks Modules implement to provide custom deserializer implementations (this is case (1)); mapping to standard JDK type deserializers (case (2)); and method for actually construction BeanDeserializers otherwise (case (3)).

Processing for all createXxxDeserializer() methods consists of following sequence:

1. Check if there is Module-provided implementation (by calling matching callback method via Deserializers modules registers with DeserializerFactory); if so, return
2. (for Structured types like Arrays, Collection (and "CollectionLike"), Map (and "MapLike")) Discover content type, fetch content deserializer if available (via annotations, or static type) -- if not, will be left for Contextualization to provide
3. Construct Standard deserializer
4. Allow Modules to modify resulting deserializer via registered BeanDeserializerModifier: type-dependant method like modifyEnumDeserializer() is called after constructing deserializer with a call to createEnumDeserializer() and so on.

BeanDeserializerFactory.createBeanDeserializer()

Of all actual factory methods -- all but one of which is defined in BasicDeserializerFactory, the most interesting is createBeanDeserializer() (defined in BeanDeserializerFactory). It uses all information contained in [Basic]BeanDescription to figure out exact details of how to deserialize contents of the matching POJO type (class); this, most importantly, contains a POJOPropertiesCollector to access everything relevant EXCEPT NOT Creator definitions!

With that, the logic of createBeanDeserializer() is the same for all other createXxxDeserializer() methods (as explained above), with some additions. So:

1. Check if a module provides custom deserializer (method _findCustomBeanDeserializer() which calls Modules registered deserializers via Deserializers.findBeanDeserializer()): if so, apply BeanDeserializerModifier(s) (if any), return
2. If no custom deserializer found, and target type is Throwable (or subtype), call buildThrowableDeserializer() to construct specialized variant of BeanDeserializer
3. Otherwise if target type is abstract, call materializeAbstractType() which may provide deserializer (typically by one of registered modules such as MrBeanModule)
4. If no deserializer found yet, see if one of "standard" deserializers -- ones handling recognized JDK/Jackson types (other than Enum/Array/Collection(Like)/Map(Like) types that are handled by different factory methods) -- and if so, construct one
5. Verify that we have valid POJO type (isPotentialBeanType()); if not, return null
6. Validate safety aspects wrt polymorphic handling (_validateSubType())
7. If no implementation found yet and its valid case, call buildBeanDeserializer() for actual construction.

BeanDeserializerFactory.buildBeanDeserializer() (line ~250)

1. Find ValueInstantiator with findValueInstantiator() -- from annotations if any, otherwise call BasicDeserializerFactory._constructDefaultValueInstantiator()
   • !!! This is where Creator-handling is invoked !!!
2. Create a BeanDeserializerBuilder with call to constructBeanDeserializerBuilder() (default impl simply creates one with BeanDescription and DeserializationContext)
3. Add properties to builder with addBeanProps()
4. Build actual BeanDeserializer by calling BeanDeserializerBuilder.build() (or .buildAbstract())

BasicDeserializerFactory._constructDefaultValueInstantiator() (line ~250)

This is finally where we start collection Creators (constructors and factory methods).

---

Detailed call path for [Basic]BeanDescription introspection

BasicClassIntrospector actions

So, createDeserializer() method calls DeserializationConfig.introspect(JavaType) method: this in turn calls BasicClassIntrospector.forDeserialization()`:

1. First, a special set of "simple" set of well-known types (primitive int, long, Bolean; matching wrappers; String, Jackson JsonNode) is checked with _findStdTypeDesc(); if matching return pre-resolved description
2. If not found, _findStdJdkCollectionDesc() will handle minimal resolution for simple Collection types like List
3. In the usual case -- and in particular, general purpose POJOs, method collectProperties() is called.

BasicClassIntrospector.collectProperties():

1. First gets AnnotatedClass via _resolveAnnotatedClass() which simply calls AnnotatedClassResolver.resolve(config, type, r) -- which in turn constructs AnnotatedClassResolver and calls resolveFully on it. This does annotation introspection and applies mix-in overlays, if any.
2. Then it gets appropriate AccessorNamingStrategy, depending on whether type is a Record or not (Records do not use get or set prefixes, typically
3. With these, a POJOPropertiesCollector is constructed via helper method constructPropertyCollector().

POJOPropertiesCollector actions

Upon construction, collector is initialized with AnnotatedClass, for access to annotated Class, Methods, Fields and Constructors; as well as basic configuration (MapperConfig, JavaType, AccessorNamingStrategy). But actual resolution of logical properties is done lazily: most commonly when POJOPropertiesCollector.getProperties() is called.