### Initial Request for Keyset Pagination

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/deltaspike_data.adoc

Example of an initial GET request to retrieve the first page of data, including sorting parameters.

```http
GET /cats?page=0&size=3&sort=id,desc
{
    content: [
        { id: 10, name: 'Felix', age: 10 },
        { id: 9, name: 'Robin', age: 4 },
        { id: 8, name: 'Billy', age: 7 }
    ]
}
```

--------------------------------

### Serve Website Documentation

Source: https://github.com/blazebit/blaze-persistence/blob/main/README.md

Starts an embedded server for the documentation website at port 8820.

```bash
./serve-website.sh
```

--------------------------------

### Set JAVA_HOME for Windows

Source: https://github.com/blazebit/blaze-persistence/blob/main/creating-a-release.md

Example of setting the JAVA_HOME environment variable on Windows to point to a JDK 8 installation.

```batch
set JAVA_HOME="C:\\Program Files\\Java\\jdk-17.0.2"
```

--------------------------------

### Build and test the project

Source: https://github.com/blazebit/blaze-persistence/blob/main/CONTRIBUTING.md

Execute this command to clean and install the project using Maven.

```sh
mvn clean install
```

--------------------------------

### Setup GraphQL schema and integration

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/graphql.adoc

Configure the schema and GraphQLEntityViewSupportFactory for manual graphql-java integration.

```graphql
type Query {
    catById(id: ID!): CatWithOwnerView
}
```

```java
EntityViewManager evm = ...

// Read in the GraphQL schema
URL url = Resources.getResource("schema.graphqls");
String sdl = Resources.toString(url, StandardCharsets.UTF_8);
TypeDefinitionRegistry typeRegistry = new SchemaParser().parse(sdl);

// Configure how to integrate entity views
boolean defineNormalTypes = true;
boolean defineRelayTypes = true;
GraphQLEntityViewSupportFactory graphQLEntityViewSupportFactory = new GraphQLEntityViewSupportFactory(defineNormalTypes, defineRelayTypes);
graphQLEntityViewSupportFactory.setImplementRelayNode(false);
graphQLEntityViewSupportFactory.setDefineRelayNodeIfNotExist(true);

// Integrate and create the support class for extraction of EntityViewSetting objects
```

--------------------------------

### Subsequent Request with Keyset Pagination Parameters

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/deltaspike_data.adoc

Example of a subsequent GET request to fetch the next page, passing `lowest`, `highest`, and `prevPage` parameters derived from the previous response.

```http
GET /cats?page=1&size=3&sort=id,desc&prevPage=0&lowest={id:10}&highest={id:8}
{
    content: [
        { id: 7, name: 'Kitty', age: 1 },
        { id: 6, name: 'Bob', age: 8 },
        { id: 5, name: 'Frank', age: 14 }
    ]
}
```

--------------------------------

### Window Function Usage

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/jpql_functions.adoc

Example of invoking a window function with partition and filter clauses.

```text
WINDOW_AVG(c.age, 'FILTER', c.age > 10, 'PARTITION BY', c.name)
```

--------------------------------

### Setup EntityViewManager

Source: https://context7.com/blazebit/blaze-persistence/llms.txt

Configure and create an EntityViewManager instance. This is typically done once at application startup. Requires a CriteriaBuilderFactory (cbf).

```java
import com.blazebit.persistence.view.EntityViews;
import com.blazebit.persistence.view.EntityViewConfiguration;
import com.blazebit.persistence.view.EntityViewManager;
import com.blazebit.persistence.view.EntityViewSetting;

// Setup - typically done once at application startup
EntityViewConfiguration config = EntityViews.createDefaultConfiguration();
config.addEntityView(CatView.class);
config.addEntityView(CatDetailView.class);
config.addEntityView(SimpleCatView.class);
EntityViewManager evm = config.createEntityViewManager(cbf);
```

--------------------------------

### Set JAVA_HOME for PowerShell

Source: https://github.com/blazebit/blaze-persistence/blob/main/creating-a-release.md

Example of setting the JAVA_HOME environment variable in PowerShell to point to a JDK 8 installation.

```powershell
$env:JAVA_HOME="C:\\Program Files\\Java\\jdk-17.0.2"
```

--------------------------------

### Define EntityViewRoot with CorrelationProvider

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/mappings.adoc

Example of an interface using multiple EntityViewRoot configurations and a custom CorrelationProvider implementation.

```java
@EntityViewRoot(name = "v1", entity = Cat.class, condition = "id = VIEW(id)", joinType = JoinType.INNER)
@EntityViewRoot(name = "v2", expression = "Cat[id = VIEW(id)]", limit = "1", order = "id DESC")
@EntityViewRoot(name = "v3", correlator = CatView.TestCorrelator.class)
public interface CatView {

    @IdMapping
    Long getId();

    String getName();

    @Mapping("v1.name")
    String getV1Name();

    @Mapping("v2.name")
    String getV2Name();

    @Mapping("v3.name")
    String getV3Name();

    class TestCorrelator implements CorrelationProvider {
        @Override
        public void applyCorrelation(CorrelationBuilder correlationBuilder, String correlationExpression) {
            correlationBuilder.correlate(Cat.class)
                    .on(correlationBuilder.getCorrelationAlias()).eqExpression(correlationExpression)
                    .end();
        }
    }
}
```

--------------------------------

### Generated SQL Queries for Offset Pagination

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/pagination.adoc

The SQL queries generated by the offset pagination example.

