Annotation Interface JakartaQuery

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

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 {

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

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

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

     @JakartaQuery("delete from Trash")
     @QueryOptions(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.

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.

Any implementation of Jakarta Data backed by Jakarta Persistence must support the use of this annotation as a Jakarta Data query annotation. Thus, a repository method annotated @JakartaQuery is treated by the Jakarta Data provider as a query method, and an implementation of the method is supplied by the Jakarta Data provider.

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 agrees with the convention for Javadoc links, that is: the concatenation of the fully qualified name of the type, with the string #, the name of the annotated member, and the raw types of the method parameters, enclosed in parentheses and separated by commas, for example, "org.example.Library#findBooksByTitle(java.lang.String)".

The persistence provider must treat the annotation jakarta.data.repository.Query as a synonym for this annotation.

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.