0
# Selenium JDBC Session Map
1

2
The Selenium JDBC Session Map provides a database-backed implementation of the SessionMap interface for Selenium Grid. It enables distributed session management through database persistence, allowing WebDriver session state to be stored, retrieved, and shared across multiple grid nodes for enterprise-scale browser automation infrastructure.
3

4
## Package Information
5

6
- **Package Name**: selenium-session-map-jdbc
7
- **Package Type**: maven
8
- **Group ID**: org.seleniumhq.selenium
9
- **Artifact ID**: selenium-session-map-jdbc
10
- **Language**: Java
11
- **Installation**: Add to your Maven dependencies or use with Selenium Grid
12

13
```xml
14
<dependency>
15
    <groupId>org.seleniumhq.selenium</groupId>
16
    <artifactId>selenium-session-map-jdbc</artifactId>
17
    <version>4.33.0</version>
18
</dependency>
19
```
20

21
## Core Imports
22

23
```java
24
import org.openqa.selenium.grid.sessionmap.jdbc.JdbcBackedSessionMap;
25
import org.openqa.selenium.grid.sessionmap.jdbc.JdbcSessionMapOptions;
26
import org.openqa.selenium.grid.sessionmap.jdbc.JdbcSessionMapFlags;
27
import org.openqa.selenium.grid.sessionmap.jdbc.JdbcException;
28
import org.openqa.selenium.grid.sessionmap.SessionMap;
29
import org.openqa.selenium.grid.data.Session;
30
import org.openqa.selenium.remote.SessionId;
31
import org.openqa.selenium.grid.config.Config;
32
import org.openqa.selenium.events.EventBus;
33
import org.openqa.selenium.remote.tracing.Tracer;
34
import org.openqa.selenium.Capabilities;
35
import org.openqa.selenium.ImmutableCapabilities;
36
import org.openqa.selenium.NoSuchSessionException;
37
import java.sql.Connection;
38
import java.sql.SQLException;
39
import java.net.URI;
40
import java.time.Instant;
41
import java.io.Closeable;
42
```
43

44
## Basic Usage
45

46
### Creating a JDBC Session Map
47

48
```java
49
import org.openqa.selenium.grid.config.Config;
50
import org.openqa.selenium.grid.sessionmap.jdbc.JdbcBackedSessionMap;
51

52
// Using the static factory method with configuration
53
Config config = // ... your grid configuration
54
SessionMap sessionMap = JdbcBackedSessionMap.create(config);
55

56
// Manual construction with explicit dependencies
57
import org.openqa.selenium.remote.tracing.Tracer;
58
import java.sql.Connection;
59
import org.openqa.selenium.events.EventBus;
60

61
Tracer tracer = // ... your tracer instance
62
Connection connection = // ... your JDBC connection
63
EventBus eventBus = // ... your event bus
64
JdbcBackedSessionMap sessionMap = new JdbcBackedSessionMap(tracer, connection, eventBus);
65
```
66

67
### Configuration Setup
68

69
```java
70
import org.openqa.selenium.grid.config.Config;
71
import org.openqa.selenium.grid.sessionmap.jdbc.JdbcSessionMapOptions;
72
import java.sql.Connection;
73

74
// Configure JDBC connection options
75
JdbcSessionMapOptions options = new JdbcSessionMapOptions(config);
76
Connection connection = options.getJdbcConnection();
77
String jdbcUrl = options.getJdbcUrl();
78
String jdbcUser = options.getJdbcUser();
79
```
80

81
### Command Line Usage
82

83
```bash
84
# Configure Selenium Grid with JDBC session map
85
java -jar selenium-server-4.33.0.jar standalone \
86
  --jdbc-url "jdbc:mysql://localhost:3306/selenium_grid" \
87
  --jdbc-user "grid_user" \
88
  --jdbc-password "password123"
89
```
90

91
## Architecture
92

93
The JDBC Session Map integrates with several key Selenium Grid components:
94

95
- **SessionMap Interface**: Implements the standard Grid session storage contract
96
- **Database Persistence**: Uses JDBC for durable session state storage
97
- **Event System Integration**: Automatically handles session cleanup via Grid events
98
- **Distributed Tracing**: Provides observability for database operations
99
- **Configuration Management**: Integrates with Grid's config system and command-line flags
100

101
## Capabilities
102

103
### Session Management
104

105
Core session storage and retrieval operations with database persistence.
106

107
```java { .api }
108
public boolean add(Session session);
109
public Session get(SessionId id) throws NoSuchSessionException;
110
public void remove(SessionId id);
111
public URI getUri(SessionId id) throws NoSuchSessionException;
112
public void removeByUri(URI sessionUri);
113
public boolean isReady();
114
public void close();
115
```
116

117
[Session Management](./session-management.md)
118

119
### Configuration and Setup
120

121
Database connection management and Grid configuration integration for JDBC session storage.
122

123
```java { .api }
124
public static SessionMap create(Config config);
125
public JdbcBackedSessionMap(Tracer tracer, Connection jdbcConnection, EventBus bus);
126
public Connection getJdbcConnection() throws SQLException;
127
public String getJdbcUrl();
128
public String getJdbcUser();
129
```
130

131
[Configuration](./configuration.md)
132

133
### Exception Handling
134

135
Custom exception types for JDBC session map error scenarios.
136

137
```java { .api }
138
public class JdbcException extends WebDriverException {
139
  public JdbcException();
140
  public JdbcException(String message);
141
  public JdbcException(Throwable cause);
142
  public JdbcException(String message, Throwable cause);
143
}
144
```
145

146
[Exception Handling](./exceptions.md)
147

148
## Types
149

150
```java { .api }
151
public class JdbcBackedSessionMap extends SessionMap implements Closeable {
152
  public JdbcBackedSessionMap(Tracer tracer, Connection jdbcConnection, EventBus bus);
153
  public static SessionMap create(Config config);
154
  public boolean add(Session session);
155
  public Session get(SessionId id) throws NoSuchSessionException;
156
  public void remove(SessionId id);
157
  public void removeByUri(URI sessionUri);
158
  public boolean isReady();
159
  public void close();
160
}
161

162
public class JdbcSessionMapOptions {
163
  public JdbcSessionMapOptions(Config config);
164
  public Connection getJdbcConnection() throws SQLException;
165
  public String getJdbcUrl();
166
  public String getJdbcUser();
167
}
168

169
public class JdbcSessionMapFlags implements HasRoles {
170
  public Set<Role> getRoles();
171
}
172

173
public class Session implements Serializable {
174
  public Session(SessionId id, URI uri, Capabilities stereotype, Capabilities capabilities, Instant startTime);
175
  public SessionId getId();
176
  public URI getUri();
177
  public Capabilities getStereotype();
178
  public Capabilities getCapabilities();
179
  public Instant getStartTime();
180
}
181

182
public class JdbcException extends WebDriverException {
183
  public JdbcException();
184
  public JdbcException(String message);
185
  public JdbcException(Throwable cause);
186
  public JdbcException(String message, Throwable cause);
187
}
188
```