```sql
SELECT COUNT(*)
FROM Cat cat
```

```sql
SELECT cat.id
FROM Cat cat
ORDER BY cat.id ASC NULLS LAST
--LIMIT 1 OFFSET 1
```

```sql
SELECT cat
FROM Cat cat
LEFT JOIN FETCH cat.kittens kittens_1
WHERE cat.id IN :idParams
ORDER BY cat.id ASC NULLS LAST
```

--------------------------------

### Controller for Keyset Pagination

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/spring_data.adoc

Example controller that uses a Keyset-Aware repository and the @KeysetConfig annotation to handle keyset pagination requests.

```java
@RestController
public class MyCatController {

    @Autowired
    private KeysetAwareCatViewRepository simpleCatViewRepository;

    @RequestMapping(path = "/cats", method = RequestMethod.GET)
    public Page<SimpleCatView> getCats(@KeysetConfig(Cat.class) KeysetPageable pageable) {
        return simpleCatViewRepository.findAll(pageable);
    }
}
```

--------------------------------

### Entity and Simple View Model

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/mappings.adoc

Base model definitions for indexed collection mapping examples.

```java
@Entity
class Cat {
    @Id
    Long id;

    int age;

    @OneToMany
    Set<Cat> kittens;
}

@EntityView(Cat.class)
interface SimpleCatView {
    @IdMapping
    Long getId();

    String getName();
}
```

--------------------------------

### Execute Offset Pagination

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/pagination.adoc

Example of performing offset pagination using the Criteria Builder API.

```java
PagedList<Cat> page2 = cbf.create(em, Cat.class)
    .fetch("kittens")
    .orderByAsc("id") // unique ordering is required for pagination
    .page(5, 5)
    .getResultList();
```

--------------------------------

### Configure MAVEN_OPTS for Windows

Source: https://github.com/blazebit/blaze-persistence/blob/main/creating-a-release.md

Example of configuring the MAVEN_OPTS environment variable on Windows to include memory settings for a large heap size.

```batch
set MAVEN_OPTS="-Xmx1536m -XX:MaxMetaspaceSize=512m"
```

--------------------------------

### Construct a simple CASE predicate

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/predicate_builder.adoc

Starts a simple case when builder using a specific expression.

```java
CriteriaBuilder<Cat> cb = cbf.create(em, Cat.class, "cat")
    .whereSimpleCase("SUBSTRING(cat.name, 1, 2)")
        .when("'Dr.'", "'Doctor'")
        .when("'Mr'", "'Mister'")
        .otherwise("'Unknown'")
    .notEqExpression("cat.fullTitle");
```

```sql
SELECT cat FROM Cat cat
WHERE CASE SUBSTRING(cat.name, 1, 2)
      WHEN 'Dr.' THEN 'Doctor'
      WHEN 'Mr.' THEN 'Mister'
      ELSE 'Unknown'
      END <> cat.fullTitle
```

--------------------------------

### Configure MicroProfile GraphQL Producer

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/graphql.adoc

Setup logic for integrating EntityViewSupport with the GraphQL schema builder.

```java
@ApplicationScoped
public class GraphQLProducer {

    @Inject
    EntityViewManager evm;

    GraphQLEntityViewSupport graphQLEntityViewSupport;

    void configure(@Observes GraphQLSchema.Builder schemaBuilder) {
        // Option 1: As of SmallRye GraphQL 1.3.1 you can disable the generation of GraphQL types and annotate all entity views with @Type instead
        // boolean defineNormalTypes = false;
        // boolean defineRelayTypes = false;

        // Option 2: Let the integration replace the entity view GraphQL types
        boolean defineNormalTypes = true;
        boolean defineRelayTypes = true;

        // Configure how to integrate entity views
        GraphQLEntityViewSupportFactory graphQLEntityViewSupportFactory = new GraphQLEntityViewSupportFactory(defineNormalTypes, defineRelayTypes);

        graphQLEntityViewSupportFactory.setImplementRelayNode(false);
        graphQLEntityViewSupportFactory.setDefineRelayNodeIfNotExist(true);
        graphQLEntityViewSupportFactory.setScalarTypeMap(GraphQLScalarTypes.getScalarMap());
        // Integrate and create the support class for extraction of EntityViewSetting objects
        this.graphQLEntityViewSupport = graphQLEntityViewSupportFactory.create(schemaBuilder, evm);
    }

    @Produces
    @ApplicationScoped
    GraphQLEntityViewSupport graphQLEntityViewSupport() {
        return graphQLEntityViewSupport;
    }
}
```

--------------------------------

### Passing Optional Parameters with EntityViewSettingProcessor

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/spring_data.adoc

Example of calling the repository method with an EntityViewSettingProcessor to set an optional parameter.

```java
simpleCatViewRepository.findAll(setting -> setting.withOptionalParameter("language", Locale.US));
```

--------------------------------

### Configure collection mapping defaults

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/updatable_entity_views.adoc

Examples demonstrating how collection relationships are handled, noting that they require specific annotations or setters to be considered updatable.

```java
@EntityView(Entity.class)
interface View {
    Set<String> getNames();
}
```

```java
@EntityView(Entity.class)
interface View {
    Set<String> getNames();
    void setNames(Set<String> names);
}
```

```java
@EntityView(Entity.class)
@UpdatableEntityView
interface View {
    Set<String> getNames();
    void setNames(Set<String> names);
}
```

```java
@EntityView(Entity.class)
@UpdatableEntityView
interface View {
    Set<java.util.Date> getDates(); // Mutable
}
```

