0
# Session Management
1

2
Client session lifecycle management with isolation and resource cleanup. Manages individual client connections to the Spark Hive Thrift Server.
3

4
## Capabilities
5

6
### Session Manager
7

8
Core session management functionality for handling client connections.
9

10
```scala { .api }
11
private[hive] class SparkSQLSessionManager(
12
  hiveServer: HiveServer2,
13
  hiveContext: HiveContext
14
) extends SessionManager {
15
  
16
  /**
17
   * Open a new client session with isolated execution context
18
   * @param protocol Hive protocol version
19
   * @param username Client username
20
   * @param password Client password (if authentication enabled)
21
   * @param ipAddress Client IP address
22
   * @param sessionConf Session-specific configuration
23
   * @param withImpersonation Whether to enable user impersonation
24
   * @param delegationToken Delegation token for secure clusters
25
   * @return SessionHandle for managing the session
26
   */
27
  override def openSession(
28
    protocol: TProtocolVersion,
29
    username: String,
30
    password: String,
31
    ipAddress: String,
32
    sessionConf: JMap[String, String],
33
    withImpersonation: Boolean,
34
    delegationToken: String
35
  ): SessionHandle
36
  
37
  /**
38
   * Close a client session and clean up associated resources
39
   * @param sessionHandle Handle of the session to close
40
   */
41
  override def closeSession(sessionHandle: SessionHandle): Unit
42
}
43
```
44

45
### Session Isolation
46

47
Each client session receives an isolated execution environment:
48

49
**Per-Session Context:**
50
- Dedicated HiveContext instance for query execution
51
- Isolated SQL configuration namespace
52
- Separate Spark job group for query tracking
53
- Independent result caching and temporary views
54

55
**Resource Management:**
56
- Automatic cleanup of temporary tables and views
57
- Session-scoped UDF registration
58
- Isolated Spark SQL configuration changes
59
- Per-session query history and statistics
60

61
### Session Lifecycle
62

63
**Session Creation Process:**
64
1. Client connection authentication (if enabled)
65
2. Session handle allocation and registration
66
3. Isolated HiveContext creation from template
67
4. Configuration application from session parameters
68
5. Event notification to monitoring listeners
69
6. Return session handle to client
70

71
**Session Termination Process:**
72
1. Cancel any running operations for the session
73
2. Clean up temporary tables and cached data
74
3. Close database connections and file handles
75
4. Update session statistics and duration
76
5. Event notification to monitoring listeners
77
6. Release session handle and resources
78

79
### Session Configuration
80

81
Sessions support configuration customization at creation time:
82

83
```scala
84
// Example session configuration parameters
85
val sessionConf = Map(
86
  "hive.exec.dynamic.partition" -> "true",
87
  "spark.sql.adaptive.enabled" -> "true",
88
  "spark.sql.adaptive.coalescePartitions.enabled" -> "true",
89
  "mapred.job.queue.name" -> "priority-queue"
90
).asJava
91

92
val sessionHandle = sessionManager.openSession(
93
  protocol = TProtocolVersion.HIVE_CLI_SERVICE_PROTOCOL_V8,
94
  username = "user1",
95
  password = "",
96
  ipAddress = "192.168.1.100",
97
  sessionConf = sessionConf,
98
  withImpersonation = false,
99
  delegationToken = null
100
)
101
```
102

103
### Authentication Integration
104

105
The session manager integrates with Hive's authentication framework:
106

107
**Security Modes:**
108
- **NONE**: No authentication required
109
- **KERBEROS**: Kerberos ticket-based authentication
110
- **LDAP**: LDAP username/password authentication
111
- **CUSTOM**: Custom authentication provider
112

113
**User Impersonation:**
114
When enabled, sessions can execute queries as different users:
115

116
```scala
117
// Enable impersonation for multi-tenant scenarios
118
val sessionHandle = sessionManager.openSession(
119
  protocol = TProtocolVersion.HIVE_CLI_SERVICE_PROTOCOL_V8,
120
  username = "service-account",
121
  password = "password",
122
  ipAddress = clientIP,
123
  sessionConf = Map.empty.asJava,
124
  withImpersonation = true,  // Enable impersonation
125
  delegationToken = userToken
126
)
127
```
128

129
### Session Monitoring
130

131
Sessions are tracked by the HiveThriftServer2Listener for monitoring:
132

133
```scala
134
// Session creation event
135
listener.onSessionCreated(
136
  ip = ipAddress,
137
  sessionId = sessionHandle.getHandleIdentifier.toString,
138
  userName = username
139
)
140

141
// Session closure event  
142
listener.onSessionClosed(sessionHandle.getHandleIdentifier.toString)
143
```
144

145
**Monitored Metrics:**
146
- Session duration and activity
147
- Number of executed statements per session
148
- Session state (active/idle/closed)
149
- Resource usage per session
150
- Error rates and failure patterns
151

152
### Concurrent Session Support
153

154
The session manager supports multiple concurrent client sessions:
155

156
**Thread Safety:**
157
- Session creation/destruction is thread-safe
158
- Per-session contexts are isolated from each other
159
- Shared resources (like metastore) use appropriate locking
160

161
**Resource Limits:**
162
- Configurable maximum number of concurrent sessions
163
- Session timeout for idle connections
164
- Memory limits per session context
165
- Query execution timeouts
166

167
### Session State Management
168

169
Sessions maintain state throughout their lifecycle:
170

171
```scala
172
// Session states tracked by the system
173
enum SessionState {
174
  ACTIVE,    // Session is actively processing requests
175
  IDLE,      // Session is connected but not processing
176
  TIMEOUT,   // Session has exceeded idle timeout
177
  CLOSED,    // Session has been explicitly closed
178
  ERROR      // Session encountered fatal error
179
}
180
```
181

182
### Integration with Operation Management
183

184
Sessions coordinate with the operation manager for query execution:
185

186
```scala
187
// Operations are scoped to sessions
188
class SparkSQLOperationManager {
189
  val sessionToActivePool: Map[SessionHandle, String]
190
  val sessionToContexts: Map[SessionHandle, HiveContext]
191
  
192
  def newExecuteStatementOperation(
193
    parentSession: HiveSession,
194
    statement: String,
195
    confOverlay: JMap[String, String],
196
    runInBackground: Boolean
197
  ): ExecuteStatementOperation
198
}
199
```
200

201
### Error Handling
202

203
Comprehensive error handling for session operations:
204

205
**Session Creation Errors:**
206
- Authentication failures
207
- Authorization issues
208
- Resource exhaustion (max sessions reached)
209
- Configuration validation errors
210

211
**Session Runtime Errors:**
212
- Network disconnections
213
- Query execution failures
214
- Resource cleanup failures
215
- Timeout handling
216

217
**Error Recovery:**
218
```scala
219
try {
220
  val sessionHandle = sessionManager.openSession(...)
221
  // Use session
222
} catch {
223
  case e: HiveSQLException =>
224
    log.error(s"Failed to create session: ${e.getMessage}")
225
    throw e
226
  case e: SQLException =>
227
    log.error(s"Database error during session creation: ${e.getMessage}")
228
    throw new HiveSQLException(e)
229
}
230
```
231

232
### Best Practices
233

234
1. **Resource Cleanup**: Always close sessions explicitly to avoid resource leaks
235
2. **Configuration**: Apply session-specific configurations at creation time
236
3. **Monitoring**: Enable session tracking for operational visibility
237
4. **Timeouts**: Configure appropriate idle timeouts for your use case
238
5. **Security**: Use authentication and impersonation appropriately for your security model
239
6. **Error Handling**: Implement proper retry logic for transient session failures