コンテキストと依存性インジェクション

Jandex インデックスを持つ依存関係は、Bean に対して自動的にスキャンされます。インデックスを生成するには、次のプラグインをビルドファイルに追加するだけです。

依存関係を変更できなくても、quarkus.index-dependency エントリーを application.properties に追加することでインデックスを作成できます。

たとえば、次のエントリーは、org.acme:acme-api 依存関係が確実にインデックス化されるようにします。

サードパーティーのライブラリーからのいくつかの Bean が Quarkus で正しく動作しないことがあります。典型的な例は、ポータブル拡張機能を注入する Bean です。このような場合は、型や依存関係を Bean の検出から除外することができます。quarkus.arc.exclude-types プロパティーは、除外すべきクラスに一致するために使用される文字列値のリストを受け入れます。

また、除外しなければ Bean をスキャンする、依存関係のあるアーティファクトを除外することも可能です。たとえば、beans.xml 記述子を含んでいる場合です。

リクエストコンテキストは次の場合もアクティブになっています:

リクエストコンテキストは破棄されます:

CDI では、フィールド注入ポイントを宣言する場合は @Inject と任意で修飾子のセットを使用する必要があります。

Quarkus では、注入されたフィールドが少なくとも 1 つの修飾子を宣言している場合は、@Inject アノテーションを完全にスキップすることができます。

CDI では、通常のスコープ付き Bean は常に no-args コンストラクターを宣言しなければなりません (このコンストラクターは、他のコンストラクターを宣言しない限り、通常はコンパイラーによって生成されます)。しかし、この要件はコンストラクターの注入を複雑にします。CDI で動作させるためにはダミーの no-args コンストラクターを提供する必要があります。

Quarkus では、通常のスコープ付き Bean のためにダミーのコンストラクターを宣言する必要はありません。自動的に生成されます。また、コンストラクターが 1 つしかない場合は、@Inject の必要性はありません。

コンテナーは、デフォルトでビルド中に未使用の Bean、インターセプター、デコレーターをすべて削除しようとします。この最適化は、生成されるクラスの量を最小限に抑え、メモリーを節約するのに役立ちます。ただし、Quarkus は、CDI.current() staticメソッドを介して実行されたプログラムによるルックアップを検出できません。したがって、削除すると誤検知エラーが発生する可能性があります。つまり、Bean は実際に使用されていても、削除されます。このような場合、ログに大きな警告が表示されます。ユーザーとエクステンションの作成者にはいくつかのオプションがあります: how to eliminate false positives。

この最適化は、quarkus.arc.remove-unused-beans を none または false に設定することで無効にすることができます。Quarkus では、アプリケーションの Bean は未使用かどうかにかかわらず削除されず、アプリケーション以外のクラスは通常通りに最適化が行われるという中間モードも提供されています。このモードを使用するには、quarkus.arc.remove-unused-beans を fwk または framework に設定します。

Quarkus は、CDI が現在サポートしていない機能を追加します。これは、利用可能な手段 (Beanクラス、producer、合成 Bean など) で同等の型と修飾子を持つ他の Bean が宣言されていない場合に、条件付きで Bean を宣言することです。これは、@io .quarkus.Arc.DefaultBean アノテーションを使用して行われ、例を挙げて説明するのが最善です。

以下のコードのようにいくつかの CDI Bean を宣言する Quarkus エクステンションがあるとします。

アイデアは、エクステンションがユーザーのために自動設定を行い、多くのボイラープレートを排除するということです。必要な場所であれば、@Inject を Tracer にすることができます。私たちのアプリケーションで、設定された Tracer を利用しようとする場合は、、カスタムの Reporter を提供するなど、少しカスタマイズする必要があります。アプリケーションで必要になるのは、次のようなものだけです。

@DefaultBean では、エクステンション (またはそのための他のコード) が Quarkus がサポートする何らかの方法でその型の Bean が提供されている場合、バックオフ中にデフォルトを提供することができます。

Default beans can optionally declare @jakarta.annotation.Priority. If there is no priority defined, @Priority(0) is assumed. Priority value is used for bean ordering and during typesafe resolution to disambiguate multiple matching default beans.

Quarkus は、CDI が現在サポートしていない機能を追加しました。これは、Quarkus のビルドタイムプロファイルが有効になっているときに条件付きで Bean を有効にするというもので、@io.quarkus.arc.profile.IfBuildProfile と @io.quarkus.arc.profile.UnlessBuildProfile のアノテーションを使用します。@io.quarkus.arc.DefaultBean と合わせて使用すると、これらのアノテーションにより、異なるビルドプロファイルに対して異なる Bean 構成を作成することができます。

