SQLiteDatabase.java revision 5274e84e88d2cba20ad3cb21c55c1758b4da8af4
1/* 2 * Copyright (C) 2006 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.database.sqlite; 18 19import android.app.AppGlobals; 20import android.content.ContentValues; 21import android.database.Cursor; 22import android.database.DatabaseErrorHandler; 23import android.database.DatabaseUtils; 24import android.database.DefaultDatabaseErrorHandler; 25import android.database.SQLException; 26import android.database.sqlite.SQLiteDebug.DbStats; 27import android.os.Debug; 28import android.os.StatFs; 29import android.os.SystemClock; 30import android.os.SystemProperties; 31import android.text.TextUtils; 32import android.util.Config; 33import android.util.EventLog; 34import android.util.Log; 35import android.util.Pair; 36 37import dalvik.system.BlockGuard; 38 39import java.io.File; 40import java.lang.ref.WeakReference; 41import java.util.ArrayList; 42import java.util.HashMap; 43import java.util.Iterator; 44import java.util.LinkedHashMap; 45import java.util.Locale; 46import java.util.Map; 47import java.util.Random; 48import java.util.WeakHashMap; 49import java.util.concurrent.locks.ReentrantLock; 50import java.util.regex.Pattern; 51 52/** 53 * Exposes methods to manage a SQLite database. 54 * <p>SQLiteDatabase has methods to create, delete, execute SQL commands, and 55 * perform other common database management tasks. 56 * <p>See the Notepad sample application in the SDK for an example of creating 57 * and managing a database. 58 * <p> Database names must be unique within an application, not across all 59 * applications. 60 * 61 * <h3>Localized Collation - ORDER BY</h3> 62 * <p>In addition to SQLite's default <code>BINARY</code> collator, Android supplies 63 * two more, <code>LOCALIZED</code>, which changes with the system's current locale 64 * if you wire it up correctly (XXX a link needed!), and <code>UNICODE</code>, which 65 * is the Unicode Collation Algorithm and not tailored to the current locale. 66 */ 67public class SQLiteDatabase extends SQLiteClosable { 68 private static final String TAG = "SQLiteDatabase"; 69 private static final int EVENT_DB_OPERATION = 52000; 70 private static final int EVENT_DB_CORRUPT = 75004; 71 72 /** 73 * Algorithms used in ON CONFLICT clause 74 * http://www.sqlite.org/lang_conflict.html 75 */ 76 /** 77 * When a constraint violation occurs, an immediate ROLLBACK occurs, 78 * thus ending the current transaction, and the command aborts with a 79 * return code of SQLITE_CONSTRAINT. If no transaction is active 80 * (other than the implied transaction that is created on every command) 81 * then this algorithm works the same as ABORT. 82 */ 83 public static final int CONFLICT_ROLLBACK = 1; 84 85 /** 86 * When a constraint violation occurs,no ROLLBACK is executed 87 * so changes from prior commands within the same transaction 88 * are preserved. This is the default behavior. 89 */ 90 public static final int CONFLICT_ABORT = 2; 91 92 /** 93 * When a constraint violation occurs, the command aborts with a return 94 * code SQLITE_CONSTRAINT. But any changes to the database that 95 * the command made prior to encountering the constraint violation 96 * are preserved and are not backed out. 97 */ 98 public static final int CONFLICT_FAIL = 3; 99 100 /** 101 * When a constraint violation occurs, the one row that contains 102 * the constraint violation is not inserted or changed. 103 * But the command continues executing normally. Other rows before and 104 * after the row that contained the constraint violation continue to be 105 * inserted or updated normally. No error is returned. 106 */ 107 public static final int CONFLICT_IGNORE = 4; 108 109 /** 110 * When a UNIQUE constraint violation occurs, the pre-existing rows that 111 * are causing the constraint violation are removed prior to inserting 112 * or updating the current row. Thus the insert or update always occurs. 113 * The command continues executing normally. No error is returned. 114 * If a NOT NULL constraint violation occurs, the NULL value is replaced 115 * by the default value for that column. If the column has no default 116 * value, then the ABORT algorithm is used. If a CHECK constraint 117 * violation occurs then the IGNORE algorithm is used. When this conflict 118 * resolution strategy deletes rows in order to satisfy a constraint, 119 * it does not invoke delete triggers on those rows. 120 * This behavior might change in a future release. 121 */ 122 public static final int CONFLICT_REPLACE = 5; 123 124 /** 125 * use the following when no conflict action is specified. 126 */ 127 public static final int CONFLICT_NONE = 0; 128 private static final String[] CONFLICT_VALUES = new String[] 129 {"", " OR ROLLBACK ", " OR ABORT ", " OR FAIL ", " OR IGNORE ", " OR REPLACE "}; 130 131 /** 132 * Maximum Length Of A LIKE Or GLOB Pattern 133 * The pattern matching algorithm used in the default LIKE and GLOB implementation 134 * of SQLite can exhibit O(N^2) performance (where N is the number of characters in 135 * the pattern) for certain pathological cases. To avoid denial-of-service attacks 136 * the length of the LIKE or GLOB pattern is limited to SQLITE_MAX_LIKE_PATTERN_LENGTH bytes. 137 * The default value of this limit is 50000. A modern workstation can evaluate 138 * even a pathological LIKE or GLOB pattern of 50000 bytes relatively quickly. 139 * The denial of service problem only comes into play when the pattern length gets 140 * into millions of bytes. Nevertheless, since most useful LIKE or GLOB patterns 141 * are at most a few dozen bytes in length, paranoid application developers may 142 * want to reduce this parameter to something in the range of a few hundred 143 * if they know that external users are able to generate arbitrary patterns. 144 */ 145 public static final int SQLITE_MAX_LIKE_PATTERN_LENGTH = 50000; 146 147 /** 148 * Flag for {@link #openDatabase} to open the database for reading and writing. 149 * If the disk is full, this may fail even before you actually write anything. 150 * 151 * {@more} Note that the value of this flag is 0, so it is the default. 152 */ 153 public static final int OPEN_READWRITE = 0x00000000; // update native code if changing 154 155 /** 156 * Flag for {@link #openDatabase} to open the database for reading only. 157 * This is the only reliable way to open a database if the disk may be full. 158 */ 159 public static final int OPEN_READONLY = 0x00000001; // update native code if changing 160 161 private static final int OPEN_READ_MASK = 0x00000001; // update native code if changing 162 163 /** 164 * Flag for {@link #openDatabase} to open the database without support for localized collators. 165 * 166 * {@more} This causes the collator <code>LOCALIZED</code> not to be created. 167 * You must be consistent when using this flag to use the setting the database was 168 * created with. If this is set, {@link #setLocale} will do nothing. 169 */ 170 public static final int NO_LOCALIZED_COLLATORS = 0x00000010; // update native code if changing 171 172 /** 173 * Flag for {@link #openDatabase} to create the database file if it does not already exist. 174 */ 175 public static final int CREATE_IF_NECESSARY = 0x10000000; // update native code if changing 176 177 /** 178 * Indicates whether the most-recently started transaction has been marked as successful. 179 */ 180 private boolean mInnerTransactionIsSuccessful; 181 182 /** 183 * Valid during the life of a transaction, and indicates whether the entire transaction (the 184 * outer one and all of the inner ones) so far has been successful. 185 */ 186 private boolean mTransactionIsSuccessful; 187 188 /** 189 * Valid during the life of a transaction. 190 */ 191 private SQLiteTransactionListener mTransactionListener; 192 193 /** 194 * this member is set if {@link #execSQL(String)} is used to begin and end transactions. 195 */ 196 private boolean mTransactionUsingExecSql; 197 198 /** Synchronize on this when accessing the database */ 199 private final ReentrantLock mLock = new ReentrantLock(true); 200 201 private long mLockAcquiredWallTime = 0L; 202 private long mLockAcquiredThreadTime = 0L; 203 204 // limit the frequency of complaints about each database to one within 20 sec 205 // unless run command adb shell setprop log.tag.Database VERBOSE 206 private static final int LOCK_WARNING_WINDOW_IN_MS = 20000; 207 /** If the lock is held this long then a warning will be printed when it is released. */ 208 private static final int LOCK_ACQUIRED_WARNING_TIME_IN_MS = 300; 209 private static final int LOCK_ACQUIRED_WARNING_THREAD_TIME_IN_MS = 100; 210 private static final int LOCK_ACQUIRED_WARNING_TIME_IN_MS_ALWAYS_PRINT = 2000; 211 212 private static final int SLEEP_AFTER_YIELD_QUANTUM = 1000; 213 214 // The pattern we remove from database filenames before 215 // potentially logging them. 216 private static final Pattern EMAIL_IN_DB_PATTERN = Pattern.compile("[\\w\\.\\-]+@[\\w\\.\\-]+"); 217 218 private long mLastLockMessageTime = 0L; 219 220 // Things related to query logging/sampling for debugging 221 // slow/frequent queries during development. Always log queries 222 // which take (by default) 500ms+; shorter queries are sampled 223 // accordingly. Commit statements, which are typically slow, are 224 // logged together with the most recently executed SQL statement, 225 // for disambiguation. The 500ms value is configurable via a 226 // SystemProperty, but developers actively debugging database I/O 227 // should probably use the regular log tunable, 228 // LOG_SLOW_QUERIES_PROPERTY, defined below. 229 private static int sQueryLogTimeInMillis = 0; // lazily initialized 230 private static final int QUERY_LOG_SQL_LENGTH = 64; 231 private static final String COMMIT_SQL = "COMMIT;"; 232 private final Random mRandom = new Random(); 233 private String mLastSqlStatement = null; 234 235 // String prefix for slow database query EventLog records that show 236 // lock acquistions of the database. 237 /* package */ static final String GET_LOCK_LOG_PREFIX = "GETLOCK:"; 238 239 /** Used by native code, do not rename. make it volatile, so it is thread-safe. */ 240 /* package */ volatile int mNativeHandle = 0; 241 242 /** 243 * The size, in bytes, of a block on "/data". This corresponds to the Unix 244 * statfs.f_bsize field. note that this field is lazily initialized. 245 */ 246 private static int sBlockSize = 0; 247 248 /** The path for the database file */ 249 private final String mPath; 250 251 /** The anonymized path for the database file for logging purposes */ 252 private String mPathForLogs = null; // lazily populated 253 254 /** The flags passed to open/create */ 255 private final int mFlags; 256 257 /** The optional factory to use when creating new Cursors */ 258 private final CursorFactory mFactory; 259 260 private final WeakHashMap<SQLiteClosable, Object> mPrograms; 261 262 /** 263 * for each instance of this class, a LRU cache is maintained to store 264 * the compiled query statement ids returned by sqlite database. 265 * key = SQL statement with "?" for bind args 266 * value = {@link SQLiteCompiledSql} 267 * If an application opens the database and keeps it open during its entire life, then 268 * there will not be an overhead of compilation of SQL statements by sqlite. 269 * 270 * why is this cache NOT static? because sqlite attaches compiledsql statements to the 271 * struct created when {@link SQLiteDatabase#openDatabase(String, CursorFactory, int)} is 272 * invoked. 273 * 274 * this cache has an upper limit of mMaxSqlCacheSize (settable by calling the method 275 * (@link #setMaxSqlCacheSize(int)}). 276 */ 277 // default statement-cache size per database connection ( = instance of this class) 278 private int mMaxSqlCacheSize = 25; 279 // guarded by itself 280 /* package */ final Map<String, SQLiteCompiledSql> mCompiledQueries = 281 new LinkedHashMap<String, SQLiteCompiledSql>(mMaxSqlCacheSize + 1, 0.75f, true) { 282 @Override 283 public boolean removeEldestEntry(Map.Entry<String, SQLiteCompiledSql> eldest) { 284 // eldest = least-recently used entry 285 // if it needs to be removed to accommodate a new entry, 286 // close {@link SQLiteCompiledSql} represented by this entry, if not in use 287 // and then let it be removed from the Map. 288 // when this is called, the caller must be trying to add a just-compiled stmt 289 // to cache; i.e., caller should already have acquired database lock AND 290 // the lock on mCompiledQueries. do as assert of these two 2 facts. 291 verifyLockOwner(); 292 if (this.size() <= mMaxSqlCacheSize) { 293 // cache is not full. nothing needs to be removed 294 return false; 295 } 296 // cache is full. eldest will be removed. 297 eldest.getValue().releaseIfNotInUse(); 298 // return true, so that this entry is removed automatically by the caller. 299 return true; 300 } 301 }; 302 /** 303 * absolute max value that can be set by {@link #setMaxSqlCacheSize(int)} 304 * size of each prepared-statement is between 1K - 6K, depending on the complexity of the 305 * SQL statement & schema. 306 */ 307 public static final int MAX_SQL_CACHE_SIZE = 100; 308 private boolean mCacheFullWarning; 309 310 /** Number of cache hits on this database connection. guarded by {@link #mCompiledQueries}. */ 311 private int mNumCacheHits; 312 /** Number of cache misses on this database connection. guarded by {@link #mCompiledQueries}. */ 313 private int mNumCacheMisses; 314 315 /** Used to find out where this object was created in case it never got closed. */ 316 private final Throwable mStackTrace; 317 318 // System property that enables logging of slow queries. Specify the threshold in ms. 319 private static final String LOG_SLOW_QUERIES_PROPERTY = "db.log.slow_query_threshold"; 320 private final int mSlowQueryThreshold; 321 322 /** stores the list of statement ids that need to be finalized by sqlite */ 323 private final ArrayList<Integer> mClosedStatementIds = new ArrayList<Integer>(); 324 325 /** {@link DatabaseErrorHandler} to be used when SQLite returns any of the following errors 326 * Corruption 327 * */ 328 private final DatabaseErrorHandler mErrorHandler; 329 330 /** The Database connection pool {@link DatabaseConnectionPool}. 331 * Visibility is package-private for testing purposes. otherwise, private visibility is enough. 332 */ 333 /* package */ volatile DatabaseConnectionPool mConnectionPool = null; 334 335 /** Each database connection handle in the pool is assigned a number 1..N, where N is the 336 * size of the connection pool. 337 * The main connection handle to which the pool is attached is assigned a value of 0. 338 */ 339 /* package */ final short mConnectionNum; 340 341 /** on pooled database connections, this member points to the parent ( = main) 342 * database connection handle. 343 * package visibility only for testing purposes 344 */ 345 /* package */ SQLiteDatabase mParentConnObj = null; 346 347 private static final String MEMORY_DB_PATH = ":memory:"; 348 349 /** set to true if the database has attached databases */ 350 private volatile boolean mHasAttachedDbs = false; 351 352 /** stores reference to all databases opened in the current process. */ 353 private static ArrayList<WeakReference<SQLiteDatabase>> mActiveDatabases = 354 new ArrayList<WeakReference<SQLiteDatabase>>(); 355 356 synchronized void addSQLiteClosable(SQLiteClosable closable) { 357 // mPrograms is per instance of SQLiteDatabase and it doesn't actually touch the database 358 // itself. so, there is no need to lock(). 359 mPrograms.put(closable, null); 360 } 361 362 synchronized void removeSQLiteClosable(SQLiteClosable closable) { 363 mPrograms.remove(closable); 364 } 365 366 @Override 367 protected void onAllReferencesReleased() { 368 if (isOpen()) { 369 // close the database which will close all pending statements to be finalized also 370 close(); 371 } 372 } 373 374 /** 375 * Attempts to release memory that SQLite holds but does not require to 376 * operate properly. Typically this memory will come from the page cache. 377 * 378 * @return the number of bytes actually released 379 */ 380 static public native int releaseMemory(); 381 382 /** 383 * Control whether or not the SQLiteDatabase is made thread-safe by using locks 384 * around critical sections. This is pretty expensive, so if you know that your 385 * DB will only be used by a single thread then you should set this to false. 386 * The default is true. 387 * @param lockingEnabled set to true to enable locks, false otherwise 388 */ 389 public void setLockingEnabled(boolean lockingEnabled) { 390 mLockingEnabled = lockingEnabled; 391 } 392 393 /** 394 * If set then the SQLiteDatabase is made thread-safe by using locks 395 * around critical sections 396 */ 397 private boolean mLockingEnabled = true; 398 399 /* package */ void onCorruption() { 400 EventLog.writeEvent(EVENT_DB_CORRUPT, mPath); 401 mErrorHandler.onCorruption(this); 402 } 403 404 /** 405 * Locks the database for exclusive access. The database lock must be held when 406 * touch the native sqlite3* object since it is single threaded and uses 407 * a polling lock contention algorithm. The lock is recursive, and may be acquired 408 * multiple times by the same thread. This is a no-op if mLockingEnabled is false. 409 * 410 * @see #unlock() 411 */ 412 /* package */ void lock() { 413 lock(false); 414 } 415 private void lock(boolean forced) { 416 // make sure this method is NOT being called from a 'synchronized' method 417 if (Thread.holdsLock(this)) { 418 // STOPSHIP change the following line to Log.w() 419 throw new IllegalStateException("don't lock() while in a synchronized method"); 420 } 421 verifyDbIsOpen(); 422 if (!forced && !mLockingEnabled) return; 423 mLock.lock(); 424 if (SQLiteDebug.DEBUG_LOCK_TIME_TRACKING) { 425 if (mLock.getHoldCount() == 1) { 426 // Use elapsed real-time since the CPU may sleep when waiting for IO 427 mLockAcquiredWallTime = SystemClock.elapsedRealtime(); 428 mLockAcquiredThreadTime = Debug.threadCpuTimeNanos(); 429 } 430 } 431 } 432 /** 433 * Locks the database for exclusive access. The database lock must be held when 434 * touch the native sqlite3* object since it is single threaded and uses 435 * a polling lock contention algorithm. The lock is recursive, and may be acquired 436 * multiple times by the same thread. 437 * 438 * @see #unlockForced() 439 */ 440 private void lockForced() { 441 lock(true); 442 } 443 444 /** 445 * Releases the database lock. This is a no-op if mLockingEnabled is false. 446 * 447 * @see #unlock() 448 */ 449 /* package */ void unlock() { 450 if (!mLockingEnabled) return; 451 if (SQLiteDebug.DEBUG_LOCK_TIME_TRACKING) { 452 if (mLock.getHoldCount() == 1) { 453 checkLockHoldTime(); 454 } 455 } 456 mLock.unlock(); 457 } 458 459 /** 460 * Releases the database lock. 461 * 462 * @see #unlockForced() 463 */ 464 private void unlockForced() { 465 if (SQLiteDebug.DEBUG_LOCK_TIME_TRACKING) { 466 if (mLock.getHoldCount() == 1) { 467 checkLockHoldTime(); 468 } 469 } 470 mLock.unlock(); 471 } 472 473 private void checkLockHoldTime() { 474 // Use elapsed real-time since the CPU may sleep when waiting for IO 475 long elapsedTime = SystemClock.elapsedRealtime(); 476 long lockedTime = elapsedTime - mLockAcquiredWallTime; 477 if (lockedTime < LOCK_ACQUIRED_WARNING_TIME_IN_MS_ALWAYS_PRINT && 478 !Log.isLoggable(TAG, Log.VERBOSE) && 479 (elapsedTime - mLastLockMessageTime) < LOCK_WARNING_WINDOW_IN_MS) { 480 return; 481 } 482 if (lockedTime > LOCK_ACQUIRED_WARNING_TIME_IN_MS) { 483 int threadTime = (int) 484 ((Debug.threadCpuTimeNanos() - mLockAcquiredThreadTime) / 1000000); 485 if (threadTime > LOCK_ACQUIRED_WARNING_THREAD_TIME_IN_MS || 486 lockedTime > LOCK_ACQUIRED_WARNING_TIME_IN_MS_ALWAYS_PRINT) { 487 mLastLockMessageTime = elapsedTime; 488 String msg = "lock held on " + mPath + " for " + lockedTime + "ms. Thread time was " 489 + threadTime + "ms"; 490 if (SQLiteDebug.DEBUG_LOCK_TIME_TRACKING_STACK_TRACE) { 491 Log.d(TAG, msg, new Exception()); 492 } else { 493 Log.d(TAG, msg); 494 } 495 } 496 } 497 } 498 499 /** 500 * Begins a transaction in EXCLUSIVE mode. 501 * <p> 502 * Transactions can be nested. 503 * When the outer transaction is ended all of 504 * the work done in that transaction and all of the nested transactions will be committed or 505 * rolled back. The changes will be rolled back if any transaction is ended without being 506 * marked as clean (by calling setTransactionSuccessful). Otherwise they will be committed. 507 * </p> 508 * <p>Here is the standard idiom for transactions: 509 * 510 * <pre> 511 * db.beginTransaction(); 512 * try { 513 * ... 514 * db.setTransactionSuccessful(); 515 * } finally { 516 * db.endTransaction(); 517 * } 518 * </pre> 519 */ 520 public void beginTransaction() { 521 beginTransaction(null /* transactionStatusCallback */, true); 522 } 523 524 /** 525 * Begins a transaction in IMMEDIATE mode. Transactions can be nested. When 526 * the outer transaction is ended all of the work done in that transaction 527 * and all of the nested transactions will be committed or rolled back. The 528 * changes will be rolled back if any transaction is ended without being 529 * marked as clean (by calling setTransactionSuccessful). Otherwise they 530 * will be committed. 531 * <p> 532 * Here is the standard idiom for transactions: 533 * 534 * <pre> 535 * db.beginTransactionNonExclusive(); 536 * try { 537 * ... 538 * db.setTransactionSuccessful(); 539 * } finally { 540 * db.endTransaction(); 541 * } 542 * </pre> 543 */ 544 public void beginTransactionNonExclusive() { 545 beginTransaction(null /* transactionStatusCallback */, false); 546 } 547 548 /** 549 * Begins a transaction in EXCLUSIVE mode. 550 * <p> 551 * Transactions can be nested. 552 * When the outer transaction is ended all of 553 * the work done in that transaction and all of the nested transactions will be committed or 554 * rolled back. The changes will be rolled back if any transaction is ended without being 555 * marked as clean (by calling setTransactionSuccessful). Otherwise they will be committed. 556 * </p> 557 * <p>Here is the standard idiom for transactions: 558 * 559 * <pre> 560 * db.beginTransactionWithListener(listener); 561 * try { 562 * ... 563 * db.setTransactionSuccessful(); 564 * } finally { 565 * db.endTransaction(); 566 * } 567 * </pre> 568 * 569 * @param transactionListener listener that should be notified when the transaction begins, 570 * commits, or is rolled back, either explicitly or by a call to 571 * {@link #yieldIfContendedSafely}. 572 */ 573 public void beginTransactionWithListener(SQLiteTransactionListener transactionListener) { 574 beginTransaction(transactionListener, true); 575 } 576 577 /** 578 * Begins a transaction in IMMEDIATE mode. Transactions can be nested. When 579 * the outer transaction is ended all of the work done in that transaction 580 * and all of the nested transactions will be committed or rolled back. The 581 * changes will be rolled back if any transaction is ended without being 582 * marked as clean (by calling setTransactionSuccessful). Otherwise they 583 * will be committed. 584 * <p> 585 * Here is the standard idiom for transactions: 586 * 587 * <pre> 588 * db.beginTransactionWithListenerNonExclusive(listener); 589 * try { 590 * ... 591 * db.setTransactionSuccessful(); 592 * } finally { 593 * db.endTransaction(); 594 * } 595 * </pre> 596 * 597 * @param transactionListener listener that should be notified when the 598 * transaction begins, commits, or is rolled back, either 599 * explicitly or by a call to {@link #yieldIfContendedSafely}. 600 */ 601 public void beginTransactionWithListenerNonExclusive( 602 SQLiteTransactionListener transactionListener) { 603 beginTransaction(transactionListener, false); 604 } 605 606 private void beginTransaction(SQLiteTransactionListener transactionListener, 607 boolean exclusive) { 608 verifyDbIsOpen(); 609 lockForced(); 610 boolean ok = false; 611 try { 612 // If this thread already had the lock then get out 613 if (mLock.getHoldCount() > 1) { 614 if (mInnerTransactionIsSuccessful) { 615 String msg = "Cannot call beginTransaction between " 616 + "calling setTransactionSuccessful and endTransaction"; 617 IllegalStateException e = new IllegalStateException(msg); 618 Log.e(TAG, "beginTransaction() failed", e); 619 throw e; 620 } 621 ok = true; 622 return; 623 } 624 625 // This thread didn't already have the lock, so begin a database 626 // transaction now. 627 if (exclusive && mConnectionPool == null) { 628 execSQL("BEGIN EXCLUSIVE;"); 629 } else { 630 execSQL("BEGIN IMMEDIATE;"); 631 } 632 mTransactionListener = transactionListener; 633 mTransactionIsSuccessful = true; 634 mInnerTransactionIsSuccessful = false; 635 if (transactionListener != null) { 636 try { 637 transactionListener.onBegin(); 638 } catch (RuntimeException e) { 639 execSQL("ROLLBACK;"); 640 throw e; 641 } 642 } 643 ok = true; 644 } finally { 645 if (!ok) { 646 // beginTransaction is called before the try block so we must release the lock in 647 // the case of failure. 648 unlockForced(); 649 } 650 } 651 } 652 653 /** 654 * End a transaction. See beginTransaction for notes about how to use this and when transactions 655 * are committed and rolled back. 656 */ 657 public void endTransaction() { 658 verifyLockOwner(); 659 try { 660 if (mInnerTransactionIsSuccessful) { 661 mInnerTransactionIsSuccessful = false; 662 } else { 663 mTransactionIsSuccessful = false; 664 } 665 if (mLock.getHoldCount() != 1) { 666 return; 667 } 668 RuntimeException savedException = null; 669 if (mTransactionListener != null) { 670 try { 671 if (mTransactionIsSuccessful) { 672 mTransactionListener.onCommit(); 673 } else { 674 mTransactionListener.onRollback(); 675 } 676 } catch (RuntimeException e) { 677 savedException = e; 678 mTransactionIsSuccessful = false; 679 } 680 } 681 if (mTransactionIsSuccessful) { 682 execSQL(COMMIT_SQL); 683 // if write-ahead logging is used, we have to take care of checkpoint. 684 // TODO: should applications be given the flexibility of choosing when to 685 // trigger checkpoint? 686 // for now, do checkpoint after every COMMIT because that is the fastest 687 // way to guarantee that readers will see latest data. 688 // but this is the slowest way to run sqlite with in write-ahead logging mode. 689 if (this.mConnectionPool != null) { 690 execSQL("PRAGMA wal_checkpoint;"); 691 if (SQLiteDebug.DEBUG_SQL_STATEMENTS) { 692 Log.i(TAG, "PRAGMA wal_Checkpoint done"); 693 } 694 } 695 } else { 696 try { 697 execSQL("ROLLBACK;"); 698 if (savedException != null) { 699 throw savedException; 700 } 701 } catch (SQLException e) { 702 if (Config.LOGD) { 703 Log.d(TAG, "exception during rollback, maybe the DB previously " 704 + "performed an auto-rollback"); 705 } 706 } 707 } 708 } finally { 709 mTransactionListener = null; 710 unlockForced(); 711 if (Config.LOGV) { 712 Log.v(TAG, "unlocked " + Thread.currentThread() 713 + ", holdCount is " + mLock.getHoldCount()); 714 } 715 } 716 } 717 718 /** 719 * Marks the current transaction as successful. Do not do any more database work between 720 * calling this and calling endTransaction. Do as little non-database work as possible in that 721 * situation too. If any errors are encountered between this and endTransaction the transaction 722 * will still be committed. 723 * 724 * @throws IllegalStateException if the current thread is not in a transaction or the 725 * transaction is already marked as successful. 726 */ 727 public void setTransactionSuccessful() { 728 verifyDbIsOpen(); 729 if (!mLock.isHeldByCurrentThread()) { 730 throw new IllegalStateException("no transaction pending"); 731 } 732 if (mInnerTransactionIsSuccessful) { 733 throw new IllegalStateException( 734 "setTransactionSuccessful may only be called once per call to beginTransaction"); 735 } 736 mInnerTransactionIsSuccessful = true; 737 } 738 739 /** 740 * return true if there is a transaction pending 741 */ 742 public boolean inTransaction() { 743 return mLock.getHoldCount() > 0 || mTransactionUsingExecSql; 744 } 745 746 /* package */ synchronized void setTransactionUsingExecSqlFlag() { 747 if (Log.isLoggable(TAG, Log.DEBUG)) { 748 Log.i(TAG, "found execSQL('begin transaction')"); 749 } 750 mTransactionUsingExecSql = true; 751 } 752 753 /* package */ synchronized void resetTransactionUsingExecSqlFlag() { 754 if (Log.isLoggable(TAG, Log.DEBUG)) { 755 if (mTransactionUsingExecSql) { 756 Log.i(TAG, "found execSQL('commit or end or rollback')"); 757 } 758 } 759 mTransactionUsingExecSql = false; 760 } 761 762 /** 763 * Returns true if the caller is considered part of the current transaction, if any. 764 * <p> 765 * Caller is part of the current transaction if either of the following is true 766 * <ol> 767 * <li>If transaction is started by calling beginTransaction() methods AND if the caller is 768 * in the same thread as the thread that started the transaction. 769 * </li> 770 * <li>If the transaction is started by calling {@link #execSQL(String)} like this: 771 * execSQL("BEGIN transaction"). In this case, every thread in the process is considered 772 * part of the current transaction.</li> 773 * </ol> 774 * 775 * @return true if the caller is considered part of the current transaction, if any. 776 */ 777 /* package */ synchronized boolean amIInTransaction() { 778 // always do this test on the main database connection - NOT on pooled database connection 779 // since transactions always occur on the main database connections only. 780 SQLiteDatabase db = (isPooledConnection()) ? mParentConnObj : this; 781 boolean b = (!db.inTransaction()) ? false : 782 db.mTransactionUsingExecSql || db.mLock.isHeldByCurrentThread(); 783 if (Log.isLoggable(TAG, Log.DEBUG)) { 784 Log.i(TAG, "amIinTransaction: " + b); 785 } 786 return b; 787 } 788 789 /** 790 * Checks if the database lock is held by this thread. 791 * 792 * @return true, if this thread is holding the database lock. 793 */ 794 public boolean isDbLockedByCurrentThread() { 795 return mLock.isHeldByCurrentThread(); 796 } 797 798 /** 799 * Checks if the database is locked by another thread. This is 800 * just an estimate, since this status can change at any time, 801 * including after the call is made but before the result has 802 * been acted upon. 803 * 804 * @return true, if the database is locked by another thread 805 */ 806 public boolean isDbLockedByOtherThreads() { 807 return !mLock.isHeldByCurrentThread() && mLock.isLocked(); 808 } 809 810 /** 811 * Temporarily end the transaction to let other threads run. The transaction is assumed to be 812 * successful so far. Do not call setTransactionSuccessful before calling this. When this 813 * returns a new transaction will have been created but not marked as successful. 814 * @return true if the transaction was yielded 815 * @deprecated if the db is locked more than once (becuase of nested transactions) then the lock 816 * will not be yielded. Use yieldIfContendedSafely instead. 817 */ 818 @Deprecated 819 public boolean yieldIfContended() { 820 return yieldIfContendedHelper(false /* do not check yielding */, 821 -1 /* sleepAfterYieldDelay */); 822 } 823 824 /** 825 * Temporarily end the transaction to let other threads run. The transaction is assumed to be 826 * successful so far. Do not call setTransactionSuccessful before calling this. When this 827 * returns a new transaction will have been created but not marked as successful. This assumes 828 * that there are no nested transactions (beginTransaction has only been called once) and will 829 * throw an exception if that is not the case. 830 * @return true if the transaction was yielded 831 */ 832 public boolean yieldIfContendedSafely() { 833 return yieldIfContendedHelper(true /* check yielding */, -1 /* sleepAfterYieldDelay*/); 834 } 835 836 /** 837 * Temporarily end the transaction to let other threads run. The transaction is assumed to be 838 * successful so far. Do not call setTransactionSuccessful before calling this. When this 839 * returns a new transaction will have been created but not marked as successful. This assumes 840 * that there are no nested transactions (beginTransaction has only been called once) and will 841 * throw an exception if that is not the case. 842 * @param sleepAfterYieldDelay if > 0, sleep this long before starting a new transaction if 843 * the lock was actually yielded. This will allow other background threads to make some 844 * more progress than they would if we started the transaction immediately. 845 * @return true if the transaction was yielded 846 */ 847 public boolean yieldIfContendedSafely(long sleepAfterYieldDelay) { 848 return yieldIfContendedHelper(true /* check yielding */, sleepAfterYieldDelay); 849 } 850 851 private boolean yieldIfContendedHelper(boolean checkFullyYielded, long sleepAfterYieldDelay) { 852 if (mLock.getQueueLength() == 0) { 853 // Reset the lock acquire time since we know that the thread was willing to yield 854 // the lock at this time. 855 mLockAcquiredWallTime = SystemClock.elapsedRealtime(); 856 mLockAcquiredThreadTime = Debug.threadCpuTimeNanos(); 857 return false; 858 } 859 setTransactionSuccessful(); 860 SQLiteTransactionListener transactionListener = mTransactionListener; 861 endTransaction(); 862 if (checkFullyYielded) { 863 if (this.isDbLockedByCurrentThread()) { 864 throw new IllegalStateException( 865 "Db locked more than once. yielfIfContended cannot yield"); 866 } 867 } 868 if (sleepAfterYieldDelay > 0) { 869 // Sleep for up to sleepAfterYieldDelay milliseconds, waking up periodically to 870 // check if anyone is using the database. If the database is not contended, 871 // retake the lock and return. 872 long remainingDelay = sleepAfterYieldDelay; 873 while (remainingDelay > 0) { 874 try { 875 Thread.sleep(remainingDelay < SLEEP_AFTER_YIELD_QUANTUM ? 876 remainingDelay : SLEEP_AFTER_YIELD_QUANTUM); 877 } catch (InterruptedException e) { 878 Thread.interrupted(); 879 } 880 remainingDelay -= SLEEP_AFTER_YIELD_QUANTUM; 881 if (mLock.getQueueLength() == 0) { 882 break; 883 } 884 } 885 } 886 beginTransactionWithListener(transactionListener); 887 return true; 888 } 889 890 /** 891 * @deprecated This method no longer serves any useful purpose and has been deprecated. 892 */ 893 @Deprecated 894 public Map<String, String> getSyncedTables() { 895 return new HashMap<String, String>(0); 896 } 897 898 /** 899 * Used to allow returning sub-classes of {@link Cursor} when calling query. 900 */ 901 public interface CursorFactory { 902 /** 903 * See 904 * {@link SQLiteCursor#SQLiteCursor(SQLiteCursorDriver, String, SQLiteQuery)}. 905 */ 906 public Cursor newCursor(SQLiteDatabase db, 907 SQLiteCursorDriver masterQuery, String editTable, 908 SQLiteQuery query); 909 } 910 911 /** 912 * Open the database according to the flags {@link #OPEN_READWRITE} 913 * {@link #OPEN_READONLY} {@link #CREATE_IF_NECESSARY} and/or {@link #NO_LOCALIZED_COLLATORS}. 914 * 915 * <p>Sets the locale of the database to the the system's current locale. 916 * Call {@link #setLocale} if you would like something else.</p> 917 * 918 * @param path to database file to open and/or create 919 * @param factory an optional factory class that is called to instantiate a 920 * cursor when query is called, or null for default 921 * @param flags to control database access mode 922 * @return the newly opened database 923 * @throws SQLiteException if the database cannot be opened 924 */ 925 public static SQLiteDatabase openDatabase(String path, CursorFactory factory, int flags) { 926 return openDatabase(path, factory, flags, new DefaultDatabaseErrorHandler()); 927 } 928 929 /** 930 * Open the database according to the flags {@link #OPEN_READWRITE} 931 * {@link #OPEN_READONLY} {@link #CREATE_IF_NECESSARY} and/or {@link #NO_LOCALIZED_COLLATORS}. 932 * 933 * <p>Sets the locale of the database to the the system's current locale. 934 * Call {@link #setLocale} if you would like something else.</p> 935 * 936 * <p>Accepts input param: a concrete instance of {@link DatabaseErrorHandler} to be 937 * used to handle corruption when sqlite reports database corruption.</p> 938 * 939 * @param path to database file to open and/or create 940 * @param factory an optional factory class that is called to instantiate a 941 * cursor when query is called, or null for default 942 * @param flags to control database access mode 943 * @param errorHandler the {@link DatabaseErrorHandler} obj to be used to handle corruption 944 * when sqlite reports database corruption 945 * @return the newly opened database 946 * @throws SQLiteException if the database cannot be opened 947 */ 948 public static SQLiteDatabase openDatabase(String path, CursorFactory factory, int flags, 949 DatabaseErrorHandler errorHandler) { 950 SQLiteDatabase sqliteDatabase = openDatabase(path, factory, flags, errorHandler, 951 (short) 0 /* the main connection handle */); 952 953 // set sqlite pagesize to mBlockSize 954 if (sBlockSize == 0) { 955 // TODO: "/data" should be a static final String constant somewhere. it is hardcoded 956 // in several places right now. 957 sBlockSize = new StatFs("/data").getBlockSize(); 958 } 959 sqliteDatabase.setPageSize(sBlockSize); 960 //STOPSHIP - uncomment the following line 961 //sqliteDatabase.setJournalMode(path, "TRUNCATE"); 962 // STOPSHIP remove the following lines 963 if (!path.equalsIgnoreCase(MEMORY_DB_PATH)) { 964 sqliteDatabase.enableWriteAheadLogging(); 965 } 966 // END STOPSHIP 967 968 // add this database to the list of databases opened in this process 969 synchronized(mActiveDatabases) { 970 mActiveDatabases.add(new WeakReference<SQLiteDatabase>(sqliteDatabase)); 971 } 972 return sqliteDatabase; 973 } 974 975 private static SQLiteDatabase openDatabase(String path, CursorFactory factory, int flags, 976 DatabaseErrorHandler errorHandler, short connectionNum) { 977 SQLiteDatabase db = new SQLiteDatabase(path, factory, flags, errorHandler, connectionNum); 978 try { 979 if (Log.isLoggable(TAG, Log.DEBUG)) { 980 Log.i(TAG, "opening the db : " + path); 981 } 982 // Open the database. 983 db.dbopen(path, flags); 984 db.setLocale(Locale.getDefault()); 985 if (SQLiteDebug.DEBUG_SQL_STATEMENTS) { 986 db.enableSqlTracing(path, connectionNum); 987 } 988 if (SQLiteDebug.DEBUG_SQL_TIME) { 989 db.enableSqlProfiling(path, connectionNum); 990 } 991 return db; 992 } catch (SQLiteDatabaseCorruptException e) { 993 db.mErrorHandler.onCorruption(db); 994 return SQLiteDatabase.openDatabase(path, factory, flags, errorHandler); 995 } catch (SQLiteException e) { 996 Log.e(TAG, "Failed to open the database. closing it.", e); 997 db.close(); 998 throw e; 999 } 1000 } 1001 1002 /** 1003 * Equivalent to openDatabase(file.getPath(), factory, CREATE_IF_NECESSARY). 1004 */ 1005 public static SQLiteDatabase openOrCreateDatabase(File file, CursorFactory factory) { 1006 return openOrCreateDatabase(file.getPath(), factory); 1007 } 1008 1009 /** 1010 * Equivalent to openDatabase(path, factory, CREATE_IF_NECESSARY). 1011 */ 1012 public static SQLiteDatabase openOrCreateDatabase(String path, CursorFactory factory) { 1013 return openDatabase(path, factory, CREATE_IF_NECESSARY); 1014 } 1015 1016 /** 1017 * Equivalent to openDatabase(path, factory, CREATE_IF_NECESSARY, errorHandler). 1018 */ 1019 public static SQLiteDatabase openOrCreateDatabase(String path, CursorFactory factory, 1020 DatabaseErrorHandler errorHandler) { 1021 return openDatabase(path, factory, CREATE_IF_NECESSARY, errorHandler); 1022 } 1023 1024 private void setJournalMode(final String dbPath, final String mode) { 1025 // journal mode can be set only for non-memory databases 1026 // AND can't be set for readonly databases 1027 if (dbPath.equalsIgnoreCase(MEMORY_DB_PATH) || isReadOnly()) { 1028 return; 1029 } 1030 String s = DatabaseUtils.stringForQuery(this, "PRAGMA journal_mode=" + mode, null); 1031 if (!s.equalsIgnoreCase(mode)) { 1032 Log.e(TAG, "setting journal_mode to " + mode + " failed for db: " + dbPath + 1033 " (on pragma set journal_mode, sqlite returned:" + s); 1034 } 1035 } 1036 1037 /** 1038 * Create a memory backed SQLite database. Its contents will be destroyed 1039 * when the database is closed. 1040 * 1041 * <p>Sets the locale of the database to the the system's current locale. 1042 * Call {@link #setLocale} if you would like something else.</p> 1043 * 1044 * @param factory an optional factory class that is called to instantiate a 1045 * cursor when query is called 1046 * @return a SQLiteDatabase object, or null if the database can't be created 1047 */ 1048 public static SQLiteDatabase create(CursorFactory factory) { 1049 // This is a magic string with special meaning for SQLite. 1050 return openDatabase(MEMORY_DB_PATH, factory, CREATE_IF_NECESSARY); 1051 } 1052 1053 /** 1054 * Close the database. 1055 */ 1056 public void close() { 1057 if (!isOpen()) { 1058 return; 1059 } 1060 if (Log.isLoggable(TAG, Log.DEBUG)) { 1061 Log.i(TAG, "closing db: " + mPath + " (connection # " + mConnectionNum); 1062 } 1063 lock(); 1064 try { 1065 // some other thread could have closed this database while I was waiting for lock. 1066 // check the database state 1067 if (!isOpen()) { 1068 return; 1069 } 1070 closeClosable(); 1071 // finalize ALL statements queued up so far 1072 closePendingStatements(); 1073 releaseCustomFunctions(); 1074 // close this database instance - regardless of its reference count value 1075 closeDatabase(); 1076 if (mConnectionPool != null) { 1077 if (Log.isLoggable(TAG, Log.DEBUG)) { 1078 assert mConnectionPool != null; 1079 Log.i(TAG, mConnectionPool.toString()); 1080 } 1081 mConnectionPool.close(); 1082 } 1083 } finally { 1084 unlock(); 1085 } 1086 } 1087 1088 private void closeClosable() { 1089 /* deallocate all compiled SQL statement objects from mCompiledQueries cache. 1090 * this should be done before de-referencing all {@link SQLiteClosable} objects 1091 * from this database object because calling 1092 * {@link SQLiteClosable#onAllReferencesReleasedFromContainer()} could cause the database 1093 * to be closed. sqlite doesn't let a database close if there are 1094 * any unfinalized statements - such as the compiled-sql objects in mCompiledQueries. 1095 */ 1096 deallocCachedSqlStatements(); 1097 1098 Iterator<Map.Entry<SQLiteClosable, Object>> iter = mPrograms.entrySet().iterator(); 1099 while (iter.hasNext()) { 1100 Map.Entry<SQLiteClosable, Object> entry = iter.next(); 1101 SQLiteClosable program = entry.getKey(); 1102 if (program != null) { 1103 program.onAllReferencesReleasedFromContainer(); 1104 } 1105 } 1106 } 1107 1108 /** 1109 * package level access for testing purposes 1110 */ 1111 /* package */ void closeDatabase() throws SQLiteException { 1112 try { 1113 dbclose(); 1114 } catch (SQLiteUnfinalizedObjectsException e) { 1115 String msg = e.getMessage(); 1116 String[] tokens = msg.split(",", 2); 1117 int stmtId = Integer.parseInt(tokens[0]); 1118 // get extra info about this statement, if it is still to be released by closeClosable() 1119 Iterator<Map.Entry<SQLiteClosable, Object>> iter = mPrograms.entrySet().iterator(); 1120 boolean found = false; 1121 while (iter.hasNext()) { 1122 Map.Entry<SQLiteClosable, Object> entry = iter.next(); 1123 SQLiteClosable program = entry.getKey(); 1124 if (program != null && program instanceof SQLiteProgram) { 1125 SQLiteCompiledSql compiledSql = ((SQLiteProgram)program).mCompiledSql; 1126 if (compiledSql.nStatement == stmtId) { 1127 msg = compiledSql.toString(); 1128 found = true; 1129 } 1130 } 1131 } 1132 if (!found) { 1133 // the statement is already released by closeClosable(). is it waiting to be 1134 // finalized? 1135 if (mClosedStatementIds.contains(stmtId)) { 1136 Log.w(TAG, "this shouldn't happen. finalizing the statement now: "); 1137 closePendingStatements(); 1138 // try to close the database again 1139 closeDatabase(); 1140 } 1141 } else { 1142 // the statement is not yet closed. most probably programming error in the app. 1143 throw new SQLiteUnfinalizedObjectsException( 1144 "close() on database: " + getPath() + 1145 " failed due to un-close()d SQL statements: " + msg); 1146 } 1147 } 1148 } 1149 1150 /** 1151 * Native call to close the database. 1152 */ 1153 private native void dbclose(); 1154 1155 /** 1156 * A callback interface for a custom sqlite3 function. 1157 * This can be used to create a function that can be called from 1158 * sqlite3 database triggers. 1159 * @hide 1160 */ 1161 public interface CustomFunction { 1162 public void callback(String[] args); 1163 } 1164 1165 /** 1166 * Registers a CustomFunction callback as a function that can be called from 1167 * sqlite3 database triggers. 1168 * @param name the name of the sqlite3 function 1169 * @param numArgs the number of arguments for the function 1170 * @param function callback to call when the function is executed 1171 * @hide 1172 */ 1173 public void addCustomFunction(String name, int numArgs, CustomFunction function) { 1174 verifyDbIsOpen(); 1175 synchronized (mCustomFunctions) { 1176 int ref = native_addCustomFunction(name, numArgs, function); 1177 if (ref != 0) { 1178 // save a reference to the function for cleanup later 1179 mCustomFunctions.add(new Integer(ref)); 1180 } else { 1181 throw new SQLiteException("failed to add custom function " + name); 1182 } 1183 } 1184 } 1185 1186 private void releaseCustomFunctions() { 1187 synchronized (mCustomFunctions) { 1188 for (int i = 0; i < mCustomFunctions.size(); i++) { 1189 Integer function = mCustomFunctions.get(i); 1190 native_releaseCustomFunction(function.intValue()); 1191 } 1192 mCustomFunctions.clear(); 1193 } 1194 } 1195 1196 // list of CustomFunction references so we can clean up when the database closes 1197 private final ArrayList<Integer> mCustomFunctions = 1198 new ArrayList<Integer>(); 1199 1200 private native int native_addCustomFunction(String name, int numArgs, CustomFunction function); 1201 private native void native_releaseCustomFunction(int function); 1202 1203 /** 1204 * Gets the database version. 1205 * 1206 * @return the database version 1207 */ 1208 public int getVersion() { 1209 return ((Long) DatabaseUtils.longForQuery(this, "PRAGMA user_version;", null)).intValue(); 1210 } 1211 1212 /** 1213 * Sets the database version. 1214 * 1215 * @param version the new database version 1216 */ 1217 public void setVersion(int version) { 1218 execSQL("PRAGMA user_version = " + version); 1219 } 1220 1221 /** 1222 * Returns the maximum size the database may grow to. 1223 * 1224 * @return the new maximum database size 1225 */ 1226 public long getMaximumSize() { 1227 long pageCount = DatabaseUtils.longForQuery(this, "PRAGMA max_page_count;", null); 1228 return pageCount * getPageSize(); 1229 } 1230 1231 /** 1232 * Sets the maximum size the database will grow to. The maximum size cannot 1233 * be set below the current size. 1234 * 1235 * @param numBytes the maximum database size, in bytes 1236 * @return the new maximum database size 1237 */ 1238 public long setMaximumSize(long numBytes) { 1239 long pageSize = getPageSize(); 1240 long numPages = numBytes / pageSize; 1241 // If numBytes isn't a multiple of pageSize, bump up a page 1242 if ((numBytes % pageSize) != 0) { 1243 numPages++; 1244 } 1245 long newPageCount = DatabaseUtils.longForQuery(this, "PRAGMA max_page_count = " + numPages, 1246 null); 1247 return newPageCount * pageSize; 1248 } 1249 1250 /** 1251 * Returns the current database page size, in bytes. 1252 * 1253 * @return the database page size, in bytes 1254 */ 1255 public long getPageSize() { 1256 return DatabaseUtils.longForQuery(this, "PRAGMA page_size;", null); 1257 } 1258 1259 /** 1260 * Sets the database page size. The page size must be a power of two. This 1261 * method does not work if any data has been written to the database file, 1262 * and must be called right after the database has been created. 1263 * 1264 * @param numBytes the database page size, in bytes 1265 */ 1266 public void setPageSize(long numBytes) { 1267 execSQL("PRAGMA page_size = " + numBytes); 1268 } 1269 1270 /** 1271 * Mark this table as syncable. When an update occurs in this table the 1272 * _sync_dirty field will be set to ensure proper syncing operation. 1273 * 1274 * @param table the table to mark as syncable 1275 * @param deletedTable The deleted table that corresponds to the 1276 * syncable table 1277 * @deprecated This method no longer serves any useful purpose and has been deprecated. 1278 */ 1279 @Deprecated 1280 public void markTableSyncable(String table, String deletedTable) { 1281 } 1282 1283 /** 1284 * Mark this table as syncable, with the _sync_dirty residing in another 1285 * table. When an update occurs in this table the _sync_dirty field of the 1286 * row in updateTable with the _id in foreignKey will be set to 1287 * ensure proper syncing operation. 1288 * 1289 * @param table an update on this table will trigger a sync time removal 1290 * @param foreignKey this is the column in table whose value is an _id in 1291 * updateTable 1292 * @param updateTable this is the table that will have its _sync_dirty 1293 * @deprecated This method no longer serves any useful purpose and has been deprecated. 1294 */ 1295 @Deprecated 1296 public void markTableSyncable(String table, String foreignKey, String updateTable) { 1297 } 1298 1299 /** 1300 * Finds the name of the first table, which is editable. 1301 * 1302 * @param tables a list of tables 1303 * @return the first table listed 1304 */ 1305 public static String findEditTable(String tables) { 1306 if (!TextUtils.isEmpty(tables)) { 1307 // find the first word terminated by either a space or a comma 1308 int spacepos = tables.indexOf(' '); 1309 int commapos = tables.indexOf(','); 1310 1311 if (spacepos > 0 && (spacepos < commapos || commapos < 0)) { 1312 return tables.substring(0, spacepos); 1313 } else if (commapos > 0 && (commapos < spacepos || spacepos < 0) ) { 1314 return tables.substring(0, commapos); 1315 } 1316 return tables; 1317 } else { 1318 throw new IllegalStateException("Invalid tables"); 1319 } 1320 } 1321 1322 /** 1323 * Compiles an SQL statement into a reusable pre-compiled statement object. 1324 * The parameters are identical to {@link #execSQL(String)}. You may put ?s in the 1325 * statement and fill in those values with {@link SQLiteProgram#bindString} 1326 * and {@link SQLiteProgram#bindLong} each time you want to run the 1327 * statement. Statements may not return result sets larger than 1x1. 1328 *<p> 1329 * No two threads should be using the same {@link SQLiteStatement} at the same time. 1330 * 1331 * @param sql The raw SQL statement, may contain ? for unknown values to be 1332 * bound later. 1333 * @return A pre-compiled {@link SQLiteStatement} object. Note that 1334 * {@link SQLiteStatement}s are not synchronized, see the documentation for more details. 1335 */ 1336 public SQLiteStatement compileStatement(String sql) throws SQLException { 1337 verifyDbIsOpen(); 1338 return new SQLiteStatement(this, sql, null); 1339 } 1340 1341 /** 1342 * Query the given URL, returning a {@link Cursor} over the result set. 1343 * 1344 * @param distinct true if you want each row to be unique, false otherwise. 1345 * @param table The table name to compile the query against. 1346 * @param columns A list of which columns to return. Passing null will 1347 * return all columns, which is discouraged to prevent reading 1348 * data from storage that isn't going to be used. 1349 * @param selection A filter declaring which rows to return, formatted as an 1350 * SQL WHERE clause (excluding the WHERE itself). Passing null 1351 * will return all rows for the given table. 1352 * @param selectionArgs You may include ?s in selection, which will be 1353 * replaced by the values from selectionArgs, in order that they 1354 * appear in the selection. The values will be bound as Strings. 1355 * @param groupBy A filter declaring how to group rows, formatted as an SQL 1356 * GROUP BY clause (excluding the GROUP BY itself). Passing null 1357 * will cause the rows to not be grouped. 1358 * @param having A filter declare which row groups to include in the cursor, 1359 * if row grouping is being used, formatted as an SQL HAVING 1360 * clause (excluding the HAVING itself). Passing null will cause 1361 * all row groups to be included, and is required when row 1362 * grouping is not being used. 1363 * @param orderBy How to order the rows, formatted as an SQL ORDER BY clause 1364 * (excluding the ORDER BY itself). Passing null will use the 1365 * default sort order, which may be unordered. 1366 * @param limit Limits the number of rows returned by the query, 1367 * formatted as LIMIT clause. Passing null denotes no LIMIT clause. 1368 * @return A {@link Cursor} object, which is positioned before the first entry. Note that 1369 * {@link Cursor}s are not synchronized, see the documentation for more details. 1370 * @see Cursor 1371 */ 1372 public Cursor query(boolean distinct, String table, String[] columns, 1373 String selection, String[] selectionArgs, String groupBy, 1374 String having, String orderBy, String limit) { 1375 return queryWithFactory(null, distinct, table, columns, selection, selectionArgs, 1376 groupBy, having, orderBy, limit); 1377 } 1378 1379 /** 1380 * Query the given URL, returning a {@link Cursor} over the result set. 1381 * 1382 * @param cursorFactory the cursor factory to use, or null for the default factory 1383 * @param distinct true if you want each row to be unique, false otherwise. 1384 * @param table The table name to compile the query against. 1385 * @param columns A list of which columns to return. Passing null will 1386 * return all columns, which is discouraged to prevent reading 1387 * data from storage that isn't going to be used. 1388 * @param selection A filter declaring which rows to return, formatted as an 1389 * SQL WHERE clause (excluding the WHERE itself). Passing null 1390 * will return all rows for the given table. 1391 * @param selectionArgs You may include ?s in selection, which will be 1392 * replaced by the values from selectionArgs, in order that they 1393 * appear in the selection. The values will be bound as Strings. 1394 * @param groupBy A filter declaring how to group rows, formatted as an SQL 1395 * GROUP BY clause (excluding the GROUP BY itself). Passing null 1396 * will cause the rows to not be grouped. 1397 * @param having A filter declare which row groups to include in the cursor, 1398 * if row grouping is being used, formatted as an SQL HAVING 1399 * clause (excluding the HAVING itself). Passing null will cause 1400 * all row groups to be included, and is required when row 1401 * grouping is not being used. 1402 * @param orderBy How to order the rows, formatted as an SQL ORDER BY clause 1403 * (excluding the ORDER BY itself). Passing null will use the 1404 * default sort order, which may be unordered. 1405 * @param limit Limits the number of rows returned by the query, 1406 * formatted as LIMIT clause. Passing null denotes no LIMIT clause. 1407 * @return A {@link Cursor} object, which is positioned before the first entry. Note that 1408 * {@link Cursor}s are not synchronized, see the documentation for more details. 1409 * @see Cursor 1410 */ 1411 public Cursor queryWithFactory(CursorFactory cursorFactory, 1412 boolean distinct, String table, String[] columns, 1413 String selection, String[] selectionArgs, String groupBy, 1414 String having, String orderBy, String limit) { 1415 verifyDbIsOpen(); 1416 String sql = SQLiteQueryBuilder.buildQueryString( 1417 distinct, table, columns, selection, groupBy, having, orderBy, limit); 1418 1419 return rawQueryWithFactory( 1420 cursorFactory, sql, selectionArgs, findEditTable(table)); 1421 } 1422 1423 /** 1424 * Query the given table, returning a {@link Cursor} over the result set. 1425 * 1426 * @param table The table name to compile the query against. 1427 * @param columns A list of which columns to return. Passing null will 1428 * return all columns, which is discouraged to prevent reading 1429 * data from storage that isn't going to be used. 1430 * @param selection A filter declaring which rows to return, formatted as an 1431 * SQL WHERE clause (excluding the WHERE itself). Passing null 1432 * will return all rows for the given table. 1433 * @param selectionArgs You may include ?s in selection, which will be 1434 * replaced by the values from selectionArgs, in order that they 1435 * appear in the selection. The values will be bound as Strings. 1436 * @param groupBy A filter declaring how to group rows, formatted as an SQL 1437 * GROUP BY clause (excluding the GROUP BY itself). Passing null 1438 * will cause the rows to not be grouped. 1439 * @param having A filter declare which row groups to include in the cursor, 1440 * if row grouping is being used, formatted as an SQL HAVING 1441 * clause (excluding the HAVING itself). Passing null will cause 1442 * all row groups to be included, and is required when row 1443 * grouping is not being used. 1444 * @param orderBy How to order the rows, formatted as an SQL ORDER BY clause 1445 * (excluding the ORDER BY itself). Passing null will use the 1446 * default sort order, which may be unordered. 1447 * @return A {@link Cursor} object, which is positioned before the first entry. Note that 1448 * {@link Cursor}s are not synchronized, see the documentation for more details. 1449 * @see Cursor 1450 */ 1451 public Cursor query(String table, String[] columns, String selection, 1452 String[] selectionArgs, String groupBy, String having, 1453 String orderBy) { 1454 1455 return query(false, table, columns, selection, selectionArgs, groupBy, 1456 having, orderBy, null /* limit */); 1457 } 1458 1459 /** 1460 * Query the given table, returning a {@link Cursor} over the result set. 1461 * 1462 * @param table The table name to compile the query against. 1463 * @param columns A list of which columns to return. Passing null will 1464 * return all columns, which is discouraged to prevent reading 1465 * data from storage that isn't going to be used. 1466 * @param selection A filter declaring which rows to return, formatted as an 1467 * SQL WHERE clause (excluding the WHERE itself). Passing null 1468 * will return all rows for the given table. 1469 * @param selectionArgs You may include ?s in selection, which will be 1470 * replaced by the values from selectionArgs, in order that they 1471 * appear in the selection. The values will be bound as Strings. 1472 * @param groupBy A filter declaring how to group rows, formatted as an SQL 1473 * GROUP BY clause (excluding the GROUP BY itself). Passing null 1474 * will cause the rows to not be grouped. 1475 * @param having A filter declare which row groups to include in the cursor, 1476 * if row grouping is being used, formatted as an SQL HAVING 1477 * clause (excluding the HAVING itself). Passing null will cause 1478 * all row groups to be included, and is required when row 1479 * grouping is not being used. 1480 * @param orderBy How to order the rows, formatted as an SQL ORDER BY clause 1481 * (excluding the ORDER BY itself). Passing null will use the 1482 * default sort order, which may be unordered. 1483 * @param limit Limits the number of rows returned by the query, 1484 * formatted as LIMIT clause. Passing null denotes no LIMIT clause. 1485 * @return A {@link Cursor} object, which is positioned before the first entry. Note that 1486 * {@link Cursor}s are not synchronized, see the documentation for more details. 1487 * @see Cursor 1488 */ 1489 public Cursor query(String table, String[] columns, String selection, 1490 String[] selectionArgs, String groupBy, String having, 1491 String orderBy, String limit) { 1492 1493 return query(false, table, columns, selection, selectionArgs, groupBy, 1494 having, orderBy, limit); 1495 } 1496 1497 /** 1498 * Runs the provided SQL and returns a {@link Cursor} over the result set. 1499 * 1500 * @param sql the SQL query. The SQL string must not be ; terminated 1501 * @param selectionArgs You may include ?s in where clause in the query, 1502 * which will be replaced by the values from selectionArgs. The 1503 * values will be bound as Strings. 1504 * @return A {@link Cursor} object, which is positioned before the first entry. Note that 1505 * {@link Cursor}s are not synchronized, see the documentation for more details. 1506 */ 1507 public Cursor rawQuery(String sql, String[] selectionArgs) { 1508 return rawQueryWithFactory(null, sql, selectionArgs, null); 1509 } 1510 1511 /** 1512 * Runs the provided SQL and returns a cursor over the result set. 1513 * 1514 * @param cursorFactory the cursor factory to use, or null for the default factory 1515 * @param sql the SQL query. The SQL string must not be ; terminated 1516 * @param selectionArgs You may include ?s in where clause in the query, 1517 * which will be replaced by the values from selectionArgs. The 1518 * values will be bound as Strings. 1519 * @param editTable the name of the first table, which is editable 1520 * @return A {@link Cursor} object, which is positioned before the first entry. Note that 1521 * {@link Cursor}s are not synchronized, see the documentation for more details. 1522 */ 1523 public Cursor rawQueryWithFactory( 1524 CursorFactory cursorFactory, String sql, String[] selectionArgs, 1525 String editTable) { 1526 verifyDbIsOpen(); 1527 BlockGuard.getThreadPolicy().onReadFromDisk(); 1528 long timeStart = 0; 1529 1530 if (Config.LOGV || mSlowQueryThreshold != -1) { 1531 timeStart = System.currentTimeMillis(); 1532 } 1533 1534 SQLiteDatabase db = getDbConnection(sql); 1535 SQLiteCursorDriver driver = new SQLiteDirectCursorDriver(db, sql, editTable); 1536 1537 Cursor cursor = null; 1538 try { 1539 cursor = driver.query( 1540 cursorFactory != null ? cursorFactory : mFactory, 1541 selectionArgs); 1542 } finally { 1543 if (Config.LOGV || mSlowQueryThreshold != -1) { 1544 1545 // Force query execution 1546 int count = -1; 1547 if (cursor != null) { 1548 count = cursor.getCount(); 1549 } 1550 1551 long duration = System.currentTimeMillis() - timeStart; 1552 1553 if (Config.LOGV || duration >= mSlowQueryThreshold) { 1554 Log.v(SQLiteCursor.TAG, 1555 "query (" + duration + " ms): " + driver.toString() + ", args are " 1556 + (selectionArgs != null 1557 ? TextUtils.join(",", selectionArgs) 1558 : "<null>") + ", count is " + count); 1559 } 1560 } 1561 releaseDbConnection(db); 1562 } 1563 return cursor; 1564 } 1565 1566 /** 1567 * Runs the provided SQL and returns a cursor over the result set. 1568 * The cursor will read an initial set of rows and the return to the caller. 1569 * It will continue to read in batches and send data changed notifications 1570 * when the later batches are ready. 1571 * @param sql the SQL query. The SQL string must not be ; terminated 1572 * @param selectionArgs You may include ?s in where clause in the query, 1573 * which will be replaced by the values from selectionArgs. The 1574 * values will be bound as Strings. 1575 * @param initialRead set the initial count of items to read from the cursor 1576 * @param maxRead set the count of items to read on each iteration after the first 1577 * @return A {@link Cursor} object, which is positioned before the first entry. Note that 1578 * {@link Cursor}s are not synchronized, see the documentation for more details. 1579 * 1580 * This work is incomplete and not fully tested or reviewed, so currently 1581 * hidden. 1582 * @hide 1583 */ 1584 public Cursor rawQuery(String sql, String[] selectionArgs, 1585 int initialRead, int maxRead) { 1586 SQLiteCursor c = (SQLiteCursor)rawQueryWithFactory( 1587 null, sql, selectionArgs, null); 1588 c.setLoadStyle(initialRead, maxRead); 1589 return c; 1590 } 1591 1592 /** 1593 * Convenience method for inserting a row into the database. 1594 * 1595 * @param table the table to insert the row into 1596 * @param nullColumnHack SQL doesn't allow inserting a completely empty row, 1597 * so if initialValues is empty this column will explicitly be 1598 * assigned a NULL value 1599 * @param values this map contains the initial column values for the 1600 * row. The keys should be the column names and the values the 1601 * column values 1602 * @return the row ID of the newly inserted row, or -1 if an error occurred 1603 */ 1604 public long insert(String table, String nullColumnHack, ContentValues values) { 1605 try { 1606 return insertWithOnConflict(table, nullColumnHack, values, CONFLICT_NONE); 1607 } catch (SQLException e) { 1608 Log.e(TAG, "Error inserting " + values, e); 1609 return -1; 1610 } 1611 } 1612 1613 /** 1614 * Convenience method for inserting a row into the database. 1615 * 1616 * @param table the table to insert the row into 1617 * @param nullColumnHack SQL doesn't allow inserting a completely empty row, 1618 * so if initialValues is empty this column will explicitly be 1619 * assigned a NULL value 1620 * @param values this map contains the initial column values for the 1621 * row. The keys should be the column names and the values the 1622 * column values 1623 * @throws SQLException 1624 * @return the row ID of the newly inserted row, or -1 if an error occurred 1625 */ 1626 public long insertOrThrow(String table, String nullColumnHack, ContentValues values) 1627 throws SQLException { 1628 return insertWithOnConflict(table, nullColumnHack, values, CONFLICT_NONE); 1629 } 1630 1631 /** 1632 * Convenience method for replacing a row in the database. 1633 * 1634 * @param table the table in which to replace the row 1635 * @param nullColumnHack SQL doesn't allow inserting a completely empty row, 1636 * so if initialValues is empty this row will explicitly be 1637 * assigned a NULL value 1638 * @param initialValues this map contains the initial column values for 1639 * the row. The key 1640 * @return the row ID of the newly inserted row, or -1 if an error occurred 1641 */ 1642 public long replace(String table, String nullColumnHack, ContentValues initialValues) { 1643 try { 1644 return insertWithOnConflict(table, nullColumnHack, initialValues, 1645 CONFLICT_REPLACE); 1646 } catch (SQLException e) { 1647 Log.e(TAG, "Error inserting " + initialValues, e); 1648 return -1; 1649 } 1650 } 1651 1652 /** 1653 * Convenience method for replacing a row in the database. 1654 * 1655 * @param table the table in which to replace the row 1656 * @param nullColumnHack SQL doesn't allow inserting a completely empty row, 1657 * so if initialValues is empty this row will explicitly be 1658 * assigned a NULL value 1659 * @param initialValues this map contains the initial column values for 1660 * the row. The key 1661 * @throws SQLException 1662 * @return the row ID of the newly inserted row, or -1 if an error occurred 1663 */ 1664 public long replaceOrThrow(String table, String nullColumnHack, 1665 ContentValues initialValues) throws SQLException { 1666 return insertWithOnConflict(table, nullColumnHack, initialValues, 1667 CONFLICT_REPLACE); 1668 } 1669 1670 /** 1671 * General method for inserting a row into the database. 1672 * 1673 * @param table the table to insert the row into 1674 * @param nullColumnHack SQL doesn't allow inserting a completely empty row, 1675 * so if initialValues is empty this column will explicitly be 1676 * assigned a NULL value 1677 * @param initialValues this map contains the initial column values for the 1678 * row. The keys should be the column names and the values the 1679 * column values 1680 * @param conflictAlgorithm for insert conflict resolver 1681 * @return the row ID of the newly inserted row 1682 * OR the primary key of the existing row if the input param 'conflictAlgorithm' = 1683 * {@link #CONFLICT_IGNORE} 1684 * OR -1 if any error 1685 */ 1686 public long insertWithOnConflict(String table, String nullColumnHack, 1687 ContentValues initialValues, int conflictAlgorithm) { 1688 StringBuilder sql = new StringBuilder(); 1689 sql.append("INSERT"); 1690 sql.append(CONFLICT_VALUES[conflictAlgorithm]); 1691 sql.append(" INTO "); 1692 sql.append(table); 1693 sql.append('('); 1694 1695 Object[] bindArgs = null; 1696 int size = (initialValues != null && initialValues.size() > 0) ? initialValues.size() : 0; 1697 if (size > 0) { 1698 bindArgs = new Object[size]; 1699 int i = 0; 1700 for (String colName : initialValues.keySet()) { 1701 sql.append((i > 0) ? "," : ""); 1702 sql.append(colName); 1703 bindArgs[i++] = initialValues.get(colName); 1704 } 1705 sql.append(')'); 1706 sql.append(" VALUES ("); 1707 for (i = 0; i < size; i++) { 1708 sql.append((i > 0) ? ",?" : "?"); 1709 } 1710 } else { 1711 sql.append(nullColumnHack + ") VALUES (NULL"); 1712 } 1713 sql.append(')'); 1714 1715 SQLiteStatement statement = new SQLiteStatement(this, sql.toString(), bindArgs); 1716 try { 1717 return statement.executeInsert(); 1718 } catch (SQLiteDatabaseCorruptException e) { 1719 onCorruption(); 1720 throw e; 1721 } finally { 1722 statement.close(); 1723 } 1724 } 1725 1726 /** 1727 * Convenience method for deleting rows in the database. 1728 * 1729 * @param table the table to delete from 1730 * @param whereClause the optional WHERE clause to apply when deleting. 1731 * Passing null will delete all rows. 1732 * @return the number of rows affected if a whereClause is passed in, 0 1733 * otherwise. To remove all rows and get a count pass "1" as the 1734 * whereClause. 1735 */ 1736 public int delete(String table, String whereClause, String[] whereArgs) { 1737 SQLiteStatement statement = new SQLiteStatement(this, "DELETE FROM " + table + 1738 (!TextUtils.isEmpty(whereClause) ? " WHERE " + whereClause : ""), whereArgs); 1739 try { 1740 return statement.executeUpdateDelete(); 1741 } catch (SQLiteDatabaseCorruptException e) { 1742 onCorruption(); 1743 throw e; 1744 } finally { 1745 statement.close(); 1746 } 1747 } 1748 1749 /** 1750 * Convenience method for updating rows in the database. 1751 * 1752 * @param table the table to update in 1753 * @param values a map from column names to new column values. null is a 1754 * valid value that will be translated to NULL. 1755 * @param whereClause the optional WHERE clause to apply when updating. 1756 * Passing null will update all rows. 1757 * @return the number of rows affected 1758 */ 1759 public int update(String table, ContentValues values, String whereClause, String[] whereArgs) { 1760 return updateWithOnConflict(table, values, whereClause, whereArgs, CONFLICT_NONE); 1761 } 1762 1763 /** 1764 * Convenience method for updating rows in the database. 1765 * 1766 * @param table the table to update in 1767 * @param values a map from column names to new column values. null is a 1768 * valid value that will be translated to NULL. 1769 * @param whereClause the optional WHERE clause to apply when updating. 1770 * Passing null will update all rows. 1771 * @param conflictAlgorithm for update conflict resolver 1772 * @return the number of rows affected 1773 */ 1774 public int updateWithOnConflict(String table, ContentValues values, 1775 String whereClause, String[] whereArgs, int conflictAlgorithm) { 1776 if (values == null || values.size() == 0) { 1777 throw new IllegalArgumentException("Empty values"); 1778 } 1779 1780 StringBuilder sql = new StringBuilder(120); 1781 sql.append("UPDATE "); 1782 sql.append(CONFLICT_VALUES[conflictAlgorithm]); 1783 sql.append(table); 1784 sql.append(" SET "); 1785 1786 // move all bind args to one array 1787 int setValuesSize = values.size(); 1788 int bindArgsSize = (whereArgs == null) ? setValuesSize : (setValuesSize + whereArgs.length); 1789 Object[] bindArgs = new Object[bindArgsSize]; 1790 int i = 0; 1791 for (String colName : values.keySet()) { 1792 sql.append((i > 0) ? "," : ""); 1793 sql.append(colName); 1794 bindArgs[i++] = values.get(colName); 1795 sql.append("=?"); 1796 } 1797 if (whereArgs != null) { 1798 for (i = setValuesSize; i < bindArgsSize; i++) { 1799 bindArgs[i] = whereArgs[i - setValuesSize]; 1800 } 1801 } 1802 if (!TextUtils.isEmpty(whereClause)) { 1803 sql.append(" WHERE "); 1804 sql.append(whereClause); 1805 } 1806 1807 SQLiteStatement statement = new SQLiteStatement(this, sql.toString(), bindArgs); 1808 try { 1809 return statement.executeUpdateDelete(); 1810 } catch (SQLiteDatabaseCorruptException e) { 1811 onCorruption(); 1812 throw e; 1813 } finally { 1814 statement.close(); 1815 } 1816 } 1817 1818 /** 1819 * Execute a single SQL statement that is NOT a SELECT 1820 * or any other SQL statement that returns data. 1821 * <p> 1822 * It has no means to return any data (such as the number of affected rows). 1823 * Instead, you're encouraged to use {@link #insert(String, String, ContentValues)}, 1824 * {@link #update(String, ContentValues, String, String[])}, et al, when possible. 1825 * </p> 1826 * <p> 1827 * When using {@link #enableWriteAheadLogging()}, journal_mode is 1828 * automatically managed by this class. So, do not set journal_mode 1829 * using "PRAGMA journal_mode'<value>" statement if your app is using 1830 * {@link #enableWriteAheadLogging()} 1831 * </p> 1832 * 1833 * @param sql the SQL statement to be executed. Multiple statements separated by semicolons are 1834 * not supported. 1835 * @throws SQLException If the SQL string is invalid for some reason 1836 */ 1837 public void execSQL(String sql) throws SQLException { 1838 int stmtType = DatabaseUtils.getSqlStatementType(sql); 1839 if (stmtType == DatabaseUtils.STATEMENT_ATTACH) { 1840 disableWriteAheadLogging(); 1841 } 1842 long timeStart = SystemClock.uptimeMillis(); 1843 logTimeStat(mLastSqlStatement, timeStart, GET_LOCK_LOG_PREFIX); 1844 executeSql(sql, null); 1845 1846 if (stmtType == DatabaseUtils.STATEMENT_ATTACH) { 1847 mHasAttachedDbs = true; 1848 } 1849 // Log commit statements along with the most recently executed 1850 // SQL statement for disambiguation. 1851 if (stmtType == DatabaseUtils.STATEMENT_COMMIT) { 1852 logTimeStat(mLastSqlStatement, timeStart, COMMIT_SQL); 1853 } else { 1854 logTimeStat(sql, timeStart, null); 1855 } 1856 } 1857 1858 /** 1859 * Execute a single SQL statement that is NOT a SELECT/INSERT/UPDATE/DELETE. 1860 * <p> 1861 * For INSERT statements, use any of the following instead. 1862 * <ul> 1863 * <li>{@link #insert(String, String, ContentValues)}</li> 1864 * <li>{@link #insertOrThrow(String, String, ContentValues)}</li> 1865 * <li>{@link #insertWithOnConflict(String, String, ContentValues, int)}</li> 1866 * </ul> 1867 * <p> 1868 * For UPDATE statements, use any of the following instead. 1869 * <ul> 1870 * <li>{@link #update(String, ContentValues, String, String[])}</li> 1871 * <li>{@link #updateWithOnConflict(String, ContentValues, String, String[], int)}</li> 1872 * </ul> 1873 * <p> 1874 * For DELETE statements, use any of the following instead. 1875 * <ul> 1876 * <li>{@link #delete(String, String, String[])}</li> 1877 * </ul> 1878 * <p> 1879 * For example, the following are good candidates for using this method: 1880 * <ul> 1881 * <li>ALTER TABLE</li> 1882 * <li>CREATE or DROP table / trigger / view / index / virtual table</li> 1883 * <li>REINDEX</li> 1884 * <li>RELEASE</li> 1885 * <li>SAVEPOINT</li> 1886 * <li>PRAGMA that returns no data</li> 1887 * </ul> 1888 * </p> 1889 * <p> 1890 * When using {@link #enableWriteAheadLogging()}, journal_mode is 1891 * automatically managed by this class. So, do not set journal_mode 1892 * using "PRAGMA journal_mode'<value>" statement if your app is using 1893 * {@link #enableWriteAheadLogging()} 1894 * </p> 1895 * 1896 * @param sql the SQL statement to be executed. Multiple statements separated by semicolons are 1897 * not supported. 1898 * @param bindArgs only byte[], String, Long and Double are supported in bindArgs. 1899 * @throws SQLException If the SQL string is invalid for some reason 1900 */ 1901 public void execSQL(String sql, Object[] bindArgs) throws SQLException { 1902 if (bindArgs == null) { 1903 throw new IllegalArgumentException("Empty bindArgs"); 1904 } 1905 executeSql(sql, bindArgs); 1906 } 1907 1908 private int executeSql(String sql, Object[] bindArgs) throws SQLException { 1909 long timeStart = SystemClock.uptimeMillis(); 1910 int n; 1911 SQLiteStatement statement = new SQLiteStatement(this, sql, bindArgs); 1912 try { 1913 n = statement.executeUpdateDelete(); 1914 } catch (SQLiteDatabaseCorruptException e) { 1915 onCorruption(); 1916 throw e; 1917 } finally { 1918 statement.close(); 1919 } 1920 logTimeStat(sql, timeStart); 1921 return n; 1922 } 1923 1924 @Override 1925 protected void finalize() throws Throwable { 1926 try { 1927 if (isOpen()) { 1928 Log.e(TAG, "close() was never explicitly called on database '" + 1929 mPath + "' ", mStackTrace); 1930 closeClosable(); 1931 onAllReferencesReleased(); 1932 releaseCustomFunctions(); 1933 } 1934 } finally { 1935 super.finalize(); 1936 } 1937 } 1938 1939 /** 1940 * Private constructor. 1941 * 1942 * @param path The full path to the database 1943 * @param factory The factory to use when creating cursors, may be NULL. 1944 * @param flags 0 or {@link #NO_LOCALIZED_COLLATORS}. If the database file already 1945 * exists, mFlags will be updated appropriately. 1946 * @param errorHandler The {@link DatabaseErrorHandler} to be used when sqlite reports database 1947 * corruption. may be NULL. 1948 * @param connectionNum 0 for main database connection handle. 1..N for pooled database 1949 * connection handles. 1950 */ 1951 private SQLiteDatabase(String path, CursorFactory factory, int flags, 1952 DatabaseErrorHandler errorHandler, short connectionNum) { 1953 if (path == null) { 1954 throw new IllegalArgumentException("path should not be null"); 1955 } 1956 mFlags = flags; 1957 mPath = path; 1958 mSlowQueryThreshold = SystemProperties.getInt(LOG_SLOW_QUERIES_PROPERTY, -1); 1959 mStackTrace = new DatabaseObjectNotClosedException().fillInStackTrace(); 1960 mFactory = factory; 1961 mPrograms = new WeakHashMap<SQLiteClosable,Object>(); 1962 // Set the DatabaseErrorHandler to be used when SQLite reports corruption. 1963 // If the caller sets errorHandler = null, then use default errorhandler. 1964 mErrorHandler = (errorHandler == null) ? new DefaultDatabaseErrorHandler() : errorHandler; 1965 mConnectionNum = connectionNum; 1966 } 1967 1968 /** 1969 * return whether the DB is opened as read only. 1970 * @return true if DB is opened as read only 1971 */ 1972 public boolean isReadOnly() { 1973 return (mFlags & OPEN_READ_MASK) == OPEN_READONLY; 1974 } 1975 1976 /** 1977 * @return true if the DB is currently open (has not been closed) 1978 */ 1979 public boolean isOpen() { 1980 return mNativeHandle != 0; 1981 } 1982 1983 public boolean needUpgrade(int newVersion) { 1984 return newVersion > getVersion(); 1985 } 1986 1987 /** 1988 * Getter for the path to the database file. 1989 * 1990 * @return the path to our database file. 1991 */ 1992 public final String getPath() { 1993 return mPath; 1994 } 1995 1996 /* package */ void logTimeStat(String sql, long beginMillis) { 1997 logTimeStat(sql, beginMillis, null); 1998 } 1999 2000 /* package */ void logTimeStat(String sql, long beginMillis, String prefix) { 2001 // Keep track of the last statement executed here, as this is 2002 // the common funnel through which all methods of hitting 2003 // libsqlite eventually flow. 2004 mLastSqlStatement = sql; 2005 2006 // Sample fast queries in proportion to the time taken. 2007 // Quantize the % first, so the logged sampling probability 2008 // exactly equals the actual sampling rate for this query. 2009 2010 int samplePercent; 2011 long durationMillis = SystemClock.uptimeMillis() - beginMillis; 2012 if (durationMillis == 0 && prefix == GET_LOCK_LOG_PREFIX) { 2013 // The common case is locks being uncontended. Don't log those, 2014 // even at 1%, which is our default below. 2015 return; 2016 } 2017 if (sQueryLogTimeInMillis == 0) { 2018 sQueryLogTimeInMillis = SystemProperties.getInt("db.db_operation.threshold_ms", 500); 2019 } 2020 if (durationMillis >= sQueryLogTimeInMillis) { 2021 samplePercent = 100; 2022 } else { 2023 samplePercent = (int) (100 * durationMillis / sQueryLogTimeInMillis) + 1; 2024 if (mRandom.nextInt(100) >= samplePercent) return; 2025 } 2026 2027 // Note: the prefix will be "COMMIT;" or "GETLOCK:" when non-null. We wait to do 2028 // it here so we avoid allocating in the common case. 2029 if (prefix != null) { 2030 sql = prefix + sql; 2031 } 2032 2033 if (sql.length() > QUERY_LOG_SQL_LENGTH) sql = sql.substring(0, QUERY_LOG_SQL_LENGTH); 2034 2035 // ActivityThread.currentPackageName() only returns non-null if the 2036 // current thread is an application main thread. This parameter tells 2037 // us whether an event loop is blocked, and if so, which app it is. 2038 // 2039 // Sadly, there's no fast way to determine app name if this is *not* a 2040 // main thread, or when we are invoked via Binder (e.g. ContentProvider). 2041 // Hopefully the full path to the database will be informative enough. 2042 2043 String blockingPackage = AppGlobals.getInitialPackage(); 2044 if (blockingPackage == null) blockingPackage = ""; 2045 2046 EventLog.writeEvent( 2047 EVENT_DB_OPERATION, 2048 getPathForLogs(), 2049 sql, 2050 durationMillis, 2051 blockingPackage, 2052 samplePercent); 2053 } 2054 2055 /** 2056 * Removes email addresses from database filenames before they're 2057 * logged to the EventLog where otherwise apps could potentially 2058 * read them. 2059 */ 2060 private String getPathForLogs() { 2061 if (mPathForLogs != null) { 2062 return mPathForLogs; 2063 } 2064 if (mPath == null) { 2065 return null; 2066 } 2067 if (mPath.indexOf('@') == -1) { 2068 mPathForLogs = mPath; 2069 } else { 2070 mPathForLogs = EMAIL_IN_DB_PATTERN.matcher(mPath).replaceAll("XX@YY"); 2071 } 2072 return mPathForLogs; 2073 } 2074 2075 /** 2076 * Sets the locale for this database. Does nothing if this database has 2077 * the NO_LOCALIZED_COLLATORS flag set or was opened read only. 2078 * @throws SQLException if the locale could not be set. The most common reason 2079 * for this is that there is no collator available for the locale you requested. 2080 * In this case the database remains unchanged. 2081 */ 2082 public void setLocale(Locale locale) { 2083 lock(); 2084 try { 2085 native_setLocale(locale.toString(), mFlags); 2086 } finally { 2087 unlock(); 2088 } 2089 } 2090 2091 /* package */ void verifyDbIsOpen() { 2092 if (!isOpen()) { 2093 throw new IllegalStateException("database " + getPath() + " (conn# " + 2094 mConnectionNum + ") already closed"); 2095 } 2096 } 2097 2098 /* package */ void verifyLockOwner() { 2099 verifyDbIsOpen(); 2100 if (mLockingEnabled && !isDbLockedByCurrentThread()) { 2101 throw new IllegalStateException("Don't have database lock!"); 2102 } 2103 } 2104 2105 /** 2106 * Adds the given SQL and its compiled-statement-id-returned-by-sqlite to the 2107 * cache of compiledQueries attached to 'this'. 2108 * <p> 2109 * If there is already a {@link SQLiteCompiledSql} in compiledQueries for the given SQL, 2110 * the new {@link SQLiteCompiledSql} object is NOT inserted into the cache (i.e.,the current 2111 * mapping is NOT replaced with the new mapping). 2112 */ 2113 /* package */ void addToCompiledQueries(String sql, SQLiteCompiledSql compiledStatement) { 2114 synchronized(mCompiledQueries) { 2115 // don't insert the new mapping if a mapping already exists 2116 if (mCompiledQueries.containsKey(sql)) { 2117 return; 2118 } 2119 2120 int maxCacheSz = (mConnectionNum == 0) ? mMaxSqlCacheSize : 2121 mParentConnObj.mMaxSqlCacheSize; 2122 2123 if (SQLiteDebug.DEBUG_SQL_CACHE) { 2124 boolean printWarning = (mConnectionNum == 0) 2125 ? (!mCacheFullWarning && mCompiledQueries.size() == maxCacheSz) 2126 : (!mParentConnObj.mCacheFullWarning && 2127 mParentConnObj.mCompiledQueries.size() == maxCacheSz); 2128 if (printWarning) { 2129 /* 2130 * cache size of {@link #mMaxSqlCacheSize} is not enough for this app. 2131 * log a warning. 2132 * chances are it is NOT using ? for bindargs - or cachesize is too small. 2133 */ 2134 Log.w(TAG, "Reached MAX size for compiled-sql statement cache for database " + 2135 getPath() + ". Use setMaxSqlCacheSize() to increase cachesize. "); 2136 mCacheFullWarning = true; 2137 Log.d(TAG, "Here are the SQL statements in Cache of database: " + mPath); 2138 for (String s : mCompiledQueries.keySet()) { 2139 Log.d(TAG, "Sql stament in Cache: " + s); 2140 } 2141 } 2142 } 2143 /* add the given SQLiteCompiledSql compiledStatement to cache. 2144 * no need to worry about the cache size - because {@link #mCompiledQueries} 2145 * self-limits its size to {@link #mMaxSqlCacheSize}. 2146 */ 2147 mCompiledQueries.put(sql, compiledStatement); 2148 } 2149 } 2150 2151 /** package-level access for testing purposes */ 2152 /* package */ void deallocCachedSqlStatements() { 2153 synchronized (mCompiledQueries) { 2154 for (SQLiteCompiledSql compiledSql : mCompiledQueries.values()) { 2155 compiledSql.releaseSqlStatement(); 2156 } 2157 mCompiledQueries.clear(); 2158 } 2159 } 2160 2161 /** 2162 * From the compiledQueries cache, returns the compiled-statement-id for the given SQL. 2163 * Returns null, if not found in the cache. 2164 */ 2165 /* package */ SQLiteCompiledSql getCompiledStatementForSql(String sql) { 2166 synchronized (mCompiledQueries) { 2167 SQLiteCompiledSql compiledStatement = mCompiledQueries.get(sql); 2168 if (compiledStatement == null) { 2169 mNumCacheMisses++; 2170 return null; 2171 } 2172 mNumCacheHits++; 2173 return compiledStatement; 2174 } 2175 } 2176 2177 /** 2178 * Sets the maximum size of the prepared-statement cache for this database. 2179 * (size of the cache = number of compiled-sql-statements stored in the cache). 2180 *<p> 2181 * Maximum cache size can ONLY be increased from its current size (default = 10). 2182 * If this method is called with smaller size than the current maximum value, 2183 * then IllegalStateException is thrown. 2184 *<p> 2185 * This method is thread-safe. 2186 * 2187 * @param cacheSize the size of the cache. can be (0 to {@link #MAX_SQL_CACHE_SIZE}) 2188 * @throws IllegalStateException if input cacheSize > {@link #MAX_SQL_CACHE_SIZE} or 2189 * the value set with previous setMaxSqlCacheSize() call. 2190 */ 2191 public void setMaxSqlCacheSize(int cacheSize) { 2192 synchronized(mCompiledQueries) { 2193 if (cacheSize > MAX_SQL_CACHE_SIZE || cacheSize < 0) { 2194 throw new IllegalStateException("expected value between 0 and " + MAX_SQL_CACHE_SIZE); 2195 } else if (cacheSize < mMaxSqlCacheSize) { 2196 throw new IllegalStateException("cannot set cacheSize to a value less than the value " + 2197 "set with previous setMaxSqlCacheSize() call."); 2198 } 2199 mMaxSqlCacheSize = cacheSize; 2200 } 2201 } 2202 2203 /* package */ boolean isInStatementCache(String sql) { 2204 synchronized (mCompiledQueries) { 2205 return mCompiledQueries.containsKey(sql); 2206 } 2207 } 2208 2209 /* package */ void releaseCompiledSqlObj(SQLiteCompiledSql compiledSql) { 2210 synchronized (mCompiledQueries) { 2211 if (mCompiledQueries.containsValue(compiledSql)) { 2212 // it is in cache - reset its inUse flag 2213 compiledSql.release(); 2214 } else { 2215 // it is NOT in cache. finalize it. 2216 compiledSql.releaseSqlStatement(); 2217 } 2218 } 2219 } 2220 2221 private int getCacheHitNum() { 2222 synchronized(mCompiledQueries) { 2223 return mNumCacheHits; 2224 } 2225 } 2226 2227 private int getCacheMissNum() { 2228 synchronized(mCompiledQueries) { 2229 return mNumCacheMisses; 2230 } 2231 } 2232 2233 private int getCachesize() { 2234 synchronized(mCompiledQueries) { 2235 return mCompiledQueries.size(); 2236 } 2237 } 2238 2239 /* package */ void finalizeStatementLater(int id) { 2240 if (!isOpen()) { 2241 // database already closed. this statement will already have been finalized. 2242 return; 2243 } 2244 synchronized(mClosedStatementIds) { 2245 if (mClosedStatementIds.contains(id)) { 2246 // this statement id is already queued up for finalization. 2247 return; 2248 } 2249 mClosedStatementIds.add(id); 2250 } 2251 } 2252 2253 /* package */ void closePendingStatements() { 2254 if (!isOpen()) { 2255 // since this database is already closed, no need to finalize anything. 2256 mClosedStatementIds.clear(); 2257 return; 2258 } 2259 verifyLockOwner(); 2260 /* to minimize synchronization on mClosedStatementIds, make a copy of the list */ 2261 ArrayList<Integer> list = new ArrayList<Integer>(mClosedStatementIds.size()); 2262 synchronized(mClosedStatementIds) { 2263 list.addAll(mClosedStatementIds); 2264 mClosedStatementIds.clear(); 2265 } 2266 // finalize all the statements from the copied list 2267 int size = list.size(); 2268 for (int i = 0; i < size; i++) { 2269 native_finalize(list.get(i)); 2270 } 2271 } 2272 2273 /** 2274 * for testing only 2275 */ 2276 /* package */ ArrayList<Integer> getQueuedUpStmtList() { 2277 return mClosedStatementIds; 2278 } 2279 2280 /** 2281 * This method enables parallel execution of queries from multiple threads on the same database. 2282 * It does this by opening multiple handles to the database and using a different 2283 * database handle for each query. 2284 * <p> 2285 * If a transaction is in progress on one connection handle and say, a table is updated in the 2286 * transaction, then query on the same table on another connection handle will block for the 2287 * transaction to complete. But this method enables such queries to execute by having them 2288 * return old version of the data from the table. Most often it is the data that existed in the 2289 * table prior to the above transaction updates on that table. 2290 * <p> 2291 * Maximum number of simultaneous handles used to execute queries in parallel is 2292 * dependent upon the device memory and possibly other properties. 2293 * <p> 2294 * After calling this method, execution of queries in parallel is enabled as long as this 2295 * database handle is open. To disable execution of queries in parallel, database should 2296 * be closed and reopened. 2297 * <p> 2298 * If a query is part of a transaction, then it is executed on the same database handle the 2299 * transaction was begun. 2300 * <p> 2301 * If the database has any attached databases, then execution of queries in paralel is NOT 2302 * possible. In such cases, a message is printed to logcat and false is returned. 2303 * <p> 2304 * This feature is not available for :memory: databases. In such cases, 2305 * a message is printed to logcat and false is returned. 2306 * <p> 2307 * A typical way to use this method is the following: 2308 * <pre> 2309 * SQLiteDatabase db = SQLiteDatabase.openDatabase("db_filename", cursorFactory, 2310 * CREATE_IF_NECESSARY, myDatabaseErrorHandler); 2311 * db.enableWriteAheadLogging(); 2312 * </pre> 2313 * <p> 2314 * Writers should use {@link #beginTransactionNonExclusive()} or 2315 * {@link #beginTransactionWithListenerNonExclusive(SQLiteTransactionListener)} 2316 * to start a trsnsaction. 2317 * Non-exclusive mode allows database file to be in readable by threads executing queries. 2318 * </p> 2319 * 2320 * @return true if write-ahead-logging is set. false otherwise 2321 */ 2322 public boolean enableWriteAheadLogging() { 2323 // make sure the database is not READONLY. WAL doesn't make sense for readonly-databases. 2324 if (isReadOnly()) { 2325 return false; 2326 } 2327 // acquire lock - no that no other thread is enabling WAL at the same time 2328 lock(); 2329 try { 2330 if (mConnectionPool != null) { 2331 // already enabled 2332 return true; 2333 } 2334 if (mPath.equalsIgnoreCase(MEMORY_DB_PATH)) { 2335 Log.i(TAG, "can't enable WAL for memory databases."); 2336 return false; 2337 } 2338 2339 // make sure this database has NO attached databases because sqlite's write-ahead-logging 2340 // doesn't work for databases with attached databases 2341 if (mHasAttachedDbs) { 2342 if (Log.isLoggable(TAG, Log.DEBUG)) { 2343 Log.d(TAG, 2344 "this database: " + mPath + " has attached databases. can't enable WAL."); 2345 } 2346 return false; 2347 } 2348 mConnectionPool = new DatabaseConnectionPool(this); 2349 setJournalMode(mPath, "WAL"); 2350 return true; 2351 } finally { 2352 unlock(); 2353 } 2354 } 2355 2356 /** 2357 * This method disables the features enabled by {@link #enableWriteAheadLogging()}. 2358 * @hide 2359 */ 2360 public void disableWriteAheadLogging() { 2361 // grab database lock so that writeAheadLogging is not disabled from 2 different threads 2362 // at the same time 2363 lock(); 2364 try { 2365 if (mConnectionPool == null) { 2366 return; // already disabled 2367 } 2368 mConnectionPool.close(); 2369 setJournalMode(mPath, "TRUNCATE"); 2370 mConnectionPool = null; 2371 } finally { 2372 unlock(); 2373 } 2374 } 2375 2376 /* package */ SQLiteDatabase getDatabaseHandle(String sql) { 2377 if (isPooledConnection()) { 2378 // this is a pooled database connection 2379 // use it if it is open AND if I am not currently part of a transaction 2380 if (isOpen() && !amIInTransaction()) { 2381 // TODO: use another connection from the pool 2382 // if this connection is currently in use by some other thread 2383 // AND if there are free connections in the pool 2384 return this; 2385 } else { 2386 // the pooled connection is not open! could have been closed either due 2387 // to corruption on this or some other connection to the database 2388 // OR, maybe the connection pool is disabled after this connection has been 2389 // allocated to me. try to get some other pooled or main database connection 2390 return getParentDbConnObj().getDbConnection(sql); 2391 } 2392 } else { 2393 // this is NOT a pooled connection. can we get one? 2394 return getDbConnection(sql); 2395 } 2396 } 2397 2398 /* package */ SQLiteDatabase createPoolConnection(short connectionNum) { 2399 SQLiteDatabase db = openDatabase(mPath, mFactory, mFlags, mErrorHandler, connectionNum); 2400 db.mParentConnObj = this; 2401 return db; 2402 } 2403 2404 private synchronized SQLiteDatabase getParentDbConnObj() { 2405 return mParentConnObj; 2406 } 2407 2408 private boolean isPooledConnection() { 2409 return this.mConnectionNum > 0; 2410 } 2411 2412 /* package */ SQLiteDatabase getDbConnection(String sql) { 2413 verifyDbIsOpen(); 2414 // this method should always be called with main database connection handle. 2415 // the only time when it is called with pooled database connection handle is 2416 // corruption occurs while trying to open a pooled database connection handle. 2417 // in that case, simply return 'this' handle 2418 if (isPooledConnection()) { 2419 return this; 2420 } 2421 2422 // use the current connection handle if 2423 // 1. if the caller is part of the ongoing transaction, if any 2424 // 2. OR, if there is NO connection handle pool setup 2425 if (amIInTransaction() || mConnectionPool == null) { 2426 return this; 2427 } else { 2428 // get a connection handle from the pool 2429 if (Log.isLoggable(TAG, Log.DEBUG)) { 2430 assert mConnectionPool != null; 2431 Log.i(TAG, mConnectionPool.toString()); 2432 } 2433 return mConnectionPool.get(sql); 2434 } 2435 } 2436 2437 private void releaseDbConnection(SQLiteDatabase db) { 2438 // ignore this release call if 2439 // 1. the database is closed 2440 // 2. OR, if db is NOT a pooled connection handle 2441 // 3. OR, if the database being released is same as 'this' (this condition means 2442 // that we should always be releasing a pooled connection handle by calling this method 2443 // from the 'main' connection handle 2444 if (!isOpen() || !db.isPooledConnection() || (db == this)) { 2445 return; 2446 } 2447 if (Log.isLoggable(TAG, Log.DEBUG)) { 2448 assert isPooledConnection(); 2449 assert mConnectionPool != null; 2450 Log.d(TAG, "releaseDbConnection threadid = " + Thread.currentThread().getId() + 2451 ", releasing # " + db.mConnectionNum + ", " + getPath()); 2452 } 2453 mConnectionPool.release(db); 2454 } 2455 2456 /** 2457 * this method is used to collect data about ALL open databases in the current process. 2458 * bugreport is a user of this data. 2459 */ 2460 /* package */ static ArrayList<DbStats> getDbStats() { 2461 ArrayList<DbStats> dbStatsList = new ArrayList<DbStats>(); 2462 // make a local copy of mActiveDatabases - so that this method is not competing 2463 // for synchronization lock on mActiveDatabases 2464 ArrayList<WeakReference<SQLiteDatabase>> tempList; 2465 synchronized(mActiveDatabases) { 2466 tempList = (ArrayList<WeakReference<SQLiteDatabase>>)mActiveDatabases.clone(); 2467 } 2468 for (WeakReference<SQLiteDatabase> w : tempList) { 2469 SQLiteDatabase db = w.get(); 2470 if (db == null || !db.isOpen()) { 2471 continue; 2472 } 2473 2474 try { 2475 // get SQLITE_DBSTATUS_LOOKASIDE_USED for the db 2476 int lookasideUsed = db.native_getDbLookaside(); 2477 2478 // get the lastnode of the dbname 2479 String path = db.getPath(); 2480 int indx = path.lastIndexOf("/"); 2481 String lastnode = path.substring((indx != -1) ? ++indx : 0); 2482 2483 // get list of attached dbs and for each db, get its size and pagesize 2484 ArrayList<Pair<String, String>> attachedDbs = db.getAttachedDbs(); 2485 if (attachedDbs == null) { 2486 continue; 2487 } 2488 for (int i = 0; i < attachedDbs.size(); i++) { 2489 Pair<String, String> p = attachedDbs.get(i); 2490 long pageCount = DatabaseUtils.longForQuery(db, "PRAGMA " + p.first 2491 + ".page_count;", null); 2492 2493 // first entry in the attached db list is always the main database 2494 // don't worry about prefixing the dbname with "main" 2495 String dbName; 2496 if (i == 0) { 2497 dbName = lastnode; 2498 } else { 2499 // lookaside is only relevant for the main db 2500 lookasideUsed = 0; 2501 dbName = " (attached) " + p.first; 2502 // if the attached db has a path, attach the lastnode from the path to above 2503 if (p.second.trim().length() > 0) { 2504 int idx = p.second.lastIndexOf("/"); 2505 dbName += " : " + p.second.substring((idx != -1) ? ++idx : 0); 2506 } 2507 } 2508 if (pageCount > 0) { 2509 dbStatsList.add(new DbStats(dbName, pageCount, db.getPageSize(), 2510 lookasideUsed, db.getCacheHitNum(), db.getCacheMissNum(), 2511 db.getCachesize())); 2512 } 2513 } 2514 // if there are pooled connections, return the cache stats for them also. 2515 // while we are trying to query the pooled connections for stats, some other thread 2516 // could be disabling conneciton pool. so, grab a reference to the connection pool. 2517 DatabaseConnectionPool connPool = db.mConnectionPool; 2518 if (connPool != null) { 2519 for (SQLiteDatabase pDb : connPool.getConnectionList()) { 2520 dbStatsList.add(new DbStats("(pooled # " + pDb.mConnectionNum + ") " 2521 + lastnode, 0, 0, 0, pDb.getCacheHitNum(), 2522 pDb.getCacheMissNum(), pDb.getCachesize())); 2523 } 2524 } 2525 } catch (SQLiteException e) { 2526 // ignore. we don't care about exceptions when we are taking adb 2527 // bugreport! 2528 } 2529 } 2530 return dbStatsList; 2531 } 2532 2533 /** 2534 * Returns list of full pathnames of all attached databases including the main database 2535 * by executing 'pragma database_list' on the database. 2536 * 2537 * @return ArrayList of pairs of (database name, database file path) or null if the database 2538 * is not open. 2539 */ 2540 public ArrayList<Pair<String, String>> getAttachedDbs() { 2541 if (!isOpen()) { 2542 return null; 2543 } 2544 ArrayList<Pair<String, String>> attachedDbs = new ArrayList<Pair<String, String>>(); 2545 if (!mHasAttachedDbs) { 2546 // No attached databases. 2547 // There is a small window where attached databases exist but this flag is not set yet. 2548 // This can occur when this thread is in a race condition with another thread 2549 // that is executing the SQL statement: "attach database <blah> as <foo>" 2550 // If this thread is NOT ok with such a race condition (and thus possibly not receive 2551 // the entire list of attached databases), then the caller should ensure that no thread 2552 // is executing any SQL statements while a thread is calling this method. 2553 // Typically, this method is called when 'adb bugreport' is done or the caller wants to 2554 // collect stats on the database and all its attached databases. 2555 attachedDbs.add(new Pair<String, String>("main", mPath)); 2556 return attachedDbs; 2557 } 2558 // has attached databases. query sqlite to get the list of attached databases. 2559 Cursor c = null; 2560 try { 2561 c = rawQuery("pragma database_list;", null); 2562 while (c.moveToNext()) { 2563 // sqlite returns a row for each database in the returned list of databases. 2564 // in each row, 2565 // 1st column is the database name such as main, or the database 2566 // name specified on the "ATTACH" command 2567 // 2nd column is the database file path. 2568 attachedDbs.add(new Pair<String, String>(c.getString(1), c.getString(2))); 2569 } 2570 } finally { 2571 if (c != null) { 2572 c.close(); 2573 } 2574 } 2575 return attachedDbs; 2576 } 2577 2578 /** 2579 * Runs 'pragma integrity_check' on the given database (and all the attached databases) 2580 * and returns true if the given database (and all its attached databases) pass integrity_check, 2581 * false otherwise. 2582 *<p> 2583 * If the result is false, then this method logs the errors reported by the integrity_check 2584 * command execution. 2585 *<p> 2586 * Note that 'pragma integrity_check' on a database can take a long time. 2587 * 2588 * @return true if the given database (and all its attached databases) pass integrity_check, 2589 * false otherwise. 2590 */ 2591 public boolean isDatabaseIntegrityOk() { 2592 verifyDbIsOpen(); 2593 ArrayList<Pair<String, String>> attachedDbs = null; 2594 try { 2595 attachedDbs = getAttachedDbs(); 2596 if (attachedDbs == null) { 2597 throw new IllegalStateException("databaselist for: " + getPath() + " couldn't " + 2598 "be retrieved. probably because the database is closed"); 2599 } 2600 } catch (SQLiteException e) { 2601 // can't get attachedDb list. do integrity check on the main database 2602 attachedDbs = new ArrayList<Pair<String, String>>(); 2603 attachedDbs.add(new Pair<String, String>("main", this.mPath)); 2604 } 2605 for (int i = 0; i < attachedDbs.size(); i++) { 2606 Pair<String, String> p = attachedDbs.get(i); 2607 SQLiteStatement prog = null; 2608 try { 2609 prog = compileStatement("PRAGMA " + p.first + ".integrity_check(1);"); 2610 String rslt = prog.simpleQueryForString(); 2611 if (!rslt.equalsIgnoreCase("ok")) { 2612 // integrity_checker failed on main or attached databases 2613 Log.e(TAG, "PRAGMA integrity_check on " + p.second + " returned: " + rslt); 2614 return false; 2615 } 2616 } finally { 2617 if (prog != null) prog.close(); 2618 } 2619 } 2620 return true; 2621 } 2622 2623 /** 2624 * Native call to open the database. 2625 * 2626 * @param path The full path to the database 2627 */ 2628 private native void dbopen(String path, int flags); 2629 2630 /** 2631 * Native call to setup tracing of all SQL statements 2632 * 2633 * @param path the full path to the database 2634 * @param connectionNum connection number: 0 - N, where the main database 2635 * connection handle is numbered 0 and the connection handles in the connection 2636 * pool are numbered 1..N. 2637 */ 2638 private native void enableSqlTracing(String path, short connectionNum); 2639 2640 /** 2641 * Native call to setup profiling of all SQL statements. 2642 * currently, sqlite's profiling = printing of execution-time 2643 * (wall-clock time) of each of the SQL statements, as they 2644 * are executed. 2645 * 2646 * @param path the full path to the database 2647 * @param connectionNum connection number: 0 - N, where the main database 2648 * connection handle is numbered 0 and the connection handles in the connection 2649 * pool are numbered 1..N. 2650 */ 2651 private native void enableSqlProfiling(String path, short connectionNum); 2652 2653 /** 2654 * Native call to set the locale. {@link #lock} must be held when calling 2655 * this method. 2656 * @throws SQLException 2657 */ 2658 private native void native_setLocale(String loc, int flags); 2659 2660 /** 2661 * return the SQLITE_DBSTATUS_LOOKASIDE_USED documented here 2662 * http://www.sqlite.org/c3ref/c_dbstatus_lookaside_used.html 2663 * @return int value of SQLITE_DBSTATUS_LOOKASIDE_USED 2664 */ 2665 private native int native_getDbLookaside(); 2666 2667 /** 2668 * finalizes the given statement id. 2669 * 2670 * @param statementId statement to be finzlied by sqlite 2671 */ 2672 private final native void native_finalize(int statementId); 2673} 2674