feat(java): programmatic provider registration on MetaDataRegistry

dmealing · dmealing · commit b78e2018856d · 2026-05-28T07:52:55.000-04:00
Mirrors the cross-port composition pattern already shipped in the
TypeScript port (composeRegistry(providers)) and the Python port
(compose_registry(providers)). Until now the Java MetaDataRegistry only
exposed ServiceLoader auto-discovery for MetaDataTypeProvider
instances — embedded scenarios where ServiceLoader is awkward (fat-jar
consolidation, GraalVM native-image, some app servers), tests that
want to inject a fixture provider without touching META-INF/services,
and conditional / tenant-driven composition all had to work around it.

Two new public entry points on MetaDataRegistry:

  // Static factory — fresh registry from an explicit list
  MetaDataRegistry registry = MetaDataRegistry.compose(List.of(
      new CoreTypesProvider(),
      new MyDomainProvider(),
      new MyTenantProvider()
  ));

  // Instance method — add providers to an existing registry
  registry.registerProviders(List.of(otherProvider));

Cross-port error contract enforced strictly (matches TS / Python):

  - Duplicate provider id  → MetaDataException(ERR_PROVIDER_DUPLICATE_ID)
  - Missing dependency     → MetaDataException(ERR_PROVIDER_MISSING_DEPENDENCY)
  - Dependency cycle       → MetaDataException(ERR_PROVIDER_DEPENDENCY_CYCLE)
  - Provider register fail → MetaDataException(ERR_UNKNOWN, wrapping cause)

The existing ServiceLoader path on MetaDataRegistry.getInstance()
keeps its warn-and-continue semantics — appropriate for runtime
robustness in production apps. The new programmatic path is strict,
matching the cross-port spec.

Implementation: resolveDependenciesStrict() + topologicalSortStrict()
sit alongside the existing warn-and-continue resolveDependencies() /
topologicalSort() in MetaDataRegistry, sharing the same topo sort
algorithm but throwing structured exceptions instead of logging.

Tests: ComposeRegistryTest covers the six scenarios:
  - compose builds registry and runs each provider against it
  - topological ordering regardless of input order
  - duplicate-id throws ERR_PROVIDER_DUPLICATE_ID
  - missing-dependency throws ERR_PROVIDER_MISSING_DEPENDENCY
  - dependency-cycle throws ERR_PROVIDER_DEPENDENCY_CYCLE
  - registerProviders adds to an existing registry

Metadata test suite: 724 tests / 5 failures — same 5 pre-existing
failures (4 provider-extension fixtures + 1 docs-file-basic
canonical-serialization), +6 from this commit, zero regressions.

Documented in MIGRATION.md and the 7.0.1-SNAPSHOT entry of
RELEASE_NOTES.md.
diff --git a/server/java/MIGRATION.md b/server/java/MIGRATION.md
@@ -43,6 +43,22 @@ Consumers running inside an OSGi container can still wrap MetaObjects' JARs with
 
 The `WeakReference` patterns in `MetaData`, `HybridCache`, and `StandardServiceRegistry` stay — they are general ClassLoader-leak prevention, not OSGi-specific.
 
+### Programmatic provider registration (new in 7.0.1)
+
+`MetaDataRegistry` now ships a `compose(...)` / `registerProviders(...)` API that mirrors the cross-port pattern already in TypeScript (`composeRegistry(providers)`) and Python (`compose_registry(providers)`):
+
+```java
+MetaDataRegistry registry = MetaDataRegistry.compose(List.of(
+    new CoreTypesProvider(),
+    new MyDomainProvider(),
+    new MyTenantProvider()
+));
+```
+
+Use this when ServiceLoader is awkward — embedded scenarios, fat-jar consolidation, GraalVM native-image, conditional / tenant-driven composition, and tests that want to inject a fixture provider without touching `META-INF/services`. Strict error contract matches the cross-port spec: duplicate provider id, missing dependency, or dependency cycle throws `MetaDataException` with the matching `ErrorCode`.
+
+The default `MetaDataRegistry.getInstance()` still uses ServiceLoader auto-discovery with warn-and-continue semantics — no change for the typical app.
+
 The `metaobjects-codegen-mustache` and `metaobjects-codegen-plantuml` modules from 6.x continue unchanged.
 
 ### Step 3 — source paradigm v2 ([ADR-0007](../../spec/decisions/ADR-0007-source-paradigm-v2.md))
