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

エクステンションケイパビリティ

Quarkusのエクステンションは、特定のケイパビリティを提供することがあり、正しく機能するために、アプリケーション内の他のエクステンションによって提供される特定のケイパビリティを必要とすることがあります。

機能は技術的な側面を表します。たとえば、一部の機能の実装、契約、または仕様である可能性があります。 各機能には、Javaパッケージの命名規則に従う必要のある名前があります。例: io.quarkus.rest

ケイパビリティの約束と要件は、Quarkusエクステンション記述子(ランタイムエクステンションJARアーティファクトの META-INF/quarkus-extension.properties エントリ)に記述されます。

1つのアプリケーションで許可されるのは、任意のケイパビリティの単一のプロバイダーのみです。1つのケイパビリティに対して複数のプロバイダーが検出された場合、アプリケーションのビルドは対応するエラーメッセージを表示して失敗します。

1つのエクステンションが特定のケイパビリティを必要とする場合、そのケイパビリティを提供するアプリケーションの依存関係の中に別のエクステンションが必要です。そうでない場合、ビルドは対応するエラーメッセージで失敗します。

ビルド時には、アプリケーションで見つかったすべてのケイパビリティが io.quarkus.deployment.Capabilities ビルドアイテムのインスタンスに集約され、エクステンションビルドステップが注入して、所定のケイパビリティが利用可能かどうかをチェックできるようになります。

ケイパビリティの宣言

The quarkus-extension-maven-plugin:extension-descriptor Maven goal and the extensionDescriptor Gradle task, that generate extension descriptors, allow configuring provided and required capabilities in the following way:

Maven
<plugin>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-extension-maven-plugin</artifactId>
    <configuration>
        <capabilities>
            <provides>io.quarkus.hibernate.orm</provides> (1)
            <requires>io.quarkus.agroal</requires> (2)
        </capabilities>
    </configuration>
</plugin>
1 エクステンションは、 io.quarkus.hibernate.orm のケイパビリティを提供します(複数の provides 要素が許可されます)。
2 エクステンションが正しく機能するためには、 io.quarkus.agroal のケイパビリティが提供されていることが必要です(複数の requires 要素が許可されます)。
Gradle (Groovy DSL)
quarkusExtension {
    capabilities {
        provides 'io.quarkus.rest' (1)
        requires 'io.quarkus.resteasy' (2)
    }
}
1 エクステンションは、 io.quarkus.hibernate.orm のケイパビリティを提供します(複数の provides 要素が許可されます)。
2 エクステンションが正しく機能するためには、 io.quarkus.agroal のケイパビリティが提供されていることが必要です(複数の requires 要素が許可されます)。
Gradleエクステンションプラグインはまだ実験的なものであり、将来的に変更される可能性があります。
Gradle (Kotlin DSL)
quarkusExtension {
    capabilities {
        provides("io.quarkus.rest") (1)
        requires("io.quarkus.resteasy") (2)
    }
}
1 エクステンションは、 io.quarkus.hibernate.orm のケイパビリティを提供します(複数の provides 要素が許可されます)。
2 エクステンションが正しく機能するためには、 io.quarkus.agroal のケイパビリティが提供されていることが必要です(複数の requires 要素が許可されます)。
Gradleエクステンションプラグインはまだ実験的なものであり、将来的に変更される可能性があります。

条件付ケイパビリティ約束と要件

ケイパビリティは、特定の条件が満たされた場合、例えば、特定の設定オプションが有効な場合、または他の条件に基づいてのみ提供される場合があります。これは以下のように表現できます:

Maven
<plugin>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-extension-maven-plugin</artifactId>
    <configuration>
        <capabilities>
            <providesIf> (1)
                <positive>io.quarkus.container.image.openshift.deployment.OpenshiftBuild</positive> (2)
                <name>io.quarkus.container.image.openshift</name> (3)
            </providesIf>
        </capabilities>
    </configuration>
</plugin>
1 条件付きケイパビリティの宣言
2 java.util.function.BooleanSupplier を実装したクラスが true に解決しなければならない条件
3 提供されたケイパビリティ名
providesIf は、複数の <positive><negative> の要素をリストアップできます。

対応する requiresIf 要素もサポートされています。

