ISSUE-512: Refactor @JsonWrapped implementation - simplify wrapper contract and validation

Cleaned up the @JsonWrapped annotation implementation to use a three-value return contract
for the wrapper name: null (not present), empty string (explicitly disabled in mix-ins),
or non-empty string (active wrapper). Removed the redundant 'enabled' flag and simplified
validation logic in BeanDeserializerBase. Updated WrappedPropertyHandler method signatures.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Author: sri-adarsh-kumar

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

@@ -513,8 +513,13 @@ public Object findTypeIdResolver(MapperConfig<?> config, Annotated ann) {
 
     /**
      * Method for finding the wrapped group name for a member annotated
-     * with {@code @JsonWrapped}. Returns the wrapper object name if the
-     * member should be wrapped, or {@code null} if not.
+     * with {@code @JsonWrapped}. Three-value return contract:
+     * <ul>
+     *   <li>{@code null} — annotation not present; secondary introspector may supply a value</li>
+     *   <li>{@code ""} (empty string) — annotation present but explicitly disabled;
+     *       secondary introspector must NOT override</li>
+     *   <li>non-empty string — active wrapper name</li>
+     * </ul>
      *
      * @since 3.1
      */

src/main/java/tools/jackson/databind/annotation/JsonWrapped.java

@@ -41,9 +41,11 @@
  *
  * <p>Constraints:
  * <ul>
- *   <li>Only scalar and primitive types are supported as wrapped fields
- *       (containers, maps, arrays, and nested POJOs will cause a mapping error).</li>
- *   <li>The wrapper name ({@code value()}) must be non-empty.</li>
+ *   <li>MVP limitation: only scalar and primitive types are currently supported as wrapped
+ *       fields (containers, maps, arrays, and nested POJOs are not yet supported).</li>
+ *   <li>The wrapper name ({@code value()}) must be non-empty, unless explicitly disabling
+ *       wrapping: an empty {@code value()} ({@code @JsonWrapped("")}) disables wrapping —
+ *       useful in mix-ins to suppress wrapping defined in a supertype.</li>
  *   <li>The wrapper name must not conflict with an existing non-wrapped property on the same bean.</li>
  *   <li>Not supported on {@code @JsonCreator} constructor or factory-method parameters.</li>
  *   <li>MVP limitation: {@code @JsonView} on inner wrapped fields is ignored — the wrapper
@@ -64,12 +66,8 @@
 public @interface JsonWrapped {
     /**
      * Single-level wrapper object name (e.g. "chr").
-     * Must be non-empty.
+     * An empty string disables wrapping (useful in mix-ins to suppress
+     * wrapping defined in a supertype).
      */
     String value();
-
-    /**
-     * Allows conditional disabling of wrapping.
-     */
-    boolean enabled() default true;
 }

src/main/java/tools/jackson/databind/deser/bean/BeanDeserializer.java

@@ -1418,8 +1418,7 @@ protected Object deserializeWithWrapped(JsonParser p, DeserializationContext ctx
             p.nextToken();
 
             if (_wrappedPropertyHandler.hasWrapperName(propName)) {
-                _wrappedPropertyHandler.handleWrappedObject(p, ctxt, bean,
-                    propName, _anySetter);
+                _wrappedPropertyHandler.handleWrappedObject(p, ctxt, bean, propName);
                 continue;
             }
 

src/main/java/tools/jackson/databind/deser/bean/BeanDeserializerBase.java

@@ -669,17 +669,14 @@ public void resolve(DeserializationContext ctxt)
             Set<SettableBeanProperty> wrappedPropSet = new HashSet<>();
             for (SettableBeanProperty prop : allProps) {
                 AnnotatedMember member = prop.getMember();
-                if (member == null) continue;
+                if (member == null) {
+                    continue;
+                }
                 String wrapperName = intr.findWrappedGroupName(ctxt.getConfig(), member);
-                if (wrapperName == null) continue;
-                wrappedPropSet.add(prop);
-
-                // Validate: empty name
-                if (wrapperName.isEmpty()) {
-                    ctxt.reportBadDefinition(handledType(),
-                        String.format("@JsonWrapped value must not be empty (on property '%s')",
-                            prop.getName()));
+                if (wrapperName == null || wrapperName.isEmpty()) {
+                    continue;  // not wrapped, or explicitly disabled via @JsonWrapped("")
                 }
+                wrappedPropSet.add(prop);
 
                 // Validate: creator parameter
                 if ((prop instanceof CreatorProperty) && ((CreatorProperty) prop).getCreatorIndex() >= 0) {

src/main/java/tools/jackson/databind/deser/impl/WrappedPropertyHandler.java

@@ -4,7 +4,6 @@
 
 import tools.jackson.core.*;
 import tools.jackson.databind.*;
-import tools.jackson.databind.deser.SettableAnyProperty;
 import tools.jackson.databind.deser.SettableBeanProperty;
 
 /**
@@ -65,15 +64,13 @@ public boolean hasWrapperName(String name) {
     /**
      * Deserialize all inner properties from a wrapper object.
      *
-     * @param p         Parser positioned at START_OBJECT of the wrapper
-     * @param ctxt      Deserialization context
-     * @param bean      The target bean being populated
+     * @param p           Parser positioned at START_OBJECT of the wrapper
+     * @param ctxt        Deserialization context
+     * @param bean        The target bean being populated
      * @param wrapperName The wrapper field name (for error messages)
-     * @param anySetter Optional any-setter from the parent bean (may be null)
      */
     public void handleWrappedObject(JsonParser p, DeserializationContext ctxt,
-            Object bean, String wrapperName,
-            /* nullable */ SettableAnyProperty anySetter)
+            Object bean, String wrapperName)
         throws JacksonException
     {
         JsonToken t = p.currentToken();
@@ -91,22 +88,13 @@ public void handleWrappedObject(JsonParser p, DeserializationContext ctxt,
             return;
         }
 
-        // Retrieve precomputed inner property lookup
+        // Invariant: caller checked hasWrapperName() so this cannot be null
         Map<String, SettableBeanProperty> innerLookup = _innerLookups.get(wrapperName);
-        if (innerLookup == null) {
-            innerLookup = Collections.emptyMap();
-        }
-
-        // Iterate inner properties
-        while ((t = p.nextToken()) != JsonToken.END_OBJECT) {
-            if (t != JsonToken.PROPERTY_NAME) {
-                ctxt.reportWrongTokenException(bean.getClass(), JsonToken.PROPERTY_NAME,
-                    "Unexpected token inside wrapped object '%s'", wrapperName);
-                return;
-            }
-            String innerName = p.currentName();
-            p.nextToken();  // move to value
 
+        // Iterate inner properties using idiomatic Jackson pattern
+        String innerName;
+        while ((innerName = p.nextName()) != null) {
+            p.nextToken(); // advance to value token
             SettableBeanProperty innerProp = innerLookup.get(innerName);
             if (innerProp != null) {
                 try {
@@ -116,19 +104,15 @@ public void handleWrappedObject(JsonParser p, DeserializationContext ctxt,
                             new JacksonException.Reference(bean, innerName));
                 }
             } else {
-                // Unknown inner property
-                if (anySetter != null) {
-                    try {
-                        anySetter.deserializeAndSet(p, ctxt, bean, innerName);
-                    } catch (Exception e) {
-                        throw DatabindException.wrapWithPath(ctxt, e,
-                                new JacksonException.Reference(bean, innerName));
-                    }
-                } else {
-                    handleUnknownInnerProperty(p, ctxt, bean, wrapperName, innerName);
-                }
+                // Unknown inner property: use standard unknown-property handling (NOT outer anySetter)
+                handleUnknownInnerProperty(p, ctxt, bean, wrapperName, innerName);
             }
         }
+        // Verify we consumed until END_OBJECT for malformed input strictness
+        if (p.currentToken() != JsonToken.END_OBJECT) {
+            ctxt.reportWrongTokenException(bean.getClass(), JsonToken.END_OBJECT,
+                "Expected END_OBJECT after wrapped group '%s'", wrapperName);
+        }
     }
 
     @SuppressWarnings("unused") // wrapperName available for subclass overrides

src/main/java/tools/jackson/databind/introspect/AnnotationIntrospectorPair.java

@@ -262,7 +262,11 @@ public NameTransformer findUnwrappingNameTransformer(MapperConfig<?> config, Ann
     @Override
     public String findWrappedGroupName(MapperConfig<?> config, AnnotatedMember member) {
         String r = _primary.findWrappedGroupName(config, member);
-        return (r == null) ? _secondary.findWrappedGroupName(config, member) : r;
+        // null = not present → try secondary; "" = explicitly disabled → don't fall through
+        if (r == null) {
+            return _secondary.findWrappedGroupName(config, member);
+        }
+        return r;
     }
 
     @Override

src/main/java/tools/jackson/databind/introspect/JacksonAnnotationIntrospector.java

@@ -520,10 +520,10 @@ public NameTransformer findUnwrappingNameTransformer(MapperConfig<?> config, Ann
     @Override
     public String findWrappedGroupName(MapperConfig<?> config, AnnotatedMember member) {
         JsonWrapped ann = _findAnnotation(member, JsonWrapped.class);
-        if (ann == null || !ann.enabled()) {
+        if (ann == null) {
             return null;
         }
-        return ann.value();
+        return ann.value(); // "" means disabled; non-empty means active
     }
 
     @Override // since 2.9

src/main/java/tools/jackson/databind/ser/BeanSerializerFactory.java

@@ -909,20 +909,13 @@ protected List<BeanPropertyWriter> _groupWrappedProperties(SerializationContext
                 continue;
             }
             String wrapperName = intr.findWrappedGroupName(config, member);
-            if (wrapperName == null) {
-                continue;
+            if (wrapperName == null || wrapperName.isEmpty()) {
+                continue;  // not wrapped, or explicitly disabled via @JsonWrapped("")
             }
 
             // Cache the wrapper name for later use
             wrapperNameCache.put(prop, wrapperName);
 
-            // Validate: empty name
-            if (wrapperName.isEmpty()) {
-                ctxt.reportBadTypeDefinition(beanDescRef,
-                    "@JsonWrapped value must not be empty (on property '%s')", prop.getName());
-                continue;
-            }
-
             // Validate: scalar-only
             JavaType type = prop.getType();
             if (!_isScalarType(type)) {

src/test/java/tools/jackson/databind/struct/JsonWrappedDeserializationTest.java

@@ -72,7 +72,7 @@ static class MultiWrapperBean {
         public MultiWrapperBean() { }
     }
 
-    private final ObjectMapper MAPPER = JsonMapper.builder().build();
+    private final ObjectMapper MAPPER = newJsonMapper();
 
     @Nested
     @DisplayName("basic deserialization")
@@ -194,7 +194,7 @@ void trueRoundTripMultipleWrappers() throws Exception {
     class UnknownInnerPropertyTests {
 
         @Test
-        @DisplayName("should collect unknown inner properties when @JsonAnySetter present")
+        @DisplayName("should NOT route unknown inner properties to outer @JsonAnySetter")
         public void testUnknownInnerWithAnySetter() throws Exception
         {
             // setup
@@ -203,10 +203,10 @@ public void testUnknownInnerWithAnySetter() throws Exception
             // when
             BeanWithAnySetter bean = MAPPER.readValue(json, BeanWithAnySetter.class);
 
-            // then
+            // then: unknown inner props are ignored (not sent to outer anySetter)
             assertThat(bean.symbol).isEqualTo("TP53");
             assertThat(bean.chrId).isEqualTo("17");
-            assertThat(bean.extra.get("extra")).isEqualTo("val");
+            assertThat(bean.extra).isEmpty();
         }
 
         @Test

src/test/java/tools/jackson/databind/struct/JsonWrappedSerializationTest.java

@@ -74,7 +74,7 @@ public MultiWrapper(int a, int b, int c, int d) {
     }
 
     static class DisabledWrapping {
-        @JsonWrapped(value = "w", enabled = false)
+        @JsonWrapped("")   // "" = explicitly disabled
         public int x;
 
         public DisabledWrapping() { }
@@ -254,12 +254,12 @@ void wrapperWithJsonPropertyOrder() throws Exception
     }
 
     @Nested
-    @DisplayName("enabled flag tests")
-    class EnabledFlagTests {
+    @DisplayName("disabled wrapping tests")
+    class DisabledWrappingTests {
 
         @Test
-        @DisplayName("should serialize flat when enabled=false")
-        void enabledFalse() throws Exception
+        @DisplayName("should serialize flat when @JsonWrapped(\"\") disables wrapping")
+        void emptyValueDisablesWrapping() throws Exception
         {
             // setup
             DisabledWrapping bean = new DisabledWrapping(42);