AbstractConnection


1   /*
2    * This file belongs to the XQuark distribution.
3    * Copyright (C) 2003 Universite de Versailles Saint-Quentin.
4    * 
5    * This program is free software; you can redistribute it and/or
6    * modify it under the terms of the GNU Lesser General Public
7    * License as published by the Free Software Foundation; either
8    * version 2.1 of the License, or (at your option) any later version.
9    * 
10   * This program is distributed in the hope that it will be useful,
11   * but WITHOUT ANY WARRANTY; without even the implied warranty of
12   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13   * Lesser General Public License for more details.
14   * 
15   * You should have received a copy of the GNU Lesser General Public
16   * License along with this program; if not, write to the Free Software
17   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307.
18   * You can also get it at http://www.gnu.org/licenses/lgpl.html
19   * 
20   * For more information on this software, see http://www.xquark.org.
21   */
22  
23  /*
24   * AbstractConnection.java
25   *
26   * Created on 9 janvier 2001, 18:23
27   */
28  
29  package org.xquark.mapper.dbms;
30  
31  import java.sql.*;
32  import java.util.Collection  ;
33  import java.util.List  ;
34  import java.util.Map  ;
35  
36  import org.xquark.jdbc.typing.DbType;
37  import org.xquark.jdbc.typing.TypeMap;
38  import org.xquark.mapper.RepositoryException;
39  import org.xquark.mapper.metadata.Repository;
40  
41  /**
42   * Interface offering vendor-independant database methods.
43   *
44   * <p>Objects implementing this interface are supposed to own a JDBC
45   * connection and use it for all accesses to dbms.</p>
46   */
47  public interface AbstractConnection
48  {
49  
50      ///////////////////////////////////////////////////////////////
51      //                      Accessors
52      ///////////////////////////////////////////////////////////////
53      /** returns the encapsulated JDBC connection */
54      public Connection getConnection();
55  
56      /** returns the database type.
57       * @return a constant defined in {@link AbstractConnectionFactory}
58       */
59      public short getDBMSType();
60      
61      /** returns the current schema name (when the connection was created).
62       * @return the currentschema name as returned by the dbms 
63       */
64      public String   getSchemaName();
65      
66     /** closes the encapsulated JDBC connection and perform ending tasks */
67      public void close() throws SQLException;
68  
69      /** returns the type map for the connection dbms */
70      public TypeMap getTypeMap();
71      
72      /** Says if table and column names must be enclosed in double quotes */
73      public boolean useDoubleQuotes4DDLNames();
74      
75      ///////////////////////////////////////////////////////////////
76      //                      Specific methods
77      ///////////////////////////////////////////////////////////////
78      /** This method is called when a repository is initialized to perform
79       * dbms preparation.
80       */
81      public void onInitRepository(Repository rep) throws SQLException;
82      
83      /** This method is called when a repository is deleted to restore initial
84       * dbms state.
85       */
86      public void onDeleteRepository(Repository rep) throws SQLException;
87      
88      /** This method is called when a repositoryConnection is opened to perform
89       * thread specific operations.
90       */
91      public void onInitConnection() throws SQLException;
92      
93      ///////////////////////////////////////////////////////////////
94      //                      Connection methods
95      ///////////////////////////////////////////////////////////////
96      /** This method should be called before processing an updating user request.
97       * This method actually saves the user specified auto-commit mode and
98       * turns the auto-commit mode of the current connection to off.
99       * @throws RepositoryException Application exception
100      * @see #commit
101      */
102     public void start() throws RepositoryException;
103     
104     /** calls  the encapsulated JDBC connection rollback method */
105     public void rollback() throws SQLException;
106     
107     /** Before processing a user request that updates the database, the
108      * auto-commit mode of the current connection is turned off to allow all
109      * the changes to be committed or aborted together. The initial
110      * auto-commit mode of the connection is backed up so it can be
111      * restored after the user request has been processed.
112      *
113      * This method is called upon successful completion of the user request.
114      * This method actually commits the database operations assuming the
115      * connection mode is off and restores the user auto-commit mode.
116      *
117      * If the initial auto-commit mode is false, this method restores the
118      * auto-commit mode and leaves the database operation uncommitted.
119      * @see #start
120      * @throws RepositoryException Application exception
121      */
122     public void commit() throws RepositoryException;
123     
124     ///////////////////////////////////////////////////////////////
125     //                      Table creation methods
126     ///////////////////////////////////////////////////////////////
127     /** Create a temporary relational table which name is automatically
128      * generated according to the single result query table specs.
129      * @return the features of the table needed especially for destruction
130      * @throws SQLException If a database error occurs while creation
131      */
132     public TableInfo createQueryTemporaryTable() throws SQLException;
133     
134     /** Create a temporary relational table which name is automatically
135      * generated.
136      * @param query a query that allow to specify and fill the table.
137      * @return the name of the table needed especially for destruction
138      * @throws SQLException If a database error occurs while creation
139      */
140     public String   createTemporaryTableAs(String   subQuery) throws SQLException;
141     
142     /** Generate a random temporary relational table name WHICH IS NOT
143      * GUARANTEED TO BE UNIQUE.
144      * @return the name of the table.
145      */
146     public String   getTemporaryTableName();
147     
148     /** Generate a random temporary relational table name WHICH IS NOT
149      * GUARANTEED TO BE UNIQUE.
150      * @return an object containing features of the table.
151      */
152     public TableInfo getTemporaryTableInfo();
153 
154     /** Delete a temporary relational.
155      * @param type The table name
156      * @return the name of the table needed especially for destruction
157      * @throws SQLException If a database error occurs while creation
158      */
159     public void dropTemporaryTable(String   tableName) throws SQLException;
160 
161     /** Drop all temporary relational tables created by the
162      * createTemporaryTable() methods.
163      * @throws SQLException If a database error occurs while creation
164      */
165     public void dropTemporaryTables() throws SQLException;
166     
167     /** Delete a relational table with a particular name.
168      * @param type The table name
169      * @return the name of the table needed especially for destruction
170      * @throws SQLException If a database error occurs while creation
171      */
172     public void dropTable(String   tableName) throws SQLException;
173 
174     /** Retrieves org.xquark.mapper.mapping.ColumnMetadata from the
175      * underlying database.
176      * @param tableName The table name
177      * @throws SQLException If a database error occurs while creation
178      */
179     public Map   getTableMetadata(String   tableName) throws SQLException;
180     
181     ///////////////////////////////////////////////////////////////
182     //                      Statements methods
183     ///////////////////////////////////////////////////////////////
184     /** Add a SQL statement in a batch for delayed execution.
185      * @param stmt the JDBC statement which the SQL statement is to be added to
186      */    
187     public void addBatch(PreparedStatement stmt) throws SQLException;
188     
189     /** Add a SQL statement in a batch for delayed execution.
190      * @param stmt the JDBC statement which the SQL statement is to be added to
191      * @param SQLStatement the SQL statement that is to be added
192      */    
193     public void addBatch(Statement stmt, String   SQLStatement) throws SQLException;
194     
195     /** Execute a batch created with the addBatch method.
196      * @param stmt the JDBC statement wich the SQL statement is to be added to
197      * @return an array of update counts containing one element for each command
198      * in the batch. The elements of the array are ordered according to the
199      * order in which commands were added to the batch.
200      */    
201     public int[] executeBatch(Statement stmt) throws SQLException;
202 
203     /** Gives the JDBC driver a hint as to the number of rows that should be fetched
204      * from the database when more rows are needed.
205      * @param stmt the JDBC statement wich the SQL statement is to be added to
206      * @param rows  the number of rows to fetch
207      */    
208     public void setFetchSize(Statement stmt, int rows) throws SQLException;
209 
210     /** Verify the table exists.
211      * @param name table name to check
212      * @return true if the table exists.
213      */
214     public boolean checkTable(String   name) throws SQLException;
215     
216     /** Verify the table exists.
217      * @param table table which existence is to check
218      * @return true if the table exists.
219      */
220     public boolean checkTable(TableInfo table) throws SQLException;
221     
222     /** Delete rows in the reconstruction temporary table name.
223      */
224     public void emptyTable(String   tableName) throws SQLException;
225     ///////////////////////////////////////////////////////////////
226     //           Complex SQL statements (recursive, subqueries...)
227     ///////////////////////////////////////////////////////////////
228     
229     public String   getDeleteUserTableRowsStatement(String   deletionStmt, String   documentRowsSelectionClause)
230     throws SQLException, RepositoryException;
231     
232     public void executeRangeUpdate(String   statement, long first, long last)
233     throws SQLException, RepositoryException;
234     
235     ///////////////////////////////////////////////////////////////
236     //                      DBMS specificities
237     ///////////////////////////////////////////////////////////////
238     /**
239      * Return the column specification conversion string specific to the
240      * rdbms corresponding to an XML Schema primitive type, especially for 
241      * date conversions (to_date() function).
242      * @param type the XML schema primitive type
243      */
244     public String   getColumnStatement(int type) throws RepositoryException;
245     ///////////////////////////////////////////////////////////////
246     //             UNIVERSAL ERROR CODES
247     ///////////////////////////////////////////////////////////////
248     public int UNKNOW_ERROR_CODE = 0;
249     public int OBJECT_ALREADY_EXISTS  = 1;
250     public int OBJECT_DOES_NOT_EXISTS  = 2;
251     
252     public int getUniversalError(SQLException e);
253     
254     ///////////////////////////////////////////////////////////////
255     //                             OTHERS
256     ///////////////////////////////////////////////////////////////
257     public void updateStatistics(String   tableName) throws SQLException;
258     
259     public int getMaxDataLength();
260     public int getSystemCollectionDataLength();
261     public boolean useStringDelimitor();
262     public boolean distinguishNullAndEmptyStrings();
263     
264     public String   getTemporaryTableCreationStatement(TableInfo table);
265     
266     public String   getIndexOrganizedTableCreationStatement(TableInfo table);
267     
268     public String   getLockSelectStatement(String   columnList, String   tableName, String   filterClause);
269     public String   getLockSelectStatement(TableInfo table, String   filterClause);
270     
271     public String   getBitmapIndexClause();
272     
273     public String   getHashIndexClause();
274     
275     public String   getBTreeIndexClause();
276     
277     public void executeUpdate(String   stmt) throws SQLException;
278     
279     public void createSequence(TableInfo table, short step) throws SQLException;
280     public void dropSequence(String   seqName) throws SQLException;
281     
282     public long nextSequenceValue(TableInfo table, short step) throws RepositoryException;
283     
284     /**
285      * Create table and indexes.
286      *
287      * @param Collection collection of TableInfo objects.
288      * @return a collection with tables not created (sequences for instance).
289      */
290     public Collection   createTables(Collection   tables) throws SQLException;
291     
292     public void createIndexes(Collection   tables) throws SQLException;
293     
294     public void dropIndexes(Collection   tables) throws SQLException;
295     
296     /** Gets a list of table names for all tables (any type) of the connection
297      * schema and default catalog.
298      * @param tablePattern a JDBC/SQL style regexp.
299      * @return a List of String objects.
300      */
301     public List   getUserTableNames(String   tablePattern) throws SQLException;
302     public List   getUserSequenceNames(String   seqPattern) throws SQLException;
303 
304     public void setObject(PreparedStatement pStmt, int index, Object   o, int javaType, DbType sqlType)
305     throws SQLException;
306 }
307
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags