HHH-16548 more flexible / robust way to specify root URL and jar file URLs for PersistenceConfiguration

Author: gavinking

hibernate-core/src/main/java/org/hibernate/boot/model/process/internal/ScanningCoordinator.java

@@ -94,15 +94,16 @@ private static Scanner buildScanner(BootstrapContext bootstrapContext, ClassLoad
 							.loadJavaServices( ScannerFactory.class )
 							.iterator();
 			if ( iterator.hasNext() ) {
-				// todo: check for multiple scanner and in case raise a warning?
 				final ScannerFactory factory = iterator.next();
-				return factory.getScanner( archiveDescriptorFactory );
+				final Scanner scanner = factory.getScanner( archiveDescriptorFactory );
+				if ( iterator.hasNext() ) {
+					log.warn("Multiple ScannerFactory services available; using '"
+								+ scanner.getClass().getName() + "'");
+				}
+				return scanner;
 			}
 			else {
-				if ( bootstrapContext.getScanOptions().canDetectUnlistedClassesInRoot() ) {
-					throw new IllegalStateException( "No ScannerFactory available"
-							+ " (add 'hibernate-scan-jandex' dependency or disable 'hibernate.archive.autodetection')" );
-				}
+				log.debug("No ScannerFactory available; add 'hibernate-scan-jandex' dependency to enable scanning");
 				return new DisabledScanner();
 			}
 		}

hibernate-core/src/main/java/org/hibernate/jpa/HibernatePersistenceConfiguration.java

@@ -4,8 +4,11 @@
  */
 package org.hibernate.jpa;
 
+import java.net.URL;
+import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Collections;
+import java.util.List;
 import java.util.Map;
 import java.util.Objects;
 
@@ -17,6 +20,7 @@
 import org.hibernate.cfg.JdbcSettings;
 import org.hibernate.cfg.JpaComplianceSettings;
 import org.hibernate.cfg.MappingSettings;
+import org.hibernate.cfg.PersistenceSettings;
 import org.hibernate.cfg.SchemaToolingSettings;
 import org.hibernate.cfg.StatisticsSettings;
 import org.hibernate.resource.jdbc.spi.StatementInspector;
@@ -67,11 +71,12 @@
  * <li>properties specified in {@code hibernate.properties}.
  * </ul>
  * <p>
