tap

Class TAPJob

java.lang.Object

uws.job.SerializableUWSObject

uws.job.UWSJob

tap.TAPJob

All Implemented Interfaces:

java.io.Serializable

public class TAPJob
extends UWSJob

Description of a TAP job. This class is used for asynchronous but also synchronous queries.

On the contrary to UWSJob, it is loading parameters from TAPParameters instances rather than UWSParameters. However, TAPParameters is an extension of UWSParameters. That's what allow the UWS library to use both TAPJob and TAPParameters.

Version:

2.2 (09/2017)

Author:

Grégory Mantelet (CDS;ARI)

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TAPJob.NoDBConnectionAvailableException This exception is thrown by a job execution when no database connection are available anymore.

Nested classes/interfaces inherited from class uws.job.UWSJob

UWSJob.JobTimeOut

Field Summary

Fields

Modifier and Type	Field and Description
protected TAPExecutionReport	execReport Internal query execution report.
static java.lang.String	FORMAT_VOTABLE FORMAT value meaning the VOTable format: "votable".
static java.lang.String	LANG_ADQL LANG value meaning ADQL language: "ADQL".
static java.lang.String	LANG_PQL LANG value meaning PQL language: "PQL".
static java.lang.String	PARAM_FORMAT Name of the standard TAP parameter which specifies the output format (format of a query result): "FORMAT".
static java.lang.String	PARAM_LANGUAGE Name of the standard TAP parameter which specifies the query language: "LANG".
static java.lang.String	PARAM_MAX_REC Name of the standard TAP parameter which specifies the maximum number of rows that must be returned in the query result: "MAXREC".
static java.lang.String	PARAM_PROGRESSION Name of the library parameter which informs about a query execution progression: "PROGRESSION".
static java.lang.String	PARAM_QUERY Name of the standard TAP parameter which specifies the query to execute: "QUERY".
static java.lang.String	PARAM_REQUEST Name of the standard TAP parameter which specifies the type of request to execute: "REQUEST".
static java.lang.String	PARAM_UPLOAD Name of the standard TAP parameter which defines the tables to upload in the database for the query execution: "UPLOAD".
static java.lang.String	PARAM_VERSION Name of the standard TAP parameter which specifies the version of the TAP protocol that must be used: "VERSION".
static java.lang.String	REQUEST_DO_QUERY REQUEST value meaning an ADQL query must be executed: "doQuery".
static java.lang.String	REQUEST_GET_CAPABILITIES REQUEST value meaning VO service capabilities must be returned: "getCapabilities".
protected TAPParameters	tapParams Parameters of this job for its execution.
static int	UNLIMITED_MAX_REC Special MAXREC value meaning the number of output rows is not limited.
static java.lang.String	VERSION_1_0 VERSION value meaning the version 1.0 of TAP: "1.0".

Fields inherited from class uws.job.UWSJob

ACTION_DELETE, ANONYMOUS_OWNER, creationTime, dateFormat, DEFAULT_DATE_FORMAT, errorSummary, inputParams, jobId, jobInfo, lastId, owner, PARAM_ACTION, PARAM_CREATION_TIME, PARAM_DESTRUCTION_TIME, PARAM_END_TIME, PARAM_ERROR_SUMMARY, PARAM_EXECUTION_DURATION, PARAM_JOB_ID, PARAM_JOB_INFO, PARAM_OWNER, PARAM_PARAMETERS, PARAM_PHASE, PARAM_QUOTE, PARAM_RESULTS, PARAM_RUN_ID, PARAM_START_TIME, PHASE_ABORT, PHASE_RUN, QUOTE_NOT_KNOWN, results, stopping, thread, UNLIMITED_DURATION, waitForStop

Constructor Summary

Constructors

