org.apache.samza.sql.client.interfaces

Interface SqlExecutor

All Known Implementing Classes:

SamzaExecutor

public interface SqlExecutor

Conventions:

Each execution (both query and non-query shall return an non-negative execution ID(execId). Negative execution IDs are reserved for error handling.

User shall be able to query the status of an execution even after it's finished, so the executor shall keep record of all the execution unless being asked to remove them ( when removeExecution is called.)

IMPORTANT: An executor shall support two ways of supplying data: 1. Say user selects profiles of users who visited LinkedIn in the last 5 mins. There could be millions of rows, but the UI only need to show a small fraction. That's retrieveQueryResult, accepting a row range (startRow and endRow). Note that UI may ask for the same data over and over, like when user switches from page 1 to page 2 and data stream changes at the same time, the two pages may actually have overlapped or even same data.

2. Say user wants to see clicks on a LinkedIn page of certain person from now on. In this mode consumeQueryResult shall be used. UI can keep asking for new rows, and once the rows are consumed, it's no longer necessary for the executor to keep them. If lots of rows come in, the UI may be only interested in the last certain rows (as it's in a logview mode), so all data older can be dropped.

Method Summary

Modifier and Type	Method and Description
java.util.List<java.lang.String[]>	consumeQueryResult(ExecutionContext context, int startRow, int endRow) Consumes rows from query result.
NonQueryResult	executeNonQuery(ExecutionContext context, java.io.File file) Executes all the NON-QUERY statements in the sqlFile.
NonQueryResult	executeNonQuery(ExecutionContext context, java.util.List<java.lang.String> statements)
QueryResult	executeQuery(ExecutionContext context, java.lang.String statement)
EnvironmentVariableHandler	getEnvironmentVariableHandler()
int	getRowCount()
org.apache.samza.sql.schema.SqlSchema	getTableSchema(ExecutionContext context, java.lang.String tableName)
java.lang.String	getVersion() Gets the version of this executor.
java.util.List<SqlFunction>	listFunctions(ExecutionContext context)
java.util.List<java.lang.String>	listTables(ExecutionContext context)
ExecutionStatus	queryExecutionStatus(int execId)
void	removeExecution(ExecutionContext context, int exeId) Removing an ongoing execution shall result in an error.
java.util.List<java.lang.String[]>	retrieveQueryResult(ExecutionContext context, int startRow, int endRow) Row starts at 0.
void	start(ExecutionContext context) SqlExecutor shall be ready to accept all other calls after start() is called.
void	stop(ExecutionContext context) Indicates no further calls will be made thus it's safe for the executor to clean up.
void	stopExecution(ExecutionContext context, int exeId)

Method Detail

start

void start(ExecutionContext context)
    throws ExecutorException

SqlExecutor shall be ready to accept all other calls after start() is called. However, it shall NOT store the ExecutionContext for future use, as each call will be given an ExecutionContext which may differ from this one.

Parameters:

context - The ExecutionContext at the time of the call.

Throws:

ExecutorException - if the Executor encounters an error.

stop

void stop(ExecutionContext context)
   throws ExecutorException

Indicates no further calls will be made thus it's safe for the executor to clean up.

Parameters:

context - The ExecutionContext at the time of the call.

Throws:

ExecutorException - if the Executor encounters an error.

getEnvironmentVariableHandler

EnvironmentVariableHandler getEnvironmentVariableHandler()

Returns:

An EnvironmentVariableHandler that handles executor specific environment variables

listTables

java.util.List<java.lang.String> listTables(ExecutionContext context)
                                     throws ExecutorException

Parameters:

context - The ExecutionContext at the time of the call.

Returns:

A list of table names. Could be empty.

Throws:

ExecutorException - if the Executor encounters an error.

getTableSchema

org.apache.samza.sql.schema.SqlSchema getTableSchema(ExecutionContext context,
                                                     java.lang.String tableName)
                                              throws ExecutorException

