Newer
Older
package tap.db;
/*
* This file is part of TAPLibrary.
*
* TAPLibrary is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* TAPLibrary is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with TAPLibrary. If not, see <http://www.gnu.org/licenses/>.
*
* Copyright 2012,2014 - UDS/Centre de Données astronomiques de Strasbourg (CDS),
* Astronomisches Rechen Institute (ARI)
import tap.data.DataReadException;
import tap.data.TableIterator;
import tap.metadata.TAPDM;
import tap.metadata.TAPTable;
import uws.service.log.UWSLogType;
import adql.query.ADQLQuery;
/**
* <p>Connection to the "database" (whatever is the type or whether it is linked to a true DBMS connection).</p>
* <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>
* @author Grégory Mantelet (CDS;ARI)
* @version 2.0 (07/2014)
public interface DBConnection {
/** Log type specific to the database activity.
* @see UWSLogType#createCustomLogType(String) */
public final static UWSLogType LOG_TYPE_DB_ACTIVITY = UWSLogType.createCustomLogType("DBActivity");
/**
* <p>Get any identifier for this connection.</p>
*
* <p><i>note: it is used only for logging purpose.</i></p>
*
* @return ID of this connection.
*/
public String getID();
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
/**
* <p>Let executing the given ADQL query.</p>
*
* <p>The result of this query must be formatted as a table, and so must be iterable using a {@link TableIterator}.</p>
*
* <p><i>note: the interpretation of the ADQL query is up to the implementation. In most of the case, it is just needed
* to translate this ADQL query into an SQL query (understandable by the chosen DBMS).</i></p>
*
* @param adqlQuery ADQL query to execute.
*
* @return The table result.
*
* @throws DBException If any errors occurs while executing the query.
*/
public TableIterator executeQuery(final ADQLQuery adqlQuery) throws DBException;
/**
* <p>Add or update the specified TAP_SCHEMA table with the given data.</p>
*
* <p><i><b>Warning:</b> It is expected that the given data SHOULD be the only ones inside the specified table.
* So, the table SHOULD probably be cleared before the insertion of the given data. However, this behavior MAY depend of the
* implementation and more particularly of the way the TAP_SCHEMA is updated.</i></p>
*
* @param tapTableName Name of the TAP_SCHEMA table to add/update.
* @param data Data to use in order to fill the specified table.
*
* @return <i>true</i> if the specified table has been successfully added/updated, <i>false</i> otherwise.
*
* @throws DBException If any error occurs while updating the database.
* @throws DataReadException If any error occurs while reading the given data.
*/
public boolean updateTAPTable(final TAPDM tapTableName, final TableIterator data) throws DBException, DataReadException;
/**
* Add the defined and given table inside the TAP_UPLOAD schema.
*
* <p><i>note: A table of TAP_UPLOAD MUST be transient and persistent only for the lifetime of the query.
* So, this function should always be used with {@link #dropUploadedTable(String)}, which is called at
* the end of each query execution.</i></p>
*
* @param tableDef Definition of the table to upload (list of all columns and of their type).
* @param data Rows and columns of the table to upload.
* @param maxNbRows Maximum number of rows allowed to be inserted. Beyond this limit, a
* {@link DataReadException} MUST be sent. <i>A negative or a NULL value means "no limit".</i>
*
* @return <i>true</i> if the given table has been successfully added, <i>false</i> otherwise.
*
* @throws DBException If any error occurs while adding the table.
* @throws DataReadException If any error occurs while reading the given data.
*/
public boolean addUploadedTable(final TAPTable tableDef, final TableIterator data, final int maxNbRows) throws DBException, DataReadException;
/**
* <p>Drop the specified uploaded table from the database.
* More precisely, it means dropping a table from the TAP_UPLOAD schema.</p>
*
* @param tableName Name (in the database) of the uploaded table to drop.
*
* @return <i>true</i> if the specified table has been successfully dropped, <i>false</i> otherwise.
*
* @throws DBException If any error occurs while dropping the specified uploaded table.
*/
public boolean dropUploadedTable(final String tableName) 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;
}