Chapter 3. Query Method Expressions

3.1. Using method expressions
3.2. Query Options

Good naming is a difficult aspects in software engineering. A good method name usually makes comments unnecessary and states exactly what the method does. And with method expressions, the method name is actually the implementation!

3.1. Using method expressions

Let's start by looking at an example:

@Entity

public class Person {

    @Id @GeneratedValue

    private Long id;

    private String name;

    private Integer age;

    private Gender gender;

}

    

public interface PersonDao extends EntityDao<Person, Long> {

    List<Person> findByNameLikeAndAgeBetweenAndGender(String name, 

                                  int minAge, int maxAge, Gender gender);

}

Looking at the method name, this can easily be read as query all Persons which have a name like the given name parameter, their age is between a min and a max age and having a specific gender. The CDI Query module can translate method names following a given format and directly generate the query implementation out of it (in EBNF-like form):

(Entity|List<Entity>) findBy(Property[Comparator]){Operator Property [Comparator]}

Or in more concrete words:

The query method must either return an entity or a list of entities
It must start with the findBy keyword
Followed by a property of the DAO entity and an optional comparator (we'll define this later). The property will be used in the query together with the comparator. Note that the number of arguments passed to the method depend on the comparator.
You can add more blocks of property-comparator which have to be concatenated by a boolean operator. This is either an And or Or

Other assumptions taken by the expression evaluator:

The property name starts lower cased while the property in the expression has an upper cases first character.

Following comparators are currently supported to be used in method expressions:

Name	# of Arguments	Description
`Equal`	`1`	Property must be equal to argument value. If the operator is omitted in the expression, this is assumed as default.
`NotEqual`	`1`	Property must be not equal to argument value.
`Like`	`1`	Property must be like the argument value. Use the %-wildcard in the argument.
`GreaterThan`	`1`	Property must be greater than argument value.
`GreaterThanEquals`	`1`	Property must be greater than or equal to argument value.
`LessThan`	`1`	Property must be less than argument value.
`LessThanEquals`	`1`	Property must be less than or equal to argument value.
`Between`	`2`	Property must be between the two argument values.
`IsNull`	`0`	Property must be null.
`IsNotNull`	`0`	Property must be non-null.

3.2. Query Options

CDI Query supports query options on method expressions. If you want to page a query, you can change the first result as well as the maximum number of results returned:

public interface PersonDao extends EntityDao<Person, Long> {


    List<Person> findByNameLike(String name, @FirstResult int start, @MaxResults int pageSize);


}