The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.
Back to Guides
このページを編集

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

Every runtime extension artifact must include this file. This file is used by Quarkus dev tools when displaying information about an extension, creating a new project or adding extensions to an existing project, etc. This file isn’t used at application build or bootstrap times. The basic and required metadata included in this file can be generated by the Quarkus Maven and Gradle plugins when the extension artifact is built. However, typically, extension authors will want to provide more information about the extension to the Quarkus dev tools and users. The extra information could be provided in a template META-INF/quarkus-extension.yaml found in the extension runtime module’s resources directory, e.g. src/main/resources/META-INF/quarkus-extension.yaml. Here is an example of such a template for the quarkus-rest extension:

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 このエクステンションモジュールのスポンサー。オプションであり、コミット履歴から自動的に決定されることもあります。

Extension offerings

This bit of metadata was introduced in Quarkus 3.26.0 and it will be evolving in the upcoming versions.

An offering is a set of extensions that are delivered and supported by a dedicated team or an organization under certain conditions. An extension may be associated with one or more offerings by adding <offering-id>-support field to its metadata, specifying support scope as its value. For example, here is a relevant snippet of metadata illustrating how it could look like:

name: "Acme Quarkus Magic"
artifact: "com.acme.quarkus:acme-quarkus-magic:999-SNAPSHOT"
metadata:
  acme-cloud-support: [ "supported" ], (1)
  team-x: [ "tech-preview" ] (2)
1 Associates acme-quarkus-magic with acme-cloud offering with support scope supported;
2 Associates acme-quarkus-magic with team-x offering with support scope tech-preview.

The meaning of support scopes, such as supported and tech-preview, would be defined in the offering documentation by the corresponding team or organization.

Offerings and support scopes may be used by Quarkus dev tools, such as Quarkus CLI and code.quarkus, to display and/or filter extensions by the relevant support-related information.

META-INF/quarkus-extension.properties

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

名前 Presence 説明

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

オプション

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

dev-mode.jvm-option.std.<option-name>=<option-value>

オプション

開発モードでアプリケーションを起動するコマンドラインに追加する必要がある標準の Java コマンドラインオプション

dev-mode.jvm-option.xx.<option-name>=<option-value>

オプション

-XX: 開発モードでアプリケーションを起動するコマンドラインに追加する必要がある Java コマンドラインオプション

dev-mode.lock.jvm-options

オプション

Quarkus Maven および Gradle プラグインによってデフォルトで事前設定された値によって上書きされるべきではない、標準の Java コマンドラインオプションのコンマ区切りリスト。

dev-mode.lock.xx-jvm-options

オプション

Quarkus Maven および Gradle プラグインによってデフォルトで事前設定された値によって上書きされるべきではない -XX: Java コマンドラインオプションのコンマ区切りリスト

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 コンパイラーを無効化することも可能です。

関連コンテンツ

同じトピックについて

Quarkus is open. All dependencies of this project are available under the Apache Software License 2.0 or compatible license. CC by 3.0

This website was built with Jekyll, is hosted on GitHub Pages and is completely open source. If you want to make it better, fork the website and show us what you’ve got.

ナビゲーション
フォローする
ヘルプ
言語
Quarkusはコミュニティプロジェクトで構成されています
Copyright © Quarkus. All rights reserved. For details on our trademarks, please visit our Trademark Policy and Trademark List. Trademarks of third parties are owned by their respective holders and their mention here does not suggest any endorsement or association.