Merge pull request #3518 from apache/CAUSEWAY-3989

Causeway 3989

Author: danhaywood

api/applib/src/main/java/module-info.java

@@ -124,8 +124,6 @@
     exports org.apache.causeway.applib.value;
     exports org.apache.causeway.applib.value.semantics;
 
-    requires com.fasterxml.jackson.core;
-    requires com.fasterxml.jackson.databind;
     requires transitive jakarta.activation;
     requires transitive java.annotation;
     requires transitive java.desktop;
@@ -146,7 +144,7 @@
     requires transitive spring.core;
     requires spring.tx;
     requires org.apache.logging.log4j.core;
-	requires com.fasterxml.jackson.annotation;
+    requires com.fasterxml.jackson.dataformat.yaml;
 
     // JAXB viewmodels
     opens org.apache.causeway.applib.annotation;

api/applib/src/main/java/org/apache/causeway/applib/util/schema/CommandDtoUtils.java

@@ -19,8 +19,10 @@
 package org.apache.causeway.applib.util.schema;
 
 import java.io.IOException;
+import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
+import java.util.Optional;
 import java.util.stream.Collectors;
 
 import javax.xml.datatype.DatatypeConstants;
@@ -37,6 +39,7 @@
 import org.apache.causeway.commons.io.JsonUtils;
 import org.apache.causeway.commons.io.JsonUtils.JacksonCustomizer;
 import org.apache.causeway.commons.io.YamlUtils;
+import org.apache.causeway.commons.functional.Try;
 import org.apache.causeway.schema.cmd.v2.ActionDto;
 import org.apache.causeway.schema.cmd.v2.CommandDto;
 import org.apache.causeway.schema.cmd.v2.MapDto;
@@ -54,11 +57,13 @@
 import com.fasterxml.jackson.databind.DeserializationContext;
 import com.fasterxml.jackson.databind.JsonDeserializer;
 import com.fasterxml.jackson.databind.JsonSerializer;
+import com.fasterxml.jackson.databind.MappingIterator;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.SerializerProvider;
 import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
 import com.fasterxml.jackson.databind.annotation.JsonSerialize;
 import com.fasterxml.jackson.databind.jsontype.NamedType;
+import com.fasterxml.jackson.dataformat.yaml.YAMLFactory;
 
 import lombok.experimental.UtilityClass;
 
