annotations for static query options

[gavinking]

In #780 we added @StaticQuery, @StaticNativeQuery, @ReadQueryOptions, @WriteQueryOptions.

Everyone was very happy with the @ReadQueryOptions and @WriteQueryOptions annotations, and @sebersole especially expressed enthusiasm about it.

At risk of making something good worse, I'm going to propose an alternative design that is a bit more consistent with the direction we've gone with annotation design in Jakarta Data.

Essentially the point is this: over time, Java APIs have moved away from using complex structured annotations toward simpler annotations with at most one member. CDI was I guess the first spec to go down that path, but it's not the only one. @StaticQuery, @StaticNativeQuery are like that now; they only have a value member. (Happy, @otaviojava?)

But @ReadQueryOptions in particular is more of the old style annotation from an earlier period. That's OK, most of the annotations in JPA have quite a lot of members. And it does arguably make options more discoverable.

However, we should at least consider an alternative, which would be to separate this stuff into smaller annotations:

• @Caching(store=BYPASS, retrieve=BYPASS)
• @QueryTimeout(1000)
• @Lock(level=PESSIMISTIC_READ)
• @QueryHint(name="com.example.persistence.hint", value="👻")
• @NamedEntityGraph(name=Customer_.GRAPH_WITH_ORDERS)

That would be 3 new annotations instead of 2 because:

• we could reuse the existing @NamedEntityGraph annotation, allowing it to specify a graph by reference or in the usual way, and
• we can reuse @QueryHint even more easily, just by giving it @Target(METHOD) and making it repeatable.

I dunno if this design is better or worse. I think it's a bit nicer for specifying timeouts and query hints, but not hugely better for the others.

Anyway, I would like to hear feedback from others.

There's no particular urgency on this one.

[gavinking]

A different possible change: even if we don't do the thing proposed above, we might want to rename these annotations @QueryOptions and @StatementOptions. After M1 I mean.

[sebersole]

In general I do really prefer more granular approaches.

But here I'm just not seeing it. What does the aggregation of this information look like? My biggest uncertainty is the fact that the named-query annotations are repeatable - how do you "link" these to the query they describe? Matched names? (barf).

@Entity
@NamedQuery(name="byLastName", query="...")
@NamedQuery(name="byAge", query="...")
class Person { ... }

How would I apply something like @Lock(level=PESSIMISTIC_READ) to affect the byLastName query?

[gavinking]

@sebersole @ReadQueryOptions and @WriteQueryOptions are not for use with @NamedQuery and @NamedStatement. They are for use with @StaticQuery and @StaticNativeQuery, which is not repeatable.

But yeah, you might be right, I might be overfitting on the "granular annotations" thing.

[gavinking]

So in #933 I proposed renaming @ReadQueryOptions and @WriteQueryOptions to @TypedQueryOptions and @StatementOptions to align with the new Statement/TypedQuery split in JPA4.

@njr-11 has pointed out that while this change is very natural for people using JPA directly, it's much less natural for a user of Jakarta Data (which is the user we're most focussed on here).

So that motivated me to take a second look at what I originally proposed here (lots of little granular annotations).

I know @sebersole didn't love that direction, but I guess we now have a stronger motivation to reconsider it.

I might sit down later and mock up something more concrete so that you guys can think about it harder.

[gavinking]

I might sit down later and mock up something more concrete so that you guys can think about it harder.

After trying this out, I'm just not feelin it anymore. Closing this one.