バージョン:

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

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

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

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

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

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

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

ケイパビリティの宣言

quarkus-extension-maven-plugin:extension-descriptor Maven ゴールと extensionDescriptor Gradle タスクはエクステンション記述子を生成し、次の方法で provided および required のケイパビリティを設定できます:

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

Including any one of those extensions in an application will enable the RESTEasy JSON serializer. In case a build step needs to check whether the RESTEasy JSON serializer is already enabled in an application, instead of checking whether any of those capabilities is present, it could simply check whether an extension with the prefix io.quarkus.resteasy.json is present.

ケイパビリティの宣言
- 条件付ケイパビリティ約束と要件
CapabilityBuildItem
ケイパビリティをクエリ
- ケイパビリティ接頭辞