Fixes #5065: default change for DateTimeFeature.ONE_BASED_MONTHS (#5077)

Author: cowtowncoder

release-notes/VERSION

@@ -7,6 +7,7 @@ Versions: 3.x (for earlier see VERSION-2.x)
 
 3.0.0-rc3 (not yet released)
 
+#5065: Change default for `DateTimeFeature.ONE_BASED_MONTHS` to `true` in 3.0
 - Branch rename "master" -> "3.x" [JSTEP-12]
 
 3.0.0-rc3 (not yet released)

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

@@ -34,13 +34,20 @@ public enum DateTimeFeature implements DatatypeFeature
     NORMALIZE_DESERIALIZED_ZONE_ID(true),
 
     /**
-     * Feature that determines whether {@link java.time.Month} is serialized
-     * and deserialized as using a zero-based index (FALSE) or a one-based index (TRUE).
-     * For example, "1" would be serialized/deserialized as Month.JANUARY if TRUE and Month.FEBRUARY if FALSE.
+     * Feature that determines whether {@link java.time.Month} is serialized as
+     * and deserialized expected a zero- ({@code false}) or one-based index ({@code true}).
+     * For example, {@code Month.JANUARY} would be serialized as {@code 1} when enabled
+     * but as {@code 0} when disabled.
+     * Conversely JSON Number {@code 1} would be deserialized as {@code Month.JANUARY}
+     * when enabled, but as {@code Month.FEBRUARY} when disabled.
      *<p>
-     * Default setting is false, meaning that Month is serialized/deserialized as a zero-based index.
+     * Default setting is {@code true}, meaning that Month is serialized using one-based index
+     * and deserialized expecting one-based index.
+     *<p>
+     * NOTE: default setting changed between Jackson 2.x (was {@code false}) and Jackson
+     * 3.0 (changed to {@code true}).
      */
-    ONE_BASED_MONTHS(false),
+    ONE_BASED_MONTHS(true),
 
     /**
      * Feature that determines whether the {@link java.util.TimeZone} of the

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

@@ -818,7 +818,9 @@ public B configureForJackson2() {
                 .enable(SerializationFeature.FAIL_ON_EMPTY_BEANS)
                 .enable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
                 .enable(SerializationFeature.WRITE_DURATIONS_AS_TIMESTAMPS)
-                .disable(SerializationFeature.WRITE_ENUMS_USING_TO_STRING);
+                .disable(SerializationFeature.WRITE_ENUMS_USING_TO_STRING)
+                .disable(DateTimeFeature.ONE_BASED_MONTHS)
+                ;
     }
 
     /*

src/main/java/tools/jackson/databind/ext/javatime/JavaTimeInitializer.java

@@ -20,7 +20,6 @@
 
 import tools.jackson.databind.*;
 import tools.jackson.databind.cfg.DatatypeFeatures;
-import tools.jackson.databind.cfg.DateTimeFeature;
 import tools.jackson.databind.deser.ValueInstantiator;
 import tools.jackson.databind.deser.ValueInstantiators;
 import tools.jackson.databind.deser.std.StdValueInstantiator;
@@ -158,9 +157,9 @@ public void setupModule(JacksonModule.SetupContext context) {
         );
 
         // [modules-java8#274]: 1-based Month (de)serializer need to be applied via modifiers:
-        final boolean oneBasedMonthEnabled = context.isEnabled(DateTimeFeature.ONE_BASED_MONTHS);
-        context.addDeserializerModifier(new JavaTimeDeserializerModifier(oneBasedMonthEnabled));
-        context.addSerializerModifier(new JavaTimeSerializerModifier(oneBasedMonthEnabled));
+        // [databind#5078]: Should rewrite not to require this
+        context.addDeserializerModifier(new JavaTimeDeserializerModifier());
+        context.addSerializerModifier(new JavaTimeSerializerModifier());
 
         context.addValueInstantiators(new ValueInstantiators.Base() {
             @Override

src/main/java/tools/jackson/databind/ext/javatime/deser/JavaTimeDeserializerModifier.java

@@ -5,22 +5,19 @@
 import tools.jackson.databind.*;
 import tools.jackson.databind.deser.ValueDeserializerModifier;
 
-/**
- * @since 2.17
+/* 08-Apr-2025, tatu: we really should rewrite things to have "native"
+ *   {@code MonthDeserializer} and not rely on {@code EnumDeserializer}.
  */
