added @mcelement(noEnvelope=true) modus (#2181)

rrayst · coderabbitai[bot] · christiangoerdes · web-flow · commit ff19bbc3beed · 2025-09-26T14:39:47.000+02:00
* added @mcelement(noEnvelope=true) modus * forbid combining 'noEnvelope' with 'topLevel' * added more 'noEnvelope' attributes * forbid 'noEvelope' elements form occurring in their old verbose form * Update core/src/main/java/com/predic8/membrane/core/kubernetes/GenericYamlParser.java Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * fixed collection type list * fixed java syntax * adjust tests --------- Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> Co-authored-by: Christian Gördes <christian.goerdes@outlook.de> Co-authored-by: Christian Gördes <118011644+christiangoerdes@users.noreply.github.com>
diff --git a/annot/src/main/java/com/predic8/membrane/annot/MCElement.java b/annot/src/main/java/com/predic8/membrane/annot/MCElement.java
@@ -21,9 +21,37 @@
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface MCElement {
-	String name();
-	String id() default "";
-	boolean mixed() default false;
-	boolean topLevel() default true;
-	String configPackage() default "";
+    String name();
+
+    String id() default "";
+
+    boolean mixed() default false;
+
+    /**
+     * Whether the element can be a separate bean in the XML schema, or a separate document in YAML/JSON.
+     */
+    boolean topLevel() default true;
+
+    String configPackage() default "";
+
+    /**
+     * If set, this activates the 'no envelope' mode for this element.
+     * <p>
+     * In 'no envelope' mode, the class annotated by <code>@MCElement</code> must have no <code>@MCAttribute</code>
+     * setter methods, no <code>@MCTextContent</code> setter methods, no <code>@MCOtherAttributes</code> setter methods
+     * and exactly one <code>@MCChildElement</code> setter, which must accept a List or Collection as parameter.
+     * <p>
+     * In JSON/YAML representations, the element's content is then represented directly by the item list
+     * <p>
+     * ["item1":{}, "item2":{}]
+     * <p>
+     * instead of
+     * <p>
+     * {"propertyName": ["item1":{}, "item2":{}]}
+     * <p>
+     * .
+     * <p>
+     * This does not have any effect on the XML grammar.
+     */
+    boolean noEnvelope() default false;
 }
diff --git a/annot/src/main/java/com/predic8/membrane/annot/SpringConfigurationXSDGeneratingAnnotationProcessor.java b/annot/src/main/java/com/predic8/membrane/annot/SpringConfigurationXSDGeneratingAnnotationProcessor.java
@@ -217,7 +217,23 @@ public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment
 					String uniquenessError = getUniquenessError(ii);
 					if (uniquenessError != null)
 						throw new ProcessingException(uniquenessError, ii.getElement());
-					if (ii.getTci() != null && !ii.getAnnotation().mixed())
+                    if (ii.getAnnotation().noEnvelope()) {
+                        if (ii.getAnnotation().topLevel())
+                            throw new ProcessingException("@MCElement(..., noEnvelope=true, topLevel=true) is invalid.", ii.getElement());
+                        if (ii.getAnnotation().mixed())
+                            throw new ProcessingException("@MCElement(..., noEnvelope=true, mixed=true) is invalid.", ii.getElement());
+                        if (ii.getChildElementSpecs().size() != 1)
+                            throw new ProcessingException("@MCElement(noEnvelope=true) requires exactly one @MCChildElement.", ii.getElement());
+                        if (!ii.getChildElementSpecs().get(0).isList())
+                            throw new ProcessingException("@MCElement(noEnvelope=true) requires its @MCChildElement() to be a List or Collection.", ii.getElement());
+                        if (!ii.getAis().isEmpty())
+                            throw new ProcessingException("@MCElement(noEnvelope=true) requires @MCAttribute to be not present.", ii.getElement());
+                        if (ii.getOai() != null)
+                            throw new ProcessingException("@MCElement(noEnvelope=true) requires @MCOtherAttributes to be not present.", ii.getElement());
+                        if (ii.getTci() != null)
+                            throw new ProcessingException("@MCElement(noEnvelope=true) requires @MCTextContent to be not present.", ii.getElement());
+                    }
+                    if (ii.getTci() != null && !ii.getAnnotation().mixed())
 						throw new ProcessingException("@MCTextContent requires @MCElement(..., mixed=true) on the class.", ii.getElement());
 					if (ii.getTci() == null && ii.getAnnotation().mixed())
 						throw new ProcessingException("@MCElement(..., mixed=true) requires @MCTextContent on a property.", ii.getElement());
diff --git a/annot/src/main/java/com/predic8/membrane/annot/generator/JsonSchemaGenerator.java b/annot/src/main/java/com/predic8/membrane/annot/generator/JsonSchemaGenerator.java
@@ -63,7 +63,7 @@ private void assemble(Model m, MainInfo main) throws IOException {
             }
 
             SchemaObject parser = new SchemaObject(elementInfo.getXSDTypeName(m));
-            parser.addAttribute("type", "object");
+            parser.addAttribute("type", elementInfo.getAnnotation().noEnvelope() ? "array" : "object");
             parser.addAttribute("additionalProperties", elementInfo.getOai() != null);
             parser.addAttribute("description", getDescriptionAsText(elementInfo));
             parser.addAttribute("x-intellij-html-description", getDescriptionAsHtml(elementInfo));
@@ -201,15 +201,19 @@ private void collectChildElements(Model m, MainInfo main, ElementInfo i, ISchema
                 items.addAttribute("type", "object");
                 items.addAttribute("additionalProperties", cei.getAnnotation().allowForeign());
 
-                SchemaObject sop = new SchemaObject(cei.getPropertyName());
-                sop.setRequired(cei.isRequired());
-                sop.addAttribute("description", getDescriptionAsText(cei));
-                sop.addAttribute("x-intellij-html-description", getDescriptionAsHtml(cei));
-                sop.addAttribute("type", "array");
-                sop.addAttribute("additionalItems", false);
-                sop.addAttribute("items", items);
+                if (i.getAnnotation().noEnvelope()) {
+                    so.addAttribute("items", items);
+                } else {
+                    SchemaObject sop = new SchemaObject(cei.getPropertyName());
+                    sop.setRequired(cei.isRequired());
+                    sop.addAttribute("description", getDescriptionAsText(cei));
+                    sop.addAttribute("x-intellij-html-description", getDescriptionAsHtml(cei));
+                    sop.addAttribute("type", "array");
+                    sop.addAttribute("additionalItems", false);
+                    sop.addAttribute("items", items);
 
-                so.addProperty(sop);
+                    so.addProperty(sop);
+                }
 
                 parent2 = items;
             } else {
diff --git a/annot/src/main/java/com/predic8/membrane/annot/generator/kubernetes/K8sJsonSchemaGenerator.java b/annot/src/main/java/com/predic8/membrane/annot/generator/kubernetes/K8sJsonSchemaGenerator.java
@@ -111,7 +111,7 @@ private void collectDefinitions(Model m, MainInfo main, ElementInfo i, Schema sc
 
         for (Map.Entry<String, ElementInfo> entry : all.entrySet()) {
             SchemaObject so = new SchemaObject(entry.getKey());
-            so.addAttribute("type", "object");
+            so.addAttribute("type", entry.getValue().getAnnotation().noEnvelope() ? "array" : "object");
             so.addAttribute("additionalProperties", entry.getValue().getOai() != null);
 
             collectProperties(m, main, entry.getValue(), so);
@@ -140,13 +140,17 @@ private void collectChildElements(Model m, MainInfo main, ElementInfo i, ISchema
                 items.addAttribute("type", "object");
                 items.addAttribute("additionalProperties", cei.getAnnotation().allowForeign());
 
-                SchemaObject sop = new SchemaObject(cei.getPropertyName());
-                sop.setRequired(cei.isRequired());
-                sop.addAttribute("type", "array");
-                sop.addAttribute("additionalItems", false);
-                sop.addAttribute("items", items);
+                if (i.getAnnotation().noEnvelope()) {
+                    so.addAttribute("items", items);
+                } else {
+                    SchemaObject sop = new SchemaObject(cei.getPropertyName());
+                    sop.setRequired(cei.isRequired());
+                    sop.addAttribute("type", "array");
+                    sop.addAttribute("additionalItems", false);
+                    sop.addAttribute("items", items);
 
-                so.addProperty(sop);
+                    so.addProperty(sop);
+                }
 
                 parent2 = items;
             } else {
diff --git a/annot/src/main/java/com/predic8/membrane/annot/generator/kubernetes/model/ISchema.java b/annot/src/main/java/com/predic8/membrane/annot/generator/kubernetes/model/ISchema.java
@@ -14,6 +14,8 @@
 package com.predic8.membrane.annot.generator.kubernetes.model;
 
 public interface ISchema {
+    void addAttribute(String key, Object value);
+
     void addProperty(SchemaObject so);
 
     void setAdditionalProperties(boolean additionalProperties);
diff --git a/core/src/main/java/com/predic8/membrane/core/interceptor/apikey/stores/inConfig/SimpleKeyStore.java b/core/src/main/java/com/predic8/membrane/core/interceptor/apikey/stores/inConfig/SimpleKeyStore.java
@@ -24,7 +24,7 @@
 /**
  * @description Stores api keys inline as XML.
  */
-@MCElement(name = "keys", topLevel = false)
+@MCElement(name = "keys", topLevel = false, noEnvelope = true)
 public class SimpleKeyStore implements ApiKeyStore {
 
     private final List<Key> keys = new ArrayList<>();
diff --git a/core/src/main/java/com/predic8/membrane/core/interceptor/authentication/session/LDAPUserDataProvider.java b/core/src/main/java/com/predic8/membrane/core/interceptor/authentication/session/LDAPUserDataProvider.java
@@ -110,7 +110,7 @@ public class LDAPUserDataProvider implements UserDataProvider {
 	AttributeMap map;
 	SSLParser sslParser;
 
-	@MCElement(name="map", topLevel=false, id="ldapUserDataProvider-map")
+	@MCElement(name="map", topLevel=false, id="ldapUserDataProvider-map", noEnvelope = true)
 	public static class AttributeMap {
 
 		@MCElement(name="attribute", topLevel=false)
diff --git a/core/src/main/java/com/predic8/membrane/core/interceptor/authentication/session/UnifyingUserDataProvider.java b/core/src/main/java/com/predic8/membrane/core/interceptor/authentication/session/UnifyingUserDataProvider.java
@@ -37,7 +37,7 @@
  *              provider could verify the user, the login attempt fails.
  *              </p>
  */
-@MCElement(name="unifyingUserDataProvider", topLevel=false)
+@MCElement(name="unifyingUserDataProvider", topLevel=false, noEnvelope = true)
 public class UnifyingUserDataProvider implements UserDataProvider {
 
 	private List<UserDataProvider> userDataProviders = new ArrayList<>();
diff --git a/core/src/main/java/com/predic8/membrane/core/interceptor/balancer/Balancer.java b/core/src/main/java/com/predic8/membrane/core/interceptor/balancer/Balancer.java
@@ -20,7 +20,7 @@
 
 import java.util.*;
 
-@MCElement(name="clusters", topLevel=false)
+@MCElement(name="clusters", topLevel=false, noEnvelope = true)
 public class Balancer extends AbstractXmlElement {
 	public static final String DEFAULT_NAME = "Default";
 	private static final Logger log = LoggerFactory.getLogger(Balancer.class.getName());
diff --git a/core/src/main/java/com/predic8/membrane/core/interceptor/flow/AbortInterceptor.java b/core/src/main/java/com/predic8/membrane/core/interceptor/flow/AbortInterceptor.java
@@ -29,7 +29,7 @@
  * allow normal processing.
  * @topic 1. Proxies and Flow
  */
-@MCElement(name="abort", topLevel=false)
+@MCElement(name="abort", topLevel=false, noEnvelope = true)
 public class AbortInterceptor extends AbstractFlowWithChildrenInterceptor {
 
     private static final Logger log = LoggerFactory.getLogger(AbortInterceptor.class);
diff --git a/core/src/main/java/com/predic8/membrane/core/interceptor/flow/RequestInterceptor.java b/core/src/main/java/com/predic8/membrane/core/interceptor/flow/RequestInterceptor.java
@@ -28,7 +28,7 @@
  * &lt;request&gt; Element you can limit their application to requests only.
  * @topic 1. Proxies and Flow
  */
-@MCElement(name = "request", topLevel = false)
+@MCElement(name = "request", topLevel = false, noEnvelope = true)
 public class RequestInterceptor extends AbstractFlowWithChildrenInterceptor {
 
     private static final Logger log = LoggerFactory.getLogger(RequestInterceptor.class);
diff --git a/core/src/main/java/com/predic8/membrane/core/interceptor/flow/ResponseInterceptor.java b/core/src/main/java/com/predic8/membrane/core/interceptor/flow/ResponseInterceptor.java
@@ -25,7 +25,7 @@
  * &lt;response&gt; plugin you can limit their application to responses only.
  * @topic 1. Proxies and Flow
  */
-@MCElement(name = "response", topLevel = false)
+@MCElement(name = "response", topLevel = false, noEnvelope = true)
 public class ResponseInterceptor extends AbstractFlowWithChildrenInterceptor {
 
     @Override
diff --git a/core/src/main/java/com/predic8/membrane/core/interceptor/flow/choice/Otherwise.java b/core/src/main/java/com/predic8/membrane/core/interceptor/flow/choice/Otherwise.java
@@ -15,5 +15,5 @@
 
 import com.predic8.membrane.annot.MCElement;
 
-@MCElement(name = "otherwise", topLevel = false)
+@MCElement(name = "otherwise", topLevel = false, noEnvelope = true)
 public class Otherwise extends InterceptorContainer {}
diff --git a/core/src/main/java/com/predic8/membrane/core/kubernetes/GenericYamlParser.java b/core/src/main/java/com/predic8/membrane/core/kubernetes/GenericYamlParser.java
@@ -15,9 +15,11 @@
 
 import com.google.common.collect.ImmutableMap;
 import com.predic8.membrane.annot.MCAttribute;
+import com.predic8.membrane.annot.MCChildElement;
 import com.predic8.membrane.annot.MCElement;
 import com.predic8.membrane.annot.MCOtherAttributes;
 import com.predic8.membrane.core.config.spring.K8sHelperGeneratorAutoGenerated;
+import org.jetbrains.annotations.NotNull;
 import org.yaml.snakeyaml.events.*;
 
 import java.lang.reflect.InvocationTargetException;
@@ -36,7 +38,16 @@ public static <T> T parse(String context, Class<T> clazz, Iterator<Event> events
         try {
             T obj = newInstance(clazz);
             Event event = events.next();
+            if (event instanceof SequenceStartEvent) {
+                // when this is a list, we are on a @MCElement(..., noEnvelope=true)
+                List value = parseListExcludingStartEvent(context, events, registry);
+                Method setter = getSingleChildSetter(clazz);
+                setSetter(obj, setter, value);
+                return obj;
+            }
             ensureMappingStart(event);
+            if (clazz.getAnnotation(MCElement.class) != null && clazz.getAnnotation(MCElement.class).noEnvelope())
+                throw new RuntimeException("Class " + clazz.getName() + " is annotated with @MCElement(noEnvelope=true), but the YAML/JSON structure does not contain a list.");
 
             while(true) {
                 event = events.next();
@@ -77,10 +88,39 @@ public static <T> T parse(String context, Class<T> clazz, Iterator<Event> events
 
     }
 
+    private static <T> Method getSingleChildSetter(Class<T> clazz) {
+        MCElement annotation = clazz.getAnnotation(MCElement.class);
+        if (annotation == null || !annotation.noEnvelope()) {
+            throw new RuntimeException("Class " + clazz.getName() + " has properties, and is not a list.");
+        }
+        if (Arrays.stream(clazz.getMethods())
+                .filter(ParserHelper::isSetter)
+                .anyMatch(method -> findAnnotation(method, MCAttribute.class) != null)) {
+            throw new RuntimeException("Class " + clazz.getName() + " should not have any @MCAttribute setters, because it is a @MCElement with noEnvelope=true .");
+        }
+        List<Method> childSetters = Arrays.stream(clazz.getMethods())
+                .filter(ParserHelper::isSetter)
+                .filter(method -> findAnnotation(method, MCChildElement.class) != null)
+                .toList();
+        if (childSetters.isEmpty()) {
+            throw new RuntimeException("No @MCChildElement setter found in " + clazz.getName());
+        }
+        if (childSetters.size() > 1) {
+            throw new RuntimeException("Multiple @MCChildElement setters found in " + clazz.getName() + ". Only one is allowed when noEnvelope=true.");
+        }
+        Method setter = childSetters.get(0);
+        Class<?> paramType = setter.getParameterTypes()[0];
+        if (!java.util.Collection.class.isAssignableFrom(paramType)) {
+            throw new RuntimeException("The single @MCChildElement setter in " + clazz.getName() +
+                 " must accept a Collection/List when noEnvelope=true, but found: " + paramType.getName());
+        }
+        return setter;
+    }
+
     @SuppressWarnings({"rawtypes", "unchecked"})
     private static Object resolveSetterValue(Class<?> wanted, Method setter, String context, Iterator<Event> events, BeanRegistry registry, String key, Class clazz2, Event event) {
-        if (wanted.equals(List.class) || wanted.equals(Enumeration.class)) {
-            return parseList(context, events, registry);
+        if (wanted.equals(List.class) || wanted.equals(Collection.class)) {
+            return parseListIncludingStartEvent(context, events, registry);
         }
         if (wanted.isEnum()) {
            return Enum.valueOf((Class<Enum>) wanted, readString(events).toUpperCase(Locale.ROOT));
@@ -134,11 +174,16 @@ private static void ensureMappingStart(Event event) {
         }
     }
 
-    private static List parseList(String context, Iterator<Event> events, BeanRegistry registry) {
+    private static List parseListIncludingStartEvent(String context, Iterator<Event> events, BeanRegistry registry) {
         Event event = events.next();
         if (!(event instanceof SequenceStartEvent)) {
             throw new IllegalStateException("Expected start-of-sequence in line " + event.getStartMark().getLine() + " column " + event.getStartMark().getColumn());
         }
+        return parseListExcludingStartEvent(context, events, registry);
+    }
+
+    private static @NotNull ArrayList parseListExcludingStartEvent(String context, Iterator<Event> events, BeanRegistry registry) {
+        Event event;
         ArrayList res = new ArrayList();
         while (true) {
             event = events.next();
diff --git a/core/src/test/java/com/predic8/membrane/core/config/spring/k8s/EnvelopeTest.java b/core/src/test/java/com/predic8/membrane/core/config/spring/k8s/EnvelopeTest.java
@@ -68,10 +68,9 @@ void routerConfConfig() {
                       from: ^/names/(.*)
                       to: /restnames/name\\.groovy\\?name=$1
             - response:
-                interceptors:
-                  - beautifier: {}
-                  - xml2Json: {}
-                  - log: {}
+              - beautifier: {}
+              - xml2Json: {}
+              - log: {}
           target:
             url: https://api.predic8.de
         ---
@@ -85,16 +84,15 @@ void routerConfConfig() {
             value: /header
           interceptors:
             - request:
-                interceptors:
-                  - groovy:
-                      src: |
-                        println "Request headers:"
-                        CONTINUE
-                  - template:
-                      contentType: application/json
-                      textTemplate: '{ "ok": 1 }'
-                  - return:
-                      statusCode: 200
+              - groovy:
+                  src: |
+                    println "Request headers:"
+                    CONTINUE
+              - template:
+                  contentType: application/json
+                  textTemplate: '{ "ok": 1 }'
+              - return:
+                  statusCode: 200
         ---
         apiVersion: membrane-soa.org/v1beta1
         kind: api
diff --git a/core/src/test/java/com/predic8/membrane/core/kubernetes/GenericYamlParserTest.java b/core/src/test/java/com/predic8/membrane/core/kubernetes/GenericYamlParserTest.java
@@ -105,8 +105,7 @@ Stream<Case> successCases() {
                               requestLimit: 3
                           - rewriter:
                               mappings: []
-                          - response:
-                              interceptors: []
+                          - response: []
                         """,
                         a -> assertAll(
                                 () -> assertEquals(3, a.getInterceptors().size()),
@@ -148,10 +147,9 @@ Stream<Case> successCases() {
                         """
                         interceptors:
                           - response:
-                              interceptors:
-                                - beautifier: {}
-                                - xml2Json: {}
-                                - log: {}
+                            - beautifier: {}
+                            - xml2Json: {}
+                            - log: {}
                         """,
                         a -> assertAll(
                                 () -> assertEquals(3, ((ResponseInterceptor) a.getInterceptors().getFirst()).getInterceptors().size()),
diff --git a/docs/JAVADOC.md b/docs/JAVADOC.md
@@ -2,7 +2,7 @@
 
 This is information for Membrane developers.
 
-Membrane API Gateway's configuration can be written in XML or (experimentally) in YAML.
+Membrane API Gateway's configuration can be written in XML or in YAML.
 
 Everything that is configurable is driven by Java Code annotations from the `annot` submodule. `annot` defines 7 annotations. Here, we document the most common ones.
 
