0
# Configuration and Client Setup
1

2
Redisson provides flexible configuration options for connecting to Redis in various deployment scenarios including single server, cluster, sentinel, and replicated server modes. The configuration system supports both programmatic setup and external configuration files.
3

4
## Capabilities
5

6
### Client Factory Methods
7

8
Factory methods for creating Redisson clients with various configurations.
9

10
```java { .api }
11
/**
12
 * Create a Redisson client with default configuration
13
 * Connects to localhost:6379 by default
14
 * @return RedissonClient instance
15
 */
16
public static RedissonClient create();
17

18
/**
19
 * Create a Redisson client with custom configuration
20
 * @param config - configuration object specifying connection details
21
 * @return RedissonClient instance
22
 */
23
public static RedissonClient create(Config config);
24

25
/**
26
 * Get reactive streams client interface from existing client
27
 * @return RedissonReactiveClient for reactive programming
28
 */
29
public RedissonReactiveClient reactive();
30

31
/**
32
 * Get RxJava client interface from existing client  
33
 * @return RedissonRxClient for RxJava programming
34
 */
35
public RedissonRxClient rxJava();
36
```
37

38
**Usage Examples:**
39

40
```java
41
import org.redisson.Redisson;
42
import org.redisson.api.RedissonClient;
43
import org.redisson.config.Config;
44

45
// Default configuration (localhost:6379)
46
RedissonClient redisson = Redisson.create();
47

48
// Custom configuration
49
Config config = new Config();
50
config.useSingleServer()
51
    .setAddress("redis://127.0.0.1:6379")
52
    .setPassword("mypassword")
53
    .setDatabase(0);
54
    
55
RedissonClient customRedisson = Redisson.create(config);
56

57
// Get reactive client
58
RedissonReactiveClient reactiveClient = redisson.reactive();
59

60
// Get RxJava client
61
RedissonRxClient rxClient = redisson.rxJava();
62
```
63

64
### Core Configuration Class
65

66
The main configuration class with server mode setup and global options.
67

68
```java { .api }
69
/**
70
 * Main configuration class for Redisson client
71
 */
72
public class Config {
73
    // Factory methods for different server modes
74
    public SingleServerConfig useSingleServer();
75
    public ClusterServersConfig useClusterServers();
76
    public SentinelServersConfig useSentinelServers(); 
77
    public MasterSlaveServersConfig useMasterSlaveServers();
78
    public ReplicatedServersConfig useReplicatedServers();
79
    
80
    // Global configuration properties
81
    public Config setThreads(int threads);
82
    public Config setNettyThreads(int nettyThreads);
83
    public Config setCodec(Codec codec);
84
    public Config setExecutor(ExecutorService executor);
85
    public Config setNettyExecutor(Executor nettyExecutor);
86
    public Config setEventLoopGroup(EventLoopGroup eventLoopGroup);
87
    public Config setTransportMode(TransportMode transportMode);
88
    
89
    // Lock and synchronization settings
90
    public Config setLockWatchdogTimeout(long lockWatchdogTimeout);
91
    public Config setLockWatchdogBatchSize(int lockWatchdogBatchSize);
92
    public Config setFairLockWaitTimeout(long fairLockWaitTimeout);
93
    public Config setCheckLockSyncedSlaves(boolean checkLockSyncedSlaves);
94
    public Config setSlavesSyncTimeout(long slavesSyncTimeout);
95
    
96
    // Pub/sub and reliability settings
97
    public Config setReliableTopicWatchdogTimeout(long reliableTopicWatchdogTimeout);
98
    public Config setKeepPubSubOrder(boolean keepPubSubOrder);
99
    public Config setUseScriptCache(boolean useScriptCache);
100
    
101
    // Cleanup settings
102
    public Config setMinCleanUpDelay(int minCleanUpDelay);
103
    public Config setMaxCleanUpDelay(int maxCleanUpDelay);
104
    public Config setCleanUpKeysAmount(int cleanUpKeysAmount);
105
    
106
    // Advanced settings
107
    public Config setReferenceEnabled(boolean referenceEnabled);
108
    public Config setNettyHook(NettyHook nettyHook);
109
    public Config setConnectionListener(ConnectionListener connectionListener);
110
    
111
    // Getters
112
    public int getThreads();
113
    public int getNettyThreads();
114
    public Codec getCodec();
115
    public TransportMode getTransportMode();
116
    public long getLockWatchdogTimeout();
117
    // ... other getters
118
}
119
```
120

