0
# Session Management
1

2
Session management provides isolation and configuration for multiple concurrent clients connecting to the SQL Gateway. Each session maintains its own catalog context, configuration, and operation history.
3

4
## Capabilities
5

6
### SessionHandle
7

8
Unique identifier for sessions using UUID-based handles.
9

10
```java { .api }
11
/**
12
 * Session Handle that identifies a unique session
13
 */
14
public class SessionHandle {
15
    private final UUID identifier;
16
    
17
    /**
18
     * Create a new session handle with random UUID
19
     * @return New SessionHandle instance
20
     */
21
    public static SessionHandle create();
22
    
23
    /**
24
     * Create session handle with specific UUID
25
     * @param identifier UUID to use for the session
26
     */
27
    public SessionHandle(UUID identifier);
28
    
29
    /**
30
     * Get the UUID identifier for this session
31
     * @return UUID identifier
32
     */
33
    public UUID getIdentifier();
34
    
35
    @Override
36
    public boolean equals(Object o);
37
    
38
    @Override
39
    public int hashCode();
40
    
41
    @Override
42
    public String toString();
43
}
44
```
45

46
### SessionEnvironment
47

48
Environment configuration for initializing sessions with catalogs, modules, and settings.
49

50
```java { .api }
51
/**
52
 * Environment configuration for session initialization
53
 */
54
public class SessionEnvironment {
55
    /**
56
     * Get optional session name
57
     * @return Optional session name
58
     */
59
    public Optional<String> getSessionName();
60
    
61
    /**
62
     * Get endpoint version negotiated for this session
63
     * @return EndpointVersion for the session
64
     */
65
    public EndpointVersion getSessionEndpointVersion();
66
    
67
    /**
68
     * Get session configuration map
69
     * @return Map of configuration key-value pairs
70
     */
71
    public Map<String, String> getSessionConfig();
72
    
73
    /**
74
     * Get registered catalog creators
75
     * @return Map of catalog creators by name
76
     */
77
    public Map<String, CatalogCreator> getRegisteredCatalogCreators();
78
    
79
    /**
80
     * Get registered module creators in order
81
     * @return List of module creators
82
     */
83
    public List<ModuleCreator> getRegisteredModuleCreators();
84
    
85
    /**
86
     * Get default catalog name if specified
87
     * @return Optional default catalog name
88
     */
89
    public Optional<String> getDefaultCatalog();
90
    
91
    /**
92
     * Create new builder for SessionEnvironment
93
     * @return Builder instance
94
     */
95
    public static Builder newBuilder();
96
    
97
    /**
98
     * Builder for constructing SessionEnvironment instances
99
     */
100
    public static class Builder {
101
        /**
102
         * Set optional session name
103
         * @param sessionName Name for the session
104
         * @return Builder instance for chaining
105
         */
106
        public Builder setSessionName(String sessionName);
107
        
108
        /**
109
         * Set endpoint version for negotiation
110
         * @param endpointVersion Version to use
111
         * @return Builder instance for chaining
112
         */
113
        public Builder setSessionEndpointVersion(EndpointVersion endpointVersion);
114
        
115
        /**
116
         * Add configuration properties to the session
117
         * @param config Map of configuration properties
118
         * @return Builder instance for chaining
119
         */
120
        public Builder addSessionConfig(Map<String, String> config);
121
        
122
        /**
123
         * Add single configuration property
124
         * @param key Configuration key
125
         * @param value Configuration value
126
         * @return Builder instance for chaining
127
         */
128
        public Builder addSessionConfig(String key, String value);
129
        
130
        /**
131
         * Register catalog instance with name
132
         * @param name Catalog name
133
         * @param catalog Catalog instance
134
         * @return Builder instance for chaining
135
         */
136
        public Builder registerCatalog(String name, Catalog catalog);
137
        
138
        /**
139
         * Register catalog creator for lazy initialization
140
         * @param name Catalog name
141
         * @param creator CatalogCreator instance
142
         * @return Builder instance for chaining
143
         */
144
        public Builder registerCatalogCreator(String name, CatalogCreator creator);
145
        
146
        /**
147
         * Register module at head of module list
148
         * @param name Module name
149
         * @param module Module instance
150
         * @return Builder instance for chaining
151
         */
152
        public Builder registerModuleAtHead(String name, Module module);
153
        
154
        /**
155
         * Register module creator at head for lazy initialization
156
         * @param name Module name
157
         * @param creator ModuleCreator instance
158
         * @return Builder instance for chaining
159
         */
160
        public Builder registerModuleCreatorAtHead(String name, ModuleCreator creator);
161
        
162
        /**
163
         * Set default catalog name
164
         * @param catalogName Default catalog name
165
         * @return Builder instance for chaining
166
         */
167
        public Builder setDefaultCatalog(String catalogName);
168
        
169
        /**
170
         * Build the SessionEnvironment instance
171
         * @return Configured SessionEnvironment
172
         */
173
        public SessionEnvironment build();
174
    }
175
    
176
    /**
177
     * Interface for creating catalogs lazily
178
     */
179
    public interface CatalogCreator {
180
        /**
181
         * Create catalog instance
182
         * @return Catalog instance
183
         */
184
        Catalog create();
185
    }
186
    
187
    /**
188
     * Interface for creating modules lazily
189
     */
190
    public interface ModuleCreator {
191
        /**
192
         * Create module instance
193
         * @return Module instance
194
         */
195
        Module create();
196
    }
197
}
198
```
199

