Module jakarta.data
Package jakarta.data.repository

Annotation Interface Find

@Documented @Retention(RUNTIME) @Target(METHOD) public @interface Find

Annotates a repository method returning entities as a parameter-based automatic query method.

The Find annotation indicates that the annotated repository method executes a query to retrieve entities based on its parameters and on the arguments assigned to its parameters. The method return type identifies the entity type returned by the query. Each parameter of the annotated method must either:

  • have exactly the same type and name (the parameter name in the Java source, or a name assigned by @By) as a persistent field or property of the entity class, or
  • be of type Limit, Sort, Order, or PageRequest.

The query is inferred from the method parameters which match persistent fields of the entity.

There is no specific naming convention for methods annotated with @Find; they may be named arbitrarily, and their names do not carry any semantic meaning defined by the Jakarta Data specification.

For example, consider an interface representing a garage:

 @Repository
 interface Garage {
     @Find
     List<Car> getCarsWithModel(@By("model") String model);
 }

The @Find annotation indicates that the getCarsWithModel(model) method retrieves Car instances with the given value of the model field.

A method annotated with @Find must return one of the following types:

  • an entity type E, when the method returns a single instance,
  • Optional<E>, when the method returns at most a single instance,
  • an entity array type E[],
  • List<E>,
  • Stream<E>, or
  • Page<E> or CursoredPage<E>.

An automatic query method annotated Find returns an entity instance for every record which satisfies the parameter-based conditions.

  • If the return type of the annotated method is E or Optional<E> and more than one record satisfies the query conditions, the method must throw NonUniqueResultException.
  • If the return type of the annotated method is E and no record satisfies the query conditions, the method must throw EmptyResultException.

Annotations such as @Find, @Query, @Insert, @Update, @Delete, and @Save are mutually-exclusive. A given method of a repository interface may have at most one @Find annotation, lifecycle annotation, or query annotation.

See Also: