Use the following information and configuration examples as a quick reference for creating and configuring Infinispan caches.
1. Clustered cache modes
- Distributed
-
Distributed caches offer linear scalability and efficient memory usage by creating fewer copies of each entry across the cluster. Distributed caches store a number of copies for each cache entry, which is equal to the Number of owners that you configure.
<distributed-cache />
- Replicated
-
Replicated caches offer fault tolerance and guarantees against data loss by creating a copy of all entries on each node in the cluster.
<replicated-cache />
2. Cluster replication
- Synchronous replication
-
Helps to keep your data consistent but adds latency to cluster traffic, which reduces throughput for cache writes.
<distributed-cache mode="SYNC" />
- Asynchronous replication
-
Reduces latency and increases the speed of write operations but because Infinispan replicates entries from primary owners, asynchronous replication provides a lower guarantee against data loss. Cluster topology changes and network errors might also lead to data inconsistency with asynchronous replication.
<distributed-cache mode="ASYNC" />
3. Cache configuration options
3.1. Encoding
A format, identified by a media type, that Infinispan uses to store keys and values in caches.
Infinispan recommends the application/x-protostream media type. Protobuf provides excellent performance as well as interoperability between client applications in different programming languages for both Hot Rod and REST endpoints. Your cache encoding must be compatible with the Hot Rod client marshaller.
|
<distributed-cache mode="SYNC">
<encoding>
<key media-type="application/x-protostream"/>
<value media-type="application/x-protostream"/>
</encoding>
</distributed-cache>
3.2. Expiration
Controls how long Infinispan keeps entries in a cache and takes effect across clusters.
- Lifespan
-
The maximum amount of time, in milliseconds, that cache entries can exist. If you set the value to -1, entries never expire. Lifespan uses a
creation
timestamp and the value for thelifespan
property to determine when entries expire. The creation time for cache entries provides a value that is consistent across clustered caches. - Max-idle
-
The maximum amount of time, in milliseconds, that cache entries can remain idle. If no operations are performed on entries within the maximum idle time, the entries expire across the cluster. If you set the value to -1, entries never expire.
Maximum idle uses a last used
timestamp and the value for the max-idle
property to determine when entries expire.
The last access time for entries is not always the same on all nodes.
To ensure that entries have the same relative access times across clusters, Infinispan sends touch commands to all owners when keys are accessed.
This synchronous behavior increases the latency of client requests.
The Infinispan team recommends that you set the lifespan property to a value that is at least double the value of the max-idle property. Configuring max-idle close to lifespan has performance drawbacks.
|
<distributed-cache>
<expiration lifespan="5000"
max-idle="1000" />
</distributed-cache>
4. Infinispan capabilities
4.1. Bounded caches
4.1.1. Eviction
Eviction controls the amount of data that Infinispan keeps in memory and takes effect on each node. Control the size of the data container in one of the following ways:
- Max size
-
Maximum size in bytes of the data container. Eviction occurs when the approximate memory usage of the data container exceeds the maximum size.
<distributed-cache> <memory max-size="12MB" when-full="REMOVE"/> </distributed-cache>
- Max count
-
Maximum number of entries. Eviction occurs after the container size exceeds the maximum count.
<distributed-cache> <memory max-count="124" when-full="REMOVE"/> </distributed-cache>
Eviction strategies
- REMOVE
-
Infinispan performs eviction. This is the default strategy when you define a size for the data container. Because not all nodes evict the same entries you should use eviction with persistent storage to avoid data inconsistency.
- EXCEPTION
-
Infinispan throws an exception instead of evicting entries.
If no strategy is defined, but max-count
or max-size
is configured, REMOVE
is used.
4.2. Indexed caches
Create indexes of values in your caches for faster queries and full-text search capabilities.
4.2.1. Index storage
- Persistent
-
On the host file system, which is the default and persists indexes between restarts.
<distributed-cache> <indexing storage="filesystem"> <!-- Indexing configuration goes here. --> </indexing> </distributed-cache>
- Volatile
-
In JVM heap memory, which means that indexes do not survive restarts. Store indexes in JVM heap memory for small data sets only.
<distributed-cache> <indexing storage="local-heap"> <!-- Indexing configuration goes here. --> </indexing> </distributed-cache>
4.2.2. Index reader
The index reader provides access to the indexes to perform queries. As the index content changes, Infinispan needs to refresh the reader so that search results are up to date.
<distributed-cache>
<indexing storage="filesystem" path="${java.io.tmpdir}/baseDir">
<!-- Sets an interval of one second for the index reader. -->
<index-reader refresh-interval="1s"/>
<!-- Additional indexing configuration goes here. -->
</indexing>
</distributed-cache>
4.2.3. Index writer
The index writer constructs an index composed of one or more segments (sub-indexes) that can be merged over time to improve performance.
<distributed-cache>
<indexing storage="filesystem" path="${java.io.tmpdir}/baseDir">
<index-writer commit-interval="2s"
low-level-trace="false"
max-buffered-entries="32"
queue-count="1"
queue-size="10000"
ram-buffer-size="400">
<index-merge calibrate-by-deletes="true"
factor="3"
max-entries="2000"
min-size="10"
max-size="20"/>
</index-writer>
<!-- Additional indexing configuration goes here. -->
</indexing>
</distributed-cache>
4.4. Backups
Define backup locations for cache data and modify state transfer properties.
- Backup strategies
-
Specifies the type of strategy that Infinispan uses to back up data to a different cluster. Infinispan can use either a synchronous or asynchronous strategy. Infinispan performs conflict resolution with the asynchronous backup strategy.
- Remote site
-
Specifies the name of the remote site that backs up data to the local cache.
- Remote cache
-
Specifies the name of the remote cache that uses the local cache as a backup.
- Timeout
-
Specifies the timeout, in milliseconds, for synchronous and asynchronous backup operations.
Cluster LON | Cluster NYC |
---|---|
|
|
4.5. Transactions
4.5.1. Transaction mode
Configure the mode that Infinispan uses when carrying out transactions to ensure that the cache state is consistent.
Enabling transaction mode for the cache to ensure consistency for conditional operations, such as putIfAbsent or remove , that require consistent cache data across the cluster.
|
- NON_XA
-
Cache will enlist within transactions as a
javax.transaction.Synchronization
. - NON_DURABLE_XA
-
Cache will enlist within transactions as a
javax.transaction.xa.XAResource
, without recovery. - FULL_XA
-
Cache will enlist within transactions as a
javax.transaction.xa.XAResource
, with recovery.
4.5.2. Locking mode
Configure how Infinispan locks keys to perform write operations for transactions. Locking keys adds contention that increases latency for write operations. You can adjust the amount of contention by using optimistic or pessimistic locking.
- Optimistic
-
Infinispan locks keys when it invokes the
commit()
method. Keys are locked for shorter periods of time which reduces overall latency but makes transaction recovery less efficient. - Pessimistic
-
Infinispan locks keys when it invokes the
put()
method. Keys are locked for longer periods of time, which increases latency but makes transaction recovery more efficient.<distributed-cache name="deee" mode="SYNC"> <transaction <!-- Transaction mode --> mode="NON_XA" <!-- Locking mode --> locking="OPTIMISTIC"/> </distributed-cache>
4.6. Persistence
Configure non-volatile storage so entries remain available after the cluster restarts.
- Passivation
-
Infinispan writes entries to persistent storage when it evicts those entries from memory. Passivation ensures that only a single copy of an entry is maintained, either in-memory or in a cache store, and prevents unnecessary and expensive writes to persistent storage.
<distributed-cache>
<persistence passivation="true">
<!-- Persistence configuration goes here. -->
</persistence>
</distributed-cache>
- File store
-
File-based cache store on the local host filesystem. For clustered caches, file-based cache stores are unique to each Infinispan node.
<distributed-cache> <persistence passivation="false"> <file-store> <data path="path/to/data"/> <index path="path/to/index"/> </file-store> </persistence> </distributed-cache>
- Remote store
-
Remote cache stores use the Hot Rod protocol to store data on Infinispan clusters.
- Table SQL store
-
Load entries from a single database table. Ensure that the appropriate JDBC driver is available to the Infinispan cluster.
- Query SQL store
-
Use SQL queries to load entries from one or more database tables, including sub-columns. You can also perform insert, update, and delete operations. You must ensure that the appropriate JDBC driver is available to the Infinispan cluster.
- JDBC string-based store
-
Use a relational database for persistent storage through a JDBC connection. Ensure that the appropriate JDBC driver is available to the Infinispan cluster.
- RocksDB store
-
A RocksDB cache store uses two databases; one as a primary store and another to hold expired entries.
- Custom store
-
Use a custom cache store that you implement with the Infinispan Persistence SPI.
5. Configuration formats
You can create Infinispan configuration in XML, JSON, or YAML format.
<distributed-cache owners="2"
mode="SYNC"
statistics="true">
<encoding media-type="application/x-protostream"/>
<locking isolation="REPEATABLE_READ"/>
<transaction mode="FULL_XA"
locking="OPTIMISTIC"/>
<expiration lifespan="5s"
max-idle="1s" />
<memory max-count="1000000"
when-full="REMOVE"/>
<indexing enabled="true"
storage="local-heap">
<index-reader refresh-interval="1s"/>
<indexed-entities>
<indexed-entity>org.infinispan.Person</indexed-entity>
</indexed-entities>
</indexing>
<persistence passivation="false">
<!-- Persistent storage configuration. -->
</persistence>
</distributed-cache>
{
"distributed-cache": {
"owners": 2,
"mode": "SYNC",
"statistics": true,
"encoding": {
"media-type": "application/x-protostream"
},
"locking": {
"isolation": "REPEATABLE_READ"
},
"transaction": {
"mode": "FULL_XA",
"locking": "OPTIMISTIC"
},
"expiration": {
"lifespan": 5000,
"max-idle": 1000
},
"memory": {
"max-count": 1000000,
"when-full": "REMOVE"
},
"indexing": {
"enabled": true,
"storage": "local-heap",
"indexed-entities": [
"org.infinispan.Person"
],
"index-reader": {
"refresh-interval": 1000
}
},
"persistence": {
"passivation": false
}
}
}
distributed-cache:
owners: 2
mode: SYNC
statistics: true
encoding:
media-type: application/x-protostream
locking:
isolation: REPEATABLE_READ
transaction:
mode: FULL_XA
locking: OPTIMISTIC
expiration:
lifespan: 5000
max-idle: 1000
memory:
max-count: 1000000
when-full: REMOVE
indexing:
enabled: true
storage: local-heap
index-reader:
refresh-interval: 1000
indexedEntities:
- "org.infinispan.Person"
persistence:
passivation: false