[id='invalidation-caches_{context}']
= Invalidation caches

Invalidation cache mode in {brandname} is designed to optimize systems that perform high volumes of read operations to a shared permanent data store.
You can use invalidation mode to reduce the number of database writes when state changes occur.

[IMPORTANT]
====
Invalidation cache mode is deprecated for {brandname} remote deployments.
Use invalidation cache mode with embedded caches that are stored in shared cache stores only.
====

Invalidation cache mode is effective only when you have a permanent data store, such as a database, and are only using {brandname} as an optimization in a read-heavy system to prevent hitting the database for every read.

When a cache is configured for invalidation, each data change in a cache triggers a message to other caches in the cluster, informing them that their data is now stale and should be removed from memory.
Invalidation messages remove stale values from other nodes' memory.
The messages are very small compared to replicating the entire value, and also other caches in the cluster look up modified data in a lazy manner, only when needed.
The update to the shared store is typically handled by user application code or Hibernate.

ifdef::community[]
image::invalidation_cache_ispn.png[align="center", title="Invalidation cache"]
endif::community[]
ifdef::downstream[]
image::invalidation_cache_rhdg.png[align="center", title="Invalidation cache"]
endif::downstream[]

Sometimes the application reads a value from the external store and wants to write it to the local cache, without removing it from the other nodes.
To do this, it must call `Cache.putForExternalRead(key, value)` instead of `Cache.put(key, value)`.

[IMPORTANT]
====
Invalidation mode is suitable only for shared stores where all nodes can access the same data.
Using invalidation mode without a persistent store is impractical, as updated values need to be read from a shared store for consistency across nodes.

Never use invalidation mode with a local, non-shared, cache store.
The invalidation message will not remove entries in the local store, and some nodes will keep seeing the stale value.
====

An invalidation cache can also be configured with a special cache loader, `ClusterLoader`.
When `ClusterLoader` is enabled, read operations that do not find the key on the local node will request it from all the other nodes first, and store it in memory locally.
This can lead to storing stale values, so only use it if you have a high tolerance for stale values.

.Synchronous or asynchronous replication

When synchronous, a write operation blocks until all nodes in the cluster have evicted the stale value.
When asynchronous, the originator broadcasts invalidation messages but does not wait for responses.
That means other nodes still see the stale value for a while after the write completed on the originator.

.Transactions

Transactions can be used to batch the invalidation messages.
Transactions acquire the key lock on the primary owner.

With pessimistic locking, each write triggers a lock message, which is
broadcast to all the nodes.
During transaction commit, the originator broadcasts a one-phase prepare message (optionally fire-and-forget) which invalidates all affected keys and releases the locks.

With optimistic locking, the originator broadcasts a prepare message, a commit message, and an unlock message (optional).
Either the one-phase prepare or the unlock message is fire-and-forget, and the last message always releases the locks.
