annotations for static queries usable in Jakarta Data

[gavinking]

Since:

1. allow @NamedQuery and @NamedNativeQuery more control over query execution #473 has run aground, and
2. it would be nice to have a similar capability to the one proposed in allow @NamedQuery and @NamedNativeQuery more control over query execution #473 for use with Jakarta Data,

we could consider adding some kind of replacement/alternative to @NamedQuery, with the following differences:

• The annotation could be placed at the method level
• The name would be optional
• There would be a full range of options like CacheXxxxModes, timeouts, etc.

That is, Jakarta Persistence would define its own "query annotation" in the sense of the Jakarta Data spec.

This is straightforward to add; the main barrier is that I have no idea what a reasonable name for this annotation would be. We can't call it @JPQL or @JpqlQuery or whatever because the query language isn't called that anymore. We can't call it @NamedQuery for multiple reasons. And we can't call it just @Query, also for multiple reasons. Nor does @EntityQuery work, since such queries are not required to return entities. I suppose @PersistenceQuery is available, but that's awful. The best option I've thought of so for is @QueryWithOptions or @QueryWithHints but ugghh.

Can anyone think of a reasonable name?

Now, an alternative solution, which works for Jakarta Data, but doesn't really help solve the need in #473 is that we could introduce a @QueryOptions or @QueryHints annotation that's meant to be used together with Jakarta Data's @Query. So you would write:

@Query("from Book")
@QueryOptions(cacheStoreMode = BYPASS)
List<Book> allBooks()

The problem is that this annotation is completely useless in Jakarta Persistence. It's only useful in Jakarta Data, which makes it an uncomfortable thing to have in this spec.

Note that this issue is very similar to #735.

[beikov]

How about @Select and @NativeSelect? As well as @Modification and @NativeModification? Maybe also something for stored procedures analogous to @NamedStoredProcedure?

I feel like the annotations are going to feel a little misplaced anyway, unless we come up with some way to specify that annotations shall be interpreted by an annotation processor or runtime.

[gavinking]

That is a great idea @beikov! Thanks

[gavinking]

So, here's an idea based on Christian's comments.

Let me know what y'all think of this:

/**
 * Specifies a query expressed in the Jakarta Persistence Query Language.
 * This annotation may be applied to any abstract method of any class or
 * interface belonging to the persistence unit, or to a method of a
 * Jakarta Data repository. The return type of the method must agree with
 * the type returned by the query.
 * {@snippet :
 * interface Library {
 *     @Select("from Book where title like :title")
 *     List<Book> findBooksByTitle(String title);
 *
 *     @Select("from Book where isbn = :isbn")
 *     Book getBookWithIsbn(String isbn);
 * }
 * }
 *
 * <p> When this annotation is applied to a method of a class or interface
 * belonging to the persistence unit, a reference to a query declared using
 * this annotation may be obtained from the static metamodel class of the
 * annotated class or interface. In addition, the query is treated as a
 * named query, where the query name is the name of the annotated method.
 * {@snippet :
 * List<Book> books =
 *         em.createQuery(Library_._findBooksByTitle_)
 *           .setParameter("title", "%Jakarta%")
 *           .getResultList();
 * }
 * {@snippet :
 * Book book =
 *         em.createQuery(Library_._getBookWithIsbn_)
 *           .setParameter("isbn", isbn)
 *           .getSingleResult();
 * }
 *
 * <p> An implementation of Jakarta Data backed by Jakarta Persistence
 * must treat this annotation as a Jakarta Data query annotation.
 *
 * @since 4.0
 */
@Target(METHOD)
@Retention(RUNTIME)
public @interface Select {

    /**
     * The query string in the Jakarta Persistence Query Language.
     */
    String query();

    /**
     * The lock mode type to use in query execution.
     * If a {@code lockMode} other than {@link LockModeType#NONE}
     * is specified, the query must be executed in a transaction
     * and the persistence context joined to the transaction.
     * @see Query#setLockMode
     */
    LockModeType lockMode() default LockModeType.NONE;

