public abstract class TAPFactory extends java.lang.Object implements UWSFactory
Let build essential objects of the TAP service.
Basically, it means answering to the following questions:
DBConnection)UWSService)UWSBackupManager)TAPJob)Uploader)ADQLExecutor)
ADQLParser)QueryChecker)| Modifier and Type | Field and Description |
|---|---|
protected ServiceConnection |
service
Connection to the TAP service ; it provides all important service configuration information.
|
| Modifier | Constructor and Description |
|---|---|
protected |
TAPFactory(ServiceConnection service)
Build a basic
TAPFactory. |
| Modifier and Type | Method and Description |
|---|---|
abstract ADQLExecutor |
createADQLExecutor()
Create the object able to execute an ADQL query and to write and to format its result.
|
abstract ADQLParser |
createADQLParser()
Create a parser of ADQL query.
|
UWSJob |
createJob(javax.servlet.http.HttpServletRequest request,
JobOwner owner)
Creates a (PENDING) UWS job from the given HTTP request.
|
UWSJob |
createJob(java.lang.String jobId,
long creationTime,
JobOwner owner,
UWSParameters params,
long quote,
long startTime,
long endTime,
java.util.List<Result> results,
ErrorSummary error)
Creates a UWS job with the following attributes.
|
JobThread |
createJobThread(UWSJob job)
Create the thread which will execute the task described by the given UWSJob instance.
|
abstract QueryChecker |
createQueryChecker(TAPSchema uploadSchema)
Create an object able to check the consistency between the ADQL query and the database.
|
abstract ADQLQueryFactory |
createQueryFactory()
Create a factory able to build every part of an
ADQLQuery object. |
RequestParser |
createRequestParser(UWSFileManager fileManager)
Create a parser of HTTP requests.
|
protected abstract TAPJob |
createTAPJob(javax.servlet.http.HttpServletRequest request,
JobOwner owner)
Create a PENDING asynchronous job from the given HTTP request.
|
protected abstract TAPJob |
createTAPJob(java.lang.String jobId,
long creationTime,
JobOwner owner,
TAPParameters params,
long quote,
long startTime,
long endTime,
java.util.List<Result> results,
ErrorSummary error)
Create a PENDING asynchronous job with the given parameters.
|
abstract TAPParameters |
createTAPParameters(javax.servlet.http.HttpServletRequest request)
Extract all the TAP parameters from the given HTTP request (multipart or not) and return them.
|
abstract TAPParameters |
createTAPParameters(java.util.Map<java.lang.String,java.lang.Object> params)
Identify all TAP parameters and gather them inside a
TAPParameters object. |
abstract Uploader |
createUploader(DBConnection dbConn)
Create an object able to manage the creation of submitted user tables (in VOTable) into the database.
|
abstract UWSService |
createUWS()
Create the object which will manage the asynchronous resource of the TAP service.
|
abstract UWSBackupManager |
createUWSBackupManager(UWSService uws)
Create the object which will manage the backup and restoration of all asynchronous jobs.
|
UWSParameters |
createUWSParameters(javax.servlet.http.HttpServletRequest request)
Extract the parameters from the given request (multipart or not).
|
UWSParameters |
createUWSParameters(java.util.Map<java.lang.String,java.lang.Object> params)
Identify and gather all identified parameters of the given map inside a
TAPParameters object. |
abstract void |
destroy()
Destroy all resources (and particularly DB connections and JDBC driver) allocated in this factory.
|
abstract void |
freeConnection(DBConnection conn)
Free the given connection.
|
abstract DBConnection |
getConnection(java.lang.String jobID)
Get a free database connection.
|
abstract ServiceErrorWriter |
getErrorWriter()
Get the object to use when an error must be formatted and written to the user.
|
protected final ServiceConnection service
protected TAPFactory(ServiceConnection service) throws java.lang.NullPointerException
TAPFactory.
Nothing is done except setting the service connection.service - Configuration of the TAP service. MUST NOT be NULLjava.lang.NullPointerException - If the given ServiceConnection is NULL.public abstract ServiceErrorWriter getErrorWriter()
Get the object to use when an error must be formatted and written to the user.
This formatted error will be either written in an HTTP response or in a job error summary.
public abstract DBConnection getConnection(java.lang.String jobID) throws TAPException
Get a free database connection.
Free means this connection is not currently in use and will be exclusively dedicated to the function/process/thread which has asked for it by calling this function.
Note: This function can create on the fly a new connection OR get a free one from a connection pool. Considering the creation time of a database connection, the second way is recommended.
IMPORTANT: The returned connection MUST be freed after having used it.
WARNING: Some implementation may free the connection automatically when not used for a specific time. So, do not forget to free the connection after use!
jobID - ID of the job/thread/process which has asked for this connection. note: The returned connection must then be identified thanks to this ID.TAPException - If there is any error while getting a free connection.public abstract void freeConnection(DBConnection conn)
Free the given connection.
This function is called by the TAP library when a job/thread does not need this connection any more. It aims to free resources associated to the given database connection.
Note: This function can just close definitely the connection OR give it back to a connection pool. The implementation is here totally free!
conn - The connection to close.public abstract void destroy()
Destroy all resources (and particularly DB connections and JDBC driver) allocated in this factory.
Note: This function is called when the TAP service is shutting down. After this call, the factory may not be able to provide any closed resources ; its behavior may be unpredictable.
public abstract ADQLExecutor createADQLExecutor() throws TAPException
Create the object able to execute an ADQL query and to write and to format its result.
Note:
A default implementation is provided by AbstractTAPFactory
TAPException - If any error occurs while creating an ADQL executor.public abstract ADQLParser createADQLParser() throws TAPException
Create a parser of ADQL query.
Warning:
This parser can be created with a query factory and/or a query checker.
createQueryFactory() will be used only if the default query factory (or none) is set
in the ADQL parser returned by this function.
Idem for createQueryChecker(TAPSchema): it will used only if no query checker is set
in the returned ADQL parser.
Note:
A default implementation is provided by AbstractTAPFactory.
TAPException - If any error occurs while creating an ADQL parser.public abstract ADQLQueryFactory createQueryFactory() throws TAPException
Create a factory able to build every part of an ADQLQuery object.
Warning:
This function is used only if the default query factory (or none) is set in the ADQL parser
returned by createADQLParser().
Note:
A default implementation is provided by AbstractTAPFactory
ADQLQuery factory.TAPException - If any error occurs while creating the factory.public abstract QueryChecker createQueryChecker(TAPSchema uploadSchema) throws TAPException
Create an object able to check the consistency between the ADQL query and the database. That's to say, it checks whether the tables and columns used in the query really exist in the database.
Warning:
This function is used only if no query checker is set in the ADQL parser
returned by createADQLParser().
Note:
A default implementation is provided by AbstractTAPFactory
uploadSchema - ADQL schema containing the description of all uploaded tables.TAPException - If any error occurs while creating a query checker.public abstract Uploader createUploader(DBConnection dbConn) throws TAPException
Create an object able to manage the creation of submitted user tables (in VOTable) into the database.
Note:
A default implementation is provided by AbstractTAPFactory.
dbConn - The database connection which has requested an Uploader.Uploader.TAPException - If any error occurs while creating an Uploader instance.public abstract UWSService createUWS() throws TAPException
Create the object which will manage the asynchronous resource of the TAP service. This resource is a UWS service.
Note:
A default implementation is provided by AbstractTAPFactory.
TAPException - If any error occurs while creating this UWS service.public abstract UWSBackupManager createUWSBackupManager(UWSService uws) throws TAPException
Create the object which will manage the backup and restoration of all asynchronous jobs.
Note: This function may return NULL. If it does, asynchronous jobs won't be backuped.
Note:
A default implementation is provided by AbstractTAPFactory.
uws - The UWS service which has to be backuped and restored.TAPException - If any error occurs while creating this backup manager.public final UWSJob createJob(javax.servlet.http.HttpServletRequest request, JobOwner owner) throws UWSException
Creates a (PENDING) UWS job from the given HTTP request.
This implementation just call createTAPJob(HttpServletRequest, JobOwner)
with the given request, in order to ensure that the returned object is always a TAPJob.
createJob in interface UWSFactoryrequest - Request which triggers the creation of a UWS job.owner - The identified UWS user (see UserIdentifier).UWSException - If there is an error while creating the job.AbstractUWSFactory.createJob(javax.servlet.http.HttpServletRequest, uws.job.user.JobOwner),
createTAPJob(HttpServletRequest, JobOwner)protected abstract TAPJob createTAPJob(javax.servlet.http.HttpServletRequest request, JobOwner owner) throws UWSException
Create a PENDING asynchronous job from the given HTTP request.
Note:
A default implementation is provided by AbstractTAPFactory.
request - Request which contains all parameters needed to set correctly the asynchronous job to create.owner - The user which has requested the job creation.UWSException - If any error occurs while reading the parameters in the request or while creating the job.public final UWSJob createJob(java.lang.String jobId, long creationTime, JobOwner owner, UWSParameters params, long quote, long startTime, long endTime, java.util.List<Result> results, ErrorSummary error) throws UWSException
Creates a UWS job with the following attributes.
This implementation just call createTAPJob(String, long, JobOwner, TAPParameters, long, long, long, List, ErrorSummary)
with the given parameters, in order to ensure that the returned object
is always a TAPJob.
Note 1: This function is mainly used to restore a UWS job at the UWS initialization.
Note 2: The job phase is chosen automatically from the given job attributes (i.e. no endTime => PENDING, no result and no error => ABORTED, ...).
createJob in interface UWSFactoryjobId - ID of the job (NOT NULL).creationTime - Creation date/time of the job (SHOULD NOT BE
NEGATIVE OR NULL).owner - Owner of the job.params - List of all input UWS job parameters.quote - Its quote (in seconds).startTime - Date/Time of the start of this job.endTime - Date/Time of the end of this job.results - All results of this job.error - The error which ended the job to create.UWSException - If there is an error while creating the job.AbstractUWSFactory.createJob(String, long, JobOwner, UWSParameters, long, long, long, List, ErrorSummary),
createTAPJob(String, long, JobOwner, TAPParameters, long, long, long, List, ErrorSummary)protected abstract TAPJob createTAPJob(java.lang.String jobId, long creationTime, JobOwner owner, TAPParameters params, long quote, long startTime, long endTime, java.util.List<Result> results, ErrorSummary error) throws UWSException
Create a PENDING asynchronous job with the given parameters.
Note:
A default implementation is provided in AbstractTAPFactory.
jobId - ID of the job (NOT NULL).creationTime - Creation date/time of the job (SHOULD NOT BE
NEGATIVE OR NULL).owner - Owner of the job.params - List of all input job parameters.quote - Its quote (in seconds).startTime - Date/Time of the start of this job.endTime - Date/Time of the end of this job.results - All results of this job.error - The error which ended the job to create.UWSException - If there is an error while creating the job.public final JobThread createJobThread(UWSJob job) throws UWSException
Create the thread which will execute the task described by the given UWSJob instance.
This function is definitely implemented here and can not be overridden. The processing of
an ADQL query must always be the same in a TAP service ; it is completely done by AsyncThread.
createJobThread in interface UWSFactoryjob - Description of the task to execute.UWSException - If there is an error while creating the job task.UWSFactory.createJobThread(uws.job.UWSJob),
AsyncThreadpublic final UWSParameters createUWSParameters(javax.servlet.http.HttpServletRequest request) throws UWSException
Extract the parameters from the given request (multipart or not).
This function is used only to create the set of parameters for a TAP job (synchronous or asynchronous).
Thus, it just call createTAPParameters(HttpServletRequest) with the given request, in order to ensure
that the returned object is always a TAPParameters.
createUWSParameters in interface UWSFactoryrequest - The request from which parameters must be extracted.UWSException - If an error occurs while extracting parameters.createTAPParameters(HttpServletRequest)public abstract TAPParameters createTAPParameters(javax.servlet.http.HttpServletRequest request) throws TAPException
Extract all the TAP parameters from the given HTTP request (multipart or not) and return them.
Note:
A default implementation is provided by AbstractTAPFactory.
request - The HTTP request containing the TAP parameters to extract.TAPException - If any error occurs while extracting the parameters.public final UWSParameters createUWSParameters(java.util.Map<java.lang.String,java.lang.Object> params) throws UWSException
Identify and gather all identified parameters of the given map inside a TAPParameters object.
This implementation just call createTAPParameters(Map) with the given map, in order to ensure
that the returned object is always a TAPParameters.
createUWSParameters in interface UWSFactoryparams - All the parameters to check and to store.UWSException - If an error occurs while extracting parameters.AbstractUWSFactory.createUWSParameters(java.util.Map),
createTAPParameters(Map)public abstract TAPParameters createTAPParameters(java.util.Map<java.lang.String,java.lang.Object> params) throws TAPException
Identify all TAP parameters and gather them inside a TAPParameters object.
Note:
A default implementation is provided by AbstractTAPFactory.
params - Map containing all parameters.TAPException - If any error occurs while creating the TAPParameters object.public RequestParser createRequestParser(UWSFileManager fileManager) throws UWSException
UWSFactorycreateRequestParser in interface UWSFactoryfileManager - File manager to use if files are uploaded in an HTTP request.UWSException - If an error occurs while creating the parser.