1 : /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
2 : * vim: sw=2 ts=2 et lcs=trail\:.,tab\:>~ :
3 : * ***** BEGIN LICENSE BLOCK *****
4 : * Version: MPL 1.1/GPL 2.0/LGPL 2.1
5 : *
6 : * The contents of this file are subject to the Mozilla Public License Version
7 : * 1.1 (the "License"); you may not use this file except in compliance with
8 : * the License. You may obtain a copy of the License at
9 : * http://www.mozilla.org/MPL/
10 : *
11 : * Software distributed under the License is distributed on an "AS IS" basis,
12 : * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
13 : * for the specific language governing rights and limitations under the
14 : * License.
15 : *
16 : * The Original Code is Oracle Corporation code.
17 : *
18 : * The Initial Developer of the Original Code is
19 : * Oracle Corporation
20 : * Portions created by the Initial Developer are Copyright (C) 2004
21 : * the Initial Developer. All Rights Reserved.
22 : *
23 : * Contributor(s):
24 : * Vladimir Vukicevic <vladimir.vukicevic@oracle.com>
25 : * Lev Serebryakov <lev@serebryakov.spb.ru>
26 : *
27 : * Alternatively, the contents of this file may be used under the terms of
28 : * either the GNU General Public License Version 2 or later (the "GPL"), or
29 : * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
30 : * in which case the provisions of the GPL or the LGPL are applicable instead
31 : * of those above. If you wish to allow use of your version of this file only
32 : * under the terms of either the GPL or the LGPL, and not to allow others to
33 : * use your version of this file under the terms of the MPL, indicate your
34 : * decision by deleting the provisions above and replace them with the notice
35 : * and other provisions required by the GPL or the LGPL. If you do not delete
36 : * the provisions above, a recipient may use your version of this file under
37 : * the terms of any one of the MPL, the GPL or the LGPL.
38 : *
39 : * ***** END LICENSE BLOCK ***** */
40 :
41 : #ifndef mozilla_storage_Connection_h
42 : #define mozilla_storage_Connection_h
43 :
44 : #include "nsAutoPtr.h"
45 : #include "nsCOMPtr.h"
46 : #include "mozilla/Mutex.h"
47 : #include "nsIInterfaceRequestor.h"
48 :
49 : #include "nsDataHashtable.h"
50 : #include "mozIStorageProgressHandler.h"
51 : #include "SQLiteMutex.h"
52 : #include "mozIStorageConnection.h"
53 : #include "mozStorageService.h"
54 :
55 : #include "nsIMutableArray.h"
56 :
57 : #include "sqlite3.h"
58 :
59 : struct PRLock;
60 : class nsIFile;
61 : class nsIEventTarget;
62 : class nsIThread;
63 :
64 : namespace mozilla {
65 : namespace storage {
66 :
67 : class Connection : public mozIStorageConnection
68 : , public nsIInterfaceRequestor
69 : {
70 : public:
71 : NS_DECL_ISUPPORTS
72 : NS_DECL_MOZISTORAGECONNECTION
73 : NS_DECL_NSIINTERFACEREQUESTOR
74 :
75 : /**
76 : * Structure used to describe user functions on the database connection.
77 : */
78 12694 : struct FunctionInfo {
79 : enum FunctionType {
80 : SIMPLE,
81 : AGGREGATE
82 : };
83 :
84 : nsCOMPtr<nsISupports> function;
85 : FunctionType type;
86 : PRInt32 numArgs;
87 : };
88 :
89 : /**
90 : * @param aService
91 : * Pointer to the storage service. Held onto for the lifetime of the
92 : * connection.
93 : * @param aFlags
94 : * The flags to pass to sqlite3_open_v2.
95 : */
96 : Connection(Service *aService, int aFlags);
97 :
98 : /**
99 : * Creates the connection to the database.
100 : *
101 : * @param aDatabaseFile
102 : * The nsIFile of the location of the database to open, or create if it
103 : * does not exist. Passing in nsnull here creates an in-memory
104 : * database.
105 : * @param aVFSName
106 : * The VFS that SQLite will use when opening this database. NULL means
107 : * "default".
108 : */
109 : nsresult initialize(nsIFile *aDatabaseFile,
110 : const char* aVFSName = NULL);
111 :
112 : // fetch the native handle
113 42749 : sqlite3 *GetNativeConnection() { return mDBConn; }
114 55 : operator sqlite3 *() const { return mDBConn; }
115 :
116 : /**
117 : * Lazily creates and returns a background execution thread. In the future,
118 : * the thread may be re-claimed if left idle, so you should call this
119 : * method just before you dispatch and not save the reference.
120 : *
121 : * @returns an event target suitable for asynchronous statement execution.
122 : */
123 : nsIEventTarget *getAsyncExecutionTarget();
124 :
125 : /**
126 : * Mutex used by asynchronous statements to protect state. The mutex is
127 : * declared on the connection object because there is no contention between
128 : * asynchronous statements (they are serialized on mAsyncExecutionThread). It
129 : * also protects mPendingStatements.
130 : */
131 : Mutex sharedAsyncExecutionMutex;
132 :
133 : /**
134 : * Wraps the mutex that SQLite gives us from sqlite3_db_mutex. This is public
135 : * because we already expose the sqlite3* native connection and proper
136 : * operation of the deadlock detector requires everyone to use the same single
137 : * SQLiteMutex instance for correctness.
138 : */
139 : SQLiteMutex sharedDBMutex;
140 :
141 : /**
142 : * References the thread this database was opened on. This MUST be thread it is
143 : * closed on.
144 : */
145 : const nsCOMPtr<nsIThread> threadOpenedOn;
146 :
147 : /**
148 : * Closes the SQLite database, and warns about any non-finalized statements.
149 : */
150 : nsresult internalClose();
151 :
152 : /**
153 : * Obtains the filename of the connection. Useful for logging.
154 : */
155 : nsCString getFilename();
156 :
157 : /**
158 : * Creates an sqlite3 prepared statement object from an SQL string.
159 : *
160 : * @param aSQL
161 : * The SQL statement string to compile.
162 : * @param _stmt
163 : * New sqlite3_stmt object.
164 : * @return the result from sqlite3_prepare_v2.
165 : */
166 : int prepareStatement(const nsCString &aSQL, sqlite3_stmt **_stmt);
167 :
168 : /**
169 : * Performs a sqlite3_step on aStatement, while properly handling SQLITE_LOCKED
170 : * when not on the main thread by waiting until we are notified.
171 : *
172 : * @param aStatement
173 : * A pointer to a sqlite3_stmt object.
174 : * @return the result from sqlite3_step.
175 : */
176 : int stepStatement(sqlite3_stmt* aStatement);
177 :
178 : private:
179 : ~Connection();
180 :
181 : /**
182 : * Sets the database into a closed state so no further actions can be
183 : * performed.
184 : *
185 : * @note mDBConn is set to NULL in this method.
186 : */
187 : nsresult setClosedState();
188 :
189 : /**
190 : * Describes a certain primitive type in the database.
191 : *
192 : * Possible Values Are:
193 : * INDEX - To check for the existence of an index
194 : * TABLE - To check for the existence of a table
195 : */
196 : enum DatabaseElementType {
197 : INDEX,
198 : TABLE
199 : };
200 :
201 : /**
202 : * Determines if the specified primitive exists.
203 : *
204 : * @param aElementType
205 : * The type of element to check the existence of
206 : * @param aElementName
207 : * The name of the element to check for
208 : * @returns true if element exists, false otherwise
209 : */
210 : nsresult databaseElementExists(enum DatabaseElementType aElementType,
211 : const nsACString& aElementName,
212 : bool *_exists);
213 :
214 : bool findFunctionByInstance(nsISupports *aInstance);
215 :
216 : static int sProgressHelper(void *aArg);
217 : // Generic progress handler
218 : // Dispatch call to registered progress handler,
219 : // if there is one. Do nothing in other cases.
220 : int progressHandler();
221 :
222 : sqlite3 *mDBConn;
223 : nsCOMPtr<nsIFile> mDatabaseFile;
224 :
225 : /**
226 : * Lazily created thread for asynchronous statement execution. Consumers
227 : * should use getAsyncExecutionTarget rather than directly accessing this
228 : * field.
229 : */
230 : nsCOMPtr<nsIThread> mAsyncExecutionThread;
231 : /**
232 : * Set to true by Close() prior to actually shutting down the thread. This
233 : * lets getAsyncExecutionTarget() know not to hand out any more thread
234 : * references (or to create the thread in the first place). This variable
235 : * should be accessed while holding the mAsyncExecutionMutex.
236 : */
237 : bool mAsyncExecutionThreadShuttingDown;
238 :
239 : /**
240 : * Tracks if we have a transaction in progress or not. Access protected by
241 : * mDBMutex.
242 : */
243 : bool mTransactionInProgress;
244 :
245 : /**
246 : * Stores the mapping of a given function by name to its instance. Access is
247 : * protected by mDBMutex.
248 : */
249 : nsDataHashtable<nsCStringHashKey, FunctionInfo> mFunctions;
250 :
251 : /**
252 : * Stores the registered progress handler for the database connection. Access
253 : * is protected by mDBMutex.
254 : */
255 : nsCOMPtr<mozIStorageProgressHandler> mProgressHandler;
256 :
257 : /**
258 : * Stores the flags we passed to sqlite3_open_v2.
259 : */
260 : const int mFlags;
261 :
262 : // This is here for two reasons: 1) It's used to make sure that the
263 : // connections do not outlive the service. 2) Our custom collating functions
264 : // call its localeCompareStrings() method.
265 : nsRefPtr<Service> mStorageService;
266 : };
267 :
268 : } // namespace storage
269 : } // namespace mozilla
270 :
271 : #endif // mozilla_storage_Connection_h
|