Tatu Saloranta | df6302f | 2011-12-23 20:05:35 -0800 | [diff] [blame] | 1 | package com.fasterxml.jackson.databind.deser; |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 2 | |
Tatu Saloranta | 28bde07 | 2012-01-22 22:57:52 -0800 | [diff] [blame] | 3 | import com.fasterxml.jackson.databind.*; |
Tatu Saloranta | df6302f | 2011-12-23 20:05:35 -0800 | [diff] [blame] | 4 | import com.fasterxml.jackson.databind.jsontype.TypeDeserializer; |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 5 | import com.fasterxml.jackson.databind.type.*; |
| 6 | |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 7 | /** |
Tatu | e142954 | 2012-01-24 17:01:45 -0800 | [diff] [blame] | 8 | * Abstract class that defines API used by {@link DeserializationContext} |
| 9 | * to construct actual |
| 10 | * {@link JsonDeserializer} instances (which are then cached by |
| 11 | * context and/or dedicated cache). |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 12 | *<p> |
| 13 | * Since there are multiple broad categories of deserializers, there are |
| 14 | * multiple factory methods: |
| 15 | *<ul> |
| 16 | * <li>For JSON "Array" type, we need 2 methods: one to deal with expected |
| 17 | * Java arrays ({@link #createArrayDeserializer}) |
| 18 | * and the other for other Java containers like {@link java.util.List}s |
Tatu | e142954 | 2012-01-24 17:01:45 -0800 | [diff] [blame] | 19 | * and {@link java.util.Set}s ({@link #createCollectionDeserializer}). |
| 20 | * Actually there is also a third method for "Collection-like" types; |
| 21 | * things like Scala collections that act like JDK collections but do not |
| 22 | * implement same interfaces. |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 23 | * </li> |
| 24 | * <li>For JSON "Object" type, we need 2 methods: one to deal with |
| 25 | * expected Java {@link java.util.Map}s |
| 26 | * ({@link #createMapDeserializer}), and another for POJOs |
Tatu | e142954 | 2012-01-24 17:01:45 -0800 | [diff] [blame] | 27 | * ({@link #createBeanDeserializer}. |
| 28 | * As an additional twist there is also a callback for "Map-like" types, |
| 29 | * mostly to make it possible to support Scala Maps (which are NOT JDK |
| 30 | * Map compatible). |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 31 | * </li> |
Tatu Saloranta | f0e232d | 2012-01-29 16:44:28 -0800 | [diff] [blame] | 32 | * <li>For Tree Model ({@link com.fasterxml.jackson.databind.JsonNode}) properties there is |
Tatu | e142954 | 2012-01-24 17:01:45 -0800 | [diff] [blame] | 33 | * {@link #createTreeDeserializer} |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 34 | * <li>For enumerated types ({@link java.lang.Enum}) there is |
Tatu | e142954 | 2012-01-24 17:01:45 -0800 | [diff] [blame] | 35 | * {@link #createEnumDeserializer} |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 36 | * </li> |
Tatu | e142954 | 2012-01-24 17:01:45 -0800 | [diff] [blame] | 37 | * <li>For all other types, {@link #createBeanDeserializer} is used. |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 38 | * </ul> |
| 39 | *<p> |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 40 | */ |
| 41 | public abstract class DeserializerFactory |
| 42 | { |
| 43 | protected final static Deserializers[] NO_DESERIALIZERS = new Deserializers[0]; |
| 44 | |
| 45 | /* |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 46 | /******************************************************** |
| 47 | /* Configuration handling |
| 48 | /******************************************************** |
| 49 | */ |
| 50 | |
| 51 | /** |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 52 | * Convenience method for creating a new factory instance with additional deserializer |
| 53 | * provider. |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 54 | */ |
Tatu | 69e3ed4 | 2012-01-26 13:42:24 -0800 | [diff] [blame] | 55 | public abstract DeserializerFactory withAdditionalDeserializers(Deserializers additional); |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 56 | |
| 57 | /** |
| 58 | * Convenience method for creating a new factory instance with additional |
| 59 | * {@link KeyDeserializers}. |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 60 | */ |
Tatu | 69e3ed4 | 2012-01-26 13:42:24 -0800 | [diff] [blame] | 61 | public abstract DeserializerFactory withAdditionalKeyDeserializers(KeyDeserializers additional); |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 62 | |
| 63 | /** |
| 64 | * Convenience method for creating a new factory instance with additional |
| 65 | * {@link BeanDeserializerModifier}. |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 66 | */ |
Tatu | 69e3ed4 | 2012-01-26 13:42:24 -0800 | [diff] [blame] | 67 | public abstract DeserializerFactory withDeserializerModifier(BeanDeserializerModifier modifier); |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 68 | |
| 69 | /** |
| 70 | * Convenience method for creating a new factory instance with additional |
| 71 | * {@link AbstractTypeResolver}. |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 72 | */ |
Tatu | 69e3ed4 | 2012-01-26 13:42:24 -0800 | [diff] [blame] | 73 | public abstract DeserializerFactory withAbstractTypeResolver(AbstractTypeResolver resolver); |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 74 | |
| 75 | /** |
| 76 | * Convenience method for creating a new factory instance with additional |
| 77 | * {@link ValueInstantiators}. |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 78 | */ |
Tatu | 69e3ed4 | 2012-01-26 13:42:24 -0800 | [diff] [blame] | 79 | public abstract DeserializerFactory withValueInstantiators(ValueInstantiators instantiators); |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 80 | |
| 81 | /* |
| 82 | /********************************************************** |
| 83 | /* Basic DeserializerFactory API: |
| 84 | /********************************************************** |
| 85 | */ |
| 86 | |
| 87 | /** |
| 88 | * Method that can be called to try to resolve an abstract type |
| 89 | * (interface, abstract class) into a concrete type, or at least |
| 90 | * something "more concrete" (abstract class instead of interface). |
| 91 | * Will either return passed type, or a more specific type. |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 92 | */ |
| 93 | public abstract JavaType mapAbstractType(DeserializationConfig config, JavaType type) |
| 94 | throws JsonMappingException; |
| 95 | |
| 96 | /** |
| 97 | * Method that is to find all creators (constructors, factory methods) |
| 98 | * for the bean type to deserialize. |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 99 | */ |
Tatu | b37ff33 | 2012-01-24 16:19:36 -0800 | [diff] [blame] | 100 | public abstract ValueInstantiator findValueInstantiator(DeserializationContext ctxt, |
Tatu Saloranta | 28bde07 | 2012-01-22 22:57:52 -0800 | [diff] [blame] | 101 | BeanDescription beanDesc) |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 102 | throws JsonMappingException; |
| 103 | |
| 104 | /** |
| 105 | * Method called to create (or, for completely immutable deserializers, |
| 106 | * reuse) a deserializer that can convert JSON content into values of |
| 107 | * specified Java "bean" (POJO) type. |
| 108 | * At this point it is known that the type is not otherwise recognized |
| 109 | * as one of structured types (array, Collection, Map) or a well-known |
| 110 | * JDK type (enum, primitives/wrappers, String); this method only |
| 111 | * gets called if other options are exhausted. This also means that |
| 112 | * this method can be overridden to add support for custom types. |
| 113 | * |
| 114 | * @param type Type to be deserialized |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 115 | */ |
Tatu | b37ff33 | 2012-01-24 16:19:36 -0800 | [diff] [blame] | 116 | public abstract JsonDeserializer<Object> createBeanDeserializer(DeserializationContext ctxt, |
Tatu Saloranta | d6e90d0 | 2012-01-30 19:15:51 -0800 | [diff] [blame] | 117 | JavaType type, BeanDescription beanDesc) |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 118 | throws JsonMappingException; |
| 119 | |
| 120 | /** |
Tatu Saloranta | 2fd4ffd | 2012-02-17 22:40:13 -0800 | [diff] [blame] | 121 | * Method called to create a deserializer that will use specified Builder |
| 122 | * class for building value instances. |
Tatu Saloranta | 2fd4ffd | 2012-02-17 22:40:13 -0800 | [diff] [blame] | 123 | */ |
| 124 | public abstract JsonDeserializer<Object> createBuilderBasedDeserializer( |
| 125 | DeserializationContext ctxt, JavaType type, BeanDescription beanDesc, |
| 126 | Class<?> builderClass) |
| 127 | throws JsonMappingException; |
Cowtowncoder | a73550e | 2015-10-21 14:18:58 -0700 | [diff] [blame] | 128 | |
| 129 | |
| 130 | public abstract JsonDeserializer<?> createEnumDeserializer(DeserializationContext ctxt, |
| 131 | JavaType type, BeanDescription beanDesc) |
| 132 | throws JsonMappingException; |
| 133 | |
| 134 | /** |
| 135 | * @since 2.7 |
| 136 | */ |
| 137 | public abstract JsonDeserializer<?> createReferenceDeserializer(DeserializationContext ctxt, |
| 138 | ReferenceType type, BeanDescription beanDesc) |
| 139 | throws JsonMappingException; |
| 140 | |
| 141 | /** |
| 142 | * Method called to create and return a deserializer that can construct |
| 143 | * JsonNode(s) from JSON content. |
| 144 | */ |
| 145 | public abstract JsonDeserializer<?> createTreeDeserializer(DeserializationConfig config, |
| 146 | JavaType type, BeanDescription beanDesc) |
| 147 | throws JsonMappingException; |
Tatu Saloranta | 2fd4ffd | 2012-02-17 22:40:13 -0800 | [diff] [blame] | 148 | |
| 149 | /** |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 150 | * Method called to create (or, for completely immutable deserializers, |
| 151 | * reuse) a deserializer that can convert JSON content into values of |
| 152 | * specified Java type. |
| 153 | * |
| 154 | * @param type Type to be deserialized |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 155 | */ |
Tatu | b37ff33 | 2012-01-24 16:19:36 -0800 | [diff] [blame] | 156 | public abstract JsonDeserializer<?> createArrayDeserializer(DeserializationContext ctxt, |
Tatu | d0bb315 | 2012-01-31 13:04:06 -0800 | [diff] [blame] | 157 | ArrayType type, BeanDescription beanDesc) |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 158 | throws JsonMappingException; |
| 159 | |
Tatu | b37ff33 | 2012-01-24 16:19:36 -0800 | [diff] [blame] | 160 | public abstract JsonDeserializer<?> createCollectionDeserializer(DeserializationContext ctxt, |
Tatu | d0bb315 | 2012-01-31 13:04:06 -0800 | [diff] [blame] | 161 | CollectionType type, BeanDescription beanDesc) |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 162 | throws JsonMappingException; |
| 163 | |
Tatu | b37ff33 | 2012-01-24 16:19:36 -0800 | [diff] [blame] | 164 | public abstract JsonDeserializer<?> createCollectionLikeDeserializer(DeserializationContext ctxt, |
Tatu Saloranta | 49b7121 | 2012-01-30 22:13:21 -0800 | [diff] [blame] | 165 | CollectionLikeType type, BeanDescription beanDesc) |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 166 | throws JsonMappingException; |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 167 | |
Tatu | b37ff33 | 2012-01-24 16:19:36 -0800 | [diff] [blame] | 168 | public abstract JsonDeserializer<?> createMapDeserializer(DeserializationContext ctxt, |
Tatu | d0bb315 | 2012-01-31 13:04:06 -0800 | [diff] [blame] | 169 | MapType type, BeanDescription beanDesc) |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 170 | throws JsonMappingException; |
| 171 | |
Tatu | b37ff33 | 2012-01-24 16:19:36 -0800 | [diff] [blame] | 172 | public abstract JsonDeserializer<?> createMapLikeDeserializer(DeserializationContext ctxt, |
Tatu Saloranta | 49b7121 | 2012-01-30 22:13:21 -0800 | [diff] [blame] | 173 | MapLikeType type, BeanDescription beanDesc) |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 174 | throws JsonMappingException; |
| 175 | |
| 176 | /** |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 177 | * Method called to find if factory knows how to create a key deserializer |
| 178 | * for specified type; currently this means checking if a module has registered |
| 179 | * possible deserializers. |
| 180 | * |
| 181 | * @return Key deserializer to use for specified type, if one found; null if not |
| 182 | * (and default key deserializer should be used) |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 183 | */ |
Tatu | b37ff33 | 2012-01-24 16:19:36 -0800 | [diff] [blame] | 184 | public abstract KeyDeserializer createKeyDeserializer(DeserializationContext ctxt, |
Tatu | d0bb315 | 2012-01-31 13:04:06 -0800 | [diff] [blame] | 185 | JavaType type) |
Tatu | bf355ca | 2012-01-24 14:46:25 -0800 | [diff] [blame] | 186 | throws JsonMappingException; |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 187 | |
| 188 | /** |
| 189 | * Method called to find and create a type information deserializer for given base type, |
| 190 | * if one is needed. If not needed (no polymorphic handling configured for type), |
| 191 | * should return null. |
| 192 | *<p> |
| 193 | * Note that this method is usually only directly called for values of container (Collection, |
| 194 | * array, Map) types and root values, but not for bean property values. |
| 195 | * |
| 196 | * @param baseType Declared base type of the value to deserializer (actual |
| 197 | * deserializer type will be this type or its subtype) |
| 198 | * |
| 199 | * @return Type deserializer to use for given base type, if one is needed; null if not. |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 200 | */ |
Tatu | bf355ca | 2012-01-24 14:46:25 -0800 | [diff] [blame] | 201 | public abstract TypeDeserializer findTypeDeserializer(DeserializationConfig config, |
Tatu Saloranta | 49b7121 | 2012-01-30 22:13:21 -0800 | [diff] [blame] | 202 | JavaType baseType) |
Tatu | bf355ca | 2012-01-24 14:46:25 -0800 | [diff] [blame] | 203 | throws JsonMappingException; |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 204 | } |