エクステンションケイパビリティ
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 のケイパビリティを設定できます:
条件付ケイパビリティ約束と要件
ケイパビリティは、特定の条件が満たされた場合、例えば、特定の設定オプションが有効な場合、または他の条件に基づいてのみ提供される場合があります。これは以下のように表現できます:
この場合、 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 を持つエクステンションが存在するかどうかを単純にチェックすることができます。
