Persistence & cache boundaries
Keep class replacement, ORM mapping, database schema and cached results separate when verifying a reload.
Four things to check separately
- Bytecode: did the class change in the JVM?
- Mapping: does the persistence unit recognize the new shape?
- Schema: does the database have the required table/column?
- Consumers: are the repositories, EntityManagers and caches using the intended state?
Success at one layer is not proof of all four. The JVM staying alive says nothing by itself about open database work surviving a persistence-unit rebuild.
Existing JPA entities
Class method changes can reload without rebuilding every ORM mapping. A new field on an existing entity needs enhanced-redefinition visibility for the documented jpaRefresh=true mapping-refresh path. That option is false by default.
With supported DDL-enabled settings such as update/create/create-drop, rebuilding the persistence unit can perform the configured schema action. In other cases the agent identifies the field and required action; it does not silently turn validation into schema creation.
Old open persistence contexts are not retained across a successful rebuild. Finish active database work before triggering it. On a stock JVM, existing-entity field additions still need enhanced redefinition or restart for ORM mapping.
New entities with a prepared schema
A separate opt-in path supports a new entity on a stock JVM when the table is already prepared and the explicitly selected Hibernate mode is validate. Native validation checks the candidate before installing it; the path does not switch the mode to update/create.
The measured path uses one persistence unit, the standard LocalContainerEntityManagerFactoryBean and Hibernate provider. Missing tables/columns or incompatible column types leave the previous factory open before candidate installation.
After fixing the schema, compile a body-only edit to the pending entity to retry. Identical class bytes are normally ignored. Changing the pending declarations/mapping is refused: restore the mapping and make the body edit, or restart for the changed mapping.
Named evidence uses Spring ORM 6.1.14 / Hibernate 6.5.3.Final / H2 on stock JDK 21; a separate held-repository observer adds stock SapMachine 17/21 coverage. Multiple persistence units, custom providers/schema tools and automatic migrations are outside that acceptance.
Spring Data repositories and held references
The repository refresh path identifies actual Spring Data Repository types. A plain @Repository DAO follows ordinary bean refresh. Warm singleton repository products can be recreated and supported ordinary singleton fields repaired; cold factories are not eagerly initialized just to discover their type.
Query edits have scoped native SQL/JPQL observers. The scalar H2 native-query lane uses Data JPA 3.3.4 / Framework 6.1.14 / Hibernate 6.5.3.Final. It does not certify all database dialects, pagination, projections or newly added repository interface methods.
A separate prepared-schema observer retains an existing domain-root repository, shared EntityManager and client factory proxy through a new-entity mapping swap. It does not establish a repository whose own generic domain root becomes a newly added type.
Spring caches: follow observed dependencies
The stock companion path records watched classes executed through Spring’s synchronous cache interceptor and the actual cache instances. A helper edit can invalidate observed dependent regions, including outer caches that read a cached inner result. Regions with the same name in different managers/contexts stay distinct.
This is region-level, conservative dependency tracking. Unknown/incomplete history uses the documented fallback for annotated classes. Unwatched code, constructor/static initialization, excluded methods, pre-attach entries and async/reactive cache computations are not fully covered.
A computation overlapping reload can return its old result to its caller; exit invalidation prevents retaining it after a successful clear. Other threads may still observe the storage-to-exit interval. This is not a concurrent cache snapshot.
A custom cache needs an explicit owner
refreshOwnersOnHelper can name supported Spring singleton cache-owner classes to recreate after a helper reload. This rebuilds the owner through its ordinary lifecycle; it is not arbitrary cache discovery.
Non-singletons, FactoryBeans and event-listener owners are declined. Review recreation state loss and the owner allowlist before opting in.
Sources & version scope
Documentation source 1.4.0 · evidence baseline 75535bd · reviewed 19 October 2026. Check your installed artifact; source features may postdate a release.