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

プラットフォーム

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

Quarkusプラットフォーム

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

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

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

QuarkusプラットフォームBOM

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

  • imports a chosen version of io.quarkus:quarkus-bom (the platform BOM may be flattened at the end, but it has to be based on some version of io.quarkus:quarkus-bom)

  • プラットフォームを構成するすべてのQuarkusエクステンションアーティファクト(ランタイムとデプロイメントのもの)を含むこと

  • プラットフォームエクステンション間の互換性を保証するために、遷移的な依存関係のバージョンを整列させるために必要なすべてのサードパーティ製アーティファクトが含まれていること

  • プラットフォームJSONディスクリプタアーティファクトを含むこと

  • プラットフォーム設定プロパティ アーティファクトを含む場合があります

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

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

Quarkus platform descriptor is a JSON artifact that provides information about the platform and its extensions to the Quarkus tools. E.g. https://code.quarkus.io/ and the Quarkus command line tools consult this descriptor to list, add and remove extensions to/from the project on user’s request. This artifact is also used as a Quarkus platform identifier. When Quarkus tools need to identify the Quarkus platform(s) used in the project, they will analyze the dependency version constraints of the project (the effective list of the managed dependencies from the dependencyManagement section in Maven terms) looking for the platform descriptor artifact(s) among them. Given that the platform descriptors are included into the Quarkus platform BOMs, every Quarkus application will inherit the platform descriptor artifact from the imported platform BOM(s) as a dependency version constraint (managed dependency in Maven terms).

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

  • ディスクリプタアーティファクトの groupId は、対応するQuarkus Platform BOMの groupId と一致している必要があります。

  • ディスクリプタアーティファクトの artifactId は、対応するQuarkus Platform BOMの artifactId で、サフィックスが -quarkus-platform-descriptor である必要があります。

  • ディスクリプタアーティファクトの classifier は、対応するQuarkus Platform BOMの version と一致している必要があります。

  • ディスクリプタアーティファクトの typejson である必要があります。

  • ディスクリプタアーティファクトの version は、対応するQuarkus Platform BOMの version と一致している必要があります。

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

例えば、Quarkus BOM io.quarkus:quarkus-bom::pom:1.2.3 のディスクリプタの座標は io.quarkus: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 です。

The classifier matching the version of the platform may look confusing at first. But this is what turns the descriptor into a true "fingerprint" of the platform. In both Maven and Gradle, the effective set of the dependency version constraints (or the managed dependencies) is obtained by merging all the imported BOMs and version constraints specified individually in the current project and also its parent(s). The artifact classifier is a part of the dependency ID, which could be expressed as groupId:artifactId:classifier:type. Which means that if a project imports a couple of BOMs, e.g. org.apple:apple-bom::pom:1.0 and org.orange:orange-bom::pom:1.0, and each of these two BOMs imports a different version io.quarkus.platform:quarkus-bom::pom, the Quarkus tools will be able to detect this fact and make the user aware of it, since it might not be a safe combination. If the descriptor artifact didn’t include the classifier containing the version of the platform then the tools wouldn’t be able to detect a potentially incompatible mix of different versions of the same platform in the same project.

プラットフォームディスクリプタは通常、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プラットフォームプロパティ

A Quarkus platform may provide its own default values for some configuration options.

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

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

  • プロパティアーティファクトの groupId は、対応するQuarkus Platform BOMの groupId と一致している必要があります。

  • プロパティアーティファクトの artifactId は、対応するQuarkus Platform BOMの artifactId で、サフィックスが -quarkus-platform-properties である必要があります。

  • ディスクリプタアーティファクトの classifier は空/NULL のままの必要があります。

  • ディスクリプタアーティファクトの typeproperties である必要があります。

  • ディスクリプタアーティファクトの version は、対応するQuarkus Platform BOMの version と一致している必要があります。

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

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

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

package io.quarkus.deployment.pkg;

@ConfigRoot(phase = ConfigPhase.BUILD_TIME)
public class NativeConfig {

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

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

platform.quarkus.native.builder-image=quay.io/quarkus/ubi-quarkus-native-image:22.1-java11

また、プラットフォームプロパティのコンテンツとそのアーティファクトの座標を検証し、プラットフォームプロパティのアーティファクトがプラットフォームの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 のプラットフォーム・プロパティよりも先に現れる為、ビルドの際に優先されます。