tap

Class ADQLExecutor

java.lang.Object

tap.ADQLExecutor

public class ADQLExecutor
extends java.lang.Object

Let process completely an ADQL query.

Thus, this class aims to apply the following actions (in the given order):

1. Upload the user tables, if any
2. Parse the ADQL query (and so, transform it in an object tree)
3. Execute it in the "database"
4. Format and write the result
5. Drop all uploaded tables from the "database"

Job execution mode

This executor is able to process queries coming from a synchronous job (the result must be written directly in the HTTP response) and from an asynchronous job (the result must be written, generally, in a file). Two start(...) functions let deal with the differences between the two job execution modes: start(AsyncThread) for asynchronous jobs and start(Thread, String, TAPParameters, HttpServletResponse) for synchronous jobs.

Input/Output formats

Uploaded tables must be provided in VOTable format.

Query results must be formatted in the format specified by the user in the job parameters. A corresponding formatter (OutputFormat) is asked to the description of the TAP service (ServiceConnection). If none can be found, VOTable will be chosen by default.

Executor customization

It is totally possible to customize some parts of the ADQL query processing. However, the main algorithm must remain the same and is implemented by start(). This function is final, like start(AsyncThread) and start(Thread, String, TAPParameters, HttpServletResponse), which are just preparing the execution for start() in function of the job execution mode (asynchronous or synchronous).

Note: start() is using the Template Method Design Pattern: it defines the skeleton/algorithm of the processing, and defers some steps to other functions.

So, you are able to customize almost all individual steps of the ADQL query processing: parseADQL(), executeADQL(ADQLQuery) and writeResult(TableIterator, OutputFormat, OutputStream).

Note: Note that the formatting of the result is done by an OutputFormat and that the executor is just calling the appropriate function of the formatter.

There is no way in this executor to customize the upload. However, it does not mean it can not be customized. Indeed you can do it easily by extending Uploader and by providing the new class inside your TAPFactory implementation (see TAPFactory.createUploader(DBConnection)).

Version:

2.3 (03/2019)

Author:

Grégory Mantelet (CDS;ARI)

Field Summary

Fields

Modifier and Type	Field and Description
protected TAPLog	logger The logger to use.
protected TAPExecutionReport	report The execution report to fill gradually while the processing of the query.
protected javax.servlet.http.HttpServletResponse	response The HTTP response in which the query execution must be written.
protected ServiceConnection	service Description of the current TAP service.
protected TAPParameters	tapParams List of all TAP parameters needed for the query execution (and particularly the ADQL query itself).
protected java.lang.Thread	thread The thread which is using this executor.
protected TAPSchema	uploadSchema Description of the ADQL schema containing all the tables uploaded by the user for this specific query execution.

Constructor Summary

Constructors

Constructor and Description
ADQLExecutor(ServiceConnection service) Build an ADQLExecutor.

Method Summary

Modifier and Type	Method and Description
void	cancelQuery() Cancel the current SQL query execution or result set fetching if any is currently running.
protected void	dropUploadedTables() Drop all tables uploaded by the user from the database.
protected TableIterator	executeADQL(ADQLQuery adql) Execute in "database" the given object representation of an ADQL query.
TAPExecutionReport	getExecReport() Get the report of the query execution.
protected OutputFormat	getFormatter() Get the object to use in order to write the query result in the appropriate format (either the asked one, or else VOTable).
TAPLog	getLogger() Get the logger used by this executor.
void	initDBConnection(java.lang.String jobID) Create the database connection required for the ADQL execution.
protected ADQLQuery	parseADQL() Parse the ADQL query provided in the parameters by the user.
protected TAPExecutionReport	start() Process the ADQL query.
TAPExecutionReport	start(AsyncThread thread) Start the asynchronous processing of the ADQL query.
TAPExecutionReport	start(java.lang.Thread thread, java.lang.String jobId, TAPParameters params, javax.servlet.http.HttpServletResponse response) Start the synchronous processing of the ADQL query.
protected void	writeResult(TableIterator queryResult) Write the given query result into the appropriate format in the appropriate output (HTTP response for a synchronous execution, otherwise a file or any output provided by UWS).
protected void	writeResult(TableIterator queryResult, OutputFormat formatter, java.io.OutputStream output) Format and write the given result in the given output with the given formatter.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

service

protected final ServiceConnection service

Description of the current TAP service.

logger

protected final TAPLog logger

The logger to use.

thread

protected java.lang.Thread thread

The thread which is using this executor.