200
### EndpointVersion
201

202
Marker interface for endpoint version negotiation during session establishment.
203

204
```java { .api }
205
/**
206
 * Marker interface for endpoint versions
207
 */
208
public interface EndpointVersion {
209
    // Marker interface - implementations define specific version behavior
210
}
211
```
212

213
### SessionManager
214

215
Interface for managing session lifecycle and coordination.
216

217
```java { .api }
218
/**
219
 * Manages session lifecycle and coordination
220
 */
221
public interface SessionManager {
222
    /**
223
     * Start the session manager
224
     */
225
    void start();
226
    
227
    /**
228
     * Stop the session manager and clean up all sessions
229
     */
230
    void stop();
231
    
232
    /**
233
     * Create session manager with default context
234
     * @param defaultContext Default context for sessions
235
     * @return SessionManager instance
236
     */
237
    static SessionManager create(DefaultContext defaultContext);
238
}
239
```
240

241
### Session
242

243
Represents an individual session instance with context and state.
244

245
```java { .api }
246
/**
247
 * Represents a single session instance
248
 */
249
public class Session {
250
    /**
251
     * Get session handle
252
     * @return SessionHandle for this session
253
     */
254
    public SessionHandle getSessionHandle();
255
    
256
    /**
257
     * Get session context
258
     * @return SessionContext for this session
259
     */
260
    public SessionContext getSessionContext();
261
    
262
    /**
263
     * Check if session is alive
264
     * @return true if session is active
265
     */
266
    public boolean isAlive();
267
    
268
    /**
269
     * Touch session to update last access time
270
     */
271
    public void touch();
272
    
273
    /**
274
     * Close session and clean up resources
275
     */
276
    public void close();
277
}
278
```
279

280
## Usage Examples
281

282
### Basic Session Creation
283

284
```java
285
import org.apache.flink.table.gateway.api.session.SessionEnvironment;
286
import org.apache.flink.table.gateway.api.session.SessionHandle;
287

288
// Create session environment
289
SessionEnvironment environment = SessionEnvironment.newBuilder()
290
    .setSessionName("analytics-session")
291
    .addSessionConfig("execution.target", "remote")
292
    .addSessionConfig("parallelism.default", "4")
293
    .build();
294

295
// Open session through service
296
SqlGatewayService service = // ... get service instance
297
SessionHandle session = service.openSession(environment);
298

299
// Use session for operations
300
// ...
301

302
// Close when done
303
service.closeSession(session);
304
```
305

306
### Advanced Session Configuration
307

308
```java
309
import org.apache.flink.table.catalog.hive.HiveCatalog;
310
import org.apache.flink.table.module.hive.HiveModule;
311

312
// Create session with custom catalogs and modules
313
SessionEnvironment environment = SessionEnvironment.newBuilder()
314
    .setSessionName("data-processing")
315
    .addSessionConfig(Map.of(
316
        "execution.target", "yarn-per-job",
317
        "execution.savepoint.path", "hdfs://cluster/savepoints",
318
        "table.exec.resource.default-parallelism", "8"
319
    ))
320
    .registerCatalogCreator("hive", () -> new HiveCatalog(
321
        "hive", 
322
        "default", 
323
        "path/to/hive-conf"
324
    ))
325
    .registerModuleCreatorAtHead("hive", () -> new HiveModule("2.3.6"))
326
    .setDefaultCatalog("hive")
327
    .build();
328

329
SessionHandle session = service.openSession(environment);
330

331
// Session now has Hive catalog and module available
332
```
333

334
### Session Configuration Management
335

336
```java
337
// Get current session configuration
338
Map<String, String> config = service.getSessionConfig(session);
339
System.out.println("Current parallelism: " + config.get("parallelism.default"));
340

341
// Configure session with SQL statements
342
service.configureSession(session, "SET 'parallelism.default' = '16'", 10000L);
343
service.configureSession(session, "CREATE CATALOG my_catalog WITH (...)", 30000L);
344
service.configureSession(session, "USE CATALOG my_catalog", 5000L);
345

346
// Configuration is now updated for this session
347
```
348

349
### Session Isolation Example
350

351
```java
352
// Create multiple isolated sessions
353
SessionHandle session1 = service.openSession(
354
    SessionEnvironment.newBuilder()
355
        .setSessionName("batch-processing")
356
        .addSessionConfig("execution.runtime-mode", "BATCH")
357
        .build()
358
);
359

360
SessionHandle session2 = service.openSession(
361
    SessionEnvironment.newBuilder()
362
        .setSessionName("stream-processing")
363
        .addSessionConfig("execution.runtime-mode", "STREAMING")
364
        .addSessionConfig("execution.checkpointing.interval", "60s")
365
        .build()
366
);
367

368
// Each session has independent configuration and catalog context
369
// Operations in session1 don't affect session2
370
```