たとえば、アプリケーションが Tracer という名前の Bean を含んでいるとします。この Bean は、テストや開発モードでは何もする必要はありませんが、本番の成果物に対しては通常の能力で動作します。このような Bean を作成する洗練された方法は以下の通りです。

代わりに、Tracer Bean も開発モードで動作し、デフォルトではテストのために何もしないことが要求される場合は、@UnlessBuildProfile が理想的です。コードは次のようになります。

Quarkus には、CDI が現在サポートしていない機能が追加されています。それは、@io.quarkus.arc.properties.IfBuildProperty と @io.quarkus.arc.properties.UnlessBuildProperty アノテーションを使用して、ビルドタイムプロパティーが特定の値であるかないときにBeanを条件付きで有効にするものです。このアノテーションを @io.quarkus.arc.DefaultBean と一緒に使用すると、ビルドプロパティーごとに異なるBean設定を作成することが可能になります。

Tracer を使用して上で述べたシナリオも、以下のように実装することができます。

代わりに、some.tracer.enabled プロパティーが false でない場合にのみ RealTracer Bean が使用されることが要求される場合は、@UnlessBuildProperty が理想的です。コードは以下のようになります。

CDI では、代替の Bean は、@Priority を使用してアプリケーションに対してグローバルに選択することも、beans.xml 記述子を使用した Bean アーカイブ用に選択することもできます。Quarkus には単純化された Bean 検出があり、`beans.xml`の内容は無視されます。

However, it is also possible to select alternatives for an application using the unified configuration. The quarkus.arc.selected-alternatives property accepts a list of string values that are used to match alternative beans. If any value matches then the priority of Integer#MAX_VALUE is used for the relevant bean. The priority declared via @Priority or inherited from a stereotype is overridden.

CDI では、producer メソッドは常に @Produces とアノテーションされていなければなりません。

Quarkus では、producer メソッドにスコープアノテーション、ステレオタイプ、または修飾子が付いている場合は、@Produces アノテーションを完全に省略できます。

インターセプターの仕様は、around-invoke メソッドを静的宣言してはならないことは明らかです。しかし、この制限は、主に技術的な制限によって設定されました。Quarkus は追加のクラス変換を可能にするビルド時指向のスタックであるため、この制限は適用されなくなりました。インターセプタ―バインディングで非プライベートの静的メソッドにアノテーションを付けることができます。

通常の CDI では、final としてマークされているクラス、または final メソッドを持つクラスは、プロキシー作成の対象になりません。これは、インターセプターと通常のスコープ Bean が正しく動作しないことを意味します。このような状況は、クラスおよびメソッドがデフォルトで `final`である Kotlin のような代替 JVM 言語で CDI を使用しようとするときに非常に一般的です。

しかし、Quarkus では、quarkus.arc.transform-unproxyable-classes を true (デフォルト値) に設定すると、これらの制限を抑制することができます。

CDI Bean の標準的な同時実行制御メカニズムはありません。それにもかかわらず、Bean インスタンスは、複数のスレッドから同時に共有およびアクセスすることができます。その場合は、スレッドセーフでなければなりません。標準の Java コンストラクト (volatile、synchronized、ReadWriteLock など) を使用するか、コンテナーに同時アクセスを制御させることができます。Quarkus は、@io.quarkus.arc.Lock と、このインターセプタ―バインディング用の組み込みインターセプターを提供します。傍受された Bean のコンテキストインスタンスに関連付けられた各インターセプターインスタンスは、公平でない順序付けポリシーを持つ ReadWriteLock を保持しています。

Quarkusでは、@Repeatable インターセプター結合アノテーションのサポートが制限されています。

インターセプタ―をコンポーネントにバインドする場合は、メソッドに対して複数の @Repeatable アノテーションを宣言できます。インターセプター仕様との相互作用に関する未解決の質問があるため、クラスとステレオタイプで宣言された反復可能なインターセプターバインディングはサポートされていません。これは将来追加される可能性があります。

たとえば、キャッシュをクリアするインターセプタ―があるとします。対応するインターセプタ―バインディングは @CacheInvalidateAll と呼ばれ、@Repeatable として宣言されます。同時に 2 つのキャッシュをクリアしたい場合は、@CacheInvalidateAll を 2 回追加します。