```java
@EntityView(Entity.class)
@UpdatableEntityView
interface View {
    @UpdatableMapping(updatable = false)
    Set<String> getNames();
    void setNames(Set<String> names);
}
```

```java
@EntityView(Entity.class)
@UpdatableEntityView
interface View {
    @UpdatableMapping(updatable = false)
    Set<java.util.Date> getDates(); // Mutable
}
```

--------------------------------

### Produce EntityViewManager in Java EE

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/getting_started.adoc

Example of using CDI to inject configuration and create an EntityViewManager in a Java EE environment.

```java
@Singleton // from javax.ejb
@Startup   // from javax.ejb
public class EntityViewManagerProducer {

    // inject the configuration provided by the cdi integration
    @Inject
    private EntityViewConfiguration config;
    
    // inject the criteria builder factory which will be used along with the entity view manager
    @Inject
    private CriteriaBuilderFactory criteriaBuilderFactory;
```

--------------------------------

### Generated SQL for JOIN Fetch Strategy

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/mappings.adoc

Example of the SQL output generated when using the JOIN fetch strategy with a correlation provider.

```sql
SELECT cat.id, pers
FROM Cat cat
LEFT JOIN Person correlated_SameAgedPersons # <1>
       ON cat.age = correlated_SameAgedPersons.age # <2>
```

--------------------------------

### CatViewImpl Implementation

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/annotation_processor.adoc

An example of a generated entity view implementation for CatView, including additional fields like kittens.

```java
@StaticImplementation(CatView.class)
public class CatViewImpl implements CatView, EntityViewProxy {
    // Similar to SimpleCatViewImpl with some additions for kittens

    private final Set<SimpleCatView> kittens;

    @Override
    public Set<SimpleCatView> getKittens() {
        return kittens;
    }
}
```

--------------------------------

### GraphQL Query and Resulting JPQL

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/graphql.adoc

Example of a GraphQL query and the corresponding optimized JPQL query generated by the integration.

```graphql
query {
    findCatById(id: 1) {
        id
        name
    }
}
```

```sql
SELECT
    c.id,
    c.name
FROM Cat c
WHERE c.id = :param
```

--------------------------------

### Configure MAVEN_OPTS for PowerShell

Source: https://github.com/blazebit/blaze-persistence/blob/main/creating-a-release.md

Example of configuring the MAVEN_OPTS environment variable in PowerShell to include memory settings for a large heap size.

```powershell
$env:MAVEN_OPTS="-Xmx1536m -XX:MaxMetaspaceSize=512m"
```

--------------------------------

### Clone Blaze-Persistence Repository

Source: https://github.com/blazebit/blaze-persistence/blob/main/website/src/main/jbake/content/community.adoc

Clone the Blaze-Persistence repository from GitHub to start contributing. Ensure you have Git installed.

```bash
git clone git@github.com:USERNAME/blaze-persistence
cd blaze-persistence
```

--------------------------------

### Querying Pages with Keyset Pagination

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/pagination.adoc

Demonstrates how to query the first page, the next page, and the previous page using keyset pagination. Ensure unique ordering is defined for pagination to work correctly. The first page query falls back to offset pagination if `oldPage` is null.

```java
KeysetPage oldPage = null;
PagedList<Cat> page2 = cbf.create(em, Cat.class)
    .orderByAsc("birthday")
    .orderByAsc("id") // unique ordering is required for pagination
    .page(oldPage, 5, 5) #<1>
    .getResultList();

// Query the next page with the keyset page of page2
PagedList<Cat> page3 = cbf.create(em, Cat.class)
    .orderByAsc("birthday")
    .orderByAsc("id") // unique ordering is required for pagination
    .page(page2.getKeysetPage(), 10, 5) #<2>
    .getResultList();

// Query the previous page with the keyset page of page2
PagedList<Cat> page1 = cbf.create(em, Cat.class)
    .orderByAsc("birthday")
    .orderByAsc("id") // unique ordering is required for pagination
    .page(page2.getKeysetPage(), 0, 5) #<3>
    .getResultList();
```

--------------------------------

### Deploy Documentation to Production

Source: https://github.com/blazebit/blaze-persistence/blob/main/creating-a-release.md

This script deploys documentation changes to the production server. Use this after verifying the staging deployment.

```bash
./build-deploy-documentation.sh prod '-Djdk8.home=C:\\Program Files\\Eclipse Adoptium\\jdk-8.0.332.9-hotspot'
```

--------------------------------

### Build Nested Compound Predicate with OR and AND

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/predicate_builder.adoc

Starts a builder for a nested compound predicate where elements are connected with OR or AND. Use `whereAnd()` to start an AND group within an OR group.

```java
CriteriaBuilder<Cat> cb = cbf.create(em, Cat.class, "cat")
    .whereOr()
        .where("cat.name").isNull()
        .whereAnd()
            .where("LENGTH(cat.name)").gt(10)
            .where("cat.name").like().value("F%").noEscape()
        .endAnd()
    .endOr();
```

```sql
SELECT cat FROM Cat cat
WHERE cat.name IS NULL OR LENGTH(cat.name) > :param_1 AND cat.name LIKE :param_2
```

--------------------------------

### Build Blaze-Persistence Project

Source: https://github.com/blazebit/blaze-persistence/blob/main/website/src/main/jbake/content/community.adoc

Build the Blaze-Persistence project using Maven. Ensure you have a current version of Maven installed. This command cleans and packages the project.

