バージョン:

プラットフォーム

Quarkusエクステンションエコシステムは、Quarkusコア開発チームを含むコミュニティによって開発・保守されたQuarkusエクステンションで構成されています。Quarkusエコシステム（"Quarkus universe"と呼ばれることもあります）には、これまでに開発されたすべてのQuarkusエクステンションが含まれていますが、Quarkusプラットフォームという概念もあります。

Quarkusプラットフォーム

Quarkusプラットフォームの基本的な約束事は、プラットフォームで構成されるQuarkusエクステンションを組み合わせて、お互いに競合することなく同じアプリケーションで使用することができるということです。Quarkusプラットフォームを作成する各組織は、プラットフォームに受け入れられるエクステンションについて独自の基準を設定し、受け入れられたエクステンション間の互換性を保証する手段を確立することができます。

Quarkusプラットフォームのアーティファクト

各Quarkusプラットフォームは、いくつかのアーティファクトで定義されています。

QuarkusプラットフォームBOM

各Quarkusプラットフォームは、次のようなMaven BOMアーティファクトを提供することが期待されています:

io.quarkus:quarkus-bom の選択されたバージョンをインポートすること (プラットフォームの BOM は最後にフラット化されますが、 io.quarkus:quarkus-bom の何らかのバージョンに基づいていなければなりません)
プラットフォームを構成するすべてのQuarkusエクステンションアーティファクト（ランタイムとデプロイメントのもの）を含むこと
プラットフォームエクステンション間の互換性を保証するために、遷移的な依存関係のバージョンを整列させるために必要なすべてのサードパーティ製アーティファクトが含まれていること
プラットフォームJSONディスクリプタアーティファクトを含むこと
プラットフォーム設定プロパティアーティファクトを含む場合があります

QuarkusプラットフォームからエクステンションをインクルードしたいQuarkusアプリケーションは、QuarkusプラットフォームのBOMをインポートします。

Quarkusプラットフォームディスクリプタ

Quarkusプラットフォームディスクリプタは、プラットフォームとそのエクステンションに関する情報をQuarkusツールに提供するJSONアーティファクトです。例： http://code.quarkus.io やQuarkusコマンドラインツールは、ユーザーの要求に応じて、このディスクリプタを参照して、プロジェクトへのエクステンションのリスト化、追加、削除を行います。このアーティファクトは、Quarkusプラットフォームディスクリプタとしても使用されます。Quarkusツールがプロジェクトで使用されているQuarkusプラットフォームを識別する必要がある場合、プロジェクトの依存関係バージョン制約（Maven用語では、 dependencyManagement セクションから管理されている依存関係の有効なリスト）を分析して、その中からプラットフォームディスクリプタのアーティファクトを探します。プラットフォームディスクリプタがQuarkusプラットフォームBOMに含まれていることを考えると、すべてのQuarkusアプリケーションは、インポートされたプラットフォームBOMからのプラットフォームディスクリプタアーティファクトを依存関係バージョン制約（Maven用語では管理された依存関係）として継承します。

プロジェクトの依存性制約の中でQuarkusプラットフォームディスクリプタを簡単に識別できるように、プラットフォームディスクリプタのMavenアーティファクト座標は、以下の命名規則に従う必要があります。

ディスクリプタアーティファクトの groupId は、対応するQuarkus Platform BOMの groupId と一致している必要があります。
ディスクリプタアーティファクトの artifactId は、対応するQuarkus Platform BOMの artifactId で、サフィックスが -quarkus-platform-descriptor である必要があります。
ディスクリプタアーティファクトの classifier は、対応するQuarkus Platform BOMの version と一致している必要があります。
ディスクリプタアーティファクトの type は json である必要があります。
ディスクリプタアーティファクトの version は、対応するQuarkus Platform BOMの version と一致している必要があります。

文字列としては次のようになります： <platform-bom-groupId>:<platform-bom-artifactId>-quarkus-platform-descriptor:<platform-version>:json:<platform-version>

例えば、Quarkus BOM io.quarkus.platform:quarkus-bom::pom:1.2.3 の記述子の座標は io.quarkus.platform:quarkus-bom-quarkus-platform-descriptor:1.2.3:json:1.2.3 となります。また、BOM org.acme:acme-bom::pom:555 で定義されたカスタムQuarkusプラットフォームの場合は、 org.acme:acme-bom-quarkus-platform-descriptor:555:json:555 となります。

