Source code: com/lutris/appserver/server/sql/DatabaseManager.java
1 /*
2 * Enhydra Java Application Server Project
3 *
4 * The contents of this file are subject to the Enhydra Public License
5 * Version 1.1 (the "License"); you may not use this file except in
6 * compliance with the License. You may obtain a copy of the License on
7 * the Enhydra web site ( http://www.enhydra.org/ ).
8 *
9 * Software distributed under the License is distributed on an "AS IS"
10 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
11 * the License for the specific terms governing rights and limitations
12 * under the License.
13 *
14 * The Initial Developer of the Enhydra Application Server is Lutris
15 * Technologies, Inc. The Enhydra Application Server and portions created
16 * by Lutris Technologies, Inc. are Copyright Lutris Technologies, Inc.
17 * All Rights Reserved.
18 *
19 * Contributor(s):
20 *
21 * $Id: DatabaseManager.java,v 1.13.12.1 2000/10/19 17:59:05 jasona Exp $
22 */
23
24
25
26
27
28 package com.lutris.appserver.server.sql;
29
30 import java.util.Date;
31 import java.sql.*;
32
33 /**
34 * The database management object interface. This class implementing this
35 * interface manages the database connections for one application.
36 *
37 * @version $Revision: 1.13.12.1 $
38 * @author Paul Morgan
39 */
40 public interface DatabaseManager {
41
42 /**
43 * Flag to enable debug logging of queries and transactions.
44 */
45 boolean debug = false;
46
47
48 /**
49 * Allocate a connection to the specified logic database. The
50 * connection should be returned to the pool by calling its
51 * <a href=com.lutris.appserver.server.sql.DBConnection#release>
52 * release()</a> function. A thread will wait if no connections
53 * are available. Interupted exceptions are converted to errors.
54 *
55 * @param dbName
56 * Logical name of the database to allocate a connection to.
57 * @return The allocated connection object.
58 * @exception DatabaseManagerException
59 * If a nonexistent logical database name is supplied.
60 * @exception SQLException
61 * If a SQL error occures.
62 */
63 public DBConnection allocateConnection (String dbName)
64 throws DatabaseManagerException, SQLException;
65
66
67 /**
68 * Allocate a connection to the default logical database. The
69 * connection should be returned to the pool by calling its
70 * <a href=com.lutris.appserver.server.sql.DBConnection#release>
71 * release()</a> function. A thread will wait if no connections
72 * are available. Interupted exceptions are converted to errors.
73 *
74 * @return The allocated connection object.
75 * @exception DatabaseManagerException
76 * If a nonexistent default logical database name is supplied.
77 * @exception SQLException
78 * If a SQL error occures.
79 * @see
80 * #setDefaultDatabase
81 */
82 public DBConnection allocateConnection ()
83 throws DatabaseManagerException, SQLException;
84
85
86 /**
87 * Allocate an object id from the specified logical database.
88 *
89 * @param dbName
90 * Logical name of the database from which to obtain an object id.
91 * @return The allocated unique OID
92 * @exception DatabaseManagerException
93 * If a nonexistent logical database name is supplied.
94 * @exception ObjectIdException
95 * If a problem (e.g. SQL error) occured in obtaining the OID.
96 */
97 public ObjectId allocateObjectId (String dbName)
98 throws DatabaseManagerException, ObjectIdException;
99
100
101 /**
102 * Allocate an object id from the specified logical database.
103 *
104 * @return The allocated connection object.
105 * @exception DatabaseManagerException
106 * If a nonexistent default logical database has been set.
107 * @exception ObjectIdException
108 * If a problem (e.g. SQL error) occured in obtaining the OID.
109 * @see
110 * #setDefaultDatabase
111 */
112 public ObjectId allocateObjectId ()
113 throws DatabaseManagerException, ObjectIdException;
114
115
116 /**
117 * Create a transaction object for the specified logical database.
118 *
119 * @param dbName
120 * Logical name of the database from which to obtain a transaction.
121 * @return The transaction
122 * @exception DatabaseManagerException
123 * If a nonexistent or invalid logical database name is supplied.
124 * @exception SQLException
125 * If a problem occured creating the transaction.
126 */
127 public DBTransaction createTransaction (String dbName)
128 throws DatabaseManagerException, SQLException;
129
130
131 /**
132 * Create a transaction object for the default logical database.
133 *
134 * @param dbName
135 * Logical name of the database from which to obtain a transaction.
136 * @return The transaction
137 * @exception DatabaseManagerException
138 * If a nonexistent default logical database has been set.
139 * @exception SQLException
140 * If a problem occured creating the transaction.
141 * @see
142 * #setDefaultDatabase
143 */
144 public DBTransaction createTransaction ()
145 throws DatabaseManagerException, SQLException;
146
147
148 /**
149 * Create a query object for the specified logical database.
150 *
151 * @param dbName
152 * Logical name of the database from which to obtain a query.
153 * @return The query
154 * @exception DatabaseManagerException
155 * If a nonexistent or invalid logical database name is supplied.
156 * @exception SQLException
157 * If a problem occured creating the query.
158 */
159 public DBQuery createQuery (String dbName)
160 throws DatabaseManagerException, SQLException;
161
162
163 /**
164 * Create a query object for the default logical database.
165 *
166 * @param dbName
167 * Logical name of the database from which to obtain a query.
168 * @return The query
169 * @exception DatabaseManagerException
170 * If a nonexistent default logical database has been set.
171 * @exception SQLException
172 * If a problem occured creating the query.
173 * @see
174 * #setDefaultDatabase
175 */
176 public DBQuery createQuery ()
177 throws DatabaseManagerException, SQLException;
178
179
180 /**
181 * Set the default logical database. This should be used with
182 * caution, but it makes allocating connections easier.
183 *
184 * @param dbName
185 * The default logical dabase name.
186 * @exception DatabaseManagerException
187 * If a nonexistent or illegal logical database name is supplied.
188 */
189 public void setDefaultDatabase(String dbName)
190 throws DatabaseManagerException;
191
192
193 /**
194 * Shutdown the database manager. All logical databases will be
195 * shutdown and all connection closed.
196 */
197 public void shutdown();
198
199
200 //====================================================================
201 // The following are primarily for management purposes...
202 //====================================================================
203
204 /**
205 * Returns the list of managed logical databases.
206 *
207 * @return List of logical database names.
208 */
209 public String[] getLogicalDatabaseNames();
210
211
212 /**
213 * Returns a description of the logical database type.
214 *
215 * @param dbName
216 * The logical database name.
217 * @return
218 * A text description of the logical database type.
219 * @exception DatabaseManagerException
220 * If a nonexistent logical database name is supplied.
221 */
222 public String getType(String dbName)
223 throws DatabaseManagerException;
224
225
226 /**
227 * Returns the number of requests made to the database since startup time.
228 *
229 * @param dbName
230 * The logical database name.
231 * @return
232 * The number of database requests since the server started.
233 * @exception DatabaseManagerException
234 * If a nonexistent logical database name is supplied.
235 */
236 public long getRequestCount(String dbName)
237 throws DatabaseManagerException;
238
239
240 /**
241 * Returns the number of currently active connections for the
242 * supplied logical database name.
243 * If not implemented, then -1 is returned.
244 *
245 * @param dbName
246 * The logical database name.
247 * @return
248 * The number of currently active connections.
249 * @exception DatabaseManagerException
250 * If a nonexistent logical database name is supplied.
251 */
252 public int getActiveConnectionCount(String dbName)
253 throws DatabaseManagerException;
254
255
256 /**
257 * Returns the maximum number of concurent connections that existed
258 * at any time since this object was created, or
259 * <CODE>resetMaxConnectionCount()</CODE> was called.
260 * This is a historical highwater mark.
261 * If not implemented, then -1 is returned.
262 *
263 * @param dbName
264 * The logical database name.
265 * @return
266 * The highwater mark for number of connections, or -1.
267 * @exception DatabaseManagerException
268 * If a nonexistent logical database name is supplied.
269 */
270 public int getMaxConnectionCount(String dbName)
271 throws DatabaseManagerException;
272
273
274 /**
275 * Returns the time when the maximum refered to by
276 * <CODE>maxConnectionCount()</CODE> occured.
277 * If not implemented, then null is returned.
278 *
279 * @param dbName
280 * The logical database name.
281 * @return
282 * The Date of when the maximum number of connections occured.
283 * @exception DatabaseManagerException
284 * If a nonexistent logical database name is supplied.
285 */
286 public Date getMaxConnectionCountDate(String dbName)
287 throws DatabaseManagerException;
288
289
290 /**
291 * Reset the maximum connection count. See
292 * <CODE>maxConnectionCount()</CODE>. The highwater mark should be
293 * reset to the current number of connections.
294 *
295 * @param dbName
296 * The logical database name.
297 * @exception DatabaseManagerException
298 * If a nonexistent logical database name is supplied.
299 */
300 public void resetMaxConnectionCount(String dbName)
301 throws DatabaseManagerException;
302 }