1 /***
2 * ConnectionPool.java
3 *
4 * This file is part of the creme library.
5 * The creme library intends to ease the development effort of large
6 * applications by providing easy to use support classes.
7 *
8 * Copyright (C) 2002 Denis Bregeon
9 *
10 *
11 * This library is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU Lesser General Public
13 * License as published by the Free Software Foundation; either
14 * version 2.1 of the License, or (at your option) any later version.
15 *
16 * This library is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * Lesser General Public License for more details.
20 *
21 * You should have received a copy of the GNU Lesser General Public
22 * License along with this library; if not, write to the Free Software
23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
24 *
25 * contact information: dbregeon@sourceforge.net
26 */
27 package org.jcreme.sql;
28
29 import java.sql.Connection;
30 import java.sql.SQLException;
31
32 /***
33 * This interface models a pool of database Connection instances. A pool is a
34 * set of reusable instances, possibly with a limited number of instances.
35 *
36 * @author $Author: dbregeon $
37 * @version $Revision: 1.1 $
38 */
39 public interface ConnectionPool {
40 /***
41 * This method provides a Connection to the database from the pool. The
42 * Connection may be created on the spot or already exists. The pool
43 * guarantees that the Connection was released by its previous user, not
44 * that the previous user actually ceased to use it.
45 *
46 * @return a ready to use Connection.
47 * @throws SQLException
48 * if a problem occurs while trying to get a Connection.
49 */
50 public Connection getConnection() throws SQLException;
51
52 /***
53 * This method provides a Connection to the database from the pool. The
54 * Connection may be created on the spot or already exists. The pool
55 * guarantees that the Connection was released by its previous user, not
56 * that the previous user actually ceased to use it. If the waiting period
57 * expires and no connection was available, it will return null.
58 *
59 * @param waitingPeriod
60 * the number of milliseconds for which the method call will be
61 * blocked waiting for an available connection.
62 * @return a ready to use Connection or null if the waiting period expired.
63 * @throws SQLException
64 * if a problem occurs while trying to get a Connection.
65 */
66 public Connection getConnection(int waitingPeriod) throws SQLException;
67
68 /***
69 * This method enables to return a Connection to the pool. Nothing is done
70 * if the Connection does not belong to the pool. The Connection should not
71 * be used after being released.
72 *
73 * @param conn
74 * the Connection to be returned.
75 * @throws SQLException
76 * if a problem occurs while trying to release a Connection.
77 */
78 public void releaseConnection(Connection conn) throws SQLException;
79
80 /***
81 * This method signals the pool it should close all the available
82 * connections. This method usually is called when exiting an application.
83 * Connections provided by this pool should not be used after the close
84 * method has been called.
85 *
86 * @throws SQLException
87 * if an error occurs while closing the pool.
88 */
89 public void close() throws SQLException;
90
91 /***
92 * This method enables to change the isolation level used in the
93 * ConnectionPool.
94 *
95 * @param isolationLevel
96 * the new isolation level to apply.
97 * @throws SQLException
98 * if a problem occurs while changing the isolation level.
99 */
100 public void setTransactionIsolation(IsolationLevel isolationLevel)
101 throws SQLException;
102
103 /***
104 * This method enables to change the minimum size of the ConnectionPool.
105 *
106 * @param minSize
107 * the new minimum size to apply.
108 * @throws SQLException
109 * if a problem occurs while changing the pool minimum size.
110 */
111 public void setMinimumSize(int minSize) throws SQLException;
112
113 /***
114 * This method enables to change the maximum size of the ConnectionPool.
115 *
116 * @param maxSize
117 * the new maximum size to apply.
118 * @throws SQLException
119 * if a problem occurs while changing the pool maximum size.
120 */
121 public void setMaximumSize(int maxSize) throws SQLException;
122
123 /***
124 * This method enables to change the commit policy of the ConnectionPool.
125 *
126 * @param autoCommit
127 * the new commit policy to apply.
128 * @throws SQLException
129 * if a problem occurs while changing the commit policy.
130 */
131 public void setAutoCommit(boolean autoCommit) throws SQLException;
132 }