Infinispan キャッシュ
デフォルトでは、Quarkus Cache はバックエンドとして Caffeine を使用します。 代わりに Infinispan を使用することも可能です。
|
この技術は、previewと考えられています。 preview では、下位互換性やエコシステムでの存在は保証されていません。具体的な改善には設定や API の変更が必要になるかもしれませんが、 stable になるための計画は現在進行中です。フィードバックは メーリングリスト や GitHub の課題管理 で受け付けています。 とりうるステータスの完全なリストについては、 FAQの項目 を参照してください。 |
キャッシュバックエンドとしての Infinispan
Quarkus キャッシュのバックエンドとして Infinispan を使用する場合、キャッシュされた各アイテムは Infinispan に保存されます。
-
バックエンドは (別の設定がされていない限り) <default> Infinispan クライアントを使用するため、適切に セットアップされていることを確認してください (または、Infinispan Dev Service を使用してください)。
-
キーと値の両方が Protostream を使用して Protobuf でマーシャリングされます。
Infinispan バックエンドの使用
まず、プロジェクトに quarkus-infinispan-cache エクステンションを追加します。
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-infinispan-cache</artifactId>
</dependency>implementation("io.quarkus:quarkus-infinispan-cache")次に、Quarkus キャッシュガイド に詳述されているように、@CacheResult やその他のキャッシュアノテーションを使用します。
@GET
@Path("/{keyElement1}/{keyElement2}/{keyElement3}")
@CacheResult(cacheName = "expensiveResourceCache")
public ExpensiveResponse getExpensiveResponse(@PathParam("keyElement1") @CacheKey String keyElement1,
@PathParam("keyElement2") @CacheKey String keyElement2, @PathParam("keyElement3") @CacheKey String keyElement3,
@QueryParam("foo") String foo) {
invocations.incrementAndGet();
ExpensiveResponse response = new ExpensiveResponse();
response.setResult(keyElement1 + " " + keyElement2 + " " + keyElement3 + " too!");
return response;
}
@POST
@CacheInvalidateAll(cacheName = "expensiveResourceCache")
public void invalidateAll() {
}Infinispan バックエンドの設定
Infinispan バックエンドは <default> Infinispan クライアントを使用します。
Infinispan へのアクセスを設定するには、Infinispan リファレンス を参照してください。
| 開発モードでは、Infinispan Dev Service を使用できます。 |
キャッシュに別の Infinispan を使用する場合は、client-name を以下のように設定します。
quarkus.cache.infinispan.client-name=anotherマーシャリング
Quarkus で Infinispan と対話する場合、キャッシュにデータを保存したり、キャッシュからデータを取得する際に、Java プリミティブ型を簡単にシリアル化およびデシリアル化できます。Infinispan には追加のマーシャリング設定は必要ありません。
@CacheResult(cacheName = "weather-cache") (1)
public String getDailyForecast(String dayOfWeek, int dayOfMonth, String city) { (2)
return dayOfWeek + " will be " + getDailyResult(dayOfMonth % 4) + " in " + city;
}| 1 | このメソッドの実行を 'weather-cache' にキャッシュするよう指定します。 |
| 2 | キーは、String dayOfWeek、int dayOfMonth、および String city を組み合わせたものです。関連付けられている値は String 型です。 |
Quarkus はデフォルトで Infinispan におけるデータのシリアル化に Protobuf を使用します。Infinispan は データを構造化する方法 として Protobuf を推奨しています。したがって、Plain Old Java Objects (POJO) を使用する場合、ユーザーは Infinispan での マーシャリング用のスキーマを提供する必要があります。
Java 型のマーシャリング
java.time.LocalDate を使用して複合キーを作成するとします。
@CacheResult(cacheName = "weather-cache") (1)
public String getDailyForecast(LocalDate date, String city) { (2)
return date.getDayOfWeek() + " will be " + getDailyResult(date.getDayOfMonth() % 4) + " in " + city;
}| 1 | このメソッド実行の応答を 'weather-cache' にキャッシュするようにリクエストします。 |
| 2 | キーは、java.util.LocalDate の日付と String city を組み合わせたものです。関連付けられた値は 'String' 型です。 |
Infinispan はデフォルトで Quarkus の Protobuf を使用してデータをシリアル化するため、コードを実行すると以下のエラーが発生します。
java.lang.IllegalArgumentException:
No marshaller registered for object of Java type java.time.LocalDateProtobuf は、java.time.LocalDate をマーシャリングする方法を本来は認識していません。幸いなことに、Protostream は @ProtoAdapter と @ProtoSchema を使用して、この問題に対する簡単な解決策を提供します。
@ProtoAdapter(LocalDate.class)
public class LocalDateAdapter {
@ProtoFactory
LocalDate create(String localDate) {
return LocalDate.parse(localDate);
}
@ProtoField(1)
String getLocalDate(LocalDate localDate) {
return localDate.toString();
}
}
@ProtoSchema(includeClasses = LocalDateAdapter.class, schemaPackageName = "quarkus")
public interface Schema extends GeneratedSchema {
}POJO のマーシャリング
Java 型の場合と同様に、POJO をキーまたは値として使用する場合は、以下のアプローチに従うことができます。
@CacheResult(cacheName = "my-cache") (1)
public ExpensiveResponse requestApi(String id) { (2)
// very expensive call
return new ExpensiveResponse(...);
}| 1 | このメソッド実行の応答を 'my-cache' にキャッシュするようにリクエストします。 |
| 2 | キーは String です。関連付けられている値は org.acme.ExpensiveResponse 型です。 |
この場合、@Proto と @ProtoSchema を使用して Java 型のスキーマを定義する必要があります。このスキーマには、Quarkus アプリケーションで使用されるすべての型とアダプターを含めることができます。
@Proto
public record ExpensiveResponse(String result) {
}
@ProtoSchema(includeClasses = { ExpensiveResponse.class })
interface Schema extends GeneratedSchema {
}詳細は、アノテーションベースのシリアル化セクションの Infinispan リファレンス を参照してください。
有効期限
データの有効期限については、lifespan と max-idle の 2 つのプロパティーを設定するオプションがあります。
存続期間
Infinispan では、lifespan は設定パラメーターの 1 つであり、エントリー (またはオブジェクト) が、 作成または最終アクセスされてから期限切れと見なされキャッシュから削除されるまで、 キャッシュに残ることができる最大時間を決定します。
Infinispan キャッシュのエントリーに lifespan パラメーターを設定すると、 期間を指定します。エントリーがキャッシュに追加されるかアクセスされた (読み取りまたは書き込み) 後、そのエントリーの存続期間のカウントダウンが始まります。エントリーの 作成または最終アクセスからの経過時間が、指定された「存続期間」を超えた場合、そのエントリーは 期限切れと見なされ、キャッシュから削除の対象となります。
quarkus.cache.infinispan.my-cache.lifespan=10sMax Idle
Infinispan キャッシュのエントリーに max-idle パラメーターを設定する場合、時間を指定します。 キャッシュ内のエントリーがアクセス (読み取りまたは書き込み) された後、指定された期間内に そのエントリーに対してその後アクセスがない場合は、アイドル状態とみなされます。アイドル時間が max-idle 期間を超えると、エントリーは期限切れとみなされ、キャッシュからのエビクションの 対象となります。
quarkus.cache.infinispan.my-cache.max-idle=100sビルド時に固定された設定プロパティー。その他の設定プロパティーはすべてランタイム時にオーバーライド可能です。
Configuration property |
タイプ |
デフォルト |
|---|---|---|
The name of the named Infinispan client to be used for communicating with Infinispan. If not set, use the default Infinispan client. Environment variable: Show more |
string |
|
The default lifespan of the item stored in the cache Environment variable: Show more |
||
The default max-idle of the item stored in the cache Environment variable: Show more |
||
Additional configuration applied to a specific Infinispan cache (highest precedence) |
タイプ |
デフォルト |
The default lifespan of the item stored in the cache Environment variable: Show more |
||
The default max-idle of the item stored in the cache Environment variable: Show more |
|
期間フォーマットについて
To write duration values, use the standard 数字で始まる簡略化した書式を使うこともできます:
その他の場合は、簡略化されたフォーマットが解析のために
|
