Top Description Fields Constructors Methods
com.fasterxml.jackson.databind.deser

public abstract Class DeserializationProblemHandler

extends Object
Class Inheritance
Imports
java.io.IOException, com.fasterxml.jackson.core.JsonParser, .JsonToken, com.fasterxml.jackson.databind.DeserializationConfig, .DeserializationContext, .JavaType, .JsonDeserializer, .ObjectMapper, com.fasterxml.jackson.databind.jsontype.TypeIdResolver

This is the class that can be registered (via DeserializationConfig object owner by ObjectMapper) to get called when a potentially recoverable problem is encountered during deserialization process. Handlers can try to resolve the problem, throw an exception or just skip the content.

Default implementations for all methods implemented minimal "do nothing" functionality, which is roughly equivalent to not having a registered listener at all. This allows for only implemented handler methods one is interested in, without handling other cases.

Note

it is typically NOT acceptable to simply do nothing, because this will result in unprocessed tokens being left in token stream (read via JsonParser, in case a structured (JSON Object or JSON Array) value is being pointed to by parser.

Field Summary

Modifier and TypeField and Description
public static final Object
NOT_HANDLED

Marker value returned by some handler methods to indicate that they could not handle problem and produce replacement value.

Constructor Summary

AccessConstructor and Description
public

Method Summary

Modifier and TypeMethod and Description
public Object

Returns:

Either NOT_HANDLED to indicate that handler does not know what to do (and exception may be thrown), or value to use (possibly null
handleInstantiationProblem
(DeserializationContext ctxt, Class<?>
Type that was to be instantiated
instClass
,
Object
(optional) Additional argument that was passed to creator, if any
argument
,
Throwable
Exception that caused instantiation failure
t
)

Method called when instance creation for a type fails due to an exception.

public Object

Returns:

Either NOT_HANDLED to indicate that handler does not know what to do (and exception may be thrown), or value to use (possibly null
handleMissingInstantiator
(DeserializationContext ctxt, Class<?>
Type that was to be instantiated
instClass
,
ValueInstantiator valueInsta, JsonParser
Parser to use for accessing content that needs handling, to either use it or skip it (latter with JsonParser#skipChildren().
p
,
String msg)

Method called when instance creation for a type fails due to lack of an instantiator.

public Object
handleMissingInstantiator(DeserializationContext ctxt, Class<?> instClass, JsonParser p, String msg)
Deprecated Since 2.9: use variant that takes ValueInstantiator

public JavaType

Returns:

Actual type to use, if resolved; `null` if handler does not know what to do; or `Void.class` to indicate that nothing should be deserialized for type with the id (which caller may choose to do... or not)
handleMissingTypeId
(DeserializationContext
Deserialization context to use for accessing information or constructing exception to throw
ctxt
,
JavaType
Base type to use for resolving subtype id
baseType
,
TypeIdResolver idResolver, String
Informational message that would be thrown as part of exception, if resolution still fails
failureMsg
)

Handler method called if an expected type id for a polymorphic value is not found and no "default type" is specified or allowed.

public Object
public Object

Returns:

Either NOT_HANDLED to indicate that handler does not know what to do (and exception may be thrown), or value to use (possibly null
handleUnexpectedToken
(DeserializationContext ctxt, JavaType targetType, JsonToken t, JsonParser p, String
Message that will be used by caller to indicate type of failure unless handler produces value to use
failureMsg
)

Method that deserializers should call if the first token of the value to deserialize is of unexpected type (that is, type of token that deserializer cannot handle).

public boolean

Returns:

True if the problem is resolved (and content available used or skipped); false if the handler did not anything and the problem is unresolved. Note that in latter case caller will either throw an exception or explicitly skip the content, depending on configuration.
handleUnknownProperty
(DeserializationContext ctxt, JsonParser
Parser to use for handling problematic content
p
,
JsonDeserializer<?> deserializer, Object
Either bean instance being deserialized (if one has been instantiated so far); or Class that indicates type that will be instantiated (if no instantiation done yet: for example when bean uses non-default constructors)
beanOrClass
,
String propertyName)

Method called when a JSON Object property with an unrecognized name is encountered.

public JavaType

Returns:

Actual type to use, if resolved; `null` if handler does not know what to do; or `Void.class` to indicate that nothing should be deserialized for type with the id (which caller may choose to do... or not)
handleUnknownTypeId
(DeserializationContext
Deserialization context to use for accessing information or constructing exception to throw
ctxt
,
JavaType
Base type to use for resolving subtype id
baseType
,
String
Subtype id that failed to resolve
subTypeId
,
TypeIdResolver idResolver, String
Informational message that would be thrown as part of exception, if resolution still fails
failureMsg
)

Handler method called if resolution of type id from given String failed to produce a subtype; usually because logical id is not mapped to actual implementation class.

public Object

Returns:

Either NOT_HANDLED to indicate that handler does not know what to do (and exception may be thrown), or value to use as key (possibly null
handleWeirdKey
(DeserializationContext ctxt, Class<?> rawKeyType, String keyValue, String
Message that will be used by caller (by calling DeserializationContext#weirdKeyException(Class, String, String)) to indicate type of failure unless handler produces key to use
failureMsg
)

Method called when a property name from input cannot be converted to a non-Java-String key type (passed as rawKeyType) due to format problem.

public Object

Returns:

Either NOT_HANDLED to indicate that handler does not know what to do (and exception may be thrown), or value to use (possibly null)
handleWeirdNativeValue
(DeserializationContext ctxt, JavaType targetType, Object valueToConvert, JsonParser p)

Method called when an embedded (native) value (JsonToken#VALUE_EMBEDDED_OBJECT) cannot be converted directly into expected value type (usually POJO).

public Object

Returns:

Either NOT_HANDLED to indicate that handler does not know what to do (and exception may be thrown), or value to use as (possibly null)
handleWeirdNumberValue
(DeserializationContext ctxt, Class<?> targetType, Number valueToConvert, String
Message that will be used by caller (by calling DeserializationContext#weirdNumberException) to indicate type of failure unless handler produces key to use
failureMsg
)

Method called when a numeric value (integral or floating-point from input cannot be converted to a non-numeric value type due to specific problem (as opposed to numeric values never being usable).

public Object

Returns:

Either NOT_HANDLED to indicate that handler does not know what to do (and exception may be thrown), or value to use as (possibly null)
handleWeirdStringValue
(DeserializationContext ctxt, Class<?> targetType, String valueToConvert, String
Message that will be used by caller (by calling DeserializationContext#weirdNumberException) to indicate type of failure unless handler produces key to use
failureMsg
)

Method called when a String value cannot be converted to a non-String value type due to specific problem (as opposed to String values never being usable).

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

NOT_HANDLEDback to summary
public static final Object NOT_HANDLED

Marker value returned by some handler methods to indicate that they could not handle problem and produce replacement value.

Since
2.7

Constructor Detail

DeserializationProblemHandlerback to summary
public DeserializationProblemHandler()

Method Detail

handleInstantiationProblemback to summary
public Object handleInstantiationProblem(DeserializationContext ctxt, Class<?> instClass, Object argument, Throwable t) throws IOException

Method called when instance creation for a type fails due to an exception. Handler may choose to do one of following things:

  • Indicate it does not know what to do by returning NOT_HANDLED
  • Throw a IOException to indicate specific fail message (instead of standard exception caller would throw
  • Return actual instantiated value (of type targetType) to use as replacement, and continue processing.
  • Return null to use null as value but not to try further processing (in cases where properties would otherwise be bound)
Parameters
instClass:Class<?>

Type that was to be instantiated

argument:Object

(optional) Additional argument that was passed to creator, if any

t:Throwable

Exception that caused instantiation failure

Returns:Object

Either NOT_HANDLED to indicate that handler does not know what to do (and exception may be thrown), or value to use (possibly null

Since
2.8
handleMissingInstantiatorback to summary
public Object handleMissingInstantiator(DeserializationContext ctxt, Class<?> instClass, ValueInstantiator valueInsta, JsonParser p, String msg) throws IOException

Method called when instance creation for a type fails due to lack of an instantiator. Method is called before actual deserialization from input is attempted, so handler may do one of following things:

  • Indicate it does not know what to do by returning NOT_HANDLED
  • Throw a IOException to indicate specific fail message (instead of standard exception caller would throw
  • Handle content to match (by consuming or skipping it), and return actual instantiated value (of type targetType) to use as replacement; value may be `null` as well as expected target type.
Parameters
instClass:Class<?>

Type that was to be instantiated

p:JsonParser

Parser to use for accessing content that needs handling, to either use it or skip it (latter with JsonParser#skipChildren().

Returns:Object

Either NOT_HANDLED to indicate that handler does not know what to do (and exception may be thrown), or value to use (possibly null

Since
2.9
handleMissingInstantiatorback to summary
public Object handleMissingInstantiator(DeserializationContext ctxt, Class<?> instClass, JsonParser p, String msg) throws IOException

Deprecated

Since 2.9: use variant that takes ValueInstantiator

Annotations
@Deprecated
Since
2.8
handleMissingTypeIdback to summary
public JavaType handleMissingTypeId(DeserializationContext ctxt, JavaType baseType, TypeIdResolver idResolver, String failureMsg) throws IOException

Handler method called if an expected type id for a polymorphic value is not found and no "default type" is specified or allowed. Handler may choose to do one of following things:

  • Indicate it does not know what to do by returning `null`
  • Indicate that nothing should be deserialized, by return `Void.class`
  • Throw a IOException to indicate specific fail message (instead of standard exception caller would throw
  • Return actual resolved type to use for this particular case.
Parameters
ctxt:DeserializationContext

Deserialization context to use for accessing information or constructing exception to throw

baseType:JavaType

Base type to use for resolving subtype id

failureMsg:String

Informational message that would be thrown as part of exception, if resolution still fails

Returns:JavaType

Actual type to use, if resolved; `null` if handler does not know what to do; or `Void.class` to indicate that nothing should be deserialized for type with the id (which caller may choose to do... or not)

Since
2.9
handleUnexpectedTokenback to summary
public Object handleUnexpectedToken(DeserializationContext ctxt, Class<?> targetType, JsonToken t, JsonParser p, String failureMsg) throws IOException

Deprecated

Since 2.10

Deprecated variant of handleUnexpectedToken(DeserializationContext, JavaType, JsonToken, JsonParser, String)

Annotations
@Deprecated
Since
2.8
handleUnexpectedTokenback to summary
public Object handleUnexpectedToken(DeserializationContext ctxt, JavaType targetType, JsonToken t, JsonParser p, String failureMsg) throws IOException

Method that deserializers should call if the first token of the value to deserialize is of unexpected type (that is, type of token that deserializer cannot handle). This could occur, for example, if a Number deserializer encounter JsonToken#START_ARRAY instead of JsonToken#VALUE_NUMBER_INT or JsonToken#VALUE_NUMBER_FLOAT.

  • Indicate it does not know what to do by returning NOT_HANDLED
  • Throw a IOException to indicate specific fail message (instead of standard exception caller would throw
  • Handle content to match (by consuming or skipping it), and return actual instantiated value (of type targetType) to use as replacement; value may be `null` as well as expected target type.
Parameters
failureMsg:String

Message that will be used by caller to indicate type of failure unless handler produces value to use

Returns:Object

Either NOT_HANDLED to indicate that handler does not know what to do (and exception may be thrown), or value to use (possibly null

Since
2.10
handleUnknownPropertyback to summary
public boolean handleUnknownProperty(DeserializationContext ctxt, JsonParser p, JsonDeserializer<?> deserializer, Object beanOrClass, String propertyName) throws IOException

Method called when a JSON Object property with an unrecognized name is encountered. Content (supposedly) matching the property are accessible via parser that can be obtained from passed deserialization context. Handler can also choose to skip the content; if so, it MUST return true to indicate it did handle property successfully. Skipping is usually done like so:

  parser.skipChildren();

Note

com.fasterxml.jackson.databind.DeserializationFeature#FAIL_ON_UNKNOWN_PROPERTIES) takes effect only after handler is called, and only if handler did not handle the problem.

Parameters
p:JsonParser

Parser to use for handling problematic content

beanOrClass:Object

Either bean instance being deserialized (if one has been instantiated so far); or Class that indicates type that will be instantiated (if no instantiation done yet: for example when bean uses non-default constructors)

Returns:boolean

True if the problem is resolved (and content available used or skipped); false if the handler did not anything and the problem is unresolved. Note that in latter case caller will either throw an exception or explicitly skip the content, depending on configuration.

handleUnknownTypeIdback to summary
public JavaType handleUnknownTypeId(DeserializationContext ctxt, JavaType baseType, String subTypeId, TypeIdResolver idResolver, String failureMsg) throws IOException

Handler method called if resolution of type id from given String failed to produce a subtype; usually because logical id is not mapped to actual implementation class. Handler may choose to do one of following things:

  • Indicate it does not know what to do by returning `null`
  • Indicate that nothing should be deserialized, by return `Void.class`
  • Throw a IOException to indicate specific fail message (instead of standard exception caller would throw
  • Return actual resolved type to use for type id.
Parameters
ctxt:DeserializationContext

Deserialization context to use for accessing information or constructing exception to throw

baseType:JavaType

Base type to use for resolving subtype id

subTypeId:String

Subtype id that failed to resolve

failureMsg:String

Informational message that would be thrown as part of exception, if resolution still fails

Returns:JavaType

Actual type to use, if resolved; `null` if handler does not know what to do; or `Void.class` to indicate that nothing should be deserialized for type with the id (which caller may choose to do... or not)

Since
2.8
handleWeirdKeyback to summary
public Object handleWeirdKey(DeserializationContext ctxt, Class<?> rawKeyType, String keyValue, String failureMsg) throws IOException

Method called when a property name from input cannot be converted to a non-Java-String key type (passed as rawKeyType) due to format problem. Handler may choose to do one of 3 things:

  • Indicate it does not know what to do by returning NOT_HANDLED
  • Throw a IOException to indicate specific fail message (instead of standard exception caller would throw
  • Return actual key value to use as replacement, and continue processing.
Parameters
failureMsg:String

Message that will be used by caller (by calling DeserializationContext#weirdKeyException(Class, String, String)) to indicate type of failure unless handler produces key to use

Returns:Object

Either NOT_HANDLED to indicate that handler does not know what to do (and exception may be thrown), or value to use as key (possibly null

Since
2.8
handleWeirdNativeValueback to summary
public Object handleWeirdNativeValue(DeserializationContext ctxt, JavaType targetType, Object valueToConvert, JsonParser p) throws IOException

Method called when an embedded (native) value (JsonToken#VALUE_EMBEDDED_OBJECT) cannot be converted directly into expected value type (usually POJO). Handler may choose to do one of 3 things:

  • Indicate it does not know what to do by returning NOT_HANDLED
  • Throw a IOException to indicate specific fail message (instead of standard exception caller would throw
  • Return actual converted value (of type targetType) to use as replacement, and continue processing.
Returns:Object

Either NOT_HANDLED to indicate that handler does not know what to do (and exception may be thrown), or value to use (possibly null)

Since
2.9
handleWeirdNumberValueback to summary
public Object handleWeirdNumberValue(DeserializationContext ctxt, Class<?> targetType, Number valueToConvert, String failureMsg) throws IOException

Method called when a numeric value (integral or floating-point from input cannot be converted to a non-numeric value type due to specific problem (as opposed to numeric values never being usable). Handler may choose to do one of 3 things:

  • Indicate it does not know what to do by returning NOT_HANDLED
  • Throw a IOException to indicate specific fail message (instead of standard exception caller would throw
  • Return actual converted value (of type targetType) to use as replacement, and continue processing.
Parameters
failureMsg:String

Message that will be used by caller (by calling DeserializationContext#weirdNumberException) to indicate type of failure unless handler produces key to use

Returns:Object

Either NOT_HANDLED to indicate that handler does not know what to do (and exception may be thrown), or value to use as (possibly null)

Since
2.8
handleWeirdStringValueback to summary
public Object handleWeirdStringValue(DeserializationContext ctxt, Class<?> targetType, String valueToConvert, String failureMsg) throws IOException

Method called when a String value cannot be converted to a non-String value type due to specific problem (as opposed to String values never being usable). Handler may choose to do one of 3 things:

  • Indicate it does not know what to do by returning NOT_HANDLED
  • Throw a IOException to indicate specific fail message (instead of standard exception caller would throw
  • Return actual converted value (of type targetType) to use as replacement, and continue processing.
Parameters
failureMsg:String

Message that will be used by caller (by calling DeserializationContext#weirdNumberException) to indicate type of failure unless handler produces key to use

Returns:Object

Either NOT_HANDLED to indicate that handler does not know what to do (and exception may be thrown), or value to use as (possibly null)

Since
2.8