ServiceConnection

All Known Implementing Classes:

ConfigurableServiceConnection
```
public interface ServiceConnection
```
Description and parameters list of a TAP service.
Through this object, it is possible to configure the different limits and formats, but also to list all available tables and columns, to declare geometry features as well as all allowed user defined functions and to say where log and other kinds of files must be stored.

Version:

2.3 (04/2019)

Author:

Grégory Mantelet (CDS;ARI)

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static class ServiceConnection.LimitUnit
List of possible limit units.

Nested Classes
Modifier and Type	Interface and Description
`static class`	`ServiceConnection.LimitUnit` List of possible limit units.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`boolean`	`fixOnFailEnabled()` [MANDATORY]
`java.lang.String`	`getAvailability()` [OPTIONAL]
`java.util.Collection<java.lang.String>`	`getCoordinateSystems()` [OPTIONAL]
`int[]`	`getExecutionDuration()` [OPTIONAL]
`TAPFactory`	`getFactory()` [MANDATORY]
`int[]`	`getFetchSize()` [OPTIONAL]
`UWSFileManager`	`getFileManager()` [MANDATORY]
`java.util.Collection<java.lang.String>`	`getGeometries()` [OPTIONAL]
`TAPLog`	`getLogger()` [MANDATORY]
`long`	`getMaxUploadSize()` [OPTIONAL]
`int`	`getNbMaxAsyncJobs()` [OPTIONAL]
`OutputFormat`	`getOutputFormat(java.lang.String mimeOrAlias)` [MANDATORY]
`java.util.Iterator<OutputFormat>`	`getOutputFormats()` [MANDATORY]
`int[]`	`getOutputLimit()` [OPTIONAL]
`ServiceConnection.LimitUnit[]`	`getOutputLimitType()` [OPTIONAL]
`java.lang.String`	`getProviderDescription()` [OPTIONAL]
`java.lang.String`	`getProviderName()` [OPTIONAL]
`int[]`	`getRetentionPeriod()` [OPTIONAL]
`TAPMetadata`	`getTAPMetadata()` [MANDATORY]
`java.util.Collection<FunctionDef>`	`getUDFs()` [OPTIONAL]
`long[]`	`getUploadLimit()` [OPTIONAL]
`ServiceConnection.LimitUnit[]`	`getUploadLimitType()` [OPTIONAL]
`UserIdentifier`	`getUserIdentifier()` [OPTIONAL]
`boolean`	`isAvailable()` [MANDATORY]
`void`	`setAvailable(boolean isAvailable, java.lang.String message)` [MANDATORY]
`boolean`	`uploadEnabled()` [MANDATORY]

- Method Detail
  - getProviderName
```
java.lang.String getProviderName()
```
    [OPTIONAL]
    Name of the service provider ; it can be an organization as an individual person.
    
    There is no restriction on the syntax or on the label to use ; this information is totally free
    
    It will be used as additional information (INFO tag) in any VOTable and HTML output.
    
    Returns:
    
    The TAP service provider or NULL to leave this field blank.
  - getProviderDescription
```
java.lang.String getProviderDescription()
```
    [OPTIONAL]
    Description of the service provider.
    
    It will be used as additional information (INFO tag) in any VOTable output.
    
    Returns:
    
    The TAP service description or NULL to leave this field blank.
  - isAvailable