121
**Configuration Examples:**
122

123
```java
124
Config config = new Config();
125

126
// Basic settings
127
config.setThreads(16) // Number of threads for Redis operations
128
      .setNettyThreads(32) // Number of Netty threads
129
      .setCodec(new JsonJacksonCodec()) // JSON serialization
130
      .setTransportMode(TransportMode.NIO); // NIO transport
131

132
// Lock settings
133
config.setLockWatchdogTimeout(30000) // 30 second lock watchdog
134
      .setCheckLockSyncedSlaves(true) // Verify lock replication
135
      .setSlavesSyncTimeout(1000); // Slave sync timeout
136

137
// Cleanup settings  
138
config.setMinCleanUpDelay(5)
139
      .setMaxCleanUpDelay(1800)
140
      .setCleanUpKeysAmount(100);
141

142
RedissonClient redisson = Redisson.create(config);
143
```
144

145
### Single Server Configuration
146

147
Configuration for connecting to a single Redis server.
148

149
```java { .api }
150
public class SingleServerConfig extends BaseConfig<SingleServerConfig> {
151
    // Connection settings
152
    public SingleServerConfig setAddress(String address);
153
    public SingleServerConfig setUsername(String username);
154
    public SingleServerConfig setPassword(String password);
155
    public SingleServerConfig setDatabase(int database);
156
    public SingleServerConfig setClientName(String clientName);
157
    
158
    // Connection pool settings
159
    public SingleServerConfig setConnectionMinimumIdleSize(int connectionMinimumIdleSize);
160
    public SingleServerConfig setConnectionPoolSize(int connectionPoolSize);
161
    public SingleServerConfig setSubscriptionConnectionMinimumIdleSize(int subscriptionConnectionMinimumIdleSize);
162
    public SingleServerConfig setSubscriptionConnectionPoolSize(int subscriptionConnectionPoolSize);
163
    
164
    // Timeout settings
165
    public SingleServerConfig setConnectTimeout(int connectTimeout);
166
    public SingleServerConfig setIdleConnectionTimeout(int idleConnectionTimeout);
167
    public SingleServerConfig setTimeout(int timeout);
168
    public SingleServerConfig setRetryAttempts(int retryAttempts);
169
    public SingleServerConfig setRetryInterval(int retryInterval);
170
    
171
    // Advanced settings
172
    public SingleServerConfig setKeepAlive(boolean keepAlive);
173
    public SingleServerConfig setTcpNoDelay(boolean tcpNoDelay);
174
    public SingleServerConfig setDnsMonitoringInterval(long dnsMonitoringInterval);
175
    public SingleServerConfig setSslTruststore(URI sslTruststore);
176
    public SingleServerConfig setSslTruststorePassword(String sslTruststorePassword);
177
    public SingleServerConfig setSslKeystore(URI sslKeystore);
178
    public SingleServerConfig setSslKeystorePassword(String sslKeystorePassword);
179
    
180
    // Getters for all properties
181
    public String getAddress();
182
    public String getPassword();
183
    public int getDatabase();
184
    public int getConnectionPoolSize();
185
    // ... other getters
186
}
187
```
188

189
**Single Server Examples:**
190

191
```java
192
Config config = new Config();
193
SingleServerConfig singleConfig = config.useSingleServer();
194

195
// Basic connection
196
singleConfig.setAddress("redis://127.0.0.1:6379")
197
           .setPassword("mypassword")
198
           .setDatabase(0)
199
           .setClientName("myapp");
200

201
// Connection pooling
202
singleConfig.setConnectionPoolSize(64)
203
           .setConnectionMinimumIdleSize(10)
204
           .setSubscriptionConnectionPoolSize(50)
205
           .setSubscriptionConnectionMinimumIdleSize(1);
206

207
// Timeouts and retry
208
singleConfig.setConnectTimeout(10000)
209
           .setIdleConnectionTimeout(10000)
210
           .setTimeout(3000)
211
           .setRetryAttempts(3)
212
           .setRetryInterval(1500);
213

214
// SSL configuration
215
singleConfig.setSslTruststore(URI.create("file:///path/to/truststore.jks"))
216
           .setSslTruststorePassword("password")
217
           .setSslKeystore(URI.create("file:///path/to/keystore.jks"))
218
           .setSslKeystorePassword("password");
219

220
RedissonClient redisson = Redisson.create(config);
221
```
222

