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