diff --git a/server/java/RELEASE_NOTES.md b/server/java/RELEASE_NOTES.md
@@ -15,6 +15,7 @@ Post-7.0.0 cleanup line:
 - **OSGi runtime variant removed.** `OSGIServiceRegistry`, `BundleLifecycleManager`, and the `maven-bundle-plugin` packaging on every reactor module are gone. All artifacts now ship as plain JARs. The `ServiceRegistry` interface drops the OSGi-specific methods; `StandardServiceRegistry` is the only implementation. See [MIGRATION.md](MIGRATION.md#osgi-support-removed) for the migration path (OSGi consumers can wrap our JARs with `bnd` / `pax-url`).
 - **`metaobjects-dynamic-core` folded into `metaobjects-metadata`.** Its 89-LoC `CoreObjectsMetaDataProvider` now ships inside the metadata jar; the module is removed from the reactor. Reactor module count: 14 → 13.
 - **`archetype` and `examples` directories deleted.** They had been out of the reactor since 7.0.0; carrying them as scaffold source risked bit-rot.
+- **Programmatic provider registration.** `MetaDataRegistry.compose(Collection<MetaDataTypeProvider>)` and `MetaDataRegistry.registerProviders(Collection<...>)` mirror the cross-port pattern already shipped in TypeScript (`composeRegistry(providers)`) and Python (`compose_registry(providers)`). Strict cross-port error contract: duplicate provider id throws `MetaDataException` with `ERR_PROVIDER_DUPLICATE_ID`; missing dependency throws `ERR_PROVIDER_MISSING_DEPENDENCY`; dependency cycle throws `ERR_PROVIDER_DEPENDENCY_CYCLE`. The ServiceLoader auto-discovery path on `MetaDataRegistry.getInstance()` continues to work unchanged (warn-and-continue semantics, for runtime robustness).
 
 ---
 
diff --git a/server/java/metadata/src/main/java/com/metaobjects/registry/MetaDataRegistry.java b/server/java/metadata/src/main/java/com/metaobjects/registry/MetaDataRegistry.java
@@ -129,10 +129,75 @@ public MetaDataRegistry(ServiceRegistry serviceRegistry) {
     public MetaDataRegistry() {
         this(ServiceRegistryFactory.getDefault());
     }
-    
+
+    // =========================================================================
+    // Programmatic provider composition (mirrors composeRegistry in TS /
+    // compose_registry in Python). Use this when you want explicit, in-process
+    // control over which providers register types — tests, embedded scenarios
+    // where ServiceLoader is awkward, and conditional / framework-driven
+    // composition. ServiceLoader auto-discovery via {@link #getInstance()} is
+    // the default for typical applications and stays unchanged.
+    // =========================================================================
+
+    /**
+     * Compose a fresh {@link MetaDataRegistry} from the given providers and
+     * return it. Mirrors {@code composeRegistry(providers)} in the TypeScript
+     * port and {@code compose_registry(providers)} in the Python port.
+     *
+     * <p>Providers are topologically sorted by their declared dependencies
+     * (stable sort — providers with no ordering constraint between them keep
+     * input order), then each provider's {@link MetaDataTypeProvider#registerTypes}
+     * runs against the new registry.</p>
+     *
+     * @param providers the providers to compose; must not contain duplicate
+     *                  ids, missing dependencies, or dependency cycles
+     * @return a new registry with all provider types registered
+     * @throws MetaDataException with {@link com.metaobjects.ErrorCode#ERR_PROVIDER_DUPLICATE_ID},
+     *                           {@link com.metaobjects.ErrorCode#ERR_PROVIDER_MISSING_DEPENDENCY},
+     *                           or {@link com.metaobjects.ErrorCode#ERR_PROVIDER_DEPENDENCY_CYCLE}
+     *                           if the provider set is malformed.
+     */
+    public static MetaDataRegistry compose(Collection<MetaDataTypeProvider> providers) {
+        Objects.requireNonNull(providers, "providers must not be null");
+        MetaDataRegistry registry = new MetaDataRegistry();
+        registry.registerProviders(providers);
+        return registry;
+    }
+
+    /**
+     * Register a collection of providers into THIS registry. Strict
+     * counterpart to ServiceLoader auto-discovery — duplicate ids, missing
+     * dependencies, and dependency cycles throw {@link MetaDataException}
+     * with the matching {@link com.metaobjects.ErrorCode} rather than logging
+     * warnings and continuing.
+     *
+     * @param providers the providers to register
+     * @throws MetaDataException on duplicate id, missing dependency, or cycle
+     */
+    public synchronized void registerProviders(Collection<MetaDataTypeProvider> providers) {
+        Objects.requireNonNull(providers, "providers must not be null");
+        List<MetaDataTypeProvider> ordered = resolveDependenciesStrict(providers);
+        for (MetaDataTypeProvider provider : ordered) {
+            try {
+                provider.registerTypes(this);
+                if (!deferredInheritanceTypes.isEmpty()) {
+                    resolveDeferredInheritance();
+                }
+            } catch (com.metaobjects.MetaDataException e) {
+                throw e;
+            } catch (Exception e) {
+                com.metaobjects.MetaDataException wrap = new com.metaobjects.MetaDataException(
+                    "Provider '" + provider.getProviderId() + "' failed during registerTypes: " + e.getMessage(),
+                    com.metaobjects.ErrorCode.ERR_UNKNOWN);
+                wrap.initCause(e);
+                throw wrap;
+            }
+        }
+    }
+
     /**
      * Register a MetaData type with fluent configuration
-     * 
+     *
      * @param clazz Implementation class
      * @param configurator Configuration function for the type definition
      */
@@ -985,6 +1050,78 @@ private void topologicalSort(MetaDataTypeProvider provider,
         result.add(provider);
     }
 
+    /**
+     * Strict counterpart to {@link #resolveDependencies(Collection)}. Used by
+     * the programmatic {@link #compose(Collection)} / {@link #registerProviders(Collection)}
+     * entry points to match the cross-port error contract: duplicate ids,
+     * missing dependencies, and dependency cycles throw {@link com.metaobjects.MetaDataException}
+     * with the matching {@link com.metaobjects.ErrorCode} rather than logging and continuing.
+     */
+    private List<MetaDataTypeProvider> resolveDependenciesStrict(Collection<MetaDataTypeProvider> providers) {
+        Map<String, MetaDataTypeProvider> providerMap = new HashMap<>();
+        for (MetaDataTypeProvider provider : providers) {
+            String id = provider.getProviderId();
+            if (providerMap.containsKey(id)) {
+                throw new com.metaobjects.MetaDataException(
+                    "Duplicate provider id '" + id + "': "
+                        + providerMap.get(id).getClass().getName() + " vs "
+                        + provider.getClass().getName(),
+                    com.metaobjects.ErrorCode.ERR_PROVIDER_DUPLICATE_ID);
+            }
+            providerMap.put(id, provider);
+        }
+
+        List<String> missing = new ArrayList<>();
+        for (MetaDataTypeProvider provider : providers) {
+            for (String dep : provider.getDependencies()) {
+                if (!providerMap.containsKey(dep)) {
+                    missing.add(dep + " (required by " + provider.getProviderId() + ")");
+                }
+            }
+        }
+        if (!missing.isEmpty()) {
+            throw new com.metaobjects.MetaDataException(
+                "Missing provider dependencies: " + String.join(", ", missing),
+                com.metaobjects.ErrorCode.ERR_PROVIDER_MISSING_DEPENDENCY);
+        }
+
+        List<MetaDataTypeProvider> result = new ArrayList<>();
+        Set<String> visited = new HashSet<>();
+        Set<String> visiting = new HashSet<>();
+        for (MetaDataTypeProvider provider : providers) {
+            if (!visited.contains(provider.getProviderId())) {
+                topologicalSortStrict(provider, providerMap, visited, visiting, result);
+            }
+        }
+        return result;
+    }
+
+    private void topologicalSortStrict(MetaDataTypeProvider provider,
+                                       Map<String, MetaDataTypeProvider> providerMap,
+                                       Set<String> visited,
+                                       Set<String> visiting,
+                                       List<MetaDataTypeProvider> result) {
+        String providerId = provider.getProviderId();
+        if (visiting.contains(providerId)) {
+            throw new com.metaobjects.MetaDataException(
+                "Circular dependency detected involving provider: " + providerId,
+                com.metaobjects.ErrorCode.ERR_PROVIDER_DEPENDENCY_CYCLE);
+        }
+        if (visited.contains(providerId)) {
+            return;
+        }
+        visiting.add(providerId);
+        for (String depId : provider.getDependencies()) {
+            MetaDataTypeProvider dependency = providerMap.get(depId);
+            if (dependency != null) {
+                topologicalSortStrict(dependency, providerMap, visited, visiting, result);
+            }
+        }
+        visiting.remove(providerId);
+        visited.add(providerId);
+        result.add(provider);
+    }
+
     /**
      * Resolve deferred inheritance for types whose parents weren't available during initial registration.
      * This method should be called after all static type registrations have completed.
diff --git a/server/java/metadata/src/test/java/com/metaobjects/registry/ComposeRegistryTest.java b/server/java/metadata/src/test/java/com/metaobjects/registry/ComposeRegistryTest.java
@@ -0,0 +1,170 @@
+package com.metaobjects.registry;
+
+import com.metaobjects.ErrorCode;
+import com.metaobjects.MetaDataException;
+import org.junit.Test;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertTrue;
+import static org.junit.Assert.fail;
+
+/**
+ * Tests for the programmatic provider-composition API on {@link MetaDataRegistry}.
+ *
+ * <p>Mirrors the cross-port pattern shipped by the TypeScript port
+ * ({@code composeRegistry(providers)}) and the Python port
+ * ({@code compose_registry(providers)}). This Java entry point lets callers
+ * build a registry by handing it an explicit list of providers — useful for
+ * tests, embedded scenarios where ServiceLoader is awkward, and conditional
+ * / framework-driven composition.</p>
+ */
+public class ComposeRegistryTest {
+
+    /** A minimal recording provider that captures the registry it was registered against. */
+    static final class RecordingProvider implements MetaDataTypeProvider {
+        private final String id;
+        private final String[] deps;
+        MetaDataRegistry registeredAgainst;
+
+        RecordingProvider(String id, String... deps) {
+            this.id = id;
+            this.deps = deps;
+        }
+
+        @Override
+        public String getProviderId() {
+            return id;
+        }
+
+        @Override
+        public String[] getDependencies() {
+            return deps;
+        }
+
+        @Override
+        public void registerTypes(MetaDataRegistry registry) {
+            this.registeredAgainst = registry;
+        }
+
+        @Override
+        public String getDescription() {
+            return "recording-provider:" + id;
+        }
+    }
+
+    /** A provider that records the order it ran in (mutating a shared list). */
+    static final class OrderRecordingProvider implements MetaDataTypeProvider {
+        private final String id;
+        private final String[] deps;
+        private final List<String> log;
+
+        OrderRecordingProvider(String id, List<String> log, String... deps) {
+            this.id = id;
+            this.log = log;
+            this.deps = deps;
+        }
+
+        @Override
+        public String getProviderId() {
+            return id;
+        }
+
+        @Override
+        public String[] getDependencies() {
+            return deps;
+        }
+
+        @Override
+        public void registerTypes(MetaDataRegistry registry) {
+            log.add(id);
+        }
+    }
+
+    @Test
+    public void compose_buildsRegistry_andRunsEachProviderAgainstIt() {
+        RecordingProvider a = new RecordingProvider("a");
+        RecordingProvider b = new RecordingProvider("b");
+
+        MetaDataRegistry registry = MetaDataRegistry.compose(List.of(a, b));
+
+        assertNotNull("compose() should return a non-null registry", registry);
+        assertSame("provider a should have registered against the returned registry",
+            registry, a.registeredAgainst);
+        assertSame("provider b should have registered against the returned registry",
+            registry, b.registeredAgainst);
+    }
+
+    @Test
+    public void compose_runsProvidersInDependencyOrder() {
+        List<String> order = new ArrayList<>();
+        OrderRecordingProvider a = new OrderRecordingProvider("a", order);
+        OrderRecordingProvider b = new OrderRecordingProvider("b", order, "a");
+        OrderRecordingProvider c = new OrderRecordingProvider("c", order, "b");
+
+        // Feed in reverse order — topo sort should still produce a, b, c.
+        MetaDataRegistry.compose(List.of(c, b, a));
+
+        assertEquals("providers must run in topological order regardless of input order",
+            List.of("a", "b", "c"), order);
+    }
+
+    @Test
+    public void compose_throwsDuplicateId() {
+        RecordingProvider dup1 = new RecordingProvider("dup");
+        RecordingProvider dup2 = new RecordingProvider("dup");
+
+        try {
+            MetaDataRegistry.compose(List.of(dup1, dup2));
+            fail("expected MetaDataException with ERR_PROVIDER_DUPLICATE_ID");
+        } catch (MetaDataException e) {
+            assertEquals(ErrorCode.ERR_PROVIDER_DUPLICATE_ID, e.getCode().orElse(null));
+            assertTrue("message should call out the duplicate id",
+                e.getMessage().contains("dup"));
+        }
+    }
+
+    @Test
+    public void compose_throwsMissingDependency() {
+        RecordingProvider provider = new RecordingProvider("dependent", "absent");
+
+        try {
+            MetaDataRegistry.compose(List.of(provider));
+            fail("expected MetaDataException with ERR_PROVIDER_MISSING_DEPENDENCY");
+        } catch (MetaDataException e) {
+            assertEquals(ErrorCode.ERR_PROVIDER_MISSING_DEPENDENCY, e.getCode().orElse(null));
+            assertTrue("message should call out the missing dependency id",
+                e.getMessage().contains("absent"));
+            assertTrue("message should identify the requiring provider",
+                e.getMessage().contains("dependent"));
+        }
+    }
+
+    @Test
+    public void compose_throwsDependencyCycle() {
+        RecordingProvider a = new RecordingProvider("a", "b");
+        RecordingProvider b = new RecordingProvider("b", "a");
+
+        try {
+            MetaDataRegistry.compose(List.of(a, b));
+            fail("expected MetaDataException with ERR_PROVIDER_DEPENDENCY_CYCLE");
+        } catch (MetaDataException e) {
+            assertEquals(ErrorCode.ERR_PROVIDER_DEPENDENCY_CYCLE, e.getCode().orElse(null));
+        }
+    }
+
+    @Test
+    public void registerProviders_addsToExistingRegistry() {
+        MetaDataRegistry registry = new MetaDataRegistry();
+        RecordingProvider added = new RecordingProvider("added");
+
+        registry.registerProviders(List.of(added));
+
+        assertSame("registerProviders should hand the receiving registry to the provider",
+            registry, added.registeredAgainst);
+    }
+}