-public class JavaTimeDeserializerModifier extends ValueDeserializerModifier {
+public class JavaTimeDeserializerModifier extends ValueDeserializerModifier
+{
     private static final long serialVersionUID = 1L;
 
-    private final boolean _oneBaseMonths;
-
-    public JavaTimeDeserializerModifier(boolean oneBaseMonths) {
-        _oneBaseMonths = oneBaseMonths;
-    }
+    public JavaTimeDeserializerModifier() { }
 
     @Override
     public ValueDeserializer<?> modifyEnumDeserializer(DeserializationConfig config, JavaType type,
             BeanDescription beanDesc, ValueDeserializer<?> defaultDeserializer) {
-        if (_oneBaseMonths && type.hasRawClass(Month.class)) {
+        if (type.hasRawClass(Month.class)) {
             return new OneBasedMonthDeserializer(defaultDeserializer);
         }
         return defaultDeserializer;

src/main/java/tools/jackson/databind/ext/javatime/deser/OneBasedMonthDeserializer.java

@@ -6,6 +6,7 @@
 import tools.jackson.core.JsonToken;
 
 import tools.jackson.databind.*;
+import tools.jackson.databind.cfg.DateTimeFeature;
 import tools.jackson.databind.deser.std.DelegatingDeserializer;
 import tools.jackson.databind.exc.InvalidFormatException;
 
@@ -16,19 +17,23 @@ public OneBasedMonthDeserializer(ValueDeserializer<?> defaultDeserializer) {
 
     @Override
     public Object deserialize(JsonParser parser, DeserializationContext context) {
-        JsonToken token = parser.currentToken();
-        switch (token) {
-            case VALUE_NUMBER_INT:
-                return _decodeMonth(parser.getIntValue(), parser);
-            case VALUE_STRING:
-                String monthSpec = parser.getString();
-                int oneBasedMonthNumber = _decodeNumber(monthSpec);
-                if (oneBasedMonthNumber >= 0) {
-                    return _decodeMonth(oneBasedMonthNumber, parser);
-                }
-            default:
-                // Otherwise fall through to default handling
-                break;
+        final boolean oneBased = context.isEnabled(DateTimeFeature.ONE_BASED_MONTHS);
+        if (oneBased) {
+            JsonToken token = parser.currentToken();
+            switch (token) {
+                case VALUE_NUMBER_INT:
+                    return _decodeMonth(parser.getIntValue(), parser);
+                case VALUE_STRING:
+                    String monthSpec = parser.getString();
+                    int oneBasedMonthNumber = _decodeNumber(monthSpec);
+                    if (oneBasedMonthNumber >= 0) {
+                        return _decodeMonth(oneBasedMonthNumber, parser);
+                    }
+                default:
+                    // Otherwise fall through to default handling
+                    break;
+            }
+            // fall-through
         }
         return getDelegatee().deserialize(parser, context);
     }

src/main/java/tools/jackson/databind/ext/javatime/ser/JavaTimeSerializerModifier.java

@@ -5,22 +5,15 @@
 import tools.jackson.databind.*;
 import tools.jackson.databind.ser.ValueSerializerModifier;
 
-/**
- * @since 2.17
- */
 public class JavaTimeSerializerModifier extends ValueSerializerModifier {
     private static final long serialVersionUID = 1L;
 
-    private final boolean _oneBaseMonths;
-
-    public JavaTimeSerializerModifier(boolean oneBaseMonths) {
-        _oneBaseMonths = oneBaseMonths;
-    }
+    public JavaTimeSerializerModifier() { }
 
     @Override
     public ValueSerializer<?> modifyEnumSerializer(SerializationConfig config, JavaType valueType,
             BeanDescription beanDesc, ValueSerializer<?> serializer) {
-        if (_oneBaseMonths && valueType.hasRawClass(Month.class)) {
+        if (valueType.hasRawClass(Month.class)) {
             return new OneBasedMonthSerializer(serializer);
         }
         return serializer;

src/main/java/tools/jackson/databind/ext/javatime/ser/OneBasedMonthSerializer.java

@@ -5,11 +5,10 @@
 import tools.jackson.core.JsonGenerator;
 
 import tools.jackson.databind.*;
+import tools.jackson.databind.cfg.DateTimeFeature;
 
-/**
- * @since 2.17
- */
-public class OneBasedMonthSerializer extends ValueSerializer<Month> {
+public class OneBasedMonthSerializer extends ValueSerializer<Month>
+{
     private final ValueSerializer<Object> _defaultSerializer;
 
     @SuppressWarnings("unchecked")
@@ -21,12 +20,15 @@ public OneBasedMonthSerializer(ValueSerializer<?> defaultSerializer)
     @Override
     public void serialize(Month value, JsonGenerator gen, SerializationContext ctxt)
     {
-        // 15-Jan-2024, tatu: [modules-java8#274] This is not really sufficient
-        //   (see `jackson-databind` `EnumSerializer` for full logic), but has to
-        //   do for now. May need to add `@JsonFormat.shape` handling in future.
-        if (ctxt.isEnabled(SerializationFeature.WRITE_ENUMS_USING_INDEX)) {
-            gen.writeNumber(value.ordinal() + 1);
-            return;
+        final boolean oneBased = ctxt.isEnabled(DateTimeFeature.ONE_BASED_MONTHS);
+        if (oneBased) {
+            // 15-Jan-2024, tatu: [modules-java8#274] This is not really sufficient
+            //   (see `jackson-databind` `EnumSerializer` for full logic), but has to
+            //   do for now. May need to add `@JsonFormat.shape` handling in future.
+            if (ctxt.isEnabled(SerializationFeature.WRITE_ENUMS_USING_INDEX)) {
+                gen.writeNumber(value.ordinal() + 1);
+                return;
+            }
         }
         _defaultSerializer.serialize(value, gen, ctxt);
     }

src/test/java/tools/jackson/databind/ext/javatime/DateTimeTestBase.java

@@ -9,6 +9,7 @@
 import tools.jackson.databind.json.JsonMapper;
 
 public class DateTimeTestBase
+    extends tools.jackson.databind.testutil.DatabindTestUtil
 {
     protected static final ZoneId UTC = ZoneId.of("UTC");
 
@@ -45,27 +46,6 @@ protected static JsonMapper.Builder mapperBuilder() {
                 .disable(JsonWriteFeature.ESCAPE_FORWARD_SLASHES);
     }
 
-    protected String q(String value) {
-        return "\"" + value + "\"";
-    }
-
-    protected String a2q(String json) {
-        return json.replace("'", "\"");
-    }
-
-    protected void verifyException(Throwable e, String... matches)
-    {
-        String msg = e.getMessage();
-        String lmsg = (msg == null) ? "" : msg.toLowerCase();
-        for (String match : matches) {
-            String lmatch = match.toLowerCase();
-            if (lmsg.indexOf(lmatch) >= 0) {
-                return;
-            }
-        }
-        throw new Error("Expected an exception with one of substrings ("+Arrays.asList(matches)+"): got one with message \""+msg+"\"");
-    }
-
     protected static <T> Map<T, String> asMap(T key, String value) {
         return Collections.singletonMap(key, value);
     }

src/test/java/tools/jackson/databind/ext/javatime/deser/OneBasedMonthDeserTest.java

@@ -93,7 +93,8 @@ static void assertError(Executable codeToRun, Class<? extends Throwable> expecte
         }
     }
 
-
+    private final ObjectMapper MAPPER = newJsonMapper();
+    
     @Test
     public void testDeserialization01_zeroBased() throws Exception
     {
@@ -161,9 +162,9 @@ public void testFormatAnnotation_oneBased() throws Exception
     }
 
     /*
-    /**********************************************************
+    /**********************************************************************
     /* Tests for empty string handling
-    /**********************************************************
+    /**********************************************************************
      */
 
     @Test
@@ -192,16 +193,14 @@ public void testDeserializeFromEmptyString() throws Exception
     }
 
     private ObjectReader readerForZeroBased() {
-        return JsonMapper.builder()
-                .disable(DateTimeFeature.ONE_BASED_MONTHS)
-                .build()
-                .readerFor(Month.class);
+        return MAPPER
+                .readerFor(Month.class)
+                .without(DateTimeFeature.ONE_BASED_MONTHS);
     }
 
     private ObjectReader readerForOneBased() {
-        return JsonMapper.builder()
-                .enable(DateTimeFeature.ONE_BASED_MONTHS)
-                .build()
-                .readerFor(Month.class);
+        return MAPPER
+            .readerFor(Month.class)
+            .with(DateTimeFeature.ONE_BASED_MONTHS);
     }
 }