0
# Configuration Management
1

2
Comprehensive configuration system providing type-safe property access, dynamic reloading, and hierarchical property resolution for client applications. The system supports runtime configuration changes and provides typed access to all configuration parameters.
3

4
## Capabilities
5

6
### IClientConfig Interface
7

8
Main interface defining client configuration used by various APIs.
9

10
```java { .api }
11
/**
12
 * Main interface defining client configuration used by various APIs
13
 */
14
public interface IClientConfig {
15
    /**
16
     * Gets client name
17
     * @return the name of this client configuration
18
     */
19
    String getClientName();
20
    
21
    /**
22
     * Gets namespace
23
     * @return the namespace for this configuration
24
     */
25
    String getNameSpace();
26
    
27
    /**
28
     * Sets namespace
29
     * @param nameSpace the namespace to set
30
     */
31
    void setNameSpace(String nameSpace);
32
    
33
    /**
34
     * Loads properties for client
35
     * @param clientName the client name to load properties for
36
     */
37
    void loadProperties(String clientName);
38
    
39
    /**
40
     * Loads default values
41
     */
42
    void loadDefaultValues();
43
    
44
    /**
45
     * Gets all properties
46
     * @return map of all configuration properties
47
     * @deprecated Use typed access methods instead
48
     */
49
    @Deprecated
50
    Map<String, Object> getProperties();
51
    
52
    /**
53
     * Gets typed property value
54
     * @param key the configuration key
55
     * @return the value for the key, or default if not set
56
     */
57
    <T> T get(IClientConfigKey<T> key);
58
    
59
    /**
60
     * Gets value or default
61
     * @param key the configuration key
62
     * @return the value for the key, or the key's default value
63
     */
64
    <T> T getOrDefault(IClientConfigKey<T> key);
65
    
66
    /**
67
     * Gets value if explicitly set
68
     * @param key the configuration key
69
     * @return Optional containing the value if explicitly set, empty otherwise
70
     */
71
    <T> Optional<T> getIfSet(IClientConfigKey<T> key);
72
    
73
    /**
74
     * Gets value with fallback
75
     * @param key the configuration key
76
     * @param defaultValue fallback value if key is not set
77
     * @return the value for the key, or defaultValue if not set
78
     */
79
    <T> T get(IClientConfigKey<T> key, T defaultValue);
80
    
81
    /**
82
     * Sets typed property
83
     * @param key the configuration key
84
     * @param value the value to set
85
     * @return this configuration instance for chaining
86
     */
87
    <T> IClientConfig set(IClientConfigKey<T> key, T value);
88
    
89
    /**
90
     * Gets global dynamic property
91
     * @param key the configuration key
92
     * @return Property that reflects global configuration changes
93
     */
94
    <T> Property<T> getGlobalProperty(IClientConfigKey<T> key);
95
    
96
    /**
97
     * Gets scoped dynamic property
98
     * @param key the configuration key
99
     * @return Property that reflects client-scoped configuration changes
100
     */
101
    <T> Property<T> getDynamicProperty(IClientConfigKey<T> key);
102
    
103
    /**
104
     * Resolves VIP addresses
105
     * @return resolved VIP addresses
106
     */
107
    String resolveDeploymentContextbasedVipAddresses();
108
}
109
```
110

111
### CommonClientConfigKey
112

113
Defines common client configuration keys with type safety.
114

