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

Quarkus Extension Metadata

Quarkus エクステンションは、アプリケーションや他のライブラリーが依存する Maven JAR アーティファクトとして配布されます。Quarkus アプリケーションプロジェクトを Quarkus 開発ツールを使用してビルド、テスト、編集すると、Quarkus エクステンション JAR アーティファクトは、その中の Quarkus エクステンションメタデータファイルの存在によって、アプリケーションクラスパス上で識別されます。このドキュメントでは、各 Quarkus エクステンションメタデータファイルの目的とその内容について説明しています。

2つのメタデータファイルは同じ名前ですが、 quarkus-extension.yamlquarkus-extension.properties という異なるエクステンションを持っています。 混同しやすいので注意してください。通常、YAMLファイルを編集し、SCMで追跡します。 プロパティファイルは手動で管理 してもよい ですが、そうしなかった場合はQuarkusがビルド時に生成します。

META-INF/quarkus-extension.yaml

すべての runtime エクステンションアーティファクトには、このファイルを含める必要があります。このファイルは、エクステンション関連情報の表示、新規プロジェクトの作成、既存プロジェクトへのエクステンションの追加などで、Quarkus 開発ツールで使用されます。このファイルは、アプリケーションのビルド時やブートストラップ時には使用されません。このファイルに含まれる基本および必須のメタデータは、エクステンションアーティファクトのビルド時に、Quarkus Maven および Gradle プラグインによって生成できます。しかし、通常、エクステンションの作成者は、Quarkus の開発ツールやユーザーにエクステンションに関する情報をより多く提供したいと考えます。このような追加情報は、エクステンションランタイムモジュールのリソースディレクトリー (例: src/main/resources/META-INF/quarkus-extension.yaml) にあるテンプレート META-INF/quarkus-extension.yaml で提供できます。以下は quarkus-resteasy-reactive エクステンションのテンプレート例です。

name: "RESTEasy Reactive" (1)
artifact: ${project.groupId}:${project.artifactId}:${project.version} (2)
metadata:
  short-name: "resteasy-reactive" (3)
  keywords: (4)
  - "jaxrs"
  - "web"
  - "rest"
  categories: (5)
  - "web"
  - "reactive"
  status: "stable" (6)
  guide: "https://quarkus.io/guides/resteasy-reactive" (7)
  icon-url: "https://quarkus.io/assets/images/about/icon-reactive.svg" (8)
  codestart: (9)
    name: "resteasy-reactive"
    languages:
      - "java"
      - "kotlin"
      - "scala"
    artifact: "io.quarkus:quarkus-project-core-extension-codestarts"
  config: (10)
  - "quarkus.resteasy-reactive."
1 ユーザーに表示されるエクステンション名
2 ビルド時に実際の座標に置き換えられるエクステンションランタイムアーティファクト式、このフィールドは省略可
3 開発ツールがユーザーに提供するエクステンションのカタログから、そのエクステンションをすばやく見つけるために使用できる短縮名
4 開発ツールがユーザーに提供するエクステンションのカタログから、エクステンションを検索するために使用できるキーワード
5 code.quarkus.io でエクステンションが表示されるカテゴリー。このフィールドを省略しても、エクステンションは引き続き code.quarkus.io にリストされますが、カテゴリーには分類されません
6 成熟度ステータス (stablepreviewexperimental)。成熟度ステータスを判断してユーザーに周知するかどうかは、エクステンションのメンテナーが決定します
7 エクステンションガイドまたはドキュメントページへのリンク
8 外部でホストされている画像へのリンクです。これは、Quarkusの開発ツールでエクステンションのアイコンとして使用されます。正方形で、220ピクセル以上の解像度である必要があります。サポートされている形式は、png、jpeg、tiff、webp、およびsvgです。あるいは、エクステンションのソースコードリポジトリで ソーシャルメディアプレビューを設定 すると、ツールはその画像をピックアップします。
9 Codestart 情報
10 設定プレフィックス

以下は、Quarkus Maven プラグインが収集した他の情報も追加された、ランタイム JAR に含まれるファイルの最終バージョンです。

name: "RESTEasy Reactive"
artifact: "io.quarkus:quarkus-resteasy-reactive:999-SNAPSHOT"
metadata:
  short-name: "resteasy-reactive"
  keywords:
  - "jaxrs"
  - "web"
  - "rest"
  categories:
  - "web"
  - "reactive"
  status: "stable"
  guide: "https://quarkus.io/guides/resteasy-reactive"
  codestart:
    name: "resteasy-reactive"
    languages:
    - "java"
    - "kotlin"
    - "scala"
    artifact: "io.quarkus:quarkus-project-core-extension-codestarts::jar:999-SNAPSHOT"
  config:
  - "quarkus.resteasy-reactive."
  built-with-quarkus-core: "999-SNAPSHOT" (1)
  capabilities: (2)
    provides:
    - "io.quarkus.rest"
    - "io.quarkus.resteasy.reactive"
  extension-dependencies: (3)
  - "io.quarkus:quarkus-resteasy-reactive-common"
  - "io.quarkus:quarkus-mutiny"
  - "io.quarkus:quarkus-smallrye-context-propagation"
  - "io.quarkus:quarkus-vertx"
  - "io.quarkus:quarkus-arc"
  - "io.quarkus:quarkus-netty"
  - "io.quarkus:quarkus-vertx-http"
  - "io.quarkus:quarkus-core"
  - "io.quarkus:quarkus-jsonp"
