Undocumented breaking change in Quarkus Hibernate ORM 3.26

[svifred]

We are using Hibernate ORM extensively, and to avoid config errors impacting production, we have tied Quarkus Hibernate ORM extension to the service health check. The check is implemented by getting the EntityManagerFactory using JPAConfig.getEntityManagerFactory(persistenceUnit), and when the lib implementing the check:

1. is compiled with reference to Quarkus pre 3.26, and
2. included as a dependency in a project using Quarkus 3.26 and later

the check fails at runtime, as the signature of the getEntityManagerFactory method is changed by #48007 to include a second boolean parameter signifying reactivity of the persistence unit.

To us, this is a breaking change in the API of JPAConfig and thus in the Quarkus Hibernate ORM Extension, that is mentioned neither in the Quarkus 3.26 migration guide nor the release blog post (though the latter does reference #48007).

Is this a bug or an oversight? Or is the public JPAConfig class considered internal? Or something else entirely?

[sberyozkin]

Cc @yrodiere

[yrodiere]

Or is the public JPAConfig class considered internal?

Exactly this.

In general:

• Anything in the "base" package of a module is API. E.g. io.quarkus.hibernate.orm contains API classes.
• Anything in the "runtime" package of a module is internal, or at best aimed at consumption by other Quarkus (core) extensions. E.g. io.quarkus.hibernate.orm.runtime and all subpackages are internal.

If you think that's a confusing (to be polite) convention, I can't disagree. There are plans to improve the situation in the future: #48688

---

To solve your immediate problem, I would recommend that you retrieve persistence units via Arc.container().select(EntityManagerFactory.class).stream().toList() or (more advanced, if you use active/inactive PUs) Arc.container().select(EntityManagerFactory.class).listActive().

[svifred]

Thanks for clarifying, and I do agree, that the convention is less obvious then ideal. Having skimmed the ADR, I support the intention.

And thank you for providing a pointer for replacing the usage of the internal API in out code.

[dankristensen]

@yrodiere Do you have any suggestions on how we can get the actual PersistenceUnit's. Previously we got these from JPAConfig.getPersistenceUnits(), but since you say, that these are internal, do you have any suggestions to how we can get these?

We can easily change, so we are not using the createEntityManagerFactory from JPAConfig, by using what you have suggested.

[yrodiere]

@dankristensen I suppose you can iterate through the beans and look at their qualifiers?
We do something similar in Quarkus' own (internal) code for datasources:

quarkus/extensions/agroal/runtime/src/main/java/io/quarkus/agroal/runtime/AgroalDataSourceUtil.java

Lines 35 to 56 in d0c635f

	public static Set<String> activeDataSourceNames() {
	Set<String> activeNames = new LinkedHashSet<>();
	for (var handle : Arc.container().select(AgroalDataSource.class).handles()) {
	var bean = handle.getBean();
	if (bean != null && bean.isActive()) {
	String name = dataSourceName(bean);
	if (name != null) { // There may be custom beans, these will have a null name and will be ignored.
	activeNames.add(name);
	}
	}
	}
	return activeNames;
	}
	public static String dataSourceName(Bean<? extends javax.sql.DataSource> bean) {
	for (Object qualifier : bean.getQualifiers()) {
	if (qualifier instanceof DataSource) {
	return ((DataSource) qualifier).value();
	}
	}
	return DataSourceUtil.DEFAULT_DATASOURCE_NAME;
	}

Of course the qualifier would be io.quarkus.hibernate.orm.PersistenceUnit instead of DataSource here, but you get the idea.