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
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
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
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
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 */
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 */
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 */
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 */
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
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
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
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