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 | 9e50422 | 2012-01-24 11:23:59 -0800 | [diff] [blame] | 8 | * Abstract class that defines API used by {@link DeserializerCache} |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 9 | * to obtain actual |
| 10 | * {@link JsonDeserializer} instances from multiple distinct factories. |
| 11 | *<p> |
| 12 | * Since there are multiple broad categories of deserializers, there are |
| 13 | * multiple factory methods: |
| 14 | *<ul> |
| 15 | * <li>For JSON "Array" type, we need 2 methods: one to deal with expected |
| 16 | * Java arrays ({@link #createArrayDeserializer}) |
| 17 | * and the other for other Java containers like {@link java.util.List}s |
Tatu | 9e50422 | 2012-01-24 11:23:59 -0800 | [diff] [blame] | 18 | * and {@link java.util.Set}s ({@link #createCollectionDeserializer(DeserializationConfig, DeserializerCache, CollectionType, BeanProperty)}) |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 19 | * </li> |
| 20 | * <li>For JSON "Object" type, we need 2 methods: one to deal with |
| 21 | * expected Java {@link java.util.Map}s |
| 22 | * ({@link #createMapDeserializer}), and another for POJOs |
Tatu | 9e50422 | 2012-01-24 11:23:59 -0800 | [diff] [blame] | 23 | * ({@link #createBeanDeserializer(DeserializationConfig, DeserializerCache, JavaType, BeanProperty)}. |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 24 | * </li> |
Tatu Saloranta | c3fbb3a | 2011-12-24 22:07:21 -0800 | [diff] [blame] | 25 | * <li>For Tree Model ({@link com.fasterxml.jackson.core.JsonNode}) properties there is |
Tatu | 9e50422 | 2012-01-24 11:23:59 -0800 | [diff] [blame] | 26 | * {@link #createTreeDeserializer(DeserializationConfig, DeserializerCache, JavaType, BeanProperty)} |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 27 | * <li>For enumerated types ({@link java.lang.Enum}) there is |
Tatu | 9e50422 | 2012-01-24 11:23:59 -0800 | [diff] [blame] | 28 | * {@link #createEnumDeserializer(DeserializationConfig, DeserializerCache, JavaType, BeanProperty)} |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 29 | * </li> |
Tatu | 9e50422 | 2012-01-24 11:23:59 -0800 | [diff] [blame] | 30 | * <li>For all other types, {@link #createBeanDeserializer(DeserializationConfig, DeserializerCache, JavaType, BeanProperty)} |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 31 | * is used. |
| 32 | * </ul> |
| 33 | *<p> |
| 34 | * All above methods take 2 type arguments, except for the first one |
| 35 | * which takes just a single argument. |
| 36 | */ |
| 37 | public abstract class DeserializerFactory |
| 38 | { |
| 39 | protected final static Deserializers[] NO_DESERIALIZERS = new Deserializers[0]; |
| 40 | |
| 41 | /* |
| 42 | /********************************************************** |
| 43 | /* Helper class to contain configuration settings |
| 44 | /********************************************************** |
| 45 | */ |
| 46 | |
| 47 | /** |
| 48 | * Configuration settings container class for bean deserializer factory |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 49 | */ |
| 50 | public abstract static class Config |
| 51 | { |
| 52 | /** |
| 53 | * Fluent/factory method used to construct a configuration object that |
| 54 | * has same deserializer providers as this instance, plus one specified |
| 55 | * as argument. Additional provider will be added before existing ones, |
| 56 | * meaning it has priority over existing definitions. |
| 57 | */ |
| 58 | public abstract Config withAdditionalDeserializers(Deserializers additional); |
| 59 | |
| 60 | /** |
| 61 | * Fluent/factory method used to construct a configuration object that |
| 62 | * has same key deserializer providers as this instance, plus one specified |
| 63 | * as argument. Additional provider will be added before existing ones, |
| 64 | * meaning it has priority over existing definitions. |
| 65 | */ |
| 66 | public abstract Config withAdditionalKeyDeserializers(KeyDeserializers additional); |
| 67 | |
| 68 | /** |
| 69 | * Fluent/factory method used to construct a configuration object that |
| 70 | * has same configuration as this instance plus one additional |
| 71 | * deserialiazer modifier. Added modifier has the highest priority (that is, it |
| 72 | * gets called before any already registered modifier). |
| 73 | */ |
| 74 | public abstract Config withDeserializerModifier(BeanDeserializerModifier modifier); |
| 75 | |
| 76 | /** |
| 77 | * Fluent/factory method used to construct a configuration object that |
| 78 | * has same configuration as this instance plus one additional |
| 79 | * abstract type resolver. |
| 80 | * Added resolver has the highest priority (that is, it |
| 81 | * gets called before any already registered resolver). |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 82 | */ |
| 83 | public abstract Config withAbstractTypeResolver(AbstractTypeResolver resolver); |
| 84 | |
| 85 | /** |
| 86 | * Fluent/factory method used to construct a configuration object that |
| 87 | * has same configuration as this instance plus specified additional |
| 88 | * value instantiator provider object. |
| 89 | * Added instantiator provider has the highest priority (that is, it |
| 90 | * gets called before any already registered resolver). |
| 91 | * |
| 92 | * @param instantiators Object that can provide {@link com.fasterxml.jackson.databind.deser.ValueInstantiator}s for |
| 93 | * constructing POJO values during deserialization |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 94 | */ |
| 95 | public abstract Config withValueInstantiators(ValueInstantiators instantiators); |
| 96 | |
| 97 | public abstract Iterable<Deserializers> deserializers(); |
| 98 | |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 99 | public abstract Iterable<KeyDeserializers> keyDeserializers(); |
| 100 | |
| 101 | public abstract Iterable<BeanDeserializerModifier> deserializerModifiers(); |
| 102 | |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 103 | public abstract Iterable<AbstractTypeResolver> abstractTypeResolvers(); |
| 104 | |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 105 | public abstract Iterable<ValueInstantiators> valueInstantiators(); |
| 106 | |
| 107 | public abstract boolean hasDeserializers(); |
| 108 | |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 109 | public abstract boolean hasKeyDeserializers(); |
| 110 | |
| 111 | public abstract boolean hasDeserializerModifiers(); |
| 112 | |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 113 | public abstract boolean hasAbstractTypeResolvers(); |
| 114 | |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 115 | public abstract boolean hasValueInstantiators(); |
| 116 | } |
| 117 | |
| 118 | /* |
| 119 | /******************************************************** |
| 120 | /* Configuration handling |
| 121 | /******************************************************** |
| 122 | */ |
| 123 | |
| 124 | /** |
Tatu Saloranta | 7f5cc15 | 2012-01-15 10:02:55 -0800 | [diff] [blame] | 125 | * Method for accessing factory configuration (NOT the general |
| 126 | * {@link DeserializationConfig}!) |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 127 | */ |
| 128 | public abstract Config getConfig(); |
| 129 | |
| 130 | /** |
| 131 | * Method used for creating a new instance of this factory, but with different |
| 132 | * configuration. Reason for specifying factory method (instead of plain constructor) |
| 133 | * is to allow proper sub-classing of factories. |
| 134 | *<p> |
| 135 | * Note that custom sub-classes <b>must override</b> implementation |
| 136 | * of this method, as it usually requires instantiating a new instance of |
| 137 | * factory type. Check out javadocs for |
| 138 | * {@link com.fasterxml.jackson.databind.deser.BeanDeserializerFactory} for more details. |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 139 | */ |
| 140 | public abstract DeserializerFactory withConfig(Config config); |
| 141 | |
| 142 | /** |
| 143 | * Convenience method for creating a new factory instance with additional deserializer |
| 144 | * provider. |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 145 | */ |
| 146 | public final DeserializerFactory withAdditionalDeserializers(Deserializers additional) { |
| 147 | return withConfig(getConfig().withAdditionalDeserializers(additional)); |
| 148 | } |
| 149 | |
| 150 | /** |
| 151 | * Convenience method for creating a new factory instance with additional |
| 152 | * {@link KeyDeserializers}. |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 153 | */ |
| 154 | public final DeserializerFactory withAdditionalKeyDeserializers(KeyDeserializers additional) { |
| 155 | return withConfig(getConfig().withAdditionalKeyDeserializers(additional)); |
| 156 | } |
| 157 | |
| 158 | /** |
| 159 | * Convenience method for creating a new factory instance with additional |
| 160 | * {@link BeanDeserializerModifier}. |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 161 | */ |
| 162 | public final DeserializerFactory withDeserializerModifier(BeanDeserializerModifier modifier) { |
| 163 | return withConfig(getConfig().withDeserializerModifier(modifier)); |
| 164 | } |
| 165 | |
| 166 | /** |
| 167 | * Convenience method for creating a new factory instance with additional |
| 168 | * {@link AbstractTypeResolver}. |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 169 | */ |
| 170 | public final DeserializerFactory withAbstractTypeResolver(AbstractTypeResolver resolver) { |
| 171 | return withConfig(getConfig().withAbstractTypeResolver(resolver)); |
| 172 | } |
| 173 | |
| 174 | /** |
| 175 | * Convenience method for creating a new factory instance with additional |
| 176 | * {@link ValueInstantiators}. |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 177 | */ |
| 178 | public final DeserializerFactory withValueInstantiators(ValueInstantiators instantiators) { |
| 179 | return withConfig(getConfig().withValueInstantiators(instantiators)); |
| 180 | } |
| 181 | |
| 182 | /* |
| 183 | /********************************************************** |
| 184 | /* Basic DeserializerFactory API: |
| 185 | /********************************************************** |
| 186 | */ |
| 187 | |
| 188 | /** |
| 189 | * Method that can be called to try to resolve an abstract type |
| 190 | * (interface, abstract class) into a concrete type, or at least |
| 191 | * something "more concrete" (abstract class instead of interface). |
| 192 | * Will either return passed type, or a more specific type. |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 193 | */ |
| 194 | public abstract JavaType mapAbstractType(DeserializationConfig config, JavaType type) |
| 195 | throws JsonMappingException; |
| 196 | |
| 197 | /** |
| 198 | * Method that is to find all creators (constructors, factory methods) |
| 199 | * for the bean type to deserialize. |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 200 | */ |
| 201 | public abstract ValueInstantiator findValueInstantiator(DeserializationConfig config, |
Tatu Saloranta | 28bde07 | 2012-01-22 22:57:52 -0800 | [diff] [blame] | 202 | BeanDescription beanDesc) |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 203 | throws JsonMappingException; |
| 204 | |
| 205 | /** |
| 206 | * Method called to create (or, for completely immutable deserializers, |
| 207 | * reuse) a deserializer that can convert JSON content into values of |
| 208 | * specified Java "bean" (POJO) type. |
| 209 | * At this point it is known that the type is not otherwise recognized |
| 210 | * as one of structured types (array, Collection, Map) or a well-known |
| 211 | * JDK type (enum, primitives/wrappers, String); this method only |
| 212 | * gets called if other options are exhausted. This also means that |
| 213 | * this method can be overridden to add support for custom types. |
| 214 | * |
| 215 | * @param type Type to be deserialized |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 216 | */ |
Tatu | f0b28a9 | 2012-01-24 13:27:14 -0800 | [diff] [blame] | 217 | public abstract JsonDeserializer<Object> createBeanDeserializer(DeserializationConfig config, |
Tatu | bf355ca | 2012-01-24 14:46:25 -0800 | [diff] [blame^] | 218 | JavaType type, BeanDescription beanDesc, BeanProperty property) |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 219 | throws JsonMappingException; |
| 220 | |
| 221 | /** |
| 222 | * Method called to create (or, for completely immutable deserializers, |
| 223 | * reuse) a deserializer that can convert JSON content into values of |
| 224 | * specified Java type. |
| 225 | * |
| 226 | * @param type Type to be deserialized |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 227 | */ |
Tatu | f0b28a9 | 2012-01-24 13:27:14 -0800 | [diff] [blame] | 228 | public abstract JsonDeserializer<?> createArrayDeserializer(DeserializationConfig config, |
Tatu | bf355ca | 2012-01-24 14:46:25 -0800 | [diff] [blame^] | 229 | ArrayType type, BeanDescription beanDesc, BeanProperty property) |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 230 | throws JsonMappingException; |
| 231 | |
| 232 | public abstract JsonDeserializer<?> createCollectionDeserializer(DeserializationConfig config, |
Tatu | bf355ca | 2012-01-24 14:46:25 -0800 | [diff] [blame^] | 233 | CollectionType type, BeanDescription beanDesc, BeanProperty property) |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 234 | throws JsonMappingException; |
| 235 | |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 236 | public abstract JsonDeserializer<?> createCollectionLikeDeserializer(DeserializationConfig config, |
Tatu | bf355ca | 2012-01-24 14:46:25 -0800 | [diff] [blame^] | 237 | CollectionLikeType type, BeanDescription beanDesc, BeanProperty property) |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 238 | throws JsonMappingException; |
| 239 | |
| 240 | public abstract JsonDeserializer<?> createEnumDeserializer(DeserializationConfig config, |
Tatu | bf355ca | 2012-01-24 14:46:25 -0800 | [diff] [blame^] | 241 | JavaType type, BeanDescription beanDesc, BeanProperty property) |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 242 | throws JsonMappingException; |
| 243 | |
| 244 | public abstract JsonDeserializer<?> createMapDeserializer(DeserializationConfig config, |
Tatu | bf355ca | 2012-01-24 14:46:25 -0800 | [diff] [blame^] | 245 | MapType type, BeanDescription beanDesc, BeanProperty property) |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 246 | throws JsonMappingException; |
| 247 | |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 248 | public abstract JsonDeserializer<?> createMapLikeDeserializer(DeserializationConfig config, |
Tatu | bf355ca | 2012-01-24 14:46:25 -0800 | [diff] [blame^] | 249 | MapLikeType type, BeanDescription beanDesc, BeanProperty property) |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 250 | throws JsonMappingException; |
| 251 | |
| 252 | /** |
| 253 | * Method called to create and return a deserializer that can construct |
| 254 | * JsonNode(s) from JSON content. |
| 255 | */ |
Tatu | f0b28a9 | 2012-01-24 13:27:14 -0800 | [diff] [blame] | 256 | public abstract JsonDeserializer<?> createTreeDeserializer(DeserializationConfig config, |
Tatu | bf355ca | 2012-01-24 14:46:25 -0800 | [diff] [blame^] | 257 | JavaType type, BeanDescription beanDesc, BeanProperty property) |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 258 | throws JsonMappingException; |
| 259 | |
| 260 | /** |
| 261 | * Method called to find if factory knows how to create a key deserializer |
| 262 | * for specified type; currently this means checking if a module has registered |
| 263 | * possible deserializers. |
| 264 | * |
| 265 | * @return Key deserializer to use for specified type, if one found; null if not |
| 266 | * (and default key deserializer should be used) |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 267 | */ |
Tatu | bf355ca | 2012-01-24 14:46:25 -0800 | [diff] [blame^] | 268 | public abstract KeyDeserializer createKeyDeserializer(DeserializationConfig config, |
Tatu | f0b28a9 | 2012-01-24 13:27:14 -0800 | [diff] [blame] | 269 | JavaType type, BeanProperty property) |
Tatu | bf355ca | 2012-01-24 14:46:25 -0800 | [diff] [blame^] | 270 | throws JsonMappingException; |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 271 | |
| 272 | /** |
| 273 | * Method called to find and create a type information deserializer for given base type, |
| 274 | * if one is needed. If not needed (no polymorphic handling configured for type), |
| 275 | * should return null. |
| 276 | *<p> |
| 277 | * Note that this method is usually only directly called for values of container (Collection, |
| 278 | * array, Map) types and root values, but not for bean property values. |
| 279 | * |
| 280 | * @param baseType Declared base type of the value to deserializer (actual |
| 281 | * deserializer type will be this type or its subtype) |
| 282 | * |
| 283 | * @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] | 284 | */ |
Tatu | bf355ca | 2012-01-24 14:46:25 -0800 | [diff] [blame^] | 285 | public abstract TypeDeserializer findTypeDeserializer(DeserializationConfig config, |
| 286 | JavaType baseType, BeanProperty property) |
| 287 | throws JsonMappingException; |
Tatu Saloranta | e4f23bb | 2011-12-23 00:31:35 -0800 | [diff] [blame] | 288 | } |