Getting Started with Blaze Persistence

1. Introduction

In this tutorial, we’ll discuss the usage of the Blaze Persistence library in the Spring Boot application.

The library provides rich Criteria API for creating SQL queries programmatically. It allows us to apply various kinds of filters, functions, and logical conditions.

We’ll cover the project setup, provide a few examples of how to create queries and see how to map entities to DTO objects.

2. Maven Dependencies

To include Blaze Persistence core in our project, we’ll need to add the dependencies blaze-persistence-core-api-jakarta, blaze-persistence-core-impl-jakarta, and blaze-persistence-integration-hibernate-6.2 in the pom.xml file:

<dependency>
    <groupId>com.blazebit</groupId>
    <artifactId>blaze-persistence-core-api-jakarta</artifactId>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>com.blazebit</groupId>
    <artifactId>blaze-persistence-core-impl-jakarta</artifactId>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>com.blazebit</groupId>
    <artifactId>blaze-persistence-integration-hibernate-6.2</artifactId>
    <scope>runtime</scope>
</dependency>

Depending on the Hibernate version we’re using, the latter dependency may be different.

3. Entity Model

As a first step, let’s define the data models we’re going to use in the examples. To automatically create tables, we’re going to use Hibernate.

We’ll have two entities, Person and Post, that are connected using a one-to-many relationship:

@Entity
public class Person {

    @Id
    @GeneratedValue
    private Long id;

    private String name;

    private int age;

    @OneToMany(mappedBy = "author")
    private Set<Post> posts = new HashSet<>();
}

@Entity
public class Post {

    @Id
    @GeneratedValue
    private Long id;

    private String title;

    private String content;

    @ManyToOne(fetch = FetchType.LAZY)
    private Person author;
}

4. Criteria API

The Blaze Persistence library is an alternative to JPA Criteria API. Both APIs give us the ability to define dynamic queries at runtime.

However, JPA Criteria API is not very popular among developers because it’s hard to read and write. In contrast, Blaze Persistence is designed to be more user-friendly and easier to use. Additionally, it integrates with various JPA implementations and provides an extensive set of query features.

4.1. Configuration

In order to use Blaze Persistence Criteria API, we need to define the CriteriaBuilderFactory bean in our configuration class:

@Autowired
private EntityManagerFactory entityManagerFactory;

@Bean
public CriteriaBuilderFactory createCriteriaBuilderFactory() {
    CriteriaBuilderConfiguration config = Criteria.getDefault();
    return config.createCriteriaBuilderFactory(entityManagerFactory);
}

4.2. Basic Query

Now, let’s start with a simple query that selects every Post from the database. We only need two method calls to define and execute a query:

List<Post> posts = builderFactory.create(entityManager, Post.class).getResultList();

The create method creates a query while a call of the getResultList method returns the result returned by the query.

Furthermore, in the create method, the Post.class argument serves several purposes:

• Identifies the result type of the query
• Identifies the implicit query root
• Adds implicit SELECT and FROM clauses for the Post table

Once executed, the query will generate the following JPQL:

SELECT post
FROM Post post;

4.3. Where Clause

We can add the WHERE clause in our criteria builder by calling the where method after the create method.

Let’s see how we’d get posts that are written by a person who wrote at least two posts and whose age is between 18 and 40 years:

CriteriaBuilder<Person> personCriteriaBuilder = builderFactory.create(entityManager, Person.class, "p")
  .where("p.age")
    .betweenExpression("18")
    .andExpression("40")
  .where("SIZE(p.posts)").geExpression("2")
  .orderByAsc("p.name")
  .orderByAsc("p.id");

Because Blaze Persistence supports a direct function call syntax, we could easily retrieve the size of the posts connected to the person.

Furthermore, we can define compound predicates by calling the whereAnd or whereOr method. They return builder instance, which we can use to define nested compound predicates by calling the where method one or more times. Once we finish, we need to call the endAnd or endOr method to close the compound predicate.

For instance, let’s create a query that selects posts with a specific title or author name:

CriteriaBuilder<Post> postCriteriaBuilder = builderFactory.create(entityManager, Post.class, "p")
  .whereOr()
    .where("p.title").like().value(title + "%").noEscape()
    .where("p.author.name").eq(authorName)
  .endOr();

4.4. From Clause

The FROM clause contains the entities which should be queried. As mentioned earlier, we can specify the root entity inside the create method. However, we can define from clause to specify the root. That way, the implicitly created query root will be removed:

CriteriaBuilder<Post> postCriteriaBuilder = builderFactory.create(entityManager, Post.class)
  .from(Person.class, "person")
  .select("person.posts");

In this example, the Post.class argument only defines the return type.

Since we are selecting from a different table, the builder will add implicit JOIN in generated query:

SELECT posts_1 
FROM Person person 
LEFT JOIN person.posts posts_1;

