Annotation Interface HQL
For example:
public interface Books { @HQL("where isbn = :isbn") Book findBookByIsbn(String isbn); @HQL("where title like ?1 order by title offset ?3 fetch first ?2 rows only") List<Book> findBooksByTitleWithPagination(String title, int max, int start); @HQL("select isbn, title, author.name from Book order by isbn") List<BookSummary> summarizeBooksWithPagination(Page page); @HQL("where title like ?1") TypedQuery<Book> createBooksByTitleQuery(String title); }
The Metamodel Generator automatically creates an "implementation"
of these methods in the static metamodel class Books_
.
The generated methods may be called according to the following
protocol:
Book book = Books_.findBookByIsbn(session, isbn); List<Book> books = Books_.findBooksByTitleWithPagination(session, pattern, 10, 0);
Notice the extra parameter of type EntityManager
at the
start of the parameter list.
Alternatively, the type to which the annotated method belongs may
also declare an abstract method with no parameters which returns
one of the types EntityManager
,
Session
,
StatelessSession
, or Mutiny.Session
,
for example:
EntityManager entityManager();In this case:
- the generated method is no longer
static
, - the generated method will use this method to obtain the
session object, instead of having a parameter of type
EntityManager
, and - the generated static metamodel class will actually implement
the type which declares the method annotated
@SQL
.
Thus, the generated methods may be called according to the following protocol:
Books books = new Books_(session); Book book = books.findBookByIsbn(isbn); List<Book> books = books.findBooksByTitleWithPagination(pattern, 10, 0);
This is reminiscent of traditional DAO-style repositories.
For a select
query, the return type of an annotated method
must be:
- an entity type, or
Optional<E>
whereE
is an entity type, List<E>
orStream<E>
whereE
is an entity type,List<Object[]>
orStream<Object[]>
- a record type or JavaBean class with a constructor signature
matching the types in the query
select
list, orList<R>
whereR
is such a type, io.smallrye.mutiny.Uni
, when used with Hibernate Reactive,Query
,SelectionQuery
,Query
, orTypedQuery
.
For an insert
, update
, or delete
query,
the return type of the annotated method must be int
,
boolean
, or void
.
The method parameters must match the parameters of the HQL query, either by name or by position:
- an ordinal query parameter of form
?n
is matched to the nth parameter of the method, and - a named query parameter of form
:name
is matched to the method parametername
.
As an exception, the method may have:
- a parameter of type
EntityManager
,Session
,StatelessSession
, orMutiny.Session
, - a parameter with type
Page
, and/or - a parameter with type
Order<? super E>
,List<Order<? super E>>
, orOrder<? super E>...
(varargs) whereE
is the entity type returned by the query.
For example:
@HQL("where title like :title) List<Book> findBooksByTitleWithPagination(String title, Page page, Order<Book> order);
As a further exception, a method might support key-based pagination. Then it must have:
- return type
KeyedResultList
, and - a parameter of type
KeyedPage
.
Queries specified using this annotation are always validated by
the Metamodel Generator, and so it isn't necessary to specify the
CheckHQL
annotation.
- Since:
- 6.3
- See Also:
- API Note:
- Instantiations with
select new
are not currently type-checked at build time, and so use of this syntax is not recommended. Nor, however, is this syntax necessary. Hibernate is able to automatically match the elements of theselect
list with a constructor of the method return type, which is much less verbose and just as type safe.
-
Required Element Summary
Required Elements
-
Element Details
-
value
String value
-