Blaze-Persistence

Blaze-Persistence is a rich Criteria API for JPA providers.

What is it?

Blaze-Persistence is a rich Criteria API for JPA providers that aims to be better than all the other Criteria APIs available. It provides a fluent API for building queries and removes common restrictions encountered when working with JPA directly. It offers rich pagination support and also supports keyset pagination.

The Entity-View module can be used to create views for JPA entites. You can roughly imagine an entity view is to an entity, what a RDBMS view is to a table.

The JPA-Criteria module implements the Criteria API of JPA but is backed by the Blaze-Persistence Core API so you can get a query builder out of your CriteriaQuery objects.

With Spring Data or DeltaSpike Data integrations you can make use of Blaze-Persistence easily in your existing repositories.

Features

Blaze-Persistence is not only a Criteria API that allows to build queries easier, but it also comes with a lot of features that are normally not supported by JPA providers.

Here is a rough overview of new features that are introduced by Blaze-Persistence on top of the JPA model

• Use CTEs and recursive CTEs
• Use modification CTEs aka DML in CTEs
• Make use of the RETURNING clause from DML statements
• Use the VALUES clause for reporting queries and soon make use of table generating functions
• Create queries that use SET operations like UNION, EXCEPT and INTERSECT
• Manage entity collections via DML statements to avoid reading them in memory
• Define functions similar to Hibernates SQLFunction in a JPA provider agnostic way
• Use many built-in functions like GROUP_CONCAT, date extraction, date arithmetic and many more
• Easy pagination and simple API to make use of keyset pagination

In addition to that, Blaze-Persistence also works around some JPA provider issues in a transparent way.

How to use it?

Blaze-Persistence is split up into different modules. We recommend that you define a version property in your parent pom that you can use for all artifacts. Modules are all released in one batch so you can safely increment just that property.

<properties>
    <blaze-persistence.version>1.6.17</blaze-persistence.version>
</properties>

