1 package com.fasterxml.jackson.databind.annotation; 2 3 import java.lang.annotation.ElementType; 4 import java.lang.annotation.Retention; 5 import java.lang.annotation.RetentionPolicy; 6 import java.lang.annotation.Target; 7 8 import com.fasterxml.jackson.databind.*; 9 import com.fasterxml.jackson.databind.util.Converter; 10 11 /** 12 * Annotation used for configuring serialization aspects, by attaching 13 * to "getter" methods or fields, or to value classes. 14 * When annotating value classes, configuration is used for instances 15 * of the value class but can be overridden by more specific annotations 16 * (ones that attach to methods or fields). 17 *<p> 18 * An example annotation would be: 19 *<pre> 20 * @JsonSerialize(using=MySerializer.class, 21 * as=MySubClass.class, 22 * typing=JsonSerialize.Typing.STATIC 23 * ) 24 *</pre> 25 * (which would be redundant, since some properties block others: 26 * specifically, 'using' has precedence over 'as', which has precedence 27 * over 'typing' setting) 28 */ 29 @Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.TYPE, ElementType.PARAMETER}) 30 @Retention(RetentionPolicy.RUNTIME) 31 @com.fasterxml.jackson.annotation.JacksonAnnotation 32 public @interface JsonSerialize 33 { 34 // // // Annotations for explicitly specifying deserializer 35 36 /** 37 * Serializer class to use for 38 * serializing associated value. Depending on what is annotated, 39 * value is either an instance of annotated class (used globablly 40 * anywhere where class serializer is needed); or only used for 41 * serializing property access via a getter method. 42 */ 43 @SuppressWarnings("rawtypes") // to work around JDK8 bug wrt Class-valued annotation properties using()44 public Class<? extends JsonSerializer> using() default JsonSerializer.None.class; 45 46 /** 47 * Serializer class to use for serializing contents (elements 48 * of a Collection/array, values of Maps) of annotated property. 49 * Can only be used on properties (methods, fields, constructors), 50 * and not value classes themselves (as they are typically generic) 51 */ 52 @SuppressWarnings("rawtypes") // to work around JDK8 bug wrt Class-valued annotation properties contentUsing()53 public Class<? extends JsonSerializer> contentUsing() 54 default JsonSerializer.None.class; 55 56 /** 57 * Serializer class to use for serializing Map keys 58 * of annotated property. 59 * Can only be used on properties (methods, fields, constructors), 60 * and not value classes themselves. 61 */ 62 @SuppressWarnings("rawtypes") // to work around JDK8 bug wrt Class-valued annotation properties keyUsing()63 public Class<? extends JsonSerializer> keyUsing() 64 default JsonSerializer.None.class; 65 66 /** 67 * Serializer class to use for serializing nulls for properties that 68 * are annotated, instead of the 69 * default null serializer. 70 * Note that using this property when annotation types (classes) has 71 * no effect currently (it is possible this could be improved in future). 72 * 73 * @since 2.3 74 */ 75 @SuppressWarnings("rawtypes") // to work around JDK8 bug wrt Class-valued annotation properties nullsUsing()76 public Class<? extends JsonSerializer> nullsUsing() 77 default JsonSerializer.None.class; 78 79 // // // Annotations for type handling, explicit declaration 80 // // // (type used for choosing deserializer, if not explicitly 81 // // // specified) 82 83 /** 84 * Supertype (of declared type, which itself is supertype of runtime type) 85 * to use as type when locating serializer to use. 86 *<p> 87 * Bogus type {@link Void} can be used to indicate that declared 88 * type is used as is (i.e. this annotation property has no setting); 89 * this since annotation properties are not allowed to have null value. 90 *<p> 91 * Note: if {@link #using} is also used it has precedence 92 * (since it directly specifies 93 * serializer, whereas this would only be used to locate the 94 * serializer) 95 * and value of this annotation property is ignored. 96 */ as()97 public Class<?> as() default Void.class; 98 99 /** 100 * Concrete type to serialize keys of {@link java.util.Map} as, 101 * instead of type otherwise declared. 102 * Must be a supertype of declared type; otherwise an exception may be 103 * thrown by serializer. 104 */ keyAs()105 public Class<?> keyAs() default Void.class; 106 107 /** 108 * Concrete type to serialize content value (elements 109 * of a Collection/array, values of Maps) as, 110 * instead of type otherwise declared. 111 * Must be a supertype of declared type; otherwise an exception may be 112 * thrown by serializer. 113 */ contentAs()114 public Class<?> contentAs() default Void.class; 115 116 /** 117 * Whether type detection used is dynamic or static: that is, 118 * whether actual runtime type is used (dynamic), or just the 119 * declared type (static). 120 *<p> 121 * Note that Jackson 2.3 changed default to <code>DEFAULT_TYPING</code>, 122 * which is roughly same as saying "whatever". 123 * This is important as it allows avoiding accidental overrides 124 * at property level. 125 */ typing()126 public Typing typing() default Typing.DEFAULT_TYPING; 127 128 // // // Annotations for specifying intermediate Converters (2.2+) 129 130 /** 131 * Which helper object is to be used to convert type into something 132 * that Jackson knows how to serialize; either because base type 133 * cannot be serialized easily, or just to alter serialization. 134 * 135 * @since 2.2 136 */ 137 @SuppressWarnings("rawtypes") // to work around JDK8 bug wrt Class-valued annotation properties converter()138 public Class<? extends Converter> converter() default Converter.None.class; 139 140 /** 141 * Similar to {@link #converter}, but used for values of structures types 142 * (List, arrays, Maps). 143 * Note that this property does NOT have effect when used as Class annotation; 144 * it can only be used as property annotation: this because association between 145 * container and value types is loose and as such converters seldom make sense 146 * for such usage. 147 * 148 * @since 2.2 149 */ 150 @SuppressWarnings("rawtypes") // to work around JDK8 bug wrt Class-valued annotation properties contentConverter()151 public Class<? extends Converter> contentConverter() default Converter.None.class; 152 153 // // // Annotation(s) for inclusion criteria 154 155 /** 156 * Which properties of annotated Bean are 157 * to be included in serialization (has no effect on other types 158 * like enums, primitives or collections). 159 * Choices are "all", "properties that have value other than null" 160 * and "properties that have non-default value" (i.e. default value 161 * being property setting for a Bean constructed with default no-arg 162 * constructor, often null). 163 *<p> 164 * This property has been replaced by special-purpose {@link com.fasterxml.jackson.annotation.JsonInclude} 165 * annotation, introduced in Jackson 2.0. 166 *<p> 167 * Note that Jackson 2.3 changed default to <code>DEFAULT_INCLUSION</code>, 168 * which is roughly same as saying "whatever". This is important because 169 * it allows hierarchic default values to be used. 170 * 171 * @deprecated As of Jackson 2.0, this annotation has been replaced 172 * by {@link com.fasterxml.jackson.annotation.JsonInclude} 173 */ 174 @Deprecated include()175 public Inclusion include() default Inclusion.DEFAULT_INCLUSION; 176 177 /* 178 /********************************************************** 179 /* Value enumerations needed 180 /********************************************************** 181 */ 182 183 /** 184 * Enumeration used with {@link JsonSerialize#include} property 185 * to define which properties 186 * of Java Beans are to be included in serialization 187 */ 188 @Deprecated // since 2.0, marked deprecated in 2.6 189 public enum Inclusion 190 { 191 /** 192 * Value that indicates that properties are to be always included, 193 * independent of value 194 */ 195 ALWAYS, 196 197 /** 198 * Value that indicates that only properties with non-null 199 * values are to be included. 200 */ 201 NON_NULL, 202 203 /** 204 * Value that indicates that only properties that have values 205 * that differ from default settings (meaning values they have 206 * when Bean is constructed with its no-arguments constructor) 207 * are to be included. Value is generally not useful with 208 * {@link java.util.Map}s, since they have no default values; 209 * and if used, works same as {@link #ALWAYS}. 210 */ 211 NON_DEFAULT, 212 213 /** 214 * Value that indicates that only properties that have values 215 * that values that are null or what is considered empty are 216 * not to be included. 217 * Emptiness is defined for following type: 218 *<ul> 219 * <li>For {@link java.util.Collection}s and {@link java.util.Map}s, 220 * method <code>isEmpty()</code> is called; 221 * </li> 222 * <li>For Java arrays, empty arrays are ones with length of 0 223 * </li> 224 * <li>For Java {@link java.lang.String}s, <code>length()</code> is called, 225 * and return value of 0 indicates empty String 226 * </li> 227 * </ul> 228 * For other types, non-null values are to be included. 229 */ 230 NON_EMPTY, 231 232 /** 233 * Pseudo-value that is used to indicate 234 * "use whatever is default used at higher level". 235 * 236 * @since 2.3 237 */ 238 DEFAULT_INCLUSION 239 ; 240 } 241 242 /** 243 * Enumeration used with {@link JsonSerialize#typing} property 244 * to define whether type detection is based on dynamic runtime 245 * type (DYNAMIC) or declared type (STATIC). 246 */ 247 public enum Typing 248 { 249 /** 250 * Value that indicates that the actual dynamic runtime type is to 251 * be used. 252 */ 253 DYNAMIC, 254 255 /** 256 * Value that indicates that the static declared type is to 257 * be used. 258 */ 259 STATIC, 260 261 /** 262 * Pseudo-value that is used to indicate 263 * "use whatever is default used at higher level". 264 * 265 * @since 2.3 266 */ 267 DEFAULT_TYPING 268 ; 269 } 270 } 271