0
# CLI Services
1

2
Comprehensive CLI service implementation providing HiveServer2 compatibility with Spark SQL enhancements, including authentication, session management, and operation handling.
3

4
## Capabilities
5

6
### SparkSQLCLIService
7

8
Core CLI service that extends HiveServer2's CLIService with Spark SQL capabilities.
9

10
```scala { .api }
11
/**
12
 * Core CLI service implementation with Spark SQL integration
13
 * @param hiveServer The parent HiveServer2 instance
14
 * @param sqlContext The Spark SQL context for query execution
15
 */
16
class SparkSQLCLIService(hiveServer: HiveServer2, sqlContext: SQLContext) extends CLIService(hiveServer) {
17
  /**
18
   * Initialize the CLI service with Hive configuration
19
   * @param hiveConf Hive configuration object containing server settings
20
   */
21
  def init(hiveConf: HiveConf): Unit
22
  
23
  /**
24
   * Start the CLI service and all composite services
25
   */
26
  def start(): Unit
27
  
28
  /**
29
   * Get server information for a given session
30
   * @param sessionHandle Handle identifying the client session
31
   * @param getInfoType Type of information to retrieve
32
   * @return GetInfoValue containing the requested information
33
   */
34
  def getInfo(sessionHandle: SessionHandle, getInfoType: GetInfoType): GetInfoValue
35
}
36
```
37

38
**Usage Examples:**
39

40
```scala
41
import org.apache.spark.sql.hive.thriftserver.SparkSQLCLIService
42
import org.apache.hadoop.hive.conf.HiveConf
43
import org.apache.hive.service.server.HiveServer2
44

45
// Create and initialize the CLI service
46
val hiveServer = new HiveServer2()
47
val cliService = new SparkSQLCLIService(hiveServer, SparkSQLEnv.sqlContext)
48

49
// Initialize with configuration
50
val hiveConf = new HiveConf()
51
cliService.init(hiveConf)
52

53
// Start the service
54
cliService.start()
55
```
56

57
### Service Information Handling
58

59
The CLI service provides enhanced information handling specific to Spark SQL.
60

61
```scala { .api }
62
// Information types supported by getInfo()
63
import org.apache.hive.service.cli.GetInfoType
64

65
// Spark SQL specific information
66
GetInfoType.CLI_SERVER_NAME    // Returns "Spark SQL"
67
GetInfoType.CLI_DBMS_NAME      // Returns "Spark SQL" 
68
GetInfoType.CLI_DBMS_VER       // Returns Spark version
69
GetInfoType.CLI_ODBC_KEYWORDS  // Returns SQL keywords supported by Spark
70
```
71

72
**Usage Examples:**
73

74
```scala
75
import org.apache.hive.service.cli.{GetInfoType, SessionHandle}
76

77
// Get server information
78
val serverName = cliService.getInfo(sessionHandle, GetInfoType.CLI_SERVER_NAME)
79
println(s"Server: ${serverName.getStringValue()}")  // "Spark SQL"
80

81
val version = cliService.getInfo(sessionHandle, GetInfoType.CLI_DBMS_VER)
82
println(s"Version: ${version.getStringValue()}")    // "3.5.6"
83

84
val keywords = cliService.getInfo(sessionHandle, GetInfoType.CLI_ODBC_KEYWORDS)
85
println(s"Keywords: ${keywords.getStringValue()}")  // "SELECT,FROM,WHERE,..."
86
```
87

88
### Authentication Integration
89

90
The CLI service integrates with multiple authentication mechanisms.
91

92
```scala { .api }
93
// Authentication configuration in init()
94
// Kerberos authentication
95
hive.server2.authentication = "KERBEROS"
96
hive.server2.authentication.kerberos.principal = "spark/_HOST@REALM"
97
hive.server2.authentication.kerberos.keytab = "/etc/spark/spark.keytab"
98

99
// SPNEGO for HTTP transport
100
hive.server2.authentication.spnego.principal = "HTTP/_HOST@REALM"  
101
hive.server2.authentication.spnego.keytab = "/etc/spark/spnego.keytab"
102

103
// Custom authentication providers
104
hive.server2.authentication = "CUSTOM"
105
hive.server2.custom.authentication.class = "com.example.MyAuthProvider"
106
```
107

108
### ReflectedCompositeService Trait
109

110
Utility trait providing reflection-based service management for HiveServer2 compatibility.
111

112
```scala { .api }
113
/**
114
 * Trait providing composite service functionality via reflection
115
 * Used to maintain compatibility with HiveServer2 internal APIs
116
 */
117
trait ReflectedCompositeService { this: AbstractService =>
118
  /**
119
   * Initialize all composite services with the given configuration
120
   * @param hiveConf Hive configuration object
121
   */
122
  def initCompositeService(hiveConf: HiveConf): Unit
123
  
124
  /**
125
   * Start all composite services in order
126
   */
127
  def startCompositeService(): Unit
128
}
129
```
130

