1616 * Abstract class that defines API used by {@link ObjectMapper} (and
1717 * other chained {@link JsonSerializer}s too) to serialize Objects of
1818 * arbitrary types into JSON, using provided {@link JsonGenerator}.
19- * {@link com.fasterxml.jackson.databind.ser.std.StdSerializer} instead
20- * of this class, since it will implement many of optional
21- * methods of this class.
22- *<p>
23- * NOTE: various <code>serialize</code> methods are never (to be) called
24- * with null values -- caller <b>must</b> handle null values, usually
25- * by calling {@link SerializerProvider#findNullValueSerializer} to obtain
26- * serializer to use.
27- * This also means that custom serializers cannot be directly used to change
28- * the output to produce when serializing null values.
19+ * Note that although API is defined here, custom serializer implementations
20+ * should almost always be based on {@link com.fasterxml.jackson.databind.ser.std.StdSerializer}
21+ * since it will implement many of optional methods of this class.
2922 *<p>
3023 * If serializer is an aggregate one -- meaning it delegates handling of some
3124 * of its contents by using other serializer(s) -- it typically also needs
3528 * resolution of secondary serializers (which may have cyclic link back
3629 * to serializer itself, directly or indirectly).
3730 *<p>
38- * In addition, to support per-property annotations (to configure aspects
39- * of serialization on per-property basis), serializers may want
40- * to implement
41- * {@link com.fasterxml.jackson.databind.ser.ContextualSerializer},
42- * which allows specialization of serializers: call to
43- * {@link com.fasterxml.jackson.databind.ser.ContextualSerializer#createContextual}
44- * is passed information on property, and can create a newly configured
45- * serializer for handling that particular property.
31+ * Initialization of serializers is handled by two main methods:
32+ *<ol>
33+ * <li>{@link #resolve}: called after instance is configured to be used for specific type,
34+ * but without yet knowing property it will be used for (or, in case of root values, without property).
35+ * Method needs to be implemented for serializers that may work on cyclic types, and specifically
36+ * is implemented by standard POJO serializer ({@code BeanSerializer}). It is usually not needed for
37+ * container types as their type definitions are not cyclic, unlike some POJO types.
38+ * <li>{@link #createContextual}: called on resolved instance (whether newly created, or found via cache),
39+ * when serializer is to be used for specific property, or as root value serializer (no referring property).
40+ * It is used to apply annotations from property accessors (getter, field), and may also be used for resolving
41+ * nested types for container serializers (such as ones for {@link java.util.Collection}s).
42+ * </ol>
43+ * Caching of serializers occurs after {@link #resolve} is called: cached instances are not contextual.
4644 *<p>
47- * Resolution of serializers occurs before contextualization.
45+ * NOTE: various <code>serialize</code> methods are never (to be) called
46+ * with null values -- caller <b>must</b> handle null values, usually
47+ * by calling {@link SerializerProvider#findNullValueSerializer} to obtain
48+ * serializer to use.
49+ * This also means that custom serializers cannot be directly used to change
50+ * the output to produce when serializing null values.
4851 */
4952public abstract class JsonSerializer <T >
5053 implements JsonFormatVisitable
5154{
5255 /*
5356 /**********************************************************
54- /* Initialization, with former `ResolvableSerializer`
57+ /* Initialization, with former `ResolvableSerializer`,
58+ /* `ContextualSerializer`.
5559 /**********************************************************
5660 */
5761
@@ -71,6 +75,35 @@ public void resolve(SerializerProvider provider) throws JsonMappingException {
7175 // Default implementation does nothing
7276 }
7377
78+ /**
79+ * Method called to see if a different (or differently configured) serializer
80+ * is needed to serialize values of specified property (or, for root values, in which
81+ * case `null` is passed).
82+ * Note that instance that this method is called on is typically shared one and
83+ * as a result method should <b>NOT</b> modify this instance but rather construct
84+ * and return a new instance. This instance should only be returned as-is, in case
85+ * it is already suitable for use.
86+ *<p>
87+ * Note that method is only called once per POJO property, and for the first usage as root
88+ * value serializer; it is not called for every serialization, as doing that would have
89+ * significant performance impact; most serializers cache contextual instances for future
90+ * use.
91+ *
92+ * @param prov Serializer provider to use for accessing config, other serializers
93+ * @param property Property (defined by one or more accessors - field or method - used
94+ * for accessing logical property value) for which serializer is used to be used;
95+ * or, `null` for root value (or in cases where caller does not have this information,
96+ * which is handled as root value case).
97+ *
98+ * @return Serializer to use for serializing values of specified property;
99+ * may be this instance or a new instance.
100+ */
101+ public JsonSerializer <?> createContextual (SerializerProvider prov ,
102+ BeanProperty property ) throws JsonMappingException {
103+ // default implementation returns instance unmodified
104+ return this ;
105+ }
106+
74107 /*
75108 /**********************************************************
76109 /* Fluent factory methods for constructing decorated versions
0 commit comments