com.fasterxml.jackson.databind.SerializationFeature Maven / Gradle / Ivy
Show all versions of jackson-databind Show documentation
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),
/**
* Feature that determines what happens when a direct self-reference is detected
* by a POJO (and no Object Id handling is enabled for it):
* if enabled write that reference as null; if disabled, default behavior is
* used (which will try to serialize usually resulting in exception).
* But if {@link SerializationFeature#FAIL_ON_SELF_REFERENCES} is enabled. this property is ignored.
*
* Feature is disabled by default.
*
* @since 2.11
*/
WRITE_SELF_REFERENCES_AS_NULL(false),
/*
/******************************************************
/* 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 time stamps (true; the default),
* or as something else (usually textual representation).
* If textual representation is used, the actual format depends on configuration
* settings including possible per-property use of {@code @JsonFormat} annotation,
* globally configured {@link java.text.DateFormat}.
*
* For "classic" JDK date types ({@link java.util.Date}, {@link java.util.Calendar})
* the default formatting is provided by {@link com.fasterxml.jackson.databind.util.StdDateFormat},
* and corresponds to format String of "yyyy-MM-dd'T'HH:mm:ss.SSSX"
* (see {@link java.text.DateFormat} for details of format Strings).
* 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} instead of
* this feature.
*
* Feature is enabled by default, so that date/time are by default
* serialized as time stamps.
*/
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 time stamps 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 whether 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.
*
* Note that since 2.10, this does NOT apply to {@link Enum}s written as
* keys of {@link java.util.Map} values, which has separate setting,
* {@link #WRITE_ENUM_KEYS_USING_INDEX}.
*
* Feature is disabled by default.
*/
WRITE_ENUMS_USING_INDEX(false),
/**
* Feature that determines whether {link Enum}s
* used as {@link java.util.Map} keys are serialized
* as using {@link Enum#ordinal()} or not.
* Similar to {@link #WRITE_ENUMS_USING_INDEX} used when writing
* {@link Enum}s as regular values.
*
* Feature is disabled by default.
*
* @since 2.10
*/
WRITE_ENUM_KEYS_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 DeserializationFeature#READ_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; }
}