HHH-16648 Documentation for implementing custom JPQL/HQL functions

[FelixDes]

I propose a technology for creating custom JPQL/HQL functions (code and documentation).

https://hibernate.atlassian.net/browse/HHH-16648

[hibernate-github-bot]

Thanks for your pull request!

This pull request does not follow the contribution rules. Could you have a look?

❌ All commit messages should start with a JIRA issue key matching pattern HHH-\d+
    ↳ Offending commits: [adc1885]
❌ The pull request description must contain the license agreement text.
    ↳ The description of this pull request must contain the following license agreement text:

----------------------
By submitting this pull request, I confirm that my contribution is made under the terms of the [Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0.txt)
and can be relicensed under the terms of the [LGPL v2.1 license](https://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt) in the future at the maintainers' discretion.
For more information on licensing, please check [here](https://github.com/hibernate/hibernate-orm/blob/main/CONTRIBUTING.md#legal).

----------------------

› This message was automatically generated.

[FelixDes]

I would appreciate feedback on the status of this pull request. Is the code being reviewed or rejected?

[beikov]

I'm sorry this takes so long. Your PR is very much appreciated and we will look into it. We are currently busy with other things. I added your PR to my todo list, so be assured that I will review it eventually.

[FelixDes]

Thank you very much!

[FelixDes]

Please let me know what needs to be fixed or added in my code for you to accept my pull request.

[gavinking]

I'm really not sure how much of an open invitation we really want to be giving to users to start depending on some of these SPIs in their application programs.

Yes, it's true that org.hibernate.sql.ast and org.hibernate.sql.ast.tree are technically SPIs, but they're both marked @Incubating for the very good reason that:

1. they're an extremely broad SPI surface, and
2. not really stabilized in any meaningful sense.

So I would leave this undocumented for now.

[yrodiere]

Let's close this and the Jira then.

I didn't find an issue about adding a proper API to define custom functions though. Should I create one, or is this not a feature we want to expose beyond an incubating SPI?

[gavinking]

I didn't find an issue about adding a proper API to define custom functions though.

I did have something at some stage.

[gavinking]

Should I create one

Yeah go ahead.

[sebersole]

The intent was always to allow users to contribute custom function definitions. It's just a question of getting the SPI correct.

[yrodiere]

Closing in favor of https://hibernate.atlassian.net/browse/HHH-19839 as mentioned above: we would need a more focused SPI before encouraging its use in applications.

[yrodiere]

Also, thank you for your contribution @FelixDes . We'll try to reuse this documentation when working on HHH-19839. If you're interested in working on that and debating what's the best way to expose it, please reach out on Zulip: https://hibernate.zulipchat.com/#narrow/channel/132094-hibernate-orm-dev