Refactor for 2.1 release

.github/workflows/site.yml

@@ -0,0 +1,48 @@
+name: Publish Maven Site
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: publish-maven-site-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  publish-site:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v6
+
+      - name: Set up Java 17
+        uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: '17'
+          cache: maven
+
+      # TODO: Later on, we need to extend this mechanism to provide both version and snapshot,
+      #       as well as a different case the stable version and "latest".
+      - name: Build and verify project site
+        # By default, docs.site.base is / for local development. For deployment, this needs to be adapted.
+        # IMPORTANT: make sure the base ends with "/"!
+        run: mvn -B verify site -Ddocs.site.base=/dataverse-spi/snapshot/
+
+      - name: Add .nojekyll
+        run: touch target/site/.nojekyll
+
+      - name: Deploy to gh-pages
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: gh-pages
+          folder: target/site
+          target-folder: snapshot
+          clean: true
+          single-commit: true

api/pom.xml

@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>io.gdcc.spi</groupId>
+        <artifactId>parent</artifactId>
+        <version>2.1.0-SNAPSHOT</version>
+    </parent>
+
+    <groupId>io.gdcc</groupId>
+    <artifactId>dataverse-spi</artifactId>
+    <!-- For now, keep all the module versions in lockstep. Can be diversified later. -->
+    <!-- <version>x.y.z.-SNAPSHOT</version> -->
+
+    <!--
+        Even with no source code, still package as JAR!
+        As a POM-only artifact, it only acts like a BOM/parent, not roping in dependencies for users!
+    -->
+    <packaging>jar</packaging>
+
+    <!--
+        This module aggregates all the artifacts to form a single distribution package.
+        Users use the transitive dependencies to build Dataverse plugins.
+    -->
+    <dependencies>
+        <dependency>
+            <groupId>io.gdcc.spi</groupId>
+            <artifactId>meta</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.gdcc.spi</groupId>
+            <artifactId>core</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.gdcc.spi</groupId>
+            <artifactId>export</artifactId>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-shade-plugin</artifactId>
+                <version>3.6.2</version>
+                <executions>
+                    <execution>
+                        <phase>package</phase>
+                        <goals>
+                            <goal>shade</goal>
+                        </goals>
+                        <configuration>
+                            <shadedArtifactAttached>false</shadedArtifactAttached>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>

core/pom.xml

@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>io.gdcc.spi</groupId>
+        <artifactId>parent</artifactId>
+        <version>2.1.0-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>core</artifactId>
+    <!-- For now, keep all the module versions in lockstep. Can be diversified later. -->
+    <!-- <version>x.y.z.-SNAPSHOT</version> -->
+
+    <dependencies>
+        <dependency>
+            <groupId>io.gdcc.spi</groupId>
+            <artifactId>meta</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-api</artifactId>
+            <scope>provided</scope>
+        </dependency>
+
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-simple</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+</project>

core/src/main/java/io/gdcc/spi/core/loader/LoaderConfiguration.java

