Permit java.sql for Elements and clarify classloader denial errors

Adds JavaSqlPermittedPackages so java.sql types (e.g. Timestamp) are
visible to Elements the same way java.base types already are,
registered via the existing PermittedPackages SPI convention.

Also gives PermittedTypesClassLoader and ElementImplementationClassLoader
denial paths descriptive exception messages naming which mechanism
denied the class and how to permit it, instead of a bare class name,
so a NoClassDefFoundError several frames removed from these loaders is
diagnosable without already knowing about this visibility gate.

Fixes #75

Author: Patrick Twohig

sdk-spi/src/main/java/dev/getelements/elements/sdk/spi/ElementImplementationClassLoader.java

@@ -3,8 +3,10 @@
 import dev.getelements.elements.sdk.PermittedPackages;
 import dev.getelements.elements.sdk.PermittedTypes;
 import dev.getelements.elements.sdk.annotation.ElementLocal;
+import dev.getelements.elements.sdk.annotation.ElementPackageRequest;
 import dev.getelements.elements.sdk.annotation.ElementPrivate;
 import dev.getelements.elements.sdk.annotation.ElementPublic;
+import dev.getelements.elements.sdk.annotation.ElementTypeRequest;
 import dev.getelements.elements.sdk.exception.SdkException;
 import dev.getelements.elements.sdk.record.ElementRecord;
 import dev.getelements.elements.sdk.record.ElementServiceRecord;
@@ -276,7 +278,24 @@ protected Class<?> loadClass(final String name, final boolean resolve) throws Cl
                 }
 
                 // Step 9: Default Deny
-                throw new ClassNotFoundException(name);
+                final var message = (
+                        "%s was denied by %s: it is not a registered service export, and no %s or %s in this " +
+                        "Element's package-info.java permits type or package %s. To permit this type, add " +
+                        "@%s(\"%s\") or @%s to the Element's package-info.java, or export it as a service."
+                ).formatted(
+                        name,
+                        ElementImplementationClassLoader.class.getSimpleName(),
+                        ElementTypeRequest.class.getSimpleName(),
+                        ElementPackageRequest.class.getSimpleName(),
+                        packageName,
+                        ElementPackageRequest.class.getSimpleName(),
+                        packageName,
+                        ElementTypeRequest.class.getSimpleName()
+                );
+
+                logger.trace(message);
+
+                throw new ClassNotFoundException(message);
 
             }
 

sdk/src/main/java/dev/getelements/elements/sdk/JavaSqlPermittedPackages.java

@@ -0,0 +1,18 @@
+package dev.getelements.elements.sdk;
+
+public class JavaSqlPermittedPackages implements PermittedPackages {
+
+    @Override
+    public boolean test(final Package aPackage) {
+        final var name = aPackage.getName();
+        return name.equals("java.sql") || name.startsWith("java.sql.");
+    }
+
+    @Override
+    public String getDescription() {
+        return "Permits the usage of java.sql types (e.g. java.sql.Timestamp, java.sql.Date). Unlike java.base, " +
+                "the java.sql platform module is not loaded by the bootstrap class loader, so its types are not " +
+                "otherwise visible to Elements without this rule.";
+    }
+
+}

sdk/src/main/java/dev/getelements/elements/sdk/PermittedTypesClassLoader.java

@@ -1,6 +1,5 @@
 package dev.getelements.elements.sdk;
 
-import dev.getelements.elements.sdk.annotation.ElementDefinition;
 import dev.getelements.elements.sdk.annotation.ElementPrivate;
 import dev.getelements.elements.sdk.annotation.ElementPublic;
 import org.slf4j.Logger;
@@ -203,26 +202,38 @@ private Class<?> processVisibilityAnnotations(final Class<?> aClass) throws Clas
             return aClass;
         }
 
-        logger.trace(
-                "{} or {}'s package ({}) must have @{} annotation, be exposed via @{}, or one of [{}] or [{}]",
-                aClass.getSimpleName(),
-                aClass.getSimpleName(),
+        final var message = (
+                "%s was denied by %s: its package (%s) is not permitted by any registered %s or %s, and " +
+                "neither the type nor its package is annotated with @%s. Registered %s: [%s]. Registered %s: [%s]. " +
+                "To permit this type, register a %s/%s service (see META-INF/services), or annotate the type or " +
+                "its package with @%s."
+        ).formatted(
+                aClass.getName(),
+                PermittedTypesClassLoader.class.getSimpleName(),
                 aClass.getPackage(),
+                PermittedTypes.class.getSimpleName(),
+                PermittedPackages.class.getSimpleName(),
                 ElementPublic.class.getSimpleName(),
-                ElementDefinition.class.getSimpleName(),
+                PermittedTypes.class.getSimpleName(),
                 permittedTypes
                         .stream()
                         .map(Object::getClass)
                         .map(Objects::toString)
                         .collect(Collectors.joining(",")),
+                PermittedPackages.class.getSimpleName(),
                 permittedPackages
                         .stream()
                         .map(Object::getClass)
                         .map(Objects::toString)
-                        .collect(Collectors.joining(","))
+                        .collect(Collectors.joining(",")),
+                PermittedTypes.class.getSimpleName(),
+                PermittedPackages.class.getSimpleName(),
+                ElementPublic.class.getSimpleName()
         );
 
-        throw new ClassNotFoundException(aClass.getName());
+        logger.trace(message);
+
+        throw new ClassNotFoundException(message);
 
     }
 

sdk/src/main/resources/META-INF/services/dev.getelements.elements.sdk.PermittedPackages

@@ -1,2 +1,3 @@
 dev.getelements.elements.sdk.LoggingPermittedPackages
 dev.getelements.elements.sdk.JakartaInjectPermittedPackages
+dev.getelements.elements.sdk.JavaSqlPermittedPackages