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 SerializationFeature(boolean defaultState)459 private SerializationFeature(boolean defaultState) { 460 _defaultState = defaultState; 461 _mask = (1 << ordinal()); 462 } 463 464 @Override enabledByDefault()465 public boolean enabledByDefault() { return _defaultState; } 466 467 468 @Override getMask()469 public int getMask() { return _mask; } 470 471 @Override enabledIn(int flags)472 public boolean enabledIn(int flags) { return (flags & _mask) != 0; } 473 } 474