All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.fasterxml.jackson.databind.SerializationFeature.orig Maven / Gradle / Ivy

There is a newer version: 2.17.0
Show newest version
package com.fasterxml.jackson.databind;

import com.fasterxml.jackson.databind.cfg.ConfigFeature;

/**
 * Enumeration that defines simple on/off features that affect
 * the way Java objects are serialized.
 *

* Note that features can be set both through * {@link ObjectMapper} (as sort of defaults) and through * {@link ObjectWriter}. * In first case these defaults must follow "config-then-use" patterns * (i.e. defined once, not changed afterwards); all per-call * changes must be done using {@link ObjectWriter}. */ public enum SerializationFeature implements ConfigFeature { /* /****************************************************** /* Generic output features /****************************************************** */ /** * Feature that can be enabled to make root value (usually JSON * Object but can be any type) wrapped within a single property * JSON object, where key as the "root name", as determined by * annotation introspector (esp. for JAXB that uses * @XmlRootElement.name) or fallback (non-qualified * class name). * Feature is mostly intended for JAXB compatibility. *

* Feature is disabled by default. */ WRAP_ROOT_VALUE(false), /** * Feature that allows enabling (or disabling) indentation * for the underlying generator, using the default pretty * printer configured for {@link ObjectMapper} (and * {@link ObjectWriter}s created from mapper). *

* Note that the default pretty printer is only used if * no explicit {@link com.fasterxml.jackson.core.PrettyPrinter} has been configured * for the generator or {@link ObjectWriter}. *

* Feature is disabled by default. */ INDENT_OUTPUT(false), /* /****************************************************** /* Error handling features /****************************************************** */ /** * Feature that determines what happens when no accessors are * found for a type (and there are no annotations to indicate * it is meant to be serialized). If enabled (default), an * exception is thrown to indicate these as non-serializable * types; if disabled, they are serialized as empty Objects, * i.e. without any properties. *

* Note that empty types that this feature has only effect on * those "empty" beans that do not have any recognized annotations * (like @JsonSerialize): ones that do have annotations * do not result in an exception being thrown. *

* Feature is enabled by default. */ FAIL_ON_EMPTY_BEANS(true), /** * Feature that determines what happens when a direct self-reference * is detected by a POJO (and no Object Id handling is enabled for it): * either a {@link JsonMappingException} is * thrown (if true), or reference is normally processed (false). *

* Feature is enabled by default. * * @since 2.4 */ FAIL_ON_SELF_REFERENCES(true), /** * Feature that determines whether Jackson code should catch * and wrap {@link Exception}s (but never {@link Error}s!) * to add additional information about * location (within input) of problem or not. If enabled, * most exceptions will be caught and re-thrown (exception * specifically being that {@link java.io.IOException}s may be passed * as is, since they are declared as throwable); this can be * convenient both in that all exceptions will be checked and * declared, and so there is more contextual information. * However, sometimes calling application may just want "raw" * unchecked exceptions passed as is. *

*

* Feature is enabled by default. */ WRAP_EXCEPTIONS(true), /** * Feature that determines what happens when an object which * normally has type information included by Jackson is used * in conjunction with {@link com.fasterxml.jackson.annotation.JsonUnwrapped}. * In the default (enabled) state, an error will be thrown when * an unwrapped object has type information. When disabled, the * object will be unwrapped and the type information discarded. *

* Feature is enabled by default. * * @since 2.4 */ FAIL_ON_UNWRAPPED_TYPE_IDENTIFIERS(true), /* /****************************************************** /* Output life cycle features /****************************************************** */ /** * Feature that determines whether close method of * serialized root level objects (ones for which ObjectMapper's * writeValue() (or equivalent) method is called) * that implement {@link java.io.Closeable} * is called after serialization or not. If enabled, close() will * be called after serialization completes (whether succesfully, or * due to an error manifested by an exception being thrown). You can * think of this as sort of "finally" processing. *

* NOTE: only affects behavior with root objects, and not other * objects reachable from the root object. Put another way, only one * call will be made for each 'writeValue' call. *

* Feature is disabled by default. */ CLOSE_CLOSEABLE(false), /** * Feature that determines whether JsonGenerator.flush() is * called after writeValue() method that takes JsonGenerator * as an argument completes (i.e. does NOT affect methods * that use other destinations); same for methods in {@link ObjectWriter}. * This usually makes sense; but there are cases where flushing * should not be forced: for example when underlying stream is * compressing and flush() causes compression state to be flushed * (which occurs with some compression codecs). *

* Feature is enabled by default. */ FLUSH_AFTER_WRITE_VALUE(true), /* /****************************************************** /* Datatype-specific serialization configuration /****************************************************** */ /** * Feature that determines whether Date (and date/time) values * (and Date-based things like {@link java.util.Calendar}s) are to be * serialized as numeric timestamps (true; the default), * or as something else (usually textual representation). * If textual representation is used, the actual format is * one returned by a call to * {@link com.fasterxml.jackson.databind.SerializationConfig#getDateFormat}: * the default setting being {@link com.fasterxml.jackson.databind.util.StdDateFormat}, * which corresponds to format String of "yyyy-MM-dd'T'HH:mm:ss.SSSZ" * (see {@link java.text.DateFormat} for details of format Strings). *

* Note: whether this feature affects handling of other date-related * types depend on handlers of those types, although ideally they * should use this feature *

* Note: whether {@link java.util.Map} keys are serialized as Strings * or not is controlled using {@link #WRITE_DATE_KEYS_AS_TIMESTAMPS}. *

* Feature is enabled by default, so that date/time are by default * serialized as timestamps. */ WRITE_DATES_AS_TIMESTAMPS(true), /** * Feature that determines whether {@link java.util.Date}s * (and sub-types) used as {@link java.util.Map} keys are serialized * as timestamps or not (if not, will be serialized as textual * values). *

* Default value is 'false', meaning that Date-valued Map keys are serialized * as textual (ISO-8601) values. *

* Feature is disabled by default. */ WRITE_DATE_KEYS_AS_TIMESTAMPS(false), /** * Feature that determines whether date/date-time values should be serialized * so that they include timezone id, in cases where type itself contains * timezone information. Including this information may lead to compatibility * issues because ISO-8601 specification does not define formats that include * such information. *

* If enabled, Timezone id should be included using format specified * with Java 8 DateTimeFormatter#ISO_ZONED_DATE_TIME definition * (for example, '2011-12-03T10:15:30+01:00[Europe/Paris]'). *

* Note: setting has no relevance if date/time values are serialized as timestamps. *

* Feature is disabled by default, so that zone id is NOT included; rather, timezone * offset is used for ISO-8601 compatibility (if any timezone information is * included in value). * * @since 2.6 */ WRITE_DATES_WITH_ZONE_ID(false), /** * Feature that determines whether time values that represents time periods * (durations, periods, ranges) are to be serialized by default using * a numeric (true) or textual (false) representations. Note that numeric * representation may mean either simple number, or an array of numbers, * depending on type. *

* Note: whether {@link java.util.Map} keys are serialized as Strings * or not is controlled using {@link #WRITE_DATE_KEYS_AS_TIMESTAMPS}. *

* Feature is enabled by default, so that period/duration are by default * serialized as timestamps. * * @since 2.5 */ WRITE_DURATIONS_AS_TIMESTAMPS(true), /** * Feature that determines how type char[] is serialized: * when enabled, will be serialized as an explict JSON array (with * single-character Strings as values); when disabled, defaults to * serializing them as Strings (which is more compact). *

* Feature is disabled by default. */ WRITE_CHAR_ARRAYS_AS_JSON_ARRAYS(false), /** * Feature that determines standard serialization mechanism used for * Enum values: if enabled, return value of Enum.toString() * is used; if disabled, return value of Enum.name() is used. *

* Note: this feature should usually have same value * as {@link DeserializationFeature#READ_ENUMS_USING_TO_STRING}. *

* Feature is disabled by default. */ WRITE_ENUMS_USING_TO_STRING(false), /** * Feature that determines whethere Java Enum values are serialized * as numbers (true), or textual values (false). If textual values are * used, other settings are also considered. * If this feature is enabled, * return value of Enum.ordinal() * (an integer) will be used as the serialization. *

* Note that this feature has precedence over {@link #WRITE_ENUMS_USING_TO_STRING}, * which is only considered if this feature is set to false. *

* Feature is disabled by default. */ WRITE_ENUMS_USING_INDEX(false), /** * Feature that determines whether Map entries with null values are * to be serialized (true) or not (false). *

* NOTE: unlike other {@link SerializationFeature}s, this feature cannot be * dynamically changed on per-call basis, because its effect is considered during * construction of serializers and property handlers. *

* Feature is enabled by default. * * @deprecated Since 2.9 there are better mechanism for specifying filtering; specifically * using {@link com.fasterxml.jackson.annotation.JsonInclude} or configuration overrides * (see {@link ObjectMapper#configOverride(Class)}}). */ @Deprecated // since 2.9 WRITE_NULL_MAP_VALUES(true), /** * Feature that determines whether Container properties (POJO properties * with declared value of Collection or array; i.e. things that produce JSON * arrays) that are empty (have no elements) * will be serialized as empty JSON arrays (true), or suppressed from output (false). *

* Note that this does not change behavior of {@link java.util.Map}s, or * "Collection-like" types. *

* NOTE: unlike other {@link SerializationFeature}s, this feature cannot be * dynamically changed on per-call basis, because its effect is considered during * construction of serializers and property handlers. *

* Feature is enabled by default. * * @deprecated Since 2.8 there are better mechanism for specifying filtering; specifically * using {@link com.fasterxml.jackson.annotation.JsonInclude} or configuration overrides. */ @Deprecated // since 2.8 WRITE_EMPTY_JSON_ARRAYS(true), /** * Feature added for interoperability, to work with oddities of * so-called "BadgerFish" convention. * Feature determines handling of single element {@link java.util.Collection}s * and arrays: if enabled, {@link java.util.Collection}s and arrays that contain exactly * one element will be serialized as if that element itself was serialized. *

* When enabled, a POJO with array that normally looks like this: *

     *  { "arrayProperty" : [ 1 ] }
     *
* will instead be serialized as *
     *  { "arrayProperty" : 1 }
     *
*

* Note that this feature is counterpart to {@link DeserializationFeature#ACCEPT_SINGLE_VALUE_AS_ARRAY} * (that is, usually both are enabled, or neither is). *

* Feature is disabled by default, so that no special handling is done. */ WRITE_SINGLE_ELEM_ARRAYS_UNWRAPPED(false), /** * Feature that determines whether {@link java.math.BigDecimal} entries are * serialized using {@link java.math.BigDecimal#toPlainString()} to prevent * values to be written using scientific notation. *

* NOTE: since this feature typically requires use of * {@link com.fasterxml.jackson.core.JsonGenerator#writeNumber(String)} * it may cause compatibility problems since not all {@link com.fasterxml.jackson.core.JsonGenerator} * implementations support such mode of output: usually only text-based formats * support it. *

* Feature is disabled by default. * * @deprecated Since 2.5: use {@link com.fasterxml.jackson.core.JsonGenerator.Feature#WRITE_BIGDECIMAL_AS_PLAIN} instead * (using {@link ObjectWriter#with(com.fasterxml.jackson.core.JsonGenerator.Feature)}). */ @Deprecated // since 2.5 WRITE_BIGDECIMAL_AS_PLAIN(false), /** * Feature that controls whether numeric timestamp values are * to be written using nanosecond timestamps (enabled) or not (disabled); * if and only if datatype supports such resolution. * Only newer datatypes (such as Java8 Date/Time) support such resolution -- * older types (pre-Java8 java.util.Date etc) and Joda do not -- * and this setting has no effect on such types. *

* If disabled, standard millisecond timestamps are assumed. * This is the counterpart to {@link SerializationFeature#WRITE_DATE_TIMESTAMPS_AS_NANOSECONDS}. *

* Feature is enabled by default, to support most accurate time values possible. * * @since 2.2 */ WRITE_DATE_TIMESTAMPS_AS_NANOSECONDS(true), /** * Feature that determines whether {@link java.util.Map} entries are first * sorted by key before serialization or not: if enabled, additional sorting * step is performed if necessary (not necessary for {@link java.util.SortedMap}s), * if disabled, no additional sorting is needed. *

* Feature is disabled by default. */ ORDER_MAP_ENTRIES_BY_KEYS(false), /* /****************************************************** /* Other /****************************************************** */ /** * Feature that determines whether {@link ObjectWriter} should * try to eagerly fetch necessary {@link JsonSerializer} when * possible. This improves performance in cases where similarly * configured {@link ObjectWriter} instance is used multiple * times; and should not significantly affect single-use cases. *

* Note that there should not be any need to normally disable this * feature: only consider that if there are actual perceived problems. *

* Feature is enabled by default. * * @since 2.1 */ EAGER_SERIALIZER_FETCH(true), /** * Feature that determines whether Object Identity is compared using * true JVM-level identity of Object (false); or, equals() method. * Latter is sometimes useful when dealing with Database-bound objects with * ORM libraries (like Hibernate). Note that Object itself is actually compared, * and NOT Object Id; naming of this feature is somewhat confusing, so it is important * that Object for which identity is to be preserved are considered equal, * above and beyond ids (which are always compared using equality anyway). *

* NOTE: due to the way functionality is implemented, it is very important that * in addition to overriding {@link Object#equals} for Objects to match (to be considered * "same") it is also necessary to ensure that {@link Object#hashCode()} is overridden * to produce the exact same value for equal instances. *

* Feature is disabled by default; meaning that strict identity is used, not * equals() * * @since 2.3 */ USE_EQUALITY_FOR_OBJECT_ID(false) ; private final boolean _defaultState; private final int _mask; private SerializationFeature(boolean defaultState) { _defaultState = defaultState; _mask = (1 << ordinal()); } @Override public boolean enabledByDefault() { return _defaultState; } @Override public int getMask() { return _mask; } @Override public boolean enabledIn(int flags) { return (flags & _mask) != 0; } }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy