Package org.hibernate.annotations.processing

Annotation Type Find

  • @Target(METHOD)
@Retention(CLASS)
@Incubating
public @interface Find
    Identifies a method of an abstract class or interface as defining the signature of a finder method, with an implementation generated automatically by the Hibernate Metamodel Generator.

    For example, suppose the entity Book 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 field name of the Book's Publisher.

    The Metamodel Generator automatically creates an "implementation" of every finder method in the static metamodel class Books_. 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 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, StatelessSession, or 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 @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 type E, or one of the following types:

    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 uses EntityManager.find(Class, Object) to retrieve the entity.
    • Similarly, if there is one parameter, and its type matches the type of the IdClass of the entity, the finder method uses EntityManager.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 uses Session.byNaturalId(Class) to retrieve the entity.
    • Otherwise, the finder method builds and executes a criteria query.

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

    • a parameter with type Page, and/or
    • a parameter with type Order<? super E>, List<Order<? super E>>, or Order<? super E>... (varargs) where E 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:

    Since:
    6.3
    See Also:
    HQL, SQL

    • Element Detail

      • enabledFetchProfiles

        String[] enabledFetchProfiles
        Default:
        {}