    /**
     * The {@linkplain CacheStoreMode cache store mode} to use.
     * @see Query#setCacheStoreMode
     */
    CacheStoreMode cacheStoreMode() default CacheStoreMode.USE;

    /**
     * The {@linkplain CacheRetrieveMode cache retrieve mode}
     * to use.
     * @see Query#setCacheRetrieveMode
     */
    CacheRetrieveMode cacheRetrieveMode() default CacheRetrieveMode.USE;

    /**
     * A query timeout in milliseconds.
     * By default, there is no timeout.
     * @see Query#setTimeout
     */
    int timeout() default -1;

    /**
     * Query properties and hints.
     * May include vendor-specific query hints.
     */
    QueryHint[] hints() default {};
}

cc @njr-11 @otaviojava

[beikov]

Maybe it's worth noting that the query shall be reflected as TypedQueryReference? We might also want to add @NamedSelect and @NamedModification. Another idea that popped into my mind is, that we could create a record class for the select tuple of named select queries. If we then also generate TypedQueryReference for named queries into the static metamodel, we could even type this appropriately.

[gavinking]

Maybe it's worth noting that the query shall be reflected as TypedQueryReference?

Yes, sure. But note that we'll also need to specify this stuff in the static metamodel section of the spec.

Another idea that popped into my mind is, that we could create a record class for the select tuple of named select queries.

Well this starts to bleed into #420. But I would say that the way this works is that you can have a hand-written record type as the return type of the method, and the results are auto-packaged into that record, as in Jakarta Data 1.1.

[njr-11]

There are some good ideas here. Another naming challenge is that Select is already an annotation of Jakarta Data, so choosing the same name would require fully qualified class names when both Select annotations are used on the same Jakarta Data repository.

I'll try to think of some possibilities for names.

Also, the example shows usage like this,

    @Select("from Book where title like :title")
    List<Book> findBooksByTitle(String title);

but the annotation has,

    String query();

These aren't consistent. The former would either need to be,

    @Select(query = "from Book where title like :title")
    List<Book> findBooksByTitle(String title);

or the latter would need to be,

    String value();

in which case usage with additional options would be,

    @Select(timeout = 60000,
            value = "from Book where title like :title")
    List<Book> findBooksByTitle(String title);

[njr-11]

We wouldn't necessarily need a separate annotation for native queries. The annotation could have a boolean field native = true/false where false is the default.

Regarding naming, I also thought of @MethodQuery.

[beikov]

I guess @ReadQuery or @SelectQuery might also be an option along with @MutationQuery or @ModificationQuery.

[gavinking]

@SelectQuery would be fine, it seems to me.

Select is already an annotation of Jakarta Data

I had forgotten that.

[otaviojava]

@SelectQuery would be fine, it seems to me.

Select is already an annotation of Jakarta Data

I had forgotten that.

I am not sure about this name.
Do you know if the goal is only to use select? Should we have UpdateQuery, InsertQuery
As an option, I would go to:

• @NativeQuery
• @RawQuery
• @sqlquery
• @SQL - To be honest, my favorite one.

[beikov]

If you read my previous comments @otaviojava, you will see that I also propose annotations for modification queries.
One of the big differences between select and modification queries is that cache and lock modes don't really make sense. I'm sure if we dig a bit, we will find other reasons for having distinct annotations.

[gavinking]

I guess @ReadQuery

Actually perhaps this is better. We could have @ReadQuery and @WriteQuery.

[gavinking]

One more comment on this: while I think it's a bit annoying to introduce four new annotations, such a design can be defended because:

• A @ReadQuery has cache interaction modes, a lockMode, and perhaps eventually an entity graph, but a @WriteQuery doesn't have any of those things.
• A @NativeReadQuery or @NativeWriteQuery can specify affectedTables or affectedEntities to influence AUTO-flushing, but a @ReadQuery or @WriteQuery never needs to.

So the four annotations aren't isomorphic.