001: /*
002: * Enhydra Java Application Server Project
003: *
004: * The contents of this file are subject to the Enhydra Public License
005: * Version 1.1 (the "License"); you may not use this file except in
006: * compliance with the License. You may obtain a copy of the License on
007: * the Enhydra web site ( http://www.enhydra.org/ ).
008: *
009: * Software distributed under the License is distributed on an "AS IS"
010: * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
011: * the License for the specific terms governing rights and limitations
012: * under the License.
013: *
014: * The Initial Developer of the Enhydra Application Server is Lutris
015: * Technologies, Inc. The Enhydra Application Server and portions created
016: * by Lutris Technologies, Inc. are Copyright Lutris Technologies, Inc.
017: * All Rights Reserved.
018: *
019: * Contributor(s):
020: *
021: * $Id: DatabaseManager.java,v 1.2 2007-10-19 10:05:39 sinisa Exp $
022: */
023: package com.lutris.appserver.server.sql;
024:
025: import java.sql.SQLException;
026: import java.util.Date;
027: import com.lutris.util.Config;
028:
029: /**
030: * The database management object interface. This class implementing this
031: * interface manages the database connections for one application.
032: *
033: * @version $Revision: 1.2 $
034: * @author Paul Morgan
035: */
036: public interface DatabaseManager {
037:
038: /**
039: * Flag to enable debug logging of queries and transactions.
040: */
041: boolean debug = false;
042:
043: /**
044: * Return main configuration class
045: *
046: * @return
047: * main configuration class.
048: */
049: public Config getConfig();
050:
051: /**
052: * Allocate a connection to the specified logic database. The
053: * connection should be returned to the pool by calling its
054: * <a href=com.lutris.appserver.server.sql.DBConnection#release>
055: * release()</a> function. A thread will wait if no connections
056: * are available. Interupted exceptions are converted to errors.
057: *
058: * @param dbName
059: * Logical name of the database to allocate a connection to.
060: * @return The allocated connection object.
061: * @exception DatabaseManagerException
062: * If a nonexistent logical database name is supplied.
063: * @exception SQLException
064: * If a SQL error occures.
065: */
066: public DBConnection allocateConnection(String dbName)
067: throws DatabaseManagerException, SQLException;
068:
069: /**
070: * Allocate a connection to the default logical database. The
071: * connection should be returned to the pool by calling its
072: * <a href=com.lutris.appserver.server.sql.DBConnection#release>
073: * release()</a> function. A thread will wait if no connections
074: * are available. Interupted exceptions are converted to errors.
075: *
076: * @return The allocated connection object.
077: * @exception DatabaseManagerException
078: * If a nonexistent default logical database name is supplied.
079: * @exception SQLException
080: * If a SQL error occures.
081: * @see
082: * #setDefaultDatabase
083: */
084: public DBConnection allocateConnection()
085: throws DatabaseManagerException, SQLException;
086:
087: /**
088: * Allocate an object id from the specified logical database.
089: *
090: * @param dbName
091: * Logical name of the database from which to obtain an object id.
092: * @return The allocated unique OID
093: * @exception DatabaseManagerException
094: * If a nonexistent logical database name is supplied.
095: * @exception ObjectIdException
096: * If a problem (e.g. SQL error) occured in obtaining the OID.
097: */
098: public ObjectId allocateObjectId(String dbName)
099: throws DatabaseManagerException, ObjectIdException;
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() throws DatabaseManagerException,
113: ObjectIdException;
114:
115: /**
116: * Check does oid belong to Object id's range [minOId, currentOId]
117: *
118: * @param dbName
119: * Logical name of the database from which to check an object id.
120: * @param oid
121: * oid which will be checked.
122: * @exception DatabaseManagerException
123: * If a nonexistent logical database name is supplied.
124: * @exception ObjectIdException
125: * If a oid does't belong to range.
126: */
127: public void checkOId(String dbName, ObjectId oid)
128: throws DatabaseManagerException, ObjectIdException;
129:
130: /**
131: * Check does oid belong to Object id's range [minOId, currentOId] for default database
132: *
133: * @param oid
134: * oid which will be checked.
135: * @exception DatabaseManagerException
136: * If a nonexistent default logical database has been set.
137: * @exception ObjectIdException
138: * If a oid does't belong to range.
139: */
140: public void checkOId(ObjectId oid) throws DatabaseManagerException,
141: ObjectIdException;
142:
143: /**
144: * Create a transaction object for the specified logical database.
145: *
146: * @param dbName
147: * Logical name of the database from which to obtain a transaction.
148: * @return The transaction
149: * @exception DatabaseManagerException
150: * If a nonexistent or invalid logical database name is supplied.
151: * @exception SQLException
152: * If a problem occured creating the transaction.
153: */
154: public DBTransaction createTransaction(String dbName)
155: throws DatabaseManagerException, SQLException;
156:
157: /**
158: * Create a transaction object for the default logical database.
159: *
160: * @return The transaction
161: * @exception DatabaseManagerException
162: * If a nonexistent default logical database has been set.
163: * @exception SQLException
164: * If a problem occured creating the transaction.
165: * @see
166: * #setDefaultDatabase
167: */
168: public DBTransaction createTransaction()
169: throws DatabaseManagerException, SQLException;
170:
171: /**
172: * Create a query object for the specified logical database.
173: *
174: * @param dbName
175: * Logical name of the database from which to obtain a query.
176: * @return The query
177: * @exception DatabaseManagerException
178: * If a nonexistent or invalid logical database name is supplied.
179: * @exception SQLException
180: * If a problem occured creating the query.
181: */
182: public DBQuery createQuery(String dbName)
183: throws DatabaseManagerException, SQLException;
184:
185: /**
186: * Create a query object for the default logical database.
187: *
188: * @return The query
189: * @exception DatabaseManagerException
190: * If a nonexistent default logical database has been set.
191: * @exception SQLException
192: * If a problem occured creating the query.
193: * @see
194: * #setDefaultDatabase
195: */
196: public DBQuery createQuery() throws DatabaseManagerException,
197: SQLException;
198:
199: /**
200: * Return a logical database type for the default logical database.
201: *
202: * @param dbName
203: * Logical name of the database from which to obtain a query.
204: * @return logical database type
205: * @exception DatabaseManagerException
206: * If a nonexistent default logical database has been set.
207: * @exception SQLException
208: * If a problem occured creating the query.
209: * @see
210: * #setDefaultDatabase
211: */
212: public String logicalDatabaseType(String dbName)
213: throws DatabaseManagerException, SQLException;
214:
215: /**
216: * Return a logical database type for the default logical database.
217: *
218: * @return logical database type
219: * @exception DatabaseManagerException
220: * If a nonexistent default logical database has been set.
221: * @exception SQLException
222: * If a problem occured creating the query.
223: * @see
224: * #setDefaultDatabase
225: */
226: public String logicalDatabaseType()
227: throws DatabaseManagerException, SQLException;
228:
229: /**
230: * Set the default logical database. This should be used with
231: * caution, but it makes allocating connections easier.
232: *
233: * @param dbName
234: * The default logical dabase name.
235: * @exception DatabaseManagerException
236: * If a nonexistent or illegal logical database name is supplied.
237: */
238: public void setDefaultDatabase(String dbName)
239: throws DatabaseManagerException;
240:
241: /**
242: * Return default database name (given in config file)
243: * @return
244: * default database name
245: */
246: public String getDefaultDB();
247:
248: /**
249: * Shutdown the database manager. All logical databases will be
250: * shutdown and all connection closed.
251: */
252: public void shutdown();
253:
254: // ====================================================================
255: // The following are primarily for management purposes...
256: // ====================================================================
257: /**
258: * Returns the list of managed logical databases.
259: *
260: * @return List of logical database names.
261: */
262: public String[] getLogicalDatabaseNames();
263:
264: /**
265: * Returns a description of the logical database type.
266: *
267: * @param dbName
268: * The logical database name.
269: * @return
270: * A text description of the logical database type.
271: * @exception DatabaseManagerException
272: * If a nonexistent logical database name is supplied.
273: */
274: public String getType(String dbName)
275: throws DatabaseManagerException;
276:
277: /**
278: * Returns the number of requests made to the database since startup time.
279: *
280: * @param dbName
281: * The logical database name.
282: * @return
283: * The number of database requests since the server started.
284: * @exception DatabaseManagerException
285: * If a nonexistent logical database name is supplied.
286: */
287: public long getRequestCount(String dbName)
288: throws DatabaseManagerException;
289:
290: /**
291: * Returns the number of currently active connections for the
292: * supplied logical database name.
293: * If not implemented, then -1 is returned.
294: *
295: * @param dbName
296: * The logical database name.
297: * @return
298: * The number of currently active connections.
299: * @exception DatabaseManagerException
300: * If a nonexistent logical database name is supplied.
301: */
302: public int getActiveConnectionCount(String dbName)
303: throws DatabaseManagerException;
304:
305: /**
306: * Returns the maximum number of concurent connections that existed
307: * at any time since this object was created, or
308: * <CODE>resetMaxConnectionCount()</CODE> was called.
309: * This is a historical highwater mark.
310: * If not implemented, then -1 is returned.
311: *
312: * @param dbName
313: * The logical database name.
314: * @return
315: * The highwater mark for number of connections, or -1.
316: * @exception DatabaseManagerException
317: * If a nonexistent logical database name is supplied.
318: */
319: public int getMaxConnectionCount(String dbName)
320: throws DatabaseManagerException;
321:
322: /**
323: * Returns the time when the maximum refered to by
324: * <CODE>maxConnectionCount()</CODE> occured.
325: * If not implemented, then null is returned.
326: *
327: * @param dbName
328: * The logical database name.
329: * @return
330: * The Date of when the maximum number of connections occured.
331: * @exception DatabaseManagerException
332: * If a nonexistent logical database name is supplied.
333: */
334: public Date getMaxConnectionCountDate(String dbName)
335: throws DatabaseManagerException;
336:
337: /**
338: * Reset the maximum connection count. See
339: * <CODE>maxConnectionCount()</CODE>. The highwater mark should be
340: * reset to the current number of connections.
341: *
342: * @param dbName
343: * The logical database name.
344: * @exception DatabaseManagerException
345: * If a nonexistent logical database name is supplied.
346: */
347: public void resetMaxConnectionCount(String dbName)
348: throws DatabaseManagerException;
349:
350: public LogicalDatabase findLogicalDatabase(String dbName)
351: throws DatabaseManagerException;
352:
353: public void registerMBeans(String appPrefix, Config appConfig,
354: ClassLoader clsLoader);
355:
356: public void unregisterMBeans();
357:
358: }
|