Move Enum-related DeserializationFeatures into EnumFeature

release-notes/VERSION

@@ -11,6 +11,8 @@ Versions: 3.x (for earlier see VERSION-2.x)
 #5066: Move date/time `SerializationFeature`s into `DateTimeFeature` (3.0)
 #5067: Move date/time `DeserializationFeature`s into `DateTimeFeature` (3.0)
 - Branch rename "master" -> "3.x" [JSTEP-12]
+#5080: Move Enum-related SerializationFeatures into EnumFeature (3.0)
+ (contributed by Joo-Hyuk K)
 
 3.0.0-rc3 (not yet released)
 

src/main/java/tools/jackson/databind/DeserializationFeature.java

@@ -129,20 +129,6 @@ public enum DeserializationFeature implements ConfigFeature
      */
     FAIL_ON_NULL_FOR_PRIMITIVES(true),
 
-    /**
-     * Feature that determines whether JSON integer numbers are valid
-     * values to be used for deserializing Java enum values.
-     * If set to 'false' numbers are acceptable and are used to map to
-     * ordinal() of matching enumeration value; if 'true', numbers are
-     * not allowed and a {@link DatabindException} will be thrown.
-     * Latter behavior makes sense if there is concern that accidental
-     * mapping from integer values to enums might happen (and when enums
-     * are always serialized as JSON Strings)
-     *<p>
-     * Feature is disabled by default.
-     */
-    FAIL_ON_NUMBERS_FOR_ENUMS(false),
-
     /**
      * Feature that determines what happens when type of a polymorphic
      * value (indicated for example by {@link com.fasterxml.jackson.annotation.JsonTypeInfo})
@@ -407,48 +393,6 @@ public enum DeserializationFeature implements ConfigFeature
      */
     ACCEPT_FLOAT_AS_INT(true),
 
-    /**
-     * Feature that determines the deserialization mechanism used for
-     * Enum values: if enabled, Enums are assumed to have been serialized using
-     * return value of {@code Enum.toString()};
-     * if disabled, return value of {@code Enum.name()} is assumed to have been used.
-     *<p>
-     * Note: this feature should usually have same value
-     * as {@link SerializationFeature#WRITE_ENUMS_USING_TO_STRING}.
-     *<p>
-     * Feature is enabled by default as of Jackson 3.0 (in 2.x it was disabled).
-     */
-    READ_ENUMS_USING_TO_STRING(true),
-
-    /**
-     * Feature that allows unknown Enum values to be parsed as {@code null} values.
-     * If disabled, unknown Enum values will throw exceptions.
-     * <p>
-     * Note that in some cases this will effectively ignore unknown {@code Enum} values,
-     * e.g. when the unknown values are used as keys of {@link java.util.EnumMap}
-     * or values of {@link java.util.EnumSet}: this is because these data structures cannot
-     * store {@code null} values.
-     * <p>
-     * Also note that this feature has lower precedence than
-     * {@link DeserializationFeature#READ_UNKNOWN_ENUM_VALUES_USING_DEFAULT_VALUE},
-     * meaning this feature will work only if latter feature is disabled.
-     * <p>
-     * Feature is disabled by default.
-     */
-    READ_UNKNOWN_ENUM_VALUES_AS_NULL(false),
-
-    /**
-     * Feature that allows unknown Enum values to be ignored and replaced by a predefined value specified through
-     * {@link com.fasterxml.jackson.annotation.JsonEnumDefaultValue @JsonEnumDefaultValue} annotation.
-     * If disabled, unknown Enum values will throw exceptions.
-     * If enabled, but no predefined default Enum value is specified, an exception will be thrown as well.
-     * <p>
-     * Note that this feature has higher precedence than {@link DeserializationFeature#READ_UNKNOWN_ENUM_VALUES_AS_NULL}.
-     * <p>
-     * Feature is disabled by default.
-     */
-    READ_UNKNOWN_ENUM_VALUES_USING_DEFAULT_VALUE(false),
-
     /*
     /**********************************************************************
     /* Other

src/main/java/tools/jackson/databind/ObjectMapper.java

@@ -1979,6 +1979,15 @@ public ObjectWriter writer(SerializationFeature first,
         return _newWriter(serializationConfig().with(first, other));
     }
 
+    /**
+     * Factory method for constructing {@link ObjectWriter} with
+     * specified features enabled (compared to settings that this
+     * mapper instance has).
+     */
+    public ObjectWriter writer(DatatypeFeature f) {
+        return _newWriter(serializationConfig().with(f));
+    }
+
     /**
      * Factory method for constructing {@link ObjectWriter} that will
      * serialize objects using specified {@link DateFormat}; or, if
@@ -2132,6 +2141,17 @@ public ObjectReader reader(DeserializationFeature first,
         return _newReader(deserializationConfig().with(first, other));
     }
 
+    /**
+     * Factory method for constructing {@link ObjectReader} with
+     * specified feature enabled (compared to settings that this
+     * mapper instance has).
+     * Note that the resulting instance is NOT usable as is,
+     * without defining expected value type.
+     */
+    public ObjectReader reader(DatatypeFeature feature) {
+        return _newReader(deserializationConfig().with(feature));
+    }
+
     /**
      * Factory method for constructing {@link ObjectReader} that will
      * update given Object (usually Bean, but can be a Collection or Map

src/main/java/tools/jackson/databind/SerializationFeature.java

@@ -182,51 +182,6 @@ public enum SerializationFeature implements ConfigFeature
      */
     WRITE_CHAR_ARRAYS_AS_JSON_ARRAYS(false),
 
