From 98b8326d9a4526949e08fe023316f58bd3761362 Mon Sep 17 00:00:00 2001 From: Nikita Koksharov Date: Tue, 21 Jan 2025 15:40:04 +0300 Subject: [PATCH] docs updated --- docs/cache-api-implementations.md | 108 +++++++++++++++++++++++++++++- docs/configuration.md | 52 +++++++++++--- docs/getting-started.md | 18 +++-- 3 files changed, 163 insertions(+), 15 deletions(-) diff --git a/docs/cache-api-implementations.md b/docs/cache-api-implementations.md index 2b64b8580..274ded897 100644 --- a/docs/cache-api-implementations.md +++ b/docs/cache-api-implementations.md @@ -340,7 +340,15 @@ Below are examples of JCache API usage. **1.** Using default config located at `/redisson-jcache.yaml`: ```java +// implementation with scripted eviction MutableConfiguration config = new MutableConfiguration<>(); + +// implementation with native eviction +NativeConfiguration config = new NativeConfiguration<>(); + +// implementation with advanced eviction +V2Configuration config = new V2Configuration<>(); + CacheManager manager = Caching.getCachingProvider().getCacheManager(); Cache cache = manager.createCache("namedCache", config); @@ -348,8 +356,16 @@ Cache cache = manager.createCache("namedCache", config); **2.** Using config file with custom location: ```java +// implementation with scripted eviction MutableConfiguration config = new MutableConfiguration<>(); +// implementation with native eviction +NativeConfiguration config = new NativeConfiguration<>(); + +// implementation with advanced eviction +V2Configuration config = new V2Configuration<>(); + + // yaml config URI redissonConfigUri = getClass().getResource("redisson-jcache.yaml").toURI(); CacheManager manager = Caching.getCachingProvider().getCacheManager(redissonConfigUri, null); @@ -358,8 +374,16 @@ Cache cache = manager.createCache("namedCache", config); **3.** Using Redisson's config object: ```java +// implementation with scripted eviction MutableConfiguration jcacheConfig = new MutableConfiguration<>(); +// implementation with native eviction +NativeConfiguration jcacheConfig = new NativeConfiguration<>(); + +// implementation with advanced eviction +V2Configuration jcacheConfig = new V2Configuration<>(); + + Config redissonCfg = ... Configuration config = RedissonConfiguration.fromConfig(redissonCfg, jcacheConfig); @@ -369,8 +393,16 @@ Cache cache = manager.createCache("namedCache", config); **4.** Using Redisson instance object: ```java +// implementation with scripted eviction MutableConfiguration jcacheConfig = new MutableConfiguration<>(); +// implementation with native eviction +NativeConfiguration jcacheConfig = new NativeConfiguration<>(); + +// implementation with advanced eviction +V2Configuration jcacheConfig = new V2Configuration<>(); + + RedissonClient redisson = ... Configuration config = RedissonConfiguration.fromInstance(redisson, jcacheConfig); @@ -390,7 +422,15 @@ Along with usual JCache API, Redisson provides Asynchronous, Reactive and RxJava Example: ```java +// implementation with scripted eviction MutableConfiguration config = new MutableConfiguration<>(); + +// implementation with native eviction +NativeConfiguration config = new NativeConfiguration<>(); + +// implementation with advanced eviction +V2Configuration config = new V2Configuration<>(); + CacheManager manager = Caching.getCachingProvider().getCacheManager(); Cache cache = manager.createCache("myCache", config); @@ -404,7 +444,15 @@ RFuture getFuture = asyncCache.getAsync("1"); Example: ```java +// implementation with scripted eviction MutableConfiguration config = new MutableConfiguration<>(); + +// implementation with native eviction +NativeConfiguration config = new NativeConfiguration<>(); + +// implementation with advanced eviction +V2Configuration config = new V2Configuration<>(); + CacheManager manager = Caching.getCachingProvider().getCacheManager(); Cache cache = manager.createCache("myCache", config); @@ -418,7 +466,15 @@ Mono getFuture = reactiveCache.get("1"); Example: ```java +// implementation with scripted eviction MutableConfiguration config = new MutableConfiguration<>(); + +// implementation with native eviction +NativeConfiguration config = new NativeConfiguration<>(); + +// implementation with advanced eviction +V2Configuration config = new V2Configuration<>(); + CacheManager manager = Caching.getCachingProvider().getCacheManager(); Cache cache = manager.createCache("myCache", config); @@ -437,7 +493,13 @@ Redisson provides JCache implementations with two important features: **fallback mode** - if set to `true` and Redis or Valkey is down the errors won't be thrown allowing application continue to operate without Redis. -Below is the complete list of available managers: +**1. Scripted eviction** + +Eviction is done on Redisson side through a custom scheduled task which removes expired entries using Lua script. Eviction task is started once per unique cache name at the moment of getting JCache 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 or Valkey calls and eviction task per unique cache 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](configuration.md) 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](configuration.md) and [maxCleanUpDelay](configuration.md). 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: | | Local
cache | Data
partitioning | Ultra-fast
read/write | Fallback
mode | | ------------- | :-----------: | :----------:| :----------:| :----------:| @@ -447,6 +509,28 @@ Below is the complete list of available managers: |JCache with data partitioning
available only in [Redisson PRO](https://redisson.pro) | ❌ | ✔️ | ✔️ | ✔️ | |JCache with local cache and data partitioning
available only in [Redisson PRO](https://redisson.pro) | ✔️ | ✔️ | ✔️ | ✔️ | +**2. Advanced eviction** + +Doesn't use an entry eviction task, entries are cleaned on Redis or Valkey side. + +Available implementations: + +| | Local
cache | Data
partitioning | Ultra-fast
read/write | Fallback
mode | +| ------------- | :-----------: | :----------:| :----------:| :----------:| +|JCache V2
available only in [Redisson PRO](https://redisson.pro) | ❌ | ✔️ | ✔️ | ✔️ | + +**3. Native eviction** + +Doesn't use an entry eviction task, entries are cleaned on Redis side. +Requires **Redis 7.4+**. + +Available implementations: + +| | Local
cache | Data
partitioning | Ultra-fast
read/write | Fallback
mode | +| ------------- | :-----------: | :----------:| :----------:| :----------:| +|JCache native
available only in [Redisson PRO](https://redisson.pro) | ❌ | ❌ | ✔️ | ✔️ | +|JCache native with data partitioning
available only in [Redisson PRO](https://redisson.pro) | ❌ | ✔️ | ✔️ | ✔️ | + **Local cache configuration** ```java @@ -546,8 +630,19 @@ Cache cache = manager.createCache("namedCache", rConfig); Usage examples: ```java - +// data partitioning configuration with scripted eviction ClusteredConfiguration config = new ClusteredConfiguration<>(); + +// data partitioning and local cache configuration with scripted eviction +ClusteredLocalCacheConfiguration config = new ClusteredLocalCacheConfiguration<>(); +config.cacheSize(1000); +config.timeToLive(Duration.ofSeconds(10)); + +// data partitioning configuration with native eviction +ClusteredNativeConfiguration config = new ClusteredNativeConfiguration<>(); + +// data partitioning configuration with advanced eviction +V2Configuration config = new V2Configuration<>(); CacheManager manager = Caching.getCachingProvider().getCacheManager(); Cache cache = manager.createCache("myCache", config); @@ -711,8 +806,15 @@ Follow settings are available per JCache instance: | | | |-|-| |Parameter| **`implementation`** | -|Description| Cache implementation.
`cache` - standard implementation
`clustered-local-cache` - data partitioning and local cache support
`local-cache` - local cache support
`clustered-cache` - data partitioning support
| +|Description| Cache implementation. | |Default value| `cache` | +|
`cache` - implementation with scripted eviction +
`cache-v2` - implementation with advanced eviction +
`native-cache` - implementation with native eviction +
`clustered-native-cache` - implementation with data partitioning and native eviction +
`local-cache` - implementation with local cache support and scripted eviction +
`clustered-local-cache` - implementation with data partitioning, local cache support and scripted eviction +
`clustered-cache` - implementation with data partitioning and scripted eviction| | | | |-|-| diff --git a/docs/configuration.md b/docs/configuration.md index de272c296..310ec0a45 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -4,7 +4,10 @@ Programmatic configuration is performed by the `Config` object instance. For exa Config config = new Config(); config.setTransportMode(TransportMode.EPOLL); config.useClusterServers() - // use "rediss://" for SSL connection + // use "redis://" for Redis connection + // use "valkey://" for Valkey connection + // use "valkeys://" for Valkey SSL connection + // use "rediss://" for Redis SSL connection .addNodeAddress("redis://127.0.0.1:7181"); RedissonClient redisson = Redisson.create(config); @@ -150,6 +153,12 @@ Default value: `30000` RLock object watchdog timeout in milliseconds. This parameter is only used if an RLock object is acquired without the `leaseTimeout` parameter. The lock expires after `lockWatchdogTimeout` if the watchdog didn’t extend it to the next `lockWatchdogTimeout` time interval. This prevents infinity-locked locks due to a Redisson client crash, or any other reason why a lock can’t be released properly. +**lockWatchdogBatchSize** + +Default value: `100` + +Amount of locks used by a single lock watchdog execution. This parameter is only used if lock has been acquired without leaseTimeout parameter definition. + **checkLockSyncedSlaves** Default value: `true` @@ -267,7 +276,10 @@ Programmatic config example: Config config = new Config(); config.useClusterServers() .setScanInterval(2000) // cluster state scan interval in milliseconds - // use "rediss://" for SSL connection + // use "redis://" for Redis connection + // use "valkey://" for Valkey connection + // use "valkeys://" for Valkey SSL connection + // use "rediss://" for Redis SSL connection .addNodeAddress("redis://127.0.0.1:7000", "redis://127.0.0.1:7001") .addNodeAddress("redis://127.0.0.1:7002"); @@ -615,7 +627,10 @@ Programmatic config example: Config config = new Config(); config.useReplicatedServers() .setScanInterval(2000) // master node change scan interval - // use "rediss://" for SSL connection + // use "redis://" for Redis connection + // use "valkey://" for Valkey connection + // use "valkeys://" for Valkey SSL connection + // use "rediss://" for Redis SSL connection .addNodeAddress("redis://127.0.0.1:7000", "redis://127.0.0.1:7001") .addNodeAddress("redis://127.0.0.1:7002"); @@ -909,6 +924,12 @@ Programmatic config example: RedissonClient redisson = Redisson.create(); Config config = new Config(); +// use "valkey+uds://" for Valkey Unix Domain Socket (UDS) connection +// use "valkey://" for Valkey connection +// use "valkeys://" for Valkey SSL connection +// use "redis+uds://" for Redis Unix Domain Socket (UDS) connection +// use "redis://" for Redis connection +// use "rediss://" for Redis SSL connection config.useSingleServer().setAddress("redis://myredisserver:6379"); RedissonClient redisson = Redisson.create(config); ``` @@ -1131,7 +1152,10 @@ Programmatic config example: Config config = new Config(); config.useSentinelServers() .setMasterName("mymaster") - // use "rediss://" for SSL connection + // use "redis://" for Redis connection + // use "valkey://" for Valkey connection + // use "valkeys://" for Valkey SSL connection + // use "rediss://" for Redis SSL connection .addSentinelAddress("redis://127.0.0.1:26389", "redis://127.0.0.1:26379") .addSentinelAddress("redis://127.0.0.1:26319"); @@ -1456,7 +1480,10 @@ Programmatic config example: ```java Config config = new Config(); config.useMasterSlaveServers() - // use "rediss://" for SSL connection + // use "redis://" for Redis connection + // use "valkey://" for Valkey connection + // use "valkeys://" for Valkey SSL connection + // use "rediss://" for Redis SSL connection .setMasterAddress("redis://127.0.0.1:6379") .addSlaveAddress("redis://127.0.0.1:6389", "redis://127.0.0.1:6332", "redis://127.0.0.1:6419") .addSlaveAddress("redis://127.0.0.1:6399"); @@ -1762,7 +1789,10 @@ Compatible with: Programmatic config example: ```java Config config = new Config(); -// use "rediss://" for SSL connection +// use "redis://" for Redis connection +// use "valkey://" for Valkey connection +// use "valkeys://" for Valkey SSL connection +// use "rediss://" for Redis SSL connection config.useProxyServers().addAddress("redis://myredisserver1:6379", "redis://myredisserver2:6379"); RedissonClient redisson = Redisson.create(config); @@ -2043,7 +2073,10 @@ Programmatic config example: Config config = new Config(); config.useMultiClusterServers() .setScanInterval(2000) // cluster state scan interval in milliseconds - // use "rediss://" for SSL connection + // use "redis://" for Redis connection + // use "valkey://" for Valkey connection + // use "valkeys://" for Valkey SSL connection + // use "rediss://" for Redis SSL connection .addAddress("redis://cluster1:7000", "redis://cluster2:70002"); RedissonClient redisson = Redisson.create(config); @@ -2383,7 +2416,10 @@ Config config = new Config(); config.useMultiSentinelServers() .setReplicationMode(ReplicationMode.ASYNC) .setMasterName("mymaster") - // use "rediss://" for SSL connection + // use "redis://" for Redis connection + // use "valkey://" for Valkey connection + // use "valkeys://" for Valkey SSL connection + // use "rediss://" for Redis SSL connection .addSentinelAddress("redis://sentinel_primary_cluster:26389", "redis://sentinel_secondary_cluster1:26379", "redis://sentinel_secondary_cluster2:26379") diff --git a/docs/getting-started.md b/docs/getting-started.md index 5d0ced69b..0cd813ed8 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -24,18 +24,28 @@ libraryDependencies += "org.redisson" % "redisson" % "xVERSIONx" **2. Start development** -1. Create config object +1. Create config object. +Use one of supported modes: ([single mode](configuration.md/#single-mode), +[replicated mode](configuration.md/#replicated-mode), +[cluster mode](configuration.md/#cluster-mode), +[sentinel mode](configuration.md/#sentinel-mode), +[proxy mode](configuration.md/#proxy-mode), +[multi cluster mode](configuration.md/#multi-cluster-mode), +[multi sentinel mode](configuration.md/#multi-sentinel-mode)) ```java Config config = new Config(); config.useClusterServers() - // use "rediss://" for SSL connection + // use "redis://" for Redis connection + // use "valkey://" for Valkey connection + // use "valkeys://" for Valkey SSL connection + // use "rediss://" for Redis SSL connection .addNodeAddress("redis://127.0.0.1:7181"); // or read config from file config = Config.fromYAML(new File("config-file.yaml")); ``` -2. Create Redisson instance +2. Create Redisson instance. ```java // Sync and Async API RedissonClient redisson = Redisson.create(config); @@ -47,7 +57,7 @@ libraryDependencies += "org.redisson" % "redisson" % "xVERSIONx" RedissonRxClient redissonRx = redisson.rxJava(); ``` -3. Get Redis or Valkey based object or service +3. Get Redis or Valkey based object or service. ```java // java.util.concurrent.ConcurrentMap