Database


1   /*
2    * Copyright (c) 2003 - 2007 OpenSubsystems s.r.o. Slovak Republic. All rights reserved.
3    * 
4    * Project: OpenSubsystems
5    * 
6    * $Id: Database.java,v 1.24 2007/01/23 05:59:34 bastafidli Exp $
7    * 
8    * This program is free software; you can redistribute it and/or modify
9    * it under the terms of the GNU General Public License as published by
10   * the Free Software Foundation; version 2 of the License. 
11   * 
12   * This program is distributed in the hope that it will be useful,
13   * but WITHOUT ANY WARRANTY; without even the implied warranty of
14   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15   * GNU General Public License for more details.
16   * 
17   * You should have received a copy of the GNU General Public License
18   * along with this program; if not, write to the Free Software
19   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
20   */
21  
22  package org.opensubsystems.core.persist.db;
23  
24  import java.sql.Connection  ;
25  import java.sql.PreparedStatement  ;
26  import java.sql.SQLException  ;
27  import java.util.Map  ;
28  
29  import org.opensubsystems.core.data.BasicDataObject;
30  import org.opensubsystems.core.data.ModifiableDataObject;
31  import org.opensubsystems.core.error.OSSException;
32  
33  /**
34   * Interface to define abstraction for initialization and management of database 
35   * instance accessed by the application. The main purpose is to define a standard 
36   * way how to interact with the database, which is used by the application to 
37   * persist data so that the application can eventually bring the database online 
38   * or shut it down in case the application runs in embedded environment or 
39   * environment without DBA babysitting the database. It also define interfaces 
40   * to access database dependent information such as different SQL functions
41   * or statements which can be then used by database schemas. 
42   * 
43   * @version $Id: Database.java,v 1.24 2007/01/23 05:59:34 bastafidli Exp $
44   * @author Miro Halas
45   * @code.reviewer Miro Halas
46   * @code.reviewed 1.18 2004/12/22 12:14:53 jlegeny
47   */
48  public interface Database
49  {
50     // Constants ////////////////////////////////////////////////////////////////
51  
52     /**
53      * Value specifying after how namy iterations the batch will be executed
54      */
55     int BATCH_ITERATOR = 500;
56  
57     /**
58      * The current database is HSQLDB
59      */
60     int HSQLDB_DATABASE_TYPE = 1;
61     
62     /**
63      * The current database is HSQLDB
64      */
65     String   HSQLDB_DATABASE_TYPE_IDENTIFIER = "HsqlDB";
66  
67     /**
68      * The current database is SAP DB
69      */
70     int SAPDB_DATABASE_TYPE = 2;
71  
72     /**
73      * The current database is SAP DB
74      */
75     String   SAPDB_DATABASE_TYPE_IDENTIFIER = "SapDB";
76  
77     /**
78      * The current database is PostgreSQL
79      */
80     int POSTGRESQL_DATABASE_TYPE = 3;
81  
82     /**
83      * The current database is PostgreSQL
84      */
85     String   POSTGRESQL_DATABASE_TYPE_IDENTIFIER = "PostgreSQL";
86  
87     /**
88      * The current database is MySQL
89      */
90     int MYSQL_DATABASE_TYPE = 4;
91  
92     /**
93      * The current database is MySQL
94      */
95     String   MYSQL_DATABASE_TYPE_IDENTIFIER = "MySQL";
96  
97     /**
98      * The current database is MSSQL
99      */
100    int MSSQL_DATABASE_TYPE = 5;
101 
102    /**
103     * The current database is MS SQL Server
104     */
105    String   MSSQL_DATABASE_TYPE_IDENTIFIER = "MSSQL";
106 
107    /**
108     * The current database is IBM DB2
109     */
110    int DB2_DATABASE_TYPE = 6;
111 
112    /**
113     * The current database is IBM DB2
114     */
115    String   DB2_DATABASE_TYPE_IDENTIFIER = "DB2";
116 
117    /**
118     * The current database is Sybase ASE
119     */
120    int SYBASE_DATABASE_TYPE = 7;
121 
122    /**
123     * The current database is Sybase
124     */
125    String   SYBASE_DATABASE_TYPE_IDENTIFIER = "Sybase";
126 
127    /**
128     * The current database is Oracle
129     */
130    int ORACLE_DATABASE_TYPE = 8;
131 
132    /**
133     * The current database is Oracle
134     */
135    String   ORACLE_DATABASE_TYPE_IDENTIFIER = "Oracle";
136 
137    /**
138     * The current database is MaxDB
139     */
140    int MAXDB_DATABASE_TYPE = 9;
141 
142    /**
143     * The current database is MaxDB
144     */
145    String   MAXDB_DATABASE_TYPE_IDENTIFIER = "MaxDB";
146 
147    // Public methods ///////////////////////////////////////////////////////////
148    
149    /**
150     * Start the database.
151     * 
152     * @throws OSSException - database cannot be started.
153     */   
154    void start(
155    ) throws OSSException;
156    
157    /**
158     * Stop the database. After the database is stopped, no more requests can be 
159     * issued until the database is started again.
160     * 
161     * @throws OSSException - problems stopping the database
162     */
163    void stop(
164    ) throws OSSException;
165    
166    /**
167     * Add new schema to the database schema.
168     * 
169     * @param dsSchema - schema to add to the database
170     * @throws OSSException - database cannot be started.
171     */
172    void add(
173       DatabaseSchema dsSchema
174    ) throws OSSException;
175    
176    /**
177     * Add new schema to the database schema by specifying the generic schema
178     * class or interface. The schema itself will be created by DatabaseSchemaManager
179     * for current environment and based on any configuration settings. 
180     * 
181     * @param clsSchema - class representing schema to add to the database
182     * @throws OSSException - database cannot be started.
183     */
184    void add(
185       Class   clsSchema
186    ) throws OSSException;
187    
188    /**
189     * Returns the type of database currently in use.
190     * It will be one of the constants defined in this class (SAPDB, HSQLDB, etc.).
191     * 
192     * @return int - database type
193     */
194    int getDatabaseType(
195    );
196    
197    /**
198     * Returns the identifier for the type of database currently in use which can 
199     * be used to construct package and class names.
200     * It will be one of the constants defined in this class (SAPDB, HSQLDB, etc.).
201     * 
202     * @return String - database type
203     */
204    String   getDatabaseTypeIdentifier(
205    );
206 
207    /**
208     * Test if the database is started.
209     * 
210     * @return boolean - true if started
211     */
212    boolean isStarted(
213    );
214    
215    // Methods to retrieve database dependent information ///////////////////////
216    
217    /**
218     * Get very efficient parameterless SQL statement which can be used to test
219     * connection validity.
220     *   
221     * @return String - SQL statement
222     */
223    String   getConnectionTestStatement(
224    );
225    
226    /**
227     * Different databases have different bugs about what they support so this 
228     * method will take the desired transaction isolation level and convert it
229     * to the one supported by database.
230     * 
231     * @param iTransactionIsolation - desired transaction isolation level
232     * @return int - supported transaction isolation level
233     */
234    int getTransactionIsolation(
235       int iTransactionIsolation
236    );
237    
238    /**
239     * This method returns default result set type which should be used to load 
240     * lists of items from the result set efficiently. Some databases supports
241     * efficient absolute cursors that allow us to efficiently find out the size
242     * of result set and efficiently allocate memory for it and they may require
243     * special result set type to do so.
244     * 
245     * @return int - result set type to use load list, see ResultSet.TYPE_XXX constants
246     */
247    int getSelectListResultSetType();
248    
249    /**
250     * This method returns default result set concurrency which should be used to load 
251     * lists of items from the result set efficiently. Some databases supports
252     * efficient absolute cursors that allow us to efficiently find out the size
253     * of result set and efficiently allocate memory for it and they may require
254     * special result set concurrency to do so.
255     * 
256     * @return int - result set concurrency to use load list, see ResultSet.CONCUR_XXX 
257     *               constants
258     */
259    int getSelectListResultSetConcurrency();   
260    
261    /**
262     * Find out if database (driver) allows us to call methods such as absolute() 
263     * or last() for retrieved result sets.
264     * 
265     * @return boolean - true if it is possible to call methods such as absolute, 
266     *                   last() for retrieved result sets.
267     */
268    boolean hasAbsolutePositioningSupport();
269    
270    /**
271     * Find out if when trying to find out size of the result set we should use
272     * rather count(*)/count(1)/count(id) instead of using hasAbsolutePositioningSupport.
273     * 
274     * @return boolean - true if should use count(x) instead of last()
275     */
276    boolean preferCountToLast();
277 
278    // Methods to retrieve differently named functions or attributes ////////////
279    
280    /**
281     * Get string which can be used in SQL queries to retrieve timestamp 
282     * representing current time.
283     * 
284     * @return String - SQL representation of function call to get current timestamp
285     */
286    String   getCurrentTimestampFunctionCall(
287    );
288 
289    /**
290     * Get DB specific SQL queries for analyzing tables or updating statistics on the tables 
291     * (it is good for performance).
292     * 
293     * @param mapTableNames - map of table names the update statistics will be 
294     *                        processed on. Key is the data object data of which
295     *                        are stored in the table and value is te name of the 
296     *                        table
297     * @return Object[] - index 0 - String[] - SQL representation of function calls 
298     *                                         to analyze tables and indexes 
299     *                                         (array of SQL commands for each table 
300     *                                         the update statistics will be processed)
301     *                  - index 1 - Boolean flag signaling if the autocommit when
302     *                              executing these statements should be true or 
303     *                              false
304     */
305    Object  [] getSQLAnalyzeFunctionCall(
306       Map   mapTableNames
307    );
308 
309    /**
310     * Get string which can be used in SQL queries to retrieve record count.
311     * 
312     * @return String - SQL representation of function call to get record count
313     */
314    String   getSQLCountFunctionCall(
315    );
316 
317    /**
318     * Find out if database allows us to support rows limitation. This means that
319     * database has to provide a way how to construct EFFICIENT SQL which allows 
320     * us to retrieve items starting from row X and ending at row Y. 
321     * 
322     * @return boolean - true if it is possible to support row limitation
323     */
324    boolean hasSelectListRangeSupport(
325    );
326 
327    /**
328     * Test if the specified query invokes stored procedure or if it is just 
329     * a regular prepared statement.
330     * 
331     * @param strQuery - query to test
332     * @return boolean - true if query invokes stored procedure false otherwise 
333     */
334    boolean isCallableStatement(
335       String   strQuery
336    );
337    
338    /**
339     * Insert the data, fetch from the database id and generated creation and 
340     * optionally modification timestamps for the newly created data object.
341     * 
342     * Note: Since the caller created the prepared (or callable) statement, 
343     * the caller is responsible for its closing.
344     *  
345     * @param dbConnection - connection to use to access the database
346     * @param insertStatement - statement used to insert the data. This can be
347     *                          CallableStatement if stored procedure is used.
348     * @param bIsInDomain - are the data objects maintained in domains
349     * @param strTableName - name of the table where the data are being inserted
350     * @param iIndex - 1 based index of the next parameter value of which can be
351     *                 set on the statement (last parameter set by caller + 1)
352     * @param data - data object to update with the fetched values
353     * @throws SQLException - an error has occured
354     * @throws OSSException - an error has occured
355     */
356    void insertAndFetchGeneratedValues(
357       Connection          dbConnection,
358       PreparedStatement   insertStatement,
359       boolean           bIsInDomain,
360       String              strTableName,
361       int               iIndex,
362       BasicDataObject   data
363    ) throws SQLException  ,
364             OSSException;
365    
366    /**
367     * Update the data, check for  errors and fetch from the database generated 
368     * modification timestamps for the updated data object.
369     * 
370     * Note: Since the caller created the prepared statement, the caller is
371     * responsible for its closing. 
372     * 
373     * @param strDataName - name of the data object
374     * @param dbConnection - connection to use to access the datavase
375     * @param updateStatement - statement to update data in the database. This 
376     *                          can be CallableStatement if stored procedure is 
377     *                          used.
378     * @param bIsInDomain - are the data objects maintained in domains
379     * @param strTableName - name of the table
380     * @param iIndex - 1 based index of the next parameter value of which can be
381     *                 set on the statement (last parameter set by caller + 1)
382     * @param data - data object to update
383     * @throws SQLException - an error has occured
384     * @throws OSSException - an error has occured
385     */
386    void updatedAndFetchGeneratedValues(
387       String                 strDataName,
388       Connection             dbConnection,
389       PreparedStatement      updateStatement,
390       boolean              bIsInDomain,
391       String                 strTableName,
392       int                  iIndex,
393       ModifiableDataObject data
394    ) throws SQLException  ,
395             OSSException;
396 }
397
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Free Books Free Magazines
Popular Tags