223
### Cluster Configuration
224

225
Configuration for connecting to a Redis cluster.
226

227
```java { .api }
228
public class ClusterServersConfig extends BaseConfig<ClusterServersConfig> {
229
    // Node addresses
230
    public ClusterServersConfig addNodeAddress(String... addresses);
231
    public ClusterServersConfig setNodeAddresses(List<String> addresses);
232
    
233
    // Scan settings
234
    public ClusterServersConfig setScanInterval(int scanInterval);
235
    public ClusterServersConfig setCheckSlotsCoverage(boolean checkSlotsCoverage);
236
    
237
    // Connection settings (inherits from BaseConfig)
238
    public ClusterServersConfig setUsername(String username);
239
    public ClusterServersConfig setPassword(String password);
240
    public ClusterServersConfig setClientName(String clientName);
241
    
242
    // Master connection pool settings
243
    public ClusterServersConfig setMasterConnectionMinimumIdleSize(int masterConnectionMinimumIdleSize);
244
    public ClusterServersConfig setMasterConnectionPoolSize(int masterConnectionPoolSize);
245
    
246
    // Slave connection pool settings
247
    public ClusterServersConfig setSlaveConnectionMinimumIdleSize(int slaveConnectionMinimumIdleSize);
248
    public ClusterServersConfig setSlaveConnectionPoolSize(int slaveConnectionPoolSize);
249
    
250
    // Subscription connection settings
251
    public ClusterServersConfig setSubscriptionConnectionMinimumIdleSize(int subscriptionConnectionMinimumIdleSize);
252
    public ClusterServersConfig setSubscriptionConnectionPoolSize(int subscriptionConnectionPoolSize);
253
    
254
    // Read mode settings
255
    public ClusterServersConfig setReadMode(ReadMode readMode);
256
    public ClusterServersConfig setSubscriptionMode(SubscriptionMode subscriptionMode);
257
    
258
    // Failover settings
259
    public ClusterServersConfig setFailedSlaveReconnectionInterval(int failedSlaveReconnectionInterval);
260
    public ClusterServersConfig setFailedSlaveCheckInterval(int failedSlaveCheckInterval);
261
    public ClusterServersConfig setSlavesSyncTimeout(long slavesSyncTimeout);
262
    
263
    // Getters
264
    public List<String> getNodeAddresses();
265
    public int getScanInterval();
266
    public ReadMode getReadMode();
267
    // ... other getters
268
}
269
```
270

271
**Cluster Examples:**
272

273
```java
274
Config config = new Config();
275
ClusterServersConfig clusterConfig = config.useClusterServers();
276

277
// Node addresses
278
clusterConfig.addNodeAddress("redis://127.0.0.1:7004", "redis://127.0.0.1:7001", "redis://127.0.0.1:7000")
279
            .setPassword("cluster_password")
280
            .setClientName("cluster-client");
281

282
// Scan settings
283
clusterConfig.setScanInterval(2000) // Scan for new nodes every 2 seconds
284
            .setCheckSlotsCoverage(true); // Verify all slots are covered
285

286
// Connection pools
287
clusterConfig.setMasterConnectionPoolSize(64)
288
            .setMasterConnectionMinimumIdleSize(10)
289
            .setSlaveConnectionPoolSize(64)
290
            .setSlaveConnectionMinimumIdleSize(10);
291

292
// Read mode - where to read from
293
clusterConfig.setReadMode(ReadMode.SLAVE) // Read from slaves
294
            .setSubscriptionMode(SubscriptionMode.MASTER); // Subscribe to masters
295

296
// Failover settings
297
clusterConfig.setFailedSlaveReconnectionInterval(3000)
298
            .setFailedSlaveCheckInterval(60000)
299
            .setSlavesSyncTimeout(1000);
300

301
RedissonClient redisson = Redisson.create(config);
302
```
303

304
### Sentinel Configuration
305

306
Configuration for connecting through Redis Sentinel for high availability.
307