```
boolean isAvailable()
```
    [MANDATORY]
    This function tells whether the TAP service is available (that's to say, "able to execute requests" ; resources like /availability, /capabilities and /tables may still work).
    
    A message explaining the current state of the TAP service could be provided thanks to getAvailability().
    
    Returns:
    
    true to enable all TAP resources, false to disable all of them (except /availability).
  - getAvailability
```
java.lang.String getAvailability()
```
    [OPTIONAL]
    Get an explanation about the current TAP service state (working or not). This message aims to provide more details to the users about the availability of this service, or more particularly about its unavailability.
    
    Returns:
    
    Explanation about the TAP service state.
  - setAvailable
```
void setAvailable(boolean isAvailable,
                  java.lang.String message)
```
    [MANDATORY]
    This function sets the state of the whole TAP service. If true, all TAP resources will be able to execute resources. If false, /sync and /async won't answer any more to requests and a HTTP-503 (Service unavailable) error will be returned.
    
    Parameters:
    
    isAvailable - true to enable all resources, false to forbid /sync and /async (all other resources will still be available).
    
    message - A message describing the current state of the service. If NULL, a default message may be set by the library.
    
    Since:
    
    2.0
  - getRetentionPeriod
```
int[] getRetentionPeriod()
```
    [OPTIONAL]
    Get the limit of the retention period (in seconds).
    
    It is the maximum period while an asynchronous job can leave in the jobs list and so can stay on the server.
    
    Important notes:
    - Exactly 2 values or a NULL object is expected here.
    - If NULL, the retention period is not limited and jobs will theoretically stay infinitely on the server.
    - If not NULL, the 2 values must correspond to the default retention period and the maximum retention period.
    - The default value is used to set the retention period when a job is created with no user defined retention period.
    - The maximum value is used to limit the retention period when specified by the user while creating a job.
    - The default value MUST be less or equals the maximum value.
    - Both values must be positive. If a negative value is given it will be interpreted as "no limit".
    Returns:
    
    NULL if no limit must be set, or a two-items array ([0]: default value, [1]: maximum value).
  - getExecutionDuration
```
int[] getExecutionDuration()
```
    [OPTIONAL]
    Get the limit of the job execution duration (in milliseconds).
    
    It is the duration of a running job (including the query execution). This duration is used for synchronous AND asynchronous jobs.
    
    Important notes:
    - Exactly 2 values or a NULL object is expected here.
    - If NULL, the execution duration is not limited and jobs could theoretically run infinitely.
    - If not NULL, the 2 values must correspond to the default execution duration and the maximum execution duration.
    - The default value is used to set the execution duration when a job is created with no user defined execution duration.
    - The maximum value is used to limit the execution duration when specified by the user while creating a job.
    - The default value MUST be less or equals the maximum value.
    - Both values must be positive. If a negative value is given it will be interpreted as "no limit".
    Returns:
    
    NULL if no limit must be set, or a two-items array ([0]: default value, [1]: maximum value).
  - getOutputLimit
```
int[] getOutputLimit()
```
    [OPTIONAL]
    Get the limit of the job execution result.
    
    This value will limit the size of the query results, either in rows or in bytes. The type of limit is defined by the function getOutputLimitType().
    
    Important notes:
    - Exactly 2 values or a NULL object is expected here.
    - If NULL, the output limit is not limited and jobs could theoretically return very big files.
    - If not NULL, the 2 values must correspond to the default output limit and the maximum output limit.
    - The default value is used to set the output limit when a job is created with no user defined output limit.
    - The maximum value is used to limit the output limit when specified by the user while creating a job.
    - The structure of the object returned by this function MUST be the same as the object returned by getOutputLimitType(). Particularly, the type given by the N-th item of getOutputLimitType() must correspond to the N-th limit returned by this function.
    - The default value MUST be less or equals the maximum value.
    - Both values must be positive. If a negative value is given it will be interpreted as "no limit".
    Important note: Currently, the default implementations of the library is only able to deal with output limits in ROWS.
    Anyway, in order to save performances, it is strongly recommended to use ROWS limit rather than in bytes. Indeed, the rows limit can be taken into account at the effective execution of the query (so before getting the result), on the contrary of the bytes limit which will be applied on the query result.
    Returns:
    
    NULL if no limit must be set, or a two-items array ([0]: default value, [1]: maximum value).
    
    See Also:
    
    getOutputLimitType()
  - getOutputLimitType
```
ServiceConnection.LimitUnit[] getOutputLimitType()
```
    [OPTIONAL]
    Get the type of each output limit set by this service connection (and accessible with getOutputLimit()).
    
    Important notes:
    - Exactly 2 values or a NULL object is expected here.
    - If NULL, the output limit will be considered as expressed in ROWS.
    - The structure of the object returned by this function MUST be the same as the object returned by getOutputLimit(). Particularly, the type given by the N-th item of this function must correspond to the N-th limit returned by getOutputLimit().
    Important note: Currently, the default implementations of the library is only able to deal with output limits in ROWS.
    Anyway, in order to save performances, it is strongly recommended to use ROWS limit rather than in bytes. Indeed, the rows limit can be taken into account at the effective execution of the query (so before getting the result), on the contrary of the bytes limit which will be applied on the query result.
    Returns:
    
    NULL if limits should be expressed in ROWS, or a two-items array ([0]: type of getOutputLimit()[0], [1]: type of getOutputLimit()[1]).
    
    See Also:
    
    getOutputLimit()
  - getUserIdentifier
```
UserIdentifier getUserIdentifier()
```
    [OPTIONAL]
    Get the object to use in order to identify users at the origin of requests.
    
    Returns:
    
    NULL if no user identification should be done, a UserIdentifier instance otherwise.
  - uploadEnabled
```
boolean uploadEnabled()
```
    [MANDATORY]
    This function lets enable or disable the upload capability of this TAP service.
    
    Note: If the upload is disabled, the request is aborted and an HTTP-400 error is thrown each time some tables are uploaded.
    
    Returns:
    
    true to enable the upload capability, false to disable it.
  - getUploadLimit
```
long[] getUploadLimit()
```
    [OPTIONAL]
    Get the maximum size of EACH uploaded table.
    
    This value is expressed either in rows or in bytes. The unit limit is defined by the function getUploadLimitType().
    
    Important notes:
    - Exactly 2 values or a NULL object is expected here.
    - If NULL, the upload limit is not limited and uploads could be theoretically unlimited.
    - If not NULL, the 2 values must correspond to the default upload limit and the maximum upload limit.
    - The default value is used to inform the user about the server wishes. In this version of TAPLib, this value is never used, whatever is its value. It is defined here only in case the TAP protocol evolves and allow a such default value for UPLOAD limits.
    - The maximum value is used to really limit the upload limit.
    - The structure of the object returned by this function MUST be the same as the object returned by getUploadLimitType(). Particularly, the type given by the N-th item of getUploadLimitType() must correspond to the N-th limit returned by this function.
    - The default value MUST be less or equals the maximum value.
    - Both values must be positive. If a negative value is given it will be interpreted as "no limit".
    Important note: To save performances, it is recommended to use BYTES limit rather than in rows. Indeed, the bytes limit can be taken into account at directly when reading the bytes of the request, on the contrary of the rows limit which requires to parse the uploaded tables.
    Returns:
    
    NULL if no limit must be set, or a two-items array ([0]: default value, [1]: maximum value).
    
    See Also:
    
    getUploadLimitType()
  - getUploadLimitType
```
ServiceConnection.LimitUnit[] getUploadLimitType()
```
    [OPTIONAL]
    Get the type of each upload limit set by this service connection (and accessible with getUploadLimit()).
    
    Important notes:
    - Exactly 2 values or a NULL object is expected here.
    - If NULL, the upload limit will be considered as expressed in ROWS.
    - The structure of the object returned by this function MUST be the same as the object returned by getUploadLimit(). Particularly, the type given by the N-th item of this function must correspond to the N-th limit returned by getUploadLimit().
    Important note: To save performances, it is recommended to use BYTES limit rather than in rows. Indeed, the bytes limit can be taken into account at directly when reading the bytes of the request, on the contrary of the rows limit which requires to parse the uploaded tables.
    Returns:
    
    NULL if limits should be expressed in ROWS, or a two-items array ([0]: type of getUploadLimit()[0], [1]: type of getUploadLimit()[1]).
    
    See Also:
    
    getUploadLimit()
  - getMaxUploadSize
```
long getMaxUploadSize()
```
    [OPTIONAL]
    Get the maximum size of the whole set of all tables uploaded in one request. This size is expressed in bytes.
    
    NOTE: This value can be negative. In such case, there will be no limit on the size of an HTTP request.
    
    Returns:
    
    A positive value (>0) corresponding to the maximum number of bytes of all uploaded tables sent in one request. A negative value (≤0) means "unlimited".
  - getTAPMetadata
```
TAPMetadata getTAPMetadata()
```
    [MANDATORY]
    Get the list of all available tables and columns.
    
    This object is really important since it lets the library check ADQL queries properly and set the good type and formatting in the query results.
    
    Returns:
    
    A TAPMetadata object. NULL is not allowed and will throw a grave error at the service initialization.
  - getCoordinateSystems
```
java.util.Collection<java.lang.String> getCoordinateSystems()
```
    [OPTIONAL]
    Get the list of all allowed coordinate systems.
    Special values
    Two special values can be returned by this function:
    - NULL which means that all coordinate systems are allowed,
    - the empty list which means that no coordinate system - except the default one (which can be reduced to an empty string) - is allowed.
    List item syntax
    Each item of this list is a pattern and not a simple coordinate system. Thus each item MUST respect the following syntax:
```
{framePattern} {refposPattern} {flavorPattern}
```
    Contrary to a coordinate system expression, all these 3 information are required. Each may take 3 kinds of value:
    - a single value (i.e. "ICRS"),
    - a list of values with the syntax ({value1}|{value2}|...) (i.e. "(ICRS|FK4)"),
    - a "*" which means that all values are possible.
    For instance: (ICRS|FK4) HELIOCENTER * is a good syntax, but not ICRS or ICRS HELIOCENTER.
    
    Note: Even if not explicitly part of the possible values, the default value of each part (i.e. UNKNOWNFRAME for frame) is always taken into account by the library. Particularly, the empty string will always be allowed even if not explicitly listed in the list returned by this function.
    Returns:
    
    NULL to allow ALL coordinate systems, an empty list to allow NO coordinate system, or a list of coordinate system patterns otherwise.
  - getGeometries
```
java.util.Collection<java.lang.String> getGeometries()
```
    [OPTIONAL]
    Get the list of all allowed geometrical functions.
    Special values
    Two special values can be returned by this function:
    - NULL which means that all geometrical functions are allowed,
    - the empty list which means that no geometrical functions is allowed.
    List item syntax
    Each item of the returned list MUST be a function name (i.e. "CONTAINS", "POINT"). It can also be a type of STC region to forbid (i.e. "POSITION", "UNION").
    
    The given names are not case sensitive.
    Returns:
    
    NULL to allow ALL geometrical functions, an empty list to allow NO geometrical function, or a list of geometrical function names otherwise.
    
    Since:
    
    2.0
  - getUDFs
```
java.util.Collection<FunctionDef> getUDFs()
```
    [OPTIONAL]
    Get the list of all allowed User Defined Functions (UDFs).
    Special values
    Two special values can be returned by this function:
    - NULL which means that all unknown functions (which should be UDFs) are allowed,
    - the empty list which means that no unknown functions (which should be UDFs) is allowed.
    List item syntax
    Each item of the returned list MUST be an instance of FunctionDef.
    Returns:
    
    NULL to allow ALL unknown functions, an empty list to allow NO unknown function, or a list of user defined functions otherwise.
    
    Since:
    
    2.0
  - getNbMaxAsyncJobs
```
int getNbMaxAsyncJobs()
```
    [OPTIONAL]
    Get the maximum number of asynchronous jobs that can run in the same time.
    
    A null or negative value means no limit on the number of running asynchronous jobs.
    
    Returns:
    
    Maximum number of running jobs (≤0 => no limit).
    
    Since:
    
    2.0
  - getLogger
```
TAPLog getLogger()
```
    [MANDATORY]
    Get the logger to use in the whole service when any error, warning or info happens.
    
    IMPORTANT: If NULL is returned by this function, grave errors will occur while executing a query or managing an error. It is strongly recommended to provide a logger, even a basic implementation.
    
    Piece of advice: A default implementation like DefaultTAPLog would be most of time largely enough.
    
    Returns:
    
    An instance of TAPLog.
  - getFactory
```
TAPFactory getFactory()
```
    [MANDATORY]
    Get the object able to build other objects essentials to configure the TAP service or to run every queries.
    
    IMPORTANT: If NULL is returned by this function, grave errors will occur while initializing the service.
    
    Piece of advice: The TAPFactory is an interface which contains a lot of functions to implement. It is rather recommended to extend AbstractTAPFactory: just 2 functions (TAPFactory.freeConnection(DBConnection) and TAPFactory.getConnection(String)) will have to be implemented.
    
    Returns:
    
    An instance of TAPFactory.
    
    See Also:
    
    AbstractTAPFactory
  - getFileManager
```
UWSFileManager getFileManager()
```
    [MANDATORY]
    Get the object in charge of the files management. This object manages log, error, result and backup files of the whole service.
    
    IMPORTANT: If NULL is returned by this function, grave errors will occur while initializing the service.
    
    Piece of advice: The library provides a default implementation of the interface UWSFileManager: LocalUWSFileManager, which stores all files on the local file-system.
    
    Returns:
    
    An instance of UWSFileManager.
  - getOutputFormats
```
java.util.Iterator<OutputFormat> getOutputFormats()
```
    [MANDATORY]
    Get the list of all available output formats.
    
    IMPORTANT:
    - All formats of this list MUST have a different MIME type.
    - At least one item must correspond to the MIME type "votable".
    - If NULL is returned by this function, grave errors will occur while writing the capabilities of this service.
    Returns:
    
    An iterator on the list of all available output formats.
  - getOutputFormat
```
OutputFormat getOutputFormat(java.lang.String mimeOrAlias)
```
    [MANDATORY]
    Get the output format having the given MIME type (or short MIME type ~ alias).
    
    IMPORTANT: This function MUST always return an OutputFormat instance when the MIME type "votable" is given in parameter.
    
    Parameters:
    
    mimeOrAlias - MIME type or short MIME type of the format to get.
    
    Returns:
    
    The corresponding OutputFormat or NULL if not found.
  - getFetchSize
```
int[] getFetchSize()
```
    [OPTIONAL]
    Get the size of result blocks to fetch from the database.
    
    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 by this function. 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).
    
    Note: Generally, this feature is well supported by DBMS. But for that, the used JDBC driver must use the V3 protocol. If anyway, this feature is supported neither by the DBMS, the JDBC driver nor your DBConnection, no error will be thrown if a value is returned by this function: it will be silently ignored by the library.
    
    Returns:
    
    null or an array of 1 or 2 integers. If null (or empty array), no attempt to set fetch size will be done and so, ONLY the default value of the DBConnection will be used. [0]=fetchSize for async queries, [1]=fetchSize for sync queries. If [1] is omitted, it will be considered as equals to [0]. If a fetchSize is negative or null, the default value of your JDBC driver will be used.
    
    Since:
    
    2.0
  - fixOnFailEnabled
```
boolean fixOnFailEnabled()
```
    [MANDATORY]
    This function tells whether TAP-Lib should automatically try to fix a query whose parsing failed because of a token error. After this fix attempt the query is parsed again for a last time.
    
    Returns:
    
    true to allow automatic fix attempt in case of error, false to disable this option.
    
    Since:
    
    2.3

Interface ServiceConnection

Nested Class Summary

Method Summary

Method Detail

getProviderName

getProviderDescription

isAvailable

getAvailability

setAvailable

getRetentionPeriod

getExecutionDuration

getOutputLimit

getOutputLimitType

getUserIdentifier

uploadEnabled

getUploadLimit

getUploadLimitType

getMaxUploadSize

getTAPMetadata

getCoordinateSystems

getGeometries

getUDFs

getNbMaxAsyncJobs

getLogger

getFactory

getFileManager

getOutputFormats

getOutputFormat

getFetchSize

fixOnFailEnabled