115
```java { .api }
116
/**
117
 * Defines common client configuration keys with type safety
118
 */
119
public abstract class CommonClientConfigKey<T> implements IClientConfigKey<T> {
120
    // Namespace constant
121
    public static final String DEFAULT_NAME_SPACE = "ribbon";
122
    
123
    // Core application properties
124
    public static final IClientConfigKey<String> AppName;
125
    public static final IClientConfigKey<String> Version;
126
    public static final IClientConfigKey<Integer> Port;
127
    public static final IClientConfigKey<Integer> SecurePort;
128
    public static final IClientConfigKey<String> VipAddress;
129
    public static final IClientConfigKey<Boolean> ForceClientPortConfiguration;
130
    
131
    // Connection and timeout settings
132
    public static final IClientConfigKey<Integer> ConnectTimeout;
133
    public static final IClientConfigKey<Integer> ReadTimeout;
134
    public static final IClientConfigKey<Integer> MaxAutoRetries;
135
    public static final IClientConfigKey<Integer> MaxAutoRetriesNextServer;
136
    public static final IClientConfigKey<Boolean> OkToRetryOnAllOperations;
137
    public static final IClientConfigKey<Boolean> RequestSpecificRetryOn;
138
    
139
    // Connection pool and HTTP settings
140
    public static final IClientConfigKey<Integer> MaxConnectionsPerHost;
141
    public static final IClientConfigKey<Integer> MaxTotalConnections;
142
    public static final IClientConfigKey<Boolean> EnableConnectionPool;
143
    public static final IClientConfigKey<Integer> PoolMaxThreads;
144
    public static final IClientConfigKey<Integer> PoolMinThreads;
145
    public static final IClientConfigKey<Integer> PoolKeepAliveTime;
146
    public static final IClientConfigKey<String> PoolKeepAliveTimeUnits;
147
    
148
    // Security and SSL
149
    public static final IClientConfigKey<Boolean> IsSecure;
150
    public static final IClientConfigKey<String> KeyStore;
151
    public static final IClientConfigKey<String> KeyStorePassword;
152
    public static final IClientConfigKey<String> TrustStore;
153
    public static final IClientConfigKey<String> TrustStorePassword;
154
    
155
    // Load balancer and server list properties
156
    public static final IClientConfigKey<String> NFLoadBalancerClassName;
157
    public static final IClientConfigKey<String> NFLoadBalancerRuleClassName;
158
    public static final IClientConfigKey<String> NFLoadBalancerPingClassName;
159
    public static final IClientConfigKey<String> ServerListClassName;
160
    public static final IClientConfigKey<String> ServerListUpdaterClassName;
161
    
162
    // Circuit breaker and health check settings
163
    public static final IClientConfigKey<Integer> CircuitBreakerRequestVolumeThreshold;
164
    public static final IClientConfigKey<Integer> CircuitBreakerSleepWindowInMilliseconds;
165
    public static final IClientConfigKey<Integer> CircuitBreakerErrorThresholdPercentage;
166
    public static final IClientConfigKey<Boolean> CircuitBreakerForceOpen;
167
    public static final IClientConfigKey<Boolean> CircuitBreakerForceClosed;
168
    
169
    // Prime connections and performance
170
    public static final IClientConfigKey<Boolean> EnablePrimeConnections;
171
    public static final IClientConfigKey<String> PrimeConnectionsClassName;
172
    public static final IClientConfigKey<Integer> MaxRetriesPerServerPrimeConnection;
173
    public static final IClientConfigKey<Integer> MaxTotalTimeToPrimeConnections;
174
    public static final IClientConfigKey<Float> MinPrimeConnectionsRatio;
175
    public static final IClientConfigKey<String> PrimeConnectionsURI;
176
    
177
    // Note: CommonClientConfigKey defines 75+ configuration keys in total.
178
    // The above shows the most commonly used keys. Use keys() method to get all available keys.
179
    
180
    /**
181
     * Protected constructor for creating configuration keys
182
     * @param configKey the string key
183
     */
184
    protected CommonClientConfigKey(String configKey);
185
    
186
    /**
187
     * Protected constructor with default value
188
     * @param configKey the string key
189
     * @param defaultValue the default value for this key
190
     */
191
    protected CommonClientConfigKey(String configKey, T defaultValue);
192
    
193
    /**
194
     * Returns the key type
195
     * @return the Class representing the value type
196
     */
197
    public Class<T> type();
198
    
199
    /**
200
     * Returns the key string
201
     * @return the string representation of this key
202
     */
203
    public String key();
204
    
205
    /**
206
     * Returns the default value
207
     * @return the default value for this key
208
     */
209
    public T defaultValue();
210
    
211
    /**
212
     * Returns all defined keys
213
     * @return Set of all configuration keys
214
     */
215
    public static Set<IClientConfigKey> keys();
216
    
217
    /**
218
     * Returns key by name
219
     * @param name the key name
220
     * @return the configuration key with the given name
221
     */
222
    public static IClientConfigKey valueOf(String name);
223
}
224
```
225

226
### Property Interface
227

228
Dynamic configuration property interface with change notifications.
229

230
```java { .api }
231
/**
232
 * Ribbon-specific encapsulation of a dynamic configuration property
233
 */
234
public interface Property<T> {
235
    /**
236
     * Registers change listener
237
     * @param consumer function to call when property value changes
238
     */
239
    void onChange(Consumer<T> consumer);
240
    
241
    /**
242
     * Gets current value
243
     * @return Optional containing current value, or empty if not set
244
     */
245
    Optional<T> get();
246
    
247
    /**
248
     * Gets current value or default
249
     * @return current value, or default value if not set
250
     */
251
    T getOrDefault();
252
    
253
    /**
254
     * Creates fallback property
255
     * @param fallback property to use if this property is not set
256
     * @return new Property that falls back to the given property
257
     */
258
    default Property<T> fallbackWith(Property<T> fallback);
259
    
260
    /**
261
     * Creates static property
262
     * @param value the static value
263
     * @return Property that always returns the given value
264
     */
265
    static <T> Property<T> of(T value);
266
}
267
```
268

269
### ReloadableClientConfig
270

271
Base implementation supporting runtime property reloading with optimization.
272

