Quarkus Extension Metadata
Quarkus エクステンションは、アプリケーションや他のライブラリーが依存する Maven JAR アーティファクトとして配布されます。Quarkus アプリケーションプロジェクトを Quarkus 開発ツールを使用してビルド、テスト、編集すると、Quarkus エクステンション JAR アーティファクトは、その中の Quarkus エクステンションメタデータファイルの存在によって、アプリケーションクラスパス上で識別されます。このドキュメントでは、各 Quarkus エクステンションメタデータファイルの目的とその内容について説明しています。
メタデータファイルのうち 2 つは、 quarkus-extension.yaml と quarkus-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: "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 | このエクステンションに必要な Quarkus バージョンの範囲。オプションであり、最小範囲として built-with-quarkus-core を使用して自動的に設定されます。 |
| 4 | このエクステンションの実行に必要な最小 Java バージョン。ビルドで使用される maven.compiler.release に基づいて生成されます。 |
| 5 | Capabilities このエクステンションは以下を提供します。 |
| 6 | 他のエクステンションへの直接の依存関係 |
| 7 | このエクステンションモジュールのソースコードリポジトリー。オプションで、多くの場合は pom 内の <scm> の情報を使って自動的に設定されます。GitHub Actions のビルドでは、CI 環境から推測されます。その他の GitHub リポジトリーの場合は、 GITHUB_REPOSITORY 環境変数で指定します。 |
| 8 | このエクステンションモジュールのスポンサー。オプションであり、コミット履歴から自動的に決定されることもあります。 |
META-INF/quarkus-extension.properties
すべての ランタイム エクステンションアーティファクトには、必ずこのファイルが含まれている必要があります。このファイルは Quarkus ブートストラップメカニズムで読み取られ、アプリケーションの ビルドまたはブートストラップ に関連する情報のみを含むためのものです。このファイルは通常、エクステンションプロジェクトのビルド時に対応する Quarkus Maven または Gradle プラグインによって生成され、手動で編集してはなりません。このファイルには、次のプロパティーが表示される場合があります。
| 名前 | Presence | 説明 |
|---|---|---|
|
必須 |
|
|
オプション |
親から先にロードされるアーティファクトキー ( |
|
オプション |
アプリケーションが本番バイナリーパッケージから起動されたときに、 |
|
オプション |
クラスローダーによってロードされず、最終的なアプリケーションにパックされないアーティファクトキーのコンマ区切りリスト。 |
|
オプション |
クラスまたはリソースを含む他のアーティファクトが存在しない場合にのみ、そのクラスまたはリソースをロードするために使用されるアーティファクトキーのコンマ区切りリスト。これは、複数のアーティファクトに同じクラスが含まれている場合に、アーティファクトの順番を制御するために使用されます。 |
|
オプション |
依存関係から削除/非表示にする必要があるリソース。これにより、クラスやその他のリソースを依存関係から削除できるため、アプリケーションからアクセスできなくなります。これは、削除するリソースのコンマ区切りリストへのアーティファクトキーのマップです。開発およびテストモードで実行している場合、これらのリソースは ClassLoader から非表示になり、実稼働モードで実行している場合、これらのファイルはそれらを含む jar から削除されます。クラスを削除する場合は、クラスファイル名を指定する必要があることに注意してください。たとえば、com.acme.Foo を削除するには、com/acme/Foo.class を指定します。 |
|
オプション |
このエクステンションが提供する 機能 のリスト。 |
|
オプション |
他の Quarkus エクステンションからこのエクステンションに提供する必要がある 機能 のリスト。 |
|
オプション |
このエクステンションが宣言する 条件付き依存関係 のリスト。 |
|
オプション |
このエクステンションへの条件付き依存関係を有効にするために満たす必要がある 依存関係の条件 |
|
オプション |
開発モードでアプリケーションを起動するコマンドラインに追加する必要がある標準の Java コマンドラインオプション |
|
オプション |
|
|
オプション |
Quarkus Maven および Gradle プラグインによってデフォルトで事前設定された値によって上書きされるべきではない、標準の Java コマンドラインオプションのコンマ区切りリスト。 |
|
オプション |
Quarkus Maven および Gradle プラグインによってデフォルトで事前設定された値によって上書きされるべきではない |
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 でアノテーションが付けられたメソッド) を実装するクラスのリストが含まれています。このファイルは、エクステンションプロジェクトのビルドプロセスの一部として生成されます。このファイルを手動で編集してはなりません。
Quarkus エクステンション Maven プラグイン
quarkus-extension-maven-plugin は、Quarkus 拡張 Maven プロジェクトのランタイムモジュールで設定され、次の目的を果たします。
-
エクステンションメタデータ設定を検証します。
-
エクステンションメタデータを生成します。
-
エクステンションの依存関係が Quarkus エクステンションの依存関係モデルに準拠しているかどうかを確認します。
開発モードの JVM オプション
エクステンションは、開発モードでアプリケーションを起動する際に、コマンドラインに追加すべき特定の Java コマンドラインオプションを事前に設定できます。以下に、そのようなオプションを quarkus-extension-maven-plugin の設定で構成する方法を示します。
<plugin>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-extension-maven-plugin</artifactId>
<version>${quarkus.version}</version>
<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>extension-descriptor</goal>
</goals>
<configuration>
<devMode>
<jvmOptions>
<add-modules>jdk.incubator.vector</add-modules>
<enable-preview/>
<enable-native-access>ALL-UNNAMED</enable-native-access>
</jvmOptions>
<xxJvmOptions>
<UseThreadPriorities>false</UseThreadPriorities>
</xxJvmOptions>
<lockJvmOptions>agentlib:jdwp</lockJvmOptions>
<lockXxJvmOptions>TieredStopAtLevel</lockXxJvmOptions>
</devMode>
</configuration>
</execution>
</executions>
</plugin>extension-descriptor は、対応するプロパティーを持つ META-INF/quarkus-extension.properties を生成することが目的です。
また、このエクステンションに依存するアプリケーションが開発モードで起動されると、ログは次のとおりです。
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) Adding JVM options from org.acme:quarkus-blue::jar
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) enable-native-access: [ALL-UNNAMED]
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) add-modules: [jdk.incubator.vector]
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) enable-preview: []
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) UseThreadPriorities: [false]
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) org.acme:quarkus-blue::jar locks JVM options [TieredStopAtLevel, agentlib:jdwp]
[INFO] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] Extension org.acme:quarkus-blue enables the C2 compiler which is disabled by default in Dev mode for optimal performance.
[INFO] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] Extension org.acme:quarkus-blue disables the Debug mode for optimal performance. Debugging can still be enabled in the Quarkus plugin configuration or with -Ddebug on the command line.
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) Executable jar: /home/<username>/app/target/acme-app-dev.jar
[DEBUG] Launching JVM with command line: /home/<username>/jdk/bin/java -Dquarkus-internal.serialized-app-model.path=/home/<username>/app/target/quarkus/bootstrap/dev-app-model.dat -javaagent:/home/<username>/.m2/repository/io/quarkus/quarkus-class-change-agent/{quarkus-verion}/quarkus-class-change-agent-{quarkus-version}.jar --enable-native-access=ALL-UNNAMED --add-modules=jdk.incubator.vector --enable-preview -XX:-UseThreadPriorities -Djava.util.logging.manager=org.jboss.logmanager.LogManager -jar /home/<username>/app/target/acme-app-dev.jarなお、INFO メッセージがいくつか表示され、開発モードで Quarkus がデフォルトで使用する特定のオプションの値が、エクステンションの設定によって上書きされたことをユーザーに通知します。具体的には、C2 コンパイラーが再度有効化され、デバッグモードが無効化されました。ただし、ユーザーは必要に応じて、対応する Quarkus Maven または Gradle プラグインのパラメーター値を明示的に設定することで、デバッグエージェントを有効化し、C2 コンパイラーを無効化することも可能です。
