public final class ConfigurableServiceConnection extends java.lang.Object implements ServiceConnection
ServiceConnection, fully parameterized
with a TAP configuration file.
Every aspects of the TAP service are configured here. This instance is also
creating the TAPFactory using the TAP configuration file thanks to
the implementation ConfigurableTAPFactory.
ServiceConnection.LimitUnit| Constructor and Description |
|---|
ConfigurableServiceConnection(java.util.Properties tapConfig)
Create a TAP service description thanks to the given TAP configuration
file.
|
ConfigurableServiceConnection(java.util.Properties tapConfig,
java.lang.String webAppRootDir)
Create a TAP service description thanks to the given TAP configuration
file.
|
| Modifier and Type | Method and Description |
|---|---|
void |
addOutputFormat(OutputFormat newOutputFormat)
Add the given
OutputFormat in the list of output formats supported by the TAP service. |
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]
|
protected static java.io.File |
getFile(java.lang.String filePath,
java.lang.String webAppRootPath,
java.lang.String propertyName)
Resolve the given file name/path.
|
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]
|
boolean |
removeOutputFormat(java.lang.String mimeOrAlias)
Remove the specified output format.
|
void |
setAvailable(boolean isAvailable,
java.lang.String message)
[MANDATORY]
|
boolean |
setDefaultExecutionDuration(int duration)
Set the default execution duration.
|
boolean |
setDefaultOutputLimit(int limit)
Set the default output limit.
|
boolean |
setDefaultRetentionPeriod(int period)
Set the default retention period.
|
boolean |
setDefaultUploadLimit(int limit)
Deprecated.
Since 2.3, use
setDefaultUploadLimit(long) instead. |
boolean |
setDefaultUploadLimit(long limit)
Set the default upload limit.
|
void |
setMaxExecutionDuration(int duration)
Set the maximum execution duration.
|
void |
setMaxOutputLimit(int limit)
Set the maximum output limit.
|
void |
setMaxRetentionPeriod(int period)
Set the maximum retention period.
|
void |
setMaxUploadLimit(int limit)
Deprecated.
Since 2.3, use
setMaxUploadLimit(long) instead. |
void |
setMaxUploadLimit(long limit)
Set the maximum upload limit.
|
boolean |
setMaxUploadSize(int maxSize)
Deprecated.
Since 2.3, use
setMaxUploadSize(long) instead. |
boolean |
setMaxUploadSize(long maxSize)
Set the maximum size of a VOTable files set that can be uploaded in once.
|
void |
setUploadEnabled(boolean enabled) |
void |
setUploadLimitType(ServiceConnection.LimitUnit type)
Set the unit of the upload limit.
|
boolean |
uploadEnabled()
[MANDATORY]
|
public ConfigurableServiceConnection(java.util.Properties tapConfig)
throws java.lang.NullPointerException,
TAPException
tapConfig - The content of the TAP configuration file.java.lang.NullPointerException - If the given properties set is NULL.TAPException - If a property is wrong or missing.public ConfigurableServiceConnection(java.util.Properties tapConfig,
java.lang.String webAppRootDir)
throws java.lang.NullPointerException,
TAPException
tapConfig - The content of the TAP configuration file.webAppRootDir - The directory of the Web Application running this
TAP service. In this directory another directory
may be created in order to store all TAP service
files if none is specified in the given TAP
configuration file.java.lang.NullPointerException - If the given properties set is NULL.TAPException - If a property is wrong or missing.protected static final java.io.File getFile(java.lang.String filePath,
java.lang.String webAppRootPath,
java.lang.String propertyName)
throws TAPException
Resolve the given file name/path.
If not an absolute path, the given path may be either relative or absolute. A relative path is always considered as relative from the Web Application directory (supposed to be given in 2nd parameter).
filePath - Path/Name of the file to get.webAppRootPath - Web Application directory local path.propertyName - Name of the property which gives the given file path.ParseException - If the given file path is a URI/URL.TAPExceptionpublic java.lang.String getProviderName()
ServiceConnectionName 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.
getProviderName in interface ServiceConnectionpublic java.lang.String getProviderDescription()
ServiceConnectionDescription of the service provider.
It will be used as additional information (INFO tag) in any VOTable output.
getProviderDescription in interface ServiceConnectionpublic boolean isAvailable()
ServiceConnectionThis 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 ServiceConnection.getAvailability().
isAvailable in interface ServiceConnectionpublic java.lang.String getAvailability()
ServiceConnectionGet 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.
getAvailability in interface ServiceConnectionpublic void setAvailable(boolean isAvailable,
java.lang.String message)
ServiceConnectionThis 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.
setAvailable in interface ServiceConnectionisAvailable - 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.public int[] getRetentionPeriod()
ServiceConnectionGet 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:
getRetentionPeriod in interface ServiceConnectionpublic boolean setDefaultRetentionPeriod(int period)
Set the default retention period.
This period is set by default if the user did not specify one before the execution of his query.
Important note: This function will apply the given retention period only if legal compared to the currently set maximum value. In other words, if the given value is less or equals to the current maximum retention period.
period - New default retention period (in seconds).public void setMaxRetentionPeriod(int period)
Set the maximum retention period.
This period limits the default retention period and the retention period specified by a user.
Important note: This function may reduce the default retention period if the current default retention period is bigger to the new maximum retention period. In a such case, the default retention period is set to the new maximum retention period.
period - New maximum retention period (in seconds).public int[] getExecutionDuration()
ServiceConnectionGet 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:
getExecutionDuration in interface ServiceConnectionpublic boolean setDefaultExecutionDuration(int duration)
Set the default execution duration.
This duration is set by default if the user did not specify one before the execution of his query.
Important note: This function will apply the given execution duration only if legal compared to the currently set maximum value. In other words, if the given value is less or equals to the current maximum execution duration.
duration - New default execution duration (in milliseconds).public void setMaxExecutionDuration(int duration)
Set the maximum execution duration.
This duration limits the default execution duration and the execution duration specified by a user.
Important note: This function may reduce the default execution duration if the current default execution duration is bigger to the new maximum execution duration. In a such case, the default execution duration is set to the new maximum execution duration.
duration - New maximum execution duration (in milliseconds).public java.util.Iterator<OutputFormat> getOutputFormats()
ServiceConnectionGet the list of all available output formats.
IMPORTANT:
getOutputFormats in interface ServiceConnectionpublic OutputFormat getOutputFormat(java.lang.String mimeOrAlias)
ServiceConnectionGet 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.
getOutputFormat in interface ServiceConnectionmimeOrAlias - MIME type or short MIME type of the format to get.OutputFormat or NULL if not found.public void addOutputFormat(OutputFormat newOutputFormat)
Add the given OutputFormat in the list of output formats supported by the TAP service.
Warning: No verification is done in order to avoid duplicated output formats in the list. NULL objects are merely ignored silently.
newOutputFormat - New output format.public boolean removeOutputFormat(java.lang.String mimeOrAlias)
mimeOrAlias - Full or short MIME type of the output format to remove.public int[] getOutputLimit()
ServiceConnectionGet 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 ServiceConnection.getOutputLimitType().
Important notes:
ServiceConnection.getOutputLimitType().
Particularly, the type given by the N-th item of ServiceConnection.getOutputLimitType() must correspond to the N-th limit returned by this function.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.
getOutputLimit in interface ServiceConnectionServiceConnection.getOutputLimitType()public boolean setDefaultOutputLimit(int limit)
Set the default output limit.
This limit is set by default if the user did not specify one before the execution of his query.
Important note: This function will apply the given output limit only if legal compared to the currently set maximum value. In other words, if the given value is less or equals to the current maximum output limit.
limit - New default output limit (in number of rows).public void setMaxOutputLimit(int limit)
Set the maximum output limit.
This output limit limits the default output limit and the output limit specified by a user.
Important note: This function may reduce the default output limit if the current default output limit is bigger to the new maximum output limit. In a such case, the default output limit is set to the new maximum output limit.
limit - New maximum output limit (in number of rows).public final ServiceConnection.LimitUnit[] getOutputLimitType()
ServiceConnectionGet the type of each output limit set by this service connection (and accessible with ServiceConnection.getOutputLimit()).
Important notes:
ServiceConnection.getOutputLimit().
Particularly, the type given by the N-th item of this function must correspond to the N-th limit returned by ServiceConnection.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.
getOutputLimitType in interface ServiceConnectionServiceConnection.getOutputLimit()public java.util.Collection<java.lang.String> getCoordinateSystems()
ServiceConnectionGet the list of all allowed coordinate systems.
Special valuesTwo special values can be returned by this function:
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:
({value1}|{value2}|...) (i.e. "(ICRS|FK4)"),
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.
getCoordinateSystems in interface ServiceConnectionpublic TAPLog getLogger()
ServiceConnectionGet 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.
getLogger in interface ServiceConnectionTAPLog.public TAPFactory getFactory()
ServiceConnectionGet 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.
getFactory in interface ServiceConnectionTAPFactory.AbstractTAPFactorypublic UWSFileManager getFileManager()
ServiceConnectionGet 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.
getFileManager in interface ServiceConnectionUWSFileManager.public boolean uploadEnabled()
ServiceConnectionThis 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.
uploadEnabled in interface ServiceConnectionpublic void setUploadEnabled(boolean enabled)
public long[] getUploadLimit()
ServiceConnectionGet 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 ServiceConnection.getUploadLimitType().
Important notes:
ServiceConnection.getUploadLimitType().
Particularly, the type given by the N-th item of
ServiceConnection.getUploadLimitType() must correspond to the N-th limit
returned by this function.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.
getUploadLimit in interface ServiceConnectionServiceConnection.getUploadLimitType()public ServiceConnection.LimitUnit[] getUploadLimitType()
ServiceConnectionGet the type of each upload limit set by this service connection (and
accessible with ServiceConnection.getUploadLimit()).
Important notes:
ServiceConnection.getUploadLimit().
Particularly, the type given by the N-th item of this function must
correspond to the N-th limit returned by ServiceConnection.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.
getUploadLimitType in interface ServiceConnectionServiceConnection.getUploadLimit()public void setUploadLimitType(ServiceConnection.LimitUnit type)
type - Unit of upload limit (rows or bytes).@Deprecated public boolean setDefaultUploadLimit(int limit)
setDefaultUploadLimit(long) instead.Important note: This function will apply the given upload limit only if legal compared to the currently set maximum value. In other words, if the given value is less or equals to the current maximum upload limit.
limit - New default upload limit.public boolean setDefaultUploadLimit(long limit)
Important note: This function will apply the given upload limit only if legal compared to the currently set maximum value. In other words, if the given value is less or equals to the current maximum upload limit.
limit - New default upload limit.@Deprecated public void setMaxUploadLimit(int limit)
setMaxUploadLimit(long) instead.This upload limit limits the default upload limit.
Important note: This function may reduce the default upload limit if the current default upload limit is bigger to the new maximum upload limit. In a such case, the default upload limit is set to the new maximum upload limit.
limit - New maximum upload limit.public void setMaxUploadLimit(long limit)
This upload limit limits the default upload limit.
Important note: This function may reduce the default upload limit if the current default upload limit is bigger to the new maximum upload limit. In a such case, the default upload limit is set to the new maximum upload limit.
limit - New maximum upload limit.public long getMaxUploadSize()
ServiceConnectionGet 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.
getMaxUploadSize in interface ServiceConnection@Deprecated public boolean setMaxUploadSize(int maxSize)
setMaxUploadSize(long) instead.Warning: This size can not be negative or 0. If the given value is in this case, nothing will be done and false will be returned. On the contrary to the other limits, no "unlimited" limit is possible here ; only the maximum value can be set (i.e. maximum positive integer value).
maxSize - New maximum size (in bytes).public boolean setMaxUploadSize(long maxSize)
Warning: This size can not be negative or 0. If the given value is in this case, nothing will be done and false will be returned. On the contrary to the other limits, no "unlimited" limit is possible here ; only the maximum value can be set (i.e. maximum positive integer value).
maxSize - New maximum size (in bytes).public int getNbMaxAsyncJobs()
ServiceConnectionGet 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.
getNbMaxAsyncJobs in interface ServiceConnectionpublic UserIdentifier getUserIdentifier()
ServiceConnectionGet the object to use in order to identify users at the origin of requests.
getUserIdentifier in interface ServiceConnectionUserIdentifier instance otherwise.public TAPMetadata getTAPMetadata()
ServiceConnectionGet 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.
getTAPMetadata in interface ServiceConnectionpublic java.util.Collection<java.lang.String> getGeometries()
ServiceConnectionGet the list of all allowed geometrical functions.
Special valuesTwo special values can be returned by this function:
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.
getGeometries in interface ServiceConnectionpublic java.util.Collection<FunctionDef> getUDFs()
ServiceConnectionGet the list of all allowed User Defined Functions (UDFs).
Special valuesTwo special values can be returned by this function:
Each item of the returned list MUST be an instance of FunctionDef.
getUDFs in interface ServiceConnectionpublic int[] getFetchSize()
ServiceConnectionGet 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.
getFetchSize in interface ServiceConnectionDBConnection 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.public boolean fixOnFailEnabled()
ServiceConnectionThis 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.
fixOnFailEnabled in interface ServiceConnection