DeserializationProblemHandler
Date: 2016-12-04

com.fasterxml.jackson.databind.deser

## Class DeserializationProblemHandler

- java.lang.Object
- - com.fasterxml.jackson.databind.deser.DeserializationProblemHandler

-     public abstract class DeserializationProblemHandler
      extends java.lang.Object

  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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.Object` | `NOT_HANDLED` Marker value returned by some handler methods to indicate that they could not handle problem and produce replacement value.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DeserializationProblemHandler()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Object` | `handleInstantiationProblem(DeserializationContext ctxt, java.lang.Class<?> instClass, java.lang.Object argument, java.lang.Throwable t)` Method called when instance creation for a type fails due to an exception.
    `java.lang.Object` | `handleMissingInstantiator(DeserializationContext ctxt, java.lang.Class<?> instClass, com.fasterxml.jackson.core.JsonParser p, java.lang.String msg)` Method called when instance creation for a type fails due to lack of an instantiator.
    `java.lang.Object` | `handleUnexpectedToken(DeserializationContext ctxt, java.lang.Class<?> targetType, com.fasterxml.jackson.core.JsonToken t, com.fasterxml.jackson.core.JsonParser p, java.lang.String 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 can not handle).
    `boolean` | `handleUnknownProperty(DeserializationContext ctxt, com.fasterxml.jackson.core.JsonParser p, JsonDeserializer<?> deserializer, java.lang.Object beanOrClass, java.lang.String propertyName)` Method called when a JSON Object property with an unrecognized name is encountered.
    `JavaType` | `handleUnknownTypeId(DeserializationContext ctxt, JavaType baseType, java.lang.String subTypeId, TypeIdResolver idResolver, java.lang.String 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.
    `java.lang.Object` | `handleWeirdKey(DeserializationContext ctxt, java.lang.Class<?> rawKeyType, java.lang.String keyValue, java.lang.String failureMsg)` Method called when a property name from input can not be converted to a non-Java-String key type (passed as `rawKeyType`) due to format problem.
    `java.lang.Object` | `handleWeirdNumberValue(DeserializationContext ctxt, java.lang.Class<?> targetType, java.lang.Number valueToConvert, java.lang.String failureMsg)` Method called when a numeric value (integral or floating-point from input can not be converted to a non-numeric value type due to specific problem (as opposed to numeric values never being usable).
    `java.lang.Object` | `handleWeirdStringValue(DeserializationContext ctxt, java.lang.Class<?> targetType, java.lang.String valueToConvert, java.lang.String failureMsg)` Method called when a String value can not be converted to a non-String value type due to specific problem (as opposed to String values never being usable).

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### NOT_HANDLED

          public static final java.lang.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

    - #### DeserializationProblemHandler

          public DeserializationProblemHandler()

  - ### Method Detail

    - #### handleUnknownProperty

          public boolean handleUnknownProperty(DeserializationContext ctxt,
                                      com.fasterxml.jackson.core.JsonParser p,
                                      JsonDeserializer<?> deserializer,
                                      java.lang.Object beanOrClass,
                                      java.lang.String propertyName)
                                        throws java.io.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: `DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES`) takes effect only after handler is called, and only if handler did not handle the problem.

      Parameters:
        `beanOrClass` - 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)
        `p` - Parser to use for handling problematic content
      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.
      Throws:
        `java.io.IOException`

    - #### handleWeirdKey

          public java.lang.Object handleWeirdKey(DeserializationContext ctxt,
                                        java.lang.Class<?> rawKeyType,
                                        java.lang.String keyValue,
                                        java.lang.String failureMsg)
                                          throws java.io.IOException

      Method called when a property name from input can not 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` - 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:
        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`
      Throws:
        `java.io.IOException`
      Since:
        2.8

    - #### handleWeirdStringValue

          public java.lang.Object handleWeirdStringValue(DeserializationContext ctxt,
                                                java.lang.Class<?> targetType,
                                                java.lang.String valueToConvert,
                                                java.lang.String failureMsg)
                                                  throws java.io.IOException

      Method called when a String value can not 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` - Message that will be used by caller (by calling `DeserializationContext.weirdNumberException(java.lang.Number, java.lang.Class<?>, java.lang.String)`) to indicate type of failure unless handler produces key to use
      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`
      Throws:
        `java.io.IOException`
      Since:
        2.8

    - #### handleWeirdNumberValue

          public java.lang.Object handleWeirdNumberValue(DeserializationContext ctxt,
                                                java.lang.Class<?> targetType,
                                                java.lang.Number valueToConvert,
                                                java.lang.String failureMsg)
                                                  throws java.io.IOException

      Method called when a numeric value (integral or floating-point from input can not 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` - Message that will be used by caller (by calling `DeserializationContext.weirdNumberException(java.lang.Number, java.lang.Class<?>, java.lang.String)`) to indicate type of failure unless handler produces key to use
      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`
      Throws:
        `java.io.IOException`
      Since:
        2.8

    - #### handleUnexpectedToken

          public java.lang.Object handleUnexpectedToken(DeserializationContext ctxt,
                                               java.lang.Class<?> targetType,
                                               com.fasterxml.jackson.core.JsonToken t,
                                               com.fasterxml.jackson.core.JsonParser p,
                                               java.lang.String failureMsg)
                                                 throws java.io.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 can not 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` - Message that will be used by caller to indicate type of failure unless handler produces value to use
      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`
      Throws:
        `java.io.IOException`
      Since:
        2.8

    - #### handleInstantiationProblem

          public java.lang.Object handleInstantiationProblem(DeserializationContext ctxt,
                                                    java.lang.Class<?> instClass,
                                                    java.lang.Object argument,
                                                    java.lang.Throwable t)
                                                      throws java.io.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` - Type that was to be instantiated
        `argument` - (optional) Additional argument that was passed to creator, if any
        `t` - Exception that caused instantiation failure
      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`
      Throws:
        `java.io.IOException`
      Since:
        2.8

    - #### handleMissingInstantiator

          public java.lang.Object handleMissingInstantiator(DeserializationContext ctxt,
                                                   java.lang.Class<?> instClass,
                                                   com.fasterxml.jackson.core.JsonParser p,
                                                   java.lang.String msg)
                                                     throws java.io.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` - Type that was to be instantiated
        `p` - Parser to use for accessing content that needs handling, to either use it or skip it (latter with `JsonParser.skipChildren()`.
      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`
      Throws:
        `java.io.IOException`
      Since:
        2.8

    - #### handleUnknownTypeId

          public JavaType handleUnknownTypeId(DeserializationContext ctxt,
                                     JavaType baseType,
                                     java.lang.String subTypeId,
                                     TypeIdResolver idResolver,
                                     java.lang.String failureMsg)
                                       throws java.io.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` - Deserialization context to use for accessing information or constructing exception to throw
        `baseType` - Base type to use for resolving subtype id
        `subTypeId` - Subtype id that failed to resolve
        `failureMsg` - Informational message that would be thrown as part of exception, if resolution still fails
      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)
      Throws:
        `java.io.IOException`
      Since:
        2.8