1 package com.fasterxml.jackson.databind;
2
3 import java.lang.annotation.Annotation;
4 import java.util.*;
5
6 import com.fasterxml.jackson.annotation.*;
7 import com.fasterxml.jackson.core.Version;
8 import com.fasterxml.jackson.core.Versioned;
9
10 import com.fasterxml.jackson.databind.annotation.JsonPOJOBuilder;
11 import com.fasterxml.jackson.databind.annotation.JsonSerialize;
12 import com.fasterxml.jackson.databind.cfg.MapperConfig;
13 import com.fasterxml.jackson.databind.deser.ValueInstantiator;
14 import com.fasterxml.jackson.databind.introspect.*;
15 import com.fasterxml.jackson.databind.jsontype.NamedType;
16 import com.fasterxml.jackson.databind.jsontype.TypeResolverBuilder;
17 import com.fasterxml.jackson.databind.ser.BeanPropertyWriter;
18 import com.fasterxml.jackson.databind.util.Converter;
19 import com.fasterxml.jackson.databind.util.NameTransformer;
20
21 /**
22 * Abstract class that defines API used for introspecting annotation-based
23 * configuration for serialization and deserialization. Separated
24 * so that different sets of annotations can be supported, and support
25 * plugged-in dynamically.
26 *<p>
27 * Although default implementations are based on using annotations as the only
28 * (or at least main) information source, custom implementations are not limited
29 * in such a way, and in fact there is no expectation they should be. So the name
30 * is bit of misnomer; this is a general configuration introspection facility.
31 *<p>
32 * NOTE: due to rapid addition of new methods (and changes to existing methods),
33 * it is <b>strongly</b> recommended that custom implementations should not directly
34 * extend this class, but rather extend {@link NopAnnotationIntrospector}.
35 * This way added methods will not break backwards compatibility of custom annotation
36 * introspectors.
37 */
38 @SuppressWarnings("serial")
39 public abstract class AnnotationIntrospector
40 implements Versioned, java.io.Serializable
41 {
42 /*
43 /**********************************************************
44 /* Helper types
45 /**********************************************************
46 */
47
48 /**
49 * Value type used with managed and back references; contains type and
50 * logic name, used to link related references
51 */
52 public static class ReferenceProperty
53 {
54 public enum Type {
55 /**
56 * Reference property that Jackson manages and that is serialized normally (by serializing
57 * reference object), but is used for resolving back references during
58 * deserialization.
59 * Usually this can be defined by using
60 * {@link com.fasterxml.jackson.annotation.JsonManagedReference}
61 */
62 MANAGED_REFERENCE
63
64 /**
65 * Reference property that Jackson manages by suppressing it during serialization,
66 * and reconstructing during deserialization.
67 * Usually this can be defined by using
68 * {@link com.fasterxml.jackson.annotation.JsonBackReference}
69 */
70 ,BACK_REFERENCE
71 ;
72 }
73
74 private final Type _type;
75 private final String _name;
76
77 public ReferenceProperty(Type t, String n) {
78 _type = t;
79 _name = n;
80 }
81
82 public static ReferenceProperty managed(String name) { return new ReferenceProperty(Type.MANAGED_REFERENCE, name); }
83 public static ReferenceProperty back(String name) { return new ReferenceProperty(Type.BACK_REFERENCE, name); }
84
85 public Type getType() { return _type; }
86 public String getName() { return _name; }
87
88 public boolean isManagedReference() { return _type == Type.MANAGED_REFERENCE; }
89 public boolean isBackReference() { return _type == Type.BACK_REFERENCE; }
90 }
91
92 /*
93 /**********************************************************
94 /* Factory methods
95 /**********************************************************
96 */
97
98 /**
99 * Factory method for accessing "no operation" implementation
100 * of introspector: instance that will never find any annotation-based
101 * configuration.
102 */
103 public static AnnotationIntrospector nopInstance() {
104 return NopAnnotationIntrospector.instance;
105 }
106
107 public static AnnotationIntrospector pair(AnnotationIntrospector a1, AnnotationIntrospector a2) {
108 return new AnnotationIntrospectorPair(a1, a2);
109 }
110
111 /*
112 /**********************************************************
113 /* Access to possibly chained introspectors
114 /**********************************************************
115 */
116
117 /**
118 * Method that can be used to collect all "real" introspectors that
119 * this introspector contains, if any; or this introspector
120 * if it is not a container. Used to get access to all container
121 * introspectors in their priority order.
122 *<p>
123 * Default implementation returns a Singleton list with this introspector
124 * as contents.
125 * This usually works for sub-classes, except for proxy or delegating "container
126 * introspectors" which need to override implementation.
127 */
128 public Collection<AnnotationIntrospector> allIntrospectors() {
129 return Collections.singletonList(this);
130 }
131
132 /**
133 * Method that can be used to collect all "real" introspectors that
134 * this introspector contains, if any; or this introspector
135 * if it is not a container. Used to get access to all container
136 * introspectors in their priority order.
137 *<p>
138 * Default implementation adds this introspector in result; this usually
139 * works for sub-classes, except for proxy or delegating "container
140 * introspectors" which need to override implementation.
141 */
142 public Collection<AnnotationIntrospector> allIntrospectors(Collection<AnnotationIntrospector> result) {
143 result.add(this);
144 return result;
145 }
146
147 /*
148 /**********************************************************
149 /* Default Versioned impl
150 /**********************************************************
151 */
152
153 @Override
154 public abstract Version version();
155
156 /*
157 /**********************************************************
158 /* Meta-annotations (annotations for annotation types)
159 /**********************************************************
160 */
161
162 /**
163 * Method for checking whether given annotation is considered an
164 * annotation bundle: if so, all meta-annotations it has will
165 * be used instead of annotation ("bundle") itself.
166 *
167 * @since 2.0
168 */
169 public boolean isAnnotationBundle(Annotation ann) {
170 return false;
171 }
172
173 /*
174 /**********************************************************
175 /* Annotations for Object Id handling
176 /**********************************************************
177 */
178
179 /**
180 * Method for checking whether given annotated thing
181 * (type, or accessor) indicates that values
182 * referenced (values of type of annotated class, or
183 * values referenced by annotated property; latter
184 * having precedence) should include Object Identifier,
185 * and if so, specify details of Object Identity used.
186 *
187 * @since 2.0
188 */
189 public ObjectIdInfo findObjectIdInfo(Annotated ann) {
190 return null;
191 }
192
193 /**
194 * Method for figuring out additional properties of an Object Identity reference
195 *
196 * @since 2.1
197 */
198 public ObjectIdInfo findObjectReferenceInfo(Annotated ann, ObjectIdInfo objectIdInfo) {
199 return objectIdInfo;
200 }
201
202 /*
203 /**********************************************************
204 /* General class annotations
205 /**********************************************************
206 */
207
208 /**
209 * Method for locating name used as "root name" (for use by
210 * some serializers when outputting root-level object -- mostly
211 * for XML compatibility purposes) for given class, if one
212 * is defined. Returns null if no declaration found; can return
213 * explicit empty String, which is usually ignored as well as null.
214 *<p>
215 * NOTE: method signature changed in 2.1, to return {@link PropertyName}
216 * instead of String.
217 */
218 public PropertyName findRootName(AnnotatedClass ac) {
219 return null;
220 }
221
222 /**
223 * Method for finding information about properties to ignore either by
224 * name, or by more general specification ("ignore all unknown").
225 * This method combines multiple aspects of ignorals and deprecates
226 * earlier methods such as
227 * {@link #findPropertiesToIgnore(Annotated, boolean)} and
228 * {@link #findIgnoreUnknownProperties(AnnotatedClass)}.
229 *
230 * @since 2.8
231 */
232 public JsonIgnoreProperties.Value findPropertyIgnorals(Annotated ac)
233 {
234 // 18-Oct-2016, tatu: Used to call deprecated methods for backwards
235 // compatibility in 2.8, but not any more in 2.9
236 return JsonIgnoreProperties.Value.empty();
237 }
238
239 /**
240 * Method for checking whether properties that have specified type
241 * (class, not generics aware) should be completely ignored for
242 * serialization and deserialization purposes.
243 *
244 * @param ac Type to check
245 *
246 * @return Boolean.TRUE if properties of type should be ignored;
247 * Boolean.FALSE if they are not to be ignored, null for default
248 * handling (which is 'do not ignore')
249 */
250 public Boolean isIgnorableType(AnnotatedClass ac) { return null; }
251
252 /**
253 * Method for finding if annotated class has associated filter; and if so,
254 * to return id that is used to locate filter.
255 *
256 * @return Id of the filter to use for filtering properties of annotated
257 * class, if any; or null if none found.
258 */
259 public Object findFilterId(Annotated ann) { return null; }
260
261 /**
262 * Method for finding {@link PropertyNamingStrategy} for given
263 * class, if any specified by annotations; and if so, either return
264 * a {@link PropertyNamingStrategy} instance, or Class to use for
265 * creating instance
266 *
267 * @return Sub-class or instance of {@link PropertyNamingStrategy}, if one
268 * is specified for given class; null if not.
269 *
270 * @since 2.1
271 */
272 public Object findNamingStrategy(AnnotatedClass ac) { return null; }
273
274 /**
275 * Method used to check whether specified class defines a human-readable
276 * description to use for documentation.
277 * There are no further definitions for contents; for example, whether
278 * these may be marked up using HTML (or something like wiki format like Markup)
279 * is not defined.
280 *
281 * @return Human-readable description, if any.
282 *
283 * @since 2.7
284 */
285 public String findClassDescription(AnnotatedClass ac) { return null; }
286
287 /**
288 * @param forSerialization True if requesting properties to ignore for serialization;
289 * false if for deserialization
290 *
291 * @since 2.6
292 *
293 * @deprecated Since 2.8, use {@link #findPropertyIgnorals} instead
294 */
295 @Deprecated // since 2.8
296 public String[] findPropertiesToIgnore(Annotated ac, boolean forSerialization) {
297 return null;
298 }
299
300 /**
301 * @deprecated Since 2.6, use variant that takes second argument.
302 */
303 @Deprecated // since 2.6
304 public String[] findPropertiesToIgnore(Annotated ac) {
305 return null;
306 }
307
308 /**
309 * Method for checking whether an annotation indicates that all unknown properties
310 *
311 * @deprecated Since 2.8, use {@link #findPropertyIgnorals} instead
312 */
313 @Deprecated // since 2.8
314 public Boolean findIgnoreUnknownProperties(AnnotatedClass ac) { return null; }
315
316 /*
317 /**********************************************************
318 /* Property auto-detection
319 /**********************************************************
320 */
321
322 /**
323 * Method for checking if annotations indicate changes to minimum visibility levels
324 * needed for auto-detecting property elements (fields, methods, constructors).
325 * A baseline checker is given, and introspector is to either return it as is
326 * (if no annotations are found), or build and return a derived instance (using
327 * checker's build methods).
328 */
329 public VisibilityChecker<?> findAutoDetectVisibility(AnnotatedClass ac, VisibilityChecker<?> checker) {
330 return checker;
331 }
332
333 /*
334 /**********************************************************
335 /* Annotations for Polymorphic type handling
336 /**********************************************************
337 */
338
339 /**
340 * Method for checking if given class has annotations that indicate
341 * that specific type resolver is to be used for handling instances.
342 * This includes not only
343 * instantiating resolver builder, but also configuring it based on
344 * relevant annotations (not including ones checked with a call to
345 * {@link #findSubtypes}
346 *
347 * @param config Configuration settings in effect (for serialization or deserialization)
348 * @param ac Annotated class to check for annotations
349 * @param baseType Base java type of value for which resolver is to be found
350 *
351 * @return Type resolver builder for given type, if one found; null if none
352 */
353 public TypeResolverBuilder<?> findTypeResolver(MapperConfig<?> config,
354 AnnotatedClass ac, JavaType baseType) {
355 return null;
356 }
357
358 /**
359 * Method for checking if given property entity (field or method) has annotations
360 * that indicate that specific type resolver is to be used for handling instances.
361 * This includes not only
362 * instantiating resolver builder, but also configuring it based on
363 * relevant annotations (not including ones checked with a call to
364 * {@link #findSubtypes}
365 *
366 * @param config Configuration settings in effect (for serialization or deserialization)
367 * @param am Annotated member (field or method) to check for annotations
368 * @param baseType Base java type of property for which resolver is to be found
369 *
370 * @return Type resolver builder for properties of given entity, if one found;
371 * null if none
372 */
373 public TypeResolverBuilder<?> findPropertyTypeResolver(MapperConfig<?> config,
374 AnnotatedMember am, JavaType baseType) {
375 return null;
376 }
377
378 /**
379 * Method for checking if given structured property entity (field or method that
380 * has nominal value of Map, Collection or array type) has annotations
381 * that indicate that specific type resolver is to be used for handling type
382 * information of contained values.
383 * This includes not only
384 * instantiating resolver builder, but also configuring it based on
385 * relevant annotations (not including ones checked with a call to
386 * {@link #findSubtypes}
387 *
388 * @param config Configuration settings in effect (for serialization or deserialization)
389 * @param am Annotated member (field or method) to check for annotations
390 * @param containerType Type of property for which resolver is to be found (must be a container type)
391 *
392 * @return Type resolver builder for values contained in properties of given entity,
393 * if one found; null if none
394 */
395 public TypeResolverBuilder<?> findPropertyContentTypeResolver(MapperConfig<?> config,
396 AnnotatedMember am, JavaType containerType) {
397 return null;
398 }
399
400 /**
401 * Method for locating annotation-specified subtypes related to annotated
402 * entity (class, method, field). Note that this is only guaranteed to be
403 * a list of directly
404 * declared subtypes, no recursive processing is guarantees (i.e. caller
405 * has to do it if/as necessary)
406 *
407 * @param a Annotated entity (class, field/method) to check for annotations
408 */
409 public List<NamedType> findSubtypes(Annotated a) { return null; }
410
411 /**
412 * Method for checking if specified type has explicit name.
413 *
414 * @param ac Class to check for type name annotations
415 */
416 public String findTypeName(AnnotatedClass ac) { return null; }
417
418 /**
419 * Method for checking whether given accessor claims to represent
420 * type id: if so, its value may be used as an override,
421 * instead of generated type id.
422 */
423 public Boolean isTypeId(AnnotatedMember member) { return null; }
424
425 /*
426 /**********************************************************
427 /* General member (field, method/constructor) annotations
428 /**********************************************************
429 */
430
431 /**
432 * Method for checking if given member indicates that it is part
433 * of a reference (parent/child).
434 */
435 public ReferenceProperty findReferenceType(AnnotatedMember member) { return null; }
436
437 /**
438 * Method called to check whether given property is marked to be "unwrapped"
439 * when being serialized (and appropriately handled in reverse direction,
440 * i.e. expect unwrapped representation during deserialization).
441 * Return value is the name transformation to use, if wrapping/unwrapping
442 * should be done, or null if not -- note that transformation may simply
443 * be identity transformation (no changes).
444 */
445 public NameTransformer findUnwrappingNameTransformer(AnnotatedMember member) { return null; }
446
447 /**
448 * Method called to check whether given property is marked to
449 * be ignored. This is used to determine whether to ignore
450 * properties, on per-property basis, usually combining
451 * annotations from multiple accessors (getters, setters, fields,
452 * constructor parameters).
453 */
454 public boolean hasIgnoreMarker(AnnotatedMember m) { return false; }
455
456 /**
457 * Method called to find out whether given member expectes a value
458 * to be injected, and if so, what is the identifier of the value
459 * to use during injection.
460 * Type if identifier needs to be compatible with provider of
461 * values (of type {@link InjectableValues}); often a simple String
462 * id is used.
463 *
464 * @param m Member to check
465 *
466 * @return Identifier of value to inject, if any; null if no injection
467 * indicator is found
468 *
469 * @since 2.9
470 */
471 public JacksonInject.Value findInjectableValue(AnnotatedMember m) {
472 // 05-Apr-2017, tatu: Just for 2.9, call deprecated method to help
473 // with some cases of overrides for legacy code
474 Object id = findInjectableValueId(m);
475 if (id != null) {
476 return JacksonInject.Value.forId(id);
477 }
478 return null;
479 }
480
481 /**
482 * Method that can be called to check whether this member has
483 * an annotation that suggests whether value for matching property
484 * is required or not.
485 */
486 public Boolean hasRequiredMarker(AnnotatedMember m) { return null; }
487
488 /**
489 * Method for checking if annotated property (represented by a field or
490 * getter/setter method) has definitions for views it is to be included in.
491 * If null is returned, no view definitions exist and property is always
492 * included (or always excluded as per default view inclusion configuration);
493 * otherwise it will only be included for views included in returned
494 * array. View matches are checked using class inheritance rules (sub-classes
495 * inherit inclusions of super-classes)
496 *<p>
497 * Since 2.9 this method may also be called to find "default view(s)" for
498 * {@link AnnotatedClass}
499 *
500 * @param a Annotated property (represented by a method, field or ctor parameter)
501 * @return Array of views (represented by classes) that the property is included in;
502 * if null, always included (same as returning array containing <code>Object.class</code>)
503 */
504 public Class<?>[] findViews(Annotated a) { return null; }
505
506 /**
507 * Method for finding format annotations for property or class.
508 * Return value is typically used by serializers and/or
509 * deserializers to customize presentation aspects of the
510 * serialized value.
511 *
512 * @since 2.1
513 */
514 public JsonFormat.Value findFormat(Annotated memberOrClass) {
515 return JsonFormat.Value.empty();
516 }
517
518 /**
519 * Method used to check if specified property has annotation that indicates
520 * that it should be wrapped in an element; and if so, name to use.
521 * Note that not all serializers and deserializers support use this method:
522 * currently (2.1) it is only used by XML-backed handlers.
523 *
524 * @return Wrapper name to use, if any, or {@link PropertyName#USE_DEFAULT}
525 * to indicate that no wrapper element should be used.
526 *
527 * @since 2.1
528 */
529 public PropertyName findWrapperName(Annotated ann) { return null; }
530
531 /**
532 * Method for finding suggested default value (as simple textual serialization)
533 * for the property. While core databind does not make any use of it, it is exposed
534 * for extension modules to use: an expected use is generation of schema representations
535 * and documentation.
536 *
537 * @since 2.5
538 */
539 public String findPropertyDefaultValue(Annotated ann) { return null; }
540
541 /**
542 * Method used to check whether specified property member (accessor
543 * or mutator) defines human-readable description to use for documentation.
544 * There are no further definitions for contents; for example, whether
545 * these may be marked up using HTML is not defined.
546 *
547 * @return Human-readable description, if any.
548 *
549 * @since 2.3
550 */
551 public String findPropertyDescription(Annotated ann) { return null; }
552
553 /**
554 * Method used to check whether specified property member (accessor
555 * or mutator) defines numeric index, and if so, what is the index value.
556 * Possible use cases for index values included use by underlying data format
557 * (some binary formats mandate use of index instead of name) and ordering
558 * of properties (for documentation, or during serialization).
559 *
560 * @since 2.4
561 *
562 * @return Explicitly specified index for the property, if any
563 */
564 public Integer findPropertyIndex(Annotated ann) { return null; }
565
566 /**
567 * Method for finding implicit name for a property that given annotated
568 * member (field, method, creator parameter) may represent.
569 * This is different from explicit, annotation-based property name, in that
570 * it is "weak" and does not either proof that a property exists (for example,
571 * if visibility is not high enough), or override explicit names.
572 * In practice this method is used to introspect optional names for creator
573 * parameters (which may or may not be available and cannot be detected
574 * by standard databind); or to provide alternate name mangling for
575 * fields, getters and/or setters.
576 *
577 * @since 2.4
578 */
579 public String findImplicitPropertyName(AnnotatedMember member) { return null; }
580
581 /**
582 * Method called to find if given property has alias(es) defined.
583 *
584 * @return `null` if member has no information; otherwise a `List` (possibly
585 * empty) of aliases to use.
586 *
587 * @since 2.9
588 */
589 public List<PropertyName> findPropertyAliases(Annotated ann) { return null; }
590
591 /**
592 * Method for finding optional access definition for a property, annotated
593 * on one of its accessors. If a definition for read-only, write-only
594 * or read-write cases, visibility rules may be modified. Note, however,
595 * that even more specific annotations (like one for ignoring specific accessor)
596 * may further override behavior of the access definition.
597 *
598 * @since 2.6
599 */
600 public JsonProperty.Access findPropertyAccess(Annotated ann) { return null; }
601
602 /**
603 * Method called in cases where a class has two methods eligible to be used
604 * for the same logical property, and default logic is not enough to figure
605 * out clear precedence. Introspector may try to choose one to use; or, if
606 * unable, return `null` to indicate it cannot resolve the problem.
607 *
608 * @since 2.7
609 */
610 public AnnotatedMethod resolveSetterConflict(MapperConfig<?> config,
611 AnnotatedMethod setter1, AnnotatedMethod setter2) {
612 return null;
613 }
614
615 /**
616 * Method called on fields that are eligible candidates for properties
617 * (that is, non-static member fields), but not necessarily selected (may
618 * or may not be visible), to let fields affect name linking.
619 * Call will be made after finding implicit name (which by default is just
620 * name of the field, but may be overridden by introspector), but before
621 * discovering other accessors.
622 * If non-null name returned, it is to be used to find other accessors (getters,
623 * setters, creator parameters) and replace their implicit names with that
624 * of field's implicit name (assuming they differ).
625 *<p>
626 * Specific example (and initial use case is for support Kotlin's "is getter"
627 * matching (see
628 * <a href="https://kotlinlang.org/docs/reference/java-to-kotlin-interop.html">Kotling Interop</a>
629 * for details), in which field like '{@code isOpen}' would have implicit name of
630 * "isOpen", match getter {@code getOpen()} and setter {@code setOpen(boolean)},
631 * but use logical external name of "isOpen" (and not implicit name of getter/setter, "open"!).
632 * To achieve this, field implicit name needs to remain "isOpen" but this method needs
633 * to return name {@code PropertyName.construct("open")}: doing so will "pull in" getter
634 * and/or setter, and rename them as "isOpen".
635 *
636 * @param config Effective mapper configuration in use
637 * @param f Field to check
638 * @param implName Implicit name of the field; usually name of field itself but not always,
639 * used as the target name for accessors to rename.
640 *
641 * @return Name used to find other accessors to rename, if any; {@code null} to indicate
642 * no renaming
643 *
644 * @since 2.11
645 */
646 public PropertyName findRenameByField(MapperConfig<?> config,
647 AnnotatedField f, PropertyName implName) {
648 return null;
649 }
650
651 /**
652 * @deprecated Since 2.9 Use {@link #findInjectableValue} instead
653 */
654 @Deprecated // since 2.9
655 public Object findInjectableValueId(AnnotatedMember m) {
656 return null;
657 }
658
659 /*
660 /**********************************************************
661 /* Serialization: general annotations
662 /**********************************************************
663 */
664
665 /**
666 * Method for getting a serializer definition on specified method
667 * or field. Type of definition is either instance (of type {@link JsonSerializer})
668 * or Class (of {@code Class<JsonSerializer>} implementation subtype);
669 * if value of different type is returned, a runtime exception may be thrown by caller.
670 */
671 public Object findSerializer(Annotated am) {
672 return null;
673 }
674
675 /**
676 * Method for getting a serializer definition for keys of associated {@code java.util.Map} property.
677 * Type of definition is either instance (of type {@link JsonSerializer})
678 * or Class (of type {@code Class<JsonSerializer>});
679 * if value of different type is returned, a runtime exception may be thrown by caller.
680 */
681 public Object findKeySerializer(Annotated am) {
682 return null;
683 }
684
685 /**
686 * Method for getting a serializer definition for content (values) of
687 * associated <code>Collection</code>, <code>array</code> or {@code Map} property.
688 * Type of definition is either instance (of type {@link JsonSerializer})
689 * or Class (of type {@code Class<JsonSerializer>});
690 * if value of different
691 * type is returned, a runtime exception may be thrown by caller.
692 */
693 public Object findContentSerializer(Annotated am) {
694 return null;
695 }
696
697 /**
698 * Method for getting a serializer definition for serializer to use
699 * for nulls (null values) of associated property or type.
700 *
701 * @since 2.3
702 */
703 public Object findNullSerializer(Annotated am) {
704 return null;
705 }
706
707 /**
708 * Method for accessing declared typing mode annotated (if any).
709 * This is used for type detection, unless more granular settings
710 * (such as actual exact type; or serializer to use which means
711 * no type information is needed) take precedence.
712 *
713 * @return Typing mode to use, if annotation is found; null otherwise
714 */
715 public JsonSerialize.Typing findSerializationTyping(Annotated a) {
716 return null;
717 }
718
719 /**
720 * Method for finding {@link Converter} that annotated entity
721 * (property or class) has indicated to be used as part of
722 * serialization. If not null, either has to be actual
723 * {@link Converter} instance, or class for such converter;
724 * and resulting converter will be used first to convert property
725 * value to converter target type, and then serializer for that
726 * type is used for actual serialization.
727 *<p>
728 * This feature is typically used to convert internal values into types
729 * that Jackson can convert.
730 *<p>
731 * Note also that this feature does not necessarily work well with polymorphic
732 * type handling, or object identity handling; if such features are needed
733 * an explicit serializer is usually better way to handle serialization.
734 *
735 * @param a Annotated property (field, method) or class to check for
736 * annotations
737 *
738 * @since 2.2
739 */
740 public Object findSerializationConverter(Annotated a) {
741 return null;
742 }
743
744 /**
745 * Method for finding {@link Converter} that annotated property
746 * has indicated needs to be used for values of container type
747 * (this also means that method should only be called for properties
748 * of container types, List/Map/array properties).
749 *<p>
750 * If not null, either has to be actual
751 * {@link Converter} instance, or class for such converter;
752 * and resulting converter will be used first to convert property
753 * value to converter target type, and then serializer for that
754 * type is used for actual serialization.
755 *<p>
756 * Other notes are same as those for {@link #findSerializationConverter}
757 *
758 * @param a Annotated property (field, method) to check.
759 *
760 * @since 2.2
761 */
762 public Object findSerializationContentConverter(AnnotatedMember a) {
763 return null;
764 }
765
766 /**
767 * Method for checking inclusion criteria for a type (Class) or property (yes, method
768 * name is bit unfortunate -- not just for properties!).
769 * In case of class, acts as the default for properties POJO contains; for properties
770 * acts as override for class defaults and possible global defaults.
771 *
772 * @since 2.6
773 */
774 public JsonInclude.Value findPropertyInclusion(Annotated a) {
775 return JsonInclude.Value.empty();
776 }
777
778 /**
779 * Method for checking whether given annotated entity (class, method,
780 * field) defines which Bean/Map properties are to be included in
781 * serialization.
782 * If no annotation is found, method should return given second
783 * argument; otherwise value indicated by the annotation.
784 *<p>
785 * Note that meaning of inclusion value depends on whether it is for
786 * a Class or property (field/method/constructor): in former case,
787 * it is the default for all properties; in latter case it is specific
788 * override for annotated property.
789 *
790 * @return Enumerated value indicating which properties to include
791 * in serialization
792 *
793 * @deprecated Since 2.7 Use {@link #findPropertyInclusion} instead
794 */
795 @Deprecated // since 2.7
796 public JsonInclude.Include findSerializationInclusion(Annotated a, JsonInclude.Include defValue) {
797 return defValue;
798 }
799
800 /**
801 * Method for checking whether content (entries) of a {@link java.util.Map} property
802 * are to be included during serialization or not.
803 * NOTE: this is NOT called for POJO properties, or array/Collection elements.
804 *
805 * @since 2.5
806 *
807 * @deprecated Since 2.7 Use {@link #findPropertyInclusion} instead
808 */
809 @Deprecated // since 2.7
810 public JsonInclude.Include findSerializationInclusionForContent(Annotated a, JsonInclude.Include defValue) {
811 return defValue;
812 }
813
814 /*
815 /**********************************************************
816 /* Serialization: type refinements
817 /**********************************************************
818 */
819
820 /**
821 * Method called to find out possible type refinements to use
822 * for deserialization, including not just value itself but
823 * key and/or content type, if type has those.
824 *
825 * @since 2.7
826 */
827 public JavaType refineSerializationType(final MapperConfig<?> config,
828 final Annotated a, final JavaType baseType) throws JsonMappingException
829 {
830 return baseType;
831 }
832
833 /**
834 * @deprecated Since 2.7 call {@link #refineSerializationType} instead
835 */
836 @Deprecated // since 2.7
837 public Class<?> findSerializationType(Annotated a) {
838 return null;
839 }
840
841 /**
842 * @deprecated Since 2.7 call {@link #refineSerializationType} instead
843 */
844 @Deprecated // since 2.7
845 public Class<?> findSerializationKeyType(Annotated am, JavaType baseType) {
846 return null;
847 }
848
849 /**
850 * @deprecated Since 2.7 call {@link #refineSerializationType} instead
851 */
852 @Deprecated // since 2.7
853 public Class<?> findSerializationContentType(Annotated am, JavaType baseType) {
854 return null;
855 }
856
857 /*
858 /**********************************************************
859 /* Serialization: class annotations
860 /**********************************************************
861 */
862
863 /**
864 * Method for accessing defined property serialization order (which may be
865 * partial). May return null if no ordering is defined.
866 */
867 public String[] findSerializationPropertyOrder(AnnotatedClass ac) {
868 return null;
869 }
870
871 /**
872 * Method for checking whether an annotation indicates that serialized properties
873 * for which no explicit is defined should be alphabetically (lexicograpically)
874 * ordered
875 */
876 public Boolean findSerializationSortAlphabetically(Annotated ann) {
877 return null;
878 }
879
880 /**
881 * Method for adding possible virtual properties to be serialized along
882 * with regular properties.
883 *
884 * @since 2.5
885 */
886 public void findAndAddVirtualProperties(MapperConfig<?> config, AnnotatedClass ac,
887 List<BeanPropertyWriter> properties) { }
888
889 /*
890 /**********************************************************
891 /* Serialization: property annotations
892 /**********************************************************
893 */
894
895 /**
896 * Method for checking whether given property accessors (method,
897 * field) has an annotation that suggests property name to use
898 * for serialization.
899 * Should return null if no annotation
900 * is found; otherwise a non-null name (possibly
901 * {@link PropertyName#USE_DEFAULT}, which means "use default heuristics").
902 *
903 * @param a Property accessor to check
904 *
905 * @return Name to use if found; null if not.
906 *
907 * @since 2.1
908 */
909 public PropertyName findNameForSerialization(Annotated a) {
910 return null;
911 }
912
913 /**
914 * Method for checking whether given method has an annotation
915 * that suggests that the return value of annotated method
916 * should be used as "the value" of the object instance; usually
917 * serialized as a primitive value such as String or number.
918 *
919 * @return {@link Boolean#TRUE} if such annotation is found and is not disabled;
920 * {@link Boolean#FALSE} if disabled annotation (block) is found (to indicate
921 * accessor is definitely NOT to be used "as value"); or `null` if no
922 * information found.
923 *
924 * @since 2.9
925 */
926 public Boolean hasAsValue(Annotated a) {
927 // 20-Nov-2016, tatu: Delegate in 2.9; remove redirect from later versions
928 if (a instanceof AnnotatedMethod) {
929 if (hasAsValueAnnotation((AnnotatedMethod) a)) {
930 return true;
931 }
932 }
933 return null;
934 }
935
936 /**
937 * Method for checking whether given method has an annotation
938 * that suggests that the method is to serve as "any setter";
939 * method to be used for accessing set of miscellaneous "extra"
940 * properties, often bound with matching "any setter" method.
941 *
942 * @return True if such annotation is found (and is not disabled),
943 * false otherwise
944 *
945 * @since 2.9
946 */
947 public Boolean hasAnyGetter(Annotated a) {
948
949 // 21-Nov-2016, tatu: Delegate in 2.9; remove redirect from later versions
950 if (a instanceof AnnotatedMethod) {
951 if (hasAnyGetterAnnotation((AnnotatedMethod) a)) {
952 return true;
953 }
954 }
955 return null;
956 }
957
958 /**
959 * Method for efficiently figuring out which if given set of <code>Enum</code> values
960 * have explicitly defined name. Method will overwrite entries in incoming <code>names</code>
961 * array with explicit names found, if any, leaving other entries unmodified.
962 *
963 * @since 2.7
964 */
965 public String[] findEnumValues(Class<?> enumType, Enum<?>[] enumValues, String[] names) {
966 // 18-Oct-2016, tatu: In 2.8 delegated to deprecated method; not so in 2.9 and beyond
967 return names;
968 }
969
970 /**
971 * Method that is related to {@link #findEnumValues} but is called to check if
972 * there are alternative names (aliased) that can be accepted for entries, in
973 * addition to primary names introspected earlier.
974 * If so, these aliases should be returned in {@code aliases} {@link List} passed
975 * as argument (and initialized for proper size by caller).
976 *
977 * @since 2.11
978 */
979 public void findEnumAliases(Class<?> enumType, Enum<?>[] enumValues, String[][] aliases) {
980 ;
981 }
982
983 /**
984 * Finds the Enum value that should be considered the default value, if possible.
985 *
986 * @param enumCls The Enum class to scan for the default value.
987 * @return null if none found or it's not possible to determine one.
988 *
989 * @since 2.8
990 */
991 public Enum<?> findDefaultEnumValue(Class<Enum<?>> enumCls) {
992 return null;
993 }
994
995 /**
996 * Method for determining the String value to use for serializing
997 * given enumeration entry; used when serializing enumerations
998 * as Strings (the standard method).
999 *
1000 * @return Serialized enum value.
1001 *
1002 * @deprecated Since 2.8: use {@link #findEnumValues} instead because this method
1003 * does not properly handle override settings (defaults to <code>enum.name</code>
1004 * without indicating whether that is explicit or not), and is inefficient to
1005 * call one-by-one.
1006 */
1007 @Deprecated
1008 public String findEnumValue(Enum<?> value) {
1009 return value.name();
1010 }
1011
1012 /**
1013 * @deprecated Since 2.9 Use {@link #hasAsValue(Annotated)} instead.
1014 */
1015 @Deprecated // since 2.9
1016 public boolean hasAsValueAnnotation(AnnotatedMethod am) {
1017 return false;
1018 }
1019
1020 /**
1021 * @deprecated Since 2.9 Use {@link #hasAnyGetter} instead
1022 */
1023 @Deprecated
1024 public boolean hasAnyGetterAnnotation(AnnotatedMethod am) {
1025 return false;
1026 }
1027
1028 /*
1029 /**********************************************************
1030 /* Deserialization: general annotations
1031 /**********************************************************
1032 */
1033
1034 /**
1035 * Method for getting a deserializer definition on specified method
1036 * or field.
1037 * Type of definition is either instance (of type {@link JsonDeserializer})
1038 * or Class (of type {@code Class&<JsonDeserializer>});
1039 * type is returned, a runtime exception may be thrown by caller.
1040 */
1041 public Object findDeserializer(Annotated am) {
1042 return null;
1043 }
1044
1045 /**
1046 * Method for getting a deserializer definition for keys of
1047 * associated <code>Map</code> property.
1048 * Type of definition is either instance (of type {@link JsonDeserializer})
1049 * or Class (of type {@code Class<JsonDeserializer>});
1050 * if value of different
1051 * type is returned, a runtime exception may be thrown by caller.
1052 */
1053 public Object findKeyDeserializer(Annotated am) {
1054 return null;
1055 }
1056
1057 /**
1058 * Method for getting a deserializer definition for content (values) of
1059 * associated <code>Collection</code>, <code>array</code> or
1060 * <code>Map</code> property.
1061 * Type of definition is either instance (of type {@link JsonDeserializer})
1062 * or Class (of type {@code Class<JsonDeserializer>});
1063 * if value of different
1064 * type is returned, a runtime exception may be thrown by caller.
1065 */
1066 public Object findContentDeserializer(Annotated am) {
1067 return null;
1068 }
1069
1070 /**
1071 * Method for finding {@link Converter} that annotated entity
1072 * (property or class) has indicated to be used as part of
1073 * deserialization.
1074 * If not null, either has to be actual
1075 * {@link Converter} instance, or class for such converter;
1076 * and resulting converter will be used after Jackson has deserializer
1077 * data into intermediate type (Converter input type), and Converter
1078 * needs to convert this into its target type to be set as property value.
1079 *<p>
1080 * This feature is typically used to convert intermediate Jackson types
1081 * (that default deserializers can produce) into custom type instances.
1082 *<p>
1083 * Note also that this feature does not necessarily work well with polymorphic
1084 * type handling, or object identity handling; if such features are needed
1085 * an explicit deserializer is usually better way to handle deserialization.
1086 *
1087 * @param a Annotated property (field, method) or class to check for
1088 * annotations
1089 *
1090 * @since 2.2
1091 */
1092 public Object findDeserializationConverter(Annotated a) {
1093 return null;
1094 }
1095
1096 /**
1097 * Method for finding {@link Converter} that annotated property
1098 * has indicated needs to be used for values of container type
1099 * (this also means that method should only be called for properties
1100 * of container types, List/Map/array properties).
1101 *<p>
1102 * If not null, either has to be actual
1103 * {@link Converter} instance, or class for such converter;
1104 * and resulting converter will be used after Jackson has deserializer
1105 * data into intermediate type (Converter input type), and Converter
1106 * needs to convert this into its target type to be set as property value.
1107 *<p>
1108 * Other notes are same as those for {@link #findDeserializationConverter}
1109 *
1110 * @param a Annotated property (field, method) to check.
1111 *
1112 * @since 2.2
1113 */
1114 public Object findDeserializationContentConverter(AnnotatedMember a) {
1115 return null;
1116 }
1117
1118 /*
1119 /**********************************************************
1120 /* Deserialization: type refinements
1121 /**********************************************************
1122 */
1123
1124 /**
1125 * Method called to find out possible type refinements to use
1126 * for deserialization.
1127 *
1128 * @since 2.7
1129 */
1130 public JavaType refineDeserializationType(final MapperConfig<?> config,
1131 final Annotated a, final JavaType baseType) throws JsonMappingException
1132 {
1133 return baseType;
1134 }
1135
1136 /**
1137 * Method for accessing annotated type definition that a
1138 * property can have, to be used as the type for deserialization
1139 * instead of the static (declared) type.
1140 * Type is usually narrowing conversion (i.e.subtype of declared type).
1141 * Declared return type of the method is also considered acceptable.
1142 *
1143 * @param baseType Assumed type before considering annotations
1144 *
1145 * @return Class to use for deserialization instead of declared type
1146 *
1147 * @deprecated Since 2.7 call {@link #refineDeserializationType} instead
1148 */
1149 @Deprecated
1150 public Class<?> findDeserializationType(Annotated am, JavaType baseType) {
1151 return null;
1152 }
1153
1154 /**
1155 * Method for accessing additional narrowing type definition that a
1156 * method can have, to define more specific key type to use.
1157 * It should be only be used with {@link java.util.Map} types.
1158 *
1159 * @param baseKeyType Assumed key type before considering annotations
1160 *
1161 * @return Class specifying more specific type to use instead of
1162 * declared type, if annotation found; null if not
1163 *
1164 * @deprecated Since 2.7 call {@link #refineDeserializationType} instead
1165 */
1166 @Deprecated
1167 public Class<?> findDeserializationKeyType(Annotated am, JavaType baseKeyType) {
1168 return null;
1169 }
1170
1171 /**
1172 * Method for accessing additional narrowing type definition that a
1173 * method can have, to define more specific content type to use;
1174 * content refers to Map values and Collection/array elements.
1175 * It should be only be used with Map, Collection and array types.
1176 *
1177 * @param baseContentType Assumed content (value) type before considering annotations
1178 *
1179 * @return Class specifying more specific type to use instead of
1180 * declared type, if annotation found; null if not
1181 *
1182 * @deprecated Since 2.7 call {@link #refineDeserializationType} instead
1183 */
1184 @Deprecated
1185 public Class<?> findDeserializationContentType(Annotated am, JavaType baseContentType) {
1186 return null;
1187 }
1188
1189 /*
1190 /**********************************************************
1191 /* Deserialization: class annotations
1192 /**********************************************************
1193 */
1194
1195 /**
1196 * Method getting {@link ValueInstantiator} to use for given
1197 * type (class): return value can either be an instance of
1198 * instantiator, or class of instantiator to create.
1199 */
1200 public Object findValueInstantiator(AnnotatedClass ac) {
1201 return null;
1202 }
1203
1204 /**
1205 * Method for finding Builder object to use for constructing
1206 * value instance and binding data (sort of combining value
1207 * instantiators that can construct, and deserializers
1208 * that can bind data).
1209 *<p>
1210 * Note that unlike accessors for some helper Objects, this
1211 * method does not allow returning instances: the reason is
1212 * that builders have state, and a separate instance needs
1213 * to be created for each deserialization call.
1214 *
1215 * @since 2.0
1216 */
1217 public Class<?> findPOJOBuilder(AnnotatedClass ac) {
1218 return null;
1219 }
1220
1221 /**
1222 * @since 2.0
1223 */
1224 public JsonPOJOBuilder.Value findPOJOBuilderConfig(AnnotatedClass ac) {
1225 return null;
1226 }
1227
1228 /*
1229 /**********************************************************
1230 /* Deserialization: property annotations
1231 /**********************************************************
1232 */
1233
1234 /**
1235 * Method for checking whether given property accessors (method,
1236 * field) has an annotation that suggests property name to use
1237 * for deserialization (reading JSON into POJOs).
1238 * Should return null if no annotation
1239 * is found; otherwise a non-null name (possibly
1240 * {@link PropertyName#USE_DEFAULT}, which means "use default heuristics").
1241 *
1242 * @param a Property accessor to check
1243 *
1244 * @return Name to use if found; null if not.
1245 *
1246 * @since 2.1
1247 */
1248 public PropertyName findNameForDeserialization(Annotated a) {
1249 return null;
1250 }
1251
1252 /**
1253 * Method for checking whether given method has an annotation
1254 * that suggests that the method is to serve as "any setter";
1255 * method to be used for setting values of any properties for
1256 * which no dedicated setter method is found.
1257 *
1258 * @return True if such annotation is found (and is not disabled),
1259 * false otherwise
1260 *
1261 * @since 2.9
1262 */
1263 public Boolean hasAnySetter(Annotated a) {
1264 return null;
1265 }
1266
1267 /**
1268 * Method for finding possible settings for property, given annotations
1269 * on an accessor.
1270 *
1271 * @since 2.9
1272 */
1273 public JsonSetter.Value findSetterInfo(Annotated a) {
1274 return JsonSetter.Value.empty();
1275 }
1276
1277 /**
1278 * Method for finding merge settings for property, if any.
1279 *
1280 * @since 2.9
1281 */
1282 public Boolean findMergeInfo(Annotated a) {
1283 return null;
1284 }
1285
1286 /**
1287 * Method called to check whether potential Creator (constructor or static factory
1288 * method) has explicit annotation to indicate it as actual Creator; and if so,
1289 * which {@link com.fasterxml.jackson.annotation.JsonCreator.Mode} to use.
1290 *<p>
1291 * NOTE: caller needs to consider possibility of both `null` (no annotation found)
1292 * and {@link com.fasterxml.jackson.annotation.JsonCreator.Mode#DISABLED} (annotation found,
1293 * but disabled); latter is necessary as marker in case multiple introspectors are chained,
1294 * as well as possibly as when using mix-in annotations.
1295 *
1296 * @param config Configuration settings in effect (for serialization or deserialization)
1297 * @param a Annotated accessor (usually constructor or static method) to check
1298 *
1299 * @since 2.9
1300 */
1301 public JsonCreator.Mode findCreatorAnnotation(MapperConfig<?> config, Annotated a) {
1302 // 13-Sep-2016, tatu: for backwards compatibility, implement using delegation
1303 /// (remove from version AFTER 2.9)
1304 if (hasCreatorAnnotation(a)) {
1305 JsonCreator.Mode mode = findCreatorBinding(a);
1306 if (mode == null) {
1307 mode = JsonCreator.Mode.DEFAULT;
1308 }
1309 return mode;
1310 }
1311 return null;
1312 }
1313
1314 /**
1315 * Method for checking whether given annotated item (method, constructor)
1316 * has an annotation
1317 * that suggests that the method is a "creator" (aka factory)
1318 * method to be used for construct new instances of deserialized
1319 * values.
1320 *
1321 * @return True if such annotation is found (and is not disabled),
1322 * false otherwise
1323 *
1324 * @deprecated Since 2.9 use {@link #findCreatorAnnotation} instead.
1325 */
1326 @Deprecated
1327 public boolean hasCreatorAnnotation(Annotated a) {
1328 return false;
1329 }
1330
1331 /**
1332 * Method for finding indication of creator binding mode for
1333 * a creator (something for which {@link #hasCreatorAnnotation} returns
1334 * true), for cases where there may be ambiguity (currently: single-argument
1335 * creator with implicit but no explicit name for the argument).
1336 *
1337 * @since 2.5
1338 * @deprecated Since 2.9 use {@link #findCreatorAnnotation} instead.
1339 */
1340 @Deprecated
1341 public JsonCreator.Mode findCreatorBinding(Annotated a) {
1342 return null;
1343 }
1344
1345 /**
1346 * @deprecated Since 2.9 use {@link #hasAnySetter} instead.
1347 */
1348 @Deprecated // since 2.9
1349 public boolean hasAnySetterAnnotation(AnnotatedMethod am) {
1350 return false;
1351 }
1352
1353 /*
1354 /**********************************************************
1355 /* Overridable methods: may be used as low-level extension
1356 /* points.
1357 /**********************************************************
1358 */
1359
1360 /**
1361 * Method that should be used by sub-classes for ALL
1362 * annotation access;
1363 * overridable so
1364 * that sub-classes may, if they choose to, mangle actual access to
1365 * block access ("hide" annotations) or perhaps change it.
1366 *<p>
1367 * Default implementation is simply:
1368 *<code>
1369 * return annotated.getAnnotation(annoClass);
1370 *</code>
1371 *
1372 * @since 2.5
1373 */
1374 protected <A extends Annotation> A _findAnnotation(Annotated annotated,
1375 Class<A> annoClass) {
1376 return annotated.getAnnotation(annoClass);
1377 }
1378
1379 /**
1380 * Method that should be used by sub-classes for ALL
1381 * annotation existence access;
1382 * overridable so that sub-classes may, if they choose to, mangle actual access to
1383 * block access ("hide" annotations) or perhaps change value seen.
1384 *<p>
1385 * Default implementation is simply:
1386 *<code>
1387 * return annotated.hasAnnotation(annoClass);
1388 *</code>
1389 *
1390 * @since 2.5
1391 */
1392 protected boolean _hasAnnotation(Annotated annotated, Class<? extends Annotation> annoClass) {
1393 return annotated.hasAnnotation(annoClass);
1394 }
1395
1396 /**
1397 * Alternative lookup method that is used to see if annotation has at least one of
1398 * annotations of types listed in second argument.
1399 *
1400 * @since 2.7
1401 */
1402 protected boolean _hasOneOf(Annotated annotated, Class<? extends Annotation>[] annoClasses) {
1403 return annotated.hasOneOf(annoClasses);
1404 }
1405 }
1406