```bash
mvn clean package
```

--------------------------------

### Deploy Documentation to Staging

Source: https://github.com/blazebit/blaze-persistence/blob/main/creating-a-release.md

This script deploys documentation changes to the staging server. Ensure the correct JDK is specified.

```bash
./build-deploy-documentation.sh staging '-Djdk8.home=C:\\Program Files\\Eclipse Adoptium\\jdk-8.0.332.9-hotspot'
```

--------------------------------

### Substring Extraction

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/expressions.adoc

Extracts a portion of a string starting at a 1-based index.

```java
CriteriaBuilder<String> cb = cbf.create(em, String.class)
    .from(Cat.class, "cat")
    .select("SUBSTRING(cat.name, 1, 2)");
```

```sql
SELECT SUBSTRING(cat.name, 1, 2)
FROM Cat cat
```

--------------------------------

### Select COALESCE expression

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/expressions.adoc

Example of a COALESCE expression used in a select clause.

```sql
SELECT COALESCE(cat.name, owner_1.name, 'default')
FROM Cat cat
LEFT JOIN cat.owner owner_1
```

--------------------------------

### JPQL Representation of ON Clause Query

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/from_clause.adoc

The resulting JPQL query for the ON clause examples.

```sql
SELECT localizedNameForLanguage
FROM Cat cat
LEFT JOIN cat.localizedName l10nName
       ON KEY(l10nName) = :lang
WHERE l10nName IS NOT NULL
```

--------------------------------

### Deploy Website to Staging

Source: https://github.com/blazebit/blaze-persistence/blob/main/creating-a-release.md

This script deploys website changes to the staging server. Ensure the correct JDK is specified.

```bash
./build-deploy-website.sh staging '-Djdk8.home=C:\\Program Files\\Eclipse Adoptium\\jdk-8.0.332.9-hotspot'
```

--------------------------------

### Deploy Website to Production

Source: https://github.com/blazebit/blaze-persistence/blob/main/creating-a-release.md

This script deploys website changes to the production server. Use this after verifying the staging deployment.

```bash
./build-deploy-website.sh prod '-Djdk8.home=C:\\Program Files\\Eclipse Adoptium\\jdk-8.0.332.9-hotspot'
```

--------------------------------

### Define Cat entity

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/querydsl.adoc

Example entity used for Querydsl integration demonstrations.

```java
@Entity
public class Cat {

    @Id
    private Long id;
    private String name;
    private Integer age;
}
```

--------------------------------

### Execute Private Release Deployment Script

Source: https://github.com/blazebit/blaze-persistence/blob/main/creating-a-release.md

This batch script is used to deploy a private release. Ensure the necessary JDKs are installed or the script is updated accordingly.

```batch
deploy-project-release.bat
```

--------------------------------

### Generate Java EE Sample Project

Source: https://github.com/blazebit/blaze-persistence/blob/main/README.md

Use this Maven command to generate a sample project for Java EE environments with Blaze Persistence.

```bash
mvn archetype:generate -DarchetypeGroupId=com.blazebit -DarchetypeArtifactId=blaze-persistence-archetype-java-ee-sample -DarchetypeVersion=1.6.18
```

--------------------------------

### Construct a simple WHERE predicate

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/predicate_builder.adoc

Starts a predicate builder with a specific expression on the left-hand side.

```java
CriteriaBuilder<Cat> cb = cbf.create(em, Cat.class, "cat")
    .where("name").eq("Felix");
```

```sql
SELECT cat FROM Cat cat
WHERE cat.name = :param_1
```

--------------------------------

### Define Indexed Collection Model

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/mappings.adoc

Example entity model with @OrderColumn and Map relationships.

```java
@Entity
class Cat {
    @Id
    Long id;

    @OneToMany
    @OrderColumn
    List<Cat> indexedKittens;

    @ManyToMany
    Map<Cat, Cat> kittensBestFriends;
}

@EntityView(Cat.class)
interface SimpleCatView {
    @IdMapping
    Long getId();

    String getName();
}
```

--------------------------------

### Generate Spring Boot Sample Project

Source: https://github.com/blazebit/blaze-persistence/blob/main/README.md

Use this Maven command to generate a sample project with Spring Boot integration for Blaze Persistence.

```bash
mvn archetype:generate -DarchetypeGroupId=com.blazebit -DarchetypeArtifactId=blaze-persistence-archetype-spring-boot-sample -DarchetypeVersion=1.6.18
```

--------------------------------

### Generate Entity View Sample Project

Source: https://github.com/blazebit/blaze-persistence/blob/main/README.md

Use this Maven command to generate a sample project with entity view support for Blaze Persistence.

```bash
mvn archetype:generate -DarchetypeGroupId=com.blazebit -DarchetypeArtifactId=blaze-persistence-archetype-entity-view-sample -DarchetypeVersion=1.6.18
```

--------------------------------

### Query Type Expression

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/expressions.adoc

Example of filtering by entity type using the TYPE operator.

```sql
SELECT cat
FROM Cat cat
WHERE TYPE(cat.status) = org.mypackage.Status.ALIVE
```

--------------------------------

### Generate Core-only Jakarta Sample Project

Source: https://github.com/blazebit/blaze-persistence/blob/main/README.md

Use this Maven command to generate a core-only sample project for Blaze Persistence with Jakarta EE compatibility.

```bash
mvn archetype:generate -DarchetypeGroupId=com.blazebit -DarchetypeArtifactId=blaze-persistence-archetype-core-sample-jakarta -DarchetypeVersion=1.6.18
```

