0
# Configuration Management
1

2
The configuration management system provides dynamic configuration capabilities for cluster client settings including server assignments, request timeouts, and property-based updates with change notifications.
3

4
## Capabilities
5

6
### ClusterClientConfigManager
7

8
Central configuration manager that handles all cluster client configuration including server assignments and client settings.
9

10
```java { .api }
11
/**
12
 * Configuration manager for cluster client settings
13
 */
14
public final class ClusterClientConfigManager {
15
    /**
16
     * Apply new client configuration settings
17
     * @param config new configuration to apply
18
     */
19
    public static void applyNewConfig(ClusterClientConfig config);
20
    
21
    /**
22
     * Apply new server assignment configuration  
23
     * @param assignConfig new server assignment to apply
24
     */
25
    public static void applyNewAssignConfig(ClusterClientAssignConfig assignConfig);
26
    
27
    /**
28
     * Register property listener for server assignment changes
29
     * @param property property to listen for server assignment updates
30
     */
31
    public static void registerServerAssignProperty(SentinelProperty<ClusterClientAssignConfig> property);
32
    
33
    /**
34
     * Register property listener for client configuration changes
35
     * @param property property to listen for client config updates
36
     */
37
    public static void registerClientConfigProperty(SentinelProperty<ClusterClientConfig> property);
38
    
39
    /**
40
     * Add observer for server assignment changes
41
     * @param observer observer to notify on server changes
42
     */
43
    public static void addServerChangeObserver(ServerChangeObserver observer);
44
    
45
    /**
46
     * Get currently configured server host
47
     * @return server host string, or null if not configured
48
     */
49
    public static String getServerHost();
50
    
51
    /**
52
     * Get currently configured server port
53
     * @return server port number
54
     */
55
    public static int getServerPort();
56
    
57
    /**
58
     * Get current request timeout setting
59
     * @return request timeout in milliseconds
60
     */
61
    public static int getRequestTimeout();
62
    
63
    /**
64
     * Get current connection timeout setting
65
     * @return connection timeout in milliseconds
66
     */
67
    public static int getConnectTimeout();
68
    
69
    /**
70
     * Validate server assignment configuration
71
     * @param config configuration to validate
72
     * @return true if configuration is valid
73
     */
74
    public static boolean isValidAssignConfig(ClusterClientAssignConfig config);
75
    
76
    /**
77
     * Validate client configuration
78
     * @param config configuration to validate  
79
     * @return true if configuration is valid
80
     */
81
    public static boolean isValidClientConfig(ClusterClientConfig config);
82
}
83
```
84

85
**Usage Examples:**
86

87
```java
88
import com.alibaba.csp.sentinel.cluster.client.config.ClusterClientConfigManager;
89
import com.alibaba.csp.sentinel.cluster.client.config.ClusterClientConfig;
90
import com.alibaba.csp.sentinel.cluster.client.config.ClusterClientAssignConfig;
91

92
// Configure server assignment
93
ClusterClientAssignConfig serverConfig = new ClusterClientAssignConfig("cluster-server", 8719);
94
ClusterClientConfigManager.applyNewAssignConfig(serverConfig);
95

96
// Configure client settings
97
ClusterClientConfig clientConfig = new ClusterClientConfig().setRequestTimeout(5000);
98
ClusterClientConfigManager.applyNewConfig(clientConfig);
99

100
// Check current configuration
101
System.out.println("Server: " + ClusterClientConfigManager.getServerHost() + 
102
                   ":" + ClusterClientConfigManager.getServerPort());
103
System.out.println("Request timeout: " + ClusterClientConfigManager.getRequestTimeout());
104

105
// Validate configuration before applying
106
ClusterClientAssignConfig newConfig = new ClusterClientAssignConfig("invalid-host", -1);
107
if (ClusterClientConfigManager.isValidAssignConfig(newConfig)) {
108
    ClusterClientConfigManager.applyNewAssignConfig(newConfig);
109
} else {
110
    System.err.println("Invalid server configuration");
111
}
112
```
113

114
### Client Configuration
115