プラットフォームのバージョンにマッチする分類子は、最初は混乱するように見えるかもしれません。しかし、これは記述子をプラットフォームの真の「フィンガープリント」に変えるものです。MavenとGradleの両方で、依存バージョン制約（または管理された依存関係）の効果的なセットは、現在のプロジェクトとその親（複数可）で個別に指定されたすべてのインポートされたBOMとバージョン制約をマージすることによって得られます。アーティファクト classifier は、依存関係IDの一部であり、 groupId:artifactId:classifier:type と表すことができます。つまり、プロジェクトが2つのBOM、例えば org.apple:apple-bom::pom:1.0 と org.orange:orange-bom::pom:1.0 をインポートし、これら2つのBOMがそれぞれ異なるバージョン io.quarkus.platform:quarkus-bom::pom をインポートする場合、Quarkusツールはこの事実を検出し、安全な組み合わせではない 可能性がある ため、ユーザーに認識させることができます。もし、記述子アーティファクトにプラットフォームのバージョンを含む分類子が含まれていなければ、ツールは、同じプロジェクトに同じプラットフォームの異なるバージョンが混在している可能性を検出できないでしょう。

プラットフォームディスクリプタは通常、Mavenプラグインを使用して生成されます。

<plugin>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-platform-descriptor-json-plugin</artifactId>
  <version>${quarkus.version}</version> (1)
  <executions>
    <execution>
      <phase>process-resources</phase>
      <goals>
        <goal>generate-extensions-json</goal> (2)
      </goals>
    </execution>
  </executions>
  <configuration>
    <bomGroupId>${quarkus.platform.group-id}</bomGroupId> (3)
    <bomArtifactId>${quarkus.platform.artifact-id}</bomArtifactId> (4)
    <bomVersion>${quarkus.platform.version}</bomVersion> (5)
    <overridesFile>${overridesfile}</overridesFile> (6)
    <resolveDependencyManagement>true</resolveDependencyManagement> (7)
  </configuration>
</plugin>

1	`quarkus-platform-descriptor-json-plugin` のバージョン
2	`generate-extensions-json` は、プラットフォームディスクリプタを生成するゴールです。
3	プラットフォーム BOM の `groupId`
4	プラットフォーム BOM の `artifactId`
5	プラットフォーム BOM の `version`
6	このパラメータはオプションで、プラットフォームディスクリプタが生成されるすべてのランタイムエクステンションアーティファクトに含まれるQuarkusエクステンションディスクリプタのメタデータの一部をオーバーライドすることができます。
7	このパラメータもオプションで、デフォルトは false です。プラットフォームBOMが生成されず、フラット化されていない場合はtrueに設定しなければなりません。たとえば、 `io.quarkus:quarkus-bom` となります。

Quarkusプラットフォームプロパティ

Quarkusプラットフォームでは、幾つかの設定オプションに対して独自のデフォルト値を提供している場合があります。

Quarkusは、アプリケーション設定の接続に SmallRye Configを使用しています。Quarkusプラットフォームは、アプリケーションの application.properties によって支配されている構成ソースの階層の別の構成ソースとして使用することができます。

プラットフォーム固有のデフォルトを提供するには、プラットフォームは、座標が下記の命名規則に従っているプロパティアーティファクトに対して、その BOM 内に依存バージョン制約を含める必要があります。

プロパティアーティファクトの groupId は、対応するQuarkus Platform BOMの groupId と一致している必要があります。
プロパティアーティファクトの artifactId は、対応するQuarkus Platform BOMの artifactId で、サフィックスが -quarkus-platform-properties である必要があります。
ディスクリプタアーティファクトの classifier は空/NULL のままの必要があります。
ディスクリプタアーティファクトの type は properties である必要があります。
ディスクリプタアーティファクトの version は、対応するQuarkus Platform BOMの version と一致している必要があります。

プロパティ・アーティファクト自体は、 java.util.Properties クラスのインスタンスにロードされる伝統的な properties ファイルであることが期待されます。