- * When {@linkplain org.hibernate.cfg.PersistenceSettings#SCANNER_DISCOVERY
- * entity discovery} is explicitly enabled, and {@code hibernate-scan-jandex}
- * or some other {@link org.hibernate.boot.archive.scan.spi.ScannerFactory}
- * service is available, the current working directly is scanned for entity
- * classes, alleviating the program of the need to call {@link #managedClass}.
+ * When a {@linkplain #rootUrl() root URL} is supplied, or when at least
+ * one {@linkplain #jarFileUrls() JAR file URL} is supplied, and when
+ * {@code hibernate-scan-jandex} or some other service implementing
+ * {@link org.hibernate.boot.archive.scan.spi.ScannerFactory} is available,
+ * the current working directly is scanned for entity classes, alleviating
+ * the program of the need to call {@link #managedClass}.
  *
  * @apiNote The specification explicitly encourages implementors to extend
  *          {@link PersistenceConfiguration} to accommodate vendor-specific
@@ -84,6 +89,10 @@
  * @since 7.0
  */
 public class HibernatePersistenceConfiguration extends PersistenceConfiguration {
+
+	private URL rootUrl;
+	private final List<URL> jarFileUrls = new ArrayList<>();
+
 	/**
 	 * Create a new empty configuration. An empty configuration does not
 	 * typically hold enough information for successful invocation of
@@ -96,6 +105,49 @@ public HibernatePersistenceConfiguration(String name) {
 		super( name );
 	}
 
+	/**
+	 * Create a new empty configuration with a given {@linkplain #rootUrl root URL}
+	 * used for {@linkplain PersistenceSettings#SCANNER_DISCOVERY entity discovery}
+	 * via scanning.
+	 * <p>
+	 * The module {@code hibernate-scan-jandex} must be added as a dependency,
+	 * or some other implementation of the service
+	 * {@link org.hibernate.boot.archive.scan.spi.ScannerFactory} must be made
+	 * available.
+	 *
+	 * @param name the name of the persistence unit, which may be used by
+	 * the persistence provider for logging and error reporting
+	 * @param rootURL the root URL of the persistence unit
+	 *
+	 * @since 7.1
+	 */
+	public HibernatePersistenceConfiguration(String name, URL rootURL) {
+		super( name );
+		this.rootUrl = rootURL;
+	}
+
+	/**
+	 * Create a new empty configuration with the {@linkplain #rootUrl root URL}
+	 * inferred from the given class file and used for
+	 * {@linkplain PersistenceSettings#SCANNER_DISCOVERY entity discovery}
+	 * via scanning.
+	 * <p>
+	 * The module {@code hibernate-scan-jandex} must be added as a dependency,
+	 * or some other implementation of the service
+	 * {@link org.hibernate.boot.archive.scan.spi.ScannerFactory} must be made
+	 * available.
+	 *
+	 * @param name the name of the persistence unit, which may be used by
+	 * the persistence provider for logging and error reporting
+	 * @param classFromRootUrl a class loaded from the root URL of the
+	 * persistence unit
+	 *
+	 * @since 7.1
+	 */
+	public HibernatePersistenceConfiguration(String name, Class<?> classFromRootUrl) {
+		this( name, classFromRootUrl.getProtectionDomain().getCodeSource().getLocation() );
+	}
+
 	/**
 	 * Create a new {@link SessionFactory} based on this configuration.
 	 */
@@ -464,7 +516,7 @@ public HibernatePersistenceConfiguration managedClasses(Collection<Class<?>> man
 	/**
 	 * Add the specified resource names as {@linkplain #mappingFiles() mapping files}.
 	 *
-	 * @see #mappingFiles
+	 * @see #mappingFiles()
 	 */
 	public HibernatePersistenceConfiguration mappingFiles(String... names) {
 		Collections.addAll( mappingFiles(), names );
@@ -474,13 +526,43 @@ public HibernatePersistenceConfiguration mappingFiles(String... names) {
 	/**
 	 * Add the specified resource names as {@linkplain #mappingFiles() mapping files}.
 	 *
-	 * @see #mappingFiles
+	 * @see #mappingFiles()
 	 */
 	public HibernatePersistenceConfiguration mappingFiles(Collection<String> names) {
 		mappingFiles().addAll( names );
 		return this;
 	}
 
+	/**
+	 * Add the specified URL as a {@linkplain #jarFileUrls() JAR file}.
+	 *
+	 * @see #jarFileUrls()
+	 */
+	public HibernatePersistenceConfiguration jarFileUrl(URL url) {
+		jarFileUrls.add( url );
+		return this;
+	}
+
+	/**
+	 * Add the specified URLs as {@linkplain #jarFileUrls() JAR files}.
+	 *
+	 * @see #jarFileUrls()
+	 */
+	public HibernatePersistenceConfiguration jarFileUrls(URL... urls) {
+		Collections.addAll( jarFileUrls, urls );
+		return this;
+	}
+
+	/**
+	 * Add the specified URLs as {@linkplain #jarFileUrls() JAR files}.
+	 *
+	 * @see #jarFileUrls()
+	 */
+	public HibernatePersistenceConfiguration jarFileUrls(Collection<URL> urls) {
+		jarFileUrls.addAll( urls );
+		return this;
+	}
+
 	/**
 	 * Specify the {@linkplain Action action} to take in terms of automatic
 	 * database schema tooling.
@@ -549,4 +631,32 @@ public HibernatePersistenceConfiguration property(String name, Object value) {
 	public HibernatePersistenceConfiguration properties(Map<String, ?> properties) {
 		return (HibernatePersistenceConfiguration) super.properties( properties );
 	}
+
+	/**
+	 * URLs of JAR files.
+	 * When {@linkplain org.hibernate.cfg.PersistenceSettings#SCANNER_DISCOVERY
+	 * entity discovery} is enabled, the JAR files will be scanned for entities.
+	 *
+	 * @see org.hibernate.cfg.PersistenceSettings#SCANNER_DISCOVERY
+	 * @see jakarta.persistence.spi.PersistenceUnitInfo#getJarFileUrls
+	 *
+	 * @since 7.1
+	 */
+	public List<URL> jarFileUrls() {
+		return jarFileUrls;
+	}
+
+	/**
+	 * Root URL of the persistence unit.
+	 * When {@linkplain org.hibernate.cfg.PersistenceSettings#SCANNER_DISCOVERY
+	 * entity discovery} is enabled, this root URL will be scanned for entities.
+	 *
+	 * @see org.hibernate.cfg.PersistenceSettings#SCANNER_DISCOVERY
+	 * @see jakarta.persistence.spi.PersistenceUnitInfo#getPersistenceUnitRootUrl
+	 *
+	 * @since 7.1
+	 */
+	public URL rootUrl() {
+		return rootUrl;
+	}
 }

hibernate-core/src/main/java/org/hibernate/jpa/boot/spi/PersistenceConfigurationDescriptor.java

@@ -4,8 +4,6 @@
  */
 package org.hibernate.jpa.boot.spi;
 
-import java.io.File;
-import java.net.MalformedURLException;
 import java.net.URL;
 import java.util.List;
 import java.util.Properties;
@@ -14,6 +12,7 @@
 import org.hibernate.bytecode.spi.ClassTransformer;
 import org.hibernate.cfg.AvailableSettings;
 import org.hibernate.internal.util.collections.CollectionHelper;
+import org.hibernate.jpa.HibernatePersistenceConfiguration;
 import org.hibernate.jpa.HibernatePersistenceProvider;
 
 import jakarta.persistence.PersistenceConfiguration;
@@ -61,8 +60,9 @@ public boolean isUseQuotedIdentifiers() {
 
 	@Override
 	public boolean isExcludeUnlistedClasses() {
-		// because we do not know the root url nor jar files we cannot do scanning
-		return true;
+		// if we do not know the root url nor jar files we cannot do scanning
+		return !(persistenceConfiguration instanceof HibernatePersistenceConfiguration configuration)
+			|| configuration.rootUrl() == null && configuration.jarFileUrls().isEmpty();
 	}
 
 	@Override @SuppressWarnings("removal")
@@ -127,18 +127,15 @@ public ClassTransformer getClassTransformer() {
 
 	@Override
 	public URL getPersistenceUnitRootUrl() {
-		// When hibernate.archive.autodetection=class
-		// scan the CWD for entities (useful for tests)
-		try {
-			return new File( System.getProperty("user.dir") ).toURI().toURL();
-		}
-		catch ( MalformedURLException e ) {
-			return null;
-		}
+		return persistenceConfiguration instanceof HibernatePersistenceConfiguration configuration
+				? configuration.rootUrl()
+				: null;
 	}
 
 	@Override
 	public List<URL> getJarFileUrls() {
-		return null;
+		return persistenceConfiguration instanceof HibernatePersistenceConfiguration configuration
+				? configuration.jarFileUrls()
+				: null;
 	}
 }

hibernate-scan-jandex/src/main/java/org/hibernate/archive/scan/spi/AbstractScannerImpl.java

@@ -6,6 +6,7 @@
 
 import java.net.URL;
 import java.util.HashMap;
+import java.util.List;
 import java.util.Map;
 
 import org.hibernate.archive.scan.internal.NoopEntryHandler;
@@ -37,18 +38,19 @@ protected AbstractScannerImpl(ArchiveDescriptorFactory archiveDescriptorFactory)
 	public ScanResult scan(ScanEnvironment environment, ScanOptions options, ScanParameters parameters) {
 		final ScanResultCollector collector = new ScanResultCollector( environment, options, parameters );
 
-		if ( environment.getNonRootUrls() != null ) {
+		final List<URL> nonRootUrls = environment.getNonRootUrls();
+		if ( nonRootUrls != null ) {
 			final ArchiveContext context = new ArchiveContextImpl( false, collector );
-			for ( URL url : environment.getNonRootUrls() ) {
-				final ArchiveDescriptor descriptor = buildArchiveDescriptor( url, environment, false );
-				descriptor.visitArchive( context );
+			for ( URL url : nonRootUrls ) {
+				buildArchiveDescriptor( url, environment, false )
+						.visitArchive( context );
 			}
 		}
 
-		if ( environment.getRootUrl() != null ) {
-			final ArchiveContext context = new ArchiveContextImpl( true, collector );
-			final ArchiveDescriptor descriptor = buildArchiveDescriptor( environment.getRootUrl(), environment, true );
-			descriptor.visitArchive( context );
+		final URL rootUrl = environment.getRootUrl();
+		if ( rootUrl != null ) {
+			buildArchiveDescriptor( rootUrl, environment, true )
+					.visitArchive( new ArchiveContextImpl( true, collector ) );
 		}
 
 		return collector.toScanResult();
@@ -62,14 +64,11 @@ private ArchiveDescriptor buildArchiveDescriptor(
 		final ArchiveDescriptor descriptor;
 		final ArchiveDescriptorInfo descriptorInfo = archiveDescriptorCache.get( url );
 		if ( descriptorInfo == null ) {
-			if ( !isRootUrl && archiveDescriptorFactory instanceof JarFileEntryUrlAdjuster ) {
-				url = ( (JarFileEntryUrlAdjuster) archiveDescriptorFactory ).adjustJarFileEntryUrl( url, environment.getRootUrl() );
+			if ( !isRootUrl && archiveDescriptorFactory instanceof JarFileEntryUrlAdjuster jarFileEntryUrlAdjuster ) {
+				url = jarFileEntryUrlAdjuster.adjustJarFileEntryUrl( url, environment.getRootUrl() );
 			}
 			descriptor = archiveDescriptorFactory.buildArchiveDescriptor( url );
-			archiveDescriptorCache.put(
-					url,
-					new ArchiveDescriptorInfo( descriptor, isRootUrl )
-			);
+			archiveDescriptorCache.put( url, new ArchiveDescriptorInfo( descriptor, isRootUrl ) );
 		}
 		else {
 			validateReuse( descriptorInfo, isRootUrl );