[TAP] Add Javadoc DBConnection (20311a47) · Commits · Sonia Zorba / vollt

src/tap/db/DBConnection.java

+8 −11

Original line number	Diff line number	Diff line
		@@ -20,6 +20,7 @@ package tap.db;
		* Astronomisches Rechen Institut (ARI)
		*/

		import tap.TAPFactory;
		import tap.data.DataReadException;
		import tap.data.TableIterator;
		import tap.metadata.TAPColumn;
		@@ -35,6 +36,13 @@ import adql.translator.ADQLTranslator;
		* <p>It lets executing ADQL queries and updating the TAP datamodel (with the list of schemas, tables and columns published in TAP,
		* or with uploaded tables).</p>
		*
		* <p><b>IMPORTANT:</b>
		* This connection aims only to provide a common and known interface for any kind of database connection.
		* A connection MUST be opened/created and closed/freed ONLY by the {@link TAPFactory}, which will usually merely wrap
		* the real database connection by a {@link DBConnection} object. That's why this interface does not provide anymore
		* a close() function.
		* </p>
		*
		* @author Grégory Mantelet (CDS;ARI)
		* @version 2.0 (07/2014)
		*/
		@@ -230,15 +238,4 @@ public interface DBConnection {
		*/
		public TableIterator executeQuery(final ADQLQuery adqlQuery) throws DBException;

		/**
		* <p>Close the connection (if needed).</p>
		*
		* <p><i>note: This function is called at the end of a query/job execution, after the result
		* has been successfully (or not) fetched. When called, it means the connection is no longer needed
		* for the job and so, can be freed (or given back to a pool, for instance).</i></p>
		*
		* @throws DBException If any error occurs while closing the connection.
		*/
		public void close() throws DBException;

		}

src/tap/db/JDBCConnection.java

+14 −18

Original line number	Diff line number	Diff line
		@@ -55,7 +55,7 @@ import adql.translator.JDBCTranslator;
		import adql.translator.TranslationException;

		/**
		* <p>This {@link DBConnection} implementation is theoretically able to deal with any DBMS connection.</p>
		* <p>This {@link DBConnection} implementation is theoretically able to deal with any DBMS JDBC connection.</p>
		*
		* <p><i>Note:
		* "Theoretically", because its design has been done using information about Postgres, SQLite, Oracle, MySQL and Java DB (Derby).
		@@ -112,7 +112,7 @@ import adql.translator.TranslationException;
		* </i></p>
		*
		* @author Grégory Mantelet (CDS;ARI)
		* @version 2.0 (07/2014)
		* @version 2.0 (08/2014)
		* @since 2.0
		*/
		public class JDBCConnection implements DBConnection {
		@@ -208,13 +208,7 @@ public class JDBCConnection implements DBConnection {
		}

		/**
		* <p>Create a JDBC connection by wrapping the given connection.</p>
		*
		* <p><i><b>Warning:</b>
		* Calling {@link #close()} will call the function close() of the given connection.
		* So, if this connection is coming from a pool, it is here supposed that a call to this function will not close the connection but gives it back to the pool.
		* If it's not the case, {@link #close()} must be overwritten in order to apply the good "close" behavior.
		* </i></p>
		* Create a JDBC connection by wrapping the given connection.
		*
		* @param conn Connection to wrap.
		* @param translator {@link ADQLTranslator} to use in order to get SQL from an ADQL query and to get qualified DB table names.
		@@ -312,15 +306,17 @@ public class JDBCConnection implements DBConnection {
		return ID;
		}

		@Override
		public void close() throws DBException{
		try{
		connection.close();
		log(0, "Connection CLOSED.", null);
		}catch(SQLException se){
		log(1, "CLOSING connection impossible!", se);
		throw new DBException("Impossible to close the database connection !", se);
		}
		/**
		* <p>Get the JDBC connection wrapped by this {@link JDBCConnection} object.</p>
		*
		* <p><i>Note:
		* This is the best way to get the JDBC connection in order to properly close it.
		* </i></p>
		*
		* @return The wrapped JDBC connection.
		*/
		public final Connection getInnerConnection(){
		return connection;
		}

		/* ********************* */