131
### ICLIService Interface
132

133
The core interface defining all CLI service operations, implemented by SparkSQLCLIService.
134

135
```java { .api }
136
/**
137
 * Core CLI service interface defining all thrift server operations
138
 */
139
public interface ICLIService {
140
  /**
141
   * Open a new client session
142
   * @param username Client username
143
   * @param password Client password  
144
   * @param configuration Session configuration parameters
145
   * @return SessionHandle identifying the new session
146
   */
147
  SessionHandle openSession(String username, String password, Map<String, String> configuration) throws HiveSQLException;
148
  
149
  /**
150
   * Open a session with user impersonation
151
   * @param username Client username
152
   * @param password Client password
153
   * @param configuration Session configuration parameters
154
   * @param delegationToken Delegation token for authentication
155
   * @return SessionHandle identifying the new session
156
   */
157
  SessionHandle openSessionWithImpersonation(String username, String password, Map<String, String> configuration, String delegationToken) throws HiveSQLException;
158
  
159
  /**
160
   * Close an existing session
161
   * @param sessionHandle Handle identifying the session to close
162
   */
163
  void closeSession(SessionHandle sessionHandle) throws HiveSQLException;
164
  
165
  /**
166
   * Get server or session information
167
   * @param sessionHandle Session handle
168
   * @param infoType Type of information to retrieve
169
   * @return GetInfoValue containing the requested information
170
   */
171
  GetInfoValue getInfo(SessionHandle sessionHandle, GetInfoType infoType) throws HiveSQLException;
172
  
173
  /**
174
   * Execute a SQL statement synchronously
175
   * @param sessionHandle Session handle
176
   * @param statement SQL statement to execute
177
   * @param confOverlay Configuration overrides for this statement
178
   * @return OperationHandle for the execution operation
179
   */
180
  OperationHandle executeStatement(SessionHandle sessionHandle, String statement, Map<String, String> confOverlay) throws HiveSQLException;
181
  
182
  /**
183
   * Execute a SQL statement asynchronously
184
   * @param sessionHandle Session handle
185
   * @param statement SQL statement to execute  
186
   * @param confOverlay Configuration overrides for this statement
187
   * @return OperationHandle for the execution operation
188
   */
189
  OperationHandle executeStatementAsync(SessionHandle sessionHandle, String statement, Map<String, String> confOverlay) throws HiveSQLException;
190
}
191
```
192

193
### Service Lifecycle Management
194

195
The CLI service manages the complete lifecycle of server components.
196

197
```scala { .api }
198
// Service states (from Apache Hive Service interface)
199
enum SERVICE_STATE {
200
  NOTINITED,    // Service not initialized
201
  INITED,       // Service initialized but not started  
202
  STARTED,      // Service started and running
203
  STOPPED       // Service stopped
204
}
205

206
// Service lifecycle methods
207
abstract class AbstractService {
208
  def init(conf: Configuration): Unit
209
  def start(): Unit  
210
  def stop(): Unit
211
  def getServiceState(): SERVICE_STATE
212
}
213
```
214

215
**Usage Examples:**
216

217
```scala
218
// Check service state
219
val state = cliService.getServiceState()
220
state match {
221
  case SERVICE_STATE.STARTED => println("Service is running")
222
  case SERVICE_STATE.STOPPED => println("Service is stopped")
223
  case _ => println(s"Service state: $state")
224
}
225

226
// Proper service shutdown
227
try {
228
  if (cliService.getServiceState() == SERVICE_STATE.STARTED) {
229
    cliService.stop()
230
  }
231
} catch {
232
  case e: Exception => 
233
    println(s"Error stopping CLI service: ${e.getMessage}")
234
}
235
```
236

237
### Error Handling
238

239
The CLI service provides comprehensive error handling for all operations.
240

241
```java { .api }
242
/**
243
 * Base exception for all CLI service errors
244
 */
245
class HiveSQLException extends SQLException {
246
  public HiveSQLException(String reason, String sqlState, int vendorCode, Throwable cause)
247
  public String getSqlState()
248
  public int getVendorCode()
249
}
250

251
/**
252
 * Service-level exceptions
253
 */
254
class ServiceException extends Exception {
255
  public ServiceException(String message)
256
  public ServiceException(String message, Throwable cause)
257
}
258
```
259

260
**Common Error Scenarios:**
261

262
```scala
263
import org.apache.hive.service.cli.HiveSQLException
264

265
try {
266
  val sessionHandle = cliService.openSession("user", "pass", Map.empty.asJava)
267
  // Use session...
268
} catch {
269
  case e: HiveSQLException =>
270
    println(s"SQL Error: ${e.getMessage}, State: ${e.getSqlState}")
271
  case e: ServiceException =>
272
    println(s"Service Error: ${e.getMessage}")
273
}
274
```