@@ -150,7 +155,7 @@ private MapDto userDataFor(final CommandDto commandDto) {
     // -- YAML SUPPORT
 
     public String toYaml(final Iterable<CommandDto> commandDtos) {
-    	final JsonUtils.JacksonCustomizer customizer = new JacksonCustomizer() {
+    	final var customizer = new JacksonCustomizer() {
 			@Override
 			public ObjectMapper apply(ObjectMapper mapper) {
 				JsonUtils.jaxbAnnotationSupport(mapper);
@@ -160,26 +165,68 @@ public ObjectMapper apply(ObjectMapper mapper) {
 				return mapper;
 			}
 		};
-        return YamlUtils.toStringUtf8(
-            _NullSafe.stream(commandDtos)
-                .collect(Collectors.toList()),
-            customizer);
+        final var commandDtoList = _NullSafe.stream(commandDtos)
+                .collect(Collectors.toList());
+        return YamlUtils.toStringUtf8ForList(
+                commandDtoList, YamlUtils.Marshalling.MULTI_DOC,
+                customizer);
     }
 
     public List<CommandDto> fromYaml(final DataSource commandDtosYaml) {
-    	final JsonUtils.JacksonCustomizer customizer = new JacksonCustomizer() {
-			@Override
-			public ObjectMapper apply(ObjectMapper mapper) {
-				JsonUtils.jaxbAnnotationSupport(mapper);
-				CommandDtoUtils.memberDtoSupport(mapper);
-				CommandDtoUtils.valueDtoSupport(mapper);
-				return mapper;
-			}
-		};
-        return YamlUtils.tryReadAsList(CommandDto.class, commandDtosYaml, customizer)
-            .ifFailureFail()
-            .getValue()
-            .orElseGet(Collections::emptyList);
+	    final var customizer = yamlCommandDtoCustomizer();
+
+        final Try<List<CommandDto>> asList = YamlUtils.tryReadAsList(CommandDto.class, commandDtosYaml, customizer);
+        if (asList.isSuccess()) {
+            return asList.getValue().orElseGet(Collections::emptyList);
+        }
+
+        final Try<List<CommandDto>> asMultiDocument = tryReadAsMultiDocument(CommandDto.class, commandDtosYaml, customizer);
+        asMultiDocument.getFailure().ifPresent(multiDocFailure ->
+            asList.getFailure().ifPresent(multiDocFailure::addSuppressed));
+
+        return asMultiDocument
+                .ifFailureFail()
+                .getValue()
+                .orElseGet(Collections::emptyList);
+    }
+
+    private JsonUtils.JacksonCustomizer yamlCommandDtoCustomizer() {
+        return mapper -> {
+            JsonUtils.jaxbAnnotationSupport(mapper);
+            CommandDtoUtils.memberDtoSupport(mapper);
+            CommandDtoUtils.valueDtoSupport(mapper);
+            return mapper;
+        };
+    }
+
+    private <T> Try<List<T>> tryReadAsMultiDocument(
+            final Class<T> elementType,
+            final DataSource source,
+            final JsonUtils.JacksonCustomizer ... customizers) {
+        return source.tryReadAll(is -> Try.call(() -> {
+            final var mapper = createYamlReader(customizers);
+            final MappingIterator<T> documentReader = mapper.readerFor(elementType).readValues(is);
+            final List<T> elements = new ArrayList<>();
+            while (documentReader.hasNextValue()) {
+                final T next = documentReader.nextValue();
+                if (next != null) {
+                    elements.add(next);
+                }
+            }
+            return elements;
+        }));
+    }
+
+    private ObjectMapper createYamlReader(final JsonUtils.JacksonCustomizer ... customizers) {
+        var mapper = new ObjectMapper(new YAMLFactory());
+        mapper = JsonUtils.jdk8Support(mapper);
+        mapper = JsonUtils.readingJavaTimeSupport(mapper);
+        mapper = JsonUtils.readingCanSupport(mapper);
+        for (final var customizer : customizers) {
+            mapper = Optional.ofNullable(customizer.apply(mapper))
+                    .orElse(mapper);
+        }
+        return mapper;
     }
 
     // Mix-in to add type metadata to MemberDto

api/applib/src/test/java/org/apache/causeway/applib/util/schema/CommandDtoUtils_fromYaml_Test.commands-with-scalar-params-multi-document-trailing-empty.yaml

@@ -0,0 +1,35 @@
+majorVersion: "2"
+minorVersion: "0"
+interactionId: "08c210e1-55c0-4c45-83db-491f6581e621"
+timestamp: "2026-04-21T09:43:58.169+00:00"
+username: "estatio-admin"
+targets:
+  oid:
+    - type: "outgoing.invoiceforlease.InvoiceForLease"
+      id: "419264"
+member: !<ACT>
+  logicalMemberIdentifier: "outgoing.invoiceforlease.InvoiceForLease#approve"
+  interactionType: "action_invocation"
+---
+majorVersion: "2"
+minorVersion: "0"
+interactionId: "0e2ad15e-c1d8-48c5-8b63-b8cdde673715"
+timestamp: "2026-04-21T09:45:07.409+00:00"
+username: "estatio-admin"
+targets:
+  oid:
+    - type: "outgoing.invoiceforlease.InvoiceForLease"
+      id: "419264"
+member: !<ACT>
+  parameters:
+    parameter:
+      - localDate: "2026-04-20"
+        type: "localDate"
+        name: "Invoice Date"
+      - boolean: false
+        type: "boolean"
+        name: "Allow Invoice Date In Future"
+  logicalMemberIdentifier: "outgoing.invoiceforlease.InvoiceForLease#invoice"
+  interactionType: "action_invocation"
+---
+

api/applib/src/test/java/org/apache/causeway/applib/util/schema/CommandDtoUtils_fromYaml_Test.commands-with-scalar-params-multi-document.yaml

@@ -0,0 +1,34 @@
+majorVersion: "2"
+minorVersion: "0"
+interactionId: "08c210e1-55c0-4c45-83db-491f6581e621"
+timestamp: "2026-04-21T09:43:58.169+00:00"
+username: "estatio-admin"
+targets:
+  oid:
+    - type: "outgoing.invoiceforlease.InvoiceForLease"
+      id: "419264"
+member: !<ACT>
+  logicalMemberIdentifier: "outgoing.invoiceforlease.InvoiceForLease#approve"
+  interactionType: "action_invocation"
+---
+majorVersion: "2"
+minorVersion: "0"
+interactionId: "0e2ad15e-c1d8-48c5-8b63-b8cdde673715"
+timestamp: "2026-04-21T09:45:07.409+00:00"
+username: "estatio-admin"
+targets:
+  oid:
+    - type: "outgoing.invoiceforlease.InvoiceForLease"
+      id: "419264"
+member: !<ACT>
+  parameters:
+    parameter:
+      - localDate: "2026-04-20"
+        type: "localDate"
+        name: "Invoice Date"
+      - boolean: false
+        type: "boolean"
+        name: "Allow Invoice Date In Future"
+  logicalMemberIdentifier: "outgoing.invoiceforlease.InvoiceForLease#invoice"
+  interactionType: "action_invocation"
+

api/applib/src/test/java/org/apache/causeway/applib/util/schema/CommandDtoUtils_fromYaml_Test.java

@@ -41,6 +41,25 @@ public class CommandDtoUtils_fromYaml_Test {
     public void scalarValues() throws IOException {
         var commandDtos = loadCommands("commands-with-scalar-params.yaml");
 
+        assertScalarCommands(commandDtos);
+    }
+
+    @Test
+    public void scalarValuesAsMultiDocument() throws IOException {
+        var commandDtos = loadCommands("commands-with-scalar-params-multi-document.yaml");
+
+        assertScalarCommands(commandDtos);
+    }
+
+    @Test
+    public void scalarValuesAsMultiDocumentWithTrailingEmptyDocument() throws IOException {
+        var commandDtos = loadCommands("commands-with-scalar-params-multi-document-trailing-empty.yaml");
+
+        assertScalarCommands(commandDtos);
+    }
+
+    private static void assertScalarCommands(final List<CommandDto> commandDtos) {
+
         Assertions.assertThat(commandDtos).hasSize(2);
 
         ActionDto firstAction = (ActionDto) commandDtos.get(0).getMember();

commons/src/main/java/org/apache/causeway/commons/io/YamlUtils.java

@@ -19,6 +19,7 @@
 package org.apache.causeway.commons.io;
 
 import java.io.InputStream;
+import java.util.ArrayList;
 import java.util.List;
 import java.util.Optional;
 
@@ -42,6 +43,11 @@
 @UtilityClass
 public class YamlUtils {
 
+    public enum Marshalling {
+        YAML_LIST,
+        MULTI_DOC
+    }
+
     // -- READING
 
     /**
@@ -111,6 +117,40 @@ public static String toStringUtf8(
                 ? createJacksonWriter(customizers).writeValueAsString(pojo)
                 : null;
     }
+
+    /**
+     * Converts given list to UTF8 encoded YAML using the requested marshalling mode.
+     * @return <code>null</code> if list is <code>null</code>
+     */
+    @SneakyThrows
+    @Nullable
+    public static String toStringUtf8ForList(
+            final @Nullable List<?> list,
+            final @NonNull Marshalling marshalling,
+            final JsonUtils.JacksonCustomizer ... customizers) {
+        if (list == null) {
+            return null;
+        }
+        if (marshalling == Marshalling.YAML_LIST) {
+            return toStringUtf8(list, customizers);
+        }
+        return toStringUtf8AsMultiDocument(list, customizers);
+    }
+
+    @SneakyThrows
+    private static String toStringUtf8AsMultiDocument(
+            final List<?> list,
+            final JsonUtils.JacksonCustomizer ... customizers) {
+        if (list.isEmpty()) {
+            return "";
+        }
+        final var mapper = createJacksonWriter(customizers);
+        final List<String> serializedDocuments = new ArrayList<>();
+        for (Object element : list) {
+            serializedDocuments.add(mapper.writeValueAsString(element));
+        }
+        return String.join("---\n", serializedDocuments);
+    }
     // -- CUSTOMIZERS
 
     /**

commons/src/test/java/org/apache/causeway/commons/io/YamlUtilsTest.java

@@ -18,6 +18,8 @@
  */
 package org.apache.causeway.commons.io;
 
+import java.util.List;
+
 import org.approvaltests.Approvals;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
@@ -43,6 +45,28 @@ void toStringUtf8() {
         Approvals.verify(yaml);
     }
 
+    @Test
+    void toStringUtf8ForList_yamlList() {
+        val person2 = _TestDomain.samplePerson();
+        person2.setName("fred");
+
+        val yaml = YamlUtils.toStringUtf8ForList(
+                List.of(person, person2),
+                YamlUtils.Marshalling.YAML_LIST);
+        Approvals.verify(yaml);
+    }
+
+    @Test
+    void toStringUtf8ForList_multiDoc() {
+        val person2 = _TestDomain.samplePerson();
+        person2.setName("fred");
+
+        val yaml = YamlUtils.toStringUtf8ForList(
+                List.of(person, person2),
+                YamlUtils.Marshalling.MULTI_DOC);
+        Approvals.verify(yaml);
+    }
+
     @Test
     void parseRecord() {
         var yamlTemplate = ""

commons/src/test/java/org/apache/causeway/commons/io/YamlUtilsTest.toStringUtf8ForList_multiDoc.approved.txt

@@ -0,0 +1,39 @@
+name: "sven"
+address:
+  zip: 1234
+  street: "backerstreet"
+additionalAddresses:
+- zip: 23
+  street: "brownstreet"
+- zip: 34
+  street: "bluestreet"
+java8Time:
+  localTime: "17:33:45"
+  localDate: "2007-11-21"
+  localDateTime: "2007-11-21T17:33:45"
+  offsetTime: "17:33:45-02:00"
+  offsetDateTime: "2007-11-21T17:33:45-02:00"
+  zonedDateTime: "2007-11-21T17:33:45+01:00"
+phone:
+  home: "+99 1234"
+  work: null
+---
+name: "fred"
+address:
+  zip: 1234
+  street: "backerstreet"
+additionalAddresses:
+- zip: 23
+  street: "brownstreet"
+- zip: 34
+  street: "bluestreet"
+java8Time:
+  localTime: "17:33:45"
+  localDate: "2007-11-21"
+  localDateTime: "2007-11-21T17:33:45"
+  offsetTime: "17:33:45-02:00"
+  offsetDateTime: "2007-11-21T17:33:45-02:00"
+  zonedDateTime: "2007-11-21T17:33:45+01:00"
+phone:
+  home: "+99 1234"
+  work: null