Status

Current state: [ DRAFTING ]DISCUSS

Discussion thread: 

JIRA: 

Released: 

Problem

Motivation

...

Samza SQL users have long been asking for a one stop shell, in which SQL statements and SQL files can be executed interactively. The requirement can be summarized as following:

• An interactive command shell

• Execute SQL queries and non-queries, show tables, functions, schema, etc.

• Execute SQL files

• Set environment variables interactively and/or via configuration file to configure behavior of shell

• Command editing, history, highlight and auto-completion

• Display SQL query in a streaming friendly way

• List status of submitted non-query SQL statements and be able to stop them

• Apart from Samza SQL, support other streaming SQLs and data sources by letting user implement their own plugins

Proposed Changes

Choice of Programming Language and Libraries

Any shell is essentially a REPL (Repeat-Evaluate-Print Loop), yet any non-trivial one is much more than that. Features like highlighting, history, command line editing, auto completion and rich data presentation require the capability of full control of the terminal. Terminal programming is a messy area, however, with the complexity coming from the long history and the vast variety of terminal types and operating systems. C/C++ is ideal for terminal IO programming, but for easier interoperation with data sources and other systems, Java is chosen.

Using Java to directly control the terminal is a lot of work. For example, to use the alternate screen and restore the previous screen we need to write code like this:

System.out.print(“\e[?1049h"); // tput smcup
System.out.print("\e[?1049l"); // tput rmcup

Which is neither pretty nor platform independent. Library Lanterna offers a Java style abstraction and solves the platform dependency problem. However, Lanterna is a very low level API; there’s still too much work. For example, for features like highlighting and auto completion, we need to use the non-canonical mode of the terminal, in which in order to process the simple user input of backspace we need to move the cursor, print a space, and move the cursor again.

The final library chosen is higher level one, Jline 3.8.2. Though knowledge of terminal programming is still necessary, Jline saves a lot of work. The mysterious code above now becomes:

terminal.puts(InfoCmp.Capability.enter_ca_mode); // tput smcup
terminal.puts(InfoCmp.Capability.exit_ca_mode); // tput rmcup

Public Interfaces

Implementation and Test Plan

...