DatabaseConnectionFactory


1   /*
2    * Copyright (c) 2003 - 2007 OpenSubsystems s.r.o. Slovak Republic. All rights reserved.
3    * 
4    * Project: OpenSubsystems
5    * 
6    * $Id: DatabaseConnectionFactory.java,v 1.15 2007/01/07 06:14:18 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  
26  import org.opensubsystems.core.error.OSSConfigException;
27  import org.opensubsystems.core.error.OSSDatabaseAccessException;
28  import org.opensubsystems.core.error.OSSException;
29  
30  /**
31   * Interface to encapsulate retrieving and returning of database connections.
32   * Data connection factory is here to implement the Abstract Factory pattern 
33   * as described in http://homepage.mac.com/loeffler/java/patterns/absfac.html 
34   * by GoF95 http://homepage.mac.com/loeffler/java/patterns.html.
35   * The main reason is that database connections can be managed in different
36   * ways: they may be always opened when requested or pooled and retrieved from
37   * the pool, they might be created by the driver or retrieved from the data source. 
38   * This interface provides unified way how to access the database
39   * connection regardless of implementation. 
40   * 
41   * @version $Id: DatabaseConnectionFactory.java,v 1.15 2007/01/07 06:14:18 bastafidli Exp $
42   * @author Miro Halas
43   * @code.reviewer Miro Halas
44   * @code.reviewed 1.13 2006/05/21 03:40:47 bastafidli
45   */
46  public interface DatabaseConnectionFactory
47  {
48     /**
49      * Get connection to a database as configured by the default data source. 
50      * The connection has to be explicitely returned using returnConnection most 
51      * likely in finalize clause. 
52      *
53      * @param bAutoCommit - The desired autocommit state of the connection. If 
54      *                      this connection is invoked in global (JTA) transaction
55      *                      then the autocommit is false regardless of what
56      *                      value is specified here. Use true here if the client
57      *                      only reads the data and false if the client also 
58      *                      modifies the data. 
59      *                      Use DatabaseTransactionFactory.commitTransaction
60      *                      to commit the transaction.
61      * @return Connection - connection to a database, never null
62      * @see #returnConnection
63      * @throws OSSDatabaseAccessException - if connection cannot be established
64      */
65     Connection   requestConnection(
66        boolean bAutoCommit
67     ) throws OSSDatabaseAccessException;
68  
69     /**
70      * Get connection to a database as configured by the default data source but 
71      * using explicit user credential. The connection has to be explicitely returned 
72      * using returnConnection most likely in finalize clause.  
73      *
74      * @param bAutoCommit - The desired autocommit state of the connection. If 
75      *                      this connection is invoked in global (JTA) transaction
76      *                      then the autocommit is false regardless of what
77      *                      value is specified here. Use true here if the client
78      *                      only reads the data and false if the client also 
79      *                      modifies the data. 
80      *                      Use DatabaseTransactionFactory.commitTransaction
81      *                      to commit the transaction.
82      * @param  strUser - user name to connect to the database
83      * @param  strPassword - password to the database
84      * @return Connection - connection to a database, never null
85      * @see #returnConnection
86      * @throws OSSDatabaseAccessException - if connection cannot be established
87      */
88     Connection   requestConnection(
89        boolean bAutoCommit,
90        String    strUser, 
91        String    strPassword
92     ) throws OSSDatabaseAccessException;
93  
94     /**
95      * Get connection to a database as configured by the default data source. 
96      * The connection has to be explicitely returned using returnConnection most 
97      * likely in finalize clause. This connection has autocommit set to true so 
98      * if you do not want to autocommit you need to explicitely reset it. This is 
99      * mainly because if selects are executed without transaction and transaction
100     * isolation is set to for example serializable, it can come to a deadlock 
101     * since the select may block table when different connection tries to modify 
102     * it.
103     *
104     * @param bAutoCommit - The desired autocommit state of the connection. If 
105     *                      this connection is invoked in global (JTA) transaction
106     *                      then the autocommit is false regardless of what
107     *                      value is specified here. Use true here if the client
108     *                      only reads the data and false if the client also 
109     *                      modifies the data. 
110     *                      Use DatabaseTransactionFactory.commitTransaction
111     *                      to commit the transaction.
112     * @param strDataSourceName - data source which will be used to get connections
113     * @return Connection - connection to a database, never null
114     * @see #returnConnection
115     * @throws OSSDatabaseAccessException - if connection cannot be established
116     */
117    Connection   requestConnection(
118       boolean bAutoCommit,
119       String    strDataSourceName
120    ) throws OSSDatabaseAccessException;
121 
122    /**
123     * Get connection to a database as configured by the default data source but 
124     * using explicit user credential. The connection has to be explicitely returned 
125     * using returnConnection most likely in finalize clause. This connection has 
126     * autocommit set to true so if you do not want to autocommit you need to 
127     * explictely reset it. This is mainly because if selects are executed without 
128     * transaction and transaction isolation is set to for example serializable, 
129     * it can come to a deadlock since the select may block table when different 
130     * connection tries to modify it.
131     *
132     * @param bAutoCommit - The desired autocommit state of the connection. If 
133     *                      this connection is invoked in global (JTA) transaction
134     *                      then the autocommit is false regardless of what
135     *                      value is specified here. Use true here if the client
136     *                      only reads the data and false if the client also 
137     *                      modifies the data. 
138     *                      Use DatabaseTransactionFactory.commitTransaction
139     *                      to commit the transaction.
140     * @param strDataSourceName - data source which will be used to get connections
141     * @param strUser - user name to connect to the database
142     * @param strPassword - password to the database
143     * @return Connection - connection to a database, never null
144     * @see #returnConnection
145     * @throws OSSDatabaseAccessException - if connection cannot be established
146     */
147    Connection   requestConnection(
148       boolean bAutoCommit,
149       String    strDataSourceName,
150       String    strUser, 
151       String    strPassword
152    ) throws OSSDatabaseAccessException;
153 
154    /**
155     * Release connection to a database. 
156     *
157     * @param cntDBConnection - connection to a database to release, may be null
158     * @see #requestConnection
159     */
160    void returnConnection(
161       Connection   cntDBConnection
162    );
163 
164    // Configuration methods ////////////////////////////////////////////////////
165    
166    /**
167     * Returns the database driver identification.
168     * 
169     * @return String
170     */
171    String   getDatabaseDriver(
172    );
173 
174    /**
175     * Sets the database driver identification.
176     * 
177     * @param strDatabaseDriver - The database driver to set
178     */
179    void setDatabaseDriver(
180       String   strDatabaseDriver
181    );
182 
183    /**
184     * Get real driver name which is used to connect to database. This can be 
185     * wrapped for example in a spy driver.
186     * 
187     * @return String - real JDBC driver name.
188     */
189    String   getRealDatabaseDriver(
190    );
191 
192    /**
193     * Returns the database password.
194     * 
195     * @return String
196     */
197    String   getDatabasePassword(
198    );
199 
200    /**
201     * Sets the database password.
202     * 
203     * @param strDatabasePassword - The database password to set
204     */
205    void setDatabasePassword(
206       String   strDatabasePassword
207    );
208 
209    /**
210     * Returns the database URL.
211     * 
212     * @return String
213     */
214    String   getDatabaseURL(
215    );
216 
217    /**
218     * Sets the database URL.
219     * 
220     * @param strDatabaseURL - The database URL to set
221     */
222    void setDatabaseURL(
223       String   strDatabaseURL
224    );
225 
226    /**
227     * Returns the database user.
228     * 
229     * @return String
230     */
231    String   getDatabaseUser(
232    );
233 
234    /**
235     * Sets the database user.
236     * 
237     * @param strDatabaseUser - The database user to set
238     */
239    void setDatabaseUser(
240       String   strDatabaseUser
241    );
242 
243    /**
244     * Returns the database administration user.
245     * 
246     * @return String
247     */
248    String   getDatabaseAdminUser(
249    );
250 
251    /**
252     * Sets the database administration user.
253     * 
254     * @param strDatabaseUser - The database user to set
255     */
256    void setDatabaseAdminUser(
257       String   strDatabaseUser
258    );
259 
260    /**
261     * Returns the database administration password.
262     * 
263     * @return String
264     */
265    String   getDatabaseAdminPassword(
266    );
267 
268    /**
269     * Sets the database administration password.
270     * 
271     * @param strDatabasePassword - The database password to set
272     */
273    void setDatabaseAdminPassword(
274       String   strDatabasePassword
275    );
276 
277    /**
278     * Get the flag specifying if to use separate datasource instead just 
279     * different creadentials to obtain administrator connection.
280     * 
281     * @return boolean - if true then separate datasource shoud be used for 
282     *                   administration connection
283     */
284    boolean getUseAdminDataSource(
285    );
286    
287    /**
288     * Sets the flag specifying if to use separate datasource instead just 
289     * different creadentials to obtain administrator connection.
290     * 
291     *  @param bUseAdminDataSource - if true then separate datasource shoud be
292     *                               used for administration connection
293     */
294    void setUseAdminDataSource(
295       boolean bUseAdminDataSource
296    );
297    
298     /**
299     * Load default database properties such as what driver, user name or password 
300     * to use from configuration file.
301     * 
302     * @throws OSSConfigException - problem locating or accessing config file
303     * @throws OSSDatabaseAccessException - problem accessing the database
304     */
305    void loadDefaultDatabaseProperties(
306    ) throws OSSConfigException,
307             OSSDatabaseAccessException;
308    
309    /**
310     * Create new data source. If it doesn't exist, it will be created.
311     * 
312     * @param strDataSourceName - data source name 
313     * @param strDriverName - name of the JDBC driver
314     * @param strUrl - url by which data source connects to the database 
315     * @param strUser - user name to connects to the database
316     * @param strPassword - password to connects to the database
317     * @throws OSSDatabaseAccessException - data source with the same name already
318     *                                      exists
319     */
320    void addDataSource(
321       String    strDataSourceName,
322       String    strDriverName,
323       String    strUrl,
324       String    strUser,
325       String    strPassword
326    ) throws OSSDatabaseAccessException;
327    
328    /**
329     * Set the default data source. 
330     * 
331     * @param strDataSourceName - data source which will be used to get connections
332     */
333    void setDefaultDataSourceName(
334       String   strDataSourceName
335    );
336 
337    /**
338     * Get the name of the default data source.
339     * 
340     * @return String
341     */
342    String   getDefaultDataSourceName(
343    );
344    
345    /**
346     * Check if the specified data has been already defined
347     * 
348     * @param strDataSourceName - name of the data source to check for
349     * @return boolean - true if the data source is already defined, false otherwise
350     */
351    boolean isDataSourceDefined(
352       String   strDataSourceName
353    );
354    
355    /**
356     * Stop the connection factory. After the connection factory is stopped
357     * all the connections should be released and they cannot be retrieved
358     * unless the connection factory is reinitialized in some way.
359     * 
360     * @throws OSSException - problem stopping connection factory.
361     */
362    void stop(
363    ) throws OSSException;
364 
365    // Debug interface //////////////////////////////////////////////////////////
366    
367    /**
368     * Get total number for connections (for all data sources) which are currently 
369     * requested and were not returned.
370     * 
371     * @return int - how many connections were currently requested from pool
372     *               and were not returned yet.
373     */
374    int getTotalRequestedConnectionCount(
375    );
376 
377    /**
378     * Get number for connections which are currently requested and were not returned 
379     * for default data source.
380     * 
381     * @return int - how many connections were currently requested from pool
382     *               and were not returned yet.
383     */
384    int getRequestedConnectionCount(
385    );
386 
387    /**
388     * Get number for connections which are currently requested and were not 
389     * returned.
390     * 
391     * @param strDataSourceName - data source which will be used to get connections
392     * @return int - how many connections were currently requested from pool
393     * and were not returned yet.
394     */
395    int getRequestedConnectionCount(
396       String   strDataSourceName
397    );
398 
399    /**
400     * Create string representing state of the factory so we can user it to debug
401     * connection related problems. 
402     *  
403     * @return String - state of the connection factory.
404     */
405    String   debug(
406    );
407 }
408
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