Skip to content

Commit e229e1d

Browse files
sebersolesebersole
committed
Prototype bootstrapping for ORM 9 based on this work
1 parent 8b9be22 commit e229e1d

2 files changed

Lines changed: 188 additions & 3 deletions

File tree

‎design/orm-bootstrap-direction.adoc‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
= ORM Bootstrap Direction
2+
3+
This note captures the proposed direction for using this PoC to replace and simplify large parts of ORM bootstrap,
4+
especially the JPA path through `EntityManagerFactoryBuilderImpl`.
5+
6+
== Current ORM Shape
7+
8+
From the JPA side, `EntityManagerFactoryBuilderImpl` currently handles several phases inline:
9+
10+
* Merge persistence-unit, integration, `hibernate.properties`, and cfg.xml settings into `MergedSettings`
11+
* Build the `BootstrapServiceRegistry`
12+
* Build the `StandardServiceRegistry`
13+
* Create `MetadataSources`
14+
* Push persistence-unit classes, packages, and XML into `MetadataSources`
15+
* Apply scanning results
16+
* Apply metadata-builder contributors and type/converter settings
17+
* Build `ManagedResources`
18+
* Later call `MetadataBuildingProcess.complete(...)`
19+
20+
`MetadataBuildingProcess.processManagedResources(...)` then unpacks `ManagedResources` into:
21+
22+
* XML preprocessing results
23+
* known class names
24+
* `ModelsContext`
25+
* global registrations
26+
* root entity, mapped-superclass, and embeddable categorization
27+
28+
This means `ManagedResources` acts as the historical source bundle, while this PoC's `AvailableResources`
29+
is the cleaner replacement candidate.
30+
31+
== Proposed Pipeline
32+
33+
Replace the current implicit sequence with explicit intermediate products:
34+
35+
[source]
36+
----
37+
JpaBootstrapSettings
38+
BootstrapSourceContributions
39+
AvailableResources
40+
CategorizedDomainModel
41+
BoundMetadata
42+
----
43+
44+
The intended flow is:
45+
46+
[source]
47+
----
48+
PersistenceUnitDescriptor / HibernatePersistenceConfiguration
49+
-> JpaBootstrapSourceCollector
50+
-> AvailableResources
51+
-> DomainModelCategorizer
52+
-> BindingCoordinator
53+
----
54+
55+
== Settings
56+
57+
Extract settings merge into a focused component, e.g. `JpaSettingsResolver` or `BootstrapSettingsResolver`.
58+
59+
Inputs:
60+
61+
* `PersistenceUnitDescriptor`
62+
* integration settings
63+
* cfg.xml
64+
* `HibernatePersistenceConfiguration`
65+
66+
Outputs:
67+
68+
* resolved settings map
69+
* cache region definitions
70+
* bootstrap flags such as XML enabled, scanner settings, and enhancement settings
71+
72+
Settings should remain separate from source resources.
73+
74+
== Source Discovery
75+
76+
Extract JPA source discovery from `EntityManagerFactoryBuilderImpl` and avoid routing through `MetadataSources`
77+
as the primary abstraction.
78+
79+
Inputs:
80+
81+
* persistence-unit class names
82+
* mapping file names
83+
* standard `META-INF/orm.xml`
84+
* explicit `HBM_XML_FILES`
85+
* scanner results
86+
* loaded classes
87+
* packages
88+
89+
Output:
90+
91+
* raw source contributions, not yet categorized
92+
93+
== AvailableResources
94+
95+
`AvailableResources` should be the normalized source model produced by source discovery.
96+
97+
It should contain:
98+
99+
* resolved `ClassDetails` for managed classes
100+
* resolved package-info `ClassDetails`
101+
* XML bindings
102+
* dynamic model names/classes if needed
103+
* possibly extra query imports, either directly or as a sibling object
104+
105+
It should not contain merged settings.
106+
107+
It should not simply clone `ManagedResources`. `ManagedResources` is raw-ish and historical, exposing class
108+
references, class names, package names, XML bindings, converter descriptors, and query imports. `AvailableResources`
109+
should be source-model oriented and normalized for categorization.
110+
111+
== XML Preprocessing
112+
113+
Move XML preprocessing behind `AvailableResources`.
114+
115+
The short-term adapter is acceptable:
116+
117+
[source]
118+
----
119+
AvailableResources -> ManagedResources adapter -> XmlPreProcessor
120+
----
121+
122+
The intended direction is direct consumption:
123+
124+
[source]
125+
----
126+
AvailableResources -> XmlPreProcessingResult
127+
----
128+
129+
== Categorization
130+
131+
Categorization should consume normalized resources:
132+
133+
[source]
134+
----
135+
AvailableResources + BootstrapContext -> CategorizedDomainModel
136+
----
137+
138+
This replaces the current ad hoc categorization work in `MetadataBuildingProcess.processManagedResources(...)`.
139+
140+
== Binding
141+
142+
Binding should consume categorized metadata and resolved bootstrap context:
143+
144+
[source]
145+
----
146+
CategorizedDomainModel + settings/defaults/global registrations -> ORM mapping model
147+
----
148+
149+
Binding should not need raw `MetadataSources` or raw `ManagedResources`.
150+
151+
== Next PoC Slice
152+
153+
Prototype this chain:
154+
155+
[source]
156+
----
157+
PersistenceUnitDescriptor / HibernatePersistenceConfiguration
158+
-> JpaBootstrapSourceCollector
159+
-> AvailableResources
160+
-> DomainModelCategorizer
161+
----
162+
163+
Do not wire binding yet.
164+
165+
The test target should be:
166+
167+
* Given JPA bootstrap inputs, the PoC derives the same available classes, packages, XML, and global registrations
168+
that ORM currently derives through `EntityManagerFactoryBuilderImpl` and `ManagedResources`
169+
170+
This establishes a clean replacement boundary before touching binder and persister integration.
171+

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

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
import java.util.Collections;
1111
import java.util.List;
1212

