1 package com.fasterxml.jackson.databind.deser;
2
3 import com.fasterxml.jackson.databind.*;
4 import com.fasterxml.jackson.databind.jsontype.TypeDeserializer;
5 import com.fasterxml.jackson.databind.type.*;
6
7 /**
8 * Interface that defines API for simple extensions that can provide additional deserializers
9 * for various types. Access is by a single callback method; instance is to either return
10 * a configured {@link JsonDeserializer} for specified type, or null to indicate that it
11 * does not support handling of the type. In latter case, further calls can be made
12 * for other providers; in former case returned deserializer is used for handling of
13 * instances of specified type.
14 *<p>
15 * It is <b>strongly recommended</b> that implementations always extend {@link Deserializers.Base}
16 * and NOT just implement {@link Deserializers}.
17 */
18 public interface Deserializers
19 {
20 // // // Scalar types first:
21
22 /**
23 * Method called to locate deserializer for specified {@link java.lang.Enum} type.
24 *
25 * @param type Type of {@link java.lang.Enum} instances to deserialize
26 * @param config Configuration in effect
27 * @param beanDesc Definition of the enumeration type that contains class annotations and
28 * other information typically needed for building deserializers
29 *
30 * @return Deserializer to use for the type; or null if this provider does not know how to construct it
31 */
32 public JsonDeserializer<?> findEnumDeserializer(Class<?> type,
33 DeserializationConfig config, BeanDescription beanDesc)
34 throws JsonMappingException;
35
36 /**
37 * Method called to locate deserializer for specified JSON tree node type.
38 *
39 * @param nodeType Specific type of JSON tree nodes to deserialize
40 * (subtype of {@link com.fasterxml.jackson.databind.JsonNode})
41 * @param config Configuration in effect
42 *
43 * @return Deserializer to use for the type; or null if this provider does not know how to construct it
44 */
45 public JsonDeserializer<?> findTreeNodeDeserializer(Class<? extends JsonNode> nodeType,
46 DeserializationConfig config, BeanDescription beanDesc)
47 throws JsonMappingException;
48
49 /**
50 * Method called to locate deserializer for specified value type which does not belong to any other
51 * category (not an Enum, Collection, Map, Array, reference value or tree node)
52 *
53 * @param type Bean type to deserialize
54 * @param config Configuration in effect
55 * @param beanDesc Definition of the enumeration type that contains class annotations and
56 * other information typically needed for building deserializers
57 *
58 * @return Deserializer to use for the type; or null if this provider does not know how to construct it
59 */
60 public JsonDeserializer<?> findBeanDeserializer(JavaType type,
61 DeserializationConfig config, BeanDescription beanDesc)
62 throws JsonMappingException;
63
64 // // // Then container types
65
66 /**
67 * Method called to locate deserializer for value that is of referential
68 * type,
69 *
70 * @param refType Specific referential type to deserialize
71 * @param config Configuration in effect
72 * @param beanDesc Definition of the reference type that contains class annotations and
73 * other information typically needed for building deserializers
74 * @param contentTypeDeserializer Possible type deserializer for referenced value
75 * @param contentDeserializer Value deserializer to use for referenced value, if indicated
76 * by property annotation
77 *
78 * @return Deserializer to use for the type; or null if this provider does not know how to construct it
79 *
80 * @since 2.7
81 */
82 public JsonDeserializer<?> findReferenceDeserializer(ReferenceType refType,
83 DeserializationConfig config, BeanDescription beanDesc,
84 TypeDeserializer contentTypeDeserializer, JsonDeserializer<?> contentDeserializer)
85 throws JsonMappingException;
86
87 /**
88 * Method called to locate serializer for specified array type.
89 *<p>
90 * Deserializer for element type may be passed, if configured explicitly at higher level (by
91 * annotations, typically), but usually are not.
92 * Type deserializer for element is passed if one is needed based on contextual information
93 * (annotations on declared element class; or on field or method type is associated with).
94 *
95 * @param type Type of array instances to deserialize
96 * @param config Configuration in effect
97 * @param beanDesc Definition of the enumeration type that contains class annotations and
98 * other information typically needed for building deserializers
99 * @param elementTypeDeserializer If element type needs polymorphic type handling, this is
100 * the type information deserializer to use; should usually be used as is when constructing
101 * array deserializer.
102 * @param elementDeserializer Deserializer to use for elements, if explicitly defined (by using
103 * annotations, for exmple). May be null, in which case it should be resolved here (or using
104 * {@link ResolvableDeserializer} callback)
105 *
106 * @return Deserializer to use for the type; or null if this provider does not know how to construct it
107 */
108 public JsonDeserializer<?> findArrayDeserializer(ArrayType type,
109 DeserializationConfig config, BeanDescription beanDesc,
110 TypeDeserializer elementTypeDeserializer, JsonDeserializer<?> elementDeserializer)
111 throws JsonMappingException;
112
113
114 /**
115 * Method called to locate serializer for specified {@link java.util.Collection} (List, Set etc) type.
116 *<p>
117 * Deserializer for element type may be passed, if configured explicitly at higher level (by
118 * annotations, typically), but usually are not.
119 * Type deserializer for element is passed if one is needed based on contextual information
120 * (annotations on declared element class; or on field or method type is associated with).
121 *
122 * @param type Type of collection instances to deserialize
123 * @param config Configuration in effect
124 * @param beanDesc Definition of the enumeration type that contains class annotations and
125 * other information typically needed for building deserializers
126 * @param elementTypeDeserializer If element type needs polymorphic type handling, this is
127 * the type information deserializer to use; should usually be used as is when constructing
128 * array deserializer.
129 * @param elementDeserializer Deserializer to use for elements, if explicitly defined (by using
130 * annotations, for exmple). May be null, in which case it should be resolved here (or using
131 * {@link ResolvableDeserializer} callback)
132 *
133 * @return Deserializer to use for the type; or null if this provider does not know how to construct it
134 */
135 public JsonDeserializer<?> findCollectionDeserializer(CollectionType type,
136 DeserializationConfig config, BeanDescription beanDesc,
137 TypeDeserializer elementTypeDeserializer, JsonDeserializer<?> elementDeserializer)
138 throws JsonMappingException;
139
140 /**
141 * Method called to locate serializer for specified
142 * "Collection-like" type (one that acts
143 * like {@link java.util.Collection} but does not implement it).
144 *<p>
145 * Deserializer for element type may be passed, if configured explicitly at higher level (by
146 * annotations, typically), but usually are not.
147 * Type deserializer for element is passed if one is needed based on contextual information
148 * (annotations on declared element class; or on field or method type is associated with).
149 *
150 * @param type Type of instances to deserialize
151 * @param config Configuration in effect
152 * @param beanDesc Definition of the enumeration type that contains class annotations and
153 * other information typically needed for building deserializers
154 * @param elementTypeDeserializer If element type needs polymorphic type handling, this is
155 * the type information deserializer to use; should usually be used as is when constructing
156 * array deserializer.
157 * @param elementDeserializer Deserializer to use for elements, if explicitly defined (by using
158 * annotations, for exmple). May be null, in which case it should be resolved here (or using
159 * {@link ResolvableDeserializer} callback)
160 *
161 * @return Deserializer to use for the type; or null if this provider does not know how to construct it
162 */
163 public JsonDeserializer<?> findCollectionLikeDeserializer(CollectionLikeType type,
164 DeserializationConfig config, BeanDescription beanDesc,
165 TypeDeserializer elementTypeDeserializer, JsonDeserializer<?> elementDeserializer)
166 throws JsonMappingException;
167
168 /**
169 * Method called to locate deserializer for specified {@link java.util.Map} type.
170 *<p>
171 * Deserializer for element type may be passed, if configured explicitly at higher level (by
172 * annotations, typically), but usually are not.
173 * Type deserializer for element is passed if one is needed based on contextual information
174 * (annotations on declared element class; or on field or method type is associated with).
175 *<p>
176 * Similarly, a {@link KeyDeserializer} may be passed, but this is only done if there is
177 * a specific configuration override (annotations) to indicate instance to use.
178 * Otherwise null is passed, and key deserializer needs to be obtained later during
179 * resolution (using {@link ResolvableDeserializer#resolve}).
180 *
181 * @param type Type of {@link java.util.Map} instances to deserialize
182 * @param config Configuration in effect
183 * @param beanDesc Definition of the enumeration type that contains class annotations and
184 * other information typically needed for building deserializers
185 * @param keyDeserializer Key deserializer use, if it is defined via annotations or other configuration;
186 * null if default key deserializer for key type can be used.
187 * @param elementTypeDeserializer If element type needs polymorphic type handling, this is
188 * the type information deserializer to use; should usually be used as is when constructing
189 * array deserializer.
190 * @param elementDeserializer Deserializer to use for elements, if explicitly defined (by using
191 * annotations, for exmple). May be null, in which case it should be resolved here (or using
192 * {@link ResolvableDeserializer} callback)
193 *
194 * @return Deserializer to use for the type; or null if this provider does not know how to construct it
195 */
196 public JsonDeserializer<?> findMapDeserializer(MapType type,
197 DeserializationConfig config, BeanDescription beanDesc,
198 KeyDeserializer keyDeserializer,
199 TypeDeserializer elementTypeDeserializer, JsonDeserializer<?> elementDeserializer)
200 throws JsonMappingException;
201
202 /**
203 * Method called to locate serializer for specified
204 * "Map-like" type (one that acts
205 * like {@link java.util.Map} but does not implement it).
206 *<p>
207 * Deserializer for element type may be passed, if configured explicitly at higher level (by
208 * annotations, typically), but usually are not.
209 * Type deserializer for element is passed if one is needed based on contextual information
210 * (annotations on declared element class; or on field or method type is associated with).
211 *<p>
212 * Similarly, a {@link KeyDeserializer} may be passed, but this is only done if there is
213 * a specific configuration override (annotations) to indicate instance to use.
214 * Otherwise null is passed, and key deserializer needs to be obtained later during
215 * resolution (using {@link ResolvableDeserializer#resolve}).
216 *
217 * @param type Type of {@link java.util.Map} instances to deserialize
218 * @param config Configuration in effect
219 * @param beanDesc Definition of the enumeration type that contains class annotations and
220 * other information typically needed for building deserializers
221 * @param keyDeserializer Key deserializer use, if it is defined via annotations or other configuration;
222 * null if default key deserializer for key type can be used.
223 * @param elementTypeDeserializer If element type needs polymorphic type handling, this is
224 * the type information deserializer to use; should usually be used as is when constructing
225 * array deserializer.
226 * @param elementDeserializer Deserializer to use for elements, if explicitly defined (by using
227 * annotations, for exmple). May be null, in which case it should be resolved here (or using
228 * {@link ResolvableDeserializer} callback)
229 *
230 * @return Deserializer to use for the type; or null if this provider does not know how to construct it
231 */
232 public JsonDeserializer<?> findMapLikeDeserializer(MapLikeType type,
233 DeserializationConfig config, BeanDescription beanDesc,
234 KeyDeserializer keyDeserializer,
235 TypeDeserializer elementTypeDeserializer, JsonDeserializer<?> elementDeserializer)
236 throws JsonMappingException;
237
238 // To be added in 3.0
239 // public boolean hasDeserializerFor(DeserializationConfig config, Class<?> valueType);
240
241 /*
242 /**********************************************************
243 /* Helper classes
244 /**********************************************************
245 */
246
247 /**
248 * Basic {@link Deserializers} implementation that implements all methods but provides
249 * no deserializers. Its main purpose is to serve as a base class so that
250 * sub-classes only need to override methods they need, as most of the time some
251 * of methods are not needed (especially enumeration and array deserializers are
252 * very rarely overridden).
253 */
254 public abstract static class Base
255 implements Deserializers
256 {
257 @Override
258 public JsonDeserializer<?> findEnumDeserializer(Class<?> type,
259 DeserializationConfig config, BeanDescription beanDesc)
260 throws JsonMappingException
261 {
262 return null;
263 }
264
265 @Override
266 public JsonDeserializer<?> findTreeNodeDeserializer(Class<? extends JsonNode> nodeType,
267 DeserializationConfig config, BeanDescription beanDesc)
268 throws JsonMappingException
269 {
270 return null;
271 }
272
273 @Override
274 public JsonDeserializer<?> findReferenceDeserializer(ReferenceType refType,
275 DeserializationConfig config, BeanDescription beanDesc,
276 TypeDeserializer contentTypeDeserializer, JsonDeserializer<?> contentDeserializer)
277 throws JsonMappingException
278 {
279 return null;
280 }
281
282 @Override
283 public JsonDeserializer<?> findBeanDeserializer(JavaType type,
284 DeserializationConfig config, BeanDescription beanDesc)
285 throws JsonMappingException
286 {
287 return null;
288 }
289
290 @Override
291 public JsonDeserializer<?> findArrayDeserializer(ArrayType type,
292 DeserializationConfig config, BeanDescription beanDesc,
293 TypeDeserializer elementTypeDeserializer, JsonDeserializer<?> elementDeserializer)
294 throws JsonMappingException
295 {
296 return null;
297 }
298
299 @Override
300 public JsonDeserializer<?> findCollectionDeserializer(CollectionType type,
301 DeserializationConfig config, BeanDescription beanDesc,
302 TypeDeserializer elementTypeDeserializer, JsonDeserializer<?> elementDeserializer)
303 throws JsonMappingException
304 {
305 return null;
306 }
307
308 @Override
309 public JsonDeserializer<?> findCollectionLikeDeserializer(CollectionLikeType type,
310 DeserializationConfig config, BeanDescription beanDesc,
311 TypeDeserializer elementTypeDeserializer, JsonDeserializer<?> elementDeserializer)
312 throws JsonMappingException
313 {
314 return null;
315 }
316
317 @Override
318 public JsonDeserializer<?> findMapDeserializer(MapType type,
319 DeserializationConfig config, BeanDescription beanDesc,
320 KeyDeserializer keyDeserializer,
321 TypeDeserializer elementTypeDeserializer, JsonDeserializer<?> elementDeserializer)
322 throws JsonMappingException
323 {
324 return null;
325 }
326
327 @Override
328 public JsonDeserializer<?> findMapLikeDeserializer(MapLikeType type,
329 DeserializationConfig config, BeanDescription beanDesc,
330 KeyDeserializer keyDeserializer,
331 TypeDeserializer elementTypeDeserializer, JsonDeserializer<?> elementDeserializer)
332 throws JsonMappingException
333 {
334 return null;
335 }
336
337 /**
338 * Method that may be called to check whether this deserializer provider would provide
339 * deserializer for values of given type, without attempting to construct (and possibly
340 * fail in some cases) actual deserializer. Mostly needed to support validation
341 * of polymorphic type ids.
342 *<p>
343 * Note: implementations should take care NOT to claim supporting types that they do
344 * not recognize as this could to incorrect assumption of safe support by caller.
345 *<p>
346 * Method added in this implementation since adding new methods for interfaces
347 * before Java 8 is not a good idea: will be added in Jackson 3.0 for `Deserializers`.
348 *
349 * @since 2.11
350 */
351 public boolean hasDeserializerFor(DeserializationConfig config,
352 Class<?> valueType) {
353 return false;
354 }
355 // public abstract boolean hasDeserializerFor(Class<?> valueType);
356 }
357 }
358