308
```java { .api }
309
public class SentinelServersConfig extends BaseConfig<SentinelServersConfig> {
310
    // Sentinel settings
311
    public SentinelServersConfig addSentinelAddress(String... addresses);
312
    public SentinelServersConfig setSentinelAddresses(List<String> sentinelAddresses);
313
    public SentinelServersConfig setMasterName(String masterName);
314
    public SentinelServersConfig setSentinelUsername(String sentinelUsername);
315
    public SentinelServersConfig setSentinelPassword(String sentinelPassword);
316
    
317
    // Database settings (inherits from BaseConfig)
318
    public SentinelServersConfig setDatabase(int database);
319
    public SentinelServersConfig setUsername(String username);
320
    public SentinelServersConfig setPassword(String password);
321
    public SentinelServersConfig setClientName(String clientName);
322
    
323
    // Master connection pool
324
    public SentinelServersConfig setMasterConnectionMinimumIdleSize(int masterConnectionMinimumIdleSize);
325
    public SentinelServersConfig setMasterConnectionPoolSize(int masterConnectionPoolSize);
326
    
327
    // Slave connection pool  
328
    public SentinelServersConfig setSlaveConnectionMinimumIdleSize(int slaveConnectionMinimumIdleSize);
329
    public SentinelServersConfig setSlaveConnectionPoolSize(int slaveConnectionPoolSize);
330
    
331
    // Subscription connections
332
    public SentinelServersConfig setSubscriptionConnectionMinimumIdleSize(int subscriptionConnectionMinimumIdleSize);
333
    public SentinelServersConfig setSubscriptionConnectionPoolSize(int subscriptionConnectionPoolSize);
334
    
335
    // Sentinel monitoring
336
    public SentinelServersConfig setSentinelsDiscovery(boolean sentinelsDiscovery);
337
    public SentinelServersConfig setCheckSentinelsList(boolean checkSentinelsList);
338
    
339
    // Read settings
340
    public SentinelServersConfig setReadMode(ReadMode readMode);
341
    public SentinelServersConfig setSubscriptionMode(SubscriptionMode subscriptionMode);
342
    
343
    // Getters
344
    public List<String> getSentinelAddresses();
345
    public String getMasterName();
346
    public String getSentinelPassword();
347
    // ... other getters
348
}
349
```
350

351
**Sentinel Examples:**
352

353
```java
354
Config config = new Config();
355
SentinelServersConfig sentinelConfig = config.useSentinelServers();
356

357
// Sentinel setup
358
sentinelConfig.setMasterName("mymaster")
359
             .addSentinelAddress("redis://127.0.0.1:26379", "redis://127.0.0.1:26380", "redis://127.0.0.1:26381")
360
             .setSentinelPassword("sentinel_password")
361
             .setPassword("redis_password")
362
             .setDatabase(0);
363

364
// Discovery settings
365
sentinelConfig.setSentinelsDiscovery(true)
366
             .setCheckSentinelsList(true);
367

368
// Connection pools
369
sentinelConfig.setMasterConnectionPoolSize(64)
370
             .setSlaveConnectionPoolSize(64)
371
             .setSubscriptionConnectionPoolSize(50);
372

373
// Read strategy  
374
sentinelConfig.setReadMode(ReadMode.SLAVE)
375
             .setSubscriptionMode(SubscriptionMode.MASTER);
376

377
RedissonClient redisson = Redisson.create(config);
378
```
379

380
### Configuration File Loading
381

382
Methods for loading configuration from external files.
383

384
```java { .api }
385
// JSON configuration loading
386
public static Config fromJSON(String content);
387
public static Config fromJSON(File file) throws IOException;
388
public static Config fromJSON(URL url) throws IOException;
389
public static Config fromJSON(Reader reader) throws IOException;
390
public static Config fromJSON(InputStream inputStream) throws IOException;
391

392
// YAML configuration loading  
393
public static Config fromYAML(String content);
394
public static Config fromYAML(File file) throws IOException;
395
public static Config fromYAML(URL url) throws IOException;
396
public static Config fromYAML(Reader reader) throws IOException;
397
public static Config fromYAML(InputStream inputStream) throws IOException;
398
```
399

400
**Configuration File Examples:**
401

402
JSON configuration file (`redisson.json`):
403
```json
404
{
405
    "threads": 16,
406
    "nettyThreads": 32,
407
    "codec": "org.redisson.codec.JsonJacksonCodec",
408
    "transportMode": "NIO",
409
    "singleServerConfig": {
410
        "address": "redis://127.0.0.1:6379",
411
        "password": "mypassword",
412
        "database": 0,
413
        "connectionPoolSize": 64,
414
        "connectionMinimumIdleSize": 10,
415
        "subscriptionConnectionPoolSize": 50,
416
        "timeout": 3000,
417
        "connectTimeout": 10000,
418
        "idleConnectionTimeout": 10000,
419
        "retryAttempts": 3,
420
        "retryInterval": 1500
421
    }
422
}
423
```
424