Constructor and Description
TAPJob(JobOwner owner, TAPParameters tapParams) Build a pending TAP job with the given parameters.
TAPJob(JobOwner owner, TAPParameters tapParams, java.lang.String requestID) Build a pending TAP job with the given parameters.
TAPJob(java.lang.String jobID, long creationTime, JobOwner owner, TAPParameters params, long quote, long startTime, long endTime, java.util.List<Result> results, ErrorSummary error) Restore a job in a state defined by the given parameters.

Method Summary

Modifier and Type	Method and Description
TAPExecutionReport	getExecReport() Get the execution report.
java.lang.String	getFormat() Get the value of the FORMAT parameter.
java.lang.String	getLanguage() Get the value of the LANG parameter.
int	getMaxRec() Get the value of the MAXREC parameter.
java.lang.String	getQuery() Get the value of the QUERY parameter (i.e.
java.lang.String	getRequest() Get the value of the REQUEST parameter.
DALIUpload[]	getTablesToUpload() Get the list of tables to upload in the database for the query execution.
TAPParameters	getTapParams() Get the object storing and managing the set of all (UWS and TAP) parameters.
java.lang.String	getUpload() Get the value of the UPLOAD parameter.
java.lang.String	getVersion() Get the value of the VERSION parameter.
boolean	isReadyForExecution() Check whether this job is able to start right now.
void	setExecReport(TAPExecutionReport execReport) Set the execution report.
void	start(boolean useManager) Starts the job.
protected void	stop() Stops the thread that executes the work of this job.

Methods inherited from class uws.job.UWSJob

abort, addObserver, addOrUpdateParameter, addOrUpdateParameter, addOrUpdateParameters, addOrUpdateParameters, addResult, applyPhaseParam, archive, clearResources, clearResources, equals, error, generateJobId, getAdditionalParameters, getAdditionalParameterValue, getCreationTime, getDestructionTime, getEndTime, getErrorSummary, getExecutionDuration, getExecutionManager, getFactory, getFileManager, getJobId, getJobInfo, getJobList, getLogger, getNbAdditionalParameters, getNbObservers, getNbResults, getObservers, getOwner, getParameter, getPhase, getPhaseManager, getQuote, getRestorationDate, getResult, getResults, getRunId, getStartTime, getTimeToWaitForEnd, getUrl, getWorkError, hashCode, isFinished, isRunning, isStopped, notifyObservers, removeAdditionalParameter, removeAllObservers, removeObserver, serialize, serialize, serialize, setDestructionTime, setEndTime, setErrorSummary, setExecutionDuration, setJobInfo, setJobList, setPhase, setPhase, setPhaseManager, setQuote, setRunId, setStartTime, setTimeToWaitForEnd, start, toString

Methods inherited from class uws.job.SerializableUWSObject

serialize, serialize, serialize

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

PARAM_REQUEST

public static final java.lang.String PARAM_REQUEST

Name of the standard TAP parameter which specifies the type of request to execute: "REQUEST".

See Also:

Constant Field Values

REQUEST_DO_QUERY

public static final java.lang.String REQUEST_DO_QUERY

REQUEST value meaning an ADQL query must be executed: "doQuery".

See Also:

Constant Field Values

REQUEST_GET_CAPABILITIES

public static final java.lang.String REQUEST_GET_CAPABILITIES

REQUEST value meaning VO service capabilities must be returned: "getCapabilities".

See Also:

Constant Field Values

PARAM_LANGUAGE

public static final java.lang.String PARAM_LANGUAGE

Name of the standard TAP parameter which specifies the query language: "LANG". (only the ADQL language is supported by default in this version of the library)

See Also:

Constant Field Values

LANG_ADQL

public static final java.lang.String LANG_ADQL

LANG value meaning ADQL language: "ADQL".

See Also:

Constant Field Values

LANG_PQL

public static final java.lang.String LANG_PQL

LANG value meaning PQL language: "PQL". (this language is not supported in this version of the library)

See Also:

Constant Field Values

PARAM_VERSION

public static final java.lang.String PARAM_VERSION

Name of the standard TAP parameter which specifies the version of the TAP protocol that must be used: "VERSION". (only the version 1.0 is supported in this version of the library)

See Also:

Constant Field Values

VERSION_1_0

public static final java.lang.String VERSION_1_0

VERSION value meaning the version 1.0 of TAP: "1.0".

See Also:

Constant Field Values

PARAM_FORMAT

public static final java.lang.String PARAM_FORMAT

Name of the standard TAP parameter which specifies the output format (format of a query result): "FORMAT".

See Also:

Constant Field Values

FORMAT_VOTABLE

public static final java.lang.String FORMAT_VOTABLE

FORMAT value meaning the VOTable format: "votable".

See Also:

Constant Field Values

PARAM_MAX_REC

public static final java.lang.String PARAM_MAX_REC

Name of the standard TAP parameter which specifies the maximum number of rows that must be returned in the query result: "MAXREC".

See Also:

Constant Field Values

UNLIMITED_MAX_REC

public static final int UNLIMITED_MAX_REC

Special MAXREC value meaning the number of output rows is not limited.

See Also:

Constant Field Values

PARAM_QUERY

public static final java.lang.String PARAM_QUERY

Name of the standard TAP parameter which specifies the query to execute: "QUERY".

See Also:

Constant Field Values

PARAM_UPLOAD

public static final java.lang.String PARAM_UPLOAD

Name of the standard TAP parameter which defines the tables to upload in the database for the query execution: "UPLOAD".

See Also:

Constant Field Values

PARAM_PROGRESSION

public static final java.lang.String PARAM_PROGRESSION

Name of the library parameter which informs about a query execution progression: "PROGRESSION". (this parameter is removed once the execution is finished)

See Also:

Constant Field Values

execReport

protected TAPExecutionReport execReport

Internal query execution report.

tapParams

protected final TAPParameters tapParams

Parameters of this job for its execution.

Constructor Detail

TAPJob

public TAPJob(JobOwner owner,
              TAPParameters tapParams)
       throws TAPException

Build a pending TAP job with the given parameters.

Note: If the parameter UWSJob.PARAM_PHASE (phase) is given with the value UWSJob.PHASE_RUN the job execution starts immediately after the job has been added to a job list or after UWSJob.applyPhaseParam(JobOwner) is called.

Parameters:

owner - User who owns this job. MAY BE NULL

tapParams - Set of parameters.

Throws:

TAPException - If one of the given parameters has a forbidden or wrong value.

TAPJob

public TAPJob(JobOwner owner,
              TAPParameters tapParams,
              java.lang.String requestID)
       throws TAPException

Build a pending TAP job with the given parameters. The given HTTP request ID will be used as Job ID if not already used by another job.

Note: If the parameter UWSJob.PARAM_PHASE (phase) is given with the value UWSJob.PHASE_RUN the job execution starts immediately after the job has been added to a job list or after UWSJob.applyPhaseParam(JobOwner) is called.

Parameters:

owner - User who owns this job. MAY BE NULL

tapParams - Set of parameters.

requestID - ID of the HTTP request which has initiated the creation of this job. Note: if NULL, empty or already used, a job ID will be generated thanks to UWSJob.generateJobId().

Throws:

TAPException - If one of the given parameters has a forbidden or wrong value.

Since:

2.1

TAPJob

public TAPJob(java.lang.String jobID,
              long creationTime,
              JobOwner owner,
              TAPParameters params,
              long quote,
              long startTime,
              long endTime,
              java.util.List<Result> results,
              ErrorSummary error)
       throws TAPException

Restore a job in a state defined by the given parameters. The phase must be set separately with UWSJob.setPhase(uws.job.ExecutionPhase, boolean), where the second parameter is true.

Parameters:

jobID - ID of the job.

creationTime - Creation date/time of the job (SHOULD NOT BE NEGATIVE OR NULL).

owner - User who owns this job.

params - Set of not-standard UWS parameters (i.e. what is called by UWSJob as additional parameters ; they includes all TAP parameters).

quote - Quote of this job.

startTime - Date/Time at which this job started. (if not null, it means the job execution was finished, so a endTime should be provided)

endTime - Date/Time at which this job finished.

results - List of results. NULL if the job has not been executed, has been aborted or finished with an error.

error - Error with which this job ends.

Throws:

TAPException - If one of the given parameters has a forbidden or wrong value.

Since:

2.2

Method Detail

getTapParams

public final TAPParameters getTapParams()

Get the object storing and managing the set of all (UWS and TAP) parameters.

Returns:

The object managing all job parameters.

getRequest

public final java.lang.String getRequest()

Get the value of the REQUEST parameter.

This value must be "doQuery".

Returns:

REQUEST value.

getFormat

public final java.lang.String getFormat()

Get the value of the FORMAT parameter.

Returns:

FORMAT value.

getLanguage

public final java.lang.String getLanguage()

Get the value of the LANG parameter.

This value should always be "ADQL" in this version of the library

Returns:

LANG value.

getMaxRec

public final int getMaxRec()

Get the value of the MAXREC parameter.

If this value is negative, it means the number of output rows is not limited.

Returns:

MAXREC value.

getQuery

public final java.lang.String getQuery()

Get the value of the QUERY parameter (i.e. the query, in the language returned by getLanguage(), to execute).

Returns:

QUERY value.

getVersion

public final java.lang.String getVersion()

Get the value of the VERSION parameter.

This value should be "1.0" in this version of the library.

Returns:

VERSION value.

getUpload

public final java.lang.String getUpload()

Get the value of the UPLOAD parameter.

This value must be formatted as specified by the TAP standard (= a semicolon separated list of DALI uploads).

Returns:

UPLOAD value.

getTablesToUpload

public final DALIUpload[] getTablesToUpload()

Get the list of tables to upload in the database for the query execution.

The returned array is an interpretation of the UPLOAD parameter.

Returns:

List of tables to upload.

getExecReport

public final TAPExecutionReport getExecReport()

Get the execution report.

This report is available only during or after the job execution. It tells in which step the execution is, and how long was the previous steps. It can also give more information about the number of resulting rows and columns.

Returns:

The execReport.

setExecReport

public final void setExecReport(TAPExecutionReport execReport)
                         throws UWSException

Set the execution report.

IMPORTANT: This function can be called only if the job is running or is being restored, otherwise an exception would be thrown. It should not be used by implementors, but only by the internal library processing.

Parameters:

execReport - An execution report.

Throws:

UWSException - If this job has never been restored and is not running.

isReadyForExecution

public final boolean isReadyForExecution()

Check whether this job is able to start right now.

Basically, this function try to get a database connection. If none is available, then this job can not start and this function return FALSE. In all the other cases, TRUE is returned.

Warning: This function will indirectly open and keep a database connection, so that the job can be started just after its call. If it turns out that the execution won't start just after this call, the DB connection should be closed in some way in order to save database resources.

Returns:

true if this job can start right now, false otherwise.

Since:

2.0

start

public final void start(boolean useManager)
                 throws UWSException

Description copied from class: UWSJob

Starts the job.

Note: This function does nothing if the job is already running!

Overrides:

start in class UWSJob

Parameters:

useManager - true to let the execution manager deciding whether the job starts immediately or whether it must be put in a queue until enough resources are available, false to start the execution immediately.

Throws:

UWSException - If there is an error while changing the execution phase or when starting the corresponding thread.

See Also:

UWSJob.isRunning(), UWSFactory.createJobThread(UWSJob), ExecutionManager.execute(UWSJob), UWSJob.setPhase(ExecutionPhase), UWSJob.isFinished(), UWSJob.startTime

stop

protected void stop()

Description copied from class: UWSJob

Stops the thread that executes the work of this job.

Overrides:

stop in class UWSJob

Since:

2.1