Add structured public DataProvider exceptions

.github/workflows/ci-tests-and-coverage.yml

@@ -30,20 +30,31 @@ jobs:
           cache: maven
 
       - name: Run Unit and Backend Integration Tests
+        id: tests
         run: mvn -U -B -ntp -Pintegration-tests verify
 
+      - name: Print failing test reports
+        if: failure() && steps.tests.outcome == 'failure'
+        shell: bash
+        run: |
+          find . -type f \( -path '*/target/surefire-reports/*.txt' -o -path '*/target/failsafe-reports/*.txt' \) -print0 \
+            | sort -z \
+            | xargs -0 -r -n1 sh -c 'echo "::group::$0"; cat "$0"; echo "::endgroup::"'
+
       - name: Upload JaCoCo Report
         if: always()
         uses: actions/upload-artifact@v7
         with:
           name: jacoco-report
-          if-no-files-found: error
+          if-no-files-found: warn
           path: "**/target/site/jacoco"
 
-      - name: Upload Integration Test Reports
+      - name: Upload Test Reports
         if: always()
         uses: actions/upload-artifact@v7
         with:
-          name: integration-test-reports
-          if-no-files-found: error
-          path: "**/target/failsafe-reports"
+          name: test-reports
+          if-no-files-found: warn
+          path: |
+            **/target/surefire-reports
+            **/target/failsafe-reports

dataprovider-api/src/main/java/nl/hauntedmc/dataprovider/api/DataProviderAPI.java

@@ -1,33 +1,22 @@
 package nl.hauntedmc.dataprovider.api;
 
+import nl.hauntedmc.dataprovider.api.orm.ORMContext;
 import nl.hauntedmc.dataprovider.database.DataAccess;
 import nl.hauntedmc.dataprovider.database.DatabaseProvider;
 import nl.hauntedmc.dataprovider.database.DatabaseType;
-import nl.hauntedmc.dataprovider.api.orm.ORMContext;
+import nl.hauntedmc.dataprovider.exception.DataProviderFailureContext;
+import nl.hauntedmc.dataprovider.exception.DataProviderRegistrationException;
+import nl.hauntedmc.dataprovider.exception.ExecutionOutcome;
+import nl.hauntedmc.dataprovider.exception.RetryAdvice;
 import nl.hauntedmc.dataprovider.logging.LoggerAdapter;
 
 import javax.sql.DataSource;
 import java.util.Objects;
 import java.util.Optional;
 
