インターフェース Cache
- すべての既知の実装クラス:
AbstractValueAdaptingCache
、CaffeineCache
、ConcurrentMapCache
、JCacheCache
、NoOpCache
、TransactionAwareCacheDecorator
主に Spring のアノテーションベースのキャッシュモデル (Cacheable
など) の SPI として機能し、次にアプリケーションで直接使用するための API として機能します。
注意 : キャッシュは汎用的に使用されるため、実装で null
値の保存を許可することをお勧めします (たとえば、null
を返すメソッドをキャッシュするため)。
- 導入:
- 3.1
- 作成者:
- Costin Leau, Juergen Hoeller, Stephane Nicoll
- 関連事項:
ネストされたクラスのサマリー
修飾子と型インターフェース説明static class
値ローダーコールバックが例外で失敗した場合に、get(Object, Callable)
からスローされるラッパー例外。static interface
キャッシュ値を表す(ラッパー)オブジェクト。メソッドのサマリー
修飾子と型メソッド説明void
clear()
すべてのマッピングを削除してキャッシュをクリアします。void
このキーが存在する場合、このキャッシュからこのキーのマッピングを削除します。default boolean
evictIfPresent
(ObjectSE key) このキーが存在する場合は、このキーのマッピングを削除し、以降の検索ではキーがすぐに見えないことを期待します。このキャッシュが指定されたキーをマップする値を返します。<T> T
このキャッシュが指定されたキーをマップする値を返します。一般的に、戻り値がキャストされる型を指定します。<T> T
get
(ObjectSE key, CallableSE<T> valueLoader) このキャッシュが指定されたキーをマップする値を返し、必要に応じてvalueLoader
からその値を取得します。getName()
キャッシュ名を返します。基になるネイティブキャッシュプロバイダーを返します。default boolean
すべてのマッピングを削除してキャッシュを無効にし、以降のルックアップではすべてのエントリがすぐに表示されないようにします。void
指定された値をこのキャッシュ内の指定されたキーに関連付けます。default Cache.ValueWrapper
putIfAbsent
(ObjectSE key, ObjectSE value) 指定された値が設定されていない場合、指定された値をこのキャッシュ内の指定されたキーと原子的に関連付けます。default CompletableFutureSE<?>
このキャッシュが指定されたキーをマップする値をCompletableFuture
SE でラップして返します。default <T> CompletableFutureSE<T>
retrieve
(ObjectSE key, SupplierSE<CompletableFutureSE<T>> valueLoader) このキャッシュが指定されたキーをマップする値を返し、必要に応じてvalueLoader
からその値を取得します。
メソッドの詳細
getName
StringSE getName()キャッシュ名を返します。getNativeCache
ObjectSE getNativeCache()基になるネイティブキャッシュプロバイダーを返します。get
このキャッシュが指定されたキーをマップする値を返します。キャッシュにこのキーのマッピングが含まれていない場合は、
null
を返します。そうでない場合、キャッシュされた値(null
自体である可能性があります)がCache.ValueWrapper
で返されます。- パラメーター:
key
- 関連する値が返されるキー- 戻り値:
- このキャッシュが指定されたキーをマップする値。
Cache.ValueWrapper
内に含まれ、キャッシュされたnull
値も保持する場合があります。返されるストレートnull
は、キャッシュにこのキーのマッピングが含まれていないことを意味します。 - 関連事項:
get
このキャッシュが指定されたキーをマップする値を返します。一般的に、戻り値がキャストされる型を指定します。メモ: この
get
のバリアントでは、キャッシュされたnull
値とキャッシュエントリがまったく見つからないことを区別できません。代わりに、その目的のために標準のget(Object)
バリアントを使用してください。- パラメーター:
key
- 関連する値が返されるキーtype
- 戻り値の必要な型 (型チェックをバイパスするnull
の場合があります。キャッシュでnull
値が見つかった場合、指定された型は無関係です)- 戻り値:
- このキャッシュが指定されたキー(
null
自体である場合があります)をマップする値、またはキャッシュにこのキーのマッピングが含まれていない場合はnull
- 例外:
IllegalStateExceptionSE
- キャッシュエントリが見つかったが、指定された型と一致しなかった場合- 導入:
- 4.0
- 関連事項:
get
このキャッシュが指定されたキーをマップする値を返し、必要に応じてvalueLoader
からその値を取得します。このメソッドは、従来の「キャッシュされている場合は返す、そうでない場合は作成、キャッシュして返す」パターンの単純な代替を提供します。可能な場合、実装は、同じキーへの同時アクセスの場合に指定された
valueLoader
が 1 回だけ呼び出されるように、ロード操作が同期されることを確認する必要があります。valueLoader
が例外をスローした場合、Cache.ValueRetrievalException
にラップされます- パラメーター:
key
- 関連する値が返されるキー- 戻り値:
- このキャッシュが指定されたキーをマップする値
- 例外:
Cache.ValueRetrievalException
-valueLoader
が例外をスローした場合- 導入:
- 4.3
- 関連事項:
retrieve
このキャッシュが指定されたキーをマップする値をCompletableFuture
SE でラップして返します。この操作はブロックしてはなりませんが、対応する値がすぐに使用できる場合は、完了したCompletableFuture
SE を返すことができます。このキーのマッピングが含まれていないことをキャッシュが即座に判断できる場合 (メモリ内のキーマップなどを通じて)、
null
を返すことができます。それ以外の場合、キャッシュされた値はCompletableFuture
SE で返され、null
は後で決定されたキャッシュミスを示します。ネストされたCache.ValueWrapper
は、NULL 許容のキャッシュ値を示す可能性があります。null 値がサポートされていない場合、キャッシュされた値はプレーン要素として表現されることもあります。呼び出しコードは、このメソッドによって返される結果のバリアントをすべて処理できるように準備する必要があります。- パラメーター:
key
- 関連する値が返されるキー- 戻り値:
- このキャッシュが指定されたキーをマップする値。
CompletableFuture
SE 内に含まれます。キャッシュミスが後で決定された場合は空になる可能性もあります。ストレートなnull
が返された場合は、キャッシュがこのキーのマッピングが含まれていないと即座に判断されたことを意味します。CompletableFuture
内に含まれるCache.ValueWrapper
は、潜在的にnull
であるキャッシュされた値を示します。これは、通常の CompletableFuture に含まれるnull
がキャッシュミスを示す、後で決定されるシナリオでは賢明です。ただし、キャッシュがnull
値の実際のキャッシュをサポートしていない場合は、余分なレベルの値の折り返しを回避してプレーン値を返すこともあります。Spring のキャッシュ処理は、こうしたすべての実装戦略に対応できます。 - 導入:
- 6.1
- 関連事項:
retrieve
default <T> CompletableFutureSE<T> retrieve(ObjectSE key, SupplierSE<CompletableFutureSE<T>> valueLoader) このキャッシュが指定されたキーをマップする値を返し、必要に応じてvalueLoader
からその値を取得します。このメソッドは、CompletableFuture
SE に基づいた、従来の「キャッシュされている場合は返す、そうでない場合は作成、キャッシュして返す」パターンの単純な代替手段を提供します。この操作はブロックしないでください。可能な場合、実装は、同じキーへの同時アクセスの場合に指定された
valueLoader
が 1 回だけ呼び出されるように、ロード操作が同期されることを確認する必要があります。このメソッドでは、NULL 値は常にユーザーレベルの
null
値を示します。提供されたCompletableFuture
SE ハンドルは値を生成するか、例外を生成します。valueLoader
が例外を発生させた場合、その例外は返されたCompletableFuture
ハンドルに伝播されます。- パラメーター:
key
- 関連する値が返されるキー- 戻り値:
- このキャッシュが指定されたキーをマップする値。
CompletableFuture
SE 内に含まれますが、null
になることはありません。提供された Future は、値を生成するか、例外を発生させることが期待されます。 - 導入:
- 6.1
- 関連事項:
put
指定された値をこのキャッシュ内の指定されたキーに関連付けます。キャッシュに以前にこのキーのマッピングが含まれていた場合、古い値は指定された値に置き換えられます。
実際の登録は非同期方式または遅延方式で実行できますが、その後の検索ではエントリがまだ表示されていない可能性があります。これは、たとえばトランザクションキャッシュデコレータの場合です。
putIfAbsent(java.lang.Object, java.lang.Object)
を使用して、即時登録を保証します。キャッシュが
CompletableFuture
SE およびリアクティブインタラクションと互換性があると想定されている場合、put 操作は事実上ノンブロッキングであり、バックエンドのライトスルーは非同期で発生する必要があります。これは、retrieve(Object)
およびretrieve(Object, Supplier)
をサポートするように実装および構成されたキャッシュとともに行われます。- パラメーター:
key
- 指定された値が関連付けられるキーvalue
- 指定されたキーに関連付けられる値- 関連事項:
putIfAbsent
指定された値が設定されていない場合、指定された値をこのキャッシュ内の指定されたキーと原子的に関連付けます。これは次と同等です:
ただし、アクションはアトミックに実行されます。すべての初期状態のValueWrapper existingValue = cache.get(key); if (existingValue == null) { cache.put(key, value); } return existingValue;
CacheManager
実装は、put をアトミックに実行することができるが、オペレーションは、たとえば、非アトミックな方法で、存在のチェックと後続の put との 2 つのステップで実装することもできます。詳細については、使用しているネイティブキャッシュ実装のドキュメントを参照してください。デフォルトの実装は、上記のコードスニペットの行に沿って
get(Object)
およびput(Object, Object)
に委譲します。- パラメーター:
key
- 指定された値が関連付けられるキーvalue
- 指定されたキーに関連付けられる値- 戻り値:
- このキャッシュが指定されたキー(
null
自体の場合もある)をマップする値、またはこの呼び出しの前にキャッシュにそのキーのマッピングが含まれていなかった場合はnull
したがって、null
を返すことは、指定されたvalue
がキーに関連付けられていることを示すインジケーターです。 - 導入:
- 4.1
- 関連事項:
evict
このキーが存在する場合、このキャッシュからこのキーのマッピングを削除します。実際のエビクションは非同期方式または遅延方式で実行できますが、その後のルックアップではおそらくエントリが引き続き表示されます。これは、たとえばトランザクションキャッシュデコレータの場合です。
evictIfPresent(java.lang.Object)
を使用して、即時の削除を保証します。キャッシュが
CompletableFuture
SE およびリアクティブインタラクションと互換性があると想定されている場合、エビクト操作は事実上ノンブロッキングであり、バックエンドのライトスルーは非同期で発生する必要があります。これは、retrieve(Object)
およびretrieve(Object, Supplier)
をサポートするように実装および構成されたキャッシュとともに行われます。- パラメーター:
key
- マッピングがキャッシュから削除されるキー- 関連事項:
evictIfPresent
このキーが存在する場合は、このキーのマッピングを削除し、以降の検索ではキーがすぐに見えないことを期待します。デフォルトの実装は
evict(Object)
に委譲し、未決定のキーの存在についてfalse
を返します。キャッシュプロバイダー、特にキャッシュデコレーターは、可能な場合は直ちにエビクションを実行し(たとえば、トランザクション内で一般的にキャッシュ操作を遅延させる場合)、指定されたキーの事前の存在を確実に判断することをお勧めします。- パラメーター:
key
- マッピングがキャッシュから削除されるキー- 戻り値:
- キャッシュに以前にこのキーのマッピングがあることがわかっていた場合は
true
、ない場合はfalse
(または事前の存在を判断できなかった場合) - 導入:
- 5.2
- 関連事項:
clear
void clear()すべてのマッピングを削除してキャッシュをクリアします。実際の消去は、非同期または遅延方式で実行され、その後のルックアップでエントリが引き続き表示される可能性があります。これは、たとえばトランザクションキャッシュデコレータの場合です。
invalidate()
を使用して、エントリの即時削除を保証します。キャッシュが
CompletableFuture
SE およびリアクティブインタラクションと互換性があると想定されている場合、クリア操作は事実上ノンブロッキングであり、バックエンドのライトスルーは非同期で発生する必要があります。これは、retrieve(Object)
およびretrieve(Object, Supplier)
をサポートするように実装および構成されたキャッシュとともに行われます。- 関連事項:
invalidate
default boolean invalidate()すべてのマッピングを削除してキャッシュを無効にし、以降のルックアップではすべてのエントリがすぐに表示されないようにします。- 戻り値:
- キャッシュにマッピングがあることがわかっている場合は
true
、マッピングがない場合はfalse
(または、エントリの事前の存在を判別できなかった場合) - 導入:
- 5.2
- 関連事項: