[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.

src/tap/ServiceConnection.java

@@ -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/ConfigurableTAPFactory.java

@@ -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

@@ -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

@@ -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. */

test/tap/config/TestConfigurableServiceConnection.java

@@ -714,10 +714,10 @@ public class TestConfigurableServiceConnection {
 		// Test with only a set maximum output limit:
 		try{
 			ServiceConnection connection = new ConfigurableServiceConnection(maxOutputLimitProp);
-			assertEquals(connection.getOutputLimit()[0], -1);
-			assertEquals(connection.getOutputLimit()[1], 1000);
-			assertEquals(connection.getOutputLimitType()[0], LimitUnit.rows);
-			assertEquals(connection.getOutputLimitType()[1], LimitUnit.rows);
+			assertEquals(1000, connection.getOutputLimit()[0]);
+			assertEquals(1000, connection.getOutputLimit()[1]);
+			assertEquals(LimitUnit.rows, connection.getOutputLimitType()[0]);
+			assertEquals(LimitUnit.rows, connection.getOutputLimitType()[1]);
 		}catch(Exception e){
 			fail("This MUST have succeeded because setting only the maximum output limit is valid! \nCaught exception: " + getPertinentMessage(e));
 		}
@@ -734,12 +734,15 @@ public class TestConfigurableServiceConnection {
 		}
 
 		// Test with both a default and a maximum output limits BUT where default > max:
+		/* In a such case, the default value is set silently to the maximum one. */
 		try{
-			new ConfigurableServiceConnection(bothOutputLimitBadProp);
-			fail("This MUST have failed because the default output limit is greater than the maximum one!");
+			ServiceConnection connection = new ConfigurableServiceConnection(bothOutputLimitBadProp);
+			assertEquals(100, connection.getOutputLimit()[1]);
+			assertEquals(connection.getOutputLimit()[1], connection.getOutputLimit()[0]);
+			assertEquals(LimitUnit.rows, connection.getOutputLimitType()[1]);
+			assertEquals(connection.getOutputLimitType()[1], connection.getOutputLimitType()[0]);
 		}catch(Exception e){
-			assertEquals(TAPException.class, e.getClass());
-			assertEquals("The default output limit (here: 1000) MUST be less or equal to the maximum output limit (here: 100)!", e.getMessage());
+			fail("This MUST have succeeded because the default output limit is set automatically to the maximum one if bigger! \nCaught exception: " + getPertinentMessage(e));
 		}
 
 		// Test with a not integer sync. fetch size: