Update the Javadoc of @Query after merge of JDQL

[gavinking]

This was now very out of date, and I forgot about it in #520.

Also caught some more instances of 'run time' -> 'runtime', 'life cycle' -> 'lifecycle'.

[gavinking]

@njr-11 These restrictions you're worried about made perfect sense when @Query was a generic annotation that could accommodate an open-ended list of languages: SQL, JPQL, etc.

But now the language is JDQL, which is syntactically trivial. Those restrictions no longer make any sense.

[gavinking]

But now the language is JDQL, which is syntactically trivial. Those restrictions no longer make any sense.

In 6041a62 and 0c81a33 I hereby propose simply remove them. :)

[njr-11]

But now the language is JDQL, which is syntactically trivial. Those restrictions no longer make any sense.

In 6041a62 and 0c81a33 I hereby propose simply remove them. :)

What we have written is that the language can be JDQL or JPQL. If a Jakarta Persistence-backed Jakarta Data provider is going to handle both, then the additional restrictions do matter.

[gavinking]

If a Jakarta Persistence-backed Jakarta Data provider is going to handle both, then the additional restrictions do matter.

Sure, but I really don't think it's placing an undue burden on a Jakarta Data provider which is backed by Jakarta Persistence to be able to understand JPQL if and only if that Jakarta Data provider voluntarily decides to also support arbitrary JPQL and pagination.

The spec does not place any requirement on such a provider to be able to support pagination with arbitrary JPQL, so if the provider disagrees with me, and thinks that being able to parse JPQL is a burden, then it is between the provider and the user to define how such extensions work.

All the spec requires is that the provider be able to handle JDQL.

[gavinking]

To be clear, what we say about this is:

A Jakarta Data provider is not required to support the complete JPQL language, which targets relational data stores.

and in the spec:

A Jakarta Data provider backed by access to a relational database might choose to allow the use of a much larger subset of JPQL—or even the whole language—via the @Query annotation. Such extensions are not required by this specification.

So we do not need to explicitly place limitations on JPQL support.

[gavinking]

@njr-11 Please see fa379ad, which makes this explicit.

[gavinking]

Force pushed to clean up commit history.

[njr-11]

In fact, the separate count() query is just no longer needed. That's one advantage of having our own query language!

I can certainly see the appeal of being able to get rid of the count query now that one can be assembled by replacing the SELECT clause and removing the ORDER BY clause from the primary query if using JDQL. I need to give this some more thought about where we end up with JPQL. It is certain that many users will opt for JPQL given that they are able to accomplish more with it, and we will want to be sure they aren't broken or consider themselves broken because there is no standard assuring them that pagination will still work.

[gavinking]

I need to give this some more thought about where we end up with JPQL.

FTR, the thing you would need to do with JPQL is replace everything between select and from with select count(1) from. This is easy in pure JPQL, since JPQL does not allow subqueries in the select clause.

Now, on the other hand, some providers, [i.e. Hibernate, but not, I believe, EclipseLink], do allow subqueries in select, and that makes the problem a bit more difficult. But that's not part of the spec and for multiple reasons not something you would need to implement support for.

[gavinking]

Note also, that Hibernate has a method that does this for you: SelectionQuery.getResultCount().

EclipseLink might also have something like that.

[gavinking]

FTR, the thing you would need to do with JPQL is replace everything between select and from with select count(1) from.

Oh yes, and remove order by, as you say. Also easy, since subqueries don't have order by clauses.

[otaviojava]

That might lead to a complex discussion, but using the self-continued principle and using JPQL as a sample, we are once again able to cross-database specification.

/**
 * <p>Annotates a repository method as a query method, specifying a query written in Jakarta Data Query Language (JDQL)
 * as the minimum requirement. This encourages the use of JDQL for cross-database compatibility. Additionally, a Jakarta Data
 * provider has the freedom to support extensions to the language, including features from the Jakarta Persistence Query Language (JPQL).
 * While providers are not required to support the complete JPQL language, which primarily targets relational data stores, they are
 * encouraged to provide as broad a support as possible to enhance the flexibility and power of data access queries.</p>
 */

[gavinking]

There's nothing wrong with what you just wrote, just not sure it's quite the right place to be saying things like that.

[otaviojava]

I put it here as a sample because it was the first paragraph. The point here is that the documentation leads to JDQL or JPQL.

However, it would be great to allow NoSQL to take advantage of this advantage.

For example:

• OrientDB query with SQL++, including Edge Operation.
• N1QL by Couchbase.

[gavinking]

OK I think I understand what you're looking for. Just not quite sure how to say it in a way which isn't out of place in the doc for that annotation. (It's the kind of thing that fits more comfortably in the spec or in module-info.

[gavinking]

@otaviojava please see 628abf4. Is that sorta approximately like what you would like to see?

[njr-11]

I think it will be acceptable to remove the counting query and have it be generated from the primary query and also to lift the restriction to have parenthesis around WHERE. The other restriction should not be removed.

[gavinking]

@njr-11 @otaviojava are there any remaining problems with this or is it OK to merge?

[njr-11]

@njr-11 @otaviojava are there any remaining problems with this or is it OK to merge?

I was only waiting to review the outcome of the conversation between you and Otavio, but the pull looks find as is so I can approve it. If more commits do get added, I'll try to remember to watch out for that and review them.

[gavinking]

Awesome!!

So according to me, JDQL is done and crossed off the list.