Annotation Interface StaticQuery

@Target(METHOD)
@Retention(RUNTIME)
public @interface StaticQuery

Specifies a query expressed in the Jakarta Persistence Query Language. This annotation may be applied to:

• any method of any class or interface belonging to the persistence unit, or
• a query method of a Jakarta Data repository with an implementation backed by Jakarta Persistence.

The return type of the method must agree with the type returned by the query. The parameter types of the method must agree with the types of the query parameters. An implementation of Jakarta Persistence or of Jakarta Data may be able to determine if such agreement exists at compilation time or when the persistence unit is initialized, but this is not required.

 interface Library {

     @StaticQuery("from Book where title like :title")
     @ReadQueryOptions(cacheStoreMode = CacheStoreMode.BYPASS)
     List<Book> findBooksByTitle(String title);

     @StaticQuery("from Book where isbn = :isbn")
     Book getBookWithIsbn(String isbn);

     record Summary(String title, String isbn, LocalDate date) {}
     @StaticQuery("""
         select title, isbn, pubDate
         from Book
         where title like = ?1 and pubDate > ?2
     """)
     List<Summary> retrieveSummaries(String title, LocalDate fromDate);

     @StaticQuery("delete from Trash")
     @WriteQueryOptions(timeout = 30_000)
     int emptyTrash();
 }

A method return type agrees with the type returned by a SELECT query if either:

• it is exactly R, List<R>, or Stream<R> for some result type R which is compatible with the query, according to the rules specified below, or
• the method is a Jakarta Data repository method, and its return type is a legal query method return type for the given query, as specified by Jakarta Data.

A result type R is considered compatible with a query if either:

1. the select list of the query contains only a single item, and the type of the item is assignable to the given result class, or
2. the result class is a non-abstract class or record type that has a constructor with the same number of parameters as the query has items in its select list, and the constructor parameter types exactly match the types of the corresponding items in the select list.

In the first case, each query result is returned directly to the caller. In the second case, each query result is automatically packaged in a new instance of the result class by calling the matching constructor.

A method return type agrees with the type returned by an UPDATE or DELETE statement if the return type is void, int, or long.

A method parameter type agrees with a query parameter type if it is a type that could be assigned to the corresponding query parameter by passing an instance of the type to setParameter(). In making this determination, method parameters are correlated with query parameters by position or by name, depending on whether the query uses positional or named parameters.

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.

List<Book> books =
        em.createQuery(Library_.findBooksByTitle("%Jakarta%"))
          .getResultList();

Book book =
        em.createQuery(Library_.getBookWithIsbn(isbn))
          .getSingleResult();

int deleted =
        em.createQuery(Library_.emptyTrash())
          .executeUpdate();

In addition, the query is treated as a named query, where the query name is the concatenation of the unqualified name of the type, with the string ".", and the name of the annotated member, for example, "Library.findBooksByTitle".

An implementation of Jakarta Data backed by Jakarta Persistence must treat this annotation as a Jakarta Data query annotation.

The parameter types of the annotated method must be basic types. If this annotation occurs on a generic method, on a method with a parameter type which is not a basic type, or on a method with a return type or parameter type involving a type variable, the behavior is undefined.

Since:

4.0

Required Element Summary

Required Elements

Modifier and Type	Required Element	Description
String	value	The query string in the Jakarta Persistence Query Language.

Element Details

value

String value

The query string in the Jakarta Persistence Query Language.