13+
import jakarta.persistence.PersistenceConfiguration;
1314
import org.hibernate.boot.jaxb.Origin;
1415
import org.hibernate.boot.jaxb.SourceType;
1516
import org.hibernate.boot.jaxb.internal.MappingBinder;
@@ -96,16 +97,29 @@ public static AvailableResources from(
9697
/// {@link HibernatePersistenceConfiguration} extension.
9798
///
9899
/// Explicit managed classes and mapping files are included. Discovery/scanning is
99-
/// not applied here.
100+
/// applied here based on [HibernatePersistenceConfiguration#rootUrl()] and
101+
/// [HibernatePersistenceConfiguration#jarFileUrls()].
100102
///
101103
/// @param persistenceConfiguration The PersistenceConfiguration
102104
/// @param metadataBuildingContext The bootstrap model building context
103105
public static AvailableResources from(
104106
HibernatePersistenceConfiguration persistenceConfiguration,
105107
MetadataBuildingContext metadataBuildingContext) {
108+
// todo : handle discovery/scanning here
109+
// for now though just assume no scanning
110+
return from( (PersistenceConfiguration) persistenceConfiguration, metadataBuildingContext );
111+
}
106112

107-
// todo : I think we need to handle discovery/scanning here
108-
113+
/// Creates available resources from JPA {@link PersistenceConfiguration}.
114+
///
115+
/// Explicit managed classes and mapping files are included. Discovery/scanning is
116+
/// not applied here.
117+
///
118+
/// @param persistenceConfiguration The PersistenceConfiguration
119+
/// @param metadataBuildingContext The bootstrap model building context
120+
public static AvailableResources from(
121+
PersistenceConfiguration persistenceConfiguration,
122+
MetadataBuildingContext metadataBuildingContext) {
109123
var bootstrapContext = metadataBuildingContext.getBootstrapContext();
110124
var classLoading = bootstrapContext.getClassLoaderService();
111125
var modelsContext = bootstrapContext.getModelsContext();

0 commit comments

Comments
 (0)