Quarkus Extension Metadata
Quarkus エクステンションは、アプリケーションや他のライブラリーが依存する Maven JAR アーティファクトとして配布されます。Quarkus アプリケーションプロジェクトを Quarkus 開発ツールを使用してビルド、テスト、編集すると、Quarkus エクステンション JAR アーティファクトは、その中の Quarkus エクステンションメタデータファイルの存在によって、アプリケーションクラスパス上で識別されます。このドキュメントでは、各 Quarkus エクステンションメタデータファイルの目的とその内容について説明しています。
Two of the metadata files have the same name but different extensions, quarkus-extension.yaml and quarkus-extension.properties. It is easy to mix them up, be careful. You will usually edit the YAML file and track it in your SCM. While you can manually manage the properties file, Quarkus will generate it at build if you don’t.
|
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: "REST" (1)
artifact: ${project.groupId}:${project.artifactId}:${project.version} (2)
metadata:
short-name: "rest" (3)
keywords: (4)
- "jaxrs"
- "web"
- "rest"
categories: (5)
- "web"
- "reactive"
status: "stable" (6)
guide: "https://quarkus.io/guides/rest" (7)
icon-url: "https://quarkus.io/assets/images/about/icon-reactive.svg" (8)
codestart: (9)
name: "rest"
languages:
- "java"
- "kotlin"
- "scala"
artifact: "io.quarkus:quarkus-project-core-extension-codestarts"
config: (10)
- "quarkus.rest."| 1 | ユーザーに表示されるエクステンション名 |
| 2 | ビルド時に実際の座標に置き換えられるエクステンションランタイムアーティファクト式、このフィールドは省略可 |
| 3 | 開発ツールがユーザーに提供するエクステンションのカタログから、そのエクステンションをすばやく見つけるために使用できる短縮名 |
| 4 | 開発ツールがユーザーに提供するエクステンションのカタログから、エクステンションを検索するために使用できるキーワード |
| 5 | code.quarkus.io でエクステンションが表示されるカテゴリー。このフィールドを省略しても、エクステンションは引き続き code.quarkus.io にリストされますが、カテゴリーには分類されません |
| 6 | 成熟度ステータス (stable、preview、experimental)。成熟度ステータスを判断してユーザーに周知するかどうかは、エクステンションのメンテナーが決定します |
| 7 | エクステンションガイドまたはドキュメントページへのリンク |
| 8 | 外部でホストされている画像へのリンクです。これは、Quarkusの開発ツールでエクステンションのアイコンとして使用されます。正方形で、220ピクセル以上の解像度である必要があります。サポートされている形式は、png、jpeg、tiff、webp、およびsvgです。あるいは、エクステンションのソースコードリポジトリで ソーシャルメディアプレビューを設定 すると、ツールはその画像をピックアップします。 |
| 9 | Codestart 情報 |
| 10 | 設定プレフィックス |
以下は、Quarkus Maven プラグインが収集した他の情報も追加された、ランタイム JAR に含まれるファイルの最終バージョンです。
name: "Quarkus REST (formerly RESTEasy Reactive)"
artifact: "io.quarkus:quarkus-rest:999-SNAPSHOT"
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." (1)
metadata:
short-name: "rest"
keywords:
- "jaxrs"
- "web"
- "rest"
categories:
- "web"
- "reactive"
status: "stable"
guide: "https://quarkus.io/guides/rest"
codestart:
name: "rest"
languages:
- "java"
- "kotlin"
- "scala"
artifact: "io.quarkus:quarkus-project-core-extension-codestarts::jar:999-SNAPSHOT"
config:
- "quarkus.rest."
built-with-quarkus-core: "3.8.5" (2)
requires-quarkus-core: "[3.8,)" (3)
minimum-java-version: "17" (4)
capabilities: (5)
provides:
- "io.quarkus.rest"
- "io.quarkus.resteasy.reactive"
extension-dependencies: (6)
- "io.quarkus:quarkus-rest-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"
scm-url: "https://github.com/quarkusio/quarkus" (7)
sponsor: A Sponsoring Organisation (8)| 1 | ユーザーに表示できる説明。この場合、説明はエクステンションモジュールの pom.xml からコピーされましたが、テンプレートファイルで提供することもできます。 |
| 2 | エクステンションがビルドされた Quarkus のバージョン |
| 3 | The Quarkus version range this extension requires. Optional, and will be set automatically by using the built-with-quarkus-core as the minimum range. |
| 4 | The minimum Java version required for this extension to run. Will be generated based on the maven.compiler.release used in the build. |
| 5 | Capabilities このエクステンションは以下を提供します。 |
| 6 | 他のエクステンションへの直接の依存関係 |
| 7 | The source code repository of this extension. Optional, and will often be set automatically by using the <scm> information in the pom. In GitHub Actions builds, it will be inferred from the CI environment. For other GitHub repositories, it can be controlled by setting a GITHUB_REPOSITORY environment variable. |
| 8 | このエクステンションモジュールのスポンサー。オプションであり、コミット履歴から自動的に決定されることもあります。 |
META-INF/quarkus-extension.properties
すべての ランタイム エクステンションアーティファクトには、必ずこのファイルが含まれている必要があります。このファイルは Quarkus ブートストラップメカニズムで読み取られ、アプリケーションの ビルドまたはブートストラップ に関連する情報のみを含むためのものです。このファイルは通常、エクステンションプロジェクトのビルド時に対応する Quarkus Maven または Gradle プラグインによって生成され、手動で編集してはなりません。このファイルには、次のプロパティーが表示される場合があります。
| Name | Presence | Description |
|---|---|---|
|
必須 |
|
|
オプション |
親から先にロードされるアーティファクトキー ( |
|
オプション |
アプリケーションが本番バイナリーパッケージから起動されたときに、 |
|
オプション |
クラスローダーによってロードされず、最終的なアプリケーションにパックされないアーティファクトキーのコンマ区切りリスト。 |
|
オプション |
クラスまたはリソースを含む他のアーティファクトが存在しない場合にのみ、そのクラスまたはリソースをロードするために使用されるアーティファクトキーのコンマ区切りリスト。これは、複数のアーティファクトに同じクラスが含まれている場合に、アーティファクトの順番を制御するために使用されます。 |
|
オプション |
依存関係から削除/非表示にする必要があるリソース。これにより、クラスやその他のリソースを依存関係から削除できるため、アプリケーションからアクセスできなくなります。これは、削除するリソースのコンマ区切りリストへのアーティファクトキーのマップです。開発およびテストモードで実行している場合、これらのリソースは ClassLoader から非表示になり、実稼働モードで実行している場合、これらのファイルはそれらを含む jar から削除されます。クラスを削除する場合は、クラスファイル名を指定する必要があることに注意してください。たとえば、com.acme.Foo を削除するには、com/acme/Foo.class を指定します。 |
|
オプション |
このエクステンションが提供する 機能 のリスト。 |
|
オプション |
他の Quarkus エクステンションからこのエクステンションに提供する必要がある 機能 のリスト。 |
|
オプション |
このエクステンションが宣言する 条件付き依存関係 のリスト。 |
|
オプション |
このエクステンションへの条件付き依存関係を有効にするために満たす必要がある 依存関係の条件 |
META-INF/quarkus-config-roots.list
このファイルは、ランタイムエクステンションアーティファクトおよびデプロイメントアーティファクトに表示される場合があります。このファイルは手動で編集しないでください。これは、エクステンションプロジェクトのビルドプロセスの一部として生成され、エクステンションが提供する io.quarkus.runtime.annotations.ConfigRoot でアノテーションが付けられた Java クラス名のリストが含まれています。
