TAP is a complex protocol to implement completely and properly. First, because inputs are ADQL queries. These queries must be parsed, checked upon the
database, translated into a "language" (usually SQL) understandable by the server and finally executed. Their execution must be carefully watched and
controlled so that avoiding strange or dangerous behavior. So a special care must be particularly taken about the ADQL and its execution. Besides
inputs may also include one or more VOTable documents corresponding to tables to temporarily (i.e. the time the query is executing) add into the database.
Putting aside inputs, TAP must also provide two execution methods: synchronous and asynchronous. Though the first is quite straightforward to implement,
the asynchronous method requires the implementation of another IVOA protocol: UWS. This latter
implies the management of a jobs/tasks queue, a threaded execution of each individual job/task and a way to store results (and optionally uploads and errors).
TAP has thus to do as well. Besides, as any such service, a log and a backup (or another way to ensure recovery in case of crash) should also be part of the
implementation of TAP (and UWS).
Considering all these main aspects of this protocol, the currently presented TAP Library aims to help as easily and quickly as possible to create a
service implementing TAP. Moreover, since many aspects have to be covered and that each service has different constraints and purpose, the library proposes
to customize as many of its parts as possible. The following documentation aims to help users of this library by explaining how each aspect has been
implemented, how it works and how much it can be customized.
Because not all nooks of the library can be documented here, you are obviously encouraged to abuse of the Javadoc and the code source to help you answering
your questions. But of course, if it is not enough or if you think something is badly implemented or is missing, do not hesitate to
send an email to the developer.
What is a TAP resource? Which one are already existing? How to customize them or add other?
How the library deals with the different files it has to manage? What can be customized and how?
The library is writting a log file. The default output can be a little customized, but it is also possible
to re-write completely this part and write logs in a completely different format (e.g. database).
Internal error or wrong parameters, are examples of errors the library has to deal with. What can be
customized on errors management? And how?
HTTP request parsing
By default, the library is able to interpret several ways to provide HTTP request parameters. What are they?
How to add/remove/change this interpretation?
A TAP service requires a database connection. How is it set and managed in the library? Does it mean only JDBC connection?
List of schemas, tables and columns must be also provided to the library. How are they stored? Why? How to provide them?
UPLOAD is an optional feature in TAP and implies addition in the database. But how the library process a table upload?
What does it imply for the database?
If a SQL database is used, a translation from ADQL to SQL is needed. Depending of the used DBMS, the library may need
help to perform a such translation.
Part 2 - ADQL
User Defined Functions
UDF may be very useful for users while writing their ADQL queries. The library lets declare them, so that syntax
and types can be checked.
While using geometrical regions, a coordinate system must be precised. However, data are generally expressed in
only one system, and conversion are not always supported. The library lets list allowed coordinate system in order
to alert the user while submitting his query.
The ADQL language comes with a defined set of geometrical functions (i.e. regions but also computation functions).
All may not be supported, that's why it is possible to give a list of all the allowed ones.
The whole query execution is lead by only one class. Some parts of this execution can be customized.
Some queries may be very long, and so consume a lot of server resources which can impact the service performances.
However, it is possible to set some limits on the query execution time.
As for the duration time of a query execution, the amount of returned rows may be limited in order to save server resources.
A TAP service must return a VOTable document as result of a query. But other formats are allowed. What are the formats
proposed by the library? How to list formats to support? How to add a new ones
The simplest query execution mode. It is designed for fast queries. How this execution mode works in the library?
More complex, this query execution mode lets execute long queries on server side. The user can watch the query execution
and get the result whenever he wants. How does it work? Is it customizable?