@@ -0,0 +1,196 @@
+package io.gdcc.spi.core.loader;
+
+
+/**
+ * Immutable configuration controlling the behavior of the plugin loader.
+ *
+ * <p>Use {@link #defaults()} to start from the standard configuration and then
+ * adjust individual options with the fluent {@code with...} methods.</p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * LoaderConfiguration configuration = LoaderConfiguration.defaults()
+ *     .withEmitWarningsOnMultiPluginSource(true)
+ *     .withAbortOnCompatibilityProblems(false);
+ * }</pre>
+ */
+public final class LoaderConfiguration {
+
+    private final boolean enforceSingleSourceMatchingPluginsOnly;
+    private final boolean emitWarningsOnMultiPluginSource;
+    private final boolean abortOnCompatibilityProblems;
+    private final boolean abortOnDuplicatedIdentities;
+    private final boolean enforceUnambiguousPluginIdentities;
+
+    private LoaderConfiguration(
+        boolean enforceSingleSourceMatchingPluginsOnly,
+        boolean emitWarningsOnMultiPluginSource,
+        boolean abortOnCompatibilityProblems,
+        boolean abortOnDuplicatedIdentities,
+        boolean enforceUnambiguousPluginIdentities
+    ) {
+        this.enforceSingleSourceMatchingPluginsOnly = enforceSingleSourceMatchingPluginsOnly;
+        this.emitWarningsOnMultiPluginSource = emitWarningsOnMultiPluginSource;
+        this.abortOnCompatibilityProblems = abortOnCompatibilityProblems;
+        this.abortOnDuplicatedIdentities = abortOnDuplicatedIdentities;
+        this.enforceUnambiguousPluginIdentities = enforceUnambiguousPluginIdentities;
+    }
+
+    /**
+     * Returns the standard loader configuration (which is strictly enforcing).
+     *
+     * <ul>
+     *   <li>{@code enforceSingleSourceMatchingPluginsOnly = false}</li>
+     *   <li>{@code emitWarningsOnMultiPluginSource = false}</li>
+     *   <li>{@code abortOnCompatibilityProblems = true}</li>
+     *   <li>{@code abortOnDuplicatedIdentities = true}</li>
+     *   <li>{@code enforceUnambiguousPluginIdentities = true}</li>
+     * </ul>
+     */
+    public static LoaderConfiguration defaults() {
+        return new LoaderConfiguration(
+            true,
+            false,
+            true,
+            true,
+            true
+        );
+    }
+
+    /**
+     * Returns a permissive loader configuration with all strict validation features disabled.
+     * It has package private visibility as the only permissive usage is in a testing context.
+     *
+     * <p>
+     * The configuration has the following properties:
+     * <ul>
+     * <li>{@code enforceSingleSourceMatchingPluginsOnly = false}</li>
+     * <li>{@code emitWarningsOnMultiPluginSource = false}</li>
+     * <li>{@code abortOnCompatibilityProblems = false}</li>
+     * <li>{@code abortOnDuplicatedIdentities = false}</li>
+     * <li>{@code enforceUnambiguousPluginIdentities = false}</li>
+     * </ul>
+     * </p>
+     *
+     * @return a {@code LoaderConfiguration} instance with permissive settings.
+     */
+    static LoaderConfiguration permissive() {
+        return new LoaderConfiguration(
+            false,
+            false,
+            false,
+            false,
+            false
+        );
+    }
+
+    /**
+     * When enabled, a source may only provide plugins for a single requested base contract.
+     * If any non-matching plugin is found, loading from that source is aborted entirely.
+     *
+     * <p>When disabled, non-matching plugins are ignored.</p>
+     */
+    public boolean enforceSingleSourceMatchingPluginsOnly() {
+        return enforceSingleSourceMatchingPluginsOnly;
+    }
+
+    /**
+     * Returns a copy with {@link #enforceSingleSourceMatchingPluginsOnly()} updated.
+     */
+    public LoaderConfiguration withEnforceSingleSourceMatchingPluginsOnly(boolean value) {
+        return new LoaderConfiguration(
+            value,
+            emitWarningsOnMultiPluginSource,
+            abortOnCompatibilityProblems,
+            abortOnDuplicatedIdentities,
+            enforceUnambiguousPluginIdentities
+        );
+    }
+
+    /**
+     * When {@link #enforceSingleSourceMatchingPluginsOnly()} is disabled, controls whether
+     * multi-plugin-contract sources should emit warnings.
+     */
+    public boolean emitWarningsOnMultiPluginSource() {
+        return emitWarningsOnMultiPluginSource;
+    }
+
+    /**
+     * Returns a copy with {@link #emitWarningsOnMultiPluginSource()} updated.
+     */
+    public LoaderConfiguration withEmitWarningsOnMultiPluginSource(boolean value) {
+        return new LoaderConfiguration(
+            enforceSingleSourceMatchingPluginsOnly,
+            value,
+            abortOnCompatibilityProblems,
+            abortOnDuplicatedIdentities,
+            enforceUnambiguousPluginIdentities
+        );
+    }
+
+    /**
+     * When enabled, plugin loading aborts on discovered compatibility problems (for example, API level mismatches).
+     * No classes are actually loaded, problems are detected using plugin metadata only.
+     */
+    public boolean abortOnCompatibilityProblems() {
+        return abortOnCompatibilityProblems;
+    }
+
+    /**
+     * Returns a copy with {@link #abortOnCompatibilityProblems()} updated.
+     */
+    public LoaderConfiguration withAbortOnCompatibilityProblems(boolean value) {
+        return new LoaderConfiguration(
+            enforceSingleSourceMatchingPluginsOnly,
+            emitWarningsOnMultiPluginSource,
+            value,
+            abortOnDuplicatedIdentities,
+            enforceUnambiguousPluginIdentities
+        );
+    }
+
+    /**
+     * When enabled, loading aborts if duplicate plugin identities are detected.
+     *
+     * <p>Note: duplicated identities make plugins undistinguishable for users.</p>
+     */
+    public boolean abortOnDuplicatedIdentities() {
+        return abortOnDuplicatedIdentities;
+    }
+
+    /**
+     * Returns a copy with {@link #abortOnDuplicatedIdentities()} updated.
+     */
+    public LoaderConfiguration withAbortOnDuplicatedIdentities(boolean value) {
+        return new LoaderConfiguration(
+            enforceSingleSourceMatchingPluginsOnly,
+            emitWarningsOnMultiPluginSource,
+            abortOnCompatibilityProblems,
+            value,
+            enforceUnambiguousPluginIdentities
+        );
+    }
+
+    /**
+     * When enabled, plugin identities must be unique within a source.
+     * Any plugin's identity that differs by case or special chars only will be seen as a duplicate.
+     */
+    public boolean enforceUnambiguousPluginIdentities() {
+        return enforceUnambiguousPluginIdentities;
+    }
+
+    /**
+     * Returns a copy with {@link #enforceUnambiguousPluginIdentities()} updated.
+     */
+    public LoaderConfiguration withEnforceUnambiguousPluginIdentities(boolean value) {
+        return new LoaderConfiguration(
+            enforceSingleSourceMatchingPluginsOnly,
+            emitWarningsOnMultiPluginSource,
+            abortOnCompatibilityProblems,
+            abortOnDuplicatedIdentities,
+            value
+        );
+    }
+}
+
+

core/src/main/java/io/gdcc/spi/core/loader/LoaderException.java

@@ -0,0 +1,17 @@
+package io.gdcc.spi.core.loader;
+
+import java.util.List;
+
+public class LoaderException extends RuntimeException {
+
+    private final List<LoaderProblem> problems;
+
+    public LoaderException(List<LoaderProblem> problems) {
+        super("Multiple problems have been detected by the loader, accessible from getProblems().");
+        this.problems = List.copyOf(problems);
+    }
+
+    public List<LoaderProblem> getProblems() {
+        return problems;
+    }
+}