From cf858b602d298073081d53288272a5d3b846d786 Mon Sep 17 00:00:00 2001 From: Nikita Koksharov Date: Fri, 27 Sep 2024 14:39:27 +0300 Subject: [PATCH] Update README.md --- redisson-hibernate/README.md | 331 +---------------------------------- 1 file changed, 1 insertion(+), 330 deletions(-) diff --git a/redisson-hibernate/README.md b/redisson-hibernate/README.md index fbe40672f..2687d1f3c 100644 --- a/redisson-hibernate/README.md +++ b/redisson-hibernate/README.md @@ -1,330 +1 @@ -# Redis based Hibernate Cache implementation - -Implements [Hibernate 2nd level Cache](https://docs.jboss.org/hibernate/orm/6.0/userguide/html_single/Hibernate_User_Guide.html#caching) provider based on Redis. -Supports all Hibernate cache strategies: `READ_ONLY`, `NONSTRICT_READ_WRITE`, `READ_WRITE` and `TRANSACTIONAL`. - -Compatible with Hibernate 4.x, 5.1.x, 5.2.x, 5.3.3+ up to 5.6.x and 6.0.2+ up to 6.x.x - -Redisson provides various Hibernate Cache factories including those with features below: - -**local cache** - so called `near cache`, which is useful for use cases when Hibernate Cache used mostly for read operations and/or network roundtrips are undesirable. It caches Map entries on Redisson side and executes read operations up to **5x faster** in comparison with common implementation. Local cache instances with the same name connected to the same pub/sub channel. This channel is used for exchanging of update/invalidate events between all instances. Cache store doesn't use `hashCode()`/`equals()` methods of key object, instead it uses hash of serialized state. - -**data partitioning** - although all implementations are cluster compatible thier content isn't scaled/partitioned across multiple Redis master nodes in cluster. Data partitioning allows to scale available memory, read/write operations and entry eviction process for individual Hibernate Cache instance in Redis cluster. - -#### 1. Scripted eviction - -Allows to define `time to live` or `max idle time` parameters per map entry. Redis hash structure doesn't support eviction thus it's done on Redisson side through a custom scheduled task which removes expired entries using Lua script. Eviction task is started once per unique object name at the moment of getting Map instance. If instance isn't used and has expired entries it should be get again to start the eviction process. This leads to extra Redis calls and eviction task per unique map object name. - -Entries are cleaned time to time by `org.redisson.eviction.EvictionScheduler`. By default, it removes 100 expired entries at a time. This can be changed through [cleanUpKeysAmount](https://github.com/redisson/redisson/wiki/2.-Configuration#cleanupkeysamount) setting. Task launch time tuned automatically and depends on expired entries amount deleted in previous time and varies between 5 second to 30 minutes by default. This time interval can be changed through [minCleanUpDelay](https://github.com/redisson/redisson/wiki/2.-Configuration#mincleanupdelay) and [maxCleanUpDelay](https://github.com/redisson/redisson/wiki/2.-Configuration#maxcleanupdelay). For example, if clean task deletes 100 entries each time it will be executed every 5 seconds (minimum execution delay). But if current expired entries amount is lower than previous one then execution delay will be increased by 1.5 times and decreased otherwise. - -Available implementations: - -|Class name | Local cache | Data
partitioning | Ultra-fast
read/write | -| ------------- | :-----------: | :----------:| :----------:| -|RedissonRegionFactory
open-source version | ❌ | ❌ | ❌ | -|RedissonRegionFactory
[Redisson PRO](http://redisson.pro) version | ❌ | ❌ | ✔️ | -|RedissonLocalCachedRegionFactory
available only in [Redisson PRO](http://redisson.pro) | ✔️ | ❌ | ✔️ | -|RedissonClusteredRegionFactory
available only in [Redisson PRO](http://redisson.pro) | ❌ | ✔️ | ✔️ | -|RedissonClusteredLocalCachedRegionFactory
available only in [Redisson PRO](http://redisson.pro) | ✔️ | ✔️ | ✔️ | - -#### 2. Advanced eviction - -Allows to define `time to live` parameter per map entry. Doesn't use an entry eviction task, entries are cleaned on Redis side. - -Available implementations: - -|Class name | Local cache | Data
partitioning | Ultra-fast
read/write | -| ------------- | :-----------: | :----------:| :----------:| -|RedissonRegionV2Factory
available only in [Redisson PRO](http://redisson.pro) | ❌ | ✔️ | ✔️ | -|RedissonLocalCachedV2RegionFactory
available only in [Redisson PRO](http://redisson.pro) | ✔️ | ✔️ | ✔️ | - -#### 3. Native eviction - -Allows to define `time to live` parameter per map entry. Doesn't use an entry eviction task, entries are cleaned on Redis side. -Requires **Redis 7.4+**. - -Available implementations: - -|Class name | Local cache | Data
partitioning | Ultra-fast
read/write | -| ------------- | :-----------: | :----------:| :----------:| -|RedissonRegionNativeFactory
open-source version | ❌ | ❌ | ❌ | -|RedissonRegionNativeFactory
[Redisson PRO](http://redisson.pro) version | ❌ | ❌ | ✔️ | -|RedissonLocalCachedNativeRegionFactory
available only in [Redisson PRO](http://redisson.pro) | ✔️ | ❌ | ✔️ | -|RedissonClusteredNativeRegionFactory
available only in [Redisson PRO](http://redisson.pro) | ❌ | ✔️ | ✔️ | - -## Hibernate Cache Usage - -### 1. Add `redisson-hibernate` dependency into your project: - -Maven - -```xml - - org.redisson - - redisson-hibernate-4 - - redisson-hibernate-5 - - redisson-hibernate-52 - - redisson-hibernate-53 - - redisson-hibernate-6 - 3.36.0 - -``` - -Gradle - -```groovy - // for Hibernate v4.x - compile 'org.redisson:redisson-hibernate-4:3.36.0' - // for Hibernate v5.0.x - v5.1.x - compile 'org.redisson:redisson-hibernate-5:3.36.0' - // for Hibernate v5.2.x - compile 'org.redisson:redisson-hibernate-52:3.36.0' - // for Hibernate v5.3.3+ - v5.6.x - compile 'org.redisson:redisson-hibernate-53:3.36.0' - // for Hibernate v6.0.2+ - v6.x.x - compile 'org.redisson:redisson-hibernate-6:3.36.0' -``` - -### 2. Specify hibernate cache settings - -Define Redisson Region Cache Factory: - -```xml - - - - - - - - - - - - -``` - -By default each Region Factory creates own Redisson instance. For multiple applications, using the same Redis setup and deployed in the same JVM, amount of Redisson instances could be reduced using JNDI registry: - -```xml - - - - - - - - - - - - - - - -``` - -```xml - - - - - - - - - -``` - -#### Redisson allows to define follow cache settings per entity, collection, naturalid, query and timestamp regions: - -`REGION_NAME` - is a name of region which is defined in @Cache annotation otherwise it's a fully qualified class name. - -| | | -|-|-| -|Parameter| **`hibernate.cache.redisson.[REGION_NAME].eviction.max_entries`** | -|Description| Max size of cache. Superfluous entries in Redis are evicted using LRU algorithm.
`0` value means unbounded cache. | -|Default value| `0` | - -| | | -|-|-| -|Parameter| **`hibernate.cache.redisson.[REGION_NAME].expiration.time_to_live`** | -|Description| Time to live per cache entry in Redis. Defined in milliseconds.
`0` value means this setting doesn't affect expiration. | -|Default value| `0` | - -| | | -|-|-| -|Parameter| **`hibernate.cache.redisson.[REGION_NAME].expiration.max_idle_time`** | -|Description| Max idle time per cache entry in Redis. Defined in milliseconds.
`0` value means this setting doesn't affect expiration. | -|Default value| `0` | - -| | | -|-|-| -|Parameter| **`hibernate.cache.redisson.[REGION_NAME].localcache.cache_provider`** | -|Description| Cache provider used as local cache store.
`REDISSON` and `CAFFEINE` providers are available. | -|Default value| `REDISSON` | - -| | | -|-|-| -|Parameter| **`hibernate.cache.redisson.[REGION_NAME].localcache.store_mode`** | -|Description| Store mode of cache data.
`LOCALCACHE` - store data in local cache only and use Redis only for data update/invalidation
`LOCALCACHE_REDIS` - store data in both Redis and local cache | -|Default value| `LOCALCACHE` | - -| | | -|-|-| -|Parameter| **`hibernate.cache.redisson.[REGION_NAME].localcache.max_idle_time`** | -|Description| Max idle time per entry in local cache. Defined in milliseconds.
`0` value means this setting doesn't affect expiration | -|Default value| `0` | - -| | | -|-|-| -|Parameter| **`hibernate.cache.redisson.[REGION_NAME].localcache.time_to_live`** | -|Description| Time to live per entry in local cache. Defined in milliseconds.
`0` value means this setting doesn't affect expiration | -|Default value| `0` | - -| | | -|-|-| -|Parameter| **`hibernate.cache.redisson.[REGION_NAME].localcache.eviction_policy`** | -|Description| Eviction policy applied to local cache entries when cache size limit reached.
`LFU`, `LRU`, `SOFT`, `WEAK` and `NONE` policies are available. | -|Default value| `NONE` | - -| | | -|-|-| -|Parameter| **`hibernate.cache.redisson.[REGION_NAME].localcache.sync_strategy`** | -|Description| Sync strategy used to synchronize local cache changes across all instances.
`INVALIDATE` - Invalidate cache entry across all LocalCachedMap instances on map entry change
`UPDATE` - Update cache entry across all LocalCachedMap instances on map entry change
`NONE` - No synchronizations on map changes | -|Default value| `INVALIDATE` | - -| | | -|-|-| -|Parameter| **`hibernate.cache.redisson.[REGION_NAME].localcache.reconnection_strategy`** | -|Description| Reconnection strategy used to load missed local cache updates through Hibernate during any connection failures to Redis.
`CLEAR` - Clear local cache if map instance has been disconnected for a while
`LOAD` - Store invalidated entry hash in invalidation log for 10 minutes. Cache keys for stored invalidated entry hashes will be removed if LocalCachedMap instance has been disconnected less than 10 minutes or whole cache will be cleaned otherwise
`NONE` - No reconnection handling | -|Default value| `NONE` | - -| | | -|-|-| -|Parameter| **`hibernate.cache.redisson.[REGION_NAME].localcache.size`** | -|Description| Max size of local cache. Superfluous entries in Redis are evicted using defined eviction policy.
`0` value means unbounded cache. | -|Default value| `0` | - -_**NOTE**: `hibernate.cache.redisson.[REGION_NAME].localcache.*` settings are available for `RedissonClusteredLocalCachedRegionFactory` and `RedissonLocalCachedRegionFactory` classes only._ - -#### Default region configuration used for all caches not specified in configuration: - -```xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -``` - -#### Configuration per entity/collection/naturalid/query region overrides default configuration: - -```xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -``` +## The documentation has been moved to [https://redisson.org/docs/cache-api-implementations/#hibernate-cache](https://redisson.org/docs/cache-api-implementations/#hibernate-cache)