5. Entity-View Module

Blaze Persistence entity view module tries to solve a problem of efficient mapping between the entity and DTO classes. Using this module, we can define DTO classes as interfaces and provide the mappings to the entity class using annotations.

5.1. Maven Dependencies

We’ll need to include additional entity-view dependencies in our project:

<dependency>
    <groupId>com.blazebit</groupId>
    <artifactId>blaze-persistence-entity-view-api-jakarta</artifactId>
</dependency>
<dependency>
    <groupId>com.blazebit</groupId>
    <artifactId>blaze-persistence-entity-view-impl-jakarta</artifactId>
</dependency>
<dependency>
    <groupId>com.blazebit</groupId>
    <artifactId>blaze-persistence-entity-view-processor-jakarta</artifactId>
</dependency>

5.2. Configuration

Furthermore, we’ll need an EntityViewManager bean with entity view classes registered:

@Bean
public EntityViewManager createEntityViewManager(
  CriteriaBuilderFactory criteriaBuilderFactory, EntityViewConfiguration entityViewConfiguration) {
    return entityViewConfiguration.createEntityViewManager(criteriaBuilderFactory);
}

Because EntityViewManager is bound to both EntityManagerFactory and CriteriaBuilderFactory, its scope should be the same.

5.3. Mapping

An entity view representation is a simple interface or an abstract class describing the structure of the projection we want.

Let’s create an interface that will represent the entity view for the Post class:

@EntityView(Post.class)
public interface PostView {
  
    @IdMapping
    Long getId();

    String getTitle();

    String getContent();
}

We need to annotate our interface with @EntityView annotation and provide an entity class.

Although it is not required, we should define an id mapping using the @IdMapping annotation whenever possible. Entity views without such a mapping would have equals and hashCode implementations that consider all attributes, whereas, with an id mapping, only the id is considered.

However, if we want to use a different name for the getter method, we could add a @Mapping annotation. Using this annotation, we can define the whole expression as well:

@Mapping("UPPER(title)")
String getTitle();

As a result, the mapping will return the uppercased title of the Post entity.

Additionally, we could extend the entity view. Suppose we want to define a view that will return a post with an additional author’s information.

Firstly, we’ll define a PersonView interface:

@EntityView(Person.class)
public interface PersonView {
    
    @IdMapping
    Long getId();

    int getAge();

    String getName();
}

Secondly, let’s define a new interface that extends the PostView interface and a method that returns PersonView information:

@EntityView(Post.class)
public interface PostWithAuthorView extends PostView {
    PersonView getAuthor();
}

Finally, let’s use views with the criteria builder. They can be applied directly to a query.

We can define a base query and then create the mapping:

CriteriaBuilder<Post> postCriteriaBuilder = builderFactory.create(entityManager, Post.class, "p")
  .whereOr()
    .where("p.title").like().value("title%").noEscape()
    .where("p.author.name").eq(authorName)
  .endOr();

CriteriaBuilder<PostWithAuthorView> postWithAuthorViewCriteriaBuilder =
  viewManager.applySetting(EntityViewSetting.create(PostWithAuthorView.class), postCriteriaBuilder);

The code above would create an optimized query and build our entity view based on the results:

SELECT p.id AS PostWithAuthorView_id,
  p.author.id AS PostWithAuthorView_author_id,
  author_1.age AS PostWithAuthorView_author_age,
  author_1.name AS PostWithAuthorView_author_name,
  p.content AS PostWithAuthorView_content,
  UPPER(p.title) AS PostWithAuthorView_title
FROM com.baeldung.model.Post p
LEFT JOIN p.author author_1
WHERE p.title LIKE REPLACE(:param_0, '\\', '\\\\')
  OR author_1.name = :param_1

5.4. Entity-View and Spring Data

Besides integration with Spring, Blaze Persistence provides a Spring Data integration module, making entity views as convenient to use as using entities.

Additionally, we’d need to include a Spring integration dependency:

<dependency>
    <groupId>com.blazebit</groupId>
    <artifactId>blaze-persistence-integration-spring-data-3.1</artifactId>
</dependency>

Moreover, to enable Spring Data, we’d need to annotate the configuration class with @EnableBlazeRepositories annotation. Optionally, we can specify the base package for repository class scanning.

The integration comes with a base EntityViewRepository interface we can use for our repository definitions.

Now, let’s define an interface that works with the PostWithAuthorView:

@Repository
@Transactional(readOnly = true)
public interface PostViewRepository extends EntityViewRepository<PostWithAuthorView, Long> {
}

Here, our interface inherits the most commonly used repository methods, such as findAll, findOne, and exists. If needed, we could define our own methods using the Spring Data JPA method naming conventions.

6. Conclusion

In this article, we’ve learned how to configure and create simple queries using the Blaze Persistence library.