Gradle (Groovy DSL)
quarkusExtension {
    capabilities {
        provides 'io.quarkus.container.image.openshift' onlyIf ['io.quarkus.container.image.openshift.deployment.OpenshiftBuild'] (1)
    }
}
1 java.util.function.BooleanSupplier を実装したクラスが true に解決しなければならない条件
onlyIfNot の条件を指定することも可能です。必要なケイパビリティに対して条件を設定することも可能です。
Gradle (Kotlin DSL)
quarkusExtension {
    capabilities {
        provides("io.quarkus.container.image.openshift").onlyIf(["io.quarkus.container.image.openshift.deployment.OpenshiftBuild"]) (1)
    }
}
1 java.util.function.BooleanSupplier を実装したクラスが true に解決しなければならない条件
onlyIfNot の条件も指定することが可能です。.必要なケイパビリティに対して条件を設定することも可能です。

この場合、 io.quarkus.container.image.openshift.deployment.OpenshiftBuild は、エクステンションのデプロイメント依存関係の1つに含まれ、 java.util.function.BooleanSupplier を実装する必要があります。ビルド時に、Quarkusのブートストラップはそのインスタンスを作成し、その getAsBoolean() メソッドがtrueを返す場合にのみ、 io.quarkus.container.image.openshift ケイパビリティを登録します。

OpenshiftBuild の実装は以下のようになります:

import java.util.function.BooleanSupplier;

import io.quarkus.container.image.deployment.ContainerImageConfig;

public class OpenshiftBuild implements BooleanSupplier {

    private ContainerImageConfig containerImageConfig;

    OpenshiftBuild(ContainerImageConfig containerImageConfig) {
        this.containerImageConfig = containerImageConfig;
    }

    @Override
    public boolean getAsBoolean() {
        return containerImageConfig.builder.map(b -> b.equals(OpenshiftProcessor.OPENSHIFT)).orElse(true);
    }
}

CapabilityBuildItem

提供された各ケイパビリティはビルド時に io.quarkus.deployment.builditem.CapabilityBuildItem のインスタンスで表されます。理論的には、`CapabilityBuildItem’sはエクステンションのビルドステップで直接生成することができ、エクステンションの記述子で対応する宣言をバイパスします。しかし、ケイパビリティを提供するこの方法は、記述子で能力を宣言しない非常に良い理由がない限り、避けるべきです。

エクステンションのビルドステップから生成されたケイパビリティは、Quarkus開発ツールでは利用できません。そのため、プロジェクト作成時にエクステンションの互換性を分析する際や、プロジェクトに新しいエクステンションを追加する際に、そのような機能を考慮することはできません。

ケイパビリティをクエリ

アプリケーションで見つかったすべてのケイパビリティは、ビルド中に io.quarkus.deployment.Capabilities ビルドアイテムのインスタンスに集約されます。このアイテムは、エクステンションビルドステップによって注入され、特定のケイパビリティが存在するかどうかをチェックすることができます。例えば、以下のようになります。

    @BuildStep
    HealthBuildItem addHealthCheck(Capabilities capabilities, DataSourcesBuildTimeConfig dataSourcesBuildTimeConfig) {
        if (capabilities.isPresent(Capability.SMALLRYE_HEALTH)) {
            return new HealthBuildItem("io.quarkus.agroal.runtime.health.DataSourceHealthCheck",
                    dataSourcesBuildTimeConfig.healthEnabled);
        } else {
            return null;
        }
    }

ケイパビリティ接頭辞

ケイパビリティ名と同様に、ケイパビリティのプレフィックスは、最初のケイパビリティ名要素、または最初のケイパビリティ名要素から始まるドット区切りのシーケンスのいずれかで構成されるドット区切りの文字列です。例)ケイパビリティ io.quarkus.resteasy.json.jackson には以下のプレフィックスが登録されます:

  • io

  • io.quarkus

  • io.quarkus.resteasy

  • io.quarkus.resteasy.json

Capabilities.isCapabilityWithPrefixPresent(prefix) は、与えられた接頭辞を持つケイパビリティが存在するかどうかをチェックするために使用できます。

1つのアプリケーションでは特定のケイパビリティの単一のプロバイダーしか認められないことを考えると、ケイパビリティのプレフィックスによって、異なるが多少関連するケイパビリティの間である共通の側面を表現することができます。例えば、以下のようなケイパビリティを提供するエクステンションがあるかもしれません:

  • io.quarkus.resteasy.json.jackson

  • io.quarkus.resteasy.json.jackson.client

  • io.quarkus.resteasy.json.jsonb

  • io.quarkus.resteasy.json.jsonb.client

これらのエクステンションのいずれかをアプリケーションに含めると、RESTEasy JSONシリアライザが有効になります。ビルド・ステップで、RESTEasy JSONシリアライザがアプリケーションですでに有効になっているかどうかをチェックする必要がある場合、これらのケイパビリティのいずれかが存在するかどうかをチェックする代わりに、プレフィックス io.quarkus.resteasy.json を持つエクステンションが存在するかどうかを単純にチェックすることができます。