0
# Configuration
1

2
Database connection management and Selenium Grid configuration integration for JDBC session storage.
3

4
## Capabilities
5

6
### Static Factory Creation
7

8
Creates a JDBC session map from Selenium Grid configuration.
9

10
```java { .api }
11
/**
12
 * Creates a JDBC-backed session map from Grid configuration
13
 * @param config The Grid configuration containing JDBC settings
14
 * @return A fully configured JdbcBackedSessionMap instance
15
 * @throws ConfigException if required configuration is missing or invalid
16
 * @throws JdbcException if database connection fails
17
 */
18
public static SessionMap create(Config config);
19
```
20

21
**Usage Example:**
22

23
```java
24
import org.openqa.selenium.grid.config.Config;
25
import org.openqa.selenium.grid.sessionmap.SessionMap;
26
import org.openqa.selenium.grid.sessionmap.jdbc.JdbcBackedSessionMap;
27

28
// Create from Grid configuration
29
Config config = // ... your Grid configuration
30
SessionMap sessionMap = JdbcBackedSessionMap.create(config);
31

32
// The factory method handles:
33
// - Reading JDBC configuration from config
34
// - Creating database connection
35
// - Setting up event bus integration
36
// - Configuring distributed tracing
37
```
38

39
### JDBC Connection Management
40

41
Manages database connections and configuration options for the session map.
42

43
```java { .api }
44
/**
45
 * Configuration manager for JDBC session map options
46
 */
47
public class JdbcSessionMapOptions {
48
  /**
49
   * Creates JDBC options from Grid configuration
50
   * @param config The Grid configuration
51
   * @throws JdbcException if required JDBC URL is missing
52
   */
53
  public JdbcSessionMapOptions(Config config);
54
  
55
  /**
56
   * Creates a JDBC connection using configured parameters
57
   * @return A JDBC connection ready for use
58
   * @throws SQLException if connection fails
59
   */
60
  public Connection getJdbcConnection() throws SQLException;
61
  
62
  /**
63
   * Gets the configured JDBC URL
64
   * @return The database connection URL
65
   */
66
  public String getJdbcUrl();
67
  
68
  /**
69
   * Gets the configured JDBC username
70
   * @return The database username
71
   */
72
  public String getJdbcUser();
73
}
74
```
75

76
**Usage Example:**
77

78
```java
79
import org.openqa.selenium.grid.sessionmap.jdbc.JdbcSessionMapOptions;
80
import java.sql.Connection;
81

82
// Create options from configuration
83
JdbcSessionMapOptions options = new JdbcSessionMapOptions(config);
84

85
// Get connection details
86
String url = options.getJdbcUrl();
87
String user = options.getJdbcUser();
88
System.out.println("Connecting to: " + url + " as " + user);
89

90
// Get active connection
91
try {
92
    Connection connection = options.getJdbcConnection();
93
    System.out.println("Database connection established");
94
    // Use connection...
95
} catch (SQLException e) {
96
    System.err.println("Failed to connect to database: " + e.getMessage());
97
}
98
```
99

100
### Command-Line Configuration
101

102
Defines command-line flags and configuration keys for JDBC session map setup.
103

104
```java { .api }
105
/**
106
 * Command-line flags for JDBC session map configuration
107
 * Implements HasRoles for Grid role-based configuration
108
 */
109
import com.google.auto.service.AutoService;
110
import org.openqa.selenium.grid.config.HasRoles;
111
import org.openqa.selenium.grid.config.Role;
112
import java.util.Set;
113

114
@AutoService(HasRoles.class)
115
public class JdbcSessionMapFlags implements HasRoles {
116
  /**
117
   * Gets the Grid roles this configuration applies to
118
   * @return Set containing SESSION_MAP_ROLE
119
   */
120
  public Set<Role> getRoles();
121
}
122
```
123

124
## Configuration Options
125

126
### JDBC URL Configuration
127

128
```java
129
// Command line flag
130
--jdbc-url "jdbc:mysql://localhost:3306/selenium_grid"
131

132
// Configuration section: "sessions"
133
// Configuration key: "jdbc-url"
134
// Example: "jdbc:mysql://localhost:3306/TestDatabase"
135
```
136

137
**Supported Database URLs:**
138