116
Configuration class for client-specific settings like request timeouts.
117

118
```java { .api }
119
/**
120
 * Configuration settings for cluster client behavior
121
 */
122
public class ClusterClientConfig {
123
    /**
124
     * Create new client configuration with default settings
125
     */
126
    public ClusterClientConfig();
127
    
128
    /**
129
     * Get current request timeout setting
130
     * @return request timeout in milliseconds, or null if not set
131
     */
132
    public Integer getRequestTimeout();
133
    
134
    /**
135
     * Set request timeout for cluster requests
136
     * @param requestTimeout timeout in milliseconds (must be > 0)
137
     * @return this configuration instance for fluent chaining
138
     */
139
    public ClusterClientConfig setRequestTimeout(Integer requestTimeout);
140
    
141
    /**
142
     * Get string representation of configuration
143
     * @return formatted configuration string
144
     */
145
    public String toString();
146
}
147
```
148

149
**Usage Examples:**
150

151
```java
152
// Create configuration with fluent API
153
ClusterClientConfig config = new ClusterClientConfig()
154
    .setRequestTimeout(3000);
155

156
// Apply configuration  
157
ClusterClientConfigManager.applyNewConfig(config);
158

159
// Create configuration step by step
160
ClusterClientConfig stepConfig = new ClusterClientConfig();
161
stepConfig.setRequestTimeout(10000);
162
ClusterClientConfigManager.applyNewConfig(stepConfig);
163
```
164

165
### Server Assignment Configuration
166

167
Configuration class for specifying which cluster server to connect to.
168

169
```java { .api }
170
/**
171
 * Configuration for cluster server assignment
172
 */
173
public class ClusterClientAssignConfig {
174
    /**
175
     * Create empty server assignment configuration
176
     */
177
    public ClusterClientAssignConfig();
178
    
179
    /**
180
     * Create server assignment configuration with host and port
181
     * @param serverHost hostname or IP address of cluster server
182
     * @param serverPort port number of cluster server
183
     */
184
    public ClusterClientAssignConfig(String serverHost, Integer serverPort);
185
    
186
    /**
187
     * Get configured server host
188
     * @return server hostname or IP address
189
     */
190
    public String getServerHost();
191
    
192
    /**
193
     * Set server host
194
     * @param serverHost hostname or IP address
195
     * @return this configuration instance for fluent chaining
196
     */
197
    public ClusterClientAssignConfig setServerHost(String serverHost);
198
    
199
    /**
200
     * Get configured server port
201
     * @return server port number
202
     */
203
    public Integer getServerPort();
204
    
205
    /**
206
     * Set server port
207
     * @param serverPort port number (must be 1-65535)
208
     * @return this configuration instance for fluent chaining  
209
     */
210
    public ClusterClientAssignConfig setServerPort(Integer serverPort);
211
    
212
    /**
213
     * Get string representation of server assignment
214
     * @return formatted server assignment string
215
     */
216
    public String toString();
217
}
218
```
219

220
**Usage Examples:**
221

222
```java
223
// Create with constructor
224
ClusterClientAssignConfig config1 = new ClusterClientAssignConfig("localhost", 8719);
225

226
// Create with fluent API
227
ClusterClientAssignConfig config2 = new ClusterClientAssignConfig()
228
    .setServerHost("cluster-server.example.com")
229
    .setServerPort(9090);
230

231
// Step-by-step configuration
232
ClusterClientAssignConfig config3 = new ClusterClientAssignConfig();
233
config3.setServerHost("10.0.1.100");
234
config3.setServerPort(8719);
235

236
// Apply any of these configurations
237
ClusterClientConfigManager.applyNewAssignConfig(config2);
238
```
239

240
### Server Change Observer
241

242
Interface for receiving notifications when cluster server assignments change.
243

244
```java { .api }
245
/**
246
 * Observer interface for server assignment changes
247
 */
248
public interface ServerChangeObserver {
249
    /**
250
     * Called when cluster server assignment changes
251
     * @param assignConfig new server assignment configuration
252
     */
253
    void onRemoteServerChange(ClusterClientAssignConfig assignConfig);
254
}
255
```
256

