package com.fasterxml.jackson.databind.deser; import java.io.IOException; import com.fasterxml.jackson.core.JsonParser; import com.fasterxml.jackson.core.JsonToken; import com.fasterxml.jackson.databind.DeserializationConfig; import com.fasterxml.jackson.databind.DeserializationContext; import com.fasterxml.jackson.databind.JavaType; import com.fasterxml.jackson.databind.JsonDeserializer; import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.jsontype.TypeIdResolver; /** * This is the class that can be registered (via * {@link DeserializationConfig} object owner by * {@link 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. *<p> * 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. *<p> * NOTE: it is typically <b>NOT</b> acceptable to simply do nothing, * because this will result in unprocessed tokens being left in * token stream (read via {@link JsonParser}, in case a structured * (JSON Object or JSON Array) value is being pointed to by parser. */ public abstract class DeserializationProblemHandler { /** * Marker value returned by some handler methods to indicate that * they could not handle problem and produce replacement value. * * @since 2.7 */ public final static Object NOT_HANDLED = new Object(); /** * 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: *<pre> * parser.skipChildren(); *</pre> *<p> * Note: {@link com.fasterxml.jackson.databind.DeserializationFeature#FAIL_ON_UNKNOWN_PROPERTIES}) * takes effect only <b>after</b> handler is called, and only * if handler did <b>not</b> handle the problem. * * @param 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) * @param p Parser to use for handling problematic content * * @return 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. */ public boolean handleUnknownProperty(DeserializationContext ctxt, JsonParser p, JsonDeserializer<?> deserializer, Object beanOrClass, String propertyName) throws IOException { return false; } /** * Method called when a property name from input can not be converted to a * non-Java-String key type (passed as <code>rawKeyType</code>) due to format problem. * Handler may choose to do one of 3 things: *<ul> * <li>Indicate it does not know what to do by returning {@link #NOT_HANDLED} * </li> * <li>Throw a {@link IOException} to indicate specific fail message (instead of * standard exception caller would throw * </li> * <li>Return actual key value to use as replacement, and continue processing. * </li> * </ul> * * @param failureMsg Message that will be used by caller (by calling * {@link DeserializationContext#weirdKeyException(Class, String, String)}) * to indicate type of failure unless handler produces key to use * * @return Either {@link #NOT_HANDLED} to indicate that handler does not know * what to do (and exception may be thrown), or value to use as key (possibly * <code>null</code> * * @since 2.8 */ public Object handleWeirdKey(DeserializationContext ctxt, Class<?> rawKeyType, String keyValue, String failureMsg) throws IOException { return NOT_HANDLED; } /** * 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: *<ul> * <li>Indicate it does not know what to do by returning {@link #NOT_HANDLED} * </li> * <li>Throw a {@link IOException} to indicate specific fail message (instead of * standard exception caller would throw * </li> * <li>Return actual converted value (of type <code>targetType</code>) to use as * replacement, and continue processing. * </li> * </ul> * * @param failureMsg Message that will be used by caller (by calling * {@link DeserializationContext#weirdNumberException}) * to indicate type of failure unless handler produces key to use * * @return Either {@link #NOT_HANDLED} to indicate that handler does not know * what to do (and exception may be thrown), or value to use as key (possibly * <code>null</code> * * @since 2.8 */ public Object handleWeirdStringValue(DeserializationContext ctxt, Class<?> targetType, String valueToConvert, String failureMsg) throws IOException { return NOT_HANDLED; } /** * 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: *<ul> * <li>Indicate it does not know what to do by returning {@link #NOT_HANDLED} * </li> * <li>Throw a {@link IOException} to indicate specific fail message (instead of * standard exception caller would throw * </li> * <li>Return actual converted value (of type <code>targetType</code>) to use as * replacement, and continue processing. * </li> * </ul> * * @param failureMsg Message that will be used by caller (by calling * {@link DeserializationContext#weirdNumberException}) * to indicate type of failure unless handler produces key to use * * @return Either {@link #NOT_HANDLED} to indicate that handler does not know * what to do (and exception may be thrown), or value to use as key (possibly * <code>null</code> * * @since 2.8 */ public Object handleWeirdNumberValue(DeserializationContext ctxt, Class<?> targetType, Number valueToConvert, String failureMsg) throws IOException { return NOT_HANDLED; } /** * 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 {@link JsonToken#START_ARRAY} instead of * {@link JsonToken#VALUE_NUMBER_INT} or {@link JsonToken#VALUE_NUMBER_FLOAT}. *<ul> * <li>Indicate it does not know what to do by returning {@link #NOT_HANDLED} * </li> * <li>Throw a {@link IOException} to indicate specific fail message (instead of * standard exception caller would throw * </li> * <li>Handle content to match (by consuming or skipping it), and return actual * instantiated value (of type <code>targetType</code>) to use as replacement; * value may be `null` as well as expected target type. * </li> * </ul> * * @param failureMsg Message that will be used by caller * to indicate type of failure unless handler produces value to use * * @return Either {@link #NOT_HANDLED} to indicate that handler does not know * what to do (and exception may be thrown), or value to use (possibly * <code>null</code> * * @since 2.8 */ public Object handleUnexpectedToken(DeserializationContext ctxt, Class<?> targetType, JsonToken t, JsonParser p, String failureMsg) throws IOException { return NOT_HANDLED; } /** * Method called when instance creation for a type fails due to an exception. * Handler may choose to do one of following things: *<ul> * <li>Indicate it does not know what to do by returning {@link #NOT_HANDLED} * </li> * <li>Throw a {@link IOException} to indicate specific fail message (instead of * standard exception caller would throw * </li> * <li>Return actual instantiated value (of type <code>targetType</code>) to use as * replacement, and continue processing. * </li> * <li>Return <code>null</code> to use null as value but not to try further * processing (in cases where properties would otherwise be bound) * </li> * </ul> * * @param instClass Type that was to be instantiated * @param argument (optional) Additional argument that was passed to creator, if any * @param t Exception that caused instantiation failure * * @return Either {@link #NOT_HANDLED} to indicate that handler does not know * what to do (and exception may be thrown), or value to use (possibly * <code>null</code> * * @since 2.8 */ public Object handleInstantiationProblem(DeserializationContext ctxt, Class<?> instClass, Object argument, Throwable t) throws IOException { return NOT_HANDLED; } /** * 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: *<ul> * <li>Indicate it does not know what to do by returning {@link #NOT_HANDLED} * </li> * <li>Throw a {@link IOException} to indicate specific fail message (instead of * standard exception caller would throw * </li> * <li>Handle content to match (by consuming or skipping it), and return actual * instantiated value (of type <code>targetType</code>) to use as replacement; * value may be `null` as well as expected target type. * </li> * </ul> * * @param instClass Type that was to be instantiated * @param p Parser to use for accessing content that needs handling, to either * use it or skip it (latter with {@link JsonParser#skipChildren()}. * * @return Either {@link #NOT_HANDLED} to indicate that handler does not know * what to do (and exception may be thrown), or value to use (possibly * <code>null</code> * * @since 2.9 */ public Object handleMissingInstantiator(DeserializationContext ctxt, Class<?> instClass, ValueInstantiator valueInsta, JsonParser p, String msg) throws IOException { // 16-Oct-2016, tatu: Need to delegate to deprecated method from 2.8; // remove redirect from later versions (post-2.9) return handleMissingInstantiator(ctxt, instClass, p, msg); } /** * 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: *<ul> * <li>Indicate it does not know what to do by returning `null` * </li> * <li>Indicate that nothing should be deserialized, by return `Void.class` * </li> * <li>Throw a {@link IOException} to indicate specific fail message (instead of * standard exception caller would throw * </li> * <li>Return actual resolved type to use for type id. * </li> * </ul> * * @param ctxt Deserialization context to use for accessing information or * constructing exception to throw * @param baseType Base type to use for resolving subtype id * @param subTypeId Subtype id that failed to resolve * @param failureMsg Informational message that would be thrown as part of * exception, if resolution still fails * * @return 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 */ public JavaType handleUnknownTypeId(DeserializationContext ctxt, JavaType baseType, String subTypeId, TypeIdResolver idResolver, String failureMsg) throws IOException { return null; } /** * 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: *<ul> * <li>Indicate it does not know what to do by returning `null` * </li> * <li>Indicate that nothing should be deserialized, by return `Void.class` * </li> * <li>Throw a {@link IOException} to indicate specific fail message (instead of * standard exception caller would throw * </li> * <li>Return actual resolved type to use for this particular case. * </li> * </ul> * * @param ctxt Deserialization context to use for accessing information or * constructing exception to throw * @param baseType Base type to use for resolving subtype id * @param failureMsg Informational message that would be thrown as part of * exception, if resolution still fails * * @return 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 */ public JavaType handleMissingTypeId(DeserializationContext ctxt, JavaType baseType, TypeIdResolver idResolver, String failureMsg) throws IOException { return null; } /* /********************************************************** /* Deprecated /********************************************************** */ /** * @since 2.8 * @deprecated Since 2.9: use variant that takes {@link ValueInstantiator} */ @Deprecated public Object handleMissingInstantiator(DeserializationContext ctxt, Class<?> instClass, JsonParser p, String msg) throws IOException { return NOT_HANDLED; } }