Using Blaze-Persistence

Blaze-Persistence 提供一个流畅的查询构建器 API，在 Jakarta Persistence 之上，利用深入的 Hibernate ORM 集成，可以在 Jakarta Persistence 模型的范围内使用高级 SQL 功能，比如常用表格表达式。 除此之外，Blaze-Persistence Entity-View 模块允许进行 DTO 定义，可以将其应用于业务逻辑查询，然后将这些查询转换为优化的查询，仅提取构建 DTO 实例所需的数据。相同的 DTO 定义还可以用于应用数据库更新，从而大幅减少样板代码，并且不需要对象映射工具。 :iokays-category: quarkus :iokays-path: modules/ROOT/pages/_includes/platform-include.adoc :keywords: Quarkus, 中文文档, 编程技术

此扩展由第三方开发并属于 Quarkus Platform。

Setting up and configuring Blaze-Persistence

该扩展为 CriteriaBuilderFactory 和 EntityViewManager 附带有默认的生产者，这些生产者在提供一个可用的 Hibernate ORM 配置时可以开箱即用。对于定制，可以通过 Quarkus CDI reference 中记录的标准机制覆盖默认生产者。如果您需要设置自定义的 Blaze-Persistence properties，则需要这样做。

在 Quarkus 中，您只需：

  • 使用 @Inject``CriteriaBuilderFactory`或 `EntityViewManager，并照常使用它

  • 使用 `@EntityView`和任何其他映射注释对实体视图进行注释

添加以下依赖关系到您的项目：

  • the Blaze-Persistence extension: com.blazebit:blaze-persistence-integration-quarkus-3

  • 根据需要进一步集成 Blaze-Persistence：

Example dependencies using Maven
<!-- Blaze-Persistence specific dependencies -->
<dependency>
    <groupId>com.blazebit</groupId>
    <artifactId>blaze-persistence-integration-quarkus-3</artifactId>
</dependency>
<dependency>
    <groupId>com.blazebit</groupId>
    <artifactId>blaze-persistence-integration-hibernate-6.2</artifactId>
    <scope>runtime</scope>
</dependency>
Using Gradle
implementation("com.blazebit:blaze-persistence-integration-quarkus-3")
runtimeOnly("com.blazebit:blaze-persistence-integration-hibernate-6.2")

在本地映像中使用需要依赖项实体视图注释处理器，该处理器可能提取到一个单独的 `native`配置文件中：

<profiles>
    <profile>
        <id>native</id>
        <dependencies>
            <dependency>
                <groupId>com.blazebit</groupId>
                <artifactId>blaze-persistence-entity-view-processor-jakarta</artifactId>
                <scope>provided</scope>
            </dependency>
        </dependencies>
    </profile>
</profiles>

根据通过 Hibernate-ORM extension提供的已配置 EntityManagerFactory，将创建 CriteriaBuilderFactory`和 `EntityViewManager。

您之后可以通过注入访问这些 Bean：

Example application bean using Hibernate
@ApplicationScoped
public class SantaClausService {
    @Inject
    EntityManager em; 1
    @Inject
    CriteriaBuilderFactory cbf; 2
    @Inject
    EntityViewManager evm; 3

    @Transactional 4
    public List<GiftView> findAllGifts() {
        CriteriaBuilder<Gift> cb = cbf.create(em, Gift.class);
        return evm.applySetting(EntityViewSetting.create(GiftView.class), cb).getResultList();
    }
}
1 Inject the EntityManager
2 Inject the CriteriaBuilderFactory
3 Inject the EntityViewManager
4 将您的 CDI Bean 方法标记为 @Transactional，以启动或加入事务。
Example Entity
@Entity
public class Gift {
    private Long id;
    private String name;
    private String description;

    @Id @GeneratedValue(strategy = GenerationType.SEQUENCE, generator="giftSeq")
    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }


    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }
}
Example Entity-View
@EntityView(Gift.class)
public interface GiftView {

    @IdMapping
    Long getId();

    String getName();
}
Example updatable Entity-View
@UpdatableEntityView
@CreatableEntityView
@EntityView(Gift.class)
public interface GiftUpdateView extends GiftView {

    void setName(String name);
}
Example Jakarta REST Resource
@Path("/gifts")
public class GiftResource {
    @Inject
    EntityManager entityManager;
    @Inject
    EntityViewManager entityViewManager;
    @Inject
    SantaClausService santaClausService;

    @POST
    @Transactional
    public Response createGift(GiftUpdateView view) {
        entityViewManager.save(entityManager, view);
        return Response.created(URI.create("/gifts/" + view.getId())).build();
    }

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public List<GiftView> getGifts() {
        return santaClausService.findAllGifts();
    }

    @PUT
    @Path("{id}")
    @Transactional
    public GiftView updateGift(@EntityViewId("id") GiftUpdateView view) {
        entityViewManager.save(entityManager, view);
        return entityViewManager.find(entityManager, GiftView.class, view.getId());
    }

    @GET
    @Path("{id"})
    @Produces(MediaType.APPLICATION_JSON)
    public GiftView getGift(Long id) {
        return return entityViewManager.find(entityManager, GiftView.class, view.getId());
    }
}

Blaze-Persistence configuration properties

有各种可选属性可用于优化您的 EntityViewManager`和 `CriteriaBuilderFactory，或指导 Quarkus 的猜测。

只要 Hibernate ORM 扩展配置正确，就没有必需属性。

如果没有设置属性，则应用 Blaze-Persistence 默认值。

此处列出的配置属性允许您覆盖这些默认值，并自定义和调整各个方面。

在构建时固定的配置属性——所有其他配置属性都可以在运行时覆盖

[id="quarkus-blaze-persistence_configuration"]Configuration property

Type

Default

[id="quarkus-blaze-persistence_quarkus.blaze-persistence.template-eager-loading"]` quarkus.blaze-persistence.template-eager-loading[style="open",role="description"]一个布尔标志，用于在启动时准备所有视图模板缓存。默认情况下，禁用视图模板的急切加载以获得更好的启动性能。此属性的有效值为 `true`或 `false。

boolean

[id="quarkus-blaze-persistence_quarkus.blaze-persistence.default-batch-size"]` quarkus.blaze-persistence.default-batch-size`[style="open",role="description"]一个整数值，用于定义实体视图属性的默认批量大小。默认情况下，值为 1，可以通过 `com.blazebit.persistence.view.BatchFetch#size()`或通过 `com.blazebit.persistence.view.EntityViewSetting#setProperty`设置此属性来覆盖。

int

[id="quarkus-blaze-persistence_quarkus.blaze-persistence.expect-batch-mode"]` quarkus.blaze-persistence.expect-batch-mode[style="open",role="description"]一个模式，用于指定是否需要关联值、视图根或嵌入式视图批量处理。默认情况下，值为 `values，可以通过 com.blazebit.persistence.view.EntityViewSetting#setProperty`设置此属性来覆盖。有效值为 - `values - view_roots - embedding_views

string

[id="quarkus-blaze-persistence_quarkus.blaze-persistence.updater.eager-loading"]` quarkus.blaze-persistence.updater.eager-loading[style="open",role="description"]一个布尔标志，用于在启动时准备实体视图更新器缓存。默认情况下，禁用实体视图更新的急切加载以获得更好的启动性能。此属性的有效值为 `true`或 `false。

boolean

[id="quarkus-blaze-persistence_quarkus.blaze-persistence.updater.disallow-owned-updatable-subview"]` quarkus.blaze-persistence.updater.disallow-owned-updatable-subview[style="open",role="description"]一个布尔标志，用于禁用严格验证，该验证不允许将可更新实体视图类型用于拥有的关系。默认情况下不允许使用，即默认值为 `true，但由于可能存在奇怪的模型，因此可以允许这样做。此属性的有效值为 true`或 `false。

boolean

[id="quarkus-blaze-persistence_quarkus.blaze-persistence.updater.strict-cascading-check"]` quarkus.blaze-persistence.updater.strict-cascading-check[style="open",role="description"]一个布尔标志，用于禁用严格级联检查，该检查不允许在与级联属性关联之前在非级联属性上设置可更新或可创建实体视图。在禁用时，就有可能（就像在 Jakarta Persistence 中一样），对可更新实体视图进行的更改在未与级联更新的属性关联时不会刷新。默认情况下，启用使用，即默认值为 `true。此属性的有效值为 true`或 `false。

boolean

[id="quarkus-blaze-persistence_quarkus.blaze-persistence.updater.error-on-invalid-plural-setter"]` quarkus.blaze-persistence.updater.error-on-invalid-plural-setter[style="open",role="description"]一个布尔标志，它允许在启用严格级联检查时遇到无效复数属性设置器时从警告切换到启动时验证错误。当 `true 时，在遇到无效设置器时会引发启动时验证错误，否则只会发出警告。当禁用严格级联检查时，此配置无效。默认情况下，禁用使用，即默认值为 false。此属性的有效值为 true`或 `false。

boolean

[id="quarkus-blaze-persistence_quarkus.blaze-persistence.create-empty-flat-views"]` quarkus.blaze-persistence.create-empty-flat-views[style="open",role="description"]一个布尔标志，允许指定如果未通过 `EmptyFlatViewCreation`指定，是否应默认创建扁平视图。默认情况下，启用创建扁平视图，即默认值为 `true。此属性的有效值为 true`或 `false。

boolean

[id="quarkus-blaze-persistence_quarkus.blaze-persistence.expression-cache-class"]` quarkus.blaze-persistence.expression-cache-class`[style="open",role="description"]完全限定的表达式缓存实施类名称。

string

[id="quarkus-blaze-persistence_quarkus.blaze-persistence.inline-ctes"]` quarkus.blaze-persistence.inline-ctes[style="open",role="description"]如果设置为 true，则默认内联 CTE 查询。此属性的有效值为 `true、false`或 `auto。默认值为 true，它始终会内联非递归 CTE。`auto`配置仅在 Jakarta Persistence 提供程序和 DBMS 方言支持/需要时使用内联。可以在构造查询之前为条件生成器更改此属性。

boolean

除这些配置选项外，还可以通过观察事件 `CriteriaBuilderConfiguration`或 `EntityViewConfiguration`并对这些对象应用自定义，来应用进一步的配置和自定义。可在 Quarkus section of the entity-view documentation中找到各种自定义用例。

Example CriteriaBuilderConfiguration and EntityViewConfiguration observing
@ApplicationScoped
public class BlazePersistenceConfigurer {

    public void configure(@Observes CriteriaBuilderConfiguration config) {
        config.setProperty("...", "...");
    }

    public void configure(@Observes EntityViewConfiguration config) {
        // Register custom BasicUserType or register type test values
        config.registerBasicUserType(MyClass.class, MyClassBasicUserType.class);
    }
}

Limitations

Apache Derby

Blaze-Persistence currently does not come with support for Apache Derby. This limitation could be lifted in the future, if there’s a compelling need for it and if someone contributes it.