0
# Session Management
1

2
Core session storage and retrieval operations with database persistence for Selenium Grid.
3

4
## Capabilities
5

6
### Add Session
7

8
Adds a WebDriver session to the database for distributed storage.
9

10
```java { .api }
11
/**
12
 * Adds a session to the database
13
 * @param session The session to store, containing ID, URI, capabilities, and metadata
14
 * @return true if the session was successfully added, false otherwise
15
 * @throws JdbcException if database operation fails
16
 */
17
public boolean add(Session session);
18
```
19

20
**Usage Example:**
21

22
```java
23
import org.openqa.selenium.grid.data.Session;
24
import org.openqa.selenium.remote.SessionId;
25
import org.openqa.selenium.ImmutableCapabilities;
26
import java.net.URI;
27
import java.time.Instant;
28

29
// Create a session object
30
Session session = new Session(
31
    new SessionId("session-12345"),
32
    URI.create("http://node1.grid.com:5555"),
33
    new ImmutableCapabilities("browserName", "chrome", "version", "91.0"),
34
    new ImmutableCapabilities("browserName", "chrome", "platformName", "linux"),
35
    Instant.now()
36
);
37

38
// Add to session map
39
boolean added = sessionMap.add(session);
40
if (added) {
41
    System.out.println("Session successfully stored in database");
42
}
43
```
44

45
### Get Session
46

47
Retrieves a session from the database by its session ID.
48

49
```java { .api }
50
/**
51
 * Retrieves a session from the database
52
 * @param id The session ID to look up
53
 * @return The complete session object with all metadata
54
 * @throws NoSuchSessionException if the session doesn't exist
55
 * @throws JdbcException if database operation fails
56
 */
57
public Session get(SessionId id) throws NoSuchSessionException;
58
```
59

60
**Usage Example:**
61

62
```java
63
import org.openqa.selenium.NoSuchSessionException;
64

65
try {
66
    SessionId sessionId = new SessionId("session-12345");
67
    Session session = sessionMap.get(sessionId);
68
    
69
    System.out.println("Session URI: " + session.getUri());
70
    System.out.println("Session capabilities: " + session.getCapabilities());
71
    System.out.println("Session start time: " + session.getStartTime());
72
} catch (NoSuchSessionException e) {
73
    System.err.println("Session not found: " + e.getMessage());
74
}
75
```
76

77
### Remove Session
78

79
Removes a session from the database by its session ID.
80

81
```java { .api }
82
/**
83
 * Removes a session from the database
84
 * @param id The session ID to remove
85
 * @throws JdbcException if database operation fails
86
 * Note: Does not throw if session doesn't exist - removal is idempotent
87
 */
88
public void remove(SessionId id);
89
```
90

91
**Usage Example:**
92

93
```java
94
SessionId sessionId = new SessionId("session-12345");
95
sessionMap.remove(sessionId);
96
System.out.println("Session removed from database");
97
```
98

99
### Get Session URI
100

101
Retrieves just the URI where a session is running, without the full session object.
102

103
```java { .api }
104
/**
105
 * Gets the URI where a session is running
106
 * @param id The session ID to look up
107
 * @return The URI where the session is hosted
108
 * @throws NoSuchSessionException if the session doesn't exist
109
 */
110
public URI getUri(SessionId id) throws NoSuchSessionException;
111
```
112

113
**Usage Example:**
114

115
```java
116
try {
117
    SessionId sessionId = new SessionId("session-12345");
118
    URI nodeUri = sessionMap.getUri(sessionId);
119
    System.out.println("Session is running on: " + nodeUri);
120
} catch (NoSuchSessionException e) {
121
    System.err.println("Session not found: " + e.getMessage());
122
}
123
```
124

125
### Advanced Session Operations
126

127
#### Remove by URI
128

129
Removes all sessions associated with a specific node URI. Used for cleanup when nodes are removed or restarted.
130

131
```java { .api }
132
/**
133
 * Removes all sessions running on a specific node URI
134
 * @param sessionUri The URI of the node whose sessions should be removed
135
 * @throws JdbcException if database operation fails
136
 */
137
public void removeByUri(URI sessionUri);
138
```
139

140
**Usage Example:**
141

142
```java
143
// Remove all sessions from a node that has gone offline
144
URI nodeUri = URI.create("http://node1.grid.com:5555");
145
((JdbcBackedSessionMap) sessionMap).removeByUri(nodeUri);
146
System.out.println("All sessions from node removed");
147
```
148

149
#### Check Readiness
150

151
Verifies that the database connection is active and ready to handle operations.
152

153
```java { .api }
154
/**
155
 * Checks if the session map is ready to handle operations
156
 * @return true if the database connection is active, false otherwise
157
 */
158
public boolean isReady();
159
```
160

161
**Usage Example:**
162

163
```java
164
if (sessionMap.isReady()) {
165
    System.out.println("Session map is ready for operations");
166
    // Proceed with session operations
167
} else {
168
    System.err.println("Session map is not ready - check database connection");
169
}
170
```
171

172
#### Close Connection
173

174
Closes the database connection when the session map is no longer needed.
175

176
```java { .api }
177
/**
178
 * Closes the database connection
179
 * Implements Closeable interface for resource management
180
 */
181
public void close();
182
```
183

184
**Usage Example:**
185

186
```java
187
// Using try-with-resources for automatic cleanup
188
try (JdbcBackedSessionMap sessionMap = new JdbcBackedSessionMap(tracer, connection, bus)) {
189
    // Use the session map
190
    sessionMap.add(session);
191
    Session retrieved = sessionMap.get(session.getId());
192
} // Connection automatically closed here
193

194
// Or manual cleanup
195
sessionMap.close();
196
```
197

198
## Event Bus Integration
199

200
The JDBC session map automatically integrates with Selenium Grid's event system for cleanup operations:
201

202
- **SessionClosedEvent**: Automatically removes sessions when they are closed
203
- **NodeRemovedEvent**: Removes all sessions from nodes that are removed from the grid
204
- **NodeRestartedEvent**: Cleans up sessions from nodes that have restarted
205

206
This integration ensures that the database doesn't accumulate stale session data as the grid operates.
207

208
## Database Schema
209

210
The session map expects a database table with the following structure:
211

212
```sql
213
CREATE TABLE sessions_map (
214
    session_ids VARCHAR(255),
215
    session_uri TEXT,
216
    session_stereotype TEXT,
217
    session_caps TEXT,
218
    session_start VARCHAR(255)
219
);
220
```
221

222
Session data is stored as JSON-serialized strings in the appropriate columns, allowing the full session state to be reconstructed when retrieved.