Alternatively you can also use our BOM in the dependencyManagement section.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.blazebit</groupId>
            <artifactId>blaze-persistence-bom</artifactId>
            <version>${blaze-persistence.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>    
    </dependencies>
</dependencyManagement>

Quickstart

If you want a sample application with everything setup where you can poke around and try out things, just go with our archetypes!

Core-only archetype:

mvn archetype:generate "-DarchetypeGroupId=com.blazebit" "-DarchetypeArtifactId=blaze-persistence-archetype-core-sample" "-DarchetypeVersion=1.6.17"

Entity view archetype:

mvn archetype:generate "-DarchetypeGroupId=com.blazebit" "-DarchetypeArtifactId=blaze-persistence-archetype-entity-view-sample" "-DarchetypeVersion=1.6.17"

Spring-Data archetype:

mvn archetype:generate "-DarchetypeGroupId=com.blazebit" "-DarchetypeArtifactId=blaze-persistence-archetype-spring-data-sample" "-DarchetypeVersion=1.6.17"

Spring-Boot archetype:

mvn archetype:generate "-DarchetypeGroupId=com.blazebit" "-DarchetypeArtifactId=blaze-persistence-archetype-spring-boot-sample" "-DarchetypeVersion=1.6.17"

DeltaSpike Data archetype:

mvn archetype:generate "-DarchetypeGroupId=com.blazebit" "-DarchetypeArtifactId=blaze-persistence-archetype-deltaspike-data-sample" "-DarchetypeVersion=1.6.17"

Java EE archetype:

mvn archetype:generate "-DarchetypeGroupId=com.blazebit" "-DarchetypeArtifactId=blaze-persistence-archetype-java-ee-sample" "-DarchetypeVersion=1.6.17"

Core-only Jakarta archetype:

mvn archetype:generate "-DarchetypeGroupId=com.blazebit" "-DarchetypeArtifactId=blaze-persistence-archetype-core-sample-jakarta" "-DarchetypeVersion=1.6.17"

Entity view Jakarta archetype:

mvn archetype:generate "-DarchetypeGroupId=com.blazebit" "-DarchetypeArtifactId=blaze-persistence-archetype-entity-view-sample-jakarta" "-DarchetypeVersion=1.6.17"

Supported Java runtimes

All projects are built for Java 7 except for the ones where dependencies already use Java 8 like e.g. Hibernate 5.2, Spring Data 2.0 etc. So you are going to need a JDK 8 for building the project. The latest Java version we test and support is Java 21.

We also support building the project with JDK 9 and try to keep up with newer versions. If you want to run your application on a Java 9 JVM you need to handle the fact that JDK 9+ doesn't export the JAXB and JTA APIs anymore. In fact, JDK 11 removed the modules, so the command line flags to add modules to the classpath won't work.

Since libraries like Hibernate and others require these APIs you need to make them available. The easiest way to get these APIs back on the classpath is to package them along with your application. This will also work when running on Java 8. We suggest you add the following dependencies.

<dependency>
    <groupId>jakarta.xml.bind</groupId>
    <artifactId>jakarta.xml.bind-api</artifactId>

    <version>2.3.3</version>

    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>com.sun.xml.bind</groupId>
    <artifactId>jaxb-impl</artifactId>

    <version>2.3.3</version>

    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>jakarta.transaction</groupId>
    <artifactId>jakarta.transaction-api</artifactId>

    <version>1.3.3</version>

    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>jakarta.activation</groupId>
    <artifactId>jakarta.activation-api</artifactId>

    <version>1.2.2</version>

    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>jakarta.annotation</groupId>
    <artifactId>jakarta.annotation-api</artifactId>

    <version>1.3.5</version>

    <scope>provided</scope>
</dependency>

The jakarta.transaction and jakarta.activation dependencies are especially relevant for the JPA metamodel generation.

Supported environments/libraries

The bare minimum is JPA 2.0. If you want to use the JPA Criteria API module, you will also have to add the JPA 2 compatibility module. Generally, we support the usage in Java EE 6+ or Spring 4+ applications.

See the following table for an overview of supported versions.

Manual setup

For compiling you will only need API artifacts and for the runtime you need impl and integration artifacts.

See the core documentation for the necessary dependencies needed to setup Blaze-Persistence. If you want to use entity views, the entity view documentation contains a similar setup section describing the necessary dependencies.

Documentation

The current documentation is a reference manual and is split into a reference for the core module and for the entity-view module. At some point we might introduce topical documentation, but for now you can find articles on the Blazebit Blog

Core quick-start

First you need to create a CriteriaBuilderFactory which is the entry point to the core api.

CriteriaBuilderConfiguration config = Criteria.getDefault();
// optionally, perform dynamic configuration
CriteriaBuilderFactory cbf = config.createCriteriaBuilderFactory(entityManagerFactory);

NOTE: The CriteriaBuilderFactory should have the same scope as your EntityManagerFactory as it is bound to it.

For demonstration purposes, we will use the following simple entity model.

@Entity
public class Cat {
    @Id
    private Integer id;
    private String name;
    @ManyToOne(fetch = FetchType.LAZY)
    private Cat father;
    @ManyToOne(fetch = FetchType.LAZY)
    private Cat mother;
    @OneToMany
    private Set<Cat> kittens;
    // Getter and setters omitted for brevity
}

If you want to select all cats and fetch their kittens as well as their father you do the following.

cbf.create(em, Cat.class).fetch("kittens.father").getResultList();

This will create quite a query behind the scenes:

SELECT cat FROM Cat cat LEFT JOIN FETCH cat.kittens kittens_1 LEFT JOIN FETCH kittens_1.father father_1

An additional bonus is that the paths and generally every expression you write will get checked against the metamodel so you can spot typos very early.

JPA Criteria API quick-start

Blaze-Persistence provides an implementation of the JPA Criteria API what allows you to mostly code against the standard JPA Criteria API, but still be able to use the advanced features Blaze-Persistence provides.

All you need is a CriteriaBuilderFactory and when constructing the actual query, an EntityManager.

```java // This is a subclass of the JPA CriteriaBuilder interface BlazeCriteriaBuilder cb = BlazeCriteria.get(criteriaBuilderFactory); // A subclass of the JPA CriteriaQuery interface BlazeCriteriaQuery query = cb.createQuery(Cat.class);

// Do your JPA Criteria query logic with cb and query Root root = query.from(Cat.class); query.where(cb.equal(root.get(Cat_.name), "Felix"));

// Finally, transform the BlazeCriteriaQuery to the Blaze-Persistence Core CriteriaBuilder CriteriaBuilder builder = query.createCriteriaBuilder(entityManager); // From here on, you can use all the power of the Blaze-Persistence Core API

// And finally fetch the result List resultList = b