--------------------------------

### JPQL Representation of Join Query

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/from_clause.adoc

The resulting JPQL query for the entity join example.

```sql
SELECT c.name, COUNT(p.id)
FROM Cat c
LEFT JOIN Person p
       ON c.age < p.age
GROUP BY c.id, c.name
```

--------------------------------

### Generate Core-only Sample Project

Source: https://github.com/blazebit/blaze-persistence/blob/main/README.md

Use this Maven command to generate a core-only sample project for Blaze Persistence.

```bash
mvn archetype:generate -DarchetypeGroupId=com.blazebit -DarchetypeArtifactId=blaze-persistence-archetype-core-sample -DarchetypeVersion=1.6.18
```

--------------------------------

### IS NOT NULL Predicate (Java)

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/predicate_builder.adoc

Example of checking if a field is not null using the IS NOT NULL predicate.

```java
CriteriaBuilder<Cat> cb = cbf.create(em, Cat.class, "cat")
    .where("cat.age").isNotNull();
```

--------------------------------

### Deploy Maven Release

Source: https://github.com/blazebit/blaze-persistence/blob/main/creating-a-release.md

Execute this command to deploy the prepared Maven release. It includes the same profile and argument configurations as the prepare step, with an added retry mechanism for failed deployments.

```bash
mvnw -P "blazebit-release,h2,hibernate-5.6,deltaspike-1.9,spring-data-2.7.x" release:perform "-Darguments=-DskipTests -DskipITs '-Djdk8.home=C:\\Program Files\\Eclipse Adoptium\\jdk-8.0.332.9-hotspot' -DretryFailedDeploymentCount=10"
```

--------------------------------

### Generated JPQL for getCountQuery

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/query_api.adoc

Example of the JPQL produced when invoking getCountQuery on a criteria builder.

```sql
SELECT COUNT(*)
FROM Cat cat
LEFT JOIN cat.kittens
WHERE cat.name = :param_0
```

--------------------------------

### Prepare Local Maven Release

Source: https://github.com/blazebit/blaze-persistence/blob/main/creating-a-release.md

Use this command to prepare a local Maven release. Ensure your Maven settings.xml is configured with credentials and profiles, and JAVA_HOME and MAVEN_OPTS are set appropriately. This command skips tests and integration tests.

```bash
mvnw -P "blazebit-release,h2,hibernate-5.6,deltaspike-1.9,spring-data-2.7.x" release:clean release:prepare "-Darguments=-DskipTests -DskipITs '-Djdk8.home=C:\\Program Files\\Eclipse Adoptium\\jdk-8.0.332.9-hotspot'"
```

--------------------------------

### Initial Object Query for Keyset Pagination

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/pagination.adoc

The initial SQL query selects the main entity and the expressions used for constructing the keyset, which correspond to the `ORDER BY` clause. This query is generated when fetching the first page or when keyset pagination falls back to offset pagination.

```sql
SELECT cat, cat.birthday, cat.id #<1>
FROM Cat cat
ORDER BY cat.birthday ASC NULLS LAST, cat.id ASC NULLS LAST
--LIMIT 5 OFFSET 5
```

--------------------------------

### Nested set operation initiation

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/architecture.adoc

Starts a nested set operation group resulting in a StartOngoingSetOperationXXXBuilder.

```java
criteriaBuilder.from(Cat.class)
    .startUnionAll() #<1>
```

--------------------------------

### Initialize CriteriaBuilderFactory and Create Query Builders

Source: https://context7.com/blazebit/blaze-persistence/llms.txt

The `CriteriaBuilderFactory` is the main entry point for creating query builders. It should be initialized once with the `EntityManagerFactory`. This example shows how to create SELECT, DELETE, UPDATE, and INSERT queries.

```java
import com.blazebit.persistence.Criteria;
import com.blazebit.persistence.CriteriaBuilderConfiguration;
import com.blazebit.persistence.CriteriaBuilderFactory;
import javax.persistence.EntityManagerFactory;
import javax.persistence.Persistence;

// Setup - typically done once at application startup
EntityManagerFactory emf = Persistence.createEntityManagerFactory("MyPU");
CriteriaBuilderConfiguration config = Criteria.getDefault();
CriteriaBuilderFactory cbf = config.createCriteriaBuilderFactory(emf);

// Create a SELECT query
CriteriaBuilder<Cat> cb = cbf.create(em, Cat.class);
List<Cat> cats = cb.getResultList();

// Create a SELECT query with custom alias
CriteriaBuilder<Cat> cb = cbf.create(em, Cat.class, "c");
List<Cat> cats = cb.where("c.name").like().value("Felix%").noEscape().getResultList();

// Create a DELETE query
DeleteCriteriaBuilder<Cat> dcb = cbf.delete(em, Cat.class);
int deletedCount = dcb.where("age").gt(10).executeUpdate();

// Create an UPDATE query
UpdateCriteriaBuilder<Cat> ucb = cbf.update(em, Cat.class);
int updatedCount = ucb.set("name", "Updated")
    .where("age").lt(5)
    .executeUpdate();

// Create an INSERT query (INSERT ... SELECT)
InsertCriteriaBuilder<Cat> icb = cbf.insert(em, Cat.class);
int insertedCount = icb.from(OldCat.class, "o")
    .bind("name").select("o.name")
    .bind("age").select("o.age")
    .executeUpdate();
```

--------------------------------

### Subquery Mapping SQL Output

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/mappings.adoc

The resulting SQL query produced by the subquery mapping example.

```sql
SELECT
    cat.id,
    (
        SELECT COUNT(*)
        FROM Cat subCat
        WHERE subCat.father.id = cat.id
           OR subCat.mother.id = cat.id
    )
FROM Cat cat
```

--------------------------------

### Initialize CriteriaBuilderFactory in Java SE

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/getting_started.adoc

Obtain a CriteriaBuilderFactory instance using the default configuration provider. The factory should be built only once at startup.

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

--------------------------------

### Keyset Pagination with page() Method

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/pagination.adoc

Implement keyset pagination using `page(KeysetPage keysetPage, int firstResult, int maxResults)`. This method attempts keyset pagination and falls back to offset pagination if keyset is not possible.

```java
FullQueryBuilder<Cat, ?> page(com.blazebit.persistence.KeysetPage keysetPage, int firstResult, int maxResults)
```

--------------------------------

### STRING_XML_AGG output format

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/jpql_functions.adoc

Example structure of the XML string produced by the STRING_XML_AGG aggregate function.

```xml
<e>
    <key1>value1</key1>
    ...
    <keyN>valueN</keyN>
</e>
<e>
    ...
</e>
...
```

--------------------------------

### Configure Select Fetch Strategy with VIEW_ROOT/EMBEDDING_VIEW

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/fetch_strategies.adoc

Example demonstrating the use of `@BatchFetch` with `FetchStrategy.SELECT` and `CorrelationProvider` for correlated attributes. This configuration handles batching when using `VIEW_ROOT` or `EMBEDDING_VIEW` functions, adapting to data cardinality to minimize queries.

```java
@EntityView(Cat.class)
public interface CatView {

    @IdMapping
    Long getId();

    Set<KittenCatView> getKittens();

}

@EntityView(Cat.class)
public interface KittenCatView {

    @IdMapping
    Long getId();

    @BatchFetch(20)
    @MappingCorrelated(
        correlationBasis = "age",
        correlator = CatAgeCorrelationProvider.class,
        fetch = FetchStrategy.SELECT
    )
    Set<Cat> getSameAgedCats();

    static class CatAgeCorrelationProvider implements CorrelationProvider {

        @Override
        public void applyCorrelation(CorrelationBuilder builder, String correlationExpression) {
            final String correlatedCat = builder.getCorrelationAlias();
            builder.correlate(Cat.class)
                .on(correlatedCat + ".age").inExpressions(correlationExpression)
                .on(correlatedCat + ".id").notInExpressions("VIEW_ROOT(id)")
            .end();
        }

    }
}
```

--------------------------------

### STRING_JSON_AGG output format

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/jpql_functions.adoc

Example structure of the JSON string produced by the STRING_JSON_AGG aggregate function.

```json
[
    {
        "key1": "value1",
        ...
        "keyN": "valueN"
    },...
]
```

--------------------------------

### Equivalent SQL Projection

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/select_clause.adoc

Represents the underlying SQL projection logic for the provided Java examples.

```sql
SELECT cat.name, cat.age
FROM Cat cat
```

--------------------------------

### Defining and Reusing Named Windows

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/window_functions.adoc

Shows how to define a named window and reuse it across multiple select clauses.

```java
CriteriaBuilder<Tuple> criteria = cbf.create(em, Tuple.class)
    .from(Person.class, "per")
    .window("x").orderByAsc("per.age").rows().betweenUnboundedPreceding().andCurrentRow().end()
    .select("MIN(per.age) OVER (x)")
    .select("MAX(per.age) OVER (x)")
```

--------------------------------

### Generate Spring Data Sample Project

Source: https://github.com/blazebit/blaze-persistence/blob/main/README.md

Use this Maven command to generate a sample project integrated with Spring Data for Blaze Persistence.

```bash
mvn archetype:generate -DarchetypeGroupId=com.blazebit -DarchetypeArtifactId=blaze-persistence-archetype-spring-data-sample -DarchetypeVersion=1.6.18
```

--------------------------------

### Construct a subquery predicate

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/predicate_builder.adoc

Starts a subquery builder for a predicate with the resulting subquery expression on the left-hand side.

```java
CriteriaBuilder<Cat> cb = cbf.create(em, Cat.class, "cat")
    .whereSubquery()
        .from(Cat.class, "subCat")
        .select("subCat.name")
        .where("subCat.id").eq(123)
    .end()
    .eqExpression("cat.name");
```

```sql
SELECT cat FROM Cat cat
WHERE (SELECT subCat.name FROM Cat subCat WHERE subCat.id = :param_1) = cat.name
```

--------------------------------

### Generated SQL for Entity Update

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/updatable_entity_views.adoc

Example of the SQL query generated when flushing an update to an entity relation.

```sql
UPDATE Cat cat
SET cat.father = :father
WHERE cat.id = :id
```

--------------------------------

### Generate Entity View Jakarta Sample Project

Source: https://github.com/blazebit/blaze-persistence/blob/main/README.md

Use this Maven command to generate a sample project with entity view support for Blaze Persistence, compatible with Jakarta EE.

```bash
mvn archetype:generate -DarchetypeGroupId=com.blazebit -DarchetypeArtifactId=blaze-persistence-archetype-entity-view-sample-jakarta -DarchetypeVersion=1.6.18
```

--------------------------------

### Order by using shorthand methods

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/order_by_clause.adoc

Demonstrates using orderByAsc and orderByDesc to sort results with default null precedence.

```java
CriteriaBuilder<Tuple> cb = cbf.create(em, Tuple.class)
    .from(Cat.class)
    .select("age")
    .select("id")
    .orderByAsc("age")
    .orderByDesc("id");
```

```sql
SELECT cat.age, cat.id
FROM Cat cat
ORDER BY
    cat.age ASC NULLS LAST,
    cat.id DESC NULLS LAST
```

--------------------------------

### SQL for Inserting Collection Entries

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/dml_statements.adoc

This SQL demonstrates the logical structure for inserting collection entries, showing how data is selected and inserted into the target collection.

```sql
INSERT INTO Cat.kittens(id, kittens.id)
SELECT :param_1, kittens_1.id
FROM Cat c
LEFT JOIN c.kittens kittens_1
WHERE c.id = :param_2
```

--------------------------------

### Implicit Group By Generation Example

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/group_by_having_clause.adoc

Demonstrates how Blaze-Persistence automatically generates a GROUP BY clause for non-aggregate expressions.

```java
CriteriaBuilder<Tuple> cb = cbf.create(em, Tuple.class)
    .from(Cat.class)
    .select("age")
    .select("COUNT(*)");
```

```sql
SELECT cat.age, COUNT(*)
FROM Cat cat
GROUP BY cat.age
```

--------------------------------

### Implement Pagination with Blaze-Persistence

Source: https://context7.com/blazebit/blaze-persistence/llms.txt

Demonstrates offset-based pagination, navigation to specific entities, keyset pagination for large datasets, and pagination with custom identifier expressions.

```java
import com.blazebit.persistence.PaginatedCriteriaBuilder;
import com.blazebit.persistence.PagedList;
import com.blazebit.persistence.KeysetPage;

// Offset-based pagination
PaginatedCriteriaBuilder<Cat> pcb = cbf.create(em, Cat.class)
    .orderByAsc("id")
    .page(0, 10);  // firstResult=0, maxResults=10

PagedList<Cat> page1 = pcb.getResultList();
System.out.println("Total count: " + page1.getTotalSize());
System.out.println("Total pages: " + page1.getTotalPages());
System.out.println("Current page: " + (page1.getFirstResult() / page1.getMaxResults() + 1));

// Navigate to page containing specific entity
PaginatedCriteriaBuilder<Cat> pcb = cbf.create(em, Cat.class)
    .orderByAsc("id")
    .pageAndNavigate(entityId, 10);  // Find page containing entity with given ID

// Keyset pagination for better performance with large datasets
PagedList<Cat> firstPage = cbf.create(em, Cat.class)
    .orderByAsc("id")
    .page(0, 10)
    .getResultList();

KeysetPage keysetPage = firstPage.getKeysetPage();

// Get next page using keyset
PagedList<Cat> nextPage = cbf.create(em, Cat.class)
    .orderByAsc("id")
    .page(keysetPage, 10, 10)  // keysetPage, firstResult=10, maxResults=10
    .getResultList();

// Pagination with custom identifier expression (for queries with joins)
PaginatedCriteriaBuilder<Cat> pcb = cbf.create(em, Cat.class)
    .leftJoinFetch("kittens", "k")
    .orderByAsc("id")
    .pageBy(0, 10, "id");  // Paginate by cat.id, not by result rows
```

--------------------------------

### Construct a general CASE WHEN predicate

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/predicate_builder.adoc

Starts a general case when builder for a predicate with the resulting expression on the left-hand side.

```java
CriteriaBuilder<Cat> cb = cbf.create(em, Cat.class, "cat")
    .whereCase()
        .when("cat.name").isNull()
            .then(1)
        .when("LENGTH(cat.name)").gt(10)
            .then(2)
        .otherwise(3)
    .eqExpression(":someValue");
```

```sql
SELECT cat FROM Cat cat
WHERE CASE
      WHEN cat.name IS NULL THEN :param_1
      WHEN LENGTH(cat.name) > 10 THEN :param_2
      ELSE :param_3
      END = :someValue
```

--------------------------------

### GraphQL Query for First Page

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/graphql.adoc

A sample GraphQL query requesting the first element with specific fields and page information.

```graphql
query {
  findAll(first: 1){
    edges {
      node {
        id
        name
      }
    }
    pageInfo {
      startCursor
      endCursor
    }
  }
}
```

--------------------------------

### Logical JPQL Statements for Cascading Delete

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/updatable_entity_views.adoc

Example of the logical JPQL operations performed during a cascading delete process.

```sql
DELETE Cat(nickNames) cat WHERE cat.id = :catId
DELETE Cat cat WHERE cat.id = :catId RETURNING owner.id
DELETE Person person WHERE person.id = :ownerId
```

--------------------------------

### Generate DeltaSpike Data Sample Project

Source: https://github.com/blazebit/blaze-persistence/blob/main/README.md

Use this Maven command to generate a sample project with DeltaSpike Data support for Blaze Persistence.

```bash
mvn archetype:generate -DarchetypeGroupId=com.blazebit -DarchetypeArtifactId=blaze-persistence-archetype-deltaspike-data-sample -DarchetypeVersion=1.6.18
```

--------------------------------

### Execute simple BlazeJPAQuery

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/querydsl.adoc

Demonstrates basic selection and filtering using BlazeJPAQuery.