この時点では、プラットフォームプロパティは、制限された設定オプションのセットに対してデフォルト値を提供することのみが許可されています。プラットフォームプロパティファイルのプロパティ名の前には、 platform. という接尾辞を付けなければなりません。

設定オプションをプラットフォーム固有のものにしたいエクステンションの開発者は、デフォルト値を platform. で始まるプロパティに設定しなければなりません。以下に例を示します。

package io.quarkus.deployment.pkg;

@ConfigRoot(phase = ConfigPhase.BUILD_TIME)
@ConfigMapping(prefix = "quarkus")
public interface NativeConfig {

    /**
     * The docker image to use to do the image build
     */
    @WithDefault("${platform.quarkus.native.builder-image}")
    String builderImage();
}

この場合、 quarkus.native.builder-image のデフォルト値はプラットフォームによって提供されます。もちろん、ユーザーは application.properties で quarkus.native.builder-image に希望の値を設定することができます。しかし、ユーザーがカスタマイズしていない場合は、デフォルト値はプラットフォームのプロパティから提供されます。上記の例のプラットフォームのプロパティファイルには、以下のようなものが含まれています（実際の値は例として提供されています）。

platform.quarkus.native.builder-image=quay.io/quarkus/ubi-quarkus-mandrel-builder-image:jdk-21

また、プラットフォームプロパティのコンテンツとそのアーティファクトの座標を検証し、プラットフォームプロパティのアーティファクトがプラットフォームのBOMに存在するかどうかをチェックするMavenプラグインのゴールもあります。ここでは、プラグインの構成例を示します。

<plugin>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-platform-descriptor-json-plugin</artifactId>
  <version>${quarkus.version}</version>
  <executions>
    <execution>
      <phase>process-resources</phase>
      <goals>
        <goal>platform-properties</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Quarkusプラットフォームプロパティのマージ

アプリケーションが複数のQuarkusプラットフォームをインポートしており、それらのプラットフォームが独自のプラットフォームプロパティアーティファクトを含んでいる場合、それらのプラットフォームプロパティアーティファクトのコンテンツは、アプリケーションのビルドに使用される単一のプロパティセットを形成するためにマージされます。プロパティアーティファクトがマージされる順番は、アプリケーションの依存関係バージョン制約のリストに表示される順番に対応します（Maven用語では、アプリケーションの管理された依存関係の実際のリスト、すなわちフラット化された managedDependencies POMセクションに対応します）。

アプリケーションの依存性制約の中では、先に見つかったプロパティアーティファクトの内容が、後に見つかったものよりも優先されます。

つまり、あるプラットフォームがベースとなるプラットフォームで定義されている特定のプロパティ値をオーバーライドする必要がある場合は、ベースとなるプラットフォームをインポートする前に、そのプラットフォームのプロパティアーティファクトをBOMの managedDependencies セクションに含める必要があります。

例えば、 org.acme:acme-quarkus-bom プラットフォームは io.quarkus:quarkus-bom プラットフォームをベースにしています。 org.acme:acme-quarkus-bom プラットフォームが、 io.quarkus:quarkus-bom プラットフォームに含まれる io.quarkus:quarkus-bom-quarkus-platform-properties で定義された特定のプロパティを上書きする場合、 org.acme:acme-quarkus-bom は次のように構成されなければなりません。

  <!-- skipped content -->

  <artifactId>acme-quarkus-bom</artifactId>
  <name>Acme - Quarkus - BOM</name>
  <packaging>pom</packaging>

  <dependencyManagement>
    <dependencies>
      <!-- Acme Quarkus platform properties -->
      <dependency>
        <groupId>org.acme</groupId>
        <artifactId>acme-quarkus-bom-quarkus-platform-properties</artifactId>
        <type>properties</type>
        <version>${project.version}</version>
      </dependency>

      <!-- The base Quarkus BOM -->
      <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-bom</artifactId>
        <version>${quarkus.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>

  <!-- skipped content -->

こうすることで、 org.acme:acme-quarkus-bom のプラットフォーム・プロパティが io.quarkus:quarkus-bom のプラットフォーム・プロパティよりも先に現れる為、ビルドの際に優先されます。

Quarkusプラットフォーム