DBSystem


1   /**
2    * com.mckoi.database.control.DBSystem  27 Mar 2002
3    *
4    * Mckoi SQL Database ( http://www.mckoi.com/database )
5    * Copyright (C) 2000, 2001, 2002  Diehl and Associates, Inc.
6    *
7    * This program is free software; you can redistribute it and/or
8    * modify it under the terms of the GNU General Public License
9    * Version 2 as published by the Free Software Foundation.
10   *
11   * This program is distributed in the hope that it will be useful,
12   * but WITHOUT ANY WARRANTY; without even the implied warranty of
13   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14   * GNU General Public License Version 2 for more details.
15   *
16   * You should have received a copy of the GNU General Public License
17   * Version 2 along with this program; if not, write to the Free Software
18   * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
19   *
20   * Change Log:
21   * 
22   * 
23   */
24  
25  package com.mckoi.database.control;
26  
27  import com.mckoi.database.Database;
28  import com.mckoi.database.DatabaseException;
29  import com.mckoi.database.jdbc.MConnection;
30  import com.mckoi.database.jdbc.DatabaseInterface;
31  import com.mckoi.database.jdbcserver.JDBCDatabaseInterface;
32  import com.mckoi.debug.*;
33  
34  import java.sql.Connection  ;
35  import java.sql.SQLException  ;
36  
37  /**
38   * An object used to access and control a single database system running in
39   * the current JVM.  This object provides various access methods to
40   * safely manipulate the database, as well as allowing server plug-ins.  For
41   * example, a TCP/IP JDBC server component might be plugged into this object
42   * to open the database to remote access.
43   *
44   * @author Tobias Downer
45   */
46  
47  public final class DBSystem {
48  
49    /**
50     * The DBController object.
51     */
52    private DBController controller;
53  
54    /**
55     * The DBConfig object that describes the startup configuration of the
56     * database.
57     */
58    private DBConfig config;
59  
60    /**
61     * The underlying Database object of this system.  This object gives low
62     * level access to the system.
63     */
64    private Database database;
65  
66    /**
67     * An internal counter for internal connections created on this system.
68     */
69    private int internal_counter;
70  
71  
72  
73    /**
74     * Package-protected constructor.
75     */
76    DBSystem(DBController controller, DBConfig config, Database database) {
77      this.controller = controller;
78      this.config = config;
79      this.database = database;
80      this.internal_counter = 0;
81  
82      // Register the shut down delegate,
83      database.registerShutDownDelegate(new Runnable  () {
84        public void run() {
85          internalDispose();
86        }
87      });
88  
89      // Enable commands to the database system...
90      database.setIsExecutingCommands(true);
91  
92    }
93  
94    /**
95     * Returns an immutable version of the database system configuration.
96     */
97    public DBConfig getConfig() {
98      return config;
99    }
100 
101   // ---------- Internal access methods ----------
102 
103   /**
104    * Returns the com.mckoi.database.Database object for this control.  This
105    * methods only works correctly if the database engine has successfully been
106    * initialized.
107    * <p>
108    * This object is generally not very useful unless you intend to perform
109    * some sort of low level function on the database.  This object can be
110    * used to bypass the SQL layer and talk directly with the internals of
111    * the database.
112    *
113    * @return a Database object that can be used to access the database system
114    *   at a low level.
115    */
116   public Database getDatabase() {
117     return database;
118   }
119 
120   /**
121    * Makes a connection to the database and returns a java.sql.Connection
122    * object that can be used to execute queries on the database.  This is a
123    * standard connection that talks directly with the database without having
124    * to go through any communication protocol layers.
125    * <p>
126    * For example, if this control is for a Mckoi database server, the
127    * java.sql.Connection returned here does not go through the TCP/IP
128    * connection.  For this reason certain database configuration constraints
129    * (such as number of concurrent connection on the database) may not apply
130    * to this connection.
131    * <p>
132    * The java.sql.Connection returned here acts exactly as an object returned
133    * by a java.sql.MDriver object.
134    * <p>
135    * An SQLException is thrown if the login fails.
136    *
137    * @param schema the initial database schema to start the connection in.
138    * @param username the user to login to the database under.
139    * @param password the password of the user.
140    * @throws SQLException if authentication of the user fails.
141    * @return a JDBC java.sql.Connection used to access the database.
142    */
143   public Connection getConnection(String   schema,
144                       String   username, String   password) throws SQLException   {
145 
146     // Create the host string, formatted as 'Internal/[hash number]/[counter]'
147     StringBuffer   buf = new StringBuffer  ();
148     buf.append("Internal/");
149     buf.append(hashCode());
150     buf.append('/');
151     synchronized (this) {
152       buf.append(internal_counter);
153       ++internal_counter;
154     }
155     String   host_string = new String  (buf);
156 
157     // Create the database interface for an internal database connection.
158     DatabaseInterface db_interface =
159                        new JDBCDatabaseInterface(getDatabase(), host_string);
160     // Create the MConnection object (very minimal cache settings for an
161     // internal connection).
162     MConnection connection = new MConnection("", db_interface, 8, 4092000);
163     // Attempt to log in with the given username and password (default schema)
164     connection.login(schema, username, password);
165 
166     // And return the new connection
167     return connection;
168   }
169 
170   /**
171    * Makes a connection to the database and returns a java.sql.Connection
172    * object that can be used to execute queries on the database.  This is a
173    * standard connection that talks directly with the database without having
174    * to go through any communication protocol layers.
175    * <p>
176    * For example, if this control is for a Mckoi database server, the
177    * java.sql.Connection returned here does not go through the TCP/IP
178    * connection.  For this reason certain database configuration constraints
179    * (such as number of concurrent connection on the database) may not apply
180    * to this connection.
181    * <p>
182    * The java.sql.Connection returned here acts exactly as an object returned
183    * by a java.sql.MDriver object.
184    * <p>
185    * An SQLException is thrown if the login fails.
186    *
187    * @param username the user to login to the database under.
188    * @param password the password of the user.
189    * @throws SQLException if authentication of the user fails.
190    * @return a JDBC java.sql.Connection used to access the database.
191    */
192   public Connection getConnection(String   username, String   password)
193                                                         throws SQLException   {
194     return getConnection(null, username, password);
195   }
196 
197   // ---------- Global methods ----------
198 
199   /**
200    * Sets a flag that causes the database to delete itself from the file system
201    * when it is shut down.  This is useful if an application needs a
202    * temporary database to work with that is released from the file system
203    * when the application ends.
204    * <p>
205    * By default, a database is not deleted from the file system when it is
206    * closed.
207    * <p>
208    * <b>NOTE: Use with care - setting this flag will cause all data stored
209    *    in the database to be lost when the database is shut down.</b>
210    */
211   public final void setDeleteOnClose(boolean status) {
212     database.setDeleteOnShutdown(status);
213   }
214 
215   /**
216    * Closes this database system so it is no longer able to process queries.
217    * A database may be shut down either through this method or by executing a
218    * query that shuts the system down (for example, 'SHUTDOWN').
219    * <p>
220    * When a database system is closed, it is not able to be restarted again
221    * unless a new DBSystem object is obtained from the DBController.
222    * <p>
223    * This method also disposes all resources associated with the
224    * database system (such as threads, etc) so that it may be reclaimed by
225    * the garbage collector.
226    * <p>
227    * When this method returns this object is no longer usable.
228    */
229   public void close() {
230     if (database != null) {
231       database.startShutDownThread();
232       database.waitUntilShutdown();
233     }
234   }
235 
236   // ---------- Private methods ----------
237 
238   /**
239    * Disposes of all the resources associated with this system.  Note that
240    * this is private method.  It may only be called from the shutdown
241    * delegate registered in the constructor.
242    */
243   private void internalDispose() {
244     if (database != null && database.isInitialized()) {
245 
246       // Disable commands (on worker threads) to the database system...
247       database.setIsExecutingCommands(false);
248 
249       try {
250         database.shutdown();
251       }
252       catch (DatabaseException e) {
253         database.Debug().write(Lvl.ERROR, this,
254                           "Unable to shutdown database because of exception");
255         database.Debug().writeException(Lvl.ERROR, e);
256       }
257     }
258     controller = null;
259     config = null;
260     database = null;
261   }
262 
263 }
264
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags