The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

Blaze-Persistenceの使用

Blaze-Persistenceは、Hibernate ORMとの深い統合により、JPAの上に流れるようなクエリビルダAPIを提供し、JPAモデルの範囲内でありながら、共通テーブル式のような高度なSQL機能の使用を可能にします。

さらに、Blaze-Persistence Entity-Viewモジュールは、ビジネスロジッククエリに適用出来るDTO定義を可能にし、そのクエリはDTOインスタンスを構築するために必要なデータのみを取得する最適化されたクエリに変換されます。同じDTO定義をデータベースの更新にも使用することができます。これにより、ボイラプレートコードが大幅に削減され、オブジェクトマッピングツールの必要性がなくなります。

このエクステンションはサードパーティによって開発されたもので、Quarkus Platformの一部です。

Blaze-Persistenceのセットアップと設定

このエクステンションには、 CriteriaBuilderFactoryEntityViewManager のデフォルトプロデューサーが付属しており、動作する Hibernate ORM 設定があればすぐに動作します。カスタマイズのために、 Quarkus CDIリファレンスに記載されている標準的なメカニズムを使用して、デフォルトのプロデューサーをオーバーライドすることができます。これは、カスタムの Blaze-Persistenceプロパティーを設定する場合に必要です。

Quarkusでは、以下を実施するだけです:

  • CriteriaBuilderFactory または EntityViewManager@Inject し、使用します

  • エンティティービューに @EntityView やその他のマッピングアノテーションを通常通りにアノテーションします

以下の依存関係をプロジェクトに追加してください:

  • Blaze-Persistence エクステンション: com.blazebit:blaze-persistence-integration-quarkus

  • 必要に応じて、さらにBlaze-Persistenceの統合を行います:

    • Jackson の為に blaze-persistence-integration-jackson

    • JAX-RSの為に blaze-persistence-integration-jaxrs

Mavenを使った依存関係の例
<!-- Blaze-Persistence specific dependencies -->
<dependency>
    <groupId>com.blazebit</groupId>
    <artifactId>blaze-persistence-integration-quarkus</artifactId>
</dependency>
<dependency>
    <groupId>com.blazebit</groupId>
    <artifactId>blaze-persistence-integration-hibernate-5.6</artifactId>
    <scope>runtime</scope>
</dependency>
Gradleの使用
implementation("com.blazebit:blaze-persistence-integration-quarkus")
runtimeOnly("com.blazebit:blaze-persistence-integration-hibernate-5.6")

ネイティブイメージでの使用には、別の native プロファイルに抽出される可能性のあるエンティティービューアーノテーションプロセッサーへの依存関係が必要です:

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

CriteriaBuilderFactoryEntityViewManager は、 Hibernate-ORM エクステンションで提供される設定済の EntityManagerFactory に基づいて作成されます。

その後、注入によってこれらのBeanにアクセスすることができます:

Hibernateを使用したアプリケーションBeanの例
@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 EntityManager を注入
2 CriteriaBuilderFactory を注入
3 EntityViewManager を注入
4 トランザクションが開始またはトランザクションに参加されるように、CDI Beanメソッドを @Transactional としてマークします。
エンティティーの例
@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;
    }
}
エンティティービューの例
@EntityView(Gift.class)
public interface GiftView {

    @IdMapping
    Long getId();

    String getName();
}
更新可能なEntity-Viewの例
@UpdatableEntityView
@CreatableEntityView
@EntityView(Gift.class)
public interface GiftUpdateView extends GiftView {

    void setName(String name);
}
JAX-RSリソースの例
@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の設定プロパティー

EntityViewManagerCriteriaBuilderFactory を洗練させたり、またはQuarkusの推測をガイドするのに便利な様々なオプションのプロパティーがあります。

Hibernate ORMエクステンションが適切に設定されている限り、必須のプロパティーはありません。

プロパティーが設定されていない場合は、Blaze-Persistenceのデフォルトが適用されます。

ここに記載されている設定プロパティーでは、このようなデフォルトを上書きしたり、様々な面をカスタマイズしたり調整したりすることができます。

ビルド時に固定した設定プロパティー: その他すべての設定プロパティーは実行時にオーバーライド可能

設定プロパティー

タイプ

デフォルト

A boolean flag to make it possible to prepare all view template caches on startup. By default, the eager loading of the view templates is disabled to have a better startup performance. Valid values for this property are true or false.

boolean

An integer value that defines the default batch size for entity view attributes. By default, the value is 1 and can be overridden either via com.blazebit.persistence.view.BatchFetch#size() or by setting this property via com.blazebit.persistence.view.EntityViewSetting#setProperty.

int

A mode specifying if correlation value, view root or embedded view batching is expected. By default, the value is values and can be overridden by setting this property via com.blazebit.persistence.view.EntityViewSetting#setProperty. Valid values are - values - view_roots - embedding_views

文字列

A boolean flag to make it possible to prepare the entity view updater cache on startup. By default, the eager loading of entity view updates is disabled to have a better startup performance. Valid values for this property are true or false.

boolean

A boolean flag to make it possible to disable the strict validation that disallows the use of an updatable entity view type for owned relationships. By default, the use is disallowed i.e. the default value is true, but since there might be strange models out there, it is possible to allow this. Valid values for this property are true or false.

boolean

A boolean flag to make it possible to disable the strict cascading check that disallows setting updatable or creatable entity views on non-cascading attributes before being associated with a cascading attribute. When disabled, it is possible, like in JPA, that the changes done to an updatable entity view are not flushed when it is not associated with an attribute that cascades updates. By default, the use is enabled i.e. the default value is true. Valid values for this property are true or false.

boolean

A boolean flag that allows to switch from warnings to boot time validation errors when invalid plural attribute setters are encountered while the strict cascading check is enabled. When true, a boot time validation error is thrown when encountering an invalid setter, otherwise just a warning. This configuration has no effect when the strict cascading check is disabled. By default, the use is disabled i.e. the default value is false. Valid values for this property are true or false.

boolean

A boolean flag that allows to specify if empty flat views should be created by default if not specified via EmptyFlatViewCreation. By default, the creation of empty flat views is enabled i.e. the default value is true. Valid values for this property are true or false.

boolean

— 完全修飾式キャッシュ実装クラス名 —

文字列

— true に設定すると、CTE クエリーがデフォルトでインライン化されます。このプロパティーに使用できる値は、truefalse、または auto です。デフォルトの値は、 true で、非再帰 CTE を常にインライン化します。auto 設定は、JPA プロバイダーと DBMS ダイアレクトが対応または必要とする場合にのみインライン化を使用できます。このプロパティーは、クエリーを構成する前にクライテリアビルダー (criteria builder) に対して変更できます。 —

boolean

Apart from these configuration options, further configuration and customization can be applied by observing a CriteriaBuilderConfiguration or EntityViewConfiguration events and applying customizations on these objects. The various customization use cases can be found in the 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);
    }
}

制約事項

Apache Derby

Blaze-Persistenceは現在、Apache Derbyをサポートしていません。切実なニーズが存在し、誰かがコントリビュートしてくれれば、この制限は、将来的には解除されるかもしれません。