139
- **MySQL**: `jdbc:mysql://hostname:port/database`
140
- **PostgreSQL**: `jdbc:postgresql://hostname:port/database`
141
- **H2**: `jdbc:h2:mem:testdb` or `jdbc:h2:file:/path/to/db`
142
- **SQLite**: `jdbc:sqlite:/path/to/database.db`
143
- **Oracle**: `jdbc:oracle:thin:@hostname:port:sid`
144
- **SQL Server**: `jdbc:sqlserver://hostname:port;databaseName=database`
145

146
### JDBC User Configuration
147

148
```java
149
// Command line flag
150
--jdbc-user "grid_user"
151

152
// Configuration section: "sessions"
153
// Configuration key: "jdbc-user"
154
// Example: "myTestUser"
155
```
156

157
### JDBC Password Configuration
158

159
```java
160
// Command line flag
161
--jdbc-password "password123"
162

163
// Configuration section: "sessions"
164
// Configuration key: "jdbc-password"
165
// Example: "hunter2"
166
```
167

168
## Complete Configuration Examples
169

170
### Command Line Setup
171

172
```bash
173
# Standalone Grid with JDBC session map
174
java -jar selenium-server-4.33.0.jar standalone \
175
  --jdbc-url "jdbc:mysql://db.example.com:3306/selenium_grid" \
176
  --jdbc-user "selenium_user" \
177
  --jdbc-password "secure_password"
178

179
# Hub with JDBC session map
180
java -jar selenium-server-4.33.0.jar hub \
181
  --jdbc-url "jdbc:postgresql://postgres.grid.com:5432/sessions" \
182
  --jdbc-user "grid_admin" \
183
  --jdbc-password "admin_pass"
184
```
185

186
### Programmatic Configuration
187

188
```java
189
import org.openqa.selenium.grid.config.Config;
190
import org.openqa.selenium.grid.config.MapConfig;
191
import java.util.Map;
192

193
// Create configuration programmatically
194
Map<String, Object> configMap = Map.of(
195
    "sessions", Map.of(
196
        "jdbc-url", "jdbc:h2:mem:testdb",
197
        "jdbc-user", "sa",
198
        "jdbc-password", ""
199
    )
200
);
201

202
Config config = new MapConfig(configMap);
203
SessionMap sessionMap = JdbcBackedSessionMap.create(config);
204
```
205

206
### Environment-Based Configuration
207

208
```java
209
// Using environment variables in configuration
210
String jdbcUrl = System.getenv("SELENIUM_JDBC_URL");
211
String jdbcUser = System.getenv("SELENIUM_JDBC_USER");
212
String jdbcPassword = System.getenv("SELENIUM_JDBC_PASSWORD");
213

214
Map<String, Object> configMap = Map.of(
215
    "sessions", Map.of(
216
        "jdbc-url", jdbcUrl != null ? jdbcUrl : "jdbc:h2:mem:default",
217
        "jdbc-user", jdbcUser != null ? jdbcUser : "sa",
218
        "jdbc-password", jdbcPassword != null ? jdbcPassword : ""
219
    )
220
);
221

222
Config config = new MapConfig(configMap);
223
```
224

225
## Configuration Validation
226

227
The configuration system validates required settings:
228

229
- **JDBC URL is required**: The system throws `JdbcException` if `--jdbc-url` is not provided
230
- **User and password are optional**: Default to empty strings if not specified
231
- **Connection testing**: The factory method attempts to establish a connection during creation
232

233
```java
234
try {
235
    SessionMap sessionMap = JdbcBackedSessionMap.create(config);
236
    System.out.println("JDBC session map configured successfully");
237
} catch (ConfigException e) {
238
    System.err.println("Configuration error: " + e.getMessage());
239
} catch (JdbcException e) {
240
    System.err.println("Database connection error: " + e.getMessage());
241
}
242
```
243

244
## Integration with Grid Configuration
245

246
The JDBC session map integrates seamlessly with Selenium Grid's configuration system:
247

248
- **Role-based configuration**: Only applies to components with SESSION_MAP_ROLE
249
- **Config section**: Uses "sessions" section for all JDBC-related settings
250
- **Automatic discovery**: Grid automatically discovers and loads the configuration via `@AutoService`
251
- **Factory integration**: Works with Grid's dependency injection system