Enum JSON.Feature

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<JSON.Feature>
    Enclosing class:
    JSON

    public static enum JSON.Feature
    extends java.lang.Enum<JSON.Feature>
    Simple on/off (enabled/disabled) features for JSON; used for simple configuration aspects.
    • Enum Constant Summary

      Enum Constants 
      Enum Constant Description
      FAIL_ON_DUPLICATE_MAP_KEYS
      When encountering duplicate keys for JSON Objects, should an exception be thrown or not? If exception is not thrown, the last instance from input document will be used.
      FAIL_ON_UNKNOWN_BEAN_PROPERTY
      When encountering a JSON Object property name for which there is no matching Bean property, should an exception be thrown (true), or should JSON Property value be quietly skipped (false)?
      FAIL_ON_UNKNOWN_TYPE_WRITE
      Feature that determines what happens when we encounter a value of unrecognized type for which we do not have standard handler: if enabled, will throw a JSONObjectException, if disabled simply calls Object.toString() and uses that JSON String as serialization.
      FLUSH_AFTER_WRITE_VALUE
      Feature that determines whether JsonGenerator.flush() is called after write() method that takes JsonGenerator as an argument completes (that is, does NOT affect methods that use other destinations).
      FORCE_REFLECTION_ACCESS
      Feature that determines whether access to Methods and Constructors that are used with dynamically introspected Beans may be forced using AccessibleObject.setAccessible(java.lang.reflect.AccessibleObject[], boolean) or not.
      HANDLE_JAVA_BEANS
      Feature that determines whether Bean types (Java objects with getters and setters that expose state to serialize) will be recognized and handled or not.
      PRESERVE_FIELD_ORDERING
      This feature can be used to indicate that the reader should preserve order of the properties same as what input document has.
      PRETTY_PRINT_OUTPUT
      Feature that can be enabled to use "pretty-printing", basic indentation to make resulting JSON easier to read by humans by adding white space such as line feeds and indentation.
      READ_JSON_ARRAYS_AS_JAVA_ARRAYS
      When reading JSON Arrays, should matching Java value be of type Object[] (true) or List (false)?
      READ_ONLY
      This feature can be enabled to reduce memory usage for use cases where resulting container objects (Maps and Collections) do not need to mutable (that is, their contents can not changed).
      USE_BIG_DECIMAL_FOR_FLOATS
      When reading JSON Numbers, should BigDecimal be used for floating-point numbers; or should Double be used.
      USE_DEFERRED_MAPS
      This feature determines whether Map instances constructed use deferred materialization (as implemented by DeferredMap), in case user has not specified custom Map implementation.
      USE_FIELDS
      Feature that enables use of public fields instead of setters and getters, in cases where no setter/getter is available.
      USE_IS_GETTERS
      Whether "is-getters" (like public boolean isValuable()) are detected for use or not.
      WRITE_DATES_AS_TIMESTAMP
      Feature that determines whether Date (and date/time) values (and Date-based things like Calendars) are to be serialized as numeric timestamps (true), or using a textual representation (false)
      WRITE_ENUMS_USING_INDEX
      Feature that determines whether Enum values are written using numeric index (true), or String representation from calling Enum.toString() (false).
      WRITE_NULL_PROPERTIES
      Feature that defines what to do with Map entries and Java Bean properties that have null as value: if enabled, they will be written out normally; if disabled, such entries and properties will be ignored.
      WRITE_READONLY_BEAN_PROPERTIES
      Feature that determines whether "read-only" properties of Beans (properties that only have a getter but no matching setter) are to be included in Bean serialization or not; if disabled, only properties have have both setter and getter are serialized.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean affectsCaching()  
      static int cacheBreakers()
      Method for calculating bitset of features that force flushing of POJO handler caches.
      static int defaults()  
      boolean enabledByDefault()  
      boolean isDisabled​(int flags)  
      boolean isEnabled​(int flags)  
      int mask()  
      static JSON.Feature valueOf​(java.lang.String name)
      Returns the enum constant of this type with the specified name.
      static JSON.Feature[] values()
      Returns an array containing the constants of this enum type, in the order they are declared.
      • Methods inherited from class java.lang.Enum

        clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait
    • Enum Constant Detail

      • USE_BIG_DECIMAL_FOR_FLOATS

        public static final JSON.Feature USE_BIG_DECIMAL_FOR_FLOATS
        When reading JSON Numbers, should BigDecimal be used for floating-point numbers; or should Double be used. Trade-off is between accuracy -- only BigDecimal is guaranteed to store the EXACT decimal value parsed -- and performance (Double is typically faster to parse).

        Default setting is false, meaning that Double is used.

      • READ_JSON_ARRAYS_AS_JAVA_ARRAYS

        public static final JSON.Feature READ_JSON_ARRAYS_AS_JAVA_ARRAYS
        When reading JSON Arrays, should matching Java value be of type Object[] (true) or List (false)?

        Default setting is false, meaning that JSON Arrays are bound to Lists.

      • READ_ONLY

        public static final JSON.Feature READ_ONLY
        This feature can be enabled to reduce memory usage for use cases where resulting container objects (Maps and Collections) do not need to mutable (that is, their contents can not changed). If set, reader is allowed to construct immutable (read-only) container objects; and specifically empty Maps and Collections can be used to reduce number of objects allocated. In addition, sizes of non-empty containers can be trimmed to exact size.

        Default setting is false, meaning that reader will have to construct mutable container instance when reading.

      • PRESERVE_FIELD_ORDERING

        public static final JSON.Feature PRESERVE_FIELD_ORDERING
        This feature can be used to indicate that the reader should preserve order of the properties same as what input document has. Note that it is up to MapBuilder to support this feature; custom implementations may ignore the setting.

        Default setting is true, meaning that reader is expected to try to preserve ordering of fields read.

      • USE_DEFERRED_MAPS

        public static final JSON.Feature USE_DEFERRED_MAPS
        This feature determines whether Map instances constructed use deferred materialization (as implemented by DeferredMap), in case user has not specified custom Map implementation. Enabling feature typically reduces initial value read time and moves overhead to actual access of contents (materialization occurs when first key or value access happens); this makes sense when only a subset of data is accessed. Conversely, when traversing full object hierarchy, it makes sense to disable this feature.

        Default setting is true, meaning that reader is expected to try to

      • FAIL_ON_DUPLICATE_MAP_KEYS

        public static final JSON.Feature FAIL_ON_DUPLICATE_MAP_KEYS
        When encountering duplicate keys for JSON Objects, should an exception be thrown or not? If exception is not thrown, the last instance from input document will be used.

        Default setting is true, meaning that a JSONObjectException will be thrown if duplicates are encountered.

      • FAIL_ON_UNKNOWN_BEAN_PROPERTY

        public static final JSON.Feature FAIL_ON_UNKNOWN_BEAN_PROPERTY
        When encountering a JSON Object property name for which there is no matching Bean property, should an exception be thrown (true), or should JSON Property value be quietly skipped (false)?

        Default setting is false, meaning that unmappable JSON Object properties will simply be ignored.

      • WRITE_NULL_PROPERTIES

        public static final JSON.Feature WRITE_NULL_PROPERTIES
        Feature that defines what to do with Map entries and Java Bean properties that have null as value: if enabled, they will be written out normally; if disabled, such entries and properties will be ignored.

        Default setting is false so that any null-valued properties are ignored during serialization.

      • WRITE_ENUMS_USING_INDEX

        public static final JSON.Feature WRITE_ENUMS_USING_INDEX
        Feature that determines whether Enum values are written using numeric index (true), or String representation from calling Enum.toString() (false).

        Feature is disabled by default, so that Enums are serialized as JSON Strings.

      • WRITE_DATES_AS_TIMESTAMP

        public static final JSON.Feature WRITE_DATES_AS_TIMESTAMP
        Feature that determines whether Date (and date/time) values (and Date-based things like Calendars) are to be serialized as numeric timestamps (true), or using a textual representation (false)

        Feature is disabled by default, so that date/time values are serialized as text, NOT timestamp.

        Since:
        2.7
      • PRETTY_PRINT_OUTPUT

        public static final JSON.Feature PRETTY_PRINT_OUTPUT
        Feature that can be enabled to use "pretty-printing", basic indentation to make resulting JSON easier to read by humans by adding white space such as line feeds and indentation.

        Default setting is false so that no pretty-printing is done (unless explicitly constructed with a pretty printer object)

      • FLUSH_AFTER_WRITE_VALUE

        public static final JSON.Feature FLUSH_AFTER_WRITE_VALUE
        Feature that determines whether JsonGenerator.flush() is called after write() method that takes JsonGenerator as an argument completes (that is, does NOT affect methods that use other destinations). 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.

      • FAIL_ON_UNKNOWN_TYPE_WRITE

        public static final JSON.Feature FAIL_ON_UNKNOWN_TYPE_WRITE
        Feature that determines what happens when we encounter a value of unrecognized type for which we do not have standard handler: if enabled, will throw a JSONObjectException, if disabled simply calls Object.toString() and uses that JSON String as serialization.

        NOTE: if HANDLE_JAVA_BEANS is enabled, this setting typically has no effect, since otherwise unknown types are recognized as Bean types.

        Feature is disabled by default so that no exceptions are thrown.

      • HANDLE_JAVA_BEANS

        public static final JSON.Feature HANDLE_JAVA_BEANS
        Feature that determines whether Bean types (Java objects with getters and setters that expose state to serialize) will be recognized and handled or not. When enabled, any types that are not recognized as standard JDK data structures, primitives or wrapper values will be introspected and handled as Java Beans (can be read/written as long as JSON matches properties discovered); when disabled, they may only be serialized (using Object.toString() method), and can not be deserialized.

        Feature is enabled by default, but can be disabled do avoid use of Bean reflection for cases where it is not desired.

      • WRITE_READONLY_BEAN_PROPERTIES

        public static final JSON.Feature WRITE_READONLY_BEAN_PROPERTIES
        Feature that determines whether "read-only" properties of Beans (properties that only have a getter but no matching setter) are to be included in Bean serialization or not; if disabled, only properties have have both setter and getter are serialized. Note that feature is only used if HANDLE_JAVA_BEANS is also enabled.

        Feature is enabled by default, so that all Bean properties are serialized.

      • FORCE_REFLECTION_ACCESS

        public static final JSON.Feature FORCE_REFLECTION_ACCESS
        Feature that determines whether access to Methods and Constructors that are used with dynamically introspected Beans may be forced using AccessibleObject.setAccessible(java.lang.reflect.AccessibleObject[], boolean) or not.

        Feature is enabled by default, so that access may be forced.

      • USE_IS_GETTERS

        public static final JSON.Feature USE_IS_GETTERS
        Whether "is-getters" (like public boolean isValuable()) are detected for use or not. Note that in addition to naming, and lack of arguments, return value also has to be boolean or java.lang.Boolean.
        Since:
        2.5
      • USE_FIELDS

        public static final JSON.Feature USE_FIELDS
        Feature that enables use of public fields instead of setters and getters, in cases where no setter/getter is available.

        Feature is enabled by default since 2.10 (but was disabled for 2.8 and 2.9), so public fields are discovered by default.

        Since:
        2.8 (enabled by default since 2.10)
    • Method Detail

      • values

        public static JSON.Feature[] values()
        Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
        for (JSON.Feature c : JSON.Feature.values())
            System.out.println(c);
        
        Returns:
        an array containing the constants of this enum type, in the order they are declared
      • valueOf

        public static JSON.Feature valueOf​(java.lang.String name)
        Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
        Parameters:
        name - the name of the enum constant to be returned.
        Returns:
        the enum constant with the specified name
        Throws:
        java.lang.IllegalArgumentException - if this enum type has no constant with the specified name
        java.lang.NullPointerException - if the argument is null
      • defaults

        public static int defaults()
      • cacheBreakers

        public static int cacheBreakers()
        Method for calculating bitset of features that force flushing of POJO handler caches.
        Since:
        2.8
      • enabledByDefault

        public final boolean enabledByDefault()
      • affectsCaching

        public final boolean affectsCaching()
      • mask

        public final int mask()
      • isDisabled

        public final boolean isDisabled​(int flags)
      • isEnabled

        public final boolean isEnabled​(int flags)