ここまで、インターセプタ―がどのように使用されるかを説明しました。では、インターセプターを作成するにはどうすれば良いでしょうか。

インターセプタ―のインターセプタ―バインディングを宣言する場合は、通常どおり、インターセプタ―クラスに複数の @Repeatable アノテーションを追加できます。@Cached アノテーションの場合と同様に、アノテーションメンバーが @Nonbinding の場合は役に立ちませんが、それ以外の場合は重要になります。

たとえば、メソッド呼び出しを特定のターゲットに自動的に記録できるインターセプタ―があるとします。インターセプタ―バインディングアノテーション @Logged には、ログを保存する場所を指定する target というメンバーがあります。この実装は、コンソールログとファイルロギングに制限することができます。

他にも、異なるターゲットへのメソッド呼び出しをログに記録するためのインターセプターを提供することができます。

In certain situations, it is practical to obtain a bean instance programmatically via an injected jakarta.enterprise.inject.Instance and Instance.get(). However, according to the specification the get() method must identify the matching bean and obtain a contextual reference. As a consequence, a new instance of a @Dependent bean is returned from each invocation of get(). Moreover, this instance is a dependent object of the injected Instance. This behavior is well-defined, but it may lead to unexpected errors and memory leaks. Therefore, Quarkus comes with the io.quarkus.arc.WithCaching annotation. An injected Instance annotated with this annotation will cache the result of the Instance#get() operation. The result is computed on the first call and the same value is returned for all subsequent calls, even for @Dependent beans.

jakarta.enterprise.inject.Instance を介したプログラムによる検索で取得できる Bean の集合を絞り込むことが有用な場合があります。典型的には，ユーザは，実行時設定プロパティに基づいて，インタフェースの適切な実装を選択する必要があります。

インターフェイス org.acme.Service を実装した 2 つの Bean があるとします。実装が CDI 修飾子を宣言していない限り、org.acme.Service を直接注入することはできません。しかし、代わりに Instance<Service> を注入して、すべての実装を繰り返し、正しいものを手動で選択することができます。また、@LookupIfProperty と @LookupUnlessProperty アノテーションを利用することもできます。@LookupIfProperty は、実行時設定プロパティーが提供された値と一致する場合にのみ、Bean を取得する必要があることを示します。一方、@LookupUnlessProperty は、実行時設定プロパティーが提供された値と一致しない場合にのみ、Bean を取得する必要があることを示します。

If there is more than one bean that matches the required type and qualifiers and is eligible for injection, it is possible to iterate (or stream) available bean instances. Beans returned by both stream and iterator methods are sorted by priority as defined by io.quarkus.arc.InjectableBean#getPriority(). Higher priority goes first. If no priority is explicitly declared, 0 is assumed.

CDIでは、 java.lang.Iterable を実装した jakarta.enterprise.inject.Instance を介して、複数のBeanインスタンス（別名：コンテキスト参照）を注入することが可能です。しかし、これは直感的に理解できるものではありません。そこで、Quarkusでは新しい方法を導入しました。 io.quarkus.arc.All 修飾子でアノテーションされた java.util.List を注入することができます。リスト内の要素の型は、検索を実行する際に必要な型として使用されます。

インジェクションポイントが @All 以外の修飾子を宣言していない場合、@Any が使用されます。つまり、動作は @Inject @Any Instance<Service> と同等です。

io.quarkus.arc.InstanceHandle でラップされた Bean インスタンスのリストを注入することもできます。これは、関連する Bean メタデータを検査する必要がある場合に役立ちます。

マネージド Bean がクラスレベルでインターセプターバインディングアノテーションを宣言する場合、対応する @AroundInvoke インターセプターがすべてのビジネスメソッドに適用されます。同様に、対応する @AroundConstruct インターセプターが Bean コンストラクターに適用されます。

たとえば、@Logged バインディングアノテーションを持つロギングインターセプターと @Traced バインディングアノテーションを持つトレースインターセプターがあるとします。

この例では、doSomething と doSomethingElse の両方が架空のロギングインターセプターによってインターセプトされます。さらに、doSomethingElse メソッドは、架空のトレースインターセプターによってインターセプトされます。

もし @Traced インターセプターが必要なロギングもすべて行っていた場合、このメソッドでは @Logged インターセプターを省略したいのですが、他のすべてのメソッドではそのままにしておきたいと思います。これを実現するには、メソッドに @NoClassInterceptors というアノテーションを付けます。

