MongoDB Exchange Store YAML Example (#2528)

* enhance: improve YAML parsing error handling with specific messages for missing classes and shorten output

* refactor: streamline imports in `GenericYamlParser`, improve exception formatting, and update MongoDB driver instructions in README

* refactor: simplify YAML parsing error log by removing configuration details

---------

Co-authored-by: Christian Gördes <118011644+christiangoerdes@users.noreply.github.com>

Author: predic8

annot/src/main/java/com/predic8/membrane/annot/yaml/GenericYamlParser.java

@@ -15,13 +15,11 @@
 
 import com.fasterxml.jackson.core.*;
 import com.fasterxml.jackson.databind.*;
-import com.fasterxml.jackson.databind.node.JsonNodeFactory;
-import com.fasterxml.jackson.databind.node.ObjectNode;
+import com.fasterxml.jackson.databind.node.*;
 import com.networknt.schema.*;
 import com.networknt.schema.Error;
 import com.predic8.membrane.annot.*;
-import com.predic8.membrane.annot.beanregistry.BeanDefinition;
-import com.predic8.membrane.annot.beanregistry.BeanRegistry;
+import com.predic8.membrane.annot.beanregistry.*;
 import org.jetbrains.annotations.*;
 import org.slf4j.*;
 
@@ -189,7 +187,17 @@ public static <T> T createAndPopulateNode(ParsingContext ctx, Class<T> clazz, Js
             if (!required.isEmpty())
                 throw new ParsingException("Missing required fields: " + required.stream().map(McYamlIntrospector::getSetterName).toList(), node);
             return configObj;
-        } catch (Throwable cause) {
+        }
+        catch (NoClassDefFoundError e) {
+            if (e.getCause() != null) {
+                var missingClass = e.getCause().getMessage(); // TODO: Better use ExceptionUtil.getRootCause() but it isn't visible in annot.
+                var msg = "Could not create bean with class: %s\nMissing class: %s\n".formatted(clazz, missingClass);
+                log.error(msg);
+                throw new ParsingException(msg, node); // TODO: Cause we know the reason, shorten output.
+            }
+            throw new ParsingException(e, node);
+        }
+        catch (Throwable cause) {
             throw new ParsingException(cause, node);
         }
     }

distribution/examples/extending-membrane/mongo-exchange-store/README.md

@@ -1,8 +1,7 @@
 # MongoDB Exchange Store
 
-Track and store all your Exchanges, even after restarts by connecting Membrane to MongoDB. View live data in the
-Admin Console. Great for debugging, audits, or traffic insights.
-This quick guide shows you how to set it up in minutes.
+Make exchanges persistent with MongoDB. You can search and inspect the HTTP traffic later even after restarts.
+View live data in the Admin Console from the MongoDB store. Great for debugging, audits, or traffic insights.
 
 ### Prerequisite
 
@@ -18,26 +17,12 @@ This quick guide shows you how to set it up in minutes.
 
 1. **Download MongoDB Driver:**
 
-- Download the MongoDB
-  driver [https://repo1.maven.org/maven2/org/mongodb/mongodb-driver-sync/5.0.1/mongodb-driver-sync-5.0.1.jar](https://repo1.maven.org/maven2/org/mongodb/mongodb-driver-sync/5.0.1/mongodb-driver-sync-5.0.1.jar).
-- Place it in the `lib` directory of your Membrane installation.
-
-2. **Configure `proxies.xml`:**
-
-- Example configuration for MongoDB:
-
-   ```xml
-   <mongoDBExchangeStore id="store" connection="mongodb://localhost:27017/" database="membrane"
-                          collection="exchanges" />
-    <router exchangeStore="store">
-        <serviceProxy name="predic8.com" port="2000">
-            <target url="https://membrane-soa.org" />
-        </serviceProxy>
-        <serviceProxy port="9000">
-            <adminConsole />
-        </serviceProxy>
-    </router>
-   ```
+  - Choose from:
+    [https://repo1.maven.org/maven2/org/mongodb/mongodb-driver-sync/](https://repo1.maven.org/maven2/org/mongodb/mongodb-driver-sync/)
+    a recent version. 5.X is recommended.
+  - Place it in the `lib` directory of your Membrane installation.
+
+2. **Configure:** edit `apis.yaml`
 
 3. **run service.proxy.sh script:**
 

distribution/examples/extending-membrane/mongo-exchange-store/apis.yaml

@@ -0,0 +1,23 @@
+# yaml-language-server: $schema=https://www.membrane-api.io/v7.0.5.json
+
+components:
+  my-store:
+    mongoDBExchangeStore:
+      connection: mongodb://localhost:27017/
+      collection: exchange
+      database: exchange
+
+---
+
+api:
+  name: predic8
+  port: 2000
+  target:
+    url: https://api.predic8.de
+
+---
+
+api:
+  port: 9000
+  flow:
+    - adminConsole: {}

docs/ROADMAP.md

@@ -22,10 +22,14 @@
   - Documentation
   - See JmxExporter
 - Synchronization of BeanRegistry
+- Move YAML Parsing to core?
+  - Core isn't visible.
+- YAML parsing:
+  - When the reason for a parse error is clear. Shorten error message.
+
 - BalancerHealthMonitor:
   - @PostConstruct instead of InitializingBean, DisposableBean
 - Scripting: expose beanRegistry  
-
 - IfInterceptor:
   - Add "else"