add comments and rename K8sHelperGenerator.java to Grammar

Author: christiangoerdes

…8/membrane/annot/K8sHelperGenerator.java …/com/predic8/membrane/annot/Grammar.javaannot/src/main/java/com/predic8/membrane/annot/K8sHelperGenerator.java renamed to annot/src/main/java/com/predic8/membrane/annot/Grammar.java annot/src/main/java/com/predic8/membrane/annot/K8sHelperGenerator.java renamed to annot/src/main/java/com/predic8/membrane/annot/Grammar.java

@@ -16,7 +16,7 @@
 
 import java.util.List;
 
-public interface K8sHelperGenerator {
+public interface Grammar {
 
  Class<?> getElement(String key);
 

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

@@ -29,7 +29,7 @@ public class BeanCache implements BeanRegistry {
  private static final Logger log = LoggerFactory.getLogger(BeanCache.class);
 
  private final BeanCacheObserver router;
- private final K8sHelperGenerator k8sHelperGenerator;
+ private final Grammar grammar;
  private final ConcurrentHashMap<String, Object> uuidMap = new ConcurrentHashMap<>();
  private final ArrayBlockingQueue<ChangeEvent> changeEvents = new ArrayBlockingQueue<>(1000);
  private Thread thread;
@@ -47,9 +47,9 @@ record StaticConfigurationLoaded() implements ChangeEvent {
  private final Map<String, BeanDefinition> bds = new ConcurrentHashMap<>();
  private final Set<String> uidsToActivate = ConcurrentHashMap.newKeySet();
 
- public BeanCache(BeanCacheObserver router, K8sHelperGenerator k8sHelperGenerator) {
+ public BeanCache(BeanCacheObserver router, Grammar grammar) {
  this.router = router;
- this.k8sHelperGenerator = k8sHelperGenerator;
+ this.grammar = grammar;
  }
 
  public void start() {
@@ -83,7 +83,7 @@ public Object define(BeanDefinition bd) throws IOException, ParsingException {
  log.debug("defining bean: {}", bd.getNode());
 
  return GenericYamlParser.readMembraneObject(bd.getKind(),
- k8sHelperGenerator,
+ grammar,
  bd.getNode(),
  this);
  }

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

@@ -20,7 +20,7 @@
 import com.networknt.schema.Schema;
 import com.networknt.schema.SchemaLocation;
 import com.networknt.schema.SchemaRegistry;
-import com.predic8.membrane.annot.K8sHelperGenerator;
+import com.predic8.membrane.annot.Grammar;
 import org.jetbrains.annotations.NotNull;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -47,19 +47,27 @@ public class GenericYamlParser {
  private static final String EMPTY_DOCUMENT_WARNING = "Skipping empty document. Maybe there are two --- separators but no configuration in between.";
 
  /**
- * Parses Membrane resources from a YAML input stream.
- * @param resource the input stream to parse. The method takes care of closing the stream.
- * @param generator the K8s helper generator
- * @param observer the bean cache observer
- * @return the bean registry
- */
- public static BeanRegistry parseMembraneResources(@NotNull InputStream resource, K8sHelperGenerator generator, BeanCacheObserver observer) throws IOException {
+ * Entry point used by the runtime to consume a YAML stream and turn it into
+ * a {@link BeanRegistry} that the router can work with.
+ * <ul>
+ * <li>Reads the entire stream as UTF-8.</li>
+ * <li>Splits multi-document YAML ("---" separators).</li>
+ * <li>Validates each document against the JSON Schema provided by {@code grammar}.</li>
+ * <li>Emits helpful line/column locations for malformed multi-document input.</li>
+ * </ul>
+ * The returned registry is fully populated and {@link BeanCache#fireConfigurationLoaded()} has been called.
+ * @param resource the input stream to parse. The method takes care of closing the stream.
+ * @param grammar the grammar to use for type resolution and schema location
+ * @param observer the bean cache observer
+ * @return the bean registry
+ */
+ public static BeanRegistry parseMembraneResources(@NotNull InputStream resource, Grammar grammar, BeanCacheObserver observer) throws IOException {
  BeanCache registry;
  try (resource) {
- registry = new BeanCache(observer, generator);
+ registry = new BeanCache(observer, grammar);
  registry.start();
 
- new GenericYamlParser(generator, new String(resource.readAllBytes(), UTF_8))
+ new GenericYamlParser(grammar, new String(resource.readAllBytes(), UTF_8))
  .getBeanDefinitions()
  .forEach(bd -> registry.handle(WatchAction.ADDED, bd));
 
@@ -78,7 +86,19 @@ public static BeanRegistry parseMembraneResources(@NotNull InputStream resource,
 
  List<BeanDefinition> beanDefs = new ArrayList<>();
 
- public GenericYamlParser(K8sHelperGenerator generator, String yaml) throws IOException {
+ /**
+ * Parses one or more YAML documents into bean definitions.
+ * <p>
+ * The input string may contain multiple YAML documents separated by '---'. Each non-empty
+ * document is validated against the schema provided by {@link Grammar} and then
+ * turned into a {@link BeanDefinition}. Validation errors are mapped back to line/column
+ * numbers using {@link JsonLocationMap} to produce helpful error messages.
+ * </p>
+ * @param grammar provides schema location and Java type resolution
+ * @param yaml the raw YAML content (may contain multi-document stream)
+ * @throws IOException if schema loading or validation fails
+ */
+ public GenericYamlParser(Grammar grammar, String yaml) throws IOException {
  JsonLocationMap jsonLocationMap = new JsonLocationMap();
  List<JsonNode> rootNodes = jsonLocationMap.parseWithLocations(yaml);
  for (int i = 0; i < rootNodes.size(); i++) {
@@ -89,7 +109,7 @@ public GenericYamlParser(K8sHelperGenerator generator, String yaml) throws IOExc
  continue;
  }
  try {
- validate(generator, rootNodes.get(i));
+ validate(grammar, rootNodes.get(i));
  } catch (YamlSchemaValidationException e) {
  JsonLocation location = jsonLocationMap.getLocationMap().get(
  e.getErrors().getFirst().getInstanceNode());
@@ -117,8 +137,8 @@ private static String getBeanType(JsonNode jsonNode) {
  return jsonNode.fieldNames().next();
  }
 
- public static void validate(K8sHelperGenerator generator, JsonNode input) throws IOException, YamlSchemaValidationException {
- Schema schema = SchemaRegistry.withDefaultDialect(DRAFT_2020_12, builder -> {}).getSchema(SchemaLocation.of(generator.getSchemaLocation()));
+ public static void validate(Grammar grammar, JsonNode input) throws IOException, YamlSchemaValidationException {
+ Schema schema = SchemaRegistry.withDefaultDialect(DRAFT_2020_12, builder -> {}).getSchema(SchemaLocation.of(grammar.getSchemaLocation()));
  schema.initializeValidators();
  List<Error> errors = schema.validate(input);
  if (!errors.isEmpty()) {
@@ -127,14 +147,26 @@ public static void validate(K8sHelperGenerator generator, JsonNode input) throws
  }
 
 
- public static Object readMembraneObject(String kind, K8sHelperGenerator generator, JsonNode node, BeanRegistry registry) throws ParsingException {
+ /**
+ * Parse a top-level Membrane resource of the given {@code kind}.
+ * <p>Ensures the node contains exactly one key (the kind), resolves the Java class via the
+ * grammar and delegates to {@link #parse(ParsingContext, Class, JsonNode)}.</p>
+ */
+ public static Object readMembraneObject(String kind, Grammar grammar, JsonNode node, BeanRegistry registry) throws ParsingException {
  ensureSingleKey(node);
- Class<?> clazz = generator.getElement(kind);
+ Class<?> clazz = grammar.getElement(kind);
  if (clazz == null)
  throw new ParsingException("Did not find java class for kind '%s'.".formatted(kind), node);
- return GenericYamlParser.parse(new ParsingContext(kind, registry, generator), clazz, node.get(kind));
+ return GenericYamlParser.parse(new ParsingContext(kind, registry, grammar), clazz, node.get(kind));
  }
 
+ /**
+ * Creates and populates an instance of {@code clazz} from the given YAML/JSON node.
+ * - Arrays: only valid for {@code @MCElement(noEnvelope=true)}; items are parsed and passed to the single {@code @MCChildElement} list setter.
+ * - Objects: each field is mapped to a setter resolved by {@link MethodSetter#getMethodSetter(ParsingContext, Class, String)};
+ * values are produced by {@link #resolveSetterValue(MethodSetter, ParsingContext, JsonNode, String)}. A top-level {@code "$ref"} injects a previously defined bean.
+ * All failures are wrapped in a {@link ParsingException} with location information.
+ */
  public static <T> T parse(ParsingContext ctx, Class<T> clazz, JsonNode node) throws ParsingException {
  try {
  T obj = clazz.getConstructor().newInstance();
@@ -207,6 +239,10 @@ private static List<Object> parseListIncludingStartEvent(ParsingContext context,
  return res;
  }
 
+ /**
+ * Parses a single-item map node like { kind: {...} } by extracting the only key and
+ * delegating to {@link #parseMapToObj(ParsingContext, JsonNode, String)}.
+ */
  private static Object parseMapToObj(ParsingContext context, JsonNode node) throws ParsingException {
  ensureSingleKey(node);
  String key = node.fieldNames().next();

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

@@ -60,6 +60,15 @@ private static boolean equalsAttributeName(Method method, String key) {
  || annotation.attributeName().equals(key);
  }
 
+ /**
+ * Returns the single {@code @MCChildElement} setter for a class annotated with
+ * {@code @MCElement(noEnvelope=true)}.
+ * <ul>
+ * <li>Class must be {@code noEnvelope=true}.</li>
+ * <li>No {@code @MCAttribute} setters are allowed.</li>
+ * <li>Exactly one child setter must exist and it must accept a {@link java.util.Collection}.</li>
+ * </ul>
+ */
  public static <T> Method getSingleChildSetter(Class<T> clazz) {
  MCElement annotation = clazz.getAnnotation(MCElement.class);
  if (annotation == null || !annotation.noEnvelope()) {

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

@@ -20,6 +20,11 @@ public MethodSetter(Method setter, Class<?> beanClass) {
  this.beanClass = beanClass;
  }
 
+ /**
+ * Resolves which setter on {@code clazz} should handle the given YAML field {@code key} and,
+ * if needed, which bean class that field represents.
+ * Throws a {@link RuntimeException} if neither a matching setter nor a resolvable bean class can be found.
+ */
  public static <T> @NotNull MethodSetter getMethodSetter(ParsingContext ctx, Class<T> clazz, String key) {
  Method setter = findSetterForKey(clazz, key);
  // MCChildElements which are not lists are directly declared as beans,
@@ -31,9 +36,9 @@ public MethodSetter(Method setter, Class<?> beanClass) {
  Class<?> beanClass = null;
  if (setter == null) {
  try {
- beanClass = ctx.k8sHelperGenerator().getLocal(ctx.context(), key);
+ beanClass = ctx.grammar().getLocal(ctx.context(), key);
  if (beanClass == null)
- beanClass = ctx.k8sHelperGenerator().getElement(key);
+ beanClass = ctx.grammar().getElement(key);
  if (beanClass != null)
  setter = getChildSetter(clazz, beanClass);
  } catch (Exception e) {

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

@@ -2,16 +2,22 @@
 
 import com.predic8.membrane.annot.*;
 
-public record ParsingContext(String context, BeanRegistry registry, K8sHelperGenerator k8sHelperGenerator) {
+/**
+ * Immutable parsing state passed down while traversing YAML.
+ * - context: current element scope used for local type resolution in {@link Grammar}.
+ * - registry: access to already materialized beans (e.g., for $ref/reference attributes).
+ * - grammar: resolves element names to Java classes via local/global lookups.
+ */
+public record ParsingContext(String context, BeanRegistry registry, Grammar grammar) {
 
  ParsingContext updateContext(String context) {
- return new ParsingContext(context, registry, k8sHelperGenerator);
+ return new ParsingContext(context, registry, grammar);
  }
 
  public Class<?> resolveClass(String key) {
- Class<?> clazz = k8sHelperGenerator.getLocal(context, key);
+ Class<?> clazz = grammar.getLocal(context, key);
  if (clazz == null)
- clazz = k8sHelperGenerator.getElement(key);
+ clazz = grammar.getElement(key);
  if (clazz == null)
  throw new RuntimeException("Did not find java class for key '%s'.".formatted(key));
  return clazz;

annot/src/test/java/com/predic8/membrane/annot/util/YamlParser.java

@@ -14,12 +14,10 @@
 
 package com.predic8.membrane.annot.util;
 
-import com.predic8.membrane.annot.K8sHelperGenerator;
+import com.predic8.membrane.annot.Grammar;
 import com.predic8.membrane.annot.yaml.*;
-import org.yaml.snakeyaml.Yaml;
 
 import java.io.IOException;
-import java.io.InputStreamReader;
 import java.lang.reflect.InvocationTargetException;
 import java.util.concurrent.CountDownLatch;
 
@@ -29,7 +27,7 @@ public class YamlParser {
  private final BeanRegistry beanRegistry;
 
  public YamlParser(String resourceName) throws ClassNotFoundException, NoSuchMethodException, InvocationTargetException, InstantiationException, IllegalAccessException, IOException, InterruptedException, YamlSchemaValidationException {
- K8sHelperGenerator generator = (K8sHelperGenerator) getClass().getClassLoader()
+ Grammar generator = (Grammar) getClass().getClassLoader()
  .loadClass("com.predic8.membrane.demo.config.spring.K8sHelperGeneratorAutoGenerated")
  .getConstructor()
  .newInstance();

core/src/main/java/com/predic8/membrane/core/Router.java

@@ -23,7 +23,7 @@
 import com.predic8.membrane.annot.yaml.WatchAction;
 import com.predic8.membrane.core.RuleManager.RuleDefinitionSource;
 import com.predic8.membrane.core.config.spring.BaseLocationApplicationContext;
-import com.predic8.membrane.core.config.spring.K8sHelperGeneratorAutoGenerated;
+import com.predic8.membrane.core.config.spring.GrammarAutoGenerated;
 import com.predic8.membrane.core.config.spring.TrackingApplicationContext;
 import com.predic8.membrane.core.config.spring.TrackingFileSystemXmlApplicationContext;
 import com.predic8.membrane.core.exceptions.SpringConfigurationErrorHandler;
@@ -720,6 +720,6 @@ else if (bd.getAction() == WatchAction.MODIFIED)
 
  @Override
  public boolean isActivatable(BeanDefinition bd) {
- return Proxy.class.isAssignableFrom(new K8sHelperGeneratorAutoGenerated().getElement(bd.getKind()));
+ return Proxy.class.isAssignableFrom(new GrammarAutoGenerated().getElement(bd.getKind()));
  }
 }

core/src/main/java/com/predic8/membrane/core/cli/RouterCLI.java

@@ -15,7 +15,7 @@
 package com.predic8.membrane.core.cli;
 
 import com.predic8.membrane.core.*;
-import com.predic8.membrane.core.config.spring.K8sHelperGeneratorAutoGenerated;
+import com.predic8.membrane.core.config.spring.GrammarAutoGenerated;
 import com.predic8.membrane.core.config.spring.TrackingFileSystemXmlApplicationContext;
 import com.predic8.membrane.core.exceptions.*;
 import com.predic8.membrane.core.openapi.serviceproxy.*;
@@ -159,7 +159,7 @@ private static Router initRouterByYAML(String location) throws Exception {
  router.setAsynchronousInitialization(true);
  router.start();
 
- parseMembraneResources(router.getResolverMap().resolve(location), new K8sHelperGeneratorAutoGenerated(), router);
+ parseMembraneResources(router.getResolverMap().resolve(location), new GrammarAutoGenerated(), router);
 
  return router;
  }

core/src/main/java/com/predic8/membrane/core/config/spring/k8s/Envelope.java

@@ -14,28 +14,20 @@
 package com.predic8.membrane.core.config.spring.k8s;
 
 import com.fasterxml.jackson.databind.JsonNode;
-import com.predic8.membrane.annot.K8sHelperGenerator;
-import com.predic8.membrane.core.config.spring.K8sHelperGeneratorAutoGenerated;
+import com.predic8.membrane.annot.Grammar;
+import com.predic8.membrane.core.config.spring.GrammarAutoGenerated;
 import com.predic8.membrane.annot.yaml.BeanRegistry;
-import com.predic8.membrane.annot.yaml.GenericYamlParser;
-import org.yaml.snakeyaml.events.Event;
-import org.yaml.snakeyaml.events.MappingEndEvent;
-import org.yaml.snakeyaml.events.MappingStartEvent;
-import org.yaml.snakeyaml.events.ScalarEvent;
 
 import java.util.*;
 
-import static com.predic8.membrane.annot.yaml.YamlLoader.readObj;
-import static com.predic8.membrane.annot.yaml.YamlLoader.readString;
-
 public class Envelope {
  String kind;
  String apiVersion;
  Metadata metadata;
  JsonNode spec;
  final Map<String, Object> additionalProperties = new HashMap<>();
 
- private static final K8sHelperGenerator K8S_HELPER = new K8sHelperGeneratorAutoGenerated();
+ private static final Grammar K8S_HELPER = new GrammarAutoGenerated();
 
  public void parse(JsonNode node, BeanRegistry registry) {
  kind = node.get("kind").asText();