Fix #556: explicit fail on nested array/Collection writes (#858)

Author: cowtowncoder

release-notes/VERSION

@@ -84,6 +84,9 @@ Version: 3.x (for earlier see VERSION-2.x)
  (fix by @cowtowncoder, w/ Claude code)
 #541: Allow specifying URI of the default namespace for root element
  (fix by @cowtowncoder, w/ Claude code)
+#556: `XmlMapper` does not support multi-dimensional arrays
+ (reported by @schwarfl)
+ (fix by @cowtowncoder, w/ Claude code)
 #561: Deserializing empty timestamp fields to `null` value doesn't
   work (instead becomes "empty", Epoch time)
  (reported by @silvestr85)

src/main/java/tools/jackson/dataformat/xml/XmlWriteFeature.java

@@ -11,6 +11,59 @@
  */
 public enum XmlWriteFeature implements FormatFeature
 {
+    /**
+     * Feature that enables automatic conversion of logical property
+     * name {@code "xsi:type"} into matching XML name where "type"
+     * is the local name and "xsi" prefix is bound to URI
+     * {@link XMLConstants#W3C_XML_SCHEMA_INSTANCE_NS_URI},
+     * and output is indicated to be done as XML Attribute.
+     * This is mostly desirable for Polymorphic handling where it is difficult
+     * to specify XML Namespace for type identifier
+     *<p>
+     * Default setting is {@code true} (enabled) in Jackson 3.0:
+     * it was {@code false} (disabled)in Jackson 2.x.
+     */
+    AUTO_DETECT_XSI_TYPE(true),
+
+    /**
+     * Feature that determines whether attempt to serialize a directly nested
+     * array or {@link java.util.Collection} (i.e. an
+     * array/Collection whose immediate parent is also an array/Collection
+     * — without an intermediate POJO) should fail with an exception (true)
+     * or be allowed (false) — knowing that, when allowed, the resulting XML
+     * cannot represent the nested structure and the inner dimension will be
+     * silently flattened into the outer one, nor can it be deserialized back.
+     *<p>
+     * "Natural-style" XML has no canonical representation for an unnamed
+     * nested array, so a clean round-trip is not possible without an
+     * intermediate POJO wrapper.
+     *<p>
+     * Default setting is {@code true} (enabled): nested arrays cause an
+     * exception. Disabling restores the legacy behavior of
+     * silently flattening dimensions.
+     *<p>
+     * See <a href="https://github.com/FasterXML/jackson-dataformat-xml/issues/556">#556</a>.
+     *
+     * @since 3.2
+     */
+    FAIL_ON_NESTED_ARRAYS(true),
+
+    /**
+     * Feature that determines writing of root values of type {@code ObjectNode}
+     * ({@code JsonNode} subtype that represents Object content values),
+     * regarding XML output.
+     * If enabled and {@code ObjectNode} has exactly one entry (key/value pair),
+     * then key of that entry is used as the root element name (and value
+     * is written as contents. Otherwise (if feature disabled, or if root
+     * {@code ObjectNode} has any other number of key/value entries,
+     * root element name is determined using normal logic (either explicitly
+     * configured, or {@code ObjectNode} otherwise).
+     *<p>
+     * Default setting is {@code true} (enabled) in Jackson 3.x:
+     * it was {@code false} (disabled)in Jackson 2.x.
+     */
+    UNWRAP_ROOT_OBJECT_NODE(true),
+
     /**
      * Feature that controls whether XML declaration should be written before
      * when generator is initialized (true) or not (false)
@@ -48,36 +101,6 @@ public enum XmlWriteFeature implements FormatFeature
      */
     WRITE_NULLS_AS_XSI_NIL(true),
 
-    /**
-     * Feature that determines writing of root values of type {@code ObjectNode}
-     * ({@code JsonNode} subtype that represents Object content values),
-     * regarding XML output.
-     * If enabled and {@code ObjectNode} has exactly one entry (key/value pair),
-     * then key of that entry is used as the root element name (and value
-     * is written as contents. Otherwise (if feature disabled, or if root
-     * {@code ObjectNode} has any other number of key/value entries,
-     * root element name is determined using normal logic (either explicitly
-     * configured, or {@code ObjectNode} otherwise).
-     *<p>
-     * Default setting is {@code true} (enabled) in Jackson 3.x:
-     * it was {@code false} (disabled)in Jackson 2.x.
-     */
-    UNWRAP_ROOT_OBJECT_NODE(true),
-
-    /**
-     * Feature that enables automatic conversion of logical property
-     * name {@code "xsi:type"} into matching XML name where "type"
-     * is the local name and "xsi" prefix is bound to URI
-     * {@link XMLConstants#W3C_XML_SCHEMA_INSTANCE_NS_URI},
-     * and output is indicated to be done as XML Attribute.
-     * This is mostly desirable for Polymorphic handling where it is difficult
-     * to specify XML Namespace for type identifier
-     *<p>
-     * Default setting is {@code true} (enabled) in Jackson 3.0:
-     * it was {@code false} (disabled)in Jackson 2.x.
-     */
-    AUTO_DETECT_XSI_TYPE(true),
-
     /**
      * Feature that determines how floating-point infinity values are
      * serialized.
@@ -104,7 +127,7 @@ public enum XmlWriteFeature implements FormatFeature
      * {@link tools.jackson.dataformat.xml.XmlReadFeature}.
      *<p>
      * Default setting is {@code true} (enabled) in Jackson 3.0:
-     * it was {@code false} (disabled)in Jackson 2.x.
+     * it was {@code false} (disabled) in Jackson 2.x.
      */
     WRITE_XML_SCHEMA_CONFORMING_FLOATS(true),
     ;

src/main/java/tools/jackson/dataformat/xml/ser/ToXmlGenerator.java

@@ -651,6 +651,7 @@ public WritableTypeId writeTypePrefix(WritableTypeId typeIdDef) throws JacksonEx
     public JsonGenerator writeStartArray() throws JacksonException
     {
         _verifyValueWrite("start an array");
+        _verifyNotNestedArray();
         _streamWriteContext = _streamWriteContext.createChildArrayContext(null);
         streamWriteConstraints().validateNestingDepth(_streamWriteContext.getNestingDepth());
         if (_xmlPrettyPrinter != null) {
@@ -660,21 +661,37 @@ public JsonGenerator writeStartArray() throws JacksonException
         }
         return this;
     }
-    
+
     @Override
     public JsonGenerator writeStartArray(Object currValue) throws JacksonException
     {
         _verifyValueWrite("start an array");
+        _verifyNotNestedArray();
         _streamWriteContext = _streamWriteContext.createChildArrayContext(currValue);
         streamWriteConstraints().validateNestingDepth(_streamWriteContext.getNestingDepth());
         if (_xmlPrettyPrinter != null) {
             _xmlPrettyPrinter.writeStartArray(this);
         } else {
-            // nothing to do here; no-operation
+            // nothing to do here; no-op
         }
         return this;
     }
 
+    // [dataformat-xml#556]: nested arrays/Collections/Maps cannot be expressed
+    // in natural-style XML without an intermediate POJO. Fail fast (when the
+    // feature is enabled) instead of silently flattening dimensions.
+    //
+    // @since 3.2
+    private void _verifyNotNestedArray() throws JacksonException
+    {
+        if (_streamWriteContext.inArray()
+                && XmlWriteFeature.FAIL_ON_NESTED_ARRAYS.enabledIn(_formatFeatures)) {
+            _reportError("XML format does not support nested arrays/Collections;"
+                    + " wrap inner array in a POJO"
+                    + " (disable XmlWriteFeature.FAIL_ON_NESTED_ARRAYS to allow legacy flattening)");
+        }
+    }
+
     @Override
     public JsonGenerator writeEndArray() throws JacksonException
     {

src/test/java/tools/jackson/dataformat/xml/dos/CyclicXMLDataSerTest.java

@@ -1,7 +1,7 @@
 package tools.jackson.dataformat.xml.dos;
 
-import java.util.ArrayList;
-import java.util.List;
+import java.util.HashMap;
+import java.util.Map;
 
 import org.junit.jupiter.api.Test;
 
@@ -17,26 +17,29 @@
 
 /**
  * Simple unit tests to verify that we fail gracefully if you attempt to serialize
- * data that is cyclic (eg a list that contains itself).
+ * data that is cyclic (eg a map that contains itself).
  */
 public class CyclicXMLDataSerTest extends XmlTestUtil
 {
     private final XmlMapper MAPPER = newMapper();
 
     @Test
-    public void testListWithSelfReference() throws Exception {
-        // Avoid direct loop as serializer might be able to catch
-        List<Object> list1 = new ArrayList<>();
-        List<Object> list2 = new ArrayList<>();
-        list1.add(list2);
-        list2.add(list1);
+    public void testMapWithSelfReference() throws Exception {
+        // Use Maps (rather than Lists) so the cycle exercises object-nesting
+        // depth without tripping XmlWriteFeature.FAIL_ON_NESTED_ARRAYS.
+        // Two distinct Maps avoid trivial self-loop detection.
+        Map<String, Object> map1 = new HashMap<>();
+        Map<String, Object> map2 = new HashMap<>();
+        map1.put("ref", map2);
+        map2.put("ref", map1);
         try {
-            MAPPER.writeValueAsString(list1);
+            MAPPER.writeValueAsString(map1);
             fail("expected DatabindException for infinite recursion");
         } catch (DatabindException e) {
             String exceptionPrefix = String.format("Document nesting depth (%d) exceeds the maximum allowed",
                     StreamWriteConstraints.DEFAULT_MAX_DEPTH + 1);
-            assertTrue(e.getMessage().startsWith(exceptionPrefix));
+            assertTrue(e.getMessage().startsWith(exceptionPrefix),
+                    "Unexpected message: " + e.getMessage());
         }
     }
 }

src/test/java/tools/jackson/dataformat/xml/ser/MultidimArray556Test.java

@@ -0,0 +1,78 @@
+package tools.jackson.dataformat.xml.ser;
+
+import java.util.Arrays;
+import java.util.List;
+
+import org.junit.jupiter.api.Test;
+
+import tools.jackson.core.JacksonException;
+import tools.jackson.dataformat.xml.XmlMapper;
+import tools.jackson.dataformat.xml.XmlTestUtil;
+import tools.jackson.dataformat.xml.XmlWriteFeature;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.fail;
+
+// [dataformat-xml#556]: nested arrays/Collections cannot be represented in
+// natural-style XML without an intermediate POJO; XmlMapper currently fails
+// fast on serialization rather than silently flattening dimensions.
+public class MultidimArray556Test extends XmlTestUtil
+{
+    private final XmlMapper MAPPER = newMapper();
+
+    // Documents the current fail-fast behavior: 2D primitive array throws on
+    // serialization (was silently producing the same output as 1D before fix).
+    @Test
+    public void test2DPrimitiveArrayFailsFast() throws Exception
+    {
+        try {
+            MAPPER.writeValueAsString(new boolean[][] { { true }, { false } });
+            fail("Should not pass: nested arrays must be rejected");
+        } catch (JacksonException e) {
+            verifyException(e, "does not support nested arrays");
+        }
+    }
+
+    // Same for nested Lists.
+    @Test
+    public void testNestedListFailsFast() throws Exception
+    {
+        List<List<String>> nested = Arrays.asList(
+                Arrays.asList("a", "b"), Arrays.asList("c"));
+        try {
+            MAPPER.writeValueAsString(nested);
+            fail("Should not pass: nested Collections must be rejected");
+        } catch (JacksonException e) {
+            verifyException(e, "does not support nested arrays");
+        }
+    }
+
+    // Disabling FAIL_ON_NESTED_ARRAYS restores legacy 2.x behavior: nested
+    // dimensions are silently flattened (no exception thrown).
+    @Test
+    public void testLegacyFlatteningWhenFeatureDisabled() throws Exception
+    {
+        String xml = MAPPER.writer()
+                .without(XmlWriteFeature.FAIL_ON_NESTED_ARRAYS)
+                .writeValueAsString(new boolean[][] { { true }, { false } });
+        assertEquals("<booleans><item>true</item><item>false</item></booleans>", xml);
+    }
+
+    // Eventual goal: a 2D array should round-trip with proper nesting.
+    // Currently fails (fail-fast above); annotation inverts pass/fail so this
+    // entry tracks the unsupported-but-desired behavior.
+    /*
+    @JacksonTestFailureExpected
+    @Test
+    public void test2DArrayRoundTrip() throws Exception
+    {
+        boolean[][] input = new boolean[][] { { true }, { false } };
+        String xml = MAPPER.writeValueAsString(input);
+        boolean[][] result = MAPPER.readValue(xml, boolean[][].class);
+        assertEquals(input.length, result.length);
+        assertEquals(input[0][0], result[0][0]);
+        assertEquals(input[1][0], result[1][0]);
+    }
+    */
+}