Improving your experience with Criteria API using Builder pattern and JPA Static Metamodel - Part I

In this tutorial, I want to show you a way of how to perform persistence operations with Criteria API in a more convenient form using Builder pattern and JPA Static Metamodel Generator. The full source code is available over on . Github 1 Spring Data JPA In the Java world, the most popular way to work with relational databases is to use Spring Data JPA. It is quite a sophisticated framework that allows you to instantly get started working with the database. The most compelling feature in the Spring Data is the Repository. All you need to do to access the database table is to create a Java interface and extend it from the with the defined domain class and with the id type of the domain class as type arguments: CrudRepository public interface CustomerRepository extends CrudRepository { } For each declared interface, Spring will create an appropriate bean, allowing you to easily use it with Dependency Injection. With the , this interface will provide basic implementations for CRUD operations for the managed entity class. For example, the following read operations will allow you to retrieve all the rows and a specific row by id: CrudRepository package org.springframework.data.repository; public interface CrudRepository extends Repository { … Iterable findAll(); Optional findById(ID id); … } If you want to filter the data with specific predicates, Spring Repository allows you to define your own methods with the query derivation mechanism using entity’s fields and keywords: public interface CustomerRepository extends CrudRepository { List findByLastName(String lastName); List findByZipCode(String zipCode); List findByLastNameAndZipCode(String lastName, String zipCode); } It looks very clear and convenient. But there are few cons and pitfalls you should be aware of: Typo mistakes Using query derivation mechanism language to compose a query, you can really minimize your code with supported keywords. Modern Intellij IDEA will help you to build such a query quite easily: @Entity class Customer { @Id private Long id; private String zipCode; } interface CustomerRepository extends CrudRepository { List findAllByZip(String zipCode); } If we construct a query using wrong or non-existing field names, like instead of , when we run this code we will probably see an exception, saying that no property is found for the type: zip zipCode zip Customer Caused by: org.springframework.data.mapping.PropertyReferenceException: No property 'zip' found for type 'Customer' Did you mean ''id'' But if we change the argument type of this field, for example to , we will not receive any exception during start up: Integer @Entity class Customer { @Id private Long id; private String zipCode; } interface CustomerRepository extends CrudRepository { List findAllByZipCode(Integer zipCode); } You’ll receive an exception only when you manually invoke this method passing specific value: java.lang.IllegalArgumentException: Parameter value [90001] did not match expected type [java.lang.String (n/a)] There is no way to mock this part of code. Therefore, you should be very careful when you compose a query or when you refactor an entity’s field type. Read complexity Query derivation mechanism language is quite useful, but it becomes difficult to read if you deal with a complex query containing a deep nested join. Let’s say we want to get Order entities filtered by address attributes: List findAllByCustomerAddressAddressLineLikeAndCustomerAddressCityNameAndCustomerAddressCityCountryName(String addressLine, String city, String country); Sure, you can simplify this query with JPQL using the annotation over this method. But in this case, you will lose all the privileges of the query derivation mechanism with proper validation when Spring starts up: @Query public interface OrderRepository extends CrudRepository { @Query("SELECT o FROM Order o " + " INNER JOIN o.customer cr" + " INNER JOIN cr.address a" + " INNER JOIN a.city ct" + " INNER JOIN ct.country cn" + " WHERE a.addressLine LIKE :address_line AND ct.name = :city AND cn.name = :country") List filterByAddress(@Param("address_line") String addressLine, @Param("city") String city, @Param("country") String country); } The other scenario is to use the Criteria API by extending your Repository with interface and allowing you to access the , and within the interface: JpaSpecificationExecutor Root CriteriaQuery CriteriaBuilder Specification orderRepository.findAll((Specification ) (root, query, cb) -> { Path addressPath = root.get(Order_.customer).get(Customer_.address); Path cityPath = addressPath.get(Address_.city); return cb.and( cb.equal(addressPath.get(Address_.addressLine), "%" + addressLine + "%"), cb.equal(cityPath.get(City_.name), city), cb.equal(cityPath.get(City_.country).get(Country_.name), country) ); }); Explicitness Using Spring Data JPA, we have to create a repository for each table. Explicitness is always good, but it’s quite problematic if you have about 200 tables. In this case, you need to create 200 repositories accordingly, even if you need only one query per repository. 2 Extension implementation My idea is to eliminate all these issues by creating an extension for the Criteria API: select() .equal(Order_.status, OrderStatus.Shipped) .like(Order_.customer, Customer_.address, Address_.addressLine, “11 Aleksandr Pushkin St”) .equal(Order_.customer, Customer_.address, Address_.city, City_.name, “Tbilisi”) .findAll(); First of all, to exclude all the typo errors, we will use the JPA Static Metamodel with an explicit parent-child path chain and with generic types to eliminate any errors during compilation. Each argument will accept an entity's attribute, providing only logical relations with a corresponding data value at the end: equal(Order_.customer, Customer_.address, Address_.city, City_.country, Country_.name, “Georgia”) To reduce read complexity and eliminate nested path duplication, we can use the Builder pattern with common paths: select() .equal(Order_.status, OrderStatus.Shipped) .and(Order_.customer, Customer_.address, like(Address_.addressLine, "11 Aleksandr Pushkin St"), and(Address_.city, equal(City_.name, "Tbilisi"), equal(City_.country, Country_.name, “Georgia”) ) ) .findAll(); To get rid of redundant explicitness by creating a separate repository for each entity, our extension will accept the entity type of the table that we use to start the query from. By passing the entity type explicitly, we can compose queries from any place in the code: select(Order.class) .equal(Order_.status, OrderStatus.Shipped) .and(Order_.customer, Customer_.address, like(Address_.addressLine, "11 Aleksandr Pushkin St"), and(Address_.city, equal(City_.name, "Tbilisi"), equal(City_.country, Country_.name, “Georgia”) ) ) .findAll(); Now, let’s dive into the code and try to build a simple implementation. Our extension will provide the ability to select, update and delete rows. 2.1 BaseQuery First, we add the interface that will contain basic operations for selecting, updating and deleting queries. This interface should have two generic types: as the type and as the implementation itself, which we can use as a return type for Builder pattern methods: BaseQuery R Root Q extends BaseQuery BaseQuery public interface BaseQuery > { } Next, we add the first method for the operation. It will accept as the entity field that we want to compare and the comparing value itself: equal SingularAttribute public interface BaseQuery > { ... Q equal(SingularAttribute attribute, V value); } provides two generic types: the first one is the entity type, and the second is the type of the entity’s represented attribute. Therefore, we put as the first generic type, and we add an extra generic type as the second type, equal to the value type. Please note that if we want to provide type safety, the value should have the same data type as the represented attribute. SingularAttribute R V Next, we can add the second overloaded implementation of the filter, that will contain a subsequent parent-child relation to allow you to compare a nested attribute. In this case, we need to add an extra generic type for the in-between relation: equal P public interface BaseQuery > { ... Q equal(SingularAttribute attribute1, SingularAttribute attribute2, V value); } Lastly, we will add the third overloaded method with an extra and generic types to allow you to reach an attribute available after two subsequent parent-child relations: equal P1 P2 public interface BaseQuery > { ... Q equal(SingularAttribute attribute1, SingularAttribute attribute2, SingularAttribute attribute3, V value); } Now, we are ready to initialize using the Criteria API. This class again should have two generic types: the type and the implementation itself, which we can use as a return type for Builder pattern methods: BaseQuery Root BaseQueryImpl public class BaseQueryImpl > implements BaseQuery { } Before we initialize the equal implementations, we first need to define the collection of predicates. Our query will have nested criteria predicates with postponed initialization. Therefore, we introduce the interface with the following arguments: , and to allow us to create the necessary predicate: QueryPredicate CommonAbstractCriteria CriteriaBuilder Path @FunctionalInterface public interface QueryPredicate { Predicate apply(CommonAbstractCriteria criteria, CriteriaBuilder cb, Path root); } Next, we introduce a collection of as field and a method that will convert this collection to a collection of : QueryPredicate BaseQueryImpl javax.persistence.criteria.Predicate public class BaseQueryImpl > implements BaseQuery { protected final Collection > predicates; public BaseQueryImpl() { this.predicates = new ArrayList<>(); } protected Predicate[] buildPredicates(CommonAbstractCriteria criteria, Collection > predicates, CriteriaBuilder cb, Path root) { return predicates .stream() .map(t -> t.apply(criteria, cb, root)) .toArray(Predicate[]::new); } } In addition, we’ll introduce abstract method that should return instance for each implementation: self() this public abstract class BaseQueryImpl > implements BaseQuery { ... //subclasses must override this method to return "this" protected abstract Q self(); } Now, we are ready to create defined implementations. Each implementation should retrieve each required and accumulate an equal predicate in the predicates collection: equal Path public abstract class BaseQueryImpl > implements BaseQuery { ... @Override public Q equal(SingularAttribute attribute, V value) { predicates.add((criteria, cb, root) -> cb.equal(root.get(attribute), value)); return self(); } @Override public Q equal(SingularAttribute attribute1, SingularAttribute attribute2, V value) { predicates.add((criteria, cb, root) -> cb.equal(root.get(attribute1).get(attribute2), value)); return self(); } @Override public Q equal(SingularAttribute attribute1, SingularAttribute attribute2, SingularAttribute attribute3, V value) { predicates.add((criteria, cb, root) -> cb.equal(root.get(attribute1).get(attribute2).get(attribute3), value)); return self(); } } You can add additional statements on your own accepting a chain of 3+ subsequent parent-child relations as well as predicates for other operators, like , , , , , etc. equal notEqual like greaterThan lessThan isNull 2.2 SelectQuery To perform select statements, we will create the interface extending the : SelectQuery BaseQuery public interface SelectQuery > extends BaseQuery { } This interface will mostly contain the terminating methods that will return the final result from a database. The first terminating method will be returning the list of (Root type): findAll() R public interface SelectQuery > extends BaseQuery { List findAll(); } Next, we will provide two overloaded methods to select nested join table: findAll() public interface SelectQuery > extends BaseQuery { ... List findAll(SingularAttribute attribute); List findAll(SingularAttribute attribute1, SingularAttribute attribute2); } The second group of terminating interfaces we implement is , which will return a single result or throw an exception if there is no result found: getOne() public interface SelectQuery > extends BaseQuery { ... R getOne(); P getOne(SingularAttribute attribute); P2 getOne(SingularAttribute attribute1, SingularAttribute attribute2); } The third terminating group we implement is , which will return a single result wrapped in the : findOne() Optional public interface SelectQuery > extends BaseQuery { ... Optional findOne(); Optional findOne(SingularAttribute attribute); Optional findOne(SingularAttribute attribute1, SingularAttribute attribute2); } The next terminating group we can provide is the method that will return number of rows matching the query: count() public interface SelectQuery > extends BaseQuery { ... long count(); long count(SingularAttribute attribute); long count(SingularAttribute attribute1, SingularAttribute attribute2); } Next, let’s add non-terminating interfaces to order the rows. Methods without Order argument will provide the ascending order: public interface SelectQuery > extends BaseQuery { ... SelectQuery order(SingularAttribute attribute); SelectQuery order(SingularAttribute attribute, Order order); SelectQuery order(SingularAttribute attribute1, SingularAttribute attribute2); SelectQuery order(SingularAttribute attribute1, SingularAttribute attribute2, Order order); SelectQuery order(SingularAttribute attribute1, SingularAttribute attribute2, SingularAttribute attribute3); SelectQuery order(SingularAttribute attribute1, SingularAttribute attribute2, SingularAttribute attribute3, Order order); } Lastly, if you want to initialize Lazy relations, you can add methods: fetch() public interface SelectQuery > extends BaseQuery { ... SelectQuery fetch(SingularAttribute attribute); SelectQuery fetch(SingularAttribute attribute1, SingularAttribute attribute2); SelectQuery fetch(SingularAttribute attribute1, SingularAttribute attribute2, SingularAttribute attribute3); } Now we have enough interfaces to perform select statements. You can add any other interfaces on your own including pagination, exists and so on. Let’s finish the implementation for the declared methods by creating the class: SelectQueryImpl public class SelectQueryImpl extends BaseQueryImpl > implements SelectQuery > { } This class will contain the following fields: , , , and the List of : javax.persistence.EntityManager javax.persistence.criteria.CriteriaBuilder javax.persistence.criteria.CriteriaQuery javax.persistence.criteria.Root javax.persistence.criteria.Order public class SelectQueryImpl extends BaseQueryImpl > implements SelectQuery > { private final EntityManager em; private final CriteriaBuilder cb; private final CriteriaQuery query; private final Root root; private final List orderList; } Next, let’s declare a constructor. To initialize Criteria fields, we need the and the root entity type: EntityManager R public class SelectQueryImpl extends BaseQueryImpl > implements SelectQuery > { ... public SelectQueryImpl(EntityManager em, Class type) { this.em = em; this.cb = em.getCriteriaBuilder(); this.query = cb.createQuery(); this.root = query.from(type); this.orderList = new ArrayList<>(); } @Override protected SelectQueryImpl self() { return this; } } Before implementing declared terminating and non-terminating interfaces, we will add a private method that will accept argument and return built : javax.persistence.criteria.Selection TypedQuery public class SelectQueryImpl extends BaseQueryImpl > implements SelectQuery > { ... private TypedQuery buildQuery(Selection selection) { CriteriaQuery resultQuery = query .select(selection) .orderBy(orderList); if (!predicates.isEmpty()) { resultQuery = resultQuery.where(buildPredicates(query, predicates, cb, root)); } return em.createQuery(resultQuery); } } This method will build our query by selecting the required table path, providing predicates and orderList. Now we are ready to implement required interfaces. To implement the first group for the interfaces, we just need to pass desired table path to the method and call : findAll() buildQuery() getResultList() public class SelectQueryImpl extends BaseQueryImpl > implements SelectQuery > { ... @Override public List findAll() { return buildQuery(root) .getResultList(); } @Override public List findAll(SingularAttribute attribute) { return buildQuery(root.get(attribute)) .getResultList(); } @Override public List findAll(SingularAttribute attribute1, SingularAttribute attribute2) { return buildQuery(root.get(attribute1).get(attribute2)) .getResultList(); } } The second implementation is for the interface, which will act the same except for the fact that we should limit the result by one row and call the : getOne() getSingleResult() public class SelectQueryImpl extends BaseQueryImpl > implements SelectQuery > { ... @Override public R getOne() { return buildQuery(root) .setMaxResults(1) .getSingleResult(); } @Override public P getOne(SingularAttribute attribute) { return buildQuery(root.get(attribute)) .setMaxResults(1) .getSingleResult(); } @Override public P2 getOne(SingularAttribute attribute1, SingularAttribute attribute2) { return buildQuery(root.get(attribute1).get(attribute2)) .setMaxResults(1) .getSingleResult(); } } The next realization for the can be implemented using method with try/catch block: findOne() getOne() public class SelectQueryImpl extends BaseQueryImpl > implements SelectQuery > { ... @Override public Optional findOne() { try { return Optional.of(getOne()); } catch (NoResultException e) { return Optional.empty(); } } @Override public Optional findOne(SingularAttribute attribute) { try { return Optional.of(getOne(attribute)); } catch (NoResultException e) { return Optional.empty(); } } @Override public Optional findOne(SingularAttribute attribute1, SingularAttribute attribute2) { try { return Optional.of(getOne(attribute1, attribute2)); } catch (NoResultException e) { return Optional.empty(); } } } The last terminating group is , which will return count of rows matching the query: count() public class SelectQueryImpl extends BaseQueryImpl > implements SelectQuery > { ... @Override public long count() { return buildQuery(cb.count(root)) .getSingleResult(); } @Override public long count(SingularAttribute attribute) { return buildQuery(cb.count(root.get(attribute))) .getSingleResult(); } @Override public long count(SingularAttribute attribute1, SingularAttribute attribute2) { return buildQuery(cb.count(root.get(attribute1).get(attribute2))) .getSingleResult(); } } Lastly, we need to implement non-terminating interfaces for the and methods: order() fetch() public class SelectQueryImpl extends BaseQueryImpl > implements SelectQuery > { ... @Override public SelectQueryImpl order(SingularAttribute attribute) { return order(attribute, Order.ASC); } @Override public SelectQueryImpl order(SingularAttribute attribute, Order sort) { javax.persistence.criteria.Order order = sort == Order.ASC ? cb.asc(root.get(attribute)) : cb.desc(root.get(attribute)); orderList.add(order); return this; } @Override public SelectQueryImpl order(SingularAttribute attribute1, SingularAttribute attribute2) { return order(attribute1, attribute2, Order.ASC); } @Override public SelectQueryImpl order(SingularAttribute attribute1, SingularAttribute attribute2, Order sort) { Path path = root.get(attribute1).get(attribute2); javax.persistence.criteria.Order order = sort == Order.ASC ? cb.asc(path) : cb.desc(path); orderList.add(order); return this; } @Override public SelectQueryImpl order(SingularAttribute attribute1, SingularAttribute attribute2, SingularAttribute attribute3) { return order(attribute1, attribute2, attribute3, Order.ASC); } @Override public SelectQueryImpl order(SingularAttribute attribute1, SingularAttribute attribute2, SingularAttribute attribute3, Order sort) { Path path = root.get(attribute1).get(attribute2).get(attribute3); javax.persistence.criteria.Order order = sort == Order.ASC ? cb.asc(path) : cb.desc(path); orderList.add(order); return this; } @Override public SelectQueryImpl fetch(SingularAttribute attribute) { root.fetch(attribute); return this; } @Override public SelectQueryImpl fetch(SingularAttribute attribute1, SingularAttribute attribute2) { root.fetch(attribute1).fetch(attribute2); return this; } @Override public SelectQueryImpl fetch(SingularAttribute attribute1, SingularAttribute attribute2, SingularAttribute attribute3) { root.fetch(attribute1).fetch(attribute2).fetch(attribute3); return this; } } 2.3 UpdateQuery To perform update statements, we will create the interface extending the : UpdateQuery BaseQuery public interface UpdateQuery > extends BaseQuery { } This query will contain only two methods: the first one to set the attributes we want to update and the second one is the terminating method that will return the number of updated rows: public interface UpdateQuery > extends BaseQuery { UpdateQuery set(SingularAttribute attribute, V value); int execute(); } Implementation for the should be quite straightforward except for the fact, now we should use instead of : UpdateQuery CriteriaUpdate CriteriaQuery public class UpdateQueryImpl extends BaseQueryImpl > implements UpdateQuery > { private final EntityManager em; private final CriteriaBuilder cb; private final CriteriaUpdate query; private final Root root; public UpdateQueryImpl(EntityManager em, Class type) { this.em = em; this.cb = em.getCriteriaBuilder(); this.query = cb.createCriteriaUpdate(type); this.root = query.from(type); } @Override public UpdateQueryImpl set(SingularAttribute attribute, V value) { query.set(attribute, value); return this; } @Override public int execute() { if (!predicates.isEmpty()) { query.where(buildPredicates(query, predicates, cb, root)); } return em.createQuery(query) .executeUpdate(); } @Override protected UpdateQueryImpl self() { return this; } } 2.4 DeleteQuery Lastly, to perform delete statements, we will create the interface extending the : DeleteQuery BaseQuery public interface DeleteQuery > extends BaseQuery { } will have only one terminating method, returning the number of deleted rows: DeleteQuery public interface DeleteQuery > extends BaseQuery { int execute(); } Implementation for the with the : DeleteQuery CriteriaDelete public class DeleteQueryImpl extends BaseQueryImpl > implements DeleteQuery > { private final EntityManager em; private final CriteriaBuilder cb; private final CriteriaDelete query; private final Root root; public DeleteQueryImpl(EntityManager em, Class type) { this.em = em; this.cb = em.getCriteriaBuilder(); this.query = cb.createCriteriaDelete(type); this.root = query.from(type); } @Override protected DeleteQueryImpl self() { return this; } @Override public int execute() { if (!predicates.isEmpty()) { query.where(buildPredicates(query, predicates, cb, root)); } return em.createQuery(query) .executeUpdate(); } } 2.5 CriteriaApiHelper In order to create any of the implementations, we should pass an instance of every time we want to perform a query. To simplify this injection process, we can declare an extra class that will hold the : BaseQuery EntityManager EntityManager public class CriteriaApiHelper { private final EntityManager em; public CriteriaApiHelper(EntityManager em) { this.em = em; } } Now we can just initialize methods for by creating a suitable implementation for each query type: BaseQuery public class CriteriaApiHelper { … public SelectQueryImpl select(Class type) { return new SelectQueryImpl<>(em, type); } public UpdateQueryImpl update(Class type) { return new UpdateQueryImpl<>(em, type); } public DeleteQueryImpl delete(Class type) { return new DeleteQueryImpl<>(em, type); } } 3 Wrapping up Now you can perform select, update and delete queries using : CriteriaApiHelper List listOfOrders = criteriaApiHelper.select(Order.class) .equal(Order_.status, OrderStatus.Shipped) .like(Order_.customer, Customer_.address, Address_.addressLine, "11 Aleksandr Pushkin St") .equal(Order_.customer, Customer_.address, Address_.city, City_.name, "Tbilisi") .equal(Order_.customer, Customer_.address, Address_.city, City_.country, Country_.name, “Georgia”) .findAll(); In order to see the entities with an underscore at the end, you should include the JPA Static Metamodel Generator library: org.hibernate hibernate-jpamodelgen provided After that, you need to rebuild your project and mark the package as the Generated Sources Root: target/generated-sources/annotations In the next chapters, we will implement nested expressions providing predicates and sub queries. or/and