0
# Configuration System
1

2
Selenium Grid's configuration system provides flexible, multi-source configuration management with role-based access and type-safe value retrieval.
3

4
## Capabilities
5

6
### Core Configuration Interface
7

8
The main configuration interface for accessing configuration values from multiple sources.
9

10
```java { .api }
11
/**
12
 * Main configuration interface providing access to configuration sections and options
13
 */
14
interface Config {
15
    /** Get all available configuration section names */
16
    Set<String> getSectionNames();
17
    
18
    /** Get all options available in a specific section */
19
    Set<String> getOptions(String section);
20
    
21
    /** Get all values for a section/option pair (supports multi-value options) */
22
    Optional<List<String>> getAll(String section, String option);
23
    
24
    /** Get single string value for a section/option pair */
25
    Optional<String> get(String section, String option);
26
    
27
    /** Get integer value with automatic type conversion */
28
    Optional<Integer> getInt(String section, String option);
29
    
30
    /** Get boolean value with automatic type conversion */
31
    Optional<Boolean> getBool(String section, String option);
32
    
33
    /** Get array values (nested lists) */
34
    Optional<List<List<String>>> getArray(String section, String option);
35
    
36
    /** Get class instance with automatic instantiation */
37
    <X> X getClass(String section, String option, Class<X> typeOfClass, String defaultClazz);
38
}
39
```
40

41
**Usage Example:**
42

43
```java
44
Config config = new TomlConfig(Paths.get("grid.toml"));
45

46
// Get string values
47
Optional<String> hubHost = config.get("server", "host");
48
String host = hubHost.orElse("localhost");
49

50
// Get typed values
51
int port = config.getInt("server", "port").orElse(4444);
52
boolean enableTracing = config.getBool("tracing", "enable").orElse(false);
53

54
// Instantiate classes
55
EventBus eventBus = config.getClass("events", "implementation", 
56
                                   EventBus.class, "org.openqa.selenium.events.local.GuavaEventBus");
57
```
58

59
### Role Management
60

61
Grid roles define component responsibilities and configuration scopes.
62

63
```java { .api }
64
/**
65
 * Represents a grid component role (e.g., hub, node, distributor)
66
 */
67
class Role implements Comparable<Role> {
68
    /** Create a new role with the specified name */
69
    Role(String roleName);
70
    
71
    /** Factory method to create or retrieve a role */
72
    static Role of(String name);
73
    
74
    /** Get the role name */
75
    String getRoleName();
76
    
77
    /** Compare roles for ordering */
78
    int compareTo(Role o);
79
    
80
    // Standard equals/hashCode implementations
81
    boolean equals(Object o);
82
    int hashCode();
83
}
84

85
/**
86
 * Standard grid roles used by default components
87
 */
88
class StandardGridRoles {
89
    static final Role DISTRIBUTOR_ROLE = Role.of("distributor");
90
    static final Role EVENT_BUS_ROLE = Role.of("events");
91
    static final Role HTTPD_ROLE = Role.of("server");
92
    static final Role NODE_ROLE = Role.of("node");
93
    static final Role ROUTER_ROLE = Role.of("router");
94
    static final Role SESSION_MAP_ROLE = Role.of("sessions");
95
    static final Role SESSION_QUEUE_ROLE = Role.of("sessionqueue");
96
    
97
    /** Complete set of all standard roles */
98
    static final Set<Role> ALL_ROLES = Set.of(
99
        DISTRIBUTOR_ROLE, EVENT_BUS_ROLE, HTTPD_ROLE, NODE_ROLE,
100
        ROUTER_ROLE, SESSION_MAP_ROLE, SESSION_QUEUE_ROLE
101
    );
102
}
103

104
/**
105
 * Interface for components that have associated roles
106
 */
107
interface HasRoles {
108
    /** Get the roles this component is associated with */
109
    Set<Role> getRoles();
110
}
111
```
112

113
### Configuration Implementations
114

115
Multiple configuration sources that can be combined or used independently.
116

117
```java { .api }
118
/**
119
 * Environment variable-based configuration
120
 */
121
class EnvConfig implements Config {
122
    EnvConfig();
123
    // Reads from system environment variables with SE_ prefix
124
}
125

126
/**
127
 * Map-based configuration for programmatic setup
128
 */
129
class MapConfig implements Config {
130
    MapConfig(Map<String, Object> raw);
131
}
132

133
/**
134
 * JSON file-based configuration  
135
 */
136
class JsonConfig implements Config {
137
    JsonConfig(Path path) throws IOException;
138
    JsonConfig(Reader reader) throws IOException;
139
}
140

141
/**
142
 * TOML file-based configuration
143
 */
144
class TomlConfig implements Config {
145
    TomlConfig(Path path) throws IOException;
146
    TomlConfig(Reader reader) throws IOException;
147
}
148

149
/**
150
 * Annotation-based configuration using reflection
151
 */
152
class AnnotatedConfig implements Config {
153
    AnnotatedConfig(Object annotatedObject);
154
}
155

156
/**
157
 * Combines multiple configuration sources with precedence
158
 */
159
class CompoundConfig implements Config {
160
    CompoundConfig(Config... configs);
161
    // First config in array has highest precedence
162
}
163

164
/**
165
 * Caching wrapper that memoizes configuration values
166
 */
167
class MemoizedConfig implements Config {
168
    MemoizedConfig(Config delegate);
169
}
170
```
171

172
**Usage Example:**
173

174
```java
175
// Combine multiple configuration sources
176
Config config = new MemoizedConfig(
177
    new CompoundConfig(
178
        new EnvConfig(),                    // Highest precedence
179
        new TomlConfig(Paths.get("grid.toml")), 
180
        new MapConfig(defaultValues)        // Lowest precedence
181
    )
182
);
183
```
184

185
### Configuration Support Classes
186

187
Helper classes for command-line integration and error handling.
188

189
```java { .api }
190
/**
191
 * Exception thrown for configuration-related problems
192
 */
193
class ConfigException extends RuntimeException {
194
    ConfigException(String message);
195
    ConfigException(String message, Throwable cause);
196
}
197

198
/**
199
 * Command-line flags for configuration options
200
 */
201
class ConfigFlags {
202
    @Parameter(names = {"--config"}, description = "Path to configuration file")
203
    List<String> configPaths = new ArrayList<>();
204
    
205
    Config getConfig();
206
}
207
```
208

209
## Configuration File Examples
210

211
### TOML Configuration
212

213
```toml
214
[server]
215
host = "0.0.0.0"
216
port = 4444
217
max-threads = 24
218

219
[distributor]
220
implementation = "org.openqa.selenium.grid.distributor.local.LocalDistributor"
221
healthcheck-interval = "120s"
222

223
[sessionmap]
224
implementation = "org.openqa.selenium.grid.sessionmap.redis.RedisSessionMap"
225

226
[sessionmap.redis]
227
host = "redis.example.com"
228
port = 6379
229
```
230

231
### JSON Configuration
232

233
```json
234
{
235
  "server": {
236
    "host": "0.0.0.0",
237
    "port": 4444,
238
    "max-threads": 24
239
  },
240
  "distributor": {
241
    "implementation": "org.openqa.selenium.grid.distributor.local.LocalDistributor",
242
    "healthcheck-interval": "120s"
243
  }
244
}
245
```
246

247
### Environment Variables
248

249
```bash
250
SE_SERVER_HOST=0.0.0.0
251
SE_SERVER_PORT=4444
252
SE_DISTRIBUTOR_IMPLEMENTATION=org.openqa.selenium.grid.distributor.local.LocalDistributor
253
```