DatabaseManager


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.1 2004/09/03 13:42:37 sinisa Exp $
22   */
23  package com.lutris.appserver.server.sql;
24  
25  import java.sql.SQLException  ;
26  import java.util.Date  ;
27  import com.lutris.util.Config;
28  
29  /**
30   * The database management object interface. This class implementing this
31   * interface manages the database connections for one application.
32   *
33   * @version $Revision: 1.1 $
34   * @author  Paul Morgan
35   */
36  public interface DatabaseManager {
37  
38      /**
39       * Flag to enable debug logging of queries and transactions.
40       */
41      boolean debug = false;
42  
43      /**
44       * Return main configuration class 
45       *
46       * @return
47       *   main configuration class.
48       */
49      public Config getConfig();
50  
51      /**
52       * Allocate a connection to the specified logic database. The
53       * connection should be returned to the pool by calling its 
54       * <a HREF=com.lutris.appserver.server.sql.DBConnection#release>
55       * release()</a> function.  A thread will wait if no connections
56       * are available.  Interupted exceptions are converted to errors.
57       *
58       * @param dbName
59       *   Logical name of the database to allocate a connection to.
60       * @return The allocated connection object.
61       * @exception DatabaseManagerException 
62       *   If a nonexistent logical database name is supplied.
63       * @exception SQLException
64       *   If a SQL error occures.
65       */
66      public DBConnection allocateConnection(String   dbName) 
67          throws DatabaseManagerException, SQLException  ;
68  
69      /**
70       * Allocate a connection to the default logical database. The
71       * connection should be returned to the pool by calling its 
72       * <a HREF=com.lutris.appserver.server.sql.DBConnection#release>
73       * release()</a> function.  A thread will wait if no connections
74       * are available.  Interupted exceptions are converted to errors.
75       *
76       * @return The allocated connection object.
77       * @exception DatabaseManagerException 
78       *   If a nonexistent default logical database name is supplied.
79       * @exception SQLException
80       *   If a SQL error occures.
81       * @see
82       *   #setDefaultDatabase
83       */
84      public DBConnection allocateConnection() 
85          throws DatabaseManagerException, SQLException  ;
86  
87      /**
88       * Allocate an object id from the specified logical database.
89       *
90       * @param dbName
91       *   Logical name of the database from which to obtain an object id.
92       * @return The allocated unique OID
93       * @exception DatabaseManagerException 
94       *   If a nonexistent logical database name is supplied.
95       * @exception ObjectIdException 
96       *   If a problem (e.g. SQL error) occured in obtaining the OID.
97       */
98      public ObjectId allocateObjectId(String   dbName) 
99          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() 
113         throws DatabaseManagerException, 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)
141         throws DatabaseManagerException, 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() 
197         throws DatabaseManagerException, 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     // The following are primarily for management purposes...
255     // ====================================================================
256     /**
257      * Returns the list of managed logical databases.
258      * 
259      * @return  List of logical database names.
260      */
261     public String  [] getLogicalDatabaseNames();
262 
263     /**
264      * Returns a description of the logical database type.
265      * 
266      * @param dbName
267      *   The logical database name.
268      * @return
269      *   A text description of the logical database type.
270      * @exception DatabaseManagerException 
271      *   If a nonexistent logical database name is supplied.
272      */
273     public String   getType(String   dbName)
274         throws DatabaseManagerException;
275     
276     /**
277      * Returns the number of requests made to the database since startup time.
278      * 
279      * @param dbName
280      *   The logical database name.
281      * @return
282      *   The number of database requests since the server started.
283      * @exception DatabaseManagerException 
284      *   If a nonexistent logical database name is supplied.
285      */
286     public long getRequestCount(String   dbName)
287         throws DatabaseManagerException;
288     
289     /**
290      * Returns the number of currently active connections for the
291      * supplied logical database name.
292      * If not implemented, then -1 is returned.
293      * 
294      * @param dbName
295      *   The logical database name.
296      * @return
297      *   The number of currently active connections.
298      * @exception DatabaseManagerException 
299      *   If a nonexistent logical database name is supplied.
300      */
301     public int getActiveConnectionCount(String   dbName)
302         throws DatabaseManagerException;
303    
304     /**
305      * Returns the maximum number of concurent connections that existed
306      * at any time since this object was created, or
307      * <CODE>resetMaxConnectionCount()</CODE> was called.
308      * This is a historical highwater mark. 
309      * If not implemented, then -1 is returned.
310      *
311      * @param dbName
312      *   The logical database name.
313      * @return
314      *   The highwater mark for number of connections, or -1.
315      * @exception DatabaseManagerException 
316      *   If a nonexistent logical database name is supplied.
317      */
318     public int getMaxConnectionCount(String   dbName)
319         throws DatabaseManagerException;
320 
321     /**
322      * Returns the time when the maximum refered to by 
323      * <CODE>maxConnectionCount()</CODE> occured.
324      * If not implemented, then null is returned.
325      *
326      * @param dbName
327      *   The logical database name.
328      * @return
329      *   The Date of when the maximum number of connections occured.
330      * @exception DatabaseManagerException 
331      *   If a nonexistent logical database name is supplied.
332      */
333     public Date   getMaxConnectionCountDate(String   dbName)
334         throws DatabaseManagerException;
335 
336     /**
337      * Reset the maximum connection count. See
338      * <CODE>maxConnectionCount()</CODE>. The highwater mark should be
339      * reset to the current number of connections.
340      *
341      * @param dbName
342      *   The logical database name.
343      * @exception DatabaseManagerException 
344      *   If a nonexistent logical database name is supplied.
345      */
346     public void resetMaxConnectionCount(String   dbName)
347         throws DatabaseManagerException;
348     
349     public LogicalDatabase findLogicalDatabase(String   dbName)
350         throws DatabaseManagerException;
351 }
352
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags