1 package com.fasterxml.jackson.databind.ser;
2 
3 import java.lang.annotation.Annotation;
4 
5 import com.fasterxml.jackson.core.JsonGenerator;
6 import com.fasterxml.jackson.databind.*;
7 import com.fasterxml.jackson.databind.introspect.BeanPropertyDefinition;
8 import com.fasterxml.jackson.databind.introspect.ConcreteBeanPropertyBase;
9 import com.fasterxml.jackson.databind.jsonFormatVisitors.JsonObjectFormatVisitor;
10 import com.fasterxml.jackson.databind.node.ObjectNode;
11 
12 /**
13  * Base class for writers used to output property values (name-value pairs)
14  * as key/value pairs via streaming API. This is the most generic abstraction
15  * implemented by both POJO and {@link java.util.Map} serializers, and invoked
16  * by filtering functionality.
17  *
18  * @since 2.3
19  */
20 public abstract class PropertyWriter
21     extends ConcreteBeanPropertyBase // since 2.7
22     implements java.io.Serializable
23 {
24     private static final long serialVersionUID = 1L;
25 
PropertyWriter(PropertyMetadata md)26     protected PropertyWriter(PropertyMetadata md) {
27         super(md);
28     }
29 
PropertyWriter(BeanPropertyDefinition propDef)30     protected PropertyWriter(BeanPropertyDefinition propDef) {
31         super(propDef.getMetadata());
32     }
33 
PropertyWriter(PropertyWriter base)34     protected PropertyWriter(PropertyWriter base) {
35         super(base);
36     }
37 
38     /*
39     /**********************************************************
40     /* Metadata access
41     /**********************************************************
42      */
43 
44     @Override
getName()45     public abstract String getName();
46 
47     @Override
getFullName()48     public abstract PropertyName getFullName();
49 
50     /**
51      * Convenience method for accessing annotation that may be associated
52      * either directly on property, or, if not, via enclosing class (context).
53      * This allows adding baseline contextual annotations, for example, by adding
54      * an annotation for a given class and making that apply to all properties
55      * unless overridden by per-property annotations.
56      *<p>
57      * This method is functionally equivalent to:
58      *<pre>
59      *  MyAnnotation ann = propWriter.getAnnotation(MyAnnotation.class);
60      *  if (ann == null) {
61      *    ann = propWriter.getContextAnnotation(MyAnnotation.class);
62      *  }
63      *</pre>
64      * that is, tries to find a property annotation first, but if one is not
65      * found, tries to find context-annotation (from enclosing class) of
66      * same type.
67      *
68      * @since 2.5
69      */
findAnnotation(Class<A> acls)70     public <A extends Annotation> A findAnnotation(Class<A> acls) {
71         A ann = getAnnotation(acls);
72         if (ann == null) {
73             ann = getContextAnnotation(acls);
74         }
75         return ann;
76     }
77 
78     /**
79      * Method for accessing annotations directly declared for property that this
80      * writer is associated with.
81      *
82      * @since 2.5
83      */
84     @Override
getAnnotation(Class<A> acls)85     public abstract <A extends Annotation> A getAnnotation(Class<A> acls);
86 
87     /**
88      * Method for accessing annotations declared in context of the property that this
89      * writer is associated with; usually this means annotations on enclosing class
90      * for property.
91      *
92      * @since 2.5
93      */
94     @Override
getContextAnnotation(Class<A> acls)95     public abstract <A extends Annotation> A getContextAnnotation(Class<A> acls);
96 
97     /*
98     /**********************************************************
99     /* Serialization methods, regular output
100     /**********************************************************
101      */
102 
103     /**
104      * The main serialization method called by filter when property is to be written normally.
105      */
serializeAsField(Object value, JsonGenerator jgen, SerializerProvider provider)106     public abstract void serializeAsField(Object value, JsonGenerator jgen, SerializerProvider provider)
107         throws Exception;
108 
109     /**
110      * Serialization method that filter needs to call in cases where property is to be
111      * filtered, but the underlying data format requires a placeholder of some kind.
112      * This is usually the case for tabular (positional) data formats such as CSV.
113      */
serializeAsOmittedField(Object value, JsonGenerator jgen, SerializerProvider provider)114     public abstract void serializeAsOmittedField(Object value, JsonGenerator jgen, SerializerProvider provider)
115         throws Exception;
116 
117     /*
118     /**********************************************************
119     /* Serialization methods, explicit positional/tabular formats
120     /**********************************************************
121      */
122 
123     /**
124      * Serialization method called when output is to be done as an array,
125      * that is, not using property names. This is needed when serializing
126      * container ({@link java.util.Collection}, array) types,
127      * or POJOs using <code>tabular</code> ("as array") output format.
128      *<p>
129      * Note that this mode of operation is independent of underlying
130      * data format; so it is typically NOT called for fully tabular formats such as CSV,
131      * where logical output is still as form of POJOs.
132      */
serializeAsElement(Object value, JsonGenerator jgen, SerializerProvider provider)133     public abstract void serializeAsElement(Object value, JsonGenerator jgen, SerializerProvider provider)
134         throws Exception;
135 
136     /**
137      * Serialization method called when doing tabular (positional) output from databind,
138      * but then value is to be omitted. This requires output of a placeholder value
139      * of some sort; often similar to {@link #serializeAsOmittedField}.
140      */
serializeAsPlaceholder(Object value, JsonGenerator jgen, SerializerProvider provider)141     public abstract void serializeAsPlaceholder(Object value, JsonGenerator jgen, SerializerProvider provider)
142         throws Exception;
143 
144     /*
145     /**********************************************************
146     /* Schema-related
147     /**********************************************************
148      */
149 
150     /**
151      * Traversal method used for things like JSON Schema generation, or
152      * POJO introspection.
153      */
154     @Override
depositSchemaProperty(JsonObjectFormatVisitor objectVisitor, SerializerProvider provider)155     public abstract void depositSchemaProperty(JsonObjectFormatVisitor objectVisitor,
156             SerializerProvider provider)
157         throws JsonMappingException;
158 
159     /**
160      * Legacy method called for JSON Schema generation; should not be called by new code
161      *
162      * @deprecated Since 2.2
163      */
164     @Deprecated
depositSchemaProperty(ObjectNode propertiesNode, SerializerProvider provider)165     public abstract void depositSchemaProperty(ObjectNode propertiesNode, SerializerProvider provider)
166         throws JsonMappingException;
167 }
168