Movatterモバイル変換

@Target(METHOD)@Retention(CLASS)@Incubatingpublic @interfaceFind

Identifies a method of an abstract class or interface as defining the signature of afinder method, with an implementation generated automatically by the Hibernate Metamodel Generator.

For example, suppose the entityBook is defined as follows:

 @Entity class Book {     @Id String isbn;     String title;     ... }

Then we might define:

 @Find Book getBookForIsbn(String isbn); @Find List<Book> getBooksWithTitle(String title);

Notice that:

• the types and names of the method parameters exactly match the types and names of the corresponding fields of the entity.
• there's no special naming convention for the@Find methods—they may be named arbitrarily, and their names encode no semantics.

It's even possible to query by a field of an embedded object:

 @Find List<Book> publishedBooks(String publisher$name);

Here,publisher$name refers to the fieldname of theBook'sPublisher.

The Metamodel Generator automatically creates an "implementation" of every finder method in the static metamodel classBooks_. The generated method may be called according to the following protocol:

 Book book = Books_.findBookByIsbn(session, isbn); List<Book> books = Books_.getBooksWithTitle(session, String title);

Notice the extra parameter of typeEntityManager 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 typesEntityManager,StatelessSession, orSession, for example:

 EntityManager entityManager();

In this case:

• the generated method is no longerstatic,
• the generated method will use this method to obtain the session object, instead of having a parameter of typeEntityManager, and
• the generated static metamodel class will actually implement the type which declares the method annotated@Find.

Thus, the generated method may be called according to the following protocol:

 Books books = new Books_(session); Book book = books.getBookForIsbn(isbn); List<Book> books = books.getBooksWithTitle(String title);

This is reminiscent of traditional DAO-style repositories.

The return type of an annotated method must be an entity typeE, or one of the following types:

• java.util.List<E>,
• java.util.stream.Stream<E>,
• java.util.Optional<E>,
• io.smallrye.mutiny.Uni<E>, when used with Hibernate Reactive,
• org.hibernate.query.Query<E>,
• org.hibernate.query.SelectionQuery<E>,
• jakarta.persistence.Query<E>, or
• jakarta.persistence.TypedQuery<E>.

The names and types of the parameters of a finder method must match exactly with the names and types of persistent fields of the entity type returned by the finder method.

• If there is one parameter, and it matches the@Id or@EmbeddedId field of the entity, the finder method usesEntityManager.find(Class, Object) to retrieve the entity.
• Similarly, if there is one parameter, and its type matches the type of theIdClass of the entity, the finder method usesEntityManager.find(Class, Object) to retrieve the entity. In this case the parameter name is not significant.
• If the parameters match exactly with the@NaturalId field or fields of the entity, the finder method usesSession.byNaturalId(Class) to retrieve the entity.
• Otherwise, the finder method builds and executes acriteria query.

As an exception, the method may have at most one parameter of typeEntityManager,Session,StatelessSession, orMutiny.Session. Furthermore, if the finder method returns multiple results, that is, if its return type isList, then it may also have:

• a parameter with typePage, and/or
• a parameter with typeOrder<? super E>,List<Order<? super E>>, orOrder<? super E>... (varargs) whereE is the entity type returned by the query.

For example:

 @Find List<Book> getBooksWithTitle(String title, List<Order<Book>> order);

As a further exception, a method might support key-based pagination. Then it must have:

• return typeKeyedResultList, and
• a parameter of typeKeyedPage.