425
YAML configuration file (`redisson.yml`):
426
```yaml
427
threads: 16
428
nettyThreads: 32
429
codec: "org.redisson.codec.JsonJacksonCodec"
430
transportMode: "NIO"
431

432
singleServerConfig:
433
  address: "redis://127.0.0.1:6379"
434
  password: "mypassword"
435
  database: 0
436
  connectionPoolSize: 64
437
  connectionMinimumIdleSize: 10
438
  subscriptionConnectionPoolSize: 50
439
  timeout: 3000
440
  connectTimeout: 10000
441
  idleConnectionTimeout: 10000
442
  retryAttempts: 3
443
  retryInterval: 1500
444
```
445

446
Loading configuration from files:
447
```java
448
// Load from JSON file
449
Config config = Config.fromJSON(new File("redisson.json"));
450
RedissonClient redisson = Redisson.create(config);
451

452
// Load from YAML file
453
Config yamlConfig = Config.fromYAML(new File("redisson.yml"));
454
RedissonClient yamlRedisson = Redisson.create(yamlConfig);
455

456
// Load from classpath resource
457
Config resourceConfig = Config.fromYAML(
458
    getClass().getClassLoader().getResourceAsStream("redisson-config.yml")
459
);
460

461
// Load from URL
462
Config urlConfig = Config.fromJSON(new URL("https://example.com/redisson-config.json"));
463
```
464

465
## Configuration Enums and Options
466

467
```java { .api }
468
// Transport modes
469
public enum TransportMode {
470
    NIO,     // Standard NIO transport
471
    EPOLL,   // Linux epoll transport (higher performance on Linux)
472
    KQUEUE   // macOS/BSD kqueue transport
473
}
474

475
// Read modes for cluster/sentinel
476
public enum ReadMode {
477
    SLAVE,              // Read from slave nodes only
478
    MASTER,             // Read from master nodes only  
479
    MASTER_SLAVE        // Read from both master and slave nodes
480
}
481

482
// Subscription modes
483
public enum SubscriptionMode {
484
    SLAVE,   // Subscribe through slave nodes
485
    MASTER   // Subscribe through master nodes
486
}
487

488
// Codec implementations for serialization
489
public enum CodecType {
490
    JSON_JACKSON("org.redisson.codec.JsonJacksonCodec"),
491
    KRYO("org.redisson.codec.KryoCodec"),
492
    FST("org.redisson.codec.FstCodec"),
493
    SERIALIZATION("org.redisson.codec.SerializationCodec"),
494
    MSGPACK_JACKSON("org.redisson.codec.MsgPackJacksonCodec"),
495
    SMILE_JACKSON("org.redisson.codec.SmileJacksonCodec"),
496
    CBOR_JACKSON("org.redisson.codec.CborJacksonCodec"),
497
    ION_JACKSON("org.redisson.codec.IonJacksonCodec");
498
    
499
    private final String className;
500
    
501
    CodecType(String className) {
502
        this.className = className;
503
    }
504
    
505
    public String getClassName() {
506
        return className;
507
    }
508
}
509

510
// Base configuration class
511
public abstract class BaseConfig<T extends BaseConfig<T>> {
512
    protected String password;
513
    protected String username;
514
    protected String clientName;
515
    protected int connectTimeout = 10000;
516
    protected int timeout = 3000;
517
    protected int retryAttempts = 3;
518
    protected int retryInterval = 1500;
519
    protected int idleConnectionTimeout = 10000;
520
    protected boolean keepAlive = true;
521
    protected boolean tcpNoDelay = true;
522
    
523
    // Common configuration methods available to all server configs
524
    public T setPassword(String password);
525
    public T setUsername(String username);
526
    public T setClientName(String clientName);
527
    public T setConnectTimeout(int connectTimeout);
528
    public T setTimeout(int timeout);
529
    public T setRetryAttempts(int retryAttempts);
530
    public T setRetryInterval(int retryInterval);
531
    public T setIdleConnectionTimeout(int idleConnectionTimeout);
532
    public T setKeepAlive(boolean keepAlive);
533
    public T setTcpNoDelay(boolean tcpNoDelay);
534
}
535
```