257
**Usage Examples:**
258

259
```java
260
// Create custom observer
261
ServerChangeObserver observer = new ServerChangeObserver() {
262
    @Override
263
    public void onRemoteServerChange(ClusterClientAssignConfig assignConfig) {
264
        System.out.println("Server changed to: " + assignConfig.getServerHost() + 
265
                          ":" + assignConfig.getServerPort());
266
        // Custom logic for server changes
267
        notifyApplicationComponents(assignConfig);
268
    }
269
};
270

271
// Register observer
272
ClusterClientConfigManager.addServerChangeObserver(observer);
273

274
// Lambda expression version (Java 8+)
275
ClusterClientConfigManager.addServerChangeObserver(assignConfig -> {
276
    System.out.println("New server: " + assignConfig);
277
    reconnectDependentServices();
278
});
279
```
280

281
### Startup Configuration
282

283
Utility for reading startup configuration parameters from system properties.
284

285
```java { .api }
286
/**
287
 * Configuration reader for startup parameters
288
 */
289
public class ClusterClientStartUpConfig {
290
    /**
291
     * Get maximum parameter serialization size from system properties
292
     * @return maximum bytes for parameter serialization, or null if not configured
293
     */
294
    public static Integer getMaxParamByteSize();
295
}
296
```
297

298
**Usage Examples:**
299

300
```java
301
// Check startup configuration
302
Integer maxBytes = ClusterClientStartUpConfig.getMaxParamByteSize();
303
if (maxBytes != null) {
304
    System.out.println("Max parameter bytes: " + maxBytes);
305
} else {
306
    System.out.println("Using default parameter size limits");
307
}
308

309
// System property: -Dcsp.sentinel.cluster.max.param.byte.size=1024
310
```
311

312
## Dynamic Configuration Updates
313

314
The configuration system supports dynamic updates through Sentinel property listeners:
315

316
**Property-Based Configuration:**
317

318
```java
319
import com.alibaba.csp.sentinel.property.DynamicSentinelProperty;
320
import com.alibaba.csp.sentinel.property.SentinelProperty;
321

322
// Create dynamic property for server assignment
323
SentinelProperty<ClusterClientAssignConfig> serverProperty = new DynamicSentinelProperty<>();
324
ClusterClientConfigManager.registerServerAssignProperty(serverProperty);
325

326
// Update server assignment dynamically
327
ClusterClientAssignConfig newServer = new ClusterClientAssignConfig("new-server", 8720);
328
serverProperty.updateValue(newServer);
329

330
// Configuration change will be automatically applied and observers notified
331
```
332

333
## Configuration Validation
334

335
The configuration manager validates all settings before applying them:
336

337
**Server Assignment Validation:**
338
- Host must not be blank
339
- Port must be between 1 and 65535
340
- Both host and port must be specified
341

342
**Client Configuration Validation:**
343
- Request timeout must be greater than 0
344

345
**Validation Examples:**
346

347
```java
348
// Valid configurations
349
ClusterClientAssignConfig valid1 = new ClusterClientAssignConfig("localhost", 8719);
350
ClusterClientAssignConfig valid2 = new ClusterClientAssignConfig("192.168.1.100", 9090);
351

352
// Invalid configurations  
353
ClusterClientAssignConfig invalid1 = new ClusterClientAssignConfig("", 8719);    // blank host
354
ClusterClientAssignConfig invalid2 = new ClusterClientAssignConfig("host", -1); // invalid port
355
ClusterClientAssignConfig invalid3 = new ClusterClientAssignConfig("host", 70000); // port too high
356

357
System.out.println(ClusterClientConfigManager.isValidAssignConfig(valid1));   // true
358
System.out.println(ClusterClientConfigManager.isValidAssignConfig(invalid1)); // false
359
```
360

361
## Thread Safety
362

363
All configuration management operations are thread-safe and can be called from multiple threads simultaneously. The configuration manager uses appropriate synchronization to ensure consistent state during updates.