Parameters:

context - The ExecutionContext at the time of the call.

tableName - Name of the table to get the schema for.

Returns:

Schema of the table.

Throws:

ExecutorException - if the Executor encounters an error.

executeQuery

QueryResult executeQuery(ExecutionContext context,
                         java.lang.String statement)
                  throws ExecutorException

Parameters:

context - The ExecutionContext at the time of the call.

statement - statement to execute

Returns:

The query result.

Throws:

ExecutorException - if the Executor encounters an error.

getRowCount

int getRowCount()
         throws ExecutorException

Returns:

how many rows available for reading.

Throws:

ExecutorException - if the Executor encounters an error.

retrieveQueryResult

java.util.List<java.lang.String[]> retrieveQueryResult(ExecutionContext context,
                                                       int startRow,
                                                       int endRow)
                                                throws ExecutorException

Row starts at 0. Executor shall keep the data retrieved. For now we get strings for display but we might want strong typed values.

Parameters:

context - The ExecutionContext at the time of the call.

startRow - Start row index (inclusive)

endRow - End row index (inclusive)

Returns:

A list of row data represented by a String array.

Throws:

ExecutorException - if the Executor encounters an error.

consumeQueryResult

java.util.List<java.lang.String[]> consumeQueryResult(ExecutionContext context,
                                                      int startRow,
                                                      int endRow)
                                               throws ExecutorException

Consumes rows from query result. Executor shall drop them, as "consume" indicates. ALL data before endRow (inclusive, including data before startRow) shall be deleted.

Parameters:

context - The ExecutionContext at the time of the call.

startRow - Start row index (inclusive)

endRow - End row index (inclusive)

Returns:

available data between startRow and endRow (both are inclusive)

Throws:

ExecutorException - if the Executor encounters an error.

executeNonQuery

NonQueryResult executeNonQuery(ExecutionContext context,
                               java.io.File file)
                        throws ExecutorException

Executes all the NON-QUERY statements in the sqlFile. Query statements are ignored as it won't make sense.

Parameters:

context - The ExecutionContext at the time of the call.

file - A File object to read statements from.

Returns:

Execution result.

Throws:

ExecutorException - if the Executor encounters an error.

executeNonQuery

NonQueryResult executeNonQuery(ExecutionContext context,
                               java.util.List<java.lang.String> statements)
                        throws ExecutorException

Parameters:

context - The ExecutionContext at the time of the call.

statements - A list of non-query sql statements.

Returns:

Execution result.

Throws:

ExecutorException - if the Executor encounters an error.

stopExecution

void stopExecution(ExecutionContext context,
                   int exeId)
            throws ExecutorException

Parameters:

context - The ExecutionContext at the time of the call.

exeId - Execution ID.

Throws:

ExecutorException - if the Executor encounters an error.

removeExecution

void removeExecution(ExecutionContext context,
                     int exeId)
              throws ExecutorException

Removing an ongoing execution shall result in an error. Stop it first.

Parameters:

context - The ExecutionContext at the time of the call

exeId - Execution ID.

Throws:

ExecutorException - if the Executor encounters an error.

queryExecutionStatus

ExecutionStatus queryExecutionStatus(int execId)
                              throws ExecutorException

Parameters:

execId - Execution ID.

Returns:

ExecutionStatus.

Throws:

ExecutorException - if the Executor encounters an error.

listFunctions

java.util.List<SqlFunction> listFunctions(ExecutionContext context)
                                   throws ExecutorException

Parameters:

context - The ExecutionContext at the time of the call.

Returns:

A list of SqlFunction.

Throws:

ExecutorException - if the Executor encounters an error.

getVersion

java.lang.String getVersion()

Gets the version of this executor.

Returns:

A String representing the version of the executor. This function does NOT throw an ExecutorException as the caller has nothing to do to "recover" if the function fails.