tapParams

protected TAPParameters tapParams

List of all TAP parameters needed for the query execution (and particularly the ADQL query itself).

uploadSchema

protected TAPSchema uploadSchema

Description of the ADQL schema containing all the tables uploaded by the user for this specific query execution. Note: This attribute is NULL before calling one of the start(...) function. It MAY be NULL also after if no table has been uploaded.

response

protected javax.servlet.http.HttpServletResponse response

The HTTP response in which the query execution must be written. This attribute is NULL if the execution is asynchronous.

report

protected TAPExecutionReport report

The execution report to fill gradually while the processing of the query. Note: This attribute is NULL before calling one of the start(...) function, but it will never be after this call.

Constructor Detail

ADQLExecutor

public ADQLExecutor(ServiceConnection service)

Build an ADQLExecutor.

Parameters:

service - The description of the TAP service.

Method Detail

getLogger

public final TAPLog getLogger()

Get the logger used by this executor.

Returns:

The used logger.

getExecReport

public final TAPExecutionReport getExecReport()

Get the report of the query execution. It helps indicating the execution progression and the duration of each step.

Note: Before starting the execution (= before the call of a "start(...)" function), this function will return NULL. It is set when the query processing starts and remains not NULL after that (even when the execution is finished).

Returns:

The execution report.

getFormatter

protected OutputFormat getFormatter()
                             throws TAPException

Get the object to use in order to write the query result in the appropriate format (either the asked one, or else VOTable).

Returns:

The appropriate result formatter to use. Can not be NULL!

Throws:

TAPException - If no format corresponds to the asked one and if no default format (for VOTable) can be found.

See Also:

ServiceConnection.getOutputFormat(String)

start

public final TAPExecutionReport start(AsyncThread thread)
                               throws UWSException,
                                      java.lang.InterruptedException

Start the asynchronous processing of the ADQL query.

This function initialize the execution report, get the execution parameters (including the query to process) and then call start().

Parameters:

thread - The asynchronous thread which asks the query processing.

Returns:

The resulting execution report.

Throws:

UWSException - If any error occurs while executing the ADQL query.

java.lang.InterruptedException - If the job has been interrupted (by the user or a time-out).

See Also:

start()

initDBConnection

public final void initDBConnection(java.lang.String jobID)
                            throws TAPException

Create the database connection required for the ADQL execution.

Note: This function has no effect if the DB connection already exists.

Parameters:

jobID - ID of the job which will be executed by this ADQLExecutor. This ID will be the database connection ID.

Throws:

TAPException - If the DB connection creation fails.

Since:

2.0

See Also:

TAPFactory.getConnection(String)

cancelQuery

public final void cancelQuery()

Cancel the current SQL query execution or result set fetching if any is currently running. If no such process is on going, this function has no effect.

Since:

2.1

start

public final TAPExecutionReport start(java.lang.Thread thread,
                                      java.lang.String jobId,
                                      TAPParameters params,
                                      javax.servlet.http.HttpServletResponse response)
                               throws TAPException,
                                      java.io.IOException,
                                      java.lang.InterruptedException

Start the synchronous processing of the ADQL query.

This function initialize the execution report and then call start().

Parameters:

thread - The synchronous thread which asks the query processing.

jobId - ID of the corresponding job.

params - All execution parameters (including the query to process).

response - Object in which the result or the error must be written.

Returns:

The resulting execution report.

Throws:

TAPException - If any error occurs while executing the ADQL query.

java.io.IOException - If any error occurs while writing the result in the given HttpServletResponse.

java.lang.InterruptedException - If the job has been interrupted (by the user or a time-out).

See Also:

start()

start

protected final TAPExecutionReport start()
                                  throws TAPException,
                                         UWSException,
                                         java.io.IOException,
                                         java.lang.InterruptedException

Process the ADQL query.

This function calls the following function (in the same order):

1. TAPFactory.getConnection(String)
2. uploadTables()
3. parseADQL()
4. executeADQL(ADQLQuery)
5. writeResult(TableIterator)
6. dropUploadedTables()
7. TAPFactory.freeConnection(DBConnection)

The execution report is updated gradually. Besides a job parameter - progression - is set at each step of the process in order to notify the user of the progression of the query execution. This parameter is removed at the end of the execution if it is successful.

The "interrupted" flag of the associated thread is often tested so that stopping the execution as soon as possible.

Returns:

The updated execution report.

Throws:

TAPException - If any error occurs while executing the ADQL query.

