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.