273
```java { .api }
274
/**
275
 * Base implementation supporting runtime property reloading with optimization
276
 */
277
public abstract class ReloadableClientConfig implements IClientConfig {
278
    /**
279
     * Protected constructor
280
     * @param resolver the property resolver to use
281
     */
282
    protected ReloadableClientConfig(PropertyResolver resolver);
283
    
284
    /**
285
     * Refreshes all properties from underlying storage
286
     */
287
    public final void reload();
288
    
289
    /**
290
     * Gets client name
291
     * @return the client name
292
     */
293
    public final String getClientName();
294
    
295
    /**
296
     * Gets namespace
297
     * @return the namespace
298
     */
299
    public String getNameSpace();
300
    
301
    /**
302
     * Sets namespace
303
     * @param nameSpace the namespace to set
304
     */
305
    public final void setNameSpace(String nameSpace);
306
    
307
    /**
308
     * Loads properties for client
309
     * @param clientName the client name
310
     */
311
    public void loadProperties(String clientName);
312
    
313
    /**
314
     * Iterates all properties
315
     * @param consumer function to call for each property
316
     */
317
    public void forEach(BiConsumer<IClientConfigKey<?>, Object> consumer);
318
    
319
    /**
320
     * Gets prefix-mapped property
321
     * @param key the configuration key
322
     * @return Property mapped with client-specific prefix
323
     */
324
    public <T> Property<T> getPrefixMappedProperty(IClientConfigKey<T> key);
325
    
326
    /**
327
     * Applies configuration override
328
     * @param override configuration to override with
329
     * @return this configuration with overrides applied
330
     */
331
    public IClientConfig applyOverride(IClientConfig override);
332
    
333
    /**
334
     * Gets number of property refreshes
335
     * @return count of how many times properties have been refreshed
336
     */
337
    public long getRefreshCount();
338
}
339
```
340

341
### ClientConfigFactory
342

343
Factory interface for creating client configurations.
344

345
```java { .api }
346
/**
347
 * Factory interface for creating client configurations
348
 */
349
public interface ClientConfigFactory {
350
    /**
351
     * Default factory instance
352
     */
353
    ClientConfigFactory DEFAULT = findDefaultConfigFactory();
354
    
355
    /**
356
     * Creates a new client configuration
357
     * @return new IClientConfig instance
358
     */
359
    IClientConfig newConfig();
360
    
361
    /**
362
     * Returns factory priority (default: 0)
363
     * @return priority value for factory selection
364
     */
365
    default int getPriority();
366
    
367
    /**
368
     * Finds the default configuration factory
369
     * @return the default ClientConfigFactory implementation
370
     */
371
    static ClientConfigFactory findDefaultConfigFactory();
372
}
373
```
374

375
**Usage Examples:**
376

377
```java
378
import com.netflix.client.config.*;
379

380
// Create and configure a client
381
IClientConfig config = ClientConfigFactory.DEFAULT.newConfig();
382
config.loadProperties("my-service-client");
383

384
// Set connection timeouts
385
config.set(CommonClientConfigKey.ConnectTimeout, 5000);  // 5 seconds
386
config.set(CommonClientConfigKey.ReadTimeout, 10000);   // 10 seconds
387

388
// Configure retry behavior
389
config.set(CommonClientConfigKey.MaxAutoRetries, 3);
390
config.set(CommonClientConfigKey.MaxAutoRetriesNextServer, 1);
391
config.set(CommonClientConfigKey.OkToRetryOnAllOperations, false);
392

393
// Configure circuit breaker
394
config.set(CommonClientConfigKey.CircuitBreakerRequestVolumeThreshold, 20);
395
config.set(CommonClientConfigKey.CircuitBreakerSleepWindowInMilliseconds, 5000);
396
config.set(CommonClientConfigKey.CircuitBreakerErrorThresholdPercentage, 50);
397

398
// Use dynamic properties for runtime configuration changes
399
Property<Integer> timeoutProperty = config.getDynamicProperty(CommonClientConfigKey.ConnectTimeout);
400
timeoutProperty.onChange(newTimeout -> {
401
    System.out.println("Connect timeout changed to: " + newTimeout + "ms");
402
});
403

404
// Get values with fallbacks
405
int connectTimeout = config.getOrDefault(CommonClientConfigKey.ConnectTimeout);
406
Optional<String> appName = config.getIfSet(CommonClientConfigKey.AppName);
407

408
// Client-specific configuration with namespace
409
config.setNameSpace("my-service");
410
config.loadProperties("user-service-client");
411
```
412

413
### Advanced Configuration Patterns
414

415
```java
416
// Custom configuration key
417
public class MyConfigKey extends CommonClientConfigKey<String> {
418
    public static final IClientConfigKey<String> CustomProperty = 
419
        new MyConfigKey("my.custom.property", "default-value");
420
    
421
    private MyConfigKey(String key, String defaultValue) {
422
        super(key, defaultValue);
423
    }
424
}
425

426
// Using fallback properties
427
Property<Integer> primary = config.getDynamicProperty(CommonClientConfigKey.ConnectTimeout);
428
Property<Integer> fallback = Property.of(5000); // static fallback
429
Property<Integer> combined = primary.fallbackWith(fallback);
430

431
// Configuration inheritance and overrides
432
IClientConfig baseConfig = ClientConfigFactory.DEFAULT.newConfig();
433
baseConfig.set(CommonClientConfigKey.ConnectTimeout, 5000);
434

435
IClientConfig serviceSpecificConfig = ClientConfigFactory.DEFAULT.newConfig();
436
serviceSpecificConfig.set(CommonClientConfigKey.ReadTimeout, 15000);
437

438
IClientConfig finalConfig = baseConfig.applyOverride(serviceSpecificConfig);
439
```