```java
QCat cat = QCat.cat;

BlazeJPAQuery<Tuple> query = new BlazeJPAQuery<Tuple>(entityManager, criteriaBuilderFactory).from(cat)
    .select(cat.name.as("name"), cat.name.substring(2))
    .where(cat.name.length().gt(1));

List<Tuple> fetch = query.fetch();
```

--------------------------------

### Configure JPA embeddable type mappings

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/updatable_entity_views.adoc

Examples for mapping JPA embeddable types within entity views.

```java
@EntityView(Entity.class)
interface View {
    Set<Embeddable> getEmbeddables();
}
```

```java
@EntityView(Entity.class)
interface View {
    Set<Embeddable> getEmbeddables();
    void setEmbeddable(Set<Embeddable> set);
}
```

```java
@EntityView(Entity.class)
@UpdatableEntityView
interface View {
    Set<Embeddable> getEmbeddables();
}
```

```java
@EntityView(Entity.class)
@UpdatableEntityView
interface View {
    Set<Embeddable> getEmbeddables();
    void setEmbeddable(Set<Embeddable> set);
}
```

```java
@EntityView(Entity.class)
@UpdatableEntityView
interface View {
    @UpdatableMapping(updatable = false)
    Set<Embeddable> getEmbeddables();
    void setEmbeddable(Set<Embeddable> set);
}
```

```java
@EntityView(Entity.class)
```

--------------------------------

### Configure CriteriaBuilderFactory in Java EE

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/getting_started.adoc

Uses a startup EJB and a CDI producer to initialize the factory in a Java EE environment.

```java
@Singleton // From javax.ejb
@Startup   // From javax.ejb
public class CriteriaBuilderFactoryProducer {

    // inject your entity manager factory
    @PersistenceUnit
    private EntityManagerFactory entityManagerFactory;
    
    private CriteriaBuilderFactory criteriaBuilderFactory;
    
    @PostConstruct
    public void init() {
        CriteriaBuilderConfiguration config = Criteria.getDefault();
        // do some configuration
        this.criteriaBuilderFactory = config.createCriteriaBuilderFactory(entityManagerFactory);
    }
    
    @Produces
    @ApplicationScoped
    public CriteriaBuilderFactory createCriteriaBuilderFactory() {
        return criteriaBuilderFactory;
    }
}
```

--------------------------------

### Define a basic updatable entity view

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/updatable_entity_views.adoc

Example of a basic updatable entity view interface with an ID mapping.

```java
@EntityView(Entity2.class)
@UpdatableEntityView
interface View2 {
    @IdMapping
    Integer getId();
    String getName();
    void setName(String name);
}
```

--------------------------------

### Define Subview Mappings

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/updatable_entity_views.adoc

An example showing how to map a relationship as a subview where the relationship role is updatable but the subview type itself is not.

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

    String getName();
}

@UpdatableEntityView
@EntityView(Cat.class)
interface CatUpdateView {
    @IdMapping
    Long getId();

    String getName();

    PersonView getOwner();
    void setOwner(PersonView owner);
}
```

--------------------------------

### Initialize EntityViewManager in Java SE

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/getting_started.adoc

Manual creation of EntityViewConfiguration and EntityViewManager for Java SE environments.

```java
EntityViewConfiguration cfg = EntityViews.createDefaultConfiguration();
cfg.addEntityView(EntityView1.class);
// Add some more
cfg.addEntityView(EntityViewn.class);
EntityViewManager evm = cfg.createEntityViewManager(criteriaBuilderFactory);
```

--------------------------------

### Quantified Subquery Predicate (Java)

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/core/manual/en_US/predicate_builder.adoc

Demonstrates using quantified subqueries with comparison predicates like NOT EQ and GE.

```java
CriteriaBuilder<Cat> cb = cbf.create(em, Cat.class, "cat")
    .where("cat.age").notEq(10)
    .where("cat.age").ge().all()
        .from(Cat.class, "subCat")
        .select("subCat.age")
    .end();
```

--------------------------------

### Keyset Pagination with Entity Views

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/querying_and_pagination_api.adoc

Enrich an `EntityViewSetting` with a `KeysetPage` using `withKeysetPage(previousKeysetPage)` to enable keyset pagination. Remember to store the `KeysetPage` from the result to use for subsequent requests.

```java
EntityViewSetting<CatView, PaginatedCriteriaBuilder<CatView>> setting;

int maxResults = ...; // elements per page
int firstResult = ...; // (pageNumber - 1) * elementsPerPage

setting = EntityViewSetting.create(CatView.class, firstResult, maxResults);
// Apply filters and sorters on setting

setting.withKeysetPage(previousKeysetPage);

PagedList<CatView> list = catDataAccess.findAll(setting);
previousKeysetPage = list.getKeysetPage();
```

--------------------------------

### SimpleCatViewImpl Constructors

Source: https://github.com/blazebit/blaze-persistence/blob/main/documentation/src/main/asciidoc/entity-view/manual/en_US/annotation_processor.adoc

Explains the different constructors for SimpleCatViewImpl, including the create-constructor, id-reference constructor, full state constructor, and internal runtime constructors.

```java
public SimpleCatViewImpl(SimpleCatViewImpl noop, Map<String, Object> optionalParameters)
    // ...
public SimpleCatViewImpl(Long id)
    // ...
public SimpleCatViewImpl(Long id, String name)
    // ...
public SimpleCatViewImpl(SimpleCatViewImpl noop, int offset, Object[] tuple)
    // ...
public SimpleCatViewImpl(SimpleCatViewImpl noop, int offset, int[] assignment, Object[] tuple)
```