1 package com.fasterxml.jackson.databind;
2
3 import com.fasterxml.jackson.databind.cfg.ConfigFeature;
4
5 /**
6 * Enumeration that defines simple on/off features that affect
7 * the way Java objects are serialized.
8 *<p>
9 * Note that features can be set both through
10 * {@link ObjectMapper} (as sort of defaults) and through
11 * {@link ObjectWriter}.
12 * In first case these defaults must follow "config-then-use" patterns
13 * (i.e. defined once, not changed afterwards); all per-call
14 * changes must be done using {@link ObjectWriter}.
15 */
16 public enum SerializationFeature implements ConfigFeature
17 {
18 /*
19 /******************************************************
20 /* Generic output features
21 /******************************************************
22 */
23
24 /**
25 * Feature that can be enabled to make root value (usually JSON
26 * Object but can be any type) wrapped within a single property
27 * JSON object, where key as the "root name", as determined by
28 * annotation introspector (esp. for JAXB that uses
29 * <code>@XmlRootElement.name</code>) or fallback (non-qualified
30 * class name).
31 * Feature is mostly intended for JAXB compatibility.
32 *<p>
33 * Feature is disabled by default.
34 */
35 WRAP_ROOT_VALUE(false),
36
37 /**
38 * Feature that allows enabling (or disabling) indentation
39 * for the underlying generator, using the default pretty
40 * printer configured for {@link ObjectMapper} (and
41 * {@link ObjectWriter}s created from mapper).
42 *<p>
43 * Note that the default pretty printer is only used if
44 * no explicit {@link com.fasterxml.jackson.core.PrettyPrinter} has been configured
45 * for the generator or {@link ObjectWriter}.
46 *<p>
47 * Feature is disabled by default.
48 */
49 INDENT_OUTPUT(false),
50
51 /*
52 /******************************************************
53 /* Error handling features
54 /******************************************************
55 */
56
57 /**
58 * Feature that determines what happens when no accessors are
59 * found for a type (and there are no annotations to indicate
60 * it is meant to be serialized). If enabled (default), an
61 * exception is thrown to indicate these as non-serializable
62 * types; if disabled, they are serialized as empty Objects,
63 * i.e. without any properties.
64 *<p>
65 * Note that empty types that this feature has only effect on
66 * those "empty" beans that do not have any recognized annotations
67 * (like <code>@JsonSerialize</code>): ones that do have annotations
68 * do not result in an exception being thrown.
69 *<p>
70 * Feature is enabled by default.
71 */
72 FAIL_ON_EMPTY_BEANS(true),
73
74 /**
75 * Feature that determines what happens when a direct self-reference
76 * is detected by a POJO (and no Object Id handling is enabled for it):
77 * either a {@link JsonMappingException} is
78 * thrown (if true), or reference is normally processed (false).
79 *<p>
80 * Feature is enabled by default.
81 *
82 * @since 2.4
83 */
84 FAIL_ON_SELF_REFERENCES(true),
85
86 /**
87 * Feature that determines whether Jackson code should catch
88 * and wrap {@link Exception}s (but never {@link Error}s!)
89 * to add additional information about
90 * location (within input) of problem or not. If enabled,
91 * most exceptions will be caught and re-thrown (exception
92 * specifically being that {@link java.io.IOException}s may be passed
93 * as is, since they are declared as throwable); this can be
94 * convenient both in that all exceptions will be checked and
95 * declared, and so there is more contextual information.
96 * However, sometimes calling application may just want "raw"
97 * unchecked exceptions passed as is.
98 *<p>
99 *<p>
100 * Feature is enabled by default.
101 */
102 WRAP_EXCEPTIONS(true),
103
104 /**
105 * Feature that determines what happens when an object which
106 * normally has type information included by Jackson is used
107 * in conjunction with {@link com.fasterxml.jackson.annotation.JsonUnwrapped}.
108 * In the default (enabled) state, an error will be thrown when
109 * an unwrapped object has type information. When disabled, the
110 * object will be unwrapped and the type information discarded.
111 *<p>
112 * Feature is enabled by default.
113 *
114 * @since 2.4
115 */
116 FAIL_ON_UNWRAPPED_TYPE_IDENTIFIERS(true),
117
118 /**
119 * Feature that determines what happens when a direct self-reference is detected
120 * by a POJO (and no Object Id handling is enabled for it):
121 * if enabled write that reference as null; if disabled, default behavior is
122 * used (which will try to serialize usually resulting in exception).
123 * But if {@link SerializationFeature#FAIL_ON_SELF_REFERENCES} is enabled. this property is ignored.
124 * <p>
125 * Feature is disabled by default.
126 *
127 * @since 2.11
128 */
129 WRITE_SELF_REFERENCES_AS_NULL(false),
130
131 /*
132 /******************************************************
133 /* Output life cycle features
134 /******************************************************
135 */
136
137 /**
138 * Feature that determines whether <code>close</code> method of
139 * serialized <b>root level</b> objects (ones for which <code>ObjectMapper</code>'s
140 * writeValue() (or equivalent) method is called)
141 * that implement {@link java.io.Closeable}
142 * is called after serialization or not. If enabled, <b>close()</b> will
143 * be called after serialization completes (whether succesfully, or
144 * due to an error manifested by an exception being thrown). You can
145 * think of this as sort of "finally" processing.
146 *<p>
147 * NOTE: only affects behavior with <b>root</b> objects, and not other
148 * objects reachable from the root object. Put another way, only one
149 * call will be made for each 'writeValue' call.
150 *<p>
151 * Feature is disabled by default.
152 */
153 CLOSE_CLOSEABLE(false),
154
155 /**
156 * Feature that determines whether <code>JsonGenerator.flush()</code> is
157 * called after <code>writeValue()</code> method <b>that takes JsonGenerator
158 * as an argument</b> completes (i.e. does NOT affect methods
159 * that use other destinations); same for methods in {@link ObjectWriter}.
160 * This usually makes sense; but there are cases where flushing
161 * should not be forced: for example when underlying stream is
162 * compressing and flush() causes compression state to be flushed
163 * (which occurs with some compression codecs).
164 *<p>
165 * Feature is enabled by default.
166 */
167 FLUSH_AFTER_WRITE_VALUE(true),
168
169 /*
170 /******************************************************
171 /* Datatype-specific serialization configuration
172 /******************************************************
173 */
174
175 /**
176 * Feature that determines whether Date (and date/time) values
177 * (and Date-based things like {@link java.util.Calendar}s) are to be
178 * serialized as numeric time stamps (true; the default),
179 * or as something else (usually textual representation).
180 * If textual representation is used, the actual format depends on configuration
181 * settings including possible per-property use of {@code @JsonFormat} annotation,
182 * globally configured {@link java.text.DateFormat}.
183 *<p>
184 * For "classic" JDK date types ({@link java.util.Date}, {@link java.util.Calendar})
185 * the default formatting is provided by {@link com.fasterxml.jackson.databind.util.StdDateFormat},
186 * and corresponds to format String of "yyyy-MM-dd'T'HH:mm:ss.SSSX"
187 * (see {@link java.text.DateFormat} for details of format Strings).
188 * Whether this feature affects handling of other date-related
189 * types depend on handlers of those types, although ideally they
190 * should use this feature
191 *<p>
192 * Note: whether {@link java.util.Map} keys are serialized as Strings
193 * or not is controlled using {@link #WRITE_DATE_KEYS_AS_TIMESTAMPS} instead of
194 * this feature.
195 *<p>
196 * Feature is enabled by default, so that date/time are by default
197 * serialized as time stamps.
198 */
199 WRITE_DATES_AS_TIMESTAMPS(true),
200
201 /**
202 * Feature that determines whether {@link java.util.Date}s
203 * (and sub-types) used as {@link java.util.Map} keys are serialized
204 * as time stamps or not (if not, will be serialized as textual values).
205 *<p>
206 * Default value is 'false', meaning that Date-valued Map keys are serialized
207 * as textual (ISO-8601) values.
208 *<p>
209 * Feature is disabled by default.
210 */
211 WRITE_DATE_KEYS_AS_TIMESTAMPS(false),
212
213 /**
214 * Feature that determines whether date/date-time values should be serialized
215 * so that they include timezone id, in cases where type itself contains
216 * timezone information. Including this information may lead to compatibility
217 * issues because ISO-8601 specification does not define formats that include
218 * such information.
219 *<p>
220 * If enabled, Timezone id should be included using format specified
221 * with Java 8 <code>DateTimeFormatter#ISO_ZONED_DATE_TIME</code> definition
222 * (for example, '2011-12-03T10:15:30+01:00[Europe/Paris]').
223 *<p>
224 * Note: setting has no relevance if date/time values are serialized as timestamps.
225 *<p>
226 * Feature is disabled by default, so that zone id is NOT included; rather, timezone
227 * offset is used for ISO-8601 compatibility (if any timezone information is
228 * included in value).
229 *
230 * @since 2.6
231 */
232 WRITE_DATES_WITH_ZONE_ID(false),
233
234 /**
235 * Feature that determines whether time values that represents time periods
236 * (durations, periods, ranges) are to be serialized by default using
237 * a numeric (true) or textual (false) representations. Note that numeric
238 * representation may mean either simple number, or an array of numbers,
239 * depending on type.
240 *<p>
241 * Note: whether {@link java.util.Map} keys are serialized as Strings
242 * or not is controlled using {@link #WRITE_DATE_KEYS_AS_TIMESTAMPS}.
243 *<p>
244 * Feature is enabled by default, so that period/duration are by default
245 * serialized as timestamps.
246 *
247 * @since 2.5
248 */
249 WRITE_DURATIONS_AS_TIMESTAMPS(true),
250
251 /**
252 * Feature that determines how type <code>char[]</code> is serialized:
253 * when enabled, will be serialized as an explict JSON array (with
254 * single-character Strings as values); when disabled, defaults to
255 * serializing them as Strings (which is more compact).
256 *<p>
257 * Feature is disabled by default.
258 */
259 WRITE_CHAR_ARRAYS_AS_JSON_ARRAYS(false),
260
261 /**
262 * Feature that determines standard serialization mechanism used for
263 * Enum values: if enabled, return value of <code>Enum.toString()</code>
264 * is used; if disabled, return value of <code>Enum.name()</code> is used.
265 *<p>
266 * Note: this feature should usually have same value
267 * as {@link DeserializationFeature#READ_ENUMS_USING_TO_STRING}.
268 *<p>
269 * Feature is disabled by default.
270 */
271 WRITE_ENUMS_USING_TO_STRING(false),
272
273 /**
274 * Feature that determines whether Java Enum values are serialized
275 * as numbers (true), or textual values (false). If textual values are
276 * used, other settings are also considered.
277 * If this feature is enabled,
278 * return value of <code>Enum.ordinal()</code>
279 * (an integer) will be used as the serialization.
280 *<p>
281 * Note that this feature has precedence over {@link #WRITE_ENUMS_USING_TO_STRING},
282 * which is only considered if this feature is set to false.
283 *<p>
284 * Note that since 2.10, this does NOT apply to {@link Enum}s written as
285 * keys of {@link java.util.Map} values, which has separate setting,
286 * {@link #WRITE_ENUM_KEYS_USING_INDEX}.
287 *<p>
288 * Feature is disabled by default.
289 */
290 WRITE_ENUMS_USING_INDEX(false),
291
292 /**
293 * Feature that determines whether {link Enum}s
294 * used as {@link java.util.Map} keys are serialized
295 * as using {@link Enum#ordinal()} or not.
296 * Similar to {@link #WRITE_ENUMS_USING_INDEX} used when writing
297 * {@link Enum}s as regular values.
298 *<p>
299 * Feature is disabled by default.
300 *
301 * @since 2.10
302 */
303 WRITE_ENUM_KEYS_USING_INDEX(false),
304
305 /**
306 * Feature that determines whether Map entries with null values are
307 * to be serialized (true) or not (false).
308 *<p>
309 * NOTE: unlike other {@link SerializationFeature}s, this feature <b>cannot</b> be
310 * dynamically changed on per-call basis, because its effect is considered during
311 * construction of serializers and property handlers.
312 *<p>
313 * Feature is enabled by default.
314 *
315 * @deprecated Since 2.9 there are better mechanism for specifying filtering; specifically
316 * using {@link com.fasterxml.jackson.annotation.JsonInclude} or configuration overrides
317 * (see {@link ObjectMapper#configOverride(Class)}}).
318 */
319 @Deprecated // since 2.9
320 WRITE_NULL_MAP_VALUES(true),
321
322 /**
323 * Feature that determines whether Container properties (POJO properties
324 * with declared value of Collection or array; i.e. things that produce JSON
325 * arrays) that are empty (have no elements)
326 * will be serialized as empty JSON arrays (true), or suppressed from output (false).
327 *<p>
328 * Note that this does not change behavior of {@link java.util.Map}s, or
329 * "Collection-like" types.
330 *<p>
331 * NOTE: unlike other {@link SerializationFeature}s, this feature <b>cannot</b> be
332 * dynamically changed on per-call basis, because its effect is considered during
333 * construction of serializers and property handlers.
334 *<p>
335 * Feature is enabled by default.
336 *
337 * @deprecated Since 2.8 there are better mechanism for specifying filtering; specifically
338 * using {@link com.fasterxml.jackson.annotation.JsonInclude} or configuration overrides.
339 */
340 @Deprecated // since 2.8
341 WRITE_EMPTY_JSON_ARRAYS(true),
342
343 /**
344 * Feature added for interoperability, to work with oddities of
345 * so-called "BadgerFish" convention.
346 * Feature determines handling of single element {@link java.util.Collection}s
347 * and arrays: if enabled, {@link java.util.Collection}s and arrays that contain exactly
348 * one element will be serialized as if that element itself was serialized.
349 *<p>
350 * When enabled, a POJO with array that normally looks like this:
351 *<pre>
352 * { "arrayProperty" : [ 1 ] }
353 *</pre>
354 * will instead be serialized as
355 *<pre>
356 * { "arrayProperty" : 1 }
357 *</pre>
358 *<p>
359 * Note that this feature is counterpart to {@link DeserializationFeature#ACCEPT_SINGLE_VALUE_AS_ARRAY}
360 * (that is, usually both are enabled, or neither is).
361 *<p>
362 * Feature is disabled by default, so that no special handling is done.
363 */
364 WRITE_SINGLE_ELEM_ARRAYS_UNWRAPPED(false),
365
366 /**
367 * Feature that determines whether {@link java.math.BigDecimal} entries are
368 * serialized using {@link java.math.BigDecimal#toPlainString()} to prevent
369 * values to be written using scientific notation.
370 *<p>
371 * NOTE: since this feature typically requires use of
372 * {@link com.fasterxml.jackson.core.JsonGenerator#writeNumber(String)}
373 * it may cause compatibility problems since not all {@link com.fasterxml.jackson.core.JsonGenerator}
374 * implementations support such mode of output: usually only text-based formats
375 * support it.
376 *<p>
377 * Feature is disabled by default.
378 *
379 * @deprecated Since 2.5: use {@link com.fasterxml.jackson.core.JsonGenerator.Feature#WRITE_BIGDECIMAL_AS_PLAIN} instead
380 * (using {@link ObjectWriter#with(com.fasterxml.jackson.core.JsonGenerator.Feature)}).
381 */
382 @Deprecated // since 2.5
383 WRITE_BIGDECIMAL_AS_PLAIN(false),
384
385 /**
386 * Feature that controls whether numeric timestamp values are
387 * to be written using nanosecond timestamps (enabled) or not (disabled);
388 * <b>if and only if</b> datatype supports such resolution.
389 * Only newer datatypes (such as Java8 Date/Time) support such resolution --
390 * older types (pre-Java8 <b>java.util.Date</b> etc) and Joda do not --
391 * and this setting <b>has no effect</b> on such types.
392 *<p>
393 * If disabled, standard millisecond timestamps are assumed.
394 * This is the counterpart to {@link DeserializationFeature#READ_DATE_TIMESTAMPS_AS_NANOSECONDS}.
395 *<p>
396 * Feature is enabled by default, to support most accurate time values possible.
397 *
398 * @since 2.2
399 */
400 WRITE_DATE_TIMESTAMPS_AS_NANOSECONDS(true),
401
402 /**
403 * Feature that determines whether {@link java.util.Map} entries are first
404 * sorted by key before serialization or not: if enabled, additional sorting
405 * step is performed if necessary (not necessary for {@link java.util.SortedMap}s),
406 * if disabled, no additional sorting is needed.
407 *<p>
408 * Feature is disabled by default.
409 */
410 ORDER_MAP_ENTRIES_BY_KEYS(false),
411
412 /*
413 /******************************************************
414 /* Other
415 /******************************************************
416 */
417
418 /**
419 * Feature that determines whether {@link ObjectWriter} should
420 * try to eagerly fetch necessary {@link JsonSerializer} when
421 * possible. This improves performance in cases where similarly
422 * configured {@link ObjectWriter} instance is used multiple
423 * times; and should not significantly affect single-use cases.
424 *<p>
425 * Note that there should not be any need to normally disable this
426 * feature: only consider that if there are actual perceived problems.
427 *<p>
428 * Feature is enabled by default.
429 *
430 * @since 2.1
431 */
432 EAGER_SERIALIZER_FETCH(true),
433
434 /**
435 * Feature that determines whether Object Identity is compared using
436 * true JVM-level identity of Object (false); or, <code>equals()</code> method.
437 * Latter is sometimes useful when dealing with Database-bound objects with
438 * ORM libraries (like Hibernate). Note that Object itself is actually compared,
439 * and NOT Object Id; naming of this feature is somewhat confusing, so it is important
440 * that Object <b>for which identity is to be preserved</b> are considered equal,
441 * above and beyond ids (which are always compared using equality anyway).
442 *<p>
443 * NOTE: due to the way functionality is implemented, it is very important that
444 * in addition to overriding {@link Object#equals} for Objects to match (to be considered
445 * "same") it is also necessary to ensure that {@link Object#hashCode()} is overridden
446 * to produce the exact same value for equal instances.
447 *<p>
448 * Feature is disabled by default; meaning that strict identity is used, not
449 * <code>equals()</code>
450 *
451 * @since 2.3
452 */
453 USE_EQUALITY_FOR_OBJECT_ID(false)
454 ;
455
456 private final boolean _defaultState;
457 private final int _mask;
458
459 private SerializationFeature(boolean defaultState) {
460 _defaultState = defaultState;
461 _mask = (1 << ordinal());
462 }
463
464 @Override
465 public boolean enabledByDefault() { return _defaultState; }
466
467
468 @Override
469 public int getMask() { return _mask; }
470
471 @Override
472 public boolean enabledIn(int flags) { return (flags & _mask) != 0; }
473 }
474