UWSException - If any error occurs while executing the ADQL query.

java.io.IOException - If an error happens while writing the result in the specified HttpServletResponse. That kind of error can be thrown only in synchronous mode. In asynchronous, the error is stored as job error report and is never propagated.

java.lang.InterruptedException - If the job has been interrupted (by the user or a time-out).

parseADQL

protected ADQLQuery parseADQL()
                       throws ParseException,
                              java.lang.InterruptedException,
                              TAPException

Parse the ADQL query provided in the parameters by the user.

The query factory and the query checker are got from the TAP factory.

The configuration of this TAP service list all allowed coordinate systems. These are got here and provided to the query checker in order to ensure the coordinate systems used in the query are in this list.

The row limit specified in the ADQL query (with TOP) is checked and adjusted (if needed). Indeed, this limit can not exceed MAXREC given in parameter and the maximum value specified in the configuration of this TAP service. In the case no row limit is specified in the query or the given value is greater than MAXREC, (MAXREC+1) is used by default. The "+1" aims to detect overflows.

Returns:

The object representation of the ADQL query.

Throws:

ParseException - If the given ADQL query can not be parsed or if the construction of the object representation has failed.

java.lang.InterruptedException - If the thread has been interrupted.

TAPException - If the TAP factory is unable to create the ADQL factory or the query checker.

executeADQL

protected TableIterator executeADQL(ADQLQuery adql)
                             throws java.lang.InterruptedException,
                                    DBCancelledException,
                                    TAPException

Execute in "database" the given object representation of an ADQL query.

By default, this function is just calling DBConnection.executeQuery(ADQLQuery) and then it returns the value returned by this call.

Note: An INFO message is logged at the end of the query execution in order to report the result status (success or error) and the execution duration.

Parameters:

adql - The object representation of the ADQL query to execute.

Returns:

The result of the query.

Throws:

java.lang.InterruptedException - If the thread has been interrupted.

DBCancelledException - If the inner DB connection has been canceled.

TAPException - If the DBConnection has failed to deal with the given ADQL query.

See Also:

DBConnection.executeQuery(ADQLQuery)

writeResult

protected final void writeResult(TableIterator queryResult)
                          throws java.lang.InterruptedException,
                                 java.io.IOException,
                                 TAPException,
                                 UWSException

Write the given query result into the appropriate format in the appropriate output (HTTP response for a synchronous execution, otherwise a file or any output provided by UWS).

This function prepare the output in function of the execution type (synchronous or asynchronous). Once prepared, the result, the output and the formatter to use are given to writeResult(TableIterator, OutputFormat, OutputStream) which will really process the result formatting and writing.

Parameters:

queryResult - The result of the query execution in database.

Throws:

java.lang.InterruptedException - If the thread has been interrupted.

java.io.IOException - If an error happens while writing the result in the HttpServletResponse. That kind of error can be thrown only in synchronous mode. In asynchronous, the error is stored as job error report and is never propagated.

TAPException - If an error occurs while getting the appropriate formatter or while formatting or writing (synchronous execution) the result.

UWSException - If an error occurs while getting the output stream or while writing (asynchronous execution) the result.

See Also:

writeResult(TableIterator, OutputFormat, OutputStream)

writeResult

protected void writeResult(TableIterator queryResult,
                           OutputFormat formatter,
                           java.io.OutputStream output)
                    throws java.lang.InterruptedException,
                           java.io.IOException,
                           TAPException

Format and write the given result in the given output with the given formatter.

By default, this function is just calling OutputFormat.writeResult(TableIterator, OutputStream, TAPExecutionReport, Thread).

Note: OutputFormat.writeResult(TableIterator, OutputStream, TAPExecutionReport, Thread) is often testing the "interrupted" flag of the thread in order to stop as fast as possible if the user has cancelled the job or if the thread has been interrupted for another reason.

Parameters:

queryResult - Query result to format and to output.

formatter - The object able to write the result in the appropriate format.

output - The stream in which the result must be written.

Throws:

java.lang.InterruptedException - If the thread has been interrupted.

java.io.IOException - If there is an error while writing the result in the given stream.

TAPException - If there is an error while formatting the result.

dropUploadedTables

protected void dropUploadedTables()
                           throws TAPException

Drop all tables uploaded by the user from the database.

Note: By default, if an error occurs while dropping a table from the database, the error will just be logged ; it won't be thrown/propagated.

Throws:

TAPException - If a grave error occurs. By default, no exception is thrown ; they are just logged.