@NoClassInterceptors アノテーションはメソッドとコンストラクターに付けることができ、これらのメソッドとコンストラクターではすべてのクラスレベルのインターセプターが無視されることを意味します。つまり、メソッド/コンストラクターに @NoClassInterceptors アノテーションが付けられている場合、このメソッド/コンストラクターに適用されるインターセプターは、メソッド/コンストラクターで直接宣言されたインターセプターのみです。

このアノテーションは、ビジネスメソッドインターセプター (@AroundInvoke) とコンストラクターライフサイクルコールバックインターセプター (@AroundConstruct) にのみ影響します。

If an exception is thrown by an asynchronous observer then the CompletionStage returned by the fireAsync() method completes exceptionally so that the event producer may react appropriately. However, if the event producer does not care then the exception is ignored silently. Therefore, Quarkus logs an error message by default. It is also possible to implement a custom AsyncObserverExceptionHandler. A bean that implements this interface should be @jakarta.inject.Singleton or @jakarta.enterprise.context.ApplicationScoped.

Quarkus supports what is known as intercepted self-invocation or just self-interception - a scenario where CDI bean invokes its own intercepted method from within another method while triggering any associated interceptors. This is a non-standard feature as CDI specification doesn’t define whether self-interception should work or not.

Suppose we have a CDI bean with two methods, one of which has the @Transactional interceptor binding associated with it:

In the above example, any code calling the doSomething() method triggers interception - in this case, the method becomes transactional. This is regardless of whether the invocation originated directly from the MyService bean (such as MyService#doSomethingElse) or from some other bean.

By default, interception is only supported for managed beans (also known as class-based beans). To support interception of producer methods and synthetic beans, the CDI specification includes an InterceptionFactory, which is a runtime oriented concept and therefore cannot be supported in Quarkus.

Instead, Quarkus has its own API: InterceptionProxy and @BindingsSource. The InterceptionProxy is very similar to InterceptionFactory: it creates a proxy that applies @AroundInvoke interceptors before forwarding the method call to the target instance. The @BindingsSource annotation allows setting interceptor bindings in case the intercepted class is external and cannot be changed.

In this example, interceptor bindings are read from the MyClass class.

The intercepted class should be proxyable and therefore should not be final, should not have non-private final methods, and should have a non-private zero-parameter constructor. If it isn’t, a bytecode transformation will attempt to fix it if enabled, but note that adding a zero-parameter constructor is not always possible.

It is often the case that the produced classes come from external libraries and don’t contain interceptor binding annotations at all. To support such cases, the @BindingsSource annotation may be declared on the InterceptionProxy parameter:

The concept of bindings source is a build-time friendly equivalent of InterceptionFactory.configure().

Per the CDI specification, the Instance.Handle.close() method always delegates to destroy(). In ArC, this is only true in the ストリクトモード.

In the default mode, the close() method only delegates to destroy() when the bean is @Dependent (or when the instance handle does not represent a CDI contextual object). When the instance handle represents a bean of any other scope, the close() method does nothing; the bean is left as is and will be destroyed whenever its context is destroyed.

This is to make the following code behave as one would naively expect:

The @Dependent beans are destroyed immediately, while other beans are not destroyed at all. This is important when multiple beans of different scopes might be returned by the Instance.

The io.quarkus.runtime.BlockingOperationControl#isBlockingAllowed() method can be used to detect whether blocking is allowed on the current thread. When it is not, and you need to perform a blocking operation, you have to offload it to another thread. The easiest way is to use the Vertx.executeBlocking() method:

CDI asynchronous observers (@ObservesAsync) are not aware of reactive programming and are not meant to be used as part of reactive pipelines. The observer methods are meant to be synchronous, they are just offloaded to a thread pool.

The Event.fireAsync() method returns a CompletionStage that completes when all observers are notified. If all observers were notified successfully, the CompletionStage completes with the event payload. If some observers have thrown an exception, the CompletionStage completes exceptionally with a CompletionException.

The return type of the observer does not matter. The return value of the observer is ignored.

You may declare an observer method that has a return type of CompletionStage<> or Uni<>, but neither the return type nor the actual return value affect the result of Event.fireAsync(). Further, if the observer declares a return type of Uni<>, the returned Uni will not be subscribed to, so it is quite possible that part of the observer logic will not even execute.

Therefore, it is recommended that observer methods, both synchronous and asynchronous, are always declared void.

In dev mode, it is also possible to enable monitoring of business method invocations and fired events. Simply set the quarkus.arc.dev-mode.monitoring-enabled configuration property to true and explore the relevant Dev UI pages.