Documentation

This documentation is splitted in 5 parts:

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.

A. Service

  1. Resource management What is a TAP resource? Which one are already existing? How to customize them or add other?
  2. File management How the library deals with the different files it has to manage? What can be customized and how?
  3. Log 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).
  4. Errors Internal error or wrong parameters, are examples of errors the library has to deal with. What can be customized on errors management? And how?
  5. 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?

B. Database & ADQL

Part 1 - Database
  1. Database connection A TAP service requires a database connection. How is it set and managed in the library? Does it mean only JDBC connection?
  2. TAP metadata List of schemas, tables and columns must be also provided to the library. How are they stored? Why? How to provide them?
  3. Upload 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?
  4. SQL translation 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
  1. 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.
  2. Coordinate system 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.
  3. Geometrical functions 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.

C. Job Description

  1. TAPJob This class contains all information about a job/query to run, running or already finished.
  2. Job parameters Parameters provided while submitting a query are stored in a way. Where? How new ones can be added?
  3. User identification The service user who submit a query may be authenticated in some way. How does this mechanism work in the library?
  4. Backup Description of all asynchronous jobs may be backuped so that in case of service failure or interruption most of the jobs can be restored.
  5. Retention limits Asynchronous jobs and their results may not be kept on the server forever. How job retention can be configured?

D. Query Execution

  1. TAPExecutor The whole query execution is lead by only one class. Some parts of this execution can be customized.
  2. Duration limits 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.
  3. Output limits As for the duration time of a query execution, the amount of returned rows may be limited in order to save server resources.
  4. Output formats 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
  5. Synchronous queries The simplest query execution mode. It is designed for fast queries. How this execution mode works in the library?
  6. Asynchronous queries 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?

E. TAP Configuration File

  1. Usage
  2. File location
  3. Properties types
  4. Supported properties