All properties listed in the below table are all the possible TAP configuration properties. Some of them are mandatory. If one of these properties is missing, the TAP Service will not able to start: an error will be displayed immediately in the application server log and a HTTP 503 error will be sent when accessing the TAP URL.
Besides, you should know that any property key not listed in this table will be ignored without error or warning message.
However, any not allowed property value will generate a warning message in the application server log and the default value will be kept. Thus, the TAP Service will be started and available but the desired configuration value will not be set. So, you should take a look at the application server log every times you start the TAP Service!
Here is an empty minimum TAP configuration file: tap_min.properties and a complete one: tap_full.properties.
Important note: Any limit value is an integer and so can be at most: 231-1 bytes/rows = 2147483647B/R (or also for the byte unit: = 2147483kB = 2147MB = 2GB). Otherwise, you should use the null value 0 to raise the limit constraint.
Legend: M means that the property is mandatory. If nothing is written for the second column, the property is optional.
/ mandatory propertiesProperty | Type | Description | Example | |
---|---|---|---|---|
General | ||||
home_page | text |
This property lets set a custom home page. 4 different kinds of value are accepted:
By default, the default home page provided by the library is used. |
|
|
home_page_mime_type | text |
MIME type of the service home page. This property is used only if the specified "home_page" is a local file path (i.e. if "home_page=file://..."). If no value is provided "text/html" will be set by default. Default: |
|
|
Provider | ||||
provider_name | text | Name of the provider of the TAP Service. | ||
service_description | text | Description of the TAP Service. | ||
Database (only if tap_factory = ø) | ||||
database_access | text |
Method to use in order to create database connections. Only two values are supported:
|
|
|
sql_translator | text |
The translator to use in order to translate ADQL to a SQL compatible with the used DBMS and its spatial extension. The TAP library supports only Postgresql (no spatial extension), PostgreSQL+PgSphere, SQLServer (no spatial extension), MySQL (no spatial extension) and H2 (no spatial extension) for the moment. But you can provide your own SQL translator (even if it does not have spatial features), by providing the name of a class (within brackets: {...}) that implements ADQLTranslator (for instance: {apackage.MyADQLTranslator}) and which have at least an empty constructor. |
|
|
sync_fetch_size | integer |
Size of result blocks to fetch from the database when a ADQL query is executed in Synchronous mode. Rather than fetching a query result in a whole, it may be possible to specify to the database that results may be retrieved by blocks whose the size can be specified with this property. If supported by the DBMS and the JDBC driver, this feature may help sparing memory and avoid too much waiting time from the TAP /sync users (and thus, avoiding some HTTP client timeouts). A negative or null value means that the default value of the JDBC driver will be used. Generally, it means that the database must wait to have collected all data before sending them to the library. Default: |
|
|
async_fetch_size | integer |
Size of result blocks to fetch from the database when an ADQL query is executed in Asynchronous mode. Rather than fetching a query result in a whole, it may be possible to specify to the database that results may be retrieved by blocks whose the size can be specified with this property. If supported by the DBMS and the JDBC driver, this feature may help sparing memory. A negative or null value means that the default value of the JDBC driver will be used. Generally, it means that the database must wait to have collected all data before sending them to the library. Default: |
|
|
fix_on_fail | boolean |
If enabled, this option lets automatically try fixing a query whose parsing failed because of a token error. This is particularly useful in the following cases:
In all these cases, the name/identifier/alias will be surrounded between
double quotes if the option This feature is also able to fix some incorrect Unicode characters (e.g. LaTeX alternatives for underscores, spaces and double/single quotes, copy-pasted from a PDF into a TAP query field). Warning: since this option alters the query provided by the query, it is possible that, after fix attempt, the query parses and runs but might generate an output different from what was expected. So, if this option is enabled, it should made be clear to the user that the TAP server might alter the query to make it work. Note:
when an input query is fixed and run successfully, the fixed ADQL query
is reported in an INFO element named Default: |
|
|
⤷ JNDI datasource (only if database_access=jndi) | ||||
datasource_jndi_name | text |
JNDI name of the datasource. It should be defined in the web application (e.g. in the META-INF/context.xml file in tomcat). |
|
|
⤷ JDBC parameters (only if database_access=jdbc) | ||||
jdbc_driver | text |
JDBC driver path. By default, it is guessed in function of the database name provided in the jdbc_url property. It MUST be provided if another DBMS is used or if the JDBC driver path does not match the following ones:
|
oracle.jdbc.driver.OracleDriver | |
jdbc_url | text |
It must be a JDBC driver URL. Note: The username, password or other parameters may be included in it, but in this case, the corresponding properties should leave empty or not provided at all. |
|
|
db_username | text |
Mandatory if the username is not already provided in jdbc_url Username used to access to the database. |
||
db_password | text |
Mandatory if the password is not already provided in jdbc_url Password used by db_username to access to the database. Warning: No password encryption can be done in this configuration file for the moment. |
||
Metadata | ||||
metadata | text |
Define the way the library must get the list of all schemas, tables and columns to publish and all their metadata (e.g. utype, description, type, ...) In its current state, the library proposes three methods:
For the two first methods, it is also possible to specify an extension of tap.metadata.TAPMetadata which will wrap a default TAPMetadata objects created using the specified methods (i.e. XML tableset or TAP_SCHEMA). In this way, it is possible to get the "default" metadata from an XML file or the database and then add/remove/modify some of them, or to change the output of the 'tables' resource. The extension of tap.metadata.TAPMetadata must have at least one constructor with the following parameters: (TAPMetadata) or (TAPMetadata, UWSFileManager, TAPFactory, TAPLog). |
| |
metadata_file | text |
Mandatory if the value of "metadata" is "xml". Local file path to the TableSet XML document. The XML document must implement the schema TableSet defined by VODataService. The file path must be either an absolute local file path or a file path relative to WebContent (i.e. the web application directory in which there are WEB-INF and META-INF). |
|
|
TAP_SCHEMA... | text |
Only used if Mapping between TAP_SCHEMA ADQL names and their names in the database. Any property named exactly (case sensitive) like TAP_SCHEMA items will be considered as a mapping between its ADQL name and its DB name. The property value MUST be NOT qualified. Just the item name is required. The value will be used as provided (with the same case). Note: The column dbName in the database TAP_SCHEMA declaring the standard TAP_SCHEMA entries (e.g. TAP_SCHEMA.schemas.dbName) is now ignored. Thus, only the mapping defined here, in the configuration file, is taken into account. |
|
|
Files | ||||
file_manager | text |
Type of the file manager. Accepted values are: local (to manage files on the local system). You can also add another way to manage files by providing the name (within brackets: {...}) of a class implementing UWSFileManager and having at least one constructor with only a java.util.Properties parameter. |
|
|
file_root_path | text |
Local file path of the directory in which all TAP files (logs, errors, job results, backup, ...) must be. The file path must be either an absolute local directory path or a directory path relative to WebContent (i.e. the web application directory in which there are WEB-INF and META-INF). |
|
|
directory_per_user | boolean |
Tells whether a directory should be created for each user. If yes, the user directory will be named with the user ID. In this directory, there will be error files, job results and it may be the backup file of the user. Default: |
|
|
group_user_directories | boolean |
Tells whether user directories must be grouped. If yes, directories are grouped by the first letter found in the user ID. Default: |
|
|
default_retention_period | integer |
The default period (in seconds) to keep query results. The prefix "default" means here that this value is put by default by the TAP Service if the client does not provide a value for it. The default period MUST be less or equals to the maximum retention period. If this rule is not respected, the default retention period is set immediately to the maximum retention period. A negative or null value means there is no restriction on the default retention period: job results will be kept forever. Float values are not allowed. By default query results are kept forever: |
86400 (1 day) | |
max_retention_period | integer |
The maximum period (in seconds) to keep query results. The prefix "max" means here that the client can not set a retention period greater than this one. The maximum period MUST be greater or equals to the default retention period. If this rule is not respected, the default retention period is set immediately to the maximum retention period. A negative or null value means there is no restriction on the maximum retention period: the job results will be kept forever. Float values are not allowed. Default: |
604800 (1 week) | |
Log files | ||||
logger | text |
Only two possibilities are already implemented.
Default: |
|
|
min_log_level | text |
Minimum level that a message must have in order to be logged by the default logger. 5 possible values:
Note:
This property is ignored if
Default: |
|
|
log_rotation | text |
Frequency of the log file rotation performed by the default logger. That's to say, logs will be written in a new file after this period. This avoid having too big log files. Old log files are renamed so that highlighting its logging period. The frequency string must respect the following syntax:
Where: hh = integer between 0 and 23, mm = integer between 0 and 59, dd (for 'W') = integer between 1 and 7 (1:sunday, 2:monday, ..., 7:saturday), dd (for 'M') = integer between 1 and 31. Warning: The frequency type is case sensitive! Then you should particularly pay attention at the case when using the frequency types 'M' (monthly) and 'm' (every minute). Note:
This property is ignored if
Default: |
|
|
UWS Backup (only if tap_factory = ø) | ||||
backup_frequency | text or integer |
Frequency at which the UWS service (that's to say, all its users and jobs) must be backuped. Allowed values are: The value Default: |
|
|
backup_by_user | text |
Tells whether the backup must be one file for every user ( This option can be enabled ONLY IF a user identification method is provided ; see property Default: |
|
|
Asynchronous jobs management | ||||
max_async_jobs | integer |
Maximum number of asynchronous jobs that can run simultaneously. A negative or null value means there is no restriction on the number of running asynchronous jobs. Default: |
|
|
Query Execution | ||||
default_execution_duration | integer |
Default time (in milliseconds) for query execution. The prefix "default" means here that the execution duration will be this one if the client does not set one. The default duration MUST be less or equals to the maximum execution duration. If this rule is not respected, the default execution duration is set immediately to the maximum execution duration. A negative or null value means there is no restriction on the default execution duration: the execution could never end. Float values are not allowed. Default: |
600000 (10 minutes) | |
max_execution_duration | integer |
Maximum time (in milliseconds) for query execution. The prefix "max" means here that the client can not set a time greater than this one. The maximum duration MUST be greater or equals to the default execution duration. If this rule is not respected, the default execution duration is set immediately to the maximum execution duration. A negative or null value means there is no restriction on the maximum execution duration: the execution could never end. Float values are not allowed. Default: |
3600000 (1 hour) | |
Output | ||||
output_formats | text |
Comma separated list of output formats for query results. Allowed values are: votable (or 'vot'), fits, text, csv, tsv, json and html. The VOTable format may be more detailed with the following syntax:
( The default VOTable format (i.e. serialization and version) is the one defined with the short form `votable`. It is be default set to `vot(binary,1.3)::votable` (see the special value `ALL` below). To change it just define a VOTable format with the short form `votable`. It is also possible to define a custom Separated Value format, different from
CSV and TSV, thanks to the following syntax:
sv( There is finally a last possible value: a class name of a class implementing OutputFormat and having at least one constructor with exactly one parameter of type tap.ServiceConnection. The special value output_formats = vot(binary,1.3)::votable, vot(td,1.3)::votable/td, vot(binary,1.3)::votable/b, vot(binary2,1.3)::votable/b2, vot(fits,1.3)::votable/fits, fits, csv, tsv, text, html,json Default: |
|
|
output_default_limit | text |
Default limit for the result output. The prefix "default" means here that this value will be set if the client does not provide one. This limit can be expressed in only one unit: rows. A negative value means there is no restriction on this limit. Float values are not allowed. Obviously this limit MUST be less or equal than output_max_limit. Default: |
|
|
output_max_limit | text |
Maximum limit for the result output. The prefix "max" means here that the client can not set a limit greater than this one. This limit can be expressed in only one unit: rows. A negative value means there is no restriction on this limit. Float values are not allowed. Obviously this limit MUST be greater or equal than output_default_limit. Default: |
|
|
Upload | ||||
upload_enabled | boolean |
Tells whether the Upload must be enabled. If enabled, files can be uploaded in the Note: Before being stored in the directory file_root_path, it is first
uploaded in the temporary directory (defined in the JVM ; generally
By default, the Upload is disabled: |
|
|
upload_default_db_limit | text |
Default limit for the number of uploaded records that can be inserted inside the database. This property is DEPRECATED. You should use Default: |
|
|
upload_max_db_limit | text |
Maximum limit for the number of uploaded records that can be inserted inside the database. This limit can be expressed with 2 types: rows or bytes. For rows, you just have to suffix the value by a "r" (upper- or lower-case), with nothing (by default, nothing will mean "rows"). For bytes, you have to suffix the numeric value by "B", "kB", "MB" or "GB". Here, unit is case sensitive. No other storage unit is allowed. A negative value means there is no restriction on this limit. Float values are not allowed. Important note: the specified limit will be checked at a different step of
a query processing in function of its unit.
If expressed in bytes, the file size will be checked when
uploading the file on disk. Thus, when the uploading file
starts to exceed the set limit, it will be no longer uploaded
and the whole request will be immediately rejected.
On the contrary, if the limit is expressed in rows, it will
be tested only when ingesting the whole uploaded file
(whatever is its size) in the database ; so, after it has been
uploaded. As soon as, the rows insertion in the database
exceeds the limit, the query is rejected.
Consequently, a very huge file could potentially be
completely uploaded before being rejected if this property is
expressed in rows. Then, it is very important to set the
property Default: |
|
|
upload_max_file_size | text |
Maximum allowed size for the uploaded file. This property is DEPRECATED. You should use Default: |
|
|
upload_max_request_size | text |
Maximum allowed size for a whole HTTP multipart request (i.e. request with uploads). This limit MUST be expressed in bytes. Thus, you have to suffix the numeric value by "B", "kB", "MB" or "GB". Here, unit is case sensitive. No other storage unit is allowed. A negative value means there is no restriction on this limit. Float values are not allowed. Warning: It is highly recommended to set this property in order to prevent
exceeding the disk storage space/quota (especially if
Default: |
|
|
User identification | ||||
user_identifier | text |
Class to use in order to identify a user of the TAP service. The same instance of this class will be used for every request sent to the service. The value of this property MUST be a class name (with brackets: {...}) of a class implementing the interface uws.service.UserIdentifier. This class MUST have one of its constructors with no parameter. By default, no identification is performed ; all users are then anonymous and their jobs can be seen by everybody. |
{apackage.FooUserIdentifier} | |
ADQL restrictions | ||||
coordinate_systems | text |
Comma-separated list of all allowed coordinate systems.
Each item of the list be a kind of regular expression respecting the following syntax:
Allowed values for Allowed values for Allowed values for
If the special value By default, any coordinate system is allowed. |
|
|
geometries | text |
Comma-separated list of all allowed geometries.
Each item of the list must be the name (whatever is the case) of an ADQL geometrical function (e.g. INTERSECTS, COORDSYS, POINT) to allow.
If the list is empty (no item), all functions are allowed. And if the special value By default, all ADQL geometrical functions are allowed. |
|
|
udfs | text |
Comma-separated list of all allowed UDFs (User Defined Functions).
Each item of the list must have the following syntax:
If the list is empty (no item), all unknown functions are forbidden. And if the special value By default, no unknown function is allowed. |
|
|
Additional TAP Resources | ||||
capabilities_stylesheet | text |
URL of the XSLT stylesheet to link with the XML output of /capabilities. By default, no XSLT stylesheet is defined. |
|
|
tables_stylesheet | text |
URL of the XSLT stylesheet to link with the XML output of /tables. By default, no XSLT stylesheet is defined. |
|
|
examples | text |
This property lets add an 3 different kinds of value are accepted:
Note:
If you want a custom By default, the TAP service does not have any |
|
|
additional_resources | text |
Comma-separated list of additional TAP resources/end-point. By default, the following standard TAP resources are already existing: /sync, /async, /tables, /capabilities and /availability. With this property, you can add a custom resource to your TAP service (e.g. /adqlValidator, /admin). Each item of the list MUST be the name of a class implementing tap.resource.TAPResource. This class MUST have at least one constructor with exactly one parameter of type tap.resource.TAP. The string returned by tap.resource.TAPResource.getName() will be the resource name, following the root TAP service URL (e.g. if getName() returns "foo", then its access URL will "{tapRoot}/foo"). Then, it is possible to replace TAP resources already existing by using the same name (e.g. if getName() returns "sync", the /sync resource won't be anymore the default Sync resource of this library but your new resource). By default, this list is empty ; only the standard TAP resources exist. |
{aPackage.QuickADQLValidator} | |
Custom TAP Factory | ||||
tap_factory | text |
Class to use in replacement of the default TAPFactory. This property must be a class name (given between {...}). It must reference an implementation of TAPFactory. This implementation must have at least one constructor with exactly one parameter of type ServiceConnection. It is recommended to extend an existing implementation such as: tap.AbstractTAPFactory or tap.config.ConfigurableTAPFactory. By default, the default TAPFactory (tap.config.ConfigurableTAPFactory) is used and may use all properties related to the backup management, the database access, the TAP_SCHEMA mapping and the ADQL translation. |
{aPackage.MyTAPFactory} |