description: "A Jakarta REST implementation utilizing build time processing and Vert.x.\
  \ This extension is not compatible with the quarkus-resteasy extension, or any of\
  \ the extensions that depend on it." (4)
scm-url: "https://github.com/quarkusio/quarkus" (5)
sponsor: A Sponsoring Organisation (6)
1 エクステンションがビルドされた Quarkus のバージョン
2 Capabilities このエクステンションは以下を提供します。
3 他のエクステンションへの直接の依存関係
4 ユーザーに表示できる説明。この場合、説明はエクステンションモジュールの pom.xml からコピーされましたが、テンプレートファイルで提供することもできます。
5 このエクステンションモジュールのソースコードリポジトリ。オプションで、多くの場合は pom 内の <scm> の情報を使って自動的に設定されます。GitHub Actions のビルドでは、CI 環境から推測されます。その他の GitHub リポジトリの場合は、 GITHUB_REPOSITORY 環境変数で指定します。
6 このエクステンションモジュールのスポンサー。オプションであり、コミット履歴から自動的に決定されることもあります。

META-INF/quarkus-extension.properties

すべての ランタイム エクステンションアーティファクトには、必ずこのファイルが含まれている必要があります。このファイルは Quarkus ブートストラップメカニズムで読み取られ、アプリケーションの ビルドまたはブートストラップ に関連する情報のみを含むためのものです。このファイルは通常、エクステンションプロジェクトのビルド時に対応する Quarkus Maven または Gradle プラグインによって生成され、手動で編集してはなりません。このファイルには、次のプロパティーが表示される場合があります。

Name Presence Description

deployment-artifact

必須

groupId:artifactId[:classifier:type]:version フォーマットで、対応するエクステンションデプロイメントアーティファクトを指します。

parent-first-artifacts

オプション

親から先にロードされるアーティファクトキー (groupId:artifactId:classifier:type) のコンマ区切りリスト。これは、システム ClassLoader によって特定のクラスをロードする必要がある問題を回避するために使用できます。

runner-parent-first-artifacts

オプション

アプリケーションが本番バイナリーパッケージから起動されたときに、parent-first-artifacts で設定されたものに加えて、親が最初に読み込まれるアーティファクトキーのコンマ区切りリスト。これは、システム ClassLoader によって特定のクラスをロードする必要がある問題を回避するために使用できます。

excluded-artifacts

オプション

クラスローダーによってロードされず、最終的なアプリケーションにパックされないアーティファクトキーのコンマ区切りリスト。

lesser-priority-artifacts

オプション

クラスまたはリソースを含む他のアーティファクトが存在しない場合にのみ、そのクラスまたはリソースをロードするために使用されるアーティファクトキーのコンマ区切りリスト。これは、複数のアーティファクトに同じクラスが含まれている場合に、アーティファクトの順番を制御するために使用されます。

removed-resources.*

オプション

依存関係から削除/非表示にする必要があるリソース。これにより、クラスやその他のリソースを依存関係から削除できるため、アプリケーションからアクセスできなくなります。これは、削除するリソースのコンマ区切りリストへのアーティファクトキーのマップです。開発およびテストモードで実行している場合、これらのリソースは ClassLoader から非表示になり、実稼働モードで実行している場合、これらのファイルはそれらを含む jar から削除されます。クラスを削除する場合は、クラスファイル名を指定する必要があることに注意してください。たとえば、com.acme.Foo を削除するには、com/acme/Foo.class を指定します。

provides-capabilities

オプション

このエクステンションが提供する 機能 のリスト。

requires-capabilities

オプション

他の Quarkus エクステンションからこのエクステンションに提供する必要がある 機能 のリスト。

conditional-dependencies

オプション

このエクステンションが宣言する 条件付き依存関係 のリスト。

dependency-condition

オプション

このエクステンションへの条件付き依存関係を有効にするために満たす必要がある 依存関係の条件

META-INF/quarkus-config-roots.list

このファイルは、ランタイムエクステンションアーティファクトおよびデプロイメントアーティファクトに表示される場合があります。このファイルは手動で編集しないでください。これは、エクステンションプロジェクトのビルドプロセスの一部として生成され、エクステンションが提供する io.quarkus.runtime.annotations.ConfigRoot でアノテーションが付けられた Java クラス名のリストが含まれています。

META-INF/quarkus-javadoc.properties

quarkus-config-roots.list と同様に、このファイルはランタイムエクステンションアーティファクトにもデプロイアーティファクトにも表示される場合があります。これは、エクステンションプロジェクトのビルドプロセスの一部として、io.quarkus.runtime.annotations.ConfigRoot でアノテーションが付けられたクラスで使用可能な設定オプションの記述から生成されました。手動での編集はサポートされていません。

META-INF/quarkus-build-steps.list

このファイルは、デプロイメントエクステンションアーチファクトに表示される場合があります。Quarkus ビルドステップ (io.quarkus.deployment.annotations.BuildStep でアノテーションが付けられたメソッド) を実装するクラスのリストが含まれています。このファイルは、エクステンションプロジェクトのビルドプロセスの一部として生成されます。このファイルを手動で編集してはなりません。

関連コンテンツ