[hibernate-issues] [JIRA] (HHH-15650) clarify the API of org.hibernate.cfg and its subpackages

Gavin King ( https://hibernate.atlassian.net/secure/ViewProfile.jspa?accountId=557058%... ) *created* an issue Hibernate ORM ( https://hibernate.atlassian.net/browse/HHH?atlOrigin=eyJpIjoiMDA4Yjc2NTc0... ) / Improvement ( https://hibernate.atlassian.net/browse/HHH-15650?atlOrigin=eyJpIjoiMDA4Yj... ) HHH-15650 ( https://hibernate.atlassian.net/browse/HHH-15650?atlOrigin=eyJpIjoiMDA4Yj... ) clarify the API of org.hibernate.cfg and its subpackages ( https://hibernate.atlassian.net/browse/HHH-15650?atlOrigin=eyJpIjoiMDA4Yj... ) Issue Type: Improvement Assignee: Unassigned Components: hibernate-core Created: 31/Oct/2022 15:28 PM Priority: Major Reporter: Gavin King ( https://hibernate.atlassian.net/secure/ViewProfile.jspa?accountId=557058%... ) The package org.hibernate.cfg contains: * some older (but still useful) user-facing APIs like Configuration and AvailableSettings , * some deprecated things like NamingStrategy , along with * a bunch of very internal implementation code, and in particular, a portion of the code which is responsible for interpreting annotations. Now, to be clear, some of this internal code has absolutely no business being in this package, and should be in the subpackage org.hibernate.cfg.annotations , where it could have all been package-private. And precisely because it is used from the subpackage, a lot of it is declared public , even though it has certainly never formed part of the public API of Hibernate. We managed to clean up quite a few problems like this in 6.0, but we overlooked this one, partly because I think everyone was just so scared to even look at that code and try to understand it. Well, I’ve spent some time working with it now, and I do understand it, and I’ve even been able to clean it up quite a lot. But I think it’s very distracting to users to have to even see that code sitting there alongside things that really are public APIs. At the very least we need to explicitly mark the non-API classes as @Internal. Even better would be to actually move a bunch of stuff into a separate.internal package, while leaving a couple of stubs for backward compatibility, in cases where there’s any risk that existing programs might be using it directly. To be clear, the stuff I would move is going to break zero programs, since there’s simply no reasonable way a program could use these things directly. It’s merely a historical accident that this code was even accessible at all. ( https://hibernate.atlassian.net/browse/HHH-15650#add-comment?atlOrigin=ey... ) Add Comment ( https://hibernate.atlassian.net/browse/HHH-15650#add-comment?atlOrigin=ey... ) Get Jira notifications on your phone! Download the Jira Cloud app for Android ( https://play.google.com/store/apps/details?id=com.atlassian.android.jira.... ) or iOS ( https://itunes.apple.com/app/apple-store/id1006972087?pt=696495&ct=Em... ) This message was sent by Atlassian Jira (v1001.0.0-SNAPSHOT#100209- sha1:5956172 )