Commit 4283809b authored by gmantele's avatar gmantele
Browse files

[TAP] Add Javadoc for all TAP configuration file related classes + Improve the... 

[TAP] Add Javadoc for all TAP configuration file related classes + Improve the function ConfigurableServiceConnection.getFile(...) + Set the default value of limits/durations/periods to the maximum value if the new maximum value is less than the current default value.
parent d801186a

src/tap/ServiceConnection.java

+2 −2
Original line number Diff line number Diff line
@@ -243,7 +243,7 @@ public interface ServiceConnection { 


	/**

	 * <i>[OPTIONAL]</i>

	 * <p>Get the limit of the retention period.</p>

	 * <p>Get the limit of the retention period (in seconds).</p>

	 * 

	 * <p>

	 * 	It is the maximum period while an asynchronous job can leave in the jobs list
@@ -269,7 +269,7 @@ public interface ServiceConnection { 


	/**

	 * <i>[OPTIONAL]</i>

	 * <p>Get the limit of the job execution duration.</p>

	 * <p>Get the limit of the job execution duration (in milliseconds).</p>

	 * 

	 * <p>

	 * 	It is the duration of a running job (including the query execution).

src/tap/config/ConfigurableServiceConnection.java

+417 −54

File changed.

Preview size limit exceeded, changes collapsed.

src/tap/config/ConfigurableTAPFactory.java

+35 −0
Original line number Diff line number Diff line
@@ -52,6 +52,7 @@ import javax.sql.DataSource; 
import tap.AbstractTAPFactory;

import tap.ServiceConnection;

import tap.TAPException;

import tap.TAPFactory;

import tap.backup.DefaultTAPBackupManager;

import tap.db.DBConnection;

import tap.db.JDBCConnection;
@@ -64,25 +65,59 @@ import adql.translator.PgSphereTranslator; 
import adql.translator.PostgreSQLTranslator;



/**

 * <p>Concrete implementation of a {@link TAPFactory} which is parameterized by a TAP configuration file.</p>

 * 

 * <p>

 * 	All abstract or NULL-implemented methods/functions left by {@link AbstractTAPFactory} are implemented using values

 *  of a TAP configuration file. The concerned methods are: {@link #getConnection(String)}, {@link #freeConnection(DBConnection)},

 *  {@link #destroy()}, {@link #createADQLTranslator()} and {@link #createUWSBackupManager(UWSService)}.

 * </p>

 * 

 * @author Gr&eacute;gory Mantelet (ARI)

 * @version 2.0 (04/2015)

 * @since 2.0

 */

public final class ConfigurableTAPFactory extends AbstractTAPFactory {



	/* ADQL to SQL translation: */

	/** The {@link JDBCTranslator} to use when a ADQL query must be executed in the database.

	 * This translator is also used to convert ADQL types into database types. */

	private Class<? extends JDBCTranslator> translator;



	/* JNDI DB access: */

	/** The {@link DataSource} to use in order to access the database.

	 * <em>This attribute is actually used only if the chosen database access method is JNDI.</em> */

	private final DataSource datasource;



	/* Simple JDBC access: */

	/** Classpath of the JDBC driver to use in order to access the database.

	 * <em>This attribute is actually used only if the chosen database access method is JDBC.</em> */

	private final String driverPath;

	/** JDBC URL of the database to access.

	 * <em>This attribute is actually used only if the chosen database access method is JDBC.</em> */

	private final String dbUrl;

	/** Name of the database user to use in order to access the database.

	 * <em>This attribute is actually used only if the chosen database access method is JDBC.</em> */

	private final String dbUser;

	/** Password of the database user to use in order to access the database.

	 * <em>This attribute is actually used only if the chosen database access method is JDBC.</em> */

	private final String dbPassword;



	/* UWS's jobs backup: */

	/** Indicate whether the jobs must be backuped gathered by user or just all mixed together. */

	private boolean backupByUser;

	/** Frequency at which the jobs must be backuped. */

	private long backupFrequency;



	/**

	 * Build a {@link TAPFactory} using the given TAP service description and TAP configuration file.

	 * 

	 * @param service		The TAP service description.

	 * @param tapConfig		The TAP configuration file containing particularly information about the database access.

	 * 

	 * @throws NullPointerException	If one of the parameter is NULL.

	 * @throws TAPException			If some properties of the TAP configuration file are wrong.

	 */

	public ConfigurableTAPFactory(ServiceConnection service, final Properties tapConfig) throws NullPointerException, TAPException{

		super(service);

src/tap/config/ConfigurableTAPServlet.java

+19 −3
Original line number Diff line number Diff line
@@ -47,14 +47,22 @@ import tap.resource.TAP; 
import tap.resource.TAPResource;



/**

 * <p>HTTP servlet fully configured with a TAP configuration file.</p>

 * 

 * <p>

 * 	This configuration file may be specified in the initial parameter named {@value TAPConfiguration#TAP_CONF_PARAMETER}

 * 	of this servlet inside the WEB-INF/web.xml file. If none is specified, the file {@value TAPConfiguration#DEFAULT_TAP_CONF_FILE}

 * 	will be searched inside the directories of the classpath, and inside WEB-INF and META-INF.

 * </p>

 * 

 * @author Gr&eacute;gory Mantelet (ARI)

 * @version 2.0 (03/2015)

 * @version 2.0 (04/2015)

 * @since 2.0

 */

public class ConfigurableTAPServlet extends HttpServlet {

	private static final long serialVersionUID = 1L;



	/** TAP object representing the TAP service. */

	private TAP tap = null;



	@Override
@@ -171,6 +179,16 @@ public class ConfigurableTAPServlet extends HttpServlet { 
		serviceConn.setAvailable(true, "TAP service available.");

	}



	/**

	 * Search the given file name/path in the directories of the classpath, then inside WEB-INF and finally inside META-INF.

	 * 

	 * @param filePath	A file name/path.

	 * @param config	Servlet configuration (containing also the context class loader - link with the servlet classpath).

	 * 

	 * @return	The input stream toward the specified file, or NULL if no file can be found.

	 * 

	 * @since 2.0

	 */

	protected final InputStream searchFile(String filePath, final ServletConfig config){

		InputStream input = null;
@@ -207,8 +225,6 @@ public class ConfigurableTAPServlet extends HttpServlet { 
			try{

				tap.executeRequest(req, resp);

			}catch(Throwable t){

				System.err.println("Request aborted !");

				t.printStackTrace(System.err);

				resp.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR, t.getMessage());

			}

		}else

src/tap/config/TAPConfiguration.java

+83 −0
Original line number Diff line number Diff line
@@ -26,6 +26,7 @@ import java.util.Properties; 


import tap.ServiceConnection.LimitUnit;

import tap.TAPException;

import tap.TAPFactory;

import tap.backup.DefaultTAPBackupManager;



/**
@@ -105,27 +106,53 @@ public final class TAPConfiguration { 
	public final static boolean DEFAULT_BACKUP_BY_USER = false;



	/* ASYNCHRONOUS JOBS */

	/** Name/Key of the property specifying the maximum number of asynchronous jobs that can run simultaneously.

	 * A negative or null value means "no limit". */

	public final static String KEY_MAX_ASYNC_JOBS = "max_async_jobs";

	/** Default value of the property {@link #KEY_MAX_ASYNC_JOBS}: {@value #DEFAULT_MAX_ASYNC_JOBS}. */

	public final static int DEFAULT_MAX_ASYNC_JOBS = 0;



	/* EXECUTION DURATION */

	/** Name/Key of the property specifying the default execution duration (in milliseconds) set automatically to a job

	 * if none has been specified by the user. */

	public final static String KEY_DEFAULT_EXECUTION_DURATION = "default_execution_duration";

	/** Name/Key of the property specifying the maximum execution duration (in milliseconds) that can be set on a job. */

	public final static String KEY_MAX_EXECUTION_DURATION = "max_execution_duration";

	/** Default value of the property {@link #KEY_DEFAULT_EXECUTION_DURATION} and {@link #KEY_MAX_EXECUTION_DURATION}: {@value #DEFAULT_EXECUTION_DURATION}. */

	public final static int DEFAULT_EXECUTION_DURATION = 0;



	/* DATABASE KEYS */

	/** Name/Key of the property specifying the database access method to use. */

	public final static String KEY_DATABASE_ACCESS = "database_access";

	/** Value of the property {@link #KEY_DATABASE_ACCESS} to select the simple JDBC method.  */

	public final static String VALUE_JDBC = "jdbc";

	/** Value of the property {@link #KEY_DATABASE_ACCESS} to access the database using a DataSource stored in JNDI.  */

	public final static String VALUE_JNDI = "jndi";

	/** Name/Key of the property specifying the ADQL to SQL translator to use. */

	public final static String KEY_SQL_TRANSLATOR = "sql_translator";

	/** Value of the property {@link #KEY_SQL_TRANSLATOR} to select a PostgreSQL translator (no support for geometrical functions). */

	public final static String VALUE_POSTGRESQL = "postgres";

	/** Value of the property {@link #KEY_SQL_TRANSLATOR} to select a PgSphere translator. */

	public final static String VALUE_PGSPHERE = "pgsphere";

	/** Name/Key of the property specifying by how many rows the library should fetch a query result from the database.

	 * This is the fetch size for to apply for synchronous queries. */

	public final static String KEY_SYNC_FETCH_SIZE = "sync_fetch_size";

	/** Default value of the property {@link #KEY_SYNC_FETCH_SIZE}: {@value #DEFAULT_SYNC_FETCH_SIZE}. */

	public final static int DEFAULT_SYNC_FETCH_SIZE = 10000;

	/** Name/Key of the property specifying by how many rows the library should fetch a query result from the database.

	 * This is the fetch size for to apply for asynchronous queries. */

	public final static String KEY_ASYNC_FETCH_SIZE = "async_fetch_size";

	/** Default value of the property {@link #KEY_ASYNC_FETCH_SIZE}: {@value #DEFAULT_ASYNC_FETCH_SIZE}. */

	public final static int DEFAULT_ASYNC_FETCH_SIZE = 100000;

	/** Name/Key of the property specifying the name of the DataSource into the JDNI. */

	public final static String KEY_DATASOURCE_JNDI_NAME = "datasource_jndi_name";

	/** Name/Key of the property specifying the full class name of the JDBC driver.

	 * Alternatively, a shortcut the most known JDBC drivers can be used. The list of these drivers is stored

	 * in {@link #VALUE_JDBC_DRIVERS}. */

	public final static String KEY_JDBC_DRIVER = "jdbc_driver";

	/** List of the most known JDBC drivers. For the moment this list contains 4 drivers:

	 * oracle ("oracle.jdbc.OracleDriver"), postgresql ("org.postgresql.Driver"), mysql ("com.mysql.jdbc.Driver")

	 * and sqlite ("org.sqlite.JDBC"). */

	public final static HashMap<String,String> VALUE_JDBC_DRIVERS = new HashMap<String,String>(4);

	static{

		VALUE_JDBC_DRIVERS.put("oracle", "oracle.jdbc.OracleDriver");
@@ -133,60 +160,116 @@ public final class TAPConfiguration { 
		VALUE_JDBC_DRIVERS.put("mysql", "com.mysql.jdbc.Driver");

		VALUE_JDBC_DRIVERS.put("sqlite", "org.sqlite.JDBC");

	}

	/** Name/Key of the property specifying the JDBC URL of the database to access. */

	public final static String KEY_JDBC_URL = "jdbc_url";

	/** Name/Key of the property specifying the database user name to use to access the database. */

	public final static String KEY_DB_USERNAME = "db_username";

	/** Name/Key of the property specifying the password of the database user. */

	public final static String KEY_DB_PASSWORD = "db_password";



	/* METADATA KEYS */

	/** Name/Key of the property specifying where the list of schemas, tables and columns and their respective metadata

	 * is provided. */

	public final static String KEY_METADATA = "metadata";

	/** Value of the property {@link #KEY_METADATA} which indicates that metadata are provided in an XML file, whose the

	 * local path is given by the property {@link #KEY_METADATA_FILE}. */

	public final static String VALUE_XML = "xml";

	/** Value of the property {@link #KEY_METADATA} which indicates that metadata are already in the TAP_SCHEMA of the database. */

	public final static String VALUE_DB = "db";

	/** Name/Key of the property specifying the local file path of the XML file containing the TAP metadata to load. */

	public final static String KEY_METADATA_FILE = "metadata_file";



	/* HOME PAGE KEY */

	/** Name/Key of the property specifying the TAP home page to use.

	 * It can be a file, a URL or a class. If null, the default TAP home page of the library is used.

	 * By default the default library home page is used. */

	public final static String KEY_HOME_PAGE = "home_page";

	/** Name/Key of the property specifying the MIME type of the set home page.

	 * By default, "text/html" is set. */

	public final static String KEY_HOME_PAGE_MIME_TYPE = "home_page_mime_type";



	/* PROVIDER KEYS */

	/** Name/Key of the property specifying the name of the organization/person providing the TAP service. */

	public final static String KEY_PROVIDER_NAME = "provider_name";

	/** Name/Key of the property specifying the description of the TAP service. */

	public final static String KEY_SERVICE_DESCRIPTION = "service_description";



	/* UPLOAD KEYS */

	/** Name/Key of the property indicating whether the UPLOAD feature must be enabled or not.

	 * By default, this feature is disabled. */

	public final static String KEY_UPLOAD_ENABLED = "upload_enabled";

	/** Name/Key of the property specifying the default limit (in rows or bytes) on the uploaded VOTable(s). */

	public final static String KEY_DEFAULT_UPLOAD_LIMIT = "upload_default_db_limit";

	/** Name/Key of the property specifying the maximum limit (in rows or bytes) on the uploaded VOTable(s). */

	public final static String KEY_MAX_UPLOAD_LIMIT = "upload_max_db_limit";

	/** Name/Key of the property specifying the maximum size of all VOTable(s) uploaded in a query. */

	public final static String KEY_UPLOAD_MAX_FILE_SIZE = "upload_max_file_size";

	/** Default value of the property {@link #KEY_UPLOAD_MAX_FILE_SIZE}: {@value #DEFAULT_UPLOAD_MAX_FILE_SIZE}.  */

	public final static int DEFAULT_UPLOAD_MAX_FILE_SIZE = Integer.MAX_VALUE;



	/* OUTPUT KEYS */

	/** Name/Key of the property specifying the list of all result output formats to support.

	 * By default all formats provided by the library are allowed. */

	public final static String KEY_OUTPUT_FORMATS = "output_formats";

	/** Value of the property {@link #KEY_OUTPUT_FORMATS} which select all formats that the library can provide. */

	public final static String VALUE_ALL = "ALL";

	/** Value of the property {@link #KEY_OUTPUT_FORMATS} which select a VOTable format.

	 * The format can be parameterized with the VOTable version and serialization. */

	public final static String VALUE_VOTABLE = "votable";

	/** Value of the property {@link #KEY_OUTPUT_FORMATS} which select a VOTable format.

	 * The format can be parameterized with the VOTable version and serialization.

	 * <em>This value is just an alias of {@link #VALUE_VOTABLE}.</em> */

	public final static String VALUE_VOT = "vot";

	/** Value of the property {@link #KEY_OUTPUT_FORMATS} which select a FITS format. */

	public final static String VALUE_FITS = "fits";

	/** Value of the property {@link #KEY_OUTPUT_FORMATS} which select a JSON format. */

	public final static String VALUE_JSON = "json";

	/** Value of the property {@link #KEY_OUTPUT_FORMATS} which select an HTML format. */

	public final static String VALUE_HTML = "html";

	/** Value of the property {@link #KEY_OUTPUT_FORMATS} which select a human-readable table. */

	public final static String VALUE_TEXT = "text";

	/** Value of the property {@link #KEY_OUTPUT_FORMATS} which select a CSV format. */

	public final static String VALUE_CSV = "csv";

	/** Value of the property {@link #KEY_OUTPUT_FORMATS} which select a TSV format. */

	public final static String VALUE_TSV = "tsv";

	/** Value of the property {@link #KEY_OUTPUT_FORMATS} which select a Separated-Value format.

	 * <em>This value must be parameterized with the separator to use.</em> */

	public final static String VALUE_SV = "sv";

	/** Name/Key of the property specifying the number of result rows that should be returned if none is specified by the user. */

	public final static String KEY_DEFAULT_OUTPUT_LIMIT = "output_default_limit";

	/** Name/Key of the property specifying the maximum number of result rows that can be returned by the TAP service. */

	public final static String KEY_MAX_OUTPUT_LIMIT = "output_max_limit";



	/* USER IDENTIFICATION */

	/** Name/Key of the property specifying the user identification method to use.

	 * None is implemented by the library, so a class must be provided as value of this property. */

	public final static String KEY_USER_IDENTIFIER = "user_identifier";



	/* ADQL RESTRICTIONS */

	/** Name/Key of the property specifying the list of all allowed coordinate systems that can be used in ADQL queries.

	 * By default, all are allowed, but no conversion is done by the library. */

	public final static String KEY_COORD_SYS = "coordinate_systems";

	/** Name/Key of the property specifying the list of all ADQL geometrical function that can be used in ADQL queries.

	 * By default, all are allowed. */

	public final static String KEY_GEOMETRIES = "geometries";

	/** Value of {@link #KEY_COORD_SYS} and {@link #KEY_GEOMETRIES} that forbid all possible values. */

	public final static String VALUE_NONE = "NONE";

	/** Name/Key of the property that lets declare all User Defined Functions that must be allowed in ADQL queries.

	 * By default, all unknown functions are rejected. This default behavior can be totally reversed by using the

	 * value {@link #VALUE_ANY} */

	public final static String KEY_UDFS = "udfs";

	/** Value of {@link #KEY_UDFS} allowing any unknown function in ADQL queries. Those functions will be considered as UDFs

	 * and will be translated into SQL exactly as they are written in ADQL. */

	public final static String VALUE_ANY = "ANY";



	/* ADDITIONAL TAP RESOURCES */

	/** Name/Key of the property specifying a list of resources to add to the TAP service (e.g. a ADQL query validator).

	 * By default, this list if empty ; only the default TAP resources exist. */

	public final static String KEY_ADD_TAP_RESOURCES = "additional_resources";



	/* CUSTOM FACTORY */

	/** Name/Key of the property specifying the {@link TAPFactory} class to use instead of the default {@link ConfigurableTAPFactory}. 

	 * <em>Setting a value to this property could disable several properties of the TAP configuration file.</em> */

	public final static String KEY_TAP_FACTORY = "tap_factory";



	/** No instance of this class should be created. */