-/**
- * Public, platform-neutral facade for plugin-scoped database registrations.
- *
- * <p>The API artifact intentionally contains contracts only. Platform modules provide the
- * runtime implementation and expose an instance through their native service mechanism.</p>
- */
+/** Public, platform-neutral facade for plugin-scoped database registrations. */
 public interface DataProviderAPI {
 
-    /**
-     * Creates an isolated ORM context owned by the calling plugin.
-     *
-     * @param pluginName plugin name used for ORM diagnostics
-     * @param dataSource relational data source obtained from a registered provider
-     * @param logger logger that receives ORM lifecycle diagnostics
-     * @param schemaMode Hibernate schema mode: validate, none, update, or create
-     * @param entityClasses annotated entity classes to register
-     * @return a new, initialized ORM context
-     */
     ORMContext createOrmContext(
             String pluginName,
             DataSource dataSource,
@@ -36,8 +25,31 @@ ORMContext createOrmContext(
             Class<?>... entityClasses
     );
 
+    /** Legacy nullable registration method retained for compatibility. */
     DatabaseProvider registerDatabase(DatabaseType databaseType, String connectionIdentifier);
 
+    /**
+     * Registers a database or throws a structured public exception retaining the failure category.
+     * Implementations should override this method to preserve backend-specific failure details.
+     */
+    default DatabaseProvider registerDatabaseOrThrow(DatabaseType databaseType, String connectionIdentifier) {
+        DatabaseProvider provider = registerDatabase(databaseType, connectionIdentifier);
+        if (provider != null) {
+            return provider;
+        }
+        throw new DataProviderRegistrationException(
+                "Database registration failed.",
+                DataProviderFailureContext.of(
+                        databaseType,
+                        connectionIdentifier,
+                        "registerDatabase",
+                        RetryAdvice.CONDITIONAL,
+                        ExecutionOutcome.NOT_STARTED
+                ),
+                null
+        );
+    }
+
     DataProviderScope scope(OwnerScope ownerScope);
 
     void unregisterDatabase(DatabaseType databaseType, String connectionIdentifier);
@@ -46,9 +58,28 @@ ORMContext createOrmContext(
 
     void unregisterAllDatabasesForPlugin();
 
+    /** Legacy nullable lookup retained for compatibility. */
     DatabaseProvider getRegisteredDatabase(DatabaseType databaseType, String connectionIdentifier);
 
-    /** Creates an isolated ownership scope for independently managed plugin components. */
+    /** Returns a registered provider or throws a structured registration-state failure. */
+    default DatabaseProvider requireRegisteredDatabase(DatabaseType databaseType, String connectionIdentifier) {
+        DatabaseProvider provider = getRegisteredDatabase(databaseType, connectionIdentifier);
+        if (provider != null) {
+            return provider;
+        }
+        throw new DataProviderRegistrationException(
+                "No active database registration exists for the requested connection.",
+                DataProviderFailureContext.of(
+                        databaseType,
+                        connectionIdentifier,
+                        "requireRegisteredDatabase",
+                        RetryAdvice.NEVER,
+                        ExecutionOutcome.NOT_STARTED
+                ),
+                null
+        );
+    }
+
     default DataProviderScope scope(String ownerScope) {
         return scope(OwnerScope.of(ownerScope));
     }

dataprovider-api/src/main/java/nl/hauntedmc/dataprovider/api/DataProviderScope.java

@@ -3,16 +3,17 @@
 import nl.hauntedmc.dataprovider.database.DataAccess;
 import nl.hauntedmc.dataprovider.database.DatabaseProvider;
 import nl.hauntedmc.dataprovider.database.DatabaseType;
+import nl.hauntedmc.dataprovider.exception.DataProviderFailureContext;
+import nl.hauntedmc.dataprovider.exception.DataProviderRegistrationException;
+import nl.hauntedmc.dataprovider.exception.ExecutionOutcome;
+import nl.hauntedmc.dataprovider.exception.RetryAdvice;
 
 import java.util.Objects;
 import java.util.Optional;
 
-/**
- * Isolated lifecycle boundary for a logical component within one plugin.
- */
+/** Isolated lifecycle boundary for a logical component within one plugin. */
 public interface DataProviderScope extends AutoCloseable {
 
-    /** Lifecycle states for a scope. A closed scope cannot be reopened. */
     enum LifecycleState {
         OPEN,
         CLOSING,
@@ -21,29 +22,56 @@ enum LifecycleState {
 
     OwnerScope ownerScope();
 
-    /**
-     * Returns this scope's current lifecycle state.
-     * Implementations created by DataProvider transition from OPEN to CLOSING to CLOSED on close.
-     */
     default LifecycleState lifecycleState() {
         return LifecycleState.OPEN;
     }
 
     DatabaseProvider registerDatabase(DatabaseType databaseType, String connectionIdentifier);
 
+    default DatabaseProvider registerDatabaseOrThrow(DatabaseType databaseType, String connectionIdentifier) {
+        DatabaseProvider provider = registerDatabase(databaseType, connectionIdentifier);
+        if (provider != null) {
+            return provider;
+        }
+        throw new DataProviderRegistrationException(
+                "Scoped database registration failed.",
+                DataProviderFailureContext.of(
+                        databaseType,
+                        connectionIdentifier,
+                        "scope.registerDatabase",
+                        RetryAdvice.CONDITIONAL,
+                        ExecutionOutcome.NOT_STARTED
+                ).withDiagnostics(java.util.Map.of("ownerScope", ownerScope().value())),
+                null
+        );
+    }
+
     void unregisterDatabase(DatabaseType databaseType, String connectionIdentifier);
 
     void unregisterAllDatabases();
 
-    /**
-     * Retrieves a provider registered by this scope.
-     *
-     * @throws UnsupportedOperationException if the scope implementation does not support scoped lookup
-     */
     default DatabaseProvider getRegisteredDatabase(DatabaseType databaseType, String connectionIdentifier) {
         throw new UnsupportedOperationException("Scoped provider lookup is not supported by this implementation.");
     }
 
+    default DatabaseProvider requireRegisteredDatabase(DatabaseType databaseType, String connectionIdentifier) {
+        DatabaseProvider provider = getRegisteredDatabase(databaseType, connectionIdentifier);
+        if (provider != null) {
+            return provider;
+        }
+        throw new DataProviderRegistrationException(
+                "No active scoped database registration exists for the requested connection.",
+                DataProviderFailureContext.of(
+                        databaseType,
+                        connectionIdentifier,
+                        "scope.requireRegisteredDatabase",
+                        RetryAdvice.NEVER,
+                        ExecutionOutcome.NOT_STARTED
+                ).withDiagnostics(java.util.Map.of("ownerScope", ownerScope().value())),
+                null
+        );
+    }
+
     default Optional<DatabaseProvider> registerDatabaseOptional(
             DatabaseType databaseType,
             String connectionIdentifier

dataprovider-api/src/main/java/nl/hauntedmc/dataprovider/exception/BackendAuthenticationException.java

@@ -0,0 +1,8 @@
+package nl.hauntedmc.dataprovider.exception;
+
+/** Backend rejected configured authentication. */
+public final class BackendAuthenticationException extends DataProviderException {
+    public BackendAuthenticationException(String message, DataProviderFailureContext context, Throwable cause) {
+        super(DataProviderErrorCode.AUTHENTICATION_FAILED, message, context, cause);
+    }
+}

dataprovider-api/src/main/java/nl/hauntedmc/dataprovider/exception/BackendUnavailableException.java

@@ -0,0 +1,13 @@
+package nl.hauntedmc.dataprovider.exception;
+
+/** Backend is disabled, unreachable, or otherwise unavailable. */
+public final class BackendUnavailableException extends DataProviderException {
+    public BackendUnavailableException(DataProviderErrorCode code, String message,
+                                       DataProviderFailureContext context, Throwable cause) {
+        super(code, message, context, cause);
+        if (code != DataProviderErrorCode.BACKEND_DISABLED
+                && code != DataProviderErrorCode.BACKEND_UNAVAILABLE) {
+            throw new IllegalArgumentException("Unsupported backend availability error code: " + code);
+        }
+    }
+}

dataprovider-api/src/main/java/nl/hauntedmc/dataprovider/exception/DataConflictException.java

@@ -0,0 +1,8 @@
+package nl.hauntedmc.dataprovider.exception;
+
+/** A uniqueness, optimistic-locking, or compare-and-set conflict occurred. */
+public final class DataConflictException extends DataProviderException {
+    public DataConflictException(String message, DataProviderFailureContext context, Throwable cause) {
+        super(DataProviderErrorCode.CONFLICT, message, context, cause);
+    }
+}

dataprovider-api/src/main/java/nl/hauntedmc/dataprovider/exception/DataProviderConfigurationException.java

@@ -0,0 +1,13 @@
+package nl.hauntedmc.dataprovider.exception;
+
+/** Invalid or missing DataProvider configuration. */
+public final class DataProviderConfigurationException extends DataProviderException {
+    public DataProviderConfigurationException(DataProviderErrorCode code, String message,
+                                              DataProviderFailureContext context, Throwable cause) {
+        super(code, message, context, cause);
+        if (code != DataProviderErrorCode.CONFIGURATION_INVALID
+                && code != DataProviderErrorCode.CONFIGURATION_MISSING) {
+            throw new IllegalArgumentException("Unsupported configuration error code: " + code);
+        }
+    }
+}

dataprovider-api/src/main/java/nl/hauntedmc/dataprovider/exception/DataProviderErrorCode.java

@@ -0,0 +1,18 @@
+package nl.hauntedmc.dataprovider.exception;
+
+/** Stable machine-readable failure codes exposed by the DataProvider API. */
+public enum DataProviderErrorCode {
+    CONFIGURATION_INVALID,
+    CONFIGURATION_MISSING,
+    REGISTRATION_FAILED,
+    BACKEND_DISABLED,
+    BACKEND_UNAVAILABLE,
+    AUTHENTICATION_FAILED,
+    OPERATION_FAILED,
+    OPERATION_TIMED_OUT,
+    QUEUE_SATURATED,
+    SERIALIZATION_FAILED,
+    CONFLICT,
+    TRANSACTION_FAILED,
+    PROVIDER_CLOSED
+}