-    /**
-     * Feature that determines standard serialization mechanism used for
-     * Enum values: if enabled, return value of <code>Enum.toString()</code>
-     * is used; if disabled, return value of <code>Enum.name()</code> is used.
-     *<p>
-     * Note: this feature should usually have same value
-     * as {@link DeserializationFeature#READ_ENUMS_USING_TO_STRING}.
-     *<p>
-     * Feature is enabled by default as of Jackson 3.0 (in 2.x it was disabled).
-     */
-    WRITE_ENUMS_USING_TO_STRING(true),
-
-    /**
-     * 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 <code>Enum.ordinal()</code>
-     * (an integer) will be used as the serialization.
-     *<p>
-     * Note that this feature has precedence over {@link #WRITE_ENUMS_USING_TO_STRING},
-     * which is only considered if this feature is set to false.
-     *<p>
-     * 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}.
-     *<p>
-     * 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.
-     *<p>
-     * NOTE: counterpart for this settings is
-     * {@link EnumFeature#READ_ENUM_KEYS_USING_INDEX}.
-     *<p>
-     * Feature is disabled by default.
-     */
-    WRITE_ENUM_KEYS_USING_INDEX(false),
-
     /**
      * Feature that determines whether Container properties (POJO properties
      * with declared value of Collection or array; i.e. things that produce JSON

src/main/java/tools/jackson/databind/cfg/CoercionConfigs.java

@@ -208,7 +208,7 @@ public CoercionAction findCoercion(DeserializationConfig config,
             break;
         case Integer:
             if (targetType == LogicalType.Enum) {
-                if (config.isEnabled(DeserializationFeature.FAIL_ON_NUMBERS_FOR_ENUMS)) {
+                if (config.isEnabled(EnumFeature.FAIL_ON_NUMBERS_FOR_ENUMS)) {
                     return CoercionAction.Fail;
                 }
             }

src/main/java/tools/jackson/databind/cfg/EnumFeature.java

@@ -1,27 +1,97 @@
 package tools.jackson.databind.cfg;
 
-import tools.jackson.databind.SerializationFeature;
+import tools.jackson.databind.DatabindException;
 
 /**
  * New Datatype-specific configuration options related to handling of
  * {@link java.lang.Enum} types.
  */
 public enum EnumFeature implements DatatypeFeature
 {
+    /*
+    /**********************************************************************
+    /* READ
+    /**********************************************************************
+     */
+
     /**
      * Feature that determines standard deserialization mechanism used for
      * Enum values: if enabled, Enums are assumed to have been serialized using
      * index of <code>Enum</code>;
      *<p>
      * Note: this feature should be symmetric to
-     * as {@link SerializationFeature#WRITE_ENUM_KEYS_USING_INDEX}.
+     * as {@link #WRITE_ENUM_KEYS_USING_INDEX}.
      *<p>
      * Feature is disabled by default.
      *
      * @since 2.15
      */
     READ_ENUM_KEYS_USING_INDEX(false),
 
+
+    /**
+     * Feature that determines the deserialization mechanism used for
+     * Enum values: if enabled, Enums are assumed to have been serialized using
+     * return value of {@code Enum.toString()};
+     * if disabled, return value of {@code Enum.name()} is assumed to have been used.
+     *<p>
+     * Note: this feature should usually have same value
+     * as {@link #WRITE_ENUMS_USING_TO_STRING}.
+     *<p>
+     * Feature is enabled by default as of Jackson 3.0 (in 2.x it was disabled).
+     */
+    READ_ENUMS_USING_TO_STRING(true),
+
+    /**
+     * Feature that allows unknown Enum values to be parsed as {@code null} values.
+     * If disabled, unknown Enum values will throw exceptions.
+     * <p>
+     * Note that in some cases this will effectively ignore unknown {@code Enum} values,
+     * e.g. when the unknown values are used as keys of {@link java.util.EnumMap}
+     * or values of {@link java.util.EnumSet}: this is because these data structures cannot
+     * store {@code null} values.
+     * <p>
+     * Also note that this feature has lower precedence than
+     * {@link #READ_UNKNOWN_ENUM_VALUES_USING_DEFAULT_VALUE},
+     * meaning this feature will work only if latter feature is disabled.
+     * <p>
+     * Feature is disabled by default.
+     */
+    READ_UNKNOWN_ENUM_VALUES_AS_NULL(false),
+
+    /**
+     * Feature that allows unknown Enum values to be ignored and replaced by a predefined value specified through
+     * {@link com.fasterxml.jackson.annotation.JsonEnumDefaultValue @JsonEnumDefaultValue} annotation.
+     * If disabled, unknown Enum values will throw exceptions.
+     * If enabled, but no predefined default Enum value is specified, an exception will be thrown as well.
+     * <p>
+     * Note that this feature has higher precedence than {@link #READ_UNKNOWN_ENUM_VALUES_AS_NULL}.
+     * <p>
+     * Feature is disabled by default.
+     */
+    READ_UNKNOWN_ENUM_VALUES_USING_DEFAULT_VALUE(false),
+
+    /**
+     * Feature that determines whether JSON integer numbers are valid
+     * values to be used for deserializing Java enum values.
+     * If set to 'false' numbers are acceptable and are used to map to
+     * ordinal() of matching enumeration value; if 'true', numbers are
+     * not allowed and a {@link DatabindException} will be thrown.
+     * Latter behavior makes sense if there is concern that accidental
+     * mapping from integer values to enums might happen (and when enums
+     * are always serialized as JSON Strings)
+     *<p>
+     * Feature is disabled by default.
+     */
+    FAIL_ON_NUMBERS_FOR_ENUMS(false),
+
+    /*
+    /**********************************************************************
+    /* WRITE
+    /**********************************************************************
+     */
+
+
     /**
      * Feature that determines standard serialization mechanism used for
      * Enum values: if enabled, return value of <code>Enum.name().toLowerCase()</code>
@@ -34,7 +104,54 @@ public enum EnumFeature implements DatatypeFeature
      *
      * @since 2.15
      */
-    WRITE_ENUMS_TO_LOWERCASE(false);
+    WRITE_ENUMS_TO_LOWERCASE(false),
+
+
+    /**
+     * Feature that determines standard serialization mechanism used for
+     * Enum values: if enabled, return value of <code>Enum.toString()</code>
+     * is used; if disabled, return value of <code>Enum.name()</code> is used.
+     *<p>
+     * Note: this feature should usually have same value
+     * as {@link #READ_ENUMS_USING_TO_STRING}.
+     *<p>
+     * Feature is enabled by default as of Jackson 3.0 (in 2.x it was disabled).
+     */
+    WRITE_ENUMS_USING_TO_STRING(true),
+
+    /**
+     * 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 <code>Enum.ordinal()</code>
+     * (an integer) will be used as the serialization.
+     *<p>
+     * Note that this feature has precedence over {@link #WRITE_ENUMS_USING_TO_STRING},
+     * which is only considered if this feature is set to false.
+     *<p>
+     * 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}.
+     *<p>
+     * 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.
+     *<p>
+     * NOTE: counterpart for this settings is
+     * {@link EnumFeature#READ_ENUM_KEYS_USING_INDEX}.
+     *<p>
+     * Feature is disabled by default.
+     */
+    WRITE_ENUM_KEYS_USING_INDEX(false),
+    ;
 
     private final static int FEATURE_INDEX = DatatypeFeatures.FEATURE_INDEX_ENUM;
 

src/main/java/tools/jackson/databind/cfg/MapperBuilder.java

@@ -814,11 +814,11 @@ public B configureForJackson2() {
                 .disable(DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES,
                         DeserializationFeature.FAIL_ON_TRAILING_TOKENS)
                 .enable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
-                .disable(DeserializationFeature.READ_ENUMS_USING_TO_STRING)
+                .disable(EnumFeature.READ_ENUMS_USING_TO_STRING)
                 .enable(SerializationFeature.FAIL_ON_EMPTY_BEANS)
                 .enable(DateTimeFeature.WRITE_DATES_AS_TIMESTAMPS,
                         DateTimeFeature.WRITE_DURATIONS_AS_TIMESTAMPS)
-                .disable(SerializationFeature.WRITE_ENUMS_USING_TO_STRING)
+                .disable(EnumFeature.WRITE_ENUMS_USING_TO_STRING)
                 .disable(DateTimeFeature.ONE_BASED_MONTHS)
                 ;
     }