Prototype bootstrapping for ORM 9 based on this work

- More work on bootstrapping orchestration

Author: sebersole

design/orm-bootstrap-direction.adoc

@@ -48,6 +48,7 @@ The intended flow is:
 ----
 PersistenceUnitDescriptor / HibernatePersistenceConfiguration
     -> JpaBootstrapSourceCollector
+    -> BootstrapSourceContributions
     -> AvailableResources
     -> DomainModelCategorizer
     -> BindingCoordinator
@@ -89,7 +90,7 @@ Inputs:
 
 Output:
 
-* raw source contributions, not yet categorized
+* `BootstrapSourceContributions`: source contributions after entry-point source discovery, including scanner results, not yet categorized
 
 == AvailableResources
 

design/session-factory-bootstrap-plan.adoc

@@ -265,20 +265,26 @@ The first orchestration shell is:
 * link:../src/main/java/org/hibernate/boot/orchestration/SessionFactoryBootstrap.java[`SessionFactoryBootstrap`]
 * link:../src/main/java/org/hibernate/boot/orchestration/SessionFactoryBootstrapRequest.java[`SessionFactoryBootstrapRequest`]
 
-The request is intentionally narrow for now:
+The request is intentionally early-input oriented for now:
 
 [source,java]
 ----
 record SessionFactoryBootstrapRequest(
-        AvailableResources availableResources,
-        MetadataBuildingContext metadataBuildingContext)
+        BootstrapSourceContributions sourceContributions,
+        Map<String, Object> configurationValues,
+        boolean jpaBootstrap,
+        FetchType defaultToOneFetchType,
+        ServiceRegistry serviceRegistry)
 ----
 
 `SessionFactoryBootstrap#buildMetadata` currently owns the phase order:
 
 [source]
 ----
-AvailableResources
+BootstrapSourceContributions + configuration values + ServiceRegistry
+    -> ResolvedBootstrapSettings
+    -> MetadataBuildingContext
+    -> AvailableResources
     -> DomainModelCategorizer
     -> BindingCoordinator
     -> order columns

src/main/java/org/hibernate/boot/models/source/AvailableResources.java

@@ -11,6 +11,7 @@
 import java.util.Collection;
 import java.util.Collections;
 import java.util.List;
+import java.util.Map;
 
 import jakarta.persistence.PersistenceConfiguration;
 import org.checkerframework.checker.nullness.qual.NonNull;
@@ -20,13 +21,11 @@
 import org.hibernate.boot.jaxb.internal.MappingBinder;
 import org.hibernate.boot.jaxb.spi.Binding;
 import org.hibernate.boot.jaxb.spi.JaxbBindableMappingDescriptor;
-import org.hibernate.boot.scan.spi.ScanningResult;
 import org.hibernate.boot.settings.BootstrapSettingsResolver;
 import org.hibernate.boot.settings.ResolvedBootstrapSettings;
 import org.hibernate.internal.util.StringHelper;
 import org.hibernate.jpa.HibernatePersistenceConfiguration;
 import org.hibernate.jpa.boot.spi.PersistenceUnitDescriptor;
-import org.hibernate.models.spi.ModelsContext;
 import org.hibernate.models.spi.ClassDetails;
 
 /// Model resources available to categorization.
@@ -77,6 +76,27 @@ public Collection<Binding<? extends JaxbBindableMappingDescriptor>> xmlMappings(
 	public static AvailableResources from(
 			PersistenceUnitDescriptor persistenceUnitDescriptor,
 			AvailableResourcesContext context) {
+		return from(
+				persistenceUnitDescriptor,
+				context,
+				new BootstrapSettingsResolver().resolve( persistenceUnitDescriptor, Map.of() )
+		);
+	}
+
+	/// Creates available resources from Hibernate's descriptor for persistence-unit
+	/// information.
+	///
+	/// Managed class names are resolved through the supplied model context. Mapping
+	/// file names are located through the bootstrap class-loading service and bound
+	/// immediately when XML mappings are enabled.
+	///
+	/// @param persistenceUnitDescriptor The persistence-unit wrapper
+	/// @param context Context used to resolve model details and load resources
+	/// @param bootstrapSettings Resolved bootstrap settings used during source collection
+	public static AvailableResources from(
+			PersistenceUnitDescriptor persistenceUnitDescriptor,
+			AvailableResourcesContext context,
+			ResolvedBootstrapSettings bootstrapSettings) {
 		var classLoading = context.getClassLoaderService();
 		var classDetailsRegistry = context.modelsContext().getClassDetailsRegistry();
 
@@ -93,7 +113,8 @@ public static AvailableResources from(
 		} );
 
 		final List<Binding<? extends JaxbBindableMappingDescriptor>> xmlBindings;
-		if ( persistenceUnitDescriptor.getMappingFileNames().isEmpty() ) {
+		if ( !bootstrapSettings.mappingSettings().xmlMappingEnabled()
+				|| persistenceUnitDescriptor.getMappingFileNames().isEmpty() ) {
 			xmlBindings = Collections.emptyList();
 		}
 		else {
@@ -119,9 +140,9 @@ public static AvailableResources from(
 	/// Creates available resources from Hibernate's JPA
 	/// {@link HibernatePersistenceConfiguration} extension.
 	///
-	/// Explicit managed classes and mapping files are included.  Archive scanning is
-	/// applied here based on [HibernatePersistenceConfiguration#rootUrl()] and
-	/// [HibernatePersistenceConfiguration#jarFileUrls()].
+	/// The configuration is first adapted to [BootstrapSourceContributions], which
+	/// includes archive scanning based on [HibernatePersistenceConfiguration#rootUrl()]
+	/// and [HibernatePersistenceConfiguration#jarFileUrls()].
 	///
 	/// @param persistenceConfiguration The PersistenceConfiguration
 	/// @param context Context used to resolve model details and load resources
@@ -138,9 +159,9 @@ public static AvailableResources from(
 	/// Creates available resources from Hibernate's JPA
 	/// {@link HibernatePersistenceConfiguration} extension.
 	///
-	/// Explicit managed classes and mapping files are included.  Archive scanning is
-	/// applied here based on [HibernatePersistenceConfiguration#rootUrl()] and
-	/// [HibernatePersistenceConfiguration#jarFileUrls()].
+	/// The configuration is first adapted to [BootstrapSourceContributions], which
+	/// includes archive scanning based on [HibernatePersistenceConfiguration#rootUrl()]
+	/// and [HibernatePersistenceConfiguration#jarFileUrls()].
 	///
 	/// @param persistenceConfiguration The PersistenceConfiguration
 	/// @param context Context used to resolve model details and load resources
@@ -149,45 +170,75 @@ public static AvailableResources from(
 			HibernatePersistenceConfiguration persistenceConfiguration,
 			AvailableResourcesContext context,
 			ResolvedBootstrapSettings bootstrapSettings) {
+		return from(
+				BootstrapSourceContributions.from(
+						persistenceConfiguration,
+						bootstrapSettings,
+						context.getClassLoaderService()
+				),
+				context,
+				bootstrapSettings
+		);
+	}
+
+	/// Creates available resources from neutral bootstrap source contributions.
+	///
+	/// Explicit and discovered managed classes, package metadata, and mapping files
+	/// are included.  Source discovery, including archive scanning, is expected to
+	/// have already happened before these contributions are consumed.
+	///
+	/// @param sourceContributions Source declarations from a bootstrap entry point
+	/// @param context Context used to resolve model details and load resources
+	/// @param bootstrapSettings Resolved bootstrap settings used during source collection
+	public static AvailableResources from(
+			BootstrapSourceContributions sourceContributions,
+			AvailableResourcesContext context,
+			ResolvedBootstrapSettings bootstrapSettings) {
 		final var classLoading = context.getClassLoaderService();
 		final var classDetailsRegistry = context.modelsContext().getClassDetailsRegistry();
 		final var mappingFileBinder = context.createMappingBinder();
 
 		var managedClassDetails = new ArrayList<ClassDetails>();
 		var packageDetailsList = new ArrayList<ClassDetails>();
-		persistenceConfiguration.managedClasses().forEach( (managedClass) -> {
+		sourceContributions.managedClasses().forEach( (managedClass) -> {
 			applyClassDetails(
 					classDetailsRegistry.resolveClassDetails( managedClass.getName() ),
 					managedClassDetails,
 					packageDetailsList
 			);
 		} );
-
-		final ScanningResult scanningResult = HibernatePersistenceConfigurationScanner.performScanning(
-				persistenceConfiguration,
-				bootstrapSettings,
-				classLoading
-		);
-		applyDiscoveredClassDetails(
-				scanningResult,
-				context.modelsContext(),
-				managedClassDetails,
-				packageDetailsList
-		);
+		sourceContributions.managedClassNames().forEach( (managedClassName) -> {
+			applyClassDetails(
+					classDetailsRegistry.resolveClassDetails( managedClassName ),
+					managedClassDetails,
+					packageDetailsList
+			);
+		} );
+		sourceContributions.packageNames().forEach( (packageName) -> {
+			applyClassDetails(
+					classDetailsRegistry.resolveClassDetails( packageName + ".package-info" ),
+					managedClassDetails,
+					packageDetailsList
+			);
+		} );
 
 		final var xmlBindings = new ArrayList<Binding<? extends JaxbBindableMappingDescriptor>>();
-		persistenceConfiguration.mappingFiles().forEach( (mappingFile) -> {
-			try (var mappingFileStream = classLoading.locateResourceStream( mappingFile )) {
-				xmlBindings.add( mappingFileBinder.bind(
-						mappingFileStream,
-						new Origin( SourceType.RESOURCE, mappingFile )
-				) );
-			}
-			catch (IOException e) {
-				throw new RuntimeException( "Error accessing mapping file - " + mappingFile, e );
-			}
-		} );
-		applyDiscoveredXmlMappings( scanningResult, mappingFileBinder, xmlBindings );
+		if ( bootstrapSettings.mappingSettings().xmlMappingEnabled() ) {
+			sourceContributions.mappingFiles().forEach( (mappingFile) -> {
+				try (var mappingFileStream = classLoading.locateResourceStream( mappingFile )) {
+					xmlBindings.add( mappingFileBinder.bind(
+							mappingFileStream,
+							new Origin( SourceType.RESOURCE, mappingFile )
+					) );
+				}
+				catch (IOException e) {
+					throw new RuntimeException( "Error accessing mapping file - " + mappingFile, e );
+				}
+			} );
+			sourceContributions.mappingFileUris().forEach( (mappingFileUri) -> {
+				xmlBindings.add( bindMappingFile( mappingFileUri, mappingFileBinder ) );
+			} );
+		}
 
 		return new AvailableResources( managedClassDetails, packageDetailsList, xmlBindings );
 	}
@@ -302,37 +353,6 @@ else if ( classDetails.getClassName().endsWith( "package-info" ) ) {
 		}
 	}
 
-	private static void applyDiscoveredClassDetails(
-			ScanningResult scanningResult,
-			ModelsContext modelsContext,
-			Collection<ClassDetails> managedClassDetails,
-			Collection<ClassDetails> packageDetailsList) {
-		var classDetailsRegistry = modelsContext.getClassDetailsRegistry();
-		scanningResult.discoveredClasses().forEach( (className) -> {
-			applyClassDetails(
-					classDetailsRegistry.resolveClassDetails( className ),
-					managedClassDetails,
-					packageDetailsList
-			);
-		} );
-		scanningResult.discoveredPackages().forEach( (packageName) -> {
-			applyClassDetails(
-					classDetailsRegistry.resolveClassDetails( packageName + ".package-info" ),
-					managedClassDetails,
-					packageDetailsList
-			);
-		} );
-	}
-
-	private static void applyDiscoveredXmlMappings(
-			ScanningResult scanningResult,
-			MappingBinder mappingFileBinder,
-			Collection<Binding<? extends JaxbBindableMappingDescriptor>> xmlBindings) {
-		scanningResult.mappingFiles().forEach( (mappingFile) -> {
-			xmlBindings.add( bindMappingFile( mappingFile, mappingFileBinder ) );
-		} );
-	}
-
 	private static Binding<? extends JaxbBindableMappingDescriptor> bindMappingFile(
 			URI mappingFile,
 			MappingBinder mappingFileBinder) {

src/main/java/org/hibernate/boot/models/source/BootstrapSourceContributions.java

@@ -0,0 +1,90 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.boot.models.source;
+
+import java.net.URI;
+import java.util.Collection;
+import java.util.List;
+
+import org.hibernate.boot.registry.classloading.spi.ClassLoaderService;
+import org.hibernate.boot.scan.spi.ScanningResult;
+import org.hibernate.boot.settings.ResolvedBootstrapSettings;
+import org.hibernate.jpa.HibernatePersistenceConfiguration;
+
+/// Mapping-source contributions collected from a bootstrap entry point.
+///
+/// This type intentionally carries source declarations only: managed classes,
+/// discovered class and package names, and XML mappings.  Settings resolution
+/// remains a separate concern handled by the orchestration layer, and scanning is
+/// performed by entry-point adapters before this descriptor is consumed.
+///
+/// @author Steve Ebersole
+public record BootstrapSourceContributions(
+		/// Managed Java classes explicitly contributed by the entry point.
+		List<Class<?>> managedClasses,
+
+		/// Managed Java class names discovered or explicitly contributed without
+		/// loading the class.
+		List<String> managedClassNames,
+
+		/// Package names discovered or explicitly contributed for package-level
+		/// metadata.
+		List<String> packageNames,
+
+		/// XML mapping resources explicitly contributed by the entry point.
+		List<String> mappingFiles,
+
+		/// XML mapping files discovered during archive scanning.
+		List<URI> mappingFileUris) {
+
+	public BootstrapSourceContributions {
+		managedClasses = managedClasses == null ? List.of() : List.copyOf( managedClasses );
+		managedClassNames = managedClassNames == null ? List.of() : List.copyOf( managedClassNames );
+		packageNames = packageNames == null ? List.of() : List.copyOf( packageNames );
+		mappingFiles = mappingFiles == null ? List.of() : List.copyOf( mappingFiles );
+		mappingFileUris = mappingFileUris == null ? List.of() : List.copyOf( mappingFileUris );
+	}
+
+	public BootstrapSourceContributions(
+			Collection<Class<?>> managedClasses,
+			Collection<String> mappingFiles) {
+		this( managedClasses, List.of(), List.of(), mappingFiles, List.of() );
+	}
+
+	public BootstrapSourceContributions(
+			Collection<Class<?>> managedClasses,
+			Collection<String> managedClassNames,
+			Collection<String> packageNames,
+			Collection<String> mappingFiles,
+			Collection<URI> mappingFileUris) {
+		this(
+				managedClasses == null ? List.of() : List.copyOf( managedClasses ),
+				managedClassNames == null ? List.of() : List.copyOf( managedClassNames ),
+				packageNames == null ? List.of() : List.copyOf( packageNames ),
+				mappingFiles == null ? List.of() : List.copyOf( mappingFiles ),
+				mappingFileUris == null ? List.of() : List.copyOf( mappingFileUris )
+		);
+	}
+
+	/// Adapts Hibernate's programmatic JPA bootstrap configuration to neutral
+	/// source contributions, including archive scanning.
+	public static BootstrapSourceContributions from(
+			HibernatePersistenceConfiguration persistenceConfiguration,
+			ResolvedBootstrapSettings bootstrapSettings,
+			ClassLoaderService classLoaderService) {
+		final ScanningResult scanningResult = HibernatePersistenceConfigurationScanner.performScanning(
+				persistenceConfiguration,
+				bootstrapSettings,
+				classLoaderService
+		);
+		return new BootstrapSourceContributions(
+				persistenceConfiguration.managedClasses(),
+				scanningResult.discoveredClasses(),
+				scanningResult.discoveredPackages(),
+				persistenceConfiguration.mappingFiles(),
+				scanningResult.mappingFiles()
+		);
+	}
+}