[hibernate-dev] 6.0 - NativeQuery#getQueryReturns

[Steve Ebersole]

For 6.0 we need to address a few problems with this method.

First, although largely minor, is that we have an API contract returning
SPI references.

The larger concern is a side-effect of this method in terms of clearing
previous registered returns if new returns have been added since the
previous call (if one) to `#getQueryReturns`.  When any of the
`NativeQuery#addXYZ` methods are called, a "builder" is actually registered
under the covers.  When `#getQueryReturns` is called all previously
registered returns are cleared and the currently open builders are executed
and their generated returns are added to the internal (emptied) list.

If this were a clean-room impl I would just add a `#register`-style method
to those return builders and skip the whole queuing of the builders.  But
that is actually a very dangerous change to make now as it would mean that
existing apps using this API would still call `#addXYZ` but no returns
would actually be registered.

I guess the correct direction depends on whether this method is used and
for what purpose.  So first, anyone know of usages of these methods either
from applications or integrations?

The "safest" option is to:

   1. document this side-effect
   2. deprecate this method - it should go away, or be rethought

And we'd still have to consider the return types.  One option would be to
temporarily keep around the SPI forms (deprecated) and continue to return
those.  Ideally we'd retro-deprecate these SPI contracts and the method
back on 5.2 maintenance release and just drop them on 6.0[1].  Of course if
anything we know of is using this method, we would need the alternative.

Thoughts?  Opinions?  Suggestions?

[1] See my earlier `Continue to add 5.2